Packs

A pack is a self-contained plugin that teaches the kernel how to work in a specific domain. The kernel itself is domain-agnostic — it provides scope enforcement, policy evaluation, evidence recording, and tool dispatch. Packs provide the actual tools, policies, and evidence types for a particular workflow.

First-Party Packs

LumenFlow currently ships three first-party packs:

Pack	Domain	Current role
software-delivery	Software development workflow	Work Units, lanes, gates, memory, CLI-driven delivery lifecycle
sidekick	Workspace-local productivity	Managed tasks, memory, channels, routines, and status under .sidekick/
agent-runtime	Governed model turns	agent-session turns, policy-aware tool gating, orchestration state

Software Delivery Pack

The Software Delivery Pack provides 90+ tools for software development workflows:

Namespace	Tools	Purpose
wu:*	23	Work Unit lifecycle (create, claim, prep, done, block, recover…)
mem:*	14	Memory layer (checkpoint, inbox, signal, recover…)
initiative:*	8	Initiative management (create, plan, status…)
file:*	4	File operations with audit trail
git:*	4	Git operations with audit trail
agent:*	4	Agent session management
orchestrate:*	3	Multi-agent orchestration
plan:*	4	Plan management
state:*	3	State management
Others	23+	Gates, validation, config, docs, metrics, flow analysis…

Every one of these tools routes through the kernel’s execution pipeline — scope intersection, policy evaluation, and evidence recording happen on every call.

Sidekick Pack

The Sidekick Pack adds a compact 23-tool workspace productivity surface:

Namespace	Tools	Purpose
task:*	6	Personal and team-local task tracking, updates, completion, cancel
memory:*	4	Workspace-local memory, snippets, and destructive forgetting
channel:*	5	Named message channels, local discovery, and local deletion
routine:*	5	Plan-only routine definitions, updates, stop flow, and deletion
sidekick:*	3	Initialization, status, and export

Destructive Sidekick lifecycle tools such as task:cancel, memory:forget, channel:delete, and routine:delete are approval-gated through the pack policy factory when invoked through the kernel runtime.

Agent Runtime Pack

The Agent Runtime Pack provides the governed agent:execute-turn contract, policy-aware tool gating, provider normalization, and pack-owned agent-session orchestration.

Tip

If you are a software team, Software Delivery gives you the main delivery workflow, Sidekick adds workspace-local productivity primitives, and Agent Runtime adds governed model turns.

Pack Structure

A pack is a directory with a manifest.yaml at its root:

• Directorymy-pack/ - manifest.yaml (declares tools, policies, evidence types) - constants.ts (pack id, version, shared strings) - config.schema.json (validates workspace config for the pack) - capability-factory.ts (derives runtime scopes/env from resolved pack config) - policy-factory.ts (returns conditional PolicyRule objects) - tools/ - types.ts (shared type definitions) - tool-impl/ - my-tool.ts (runtime implementation)

  • …

The manifest is the contract between a pack and the kernel. It declares:

• Tools — what the pack can do (name, entry point, permissions, required scopes)
• Policies — static rules the kernel evaluates at specific lifecycle triggers
• Evidence types — kinds of audit records the pack produces
• Task types — what domain objects the pack manages (e.g., work-unit)
• State aliases — friendly names for kernel state machine states
• Lane templates — pre-defined lane configurations
• Config namespace — config_key and config_schema for pack-specific workspace settings
• Capability factory — runtime augmentation of required_scopes and required_env
• Policy factory — runtime-authored rules that can inspect PolicyEvaluationContext

Minimal manifest

id: my-pack
version: 0.1.0
task_types:
  - my-task-type
tools:
  - name: my-pack:do-something
    entry: tool-impl/my-tool.ts#doSomethingTool
    permission: write
    required_env:
      - MY_PACK_TOKEN
    required_scopes:
      - type: path
        pattern: '**'
        access: write
config_key: my_pack
config_schema: config.schema.json
capability_factory: capability-factory.ts#createMyPackCapabilityFactory
policy_factory: policy-factory.ts#createMyPackPolicyFactory
policies: []
evidence_types: []
state_aliases: {}
lane_templates: []

How Packs Are Loaded

When the kernel starts, it reads the workspace spec (workspace.yaml) which lists pinned packs:

packs:
  - id: software-delivery
    version: 0.1.0
    integrity: sha256:a1b2c3...
    source: local

For each pack pin, the kernel:

1. Resolves the pack root — in order:
   • workspaceRoot/packs/
   • workspaceRoot/packages/@lumenflow/packs/ (monorepo development)
   • bundled CLI packs (@lumenflow/cli/packs/) for end-user installs
   • a git repository (source: git) or registry cache (source: registry) when configured
2. Parses the manifest — validates against the schema, checks that id and version match the pin.
3. Validates pack config — if the manifest declares config_key and config_schema, the kernel validates the matching workspace config and makes the resolved payload available at runtime.
4. Validates import boundaries — scans all source files to ensure the pack only imports from allowed dependencies (node:* builtins, @lumenflow/kernel, and relative imports within the pack). No arbitrary npm packages allowed.
5. Verifies integrity — computes a SHA-256 hash of all pack files and compares it to the pinned hash. A mismatch means the pack was modified and the kernel refuses to load it.
6. Registers tools — each tool declared in the manifest becomes available in the kernel’s tool registry, then optional capability factories can augment required_scopes and required_env using the resolved pack config.
7. Injects policies — pack-declared policies are added to the pack layer of the policy engine, and optional policy factories can add conditional rules such as intent-aware gating.

Caution

During development, you can use integrity: dev to skip hash verification. In production, the kernel requires a valid SHA-256 hash and will refuse to start with unverified packs.

The Pack Ecosystem

LumenFlow is pack-first. First-party packs share the same manifest contract and are loaded from local paths, monorepo packages, bundled installs, or external sources such as git and registries.

See:

• Software Delivery Pack
• Sidekick Pack
• Agent Runtime Pack

Tool Implementation Pattern

Pack tools follow a standard pattern. Each tool returns a ToolOutput:

interface ToolOutput {
  success: boolean;
  data?: Record<string, unknown>;
  error?: { code: string; message: string };
  metadata?: {
    artifacts_written?: string[]; // paths written (for evidence)
  };
}

Tools can be implemented as:

• In-process handlers — TypeScript functions that run directly in the kernel process. Used for lightweight read operations.
• Subprocess handlers — executed in a sandboxed subprocess via spawnSync. Used for write operations and anything that needs OS-level isolation.

The Software Delivery Pack uses two implementation strategies. Most tools (~80) use the runtime CLI adapter to reuse existing CLI command modules in-process. A smaller set (~10) use direct implementations with simple-git wrappers and Node builtins. See Tool Execution for the full execution architecture.

Next Steps

• Kernel Runtime — How the kernel dispatches and governs tool calls
• Create a Pack — Step-by-step guide to building your own pack
• Scope Intersection — How pack tool scopes interact with other permission levels
• Policy Engine — How pack-declared policies are evaluated