CLI Commands

LumenFlow provides a curated public CLI surface for everyday workflows.

Tip

This page lists primary commands only. Use pnpm lumenflow:commands for full command discovery including aliases and legacy entrypoints.

Commands Overview

Category	Commands
Gates & Quality	gate:co-change, gate:conditional, gates, lane:create, lane:edit, lane:health, lane:list, lane:lock, lane:remove, lane:setup, lane:status, lane:suggest, lane:validate, lumenflow:pre-commit-check, validate
Initiatives	initiative:add-wu, initiative:bulk-assign, initiative:create, initiative:delete, initiative:edit, initiative:list, initiative:plan, initiative:remove-wu, initiative:rename, initiative:status
Memory & Sessions	mem:checkpoint, mem:cleanup, mem:context, mem:create, mem:delete, mem:export, mem:inbox, mem:init, mem:ready, mem:recover, mem:roster, mem:signal, mem:start, mem:summarize, mem:triage, signal:cleanup
Metrics & Flow	cost:summary, flow:bottlenecks, flow:report, metrics, metrics:snapshot
Orchestration	agent:issues-query, agent:log-issue, agent:session, agent:session-end, delegation:list, orchestrate:init-status, orchestrate:initiative, orchestrate:monitor, task:claim
Packs	pack:author, pack:hash, pack:install, pack:publish, pack:scaffold, pack:search, pack:validate
Plans	plan:create, plan:edit, plan:link, plan:promote
Setup & Development	backlog:prune, cloud:connect, config:get, config:set, distribution:preflight, file:delete, file:edit, file:read, file:write, git:branch, git:diff, git:log, git:status, lumenflow, lumenflow:commands, lumenflow:disable, lumenflow:docs-sync, lumenflow:doctor, lumenflow:enable, lumenflow:integrate, lumenflow:release, lumenflow:sync-templates, lumenflow:uninstall, lumenflow:upgrade
State Management	state:bootstrap, state:cleanup, state:doctor, state:emit
WU Lifecycle	approval:list, approval:request, approval:review, wu:block, wu:brief, wu:claim, wu:create, wu:delegate, wu:done, wu:edit, wu:escalate, wu:prep, wu:recover, wu:release, wu:rename, wu:sandbox, wu:status, wu:unblock, wu:validate, wu:verify
WU Maintenance	wu:cleanup, wu:delete, wu:deps, wu:infer-lane, wu:preflight, wu:proto, wu:prune, wu:repair, wu:review, wu:unlock-lane

Gates & Quality

gate:co-change

Manage co-change gate rules (add, remove, edit, list)

pnpm gate:co-change

gate:conditional

Manage conditional_commands gate entries (add, remove, edit, list)

pnpm gate:conditional

gates

Run all quality gates

pnpm gates

lane:create

Create a new lane definition

pnpm lane:create

lane:edit

Edit a lane definition (rename, wip-limit, paths, description)

pnpm lane:edit

lane:health

Check lane config health

pnpm lane:health

lane:list

List lane definitions (table or —json)

pnpm lane:list

lane:lock

Lock lane lifecycle for delivery WUs

pnpm lane:lock

lane:remove

Remove a lane definition when no active WUs still reference it

pnpm lane:remove

lane:setup

Create/update draft lane artifacts

pnpm lane:setup

lane:status

Show lane lifecycle status and next step

pnpm lane:status

lane:suggest

Suggest workspace lane definitions from project context

pnpm lane:suggest

lane:validate

Validate lane artifacts before lock

pnpm lane:validate

lumenflow:pre-commit-check

Run enforcement checks used by pre-commit and CI

pnpm lumenflow:pre-commit-check

validate

Run validation checks

pnpm validate

Initiatives

initiative:add-wu

Add WU to initiative

pnpm initiative:add-wu --initiative <ref>

Options:

Flag	Description	Required
--initiative <ref>	Parent initiative (INIT-XXX or slug)	Yes

initiative:bulk-assign

Bulk assign WUs to initiative

pnpm initiative:bulk-assign

Options:

Flag	Description	Required
--config <path>	Path to config file (tool-specific)	No
--apply	Apply changes (default is dry-run)	No
--sync-from-initiative	Ensure WU initiative fields exist for WUs listed in initiatives	No

initiative:create

Create new initiative

pnpm initiative:create --slug <slug> --title <title>

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	No
-s, --slug <slug>	Initiative slug (kebab-case)	Yes
-t, --title <title>	Work Unit title	Yes
-p, --priority <priority>	Priority level (P0, P1, P2, P3)	No
-o, --owner <owner>	Initiative owner (team or individual)	No
--target-date <date>	Target completion date (YYYY-MM-DD)	No

initiative:delete

Delete an initiative with explicit linked-WU safeguards

pnpm initiative:delete --id <wuId>

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	Yes
-f, --force	Force operation	No

initiative:edit

Edit initiative fields and phase metadata

pnpm initiative:edit

Options:

