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. During the v6 migration, core is a compatibility consumer of pack-owned software delivery behavior; packs never import core.

Package Reference

| Package | Path | Role | Key Dependencies | | ------------------------------ | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | @lumenflow/cli | packages/@lumenflow/cli | 110+ CLI commands, each exporting main() | software-delivery pack, core, agent, kernel, host | | @lumenflow/core | packages/@lumenflow/core | Temporary compatibility exports while software-delivery owners move to the pack | software-delivery pack, kernel, host | | @lumenflow/kernel | packages/@lumenflow/kernel | KernelRuntime, canonical identifiers, protected-state and event ports, pure projections, ToolHost, scope intersection, and policy engine | zod, yaml, micromatch | | @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 | | @lumenflow/memory | packages/@lumenflow/memory | Deprecated compatibility shell for delivery/workflow memory | software-delivery pack | | @lumenflow/agent | packages/@lumenflow/agent | Agent coordination, delegation, spawn management | (minimal) | | @lumenflow/metrics | packages/@lumenflow/metrics | Deprecated compatibility shell for delivery flow metrics | software-delivery pack | | @lumenflow/initiatives | packages/@lumenflow/initiatives | Deprecated compatibility shell for multi-WU initiative orchestration | software-delivery pack | | @lumenflow/runtime | packages/@lumenflow/runtime | Runtime surface for programmatic API usage | kernel | | @lumenflow/mcp | packages/@lumenflow/mcp | MCP (Model Context Protocol) server for AI agent integration | kernel, host | | @lumenflow/shims | packages/@lumenflow/shims | Git safety shims (pre-commit, pre-push hooks) | (none) | | @lumenflow/control-plane-sdk | packages/@lumenflow/control-plane-sdk | Control plane sync contracts and adapters for the LumenFlow runtime | zod | | @lumenflow/conductor-sdk | packages/@lumenflow/conductor-sdk | Conductor SDK for the Software Delivery Pack — SDLC-specific event kinds and conductor contracts | control-plane-sdk | | @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

@lumenflow/core is compatibility-only. WU-3369 dissolved core’s implementation into the pack and kernel, leaving only thin one-line forwarders; WU-3541 will physically delete those forwarders once remaining consumers migrate.

Caution

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

WU authoring is owned by @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 zero pack-to-core imports and exact one-line core forwarders, preventing compatibility paths from becoming a second implementation.

Canonical identifier validation, protected path intents, task/evidence behavior, and event projections in @lumenflow/kernel are host-neutral. @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=@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 @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 @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 @lumenflow/host or pnpm add -D @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