Package Architecture

LumenFlow is a TypeScript monorepo with clear dependency boundaries between packages. This page explains the package graph, what each package contains, and how packs are built and distributed.

Package Dependency Graph

The CLI package sits at the top of the dependency graph. The kernel is standalone with minimal external dependencies and contains no persistence adapter. The host package implements kernel ports for local Node.js environments. Domain packs consume kernel contracts and generic host adapters. The Software Delivery Pack owns delivery behavior. Generic layers never import the pack. The remaining dynamic runtime-CLI adapter is a measured migration exception: the dependency gate prevents the exception set from growing while native pack handlers replace it. The same ratchet records two narrow host exceptions for the scheduler transport and phone-device identity helper; the allowed direction remains the target shown by the solid edges.

Package Reference

Package	Path	Role	Key Dependencies
@hellmai/lumenflow-cli	packages/@lumenflow/cli	110+ CLI commands, each exporting main()	software-delivery pack, agent, kernel, host
@hellmai/lumenflow-kernel	packages/@lumenflow/kernel	KernelRuntime, canonical identifiers, protected-state and event ports, pure projections, ToolHost, scope intersection, and policy engine	zod, yaml, micromatch
@hellmai/lumenflow-host	packages/@lumenflow/host	Local Node.js adapters, including Linux descriptor-held protected state, transactional SQLite/WAL event log, and JSONL migration	kernel, better-sqlite3
@hellmai/lumenflow-memory	packages/@lumenflow/memory	Deprecated compatibility shell for delivery/workflow memory	software-delivery pack
@hellmai/lumenflow-agent	packages/@lumenflow/agent	Agent coordination, delegation, spawn management	(minimal)
@hellmai/lumenflow-metrics	packages/@lumenflow/metrics	Deprecated compatibility shell for delivery flow metrics	software-delivery pack
@hellmai/lumenflow-initiatives	packages/@lumenflow/initiatives	Deprecated compatibility shell for multi-WU initiative orchestration	software-delivery pack
@hellmai/lumenflow-runtime	packages/@lumenflow/runtime	Runtime surface for programmatic API usage	kernel
@hellmai/lumenflow-mcp	packages/@lumenflow/mcp	MCP (Model Context Protocol) server for AI agent integration	kernel, host
@hellmai/lumenflow-shims	packages/@lumenflow/shims	Git safety shims (pre-commit, pre-push hooks)	(none)
@hellmai/lumenflow-control-plane-sdk	packages/@lumenflow/control-plane-sdk	Control plane sync contracts and adapters for the LumenFlow runtime	zod
@hellmai/lumenflow-conductor-sdk	packages/@lumenflow/conductor-sdk	Conductor SDK for the Software Delivery Pack — SDLC-specific event kinds and conductor contracts	control-plane-sdk
@hellmai/lumenflow-surfaces	packages/@lumenflow/surfaces	Kernel surfaces — HTTP, CLI, and MCP integration layers (cloud-facing boundary, ADR-011 §1)	control-plane-sdk, host, kernel
software-delivery	packages/@lumenflow/packs/software-delivery	Canonical owner of WU lifecycle, initiatives, delivery metrics, workflow memory, and 90+ software-delivery tool implementations	kernel, host, agent-runtime pack
agent-runtime	packages/@lumenflow/packs/agent-runtime	Governed turn execution, provider adapters, policy/capability factories, and agent-session orchestration	kernel (types only)

Note

WU-3541 physically deleted the retired compatibility package. Workflow code belongs to the Software Delivery Pack; generic contracts and adapters belong to kernel, host, or runtime.

Caution

@hellmai/lumenflow-initiatives, @hellmai/lumenflow-metrics, and @hellmai/lumenflow-memory are deprecated compatibility shells. Their published entrypoints forward to @hellmai/lumenflow-packs-software-delivery; new integrations should import the corresponding /initiatives, /metrics, or /memory pack subpath directly.

WU authoring is owned by @hellmai/lumenflow-packs-software-delivery/runtime/authoring. Direct module subpaths cover parsing, claim/create validation, ID generation, lint/list, rules, normalization, validation, and YAML repair. The pack also exposes an authoring namespace from its runtime barrel. Ownership tests require static pack code to remain free of dependencies on higher-level CLI surfaces. The remaining dynamic runtime adapter is separately ratcheted and cannot expand.

