CLI Commands

The LumenFlow CLI provides commands for managing work units, initiatives, memory, and quality gates.

Installation

pnpm

bash pnpm add -D @lumenflow/cli

npm

bash npm install -D @lumenflow/cli

yarn

bash yarn add -D @lumenflow/cli

---

Work Unit Commands

wu:create

Create a new work unit spec.

pnpm wu:create --id WU-001 --title "Add feature" --lane Core

Flag	Description	Required
--id	Unique WU identifier	Yes
--title	Short description	Yes
--lane	Target lane	Yes
--type	feature, fix, chore, discovery	No (default: feature)

wu:claim

Claim a WU and create a worktree.

pnpm wu:claim --id WU-001 --lane Core

Flag	Description	Required
--id	WU to claim	Yes
--lane	Lane to claim in	Yes

Creates:

• Worktree at worktrees/{lane}-{wu-id}
• Branch lane/{lane}/{wu-id}
• Updates WU status to in_progress

wu:done

Complete a WU after gates pass.

pnpm wu:done --id WU-001

Flag	Description	Required
--id	WU to complete	Yes
--skip-gates	Skip gate checks (requires --reason)	No
--reason	Reason for skipping gates	No

Actions:

1. Runs gates (unless skipped)
2. Merges worktree to main
3. Creates stamp in .beacon/stamps/
4. Cleans up worktree
5. Updates WU status to done

wu:edit

Edit WU spec files with micro-worktree isolation.

pnpm wu:edit --id WU-001 --description "Updated description"
pnpm wu:edit --id WU-001 --acceptance "New criterion" --append
pnpm wu:edit --id WU-001 --initiative INIT-001 --phase 2

Flag	Description
--id	WU to edit (required)
--description	New description (replaces existing)
--acceptance	Acceptance criterion (repeatable)
--notes	New notes text
--code-paths	Code path (repeatable)
--append	Append to arrays instead of replacing
--lane	New lane assignment
--type	New WU type
--priority	New priority (P0-P3)
--initiative	Link to initiative
--phase	Phase number within initiative
--blocked-by	Comma-separated blocking WU IDs
--add-dep	Add to dependencies array

wu:block

Mark a WU as blocked.

pnpm wu:block --id WU-001 --reason "Waiting for API spec"

Flag	Description	Required
--id	WU to block	Yes
--reason	Why it’s blocked	Yes

wu:unblock

Unblock a WU.

pnpm wu:unblock --id WU-001

wu:validate

Validate WU YAML against schema.

pnpm wu:validate --id WU-001
pnpm wu:validate --all

wu:preflight

Fast validation before running full gates. Completes in under 5 seconds.

pnpm wu:preflight --id WU-001

Checks:

• code_paths files exist
• Test file paths exist
• WU YAML schema is valid

Recommended workflow:

1. Implement feature/fix
2. pnpm wu:preflight --id WU-XXX (fast check)
3. pnpm gates (full validation)
4. pnpm wu:done --id WU-XXX

wu:spawn

Generate Task tool invocation for sub-agent WU execution.

pnpm wu:spawn --id WU-001
pnpm wu:spawn --id WU-001 --thinking --budget 10000
pnpm wu:spawn --id WU-001 --parent-wu WU-1000

Flag	Description
--id	WU to spawn (required)
--thinking	Enable extended thinking
--budget	Token budget for thinking
--codex	Output Codex/GPT-friendly format
--parent-wu	Parent WU for orchestrator context

wu:repair

Detect and fix WU state issues.

# Consistency repair (default)
pnpm wu:repair --id WU-001
pnpm wu:repair --all --check

# Claim repair
pnpm wu:repair --claim --id WU-001

# Admin repair
pnpm wu:repair --admin --id WU-001 --lane "New Lane" --status done

Flag	Description	Mode
--id	WU to repair	All
--check	Audit only, no changes	Consistency
--all	Check/repair all WUs	Consistency
--claim	Fix missing claim metadata	Claim
--admin	Fix done WUs	Admin
--repair-state	Fix corrupted state files	State

wu:prune

Maintain worktree hygiene.

pnpm wu:prune              # Dry-run (shows issues)
pnpm wu:prune --execute    # Execute cleanup

Detects:

• Orphan directories (exist but not tracked)
• Stale worktrees (WU is done/blocked)
• Invalid branch naming