Flag	Description	Required
-i, --id <initId>	Initiative ID (e.g., INIT-001)	No
--blocked-by <initId>	Initiative ID that blocks this initiative	No
--blocked-reason <text>	Reason for blocking (required with —blocked-by)	No
--unblock	Remove blocked_by and blocked_reason fields	No
--add-lane <lane>	Lane to add (repeatable)	No
--remove-lane <lane>	Lane to remove (repeatable)	No
--notes <text>	Note to append to notes array	No
--description <text>	Replace the initiative description field	No
--add-phase <title>	Append a new phase with auto-incremented id and pending status (repeatable)	No
--add-success-metric <text>	Append to success_metrics array, avoiding duplicates (repeatable)	No
--remove-success-metric <text>	Remove exact match from success_metrics array (repeatable)	No
--phase-id <id>	Phase ID to update (use with —phase-status)	No
--phase-title <title>	Update phase title (use with —phase-id)	No
--created <date>	Set created date (YYYY-MM-DD format)	No
--phase-execution-order <order>	Phase execution order (sequential, parallel)	No
--dependency-model <model>	Dependency model for the initiative	No

initiative:list

List all initiatives

pnpm initiative:list

Options:

Flag	Description	Required
--format <format>	Output format (table, json, ascii, mermaid)	No
--status <status>	Filter by status	No
--color	Enable colored output	No

initiative:plan

Link plan to initiative

pnpm initiative:plan --initiative <ref>

Options:

Flag	Description	Required
--initiative <ref>	Parent initiative (INIT-XXX or slug)	Yes

initiative:remove-wu

Remove WU from initiative

pnpm initiative:remove-wu --initiative <ref> --wu <wuId>

Options:

Flag	Description	Required
--initiative <ref>	Parent initiative (INIT-XXX or slug)	Yes
--wu <wuId>	Work Unit ID to link (e.g., WU-123)	Yes

initiative:rename

Rename an initiative and rewrite linked references

pnpm initiative:rename --from <wuId> --to <wuId>

Options:

Flag	Description	Required
--from <wuId>	Original WU ID to rename from (e.g. WU-5)	Yes
--to <wuId>	Target WU ID to rename to (e.g. WU-0015)	Yes

initiative:status

Show initiative status

pnpm initiative:status

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	No
--format <format>	Output format (table, json, ascii, mermaid)	No
--color	Enable colored output	No

Memory & Sessions

mem:checkpoint

Save progress checkpoint

pnpm mem:checkpoint

Options:

Flag	Description	Required
--wu <wuId>	Work Unit ID to link (e.g., WU-123)	No
-n, --note <text>	Checkpoint note (required if not positional)	No
-s, --session <id>	Session ID to link checkpoint to (UUID)	No
-p, --progress <text>	Progress summary	No
--next-steps <text>	Next steps description	No
-t, --trigger <type>	Handoff trigger type (e.g., clear, handoff)	No
--git-diff-stat <text>	Git diff —stat output to include in checkpoint metadata (WU-2157)	No
-d, --base-dir <path>	Base directory (defaults to current directory)	No
-q, --quiet	Suppress output except errors	No

mem:cleanup

Clean up stale memory data

pnpm mem:cleanup

Options:

Flag	Description	Required
--dry-run	Preview cleanup without making changes	No
--ttl <duration>	Remove nodes older than duration (e.g., 30d, 7d, 24h). Active sessions are protected.	No
--session-id <uuid>	Session ID to consider closed (removes session lifecycle nodes)	No
--json	Output as JSON	No
-q, --quiet	Suppress output except errors	No
-b, --base-dir <path>	Base directory (defaults to current directory)	No
--decay	Run decay-based archival (archive stale nodes below threshold). Uses config from workspace.yaml software_delivery or defaults.	No

mem:context

Get context for current lane/WU

pnpm mem:context --wu <wuId>

Options:

Flag	Description	Required
--wu <wuId>	Work Unit ID to link (e.g., WU-123)	Yes
-m, --max-size <bytes>	Maximum context size in bytes (default: 4096)	No
--delegation-context-max-size <bytes>	Alias for —max-size (for config parity with delegation_context_max_size)	No
-l, --lane <lane>	Filter project memories by lane (e.g., “Framework: CLI”)	No
--max-recent-summaries <count>	Maximum number of recent summaries to include (default: 5)	No
--max-project-nodes <count>	Maximum number of project nodes to include (default: 10)	No
-f, --format <format>	Output format: json or human (default: human)	No
-d, --base-dir <path>	Base directory (defaults to current directory)	No
-q, --quiet	Suppress header/footer output, only show context block	No
--include-roster	Legacy alias; roster auto-composes by default when active sessions exist	No
--no-roster	Disable automatic coordination roster composition	No
--initiative <id>	Initiative ID to scope the roster to	No

mem:create

Create memory node (bug discovery)

pnpm mem:create

Options:

Flag	Description	Required
--wu <wuId>	Work Unit ID to link (e.g., WU-123)	No
-t, --title <text>	Node title/content (required if not positional)	No
--title-file <path>	Read title from file (prefer over —title for prose with $, backticks, !; bypasses shell expansion)	No
-d, --discovered-from <id>	Parent node ID for provenance tracking (mem-XXXX format)	No
-s, --session <id>	Session ID to link node to (UUID)	No
--tags <tags>	Comma-separated tags for categorization	No
-p, --priority <level>	Priority level (P0, P1, P2, P3)	No
-b, --base-dir <path>	Base directory (defaults to current directory)	No
-q, --quiet	Suppress output except errors	No

