CLI Commands

LumenFlow provides a curated public CLI surface for everyday workflows.

Commands Overview

Gates & Quality

cert:verify

Verify an agent promotion-ladder transition against certification evidence

pnpm cert:verify

eval:run

Run a certification scenario suite against an agent evaluation report

pnpm eval:run

eval:suite

Define, list, and validate agent certification scenario suites

pnpm eval:suite

events:validate

Validate event payloads against the published schema catalog

pnpm events:validate

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

Options:

| Flag | Description | Required | | --------------- | --------------------------- | -------- | | -j, --json | Output as JSON | No | | -v, --verbose | Show verbose output | No | | --no-coverage | Skip coverage gap detection | No |

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

Options:

| Flag | Description | Required | | -------------------- | ---------------------------------------------------------- | -------- | | --ci | Use CI diff mode (range-based) instead of staged diff mode | No | | --base <ref> | Base git ref/sha for CI mode | No | | --head <ref> | Head git ref/sha for CI mode (default: HEAD) | No |

test:baseline:init

Create .lumenflow/test-baseline.json from current failing tests

pnpm test:baseline:init

Options:

| Flag | Description | Required | | ----------------------- | -------------------------------------- | -------- | | --mode <mode> | Baseline operation: init or update | No | | --wu <wuId> | WU ID recording the baseline update | No | | --reason <text> | Reason stored on each captured failure | No |

test:baseline:update

Refresh .lumenflow/test-baseline.json from current failing tests

pnpm test:baseline:update

Options:

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 | 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:converged

Evaluate whether an A2A signal thread has converged

pnpm mem:converged

Options:

| Flag | Description | Required | | --------------------- | ----------------------------------------- | -------- | | --thread <id> | A2A thread id to evaluate | No | | -q, --quiet | Suppress detail output; rely on exit code | 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\|agent_identity> | Show signals addressed to a session or agent identity, plus broadcasts | No | | --thread <id> | Show signals in a single A2A thread | No | | --intent <intent[,intent...]> | Filter by A2A intent values (INFO, PROPOSE, COUNTER, AGREE, REJECT) | 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 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-001) | No | | --delegation-id <id> | Delegation registry linkage (dlg-XXXX) | No | | --to <recipient[,recipient...]> | Address the signal to one or more session IDs, display names, or agent identities | No | | --thread <id> | A2A thread id for grouping signals | No | | --reply-to <signal_id> | Parent signal id; inherits the parent thread when —thread is omitted | No | | --intent <INFO\|PROPOSE\|COUNTER\|AGREE\|REJECT> | Machine-readable A2A signal intent | No | | --interrupt-class <advisory\|priority\|urgent\|soon\|immediate> | A2A interrupt class (advisory|priority|urgent canonical; soon|immediate are legacy aliases) | No | | --interrupt <advisory\|priority\|urgent\|soon\|immediate> | [DEPRECATED] Legacy alias for —interrupt-class. Same enum values. | No | | --requires-ack | Mark the signal as requiring an AGREE or REJECT reply | 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 |

mem:watch

Deliver A2A signal events for clients without native hooks

pnpm mem:watch --session <id>

Options:

| Flag | Description | Required | | ---------------------- | ------------------------------------------------------------------------ | -------- | | --session <id> | Active session_id, display_name, or agent_identity to deliver events for | Yes | | -q, --quiet | Suppress watcher lifecycle messages; signal events still print | 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 or brief metrics with —brief

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:resolve

Show effective vendor model routing (model_profile → model) per agent

pnpm agent:resolve

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

orchestrate:pre-phase-audit

Print a read-only pre-phase audit checklist before creating phase WUs

pnpm orchestrate:pre-phase-audit

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 <hash> | Expected SHA-256 integrity hash in “sha256:<hex>” format (optional) | No |

pack:publish

Publish a domain pack to a registry

pnpm pack:publish

Options:

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:

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:

plan:link

Link plan to WU or initiative

pnpm plan:link --id <wuId>

Options:

plan:promote

Promote plan to WU

pnpm plan:promote --id <wuId>

Options:

Setup & Development

backlog:prune

Clean stale backlog entries

pnpm backlog:prune

cloud:connect

Connect workspace.yaml to cloud control plane

pnpm cloud:connect

compute:connect

Enrol the runner with the cloud control-plane (experimental developer substrate)

pnpm compute:connect

compute:doctor

Self-check the Connected Compute runner (experimental developer substrate)

pnpm compute:doctor

compute:run

Run the governed Connected Compute polling loop (experimental)

pnpm compute:run

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

config:unset

Safely delete a key from workspace.yaml via micro-worktree

pnpm config:unset

db:journal-recover

Detect drizzle journal collisions and offer a safe-resequence path (dry-run by default; —confirm applies)

pnpm db:journal-recover

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

git:sync-main

Fast-forward a clean local main checkout to origin/main

pnpm git:sync-main

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

Options:

| Flag | Description | Required | | ----------------------- | ----------------------------------------------- | -------- | | --client <type> | Scope to a single client (default: claude-code) | No | | --json | Emit machine-readable JSON output | No |

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