wu:cleanup

Clean up worktree and branch after PR merge.

pnpm wu:cleanup --id WU-001

wu:deps

Show WU dependency graph.

pnpm wu:deps --id WU-001

wu:infer-lane

Suggest sub-lane for a WU based on paths and description.

pnpm wu:infer-lane --id WU-001
pnpm wu:infer-lane --paths "tools/**" "docs/**" --desc "Tooling improvements"

wu:delete

Delete WU files with micro-worktree isolation.

pnpm wu:delete --id WU-001
pnpm wu:delete --id WU-001 --dry-run
pnpm wu:delete --batch WU-1,WU-2,WU-3

Flag	Description
--id	WU to delete
--batch	Comma-separated WU IDs
--dry-run	Preview without making changes

wu:unlock-lane

Clear lane locks for recovery scenarios.

pnpm wu:unlock-lane --lane Core --reason "Process crashed"
pnpm wu:unlock-lane --lane Core --reason "Emergency" --force
pnpm wu:unlock-lane --list

Flag	Description
--lane	Lane to unlock
--reason	Audit reason (required)
--force	Force unlock active locks
--list	List all current locks

Lock types:

• Zombie locks (PID not running): Can be unlocked without --force
• Stale locks (>24h old): Can be unlocked without --force
• Active locks: Require --force to unlock

---

Initiative Commands

Initiatives group related WUs into phased execution plans.

initiative:create

Create a new initiative.

pnpm initiative:create --id INIT-001 --slug my-initiative --title "Big Feature" --priority P1

Flag	Description	Required
--id	Initiative ID	Yes
--slug	Kebab-case slug	Yes
--title	Initiative title	Yes
--priority	Priority (P0-P3)	No
--owner	Owner (team or individual)	No
--target-date	Target date (YYYY-MM-DD)	No

initiative:edit

Edit initiative YAML files.

pnpm initiative:edit --id INIT-001 --status in_progress
pnpm initiative:edit --id INIT-001 --add-phase "Phase 3: Rollout"
pnpm initiative:edit --id INIT-001 --blocked-by INIT-002 --blocked-reason "Waiting for infrastructure"

Flag	Description
--status	draft, open, in_progress, done, archived
--blocked-by	Blocking initiative ID
--unblock	Remove blocked status
--add-lane	Add lane (repeatable)
--remove-lane	Remove lane (repeatable)
--notes	Append to notes
--add-phase	Add new phase
--phase-id + --phase-status	Update phase status

initiative:list

List all initiatives with progress.

pnpm initiative:list
pnpm initiative:list --format json
pnpm initiative:list --status in_progress

Flag	Description
--format	table, json, ascii, mermaid
--status	Filter by status
--color	Enable colored output

initiative:status

Show detailed initiative view with phases and WUs.

pnpm initiative:status --id INIT-001
pnpm initiative:status --id INIT-001 --format mermaid

initiative:add-wu

Link a WU to an initiative bidirectionally.

pnpm initiative:add-wu --initiative INIT-001 --wu WU-123

---

Memory Commands

The memory layer provides persistent context for AI agents across sessions.

mem:init

Initialize memory layer.

pnpm mem:init

Creates .beacon/memory/ directory structure.

mem:start

Start a new agent session.

pnpm mem:start
pnpm mem:start --wu WU-001

mem:ready

Check pending work and context.

pnpm mem:ready

Shows:

• Active WU
• Last checkpoint
• Pending signals
• Next steps

mem:checkpoint

Create a checkpoint to save session state.

pnpm mem:checkpoint

mem:signal

Signal progress to other agents.

pnpm mem:signal "Completed validation logic"

mem:inbox

Check for messages/signals from other sessions.

pnpm mem:inbox

mem:create

Create a memory node with provenance tracking.

pnpm mem:create "Found a bug in auth flow" --type discovery --wu WU-001
pnpm mem:create "API changed" --discovered-from mem-abc123 --tags api,breaking

Flag	Description
--type	session, discovery, checkpoint, note, summary
--discovered-from	Parent node ID for provenance
--wu	Link to WU
--session	Link to session
--tags	Comma-separated tags
--priority	P0-P3

mem:summarize

Rollup older memory nodes into summary nodes.

pnpm mem:summarize --wu WU-001
pnpm mem:summarize --wu WU-001 --dry-run