mem:delete

Delete/archive a memory node

pnpm mem:delete

Options:

Flag	Description	Required
--dry-run	Preview deletion without making changes	No
--id <nodeId...>	Node ID to delete (mem-XXXX; repeatable). Also accepted as positional args.	No
--tag <tag>	Delete all nodes matching this tag	No
--older-than <duration>	Delete nodes older than duration (e.g., 30d, 7d, 24h, 2w)	No
--json	Output as JSON	No
-q, --quiet	Suppress output except errors	No
-b, --base-dir <path>	Base directory (defaults to current directory)	No

mem:export

Export memory as markdown

pnpm mem:export

Options:

Flag	Description	Required
--wu <wuId>	Work Unit ID to link (e.g., WU-123)	No
-l, --lifecycle <lifecycle>	Filter by lifecycle (ephemeral, session, wu, project)	No
-f, --format <format>	Output format (markdown, json). Default: markdown	No
-d, --base-dir <path>	Base directory (defaults to current directory)	No
-q, --quiet	Suppress header/footer output	No

mem:inbox

Check coordination signals

pnpm mem:inbox

Options:

Flag	Description	Required
--wu <wuId>	Work Unit ID to link (e.g., WU-123)	No
-l, --lane <lane>	Lane name (e.g., “Operations: Tooling”)	No
-s, --since <time>	Filter signals since time (e.g., “1h”, “30m”, “2025-12-09”)	No
-w, --watch	Continuously monitor for new signals	No
-q, --quiet	Suppress output except signal content	No
--no-mark	Do not mark signals as read after display	No
-c, --count	Output only signal count (lightweight polling for orchestrators)	No
--for <session_id|display_name>	Show signals addressed to a live session, plus broadcasts	No

mem:init

Initialize memory for WU

pnpm mem:init

Options:

Flag	Description	Required
-d, --base-dir <path>	Base directory to initialize (defaults to current directory)	No
-q, --quiet	Suppress output except errors	No

mem:ready

Check pending memory nodes

pnpm mem:ready --wu <wuId>

Options:

Flag	Description	Required
--wu <wuId>	Work Unit ID to link (e.g., WU-123)	Yes
-f, --format <format>	Output format (json, human). Default: human	No
-d, --base-dir <path>	Base directory (defaults to current directory)	No
-q, --quiet	Suppress header/footer output, only show nodes	No

mem:recover

Generate recovery context after compaction

pnpm mem:recover --wu <wuId>

Options:

Flag	Description	Required
--wu <wuId>	Work Unit ID to link (e.g., WU-123)	Yes
-m, --max-size <bytes>	Maximum output size in bytes (default: 2048)	No
-f, --format <format>	Output format: json or human (default: human)	No
-d, --base-dir <path>	Base directory (defaults to current directory)	No
-q, --quiet	Suppress header/footer output, only show recovery context	No

mem:roster

List live agent sessions and role axes

pnpm mem:roster

Options:

Flag	Description	Required
--json	Output roster entries as JSON	No
--initiative <id>	Limit roster to sessions linked to an initiative	No

mem:signal

Broadcast coordination signal

pnpm mem:signal

Options:

Flag	Description	Required
--wu <wuId>	Work Unit ID to link (e.g., WU-123)	No
-l, --lane <lane>	Lane name (e.g., “Operations: Tooling”)	No
-m, --message <text>	Signal message (required if not positional)	No
-q, --quiet	Suppress output except errors (outputs signal ID only)	No
--role <descriptor>	Sender ADR-014 role descriptor (e.g. “implementer/general”)	No
--target-role <descriptor>	Intended-recipient role descriptor (filter-able via mem:inbox)	No
--initiative <id>	Initiative scope (e.g., INIT-060)	No
--delegation-id <id>	Delegation registry linkage (dlg-XXXX)	No
--to <session_id|display_name>	Address the signal to a live session by session ID or display name	No

mem:start

Start a memory session

pnpm mem:start --wu <wuId>

Options:

Flag	Description	Required
--wu <wuId>	Work Unit ID to link (e.g., WU-123)	Yes
-a, --agent-type <type>	Agent type (e.g., general-purpose, explore, test-engineer)	No
-c, --context-tier <tier>	Context tier (core, full, minimal)	No
-d, --base-dir <path>	Base directory (defaults to current directory)	No
-q, --quiet	Suppress output except errors	No

mem:summarize

Summarize memory context

pnpm mem:summarize --wu <id>

Options:

Flag	Description	Required
--wu <id>	WU ID to summarize (e.g., WU-1234)	Yes
--dry-run	Preview summary without making changes	No
--json	Output as JSON	No
-q, --quiet	Suppress output except errors	No
-b, --base-dir <path>	Base directory (defaults to current directory)	No

