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
Section titled “Package Dependency Graph”
The CLI package sits at the top of the dependency graph. Leaf packages (core, memory, agent, metrics, initiatives) are independently buildable. The kernel is standalone with minimal external dependencies. The pack has a unique dual relationship: it imports kernel types at compile time, but loads CLI modules at runtime via the runtime CLI adapter.
Package Reference
Section titled “Package Reference”| Package | Path | Role | Key Dependencies |
|---|---|---|---|
@lumenflow/cli | packages/@lumenflow/cli | 110+ CLI commands, each exporting main() | core, memory, agent, metrics, initiatives, kernel |
@lumenflow/core | packages/@lumenflow/core | WU types, YAML parsing, validation, configuration | zod, yaml, fast-glob |
@lumenflow/kernel | packages/@lumenflow/kernel | KernelRuntime, ToolHost, scope intersection, policy engine, evidence store, sandbox dispatch | zod, yaml, micromatch |
@lumenflow/memory | packages/@lumenflow/memory | Session tracking, checkpoints, signals, context recovery | (minimal) |
@lumenflow/agent | packages/@lumenflow/agent | Agent coordination, delegation, spawn management | (minimal) |
@lumenflow/metrics | packages/@lumenflow/metrics | Flow metrics collection and reporting | (minimal) |
@lumenflow/initiatives | packages/@lumenflow/initiatives | Multi-WU initiative tracking and wave orchestration | (minimal) |
@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 |
@lumenflow/shims | packages/@lumenflow/shims | Git safety shims (pre-commit, pre-push hooks) | (none) |
software-delivery | packages/@lumenflow/packs/software-delivery | 90+ tool implementations for software development workflows | kernel (types only) |
Build and Distribution
Section titled “Build and Distribution”pnpm bootstrap
Section titled “pnpm bootstrap”The pnpm bootstrap command builds the CLI and all its workspace dependencies in the correct order:
Turbo’s ^build dependency means “build all workspace dependencies first.” This produces a build order like:
Phase 1 packages have no workspace dependencies, so they build in parallel. The CLI builds last because it depends on all of them.
Pack Bundling
Section titled “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
Section titled “Pack Resolution Order”When the kernel starts, it resolves pack locations using resolvePacksRoot() with this priority:
- Workspace packs directory —
{workspaceRoot}/packs/(for projects with local packs) - Monorepo development path —
{workspaceRoot}/packages/@lumenflow/packs/(for LumenFlow development) - CLI-relative fallback —
{cliPackageRoot}/packs/(for end-user npm installs)
Next Steps
Section titled “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