Canonical identifier validation, protected path intents, task/evidence behavior, and event projections in @hellmai/lumenflow-kernel are host-neutral. @hellmai/lumenflow-host binds the protected-state port to descriptor-held Linux filesystem operations and binds the event-log port to SQLite/WAL. The kernel requires that binding and fails closed for unbound custom factories; it never falls back to host filesystem access. Immutable task publication is an explicit port operation so the host can stage, flush, and atomically publish a complete spec without exposing partial content. Workspace and pack discovery adapters continue to move out of the broader runtime under INIT-087.

Build and Distribution

pnpm bootstrap

The pnpm bootstrap command builds the CLI and all its workspace dependencies in the correct order:

turbo build --filter=@hellmai/lumenflow-cli

Turbo’s ^build dependency means “build all workspace dependencies first.” This produces a build order like:

The diagram is illustrative; the workspace manifests remain the source of truth. The package-local CLI distribution build, MCP source build, and web production build select their complete transitive prerequisite graph with pnpm’s dependency-only "<package>^..." selector. Repository-level build:dist and pack:dist runs derive their distribution prerequisite graph through Turbo’s ^build:dist dependency edge instead. Both mechanisms follow workspace manifests rather than a second handwritten package list, so a clean checkout cannot accidentally compile against ignored dist/ output from an omitted dependency. The target package builds only after its derived closure succeeds. The web app declares its source-shipped @hellmai/lumenflow-surfaces edge explicitly and hashes the HTTP surface source in its build task until that package gains the standalone dist/ artifact described in its package README.

Both the governed local release command and tag-driven publish workflow delete package output and run the repository build:dist graph before packing. Every publishable dist package exposes that task, and distribution TypeScript configurations disable declaration maps and source maps. A normal developer build may retain maps for debugging; it is not a publish artifact authority.

pnpm native-build authorization

The local host adapter uses better-sqlite3, so both direct @hellmai/lumenflow-host consumers and packed CLI consumers must allow that package’s native install script. This approval belongs to the consuming project, never to published LumenFlow dependency metadata.

Before pnpm add @hellmai/lumenflow-host or pnpm add -D @hellmai/lumenflow-cli, merge the applicable policy into the consumer root’s existing pnpm-workspace.yaml. Preserve unrelated settings and approvals.

For pnpm 10.26 and newer (including pnpm 11):

allowBuilds:
  better-sqlite3: true

For pnpm 10.0 through 10.25:

onlyBuiltDependencies:
  - better-sqlite3

Use only the policy form supported by the project’s pnpm version. pnpm 9 does not require an explicit dependency-build approval. When migrating to allowBuilds, preserve every existing approval as a true entry before removing onlyBuiltDependencies. If installation already completed with an “ignored build scripts” warning, add the policy and run:

pnpm rebuild better-sqlite3

LumenFlow’s release smoke installs the packed CLI with pnpm, a scratch-local store, strict dependency-build checks, and a consumer-root allowlist. It then loads the native binding and runs the installed task create/inspect path against SQLite. This prevents npm hoisting or a previously built global-store artifact from masking a broken pnpm release.

Pack Bundling

The Software Delivery Pack is bundled into the CLI package for npm distribution. A sync-bundled-packs.mjs script handles this:

The CLI’s package.json files array includes "packs", ensuring the bundled pack ships with the npm package. The prepack hook runs sync automatically before npm publish.

Pack Resolution Order

When the kernel starts, it resolves pack locations using resolvePacksRoot() with this priority:

1. Workspace packs directory — {workspaceRoot}/packs/ (for projects with local packs)
2. Monorepo development path — {workspaceRoot}/packages/@lumenflow/packs/ (for LumenFlow development)
3. CLI-relative fallback — {cliPackageRoot}/packs/ (for end-user npm installs)

Tip

For most users who install LumenFlow via npm, the CLI-relative fallback is used. The workspace and monorepo paths exist for development and advanced pack customization.

Next Steps

• Tool Execution — How tools execute through the three-layer stack
• Kernel Runtime — The execution engine behind every tool call
• Packs — How domain tools are declared and loaded
• Create a Pack — Build your own domain pack