mem:triage

Triage discovered bugs

pnpm mem:triage

Options:

Flag	Description	Required
-l, --list	List open discoveries (default action)	No
-p, --promote <nodeId>	Promote discovery to WU (mem-XXXX format)	No
-a, --archive <nodeId>	Archive discovery without promotion (mem-XXXX format)	No
-r, --reason <text>	Reason for archiving (required with —archive)	No
--title <text>	Custom title for promoted WU (optional)	No
--lane <lane>	Lane for promoted WU (required with —promote)	No
--wu-id <id>	Explicit WU ID for promotion (optional)	No
--wu <id>	Filter discoveries by WU ID (or “unlinked”)	No
--tag <tag>	Filter discoveries by tag	No
--dry-run	Preview promotion without creating WU	No
--json	Output as JSON	No
-q, --quiet	Suppress output except errors	No

signal:cleanup

Clean up stale signals

pnpm signal:cleanup

Options:

Flag	Description	Required
--dry-run	Preview cleanup without making changes	No
--ttl <duration>	TTL for read signals (e.g., 7d, 24h). Default: 7d	No
--unread-ttl <duration>	TTL for unread signals (e.g., 30d). Default: 30d	No
--max-entries <count>	Maximum signals to retain. Default: 500	No
--json	Output as JSON	No
-q, --quiet	Suppress output except errors	No
-b, --base-dir <path>	Base directory (defaults to current directory)	No

Metrics & Flow

cost:summary

Summarize local cost telemetry

pnpm cost:summary

flow:bottlenecks

Identify flow bottlenecks

pnpm flow:bottlenecks

flow:report

Generate flow metrics report

pnpm flow:report

metrics

View workflow metrics

pnpm metrics

metrics:snapshot

Capture metrics snapshot

pnpm metrics:snapshot

Orchestration

agent:issues-query

Query GitHub issues for agent work

pnpm agent:issues-query

agent:log-issue

Log issue during agent session

pnpm agent:log-issue --category <cat> --severity <sev> --title <title> --description <desc>

Options:

Flag	Description	Required
--category <cat>	Issue category (workflow|tooling|confusion|violation|error)	Yes
--severity <sev>	Severity level (blocker|major|minor|info)	Yes
--title <title>	Short description (5-100 chars)	Yes
--description <desc>	Detailed context (10-2000 chars)	Yes
--resolution <res>	How the issue was resolved	No
--tag <tag>	Tag for categorization (repeatable)	No
--step <step>	Current workflow step (e.g., wu:done, gates)	No
--file <file>	Related file path (repeatable)	No

agent:session

Start agent session

pnpm agent:session --wu <wuId> --tier <tier>

Options:

Flag	Description	Required
--wu <wuId>	WU ID to work on (e.g., WU-1234)	Yes
--tier <tier>	Context tier (1, 2, or 3)	Yes
--agent-type <type>	Agent type (default: claude-code)	No

agent:session-end

End agent session

pnpm agent:session-end

delegation:list

List delegation and launch records with planned-versus-launched state

pnpm delegation:list

Options:

Flag	Description	Required
--wu <wuId>	Work Unit ID to link (e.g., WU-123)	No
--initiative <initId>	Initiative ID to show all delegations for (e.g., INIT-001)	No
--json	Output as JSON	No

orchestrate:init-status

Compact initiative status with evidence-based orchestration state

pnpm orchestrate:init-status

orchestrate:initiative

Plan, launch, and reconcile initiative execution with structured orchestration artifacts; launch modes print lean summaries by default and can replay stored handoffs inline

pnpm orchestrate:initiative --initiative <ids...>

Options:

Flag	Description	Required
-i, --initiative <ids...>	Initiative ID(s) to orchestrate	Yes
-d, --dry-run	Show execution plan without spawning agents	No
-p, --progress	Show current progress only	No
-c, --checkpoint-per-wave	Spawn next wave then exit (no polling)	No
--no-checkpoint	Force polling mode	No
--client <name>	Agent client (claude-code, codex-cli, gemini-cli, cursor, windsurf)	No
--print-handoffs	Print stored handoff artifacts inline for manual copy/paste output	No
--max-active-workers <count>	Cap concurrent active workers; overrides software_delivery.orchestration.max_active_workers	No

orchestrate:monitor

Monitor orchestration progress, stalls, returned workers, and recovery signals

pnpm orchestrate:monitor

task:claim

Claim a task directly through KernelRuntime

pnpm task:claim

Packs

pack:author

Author a secure domain pack from templates

pnpm pack:author

Options:

Flag	Description	Required
-f, --force	Force operation	No
--spec-file <path>	Path to YAML/JSON request file for non-interactive generation	No
--skip-validate	Skip post-generation pack validation	No

pack:hash

Compute integrity hash for a domain pack

pnpm pack:hash

Options:

Flag	Description	Required
-f, --force	Force operation	No
--pack-root <dir>	Direct path to pack directory (overrides —id and —packs-root)	No

pack:install

Install a domain pack into workspace

pnpm pack:install --source <source> --version <version>

Options:

Flag	Description	Required
-f, --force	Force operation	No
--source <source>	Pack source: local, git, or registry	Yes
--version <version>	Pack version in semver format	Yes
--url <url>	Git repository URL (required for source: git)	No
--registry-url <url>	Registry base URL (for source: registry)	No
--pack-root <dir>	Direct path to resolved pack directory on disk (overrides default resolution)	No
--integrity &lt;hash&gt;	Expected SHA-256 integrity hash in “sha256:<hex>” format (optional)	No

pack:publish

Publish a domain pack to a registry

pnpm pack:publish

Options:

Flag	Description	Required
-f, --force	Force operation	No
--pack-root <dir>	Direct path to pack directory (overrides —id and —packs-root)	No

pack:scaffold

Scaffold a new domain pack

pnpm pack:scaffold --version <version>

Options:

Flag	Description	Required
-f, --force	Force operation	No
--version <version>	Pack version in semver format (e.g., “0.1.0”)	Yes
--task-type <type>	Task type name (repeatable)	No
--tool <name>	Tool name to scaffold (repeatable)	No

pack:search

Search for domain packs in a registry

pnpm pack:search

Options:

Flag	Description	Required
--query <query>	Search query string	No

pack:validate

Validate a domain pack for integrity

pnpm pack:validate

Options:

Flag	Description	Required
-f, --force	Force operation	No
--pack-root <dir>	Direct path to pack directory (overrides —id and —packs-root)	No

Plans

plan:create

Create a new plan

pnpm plan:create --id <wuId> --title <title>

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	Yes
-t, --title <title>	Work Unit title	Yes

plan:edit

Edit plan content

pnpm plan:edit --id <wuId>

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	Yes

plan:link

Link plan to WU or initiative

pnpm plan:link --id <wuId>

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	Yes

plan:promote

Promote plan to WU

pnpm plan:promote --id <wuId>

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	Yes

Setup & Development

backlog:prune

Clean stale backlog entries

pnpm backlog:prune

cloud:connect

Connect workspace.yaml to cloud control plane

pnpm cloud:connect

config:get

Read and display a value from workspace.yaml software_delivery

pnpm config:get

config:set

Safely update workspace.yaml software_delivery via micro-worktree

pnpm config:set

distribution:preflight