mem:triage

Review discovery nodes and promote to WUs or archive.

pnpm mem:triage --list
pnpm mem:triage --promote mem-abc123 --lane Core --title "Fix auth bug"
pnpm mem:triage --archive mem-def456 --reason "Duplicate of WU-100"

Flag	Description
--list	List open discoveries
--promote	Promote to WU
--archive	Archive without promotion
--wu	Filter by WU ID
--tag	Filter by tag

mem:cleanup

Prune memory nodes based on lifecycle policy and TTL.

pnpm mem:cleanup                    # Cleanup based on lifecycle policy
pnpm mem:cleanup --dry-run          # Preview without changes
pnpm mem:cleanup --ttl 30d          # Remove nodes older than 30 days
pnpm mem:cleanup --session-id <uuid> # Close specific session
pnpm mem:cleanup --json             # Output as JSON

Flag	Description
--dry-run	Preview without making changes
--ttl	Remove nodes older than duration
--session-id	Close specific session
--json	Output results as JSON

Cleanup rules:

• Ephemeral nodes are always discarded
• Session nodes removed when session closes
• Summarized nodes archived (marked with summarized_into)
• Active sessions are never removed

---

Gate Commands

Quality gates ensure code meets standards before completion.

gates

Run all quality gates.

pnpm gates
pnpm gates --docs-only  # For documentation changes

Runs:

1. Format check
2. Lint check
3. Type check
4. Test suite

gates:format

Run only format gate.

pnpm gates:format

gates:lint

Run only lint gate.

pnpm gates:lint

gates:typecheck

Run only typecheck gate.

pnpm gates:typecheck

gates:test

Run only test gate.

pnpm gates:test

---

Orchestration Commands

spawn-list

Display spawn trees for WUs or initiatives.

pnpm spawn-list --wu WU-001
pnpm spawn-list --initiative INIT-001
pnpm spawn-list --initiative INIT-001 --json

orchestrate:initiative

Orchestrate initiative execution with parallel agent spawning.

pnpm orchestrate:initiative --initiative INIT-001
pnpm orchestrate:initiative --initiative INIT-001 --dry-run
pnpm orchestrate:initiative --initiative INIT-001 --progress
pnpm orchestrate:initiative --initiative INIT-001 --checkpoint-per-wave

Flag	Description
--initiative	Initiative ID(s) to orchestrate
--dry-run	Show execution plan without spawning
--progress	Show current progress only
--checkpoint-per-wave	Spawn next wave then exit (no polling)
--no-checkpoint	Force polling mode

orchestrate:init-status

Compact status view for initiative progress.

pnpm orchestrate:init-status --initiative INIT-001

orchestrate:monitor

Monitor spawned agent progress using mem:inbox signals.

pnpm orchestrate:monitor --since 30m
pnpm orchestrate:monitor --since 1h

Flag	Description
--since	Show signals from this time (e.g., 30m)

---

Agent Commands

Commands for managing agent sessions and telemetry.

agent:session

Start an agent session for tracking WU execution.

pnpm agent:session --wu WU-001 --tier 2
pnpm agent:session --wu WU-001 --tier 2 --agent-type claude-code

Flag	Description
--wu	WU ID to work on (required)
--tier	Context tier: 1, 2, or 3
--agent-type	Agent type (default: claude-code)

agent:session:end

End the current agent session.

pnpm agent:session:end

---

Initialization

lumenflow init

Initialize LumenFlow in a new project.

pnpm exec lumenflow init

Creates:

• .lumenflow.config.yaml
• docs/tasks/backlog.md
• docs/tasks/wu/
• .beacon/stamps/

lumenflow validate

Validate configuration.

pnpm exec lumenflow validate

Checks:

• Config file syntax
• Lane definitions
• Gate configuration

---

Exit Codes

Code	Meaning
0	Success
1	Command failed (see error message)
2	Validation error
3	WU not found
4	Lane at WIP limit

Environment Variables

Variable	Description	Default
LUMENFLOW_CONFIG	Config file path	.lumenflow.config.yaml
LUMENFLOW_VERBOSE	Enable verbose output	false
LUMENFLOW_NO_COLOR	Disable colored output	false

Next Steps

• Configuration Reference – Config file options
• WU Schema – WU YAML structure