Options:

lumenflow:integrate

Generate enforcement hooks for client

pnpm lumenflow:integrate

lumenflow:migrate-state

Explicit standalone Software Delivery state-namespace cutover (main checkout only; for repos that never run lumenflow:upgrade)

pnpm lumenflow:migrate-state

lumenflow:release

Run release workflow

pnpm lumenflow:release

lumenflow:setup-prereqs

Surface external prerequisites and local runtime readiness at end of pnpm setup

pnpm lumenflow:setup-prereqs

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

Options:

| Flag | Description | Required | | ----------------------- | --------------------------------------------------------- | -------- | | --confirm | Actually delete files. Without this, runs as a dry-run. | No | | --keep-history | Preserve docs/operations/tasks/wu/ and .lumenflow/stamps/ | No | | --keep-config | Preserve workspace.yaml and .lumenflow/constraints.md | No | | --client <type> | Scope deletion to a single client (default: all) | No | | --json | Emit machine-readable JSON output | No |

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

pnpm state:emit

Options:

| Flag | Description | Required | | ----------------------------- | ----------------------------------------------------------- | -------- | | --wu <wuId> | Work Unit ID (e.g., WU-123) | No | | -r, --reason <reason> | Reason for the corrective event (required) | No | | -b, --base-dir <path> | Base directory (defaults to current directory) | No | | --transactional | Commit corrective event via micro-worktree (push-only mode) | No |

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-gate, —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, record evidence, and optionally report prompt tokens

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, cursor, windsurf) | No | | --vendor <vendor> | Deprecated alias for —client | No | | --no-context | Skip memory context injection in handoff prompts | No | | --evidence-only | [DEPRECATED] Removed. 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 | No | | -r, --reason <reason> | Reason for action (required with —skip-gate, —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 | 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) | No |

wu:create

Create new WU spec

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

Options:

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

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 | | --spec-refs <path> | Spec/plan reference (repeatable, appends to existing; use —replace-spec-refs to overwrite) | No | | --remove-spec-refs <path> | Remove specific spec_refs entries without replacing the full array | No | | --rename-spec-refs <old=new> | Rename specific spec_refs entries without rewriting the full array | No | | --replace-spec-refs | Replace existing spec_refs 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 | | --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 | | --estimated-files <count> | Sizing estimate: expected number of files modified (non-negative integer) | No | | --estimated-tool-calls <count> | Sizing estimate: expected number of tool calls (non-negative integer) | No | | --sizing-strategy <strategy> | Execution strategy (single-session, checkpoint-resume, orchestrator-worker, decomposition) | No | | --sizing-exception-type <type> | Sizing exception type (docs-only, shallow-multi-file, review-audit) | No | | --sizing-exception-reason <text> | Sizing exception justification (required when —sizing-exception-type is set) | 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 test_full once (disable tests.unit and incremental execution) | No | | --allow-unread-signals | Allow prep to continue with unread directed mem:signal entries; requires —reason | No |

wu:recover

Recover WU state, including restoring missing active worktrees

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-gate, —override-owner) | No | | -a, --action <action> | Recovery action: resume, restore, reset, nuke, cleanup | No | | -f, --force | Required for destructive actions (reset, nuke) | No | | --discard-changes | Allow reset to proceed even if worktree has uncommitted changes | No | | -j, --json | Output as JSON | 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-gate, —override-owner) | Yes | | --override-owner | Override ownership check (requires —reason) | No | | --keep-branch | Retain the lane branch instead of deleting it (overrides wu_release.branch_action) | 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-gate, —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:

wu:status

Show WU status, location, valid commands

pnpm wu:status

Options:

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-gate, —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 | | -a, --all | Validate all WUs | No | | --json | Output JSON summary only | No |

wu:verify

Verify WU completion (stamp, commit, clean tree)

pnpm wu:verify --id <wuId>

Options:

WU Maintenance

wu:clean-generated

Governed scoped-rollback for the 26 known docs:sync/cli-docs projection files

pnpm wu:clean-generated

wu:cleanup

Cleanup after PR merge

pnpm wu:cleanup

Options:

wu:delete

Delete WU spec and cleanup

pnpm wu:delete

Options:

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:

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 | | --template <template> | Template preset name | 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 | | --labels <labels> | Labels (repeatable) | No | | --assigned-to <email> | Override assigned_to (defaults to git config user.email) | No |

wu:prune

Lease-aware stale worktree cleanup and already-merged remote lane branch pruning

pnpm wu:prune

wu:rebase

Rebase the claimed WU lane branch onto the integration target (governed; auto-resolves metadata conflicts)

pnpm wu:rebase

wu:rebase-meta

Governed metadata-rebase normalizer for parallel-WU conflict recovery

pnpm wu:rebase-meta

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:

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-gate, —override-owner) | No | | -f, --force | Force operation | No | | --list | List all current lane locks | No | | --status | Show detailed status for the specified lane | No |

Next Steps

Configuration – Configure LumenFlow
WU Schema – Work Unit YAML structure