Audit consumer repos for @lumenflow/* privatization readiness

pnpm distribution:preflight

file:delete

Delete file with audit trail

pnpm file:delete

file:edit

Edit file with audit trail

pnpm file:edit

file:read

Read file with audit trail

pnpm file:read

file:write

Write file with audit trail

pnpm file:write

git:branch

Show git branch with audit trail

pnpm git:branch

git:diff

Show git diff with audit trail

pnpm git:diff

git:log

Show git log with audit trail

pnpm git:log

git:status

Show git status with audit trail

pnpm git:status

lumenflow

Initialize LumenFlow in a project

pnpm lumenflow

lumenflow:commands

List all available CLI commands

pnpm lumenflow:commands

lumenflow:disable

Flip enforcement flags to false and regenerate hooks as no-ops (reversible)

pnpm lumenflow:disable

lumenflow:docs-sync

Refresh core docs, onboarding docs, and supported vendor assets

pnpm lumenflow:docs-sync

lumenflow:doctor

Diagnose LumenFlow configuration

pnpm lumenflow:doctor

lumenflow:enable

Re-enable enforcement after lumenflow:disable (restores prior state)

pnpm lumenflow:enable

lumenflow:integrate

Generate enforcement hooks for client

pnpm lumenflow:integrate

lumenflow:release

Run release workflow

pnpm lumenflow:release

lumenflow:sync-templates

Sync templates to project

pnpm lumenflow:sync-templates

lumenflow:uninstall

Remove LumenFlow-generated files (dry-run by default; requires —confirm)

pnpm lumenflow:uninstall

lumenflow:upgrade

Upgrade LumenFlow packages

pnpm lumenflow:upgrade

State Management

state:bootstrap

Bootstrap state store

pnpm state:bootstrap

state:cleanup

Clean up stale state data

pnpm state:cleanup

Options:

Flag	Description	Required
--dry-run	Preview cleanup without making changes	No
--signals-only	Only execute signal cleanup	No
--memory-only	Only execute memory cleanup	No
--events-only	Only execute event archival	No
--json	Output as JSON	No
-q, --quiet	Suppress output except errors and summary	No
-b, --base-dir <path>	Base directory (defaults to current directory)	No

state:doctor

Diagnose state store issues

pnpm state:doctor

Options:

Flag	Description	Required
--fix	Auto-repair safe issues	No
--dry-run	Preview repairs without making changes	No
--json	Output as JSON	No
-q, --quiet	Suppress output except errors and summary	No
-b, --base-dir <path>	Base directory (defaults to current directory)	No

state:emit

Emit corrective event to state store (WU-2241)

pnpm state:emit

WU Lifecycle

approval:list

List control-plane approvals with optional filters

pnpm approval:list

approval:request

Request control-plane approval for a workflow action

pnpm approval:request

approval:review

Resolve a control-plane approval decision

pnpm approval:review

wu:block

Block WU with reason

pnpm wu:block --id <wuId>

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	Yes
-r, --reason <reason>	Reason for action (required with —skip-gates, —override-owner)	No
-w, --worktree <path>	Override worktree path	No
--remove-worktree	Remove worktree when blocking	No
--no-auto	Skip auto-updating YAML/backlog/status	No
--override-owner	Override ownership check (requires —reason)	No

wu:brief

Generate the canonical full WU handoff prompt and record brief evidence

pnpm wu:brief --id <wuId>

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	Yes
--thinking	Enable extended thinking for sub-agent WU execution	No
--no-thinking	Explicitly disable extended thinking (default behavior)	No
--budget <tokens>	Token budget for extended thinking (requires —thinking)	No
--codex	Deprecated: use —client codex-cli. Outputs Markdown prompt format.	No
--parent-wu <wuId>	Parent WU ID for orchestrator context (e.g., WU-1000)	No
--client <client>	Target client (e.g. claude-code, codex-cli, gemini-cli)	No
--vendor <vendor>	Deprecated alias for —client	No
--no-context	Skip memory context injection in handoff prompts	No
--evidence-only	[DEPRECATED] Removed in WU-2359. Use wu:brief —client <client> instead (always gives full context + records evidence).	No
--strict-sizing	Block when sizing_estimate metadata is missing or exceeds thresholds without exception. Advisory by default.	No

wu:claim

Claim WU and create worktree

pnpm wu:claim --id <wuId>

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	Yes
-l, --lane <lane>	Lane name (e.g., “Operations: Tooling”)	No
-w, --worktree <path>	Override worktree path	No
-b, --branch <branch>	Override branch name	No
--branch-only	Use branch-only mode (no worktree)	No
--pr-mode	Use PR mode (create PR instead of auto-merge)	No
--no-auto	Skip auto-updating YAML/backlog/status	No
-f, --force	Force operation	No
--force-overlap	Force claiming despite overlap (requires —reason)	No
--fix	Auto-fix common YAML validation issues (WU-1359)	No
-r, --reason <reason>	Reason for action (required with —skip-gates, —override-owner)	No
--allow-incomplete	Allow claiming with incomplete spec (bypasses spec completeness, NOT schema errors)	No
--cloud	Use cloud/branch-pr mode (no worktree, PR-based completion for cloud agents and MCP callers)	No
--resume	Resume a WU from a crashed/killed agent (handoff) by taking over the existing worktree and updating the lock with new PID. Fails if original PID is still running (safety) or worktree does not exist.	No
--skip-setup	Skip automatic pnpm install in worktree after creation (faster claims when deps already built)	No
--no-push	Skip pushing claim branch or canonical updates (air-gapped/offline)	No
--wait-for-lane	Queue the claim when code-path overlaps exist and auto-fire once every blocker WU has merged (WU-2668)	No
--wait-timeout-seconds <seconds>	Maximum seconds to wait for blocker WUs to merge before giving up (default 3600, used with —wait-for-lane)	No
--cancel-queue	Cancel an active queued claim for —id (pairs with —wait-for-lane) (WU-2668)	No

wu:create

Create new WU spec

pnpm wu:create --lane <lane> --title <title>

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	No
-l, --lane <lane>	Lane name (e.g., “Operations: Tooling”)	Yes
-t, --title <title>	Work Unit title	Yes
-p, --priority <priority>	Priority level (P0, P1, P2, P3)	No
--type <type>	WU type (feature, bug, documentation, process, tooling, chore, refactor)	No
--initiative <ref>	Parent initiative (INIT-XXX or slug)	No
--phase <number>	Phase number within initiative	No
--blocked-by <wuIds>	WU IDs that block this WU (repeatable)	No
--blocks <wuIds>	WU IDs this WU blocks (repeatable)	No
--labels <labels>	Labels (repeatable)	No
--assigned-to <email>	Override assigned_to (defaults to git config user.email)	No
--description <text>	WU description text (Context/Problem/Solution)	No
--acceptance <criterion>	Acceptance criterion (repeatable, use multiple times)	No
--notes <text>	Implementation notes or context (optional)	No
--code-paths <paths>	Code paths (repeatable)	No
--test-paths-manual <tests>	Manual test descriptions (repeatable)	No
--test-paths-unit <paths>	Unit test file paths (repeatable)	No
--test-paths-e2e <paths>	E2E test file paths (repeatable)	No
--validate	Validate spec completeness (requires description, acceptance, test paths)	No
--spec-refs <paths>	Spec/plan references (repeatable or comma-separated, required for type: feature)	No
--exposure <type>	Exposure level (ui, api, backend-only, documentation)	No
--user-journey <text>	User journey description (recommended for ui/api exposure)	No
--ui-pairing-wus <wuIds>	UI WU IDs that consume this API (repeatable or comma-separated, for api exposure)	No
--plan	Create plan template in $LUMENFLOW_HOME/plans/ (external plan storage)	No
--estimated-files <count>	Optional sizing estimate: expected number of files to modify (non-negative integer)	No
--estimated-tool-calls <count>	Optional sizing estimate: expected number of tool calls (non-negative integer)	No
--sizing-strategy <strategy>	Optional sizing strategy (single-session, checkpoint-resume, orchestrator-worker, decomposition)	No
--sizing-exception-type <type>	Optional sizing exception type when thresholds are exceeded (docs-only, shallow-multi-file)	No
--sizing-exception-reason <text>	Optional sizing exception justification text	No
--no-strict	Bypass code_paths/test_paths path existence checks. Reality-phase checks run at wu:prep/wu:done. Logged when used.	No
--cloud	Use cloud/branch-pr mode (no worktree, PR-based completion for cloud agents and MCP callers)	No
--offline	Skip remote fetch during ID generation (air-gapped/offline mode)	No

wu:delegate

Generate the canonical delegation handoff prompt and record explicit lineage intent

pnpm wu:delegate --id <wuId>

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	Yes
--thinking	Enable extended thinking for sub-agent WU execution	No
--no-thinking	Explicitly disable extended thinking (default behavior)	No
--budget <tokens>	Token budget for extended thinking (requires —thinking)	No
--codex	Deprecated: use —client codex-cli. Outputs Markdown prompt format.	No
--parent-wu <wuId>	Parent WU ID for orchestrator context (e.g., WU-1000)	No
--client <client>	Target client (e.g. claude-code, codex-cli, gemini-cli)	No
--vendor <vendor>	Deprecated alias for —client	No
--no-context	Skip memory context injection in handoff prompts	No
--evidence-only	[DEPRECATED] Removed in WU-2359. Use wu:brief —client <client> instead (always gives full context + records evidence).	No
--strict-sizing	Block when sizing_estimate metadata is missing or exceeds thresholds without exception. Advisory by default.	No

wu:done

Complete WU (merge, stamp, cleanup) from main

pnpm wu:done

wu:edit

Edit WU spec fields

pnpm wu:edit --id <wuId>

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	Yes
--test-paths-manual <tests>	Manual test descriptions (repeatable)	No
--test-paths-unit <paths>	Unit test file paths (repeatable)	No
--test-paths-e2e <paths>	E2E test file paths (repeatable)	No
--exposure <type>	Exposure level (ui, api, backend-only, documentation)	No
--no-strict	Bypass code_paths/test_paths path existence checks. Reality-phase checks run at wu:prep/wu:done. Logged when used.	No
--spec-file <path>	Path to YAML file with updated spec content	No
--title <text>	New title text (replaces existing)	No
--description <text>	New description text (replaces existing)	No
--acceptance <criterion>	Acceptance criterion (repeatable, appends to existing; use —replace-acceptance to overwrite)	No
--notes <text>	Notes text (appends to existing; use —replace-notes to overwrite)	No
--replace-notes	Replace existing notes instead of appending	No
--replace-acceptance	Replace existing acceptance criteria instead of appending	No
--code-paths <path>	Code path (repeatable, appends to existing; use —replace-code-paths to overwrite)	No
--remove-code-paths <path>	Remove specific code_paths entries without replacing the full array	No
--rename-code-paths <old=new>	Rename specific code_paths entries without rewriting the full array	No
--replace-code-paths	Replace existing code_paths instead of appending	No
--risks <risk>	Risk entry (repeatable, appends to existing; use —replace-risks to overwrite)	No
--replace-risks	Replace existing risks instead of appending	No
--append	[DEPRECATED] Arrays now append by default. Use —replace-* flags to replace.	No
--remove-test-paths-manual <text>	Remove specific manual test entries without replacing the full array	No
--rename-test-paths-manual <old=new>	Rename specific manual test entries without rewriting the full array	No
--remove-test-paths-unit <path>	Remove specific unit test paths without replacing the full array	No
--rename-test-paths-unit <old=new>	Rename specific unit test paths without rewriting the full array	No
--remove-test-paths-e2e <path>	Remove specific e2e test paths without replacing the full array	No
--rename-test-paths-e2e <old=new>	Rename specific e2e test paths without rewriting the full array	No
--replace-test-paths-unit	Replace existing unit test paths instead of appending	No
--replace-test-paths-e2e	Replace existing e2e test paths instead of appending	No
--replace-test-paths-manual	Replace existing manual test descriptions instead of appending	No
--lane <lane>	New lane assignment (e.g., “Operations: Tooling”)	No
--type <type>	New WU type (feature, bug, refactor, documentation)	No
--priority <priority>	New priority (P0, P1, P2, P3)	No
--initiative <initId>	Initiative ID (e.g., INIT-001). Updates WU and initiative wus: arrays bidirectionally.	No
--phase <number>	Phase number within initiative (e.g., 1, 2)	No
--blocked-by <wuIds>	Comma-separated WU IDs that block this WU (appends to existing; use —replace-blocked-by to overwrite)	No
--replace-blocked-by	Replace existing blocked_by instead of appending	No
--add-dep <wuIds>	Comma-separated WU IDs to add to dependencies array (appends to existing; use —replace-dependencies to overwrite)	No
--replace-dependencies	Replace existing dependencies instead of appending	No
--plan <uri>	Plan file URI (lumenflow://plans/… or repo-relative path)	No

wu:escalate

Show or resolve WU escalation status

pnpm wu:escalate --id <wuId>

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	Yes
--resolve	Resolve the escalation (set resolved_by and resolved_at)	No
--resolver <email>	Override resolver email (defaults to git user.email)	No

wu:prep

Run gates in worktree, prep for wu:done

pnpm wu:prep --id <wuId>

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	Yes
--docs-only	Run docs-only gates (format, spec-linter)	No
--full-tests	Run full incremental test suite (disable tests.unit scoped execution)	No

wu:recover

Analyze and fix WU state inconsistencies

pnpm wu:recover --id <wuId>

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	Yes
--override-owner	Override ownership check (requires —reason)	No
-r, --reason <reason>	Reason for action (required with —skip-gates, —override-owner)	No

wu:release

Release orphaned WU (in_progress to ready)

pnpm wu:release --id <wuId> --reason <reason>

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	Yes
-r, --reason <reason>	Reason for action (required with —skip-gates, —override-owner)	Yes
--override-owner	Override ownership check (requires —reason)	No

wu:rename

Rename a WU (canonical WU IDs, —replay-only supported)

pnpm wu:rename --from <wuId> --to <wuId>

Options:

Flag	Description	Required
--from <wuId>	Original WU ID to rename from (e.g. WU-5)	Yes
--to <wuId>	Target WU ID to rename to (e.g. WU-0015)	Yes
-r, --reason <reason>	Reason for action (required with —skip-gates, —override-owner)	No
--replay-only	Skip file/stamp renames; only append wu_renamed event and regenerate backlog/status	No

wu:sandbox

Run command through hardened WU sandbox backend

pnpm wu:sandbox --id <wuId>

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	Yes
-w, --worktree <path>	Override worktree path	No

wu:status

Show WU status, location, valid commands

pnpm wu:status

wu:unblock

Unblock WU

pnpm wu:unblock --id <wuId>

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	Yes
-r, --reason <reason>	Reason for action (required with —skip-gates, —override-owner)	No
--create-worktree	Create worktree when unblocking	No
-w, --worktree <path>	Override worktree path	No
-b, --branch <branch>	Override branch name	No
--no-auto	Skip auto-updating YAML/backlog/status	No
-f, --force	Force operation	No
--override-owner	Override ownership check (requires —reason)	No

wu:validate

Validate WU spec

pnpm wu:validate

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	No
--no-strict	Bypass code_paths/test_paths path existence checks. Reality-phase checks run at wu:prep/wu:done. Logged when used.	No

wu:verify

Verify WU completion (stamp, commit, clean tree)

pnpm wu:verify --id <wuId>

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	Yes

WU Maintenance

wu:cleanup

Cleanup after PR merge

pnpm wu:cleanup

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	No
--artifacts	Remove build artifacts (dist, tsbuildinfo) in current worktree	No

wu:delete

Delete WU spec and cleanup

pnpm wu:delete

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	No
--dry-run	Show what would be deleted without making changes	No
--batch <ids>	Delete multiple WUs atomically (comma-separated: WU-1,WU-2,WU-3)	No

wu:deps

Show WU dependencies

pnpm wu:deps

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	No
--format <format>	Output format (table, json, ascii, mermaid)	No
-d, --depth <number>	Maximum traversal depth	No
--direction <dir>	Graph direction (up, down, both)	No

wu:infer-lane

Infer lane from code paths/description using workspace definitions

pnpm wu:infer-lane

wu:preflight

Pre-flight checks before wu:done

pnpm wu:preflight --id <wuId>

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	Yes
-w, --worktree <path>	Override worktree path	No

wu:proto

Create WU prototype

pnpm wu:proto --lane <lane> --title <title>

Options:

Flag	Description	Required
-l, --lane <lane>	Lane name (e.g., “Operations: Tooling”)	Yes
-t, --title <title>	Work Unit title	Yes
--description <text>	WU description text (Context/Problem/Solution)	No
--code-paths <paths>	Code paths (repeatable)	No
--labels <labels>	Labels (repeatable)	No
--assigned-to <email>	Override assigned_to (defaults to git config user.email)	No

wu:prune

Clean stale worktrees

pnpm wu:prune

wu:repair

Repair WU state issues

pnpm wu:repair

wu:review

Review a WU worktree against the configured integration target

pnpm wu:review --id <wuId>

Options:

Flag	Description	Required
-i, --id <wuId>	Work Unit ID (e.g., WU-123). If not provided, auto-generates next sequential ID.	Yes
-w, --worktree <path>	Override worktree path	No

wu:unlock-lane

Unlock stuck lane

pnpm wu:unlock-lane

Options:

Flag	Description	Required
-l, --lane <lane>	Lane name (e.g., “Operations: Tooling”)	No
-r, --reason <reason>	Reason for action (required with —skip-gates, —override-owner)	No
-f, --force	Force operation	No

---

Next Steps

• Configuration – Configure LumenFlow
• WU Schema – Work Unit YAML structure