Configuration

LumenFlow is configured via workspace.yaml in your project root (software_delivery block).

Minimal Config

software_delivery:
  lanes:
    definitions:
      - name: 'Framework: Core'
        code_paths: ['src/**']
  gates:
    format: true
    lint: true
    typecheck: true
    test: true

Config Sections

directories

Directory paths configuration

Field	Type	Default	Description
appsWeb	string	""	Working directory for a web app, if one exists.
worktrees	string	"worktrees/"	Directory where WU lifecycle worktrees are created.
ai	string	"ai/"	Directory for AI-related assets.
claude	string	".claude/"	Directory for Claude-specific configuration.
docs	string	"docs/"	Root directory for project documentation.
packages	string	"packages/"	Root directory for workspace packages.
tools	string	"tools/"	Directory for build and generator tooling.
memoryBank	string	"memory-bank/"	Directory backing the shared memory layer.
wuDir	string	"docs/tasks/wu"	Directory of WU YAML specs.
initiativesDir	string	"docs/tasks/initiatives"	Directory of initiative YAML records.
backlogPath	string	"docs/tasks/backlog.md"	Path to the generated backlog markdown file.
statusPath	string	"docs/tasks/status.md"	Path to the generated status markdown file.
skillsDir	string	".lumenflow/skills"	Canonical directory for LumenFlow skills.
agentsDir	string	".claude/agents"	Directory of agent definition files for the default client.
adrDir	string	"docs/architecture-decisions"	Directory of architecture decision records (ADRs).
plansDir	string	"docs/plans"	Directory of planning documents.
templatesDir	string	".lumenflow/templates"	Directory of WU and initiative template files.
onboardingDir	string	"docs/_frameworks/lumenflow/agent/onboarding"	Directory of agent onboarding documentation.
completeGuidePath	string	"docs/_frameworks/lumenflow/lumenflow-complete.md"	Path to the full LumenFlow workflow guide.
quickRefPath	string	see below	Path to the agent quick-reference commands document.
startingPromptPath	string	see below	Path to the agent starting-prompt document.
sizingGuidePath	string	"docs/_frameworks/lumenflow/wu-sizing-guide.md"	Path to the WU sizing guide document.
governancePath	string	"docs/governance/project-governance.md"	Path to the project governance document.
safeGitPath	string	"scripts/safe-git"	Path to the safe-git wrapper script relative to the project root.

Field details

quickRefPath default

docs/_frameworks/lumenflow/agent/onboarding/quick-ref-commands.md

startingPromptPath default

docs/_frameworks/lumenflow/agent/onboarding/starting-prompt.md

state

State paths configuration (.lumenflow directory structure)

Field	Type	Default	Description
base	string	".lumenflow"	Kernel-shared base state directory, not pack-namespaced.
stateDir	string	".lumenflow/state/packs/software-delivery"	Root state directory for the Software Delivery pack.
archiveDir	string	".lumenflow/state/packs/software-delivery/archive"	Directory holding archived WU events.
stampsDir	string	".lumenflow/state/packs/software-delivery/stamps"	Directory holding completion stamps for done WUs.
mergeLock	string	".lumenflow/state/packs/software-delivery/merge.lock"	Path to the merge lock file serializing lifecycle merges to main.
telemetry	string	".lumenflow/state/packs/software-delivery/telemetry"	Directory holding local telemetry state.
sessions	string	".lumenflow/sessions"	Kernel-shared agent sessions directory, not pack-namespaced.
incidents	string	".lumenflow/state/packs/software-delivery/incidents"	Directory holding recorded incident records.
commandsLog	string	".lumenflow/state/packs/software-delivery/commands.log"	Path to the executed-commands audit log file.
eventArchival	object	see below	Controls archival of old WU events to prevent unbounded growth.

Field details

eventArchival default

archiveAfter: 7776000000
keepArchives: true

git

Git configuration

Field	Type	Default	Description
mainBranch	string	"main"	Name of the repository main branch.
defaultRemote	string	"origin"	Name of the default git remote.
laneBranchPrefix	string	"lane/"	Prefix applied to every claimed lane branch name.
tempBranchPrefix	string	"tmp/"	Prefix applied to short-lived micro-worktree branch names.
realGitPath	string	"/usr/bin/git"	Path to the real git executable used by lifecycle commands.
maxBranchDrift	integer	20	Maximum commits a lane branch may be behind main before rebase is required.
branchDriftWarning	integer	15	Commits-behind-main threshold that emits a branch drift warning.
branchDriftInfo	integer	10	Commits-behind-main threshold that emits an informational branch drift note.
requireRemote	boolean	true	When true, wu:create and wu:claim fail without a remote “origin”.
agentBranchPatterns	string[]	[]	Custom agent branch patterns merged with the registry patterns.
agentBranchPatternsOverride	string[]	-	Agent branch patterns that fully replace the registry patterns when set.
disableAgentPatternRegistry	boolean	false	Disables fetching agent branch patterns from the registry (airgapped mode).
push_retry	object	see below	Retry-with-rebase behaviour for non-fast-forward push errors.

Field details

push_retry default

enabled: true
retries: 3
min_delay_ms: 100
max_delay_ms: 1000
jitter: true

wu

WU (Work Unit) configuration

Field	Type	Default	Description
idPattern	string	"^WU-\d+$"	Regex pattern a WU id must match.
minDescriptionLength	integer	50	Minimum accepted length, in characters, of a WU description.
maxCommitSubject	integer	100	Maximum accepted length, in characters, of a lifecycle commit subject line.
defaultPriority	string	"P2"	Priority assigned to a new WU when none is supplied.
defaultStatus	string	"ready"	Status assigned to a new WU when none is supplied.
defaultType	string	"feature"	Type assigned to a new WU when none is supplied.
brief	object	see below	Claim-time wu:brief automation policy and freshness threshold.

Field details

brief default

policyMode: auto
freshnessMinutes: 1440

gates

Quality gates configuration

Field	Type	Default	Description
maxEslintWarnings	integer	100	Maximum ESLint warning count the lint gate tolerates before failing.
enableCoverage	boolean	true	Enables the test coverage gate.
minCoverage	number	90	Minimum required test coverage percentage.
enableSafetyCriticalTests	boolean	true	Enables the safety-critical-test gate.
enableInvariants	boolean	true	Enables the invariants gate.
tdd_diff_evidence	object	-	Controls which WU types the TDD diff-evidence gate applies to and how it enforces.
tdd_ordering	object	-	Controls the RED-first commit-order gate: which WU types it applies to and its thresholds.
execution_lock	object	see below	Repository-scoped bounded gate semaphore controlling concurrent gate runs.
shared_build_output_roots	string[]	[]	Build-output roots this workspace shares with other checkouts, for the gate build-output lock only (not gates.execution_lock).
execution	object	-	Custom per-gate commands, with optional preset expansion, overriding the hardcoded defaults.
commands	object	see below	Configurable test/lint/typecheck/format commands consumed by the gates runner.
ignore_patterns	string[]	-	Glob patterns to ignore when detecting changed tests for the scoped test gate.
lane_health	”warn” | “error” | “off”	"warn"	How the lane health check behaves during gates: warn, error, or off.
co_change	object[]	[]	Rules requiring a companion file change when trigger files are modified.
conditional_commands	object[]	[]	Commands that run only when their trigger_patterns match changed files.
include_builtin_co_change_defaults	boolean	true	Merges the built-in database schema-to-migration co-change rules when true.
delivery_review	object	see below	Native delivery review gate evaluating acceptance-criteria satisfaction.
overrides	object	see below	Per-gate-id overrides of framework gate definition defaults, keyed by gate id.
local_prep	object	see below	Opt-in local-prep profile extending wu:prep with build/integration/e2e-smoke gates.
resources	object	-	Vendor-agnostic environment variables and per-runner resource caps for gate subprocesses.
parity_suites	string[]	[]	Repo-specific parity/drift test paths appended to the always-on framework defaults.
throughput_baseline	object	see below	Release throughput ratchet baseline path and tolerance percentage.

Field details

execution_lock default

concurrency: 2

shared_build_output_roots description

Build-output roots this workspace shares with other checkouts, for the gate build-output lock only (not gates.execution_lock). Empty (the default) keys each run on its own resolved output root, so disjoint checkouts run concurrently. One declared root serializes every run declaring the identical root. Two or more distinct roots cannot be one lock directory, so the workspace falls back to the machine-wide lock. Relative entries resolve against the checkout root and are compared after native realpath, which collapses symlinks and junctions but not Windows subst or mapped drives: declare the same spelling everywhere.

commands default

test_full: ''
test_docs_only: ''
test_incremental: ''
migration_verify: ''

delivery_review default

enabled: false
auto_run: false
block_partial: false
verifier_command: ''
verifier_command_mode: always
skip_types:
  - documentation
  - process

overrides default

{}

local_prep default

build:
  enabled: false
build_scope: applicable
integration_test:
  enabled: false
e2e_smoke:
  enabled: false
  tag: smoke
latency_budget_warn_ms: 180000
latency_budget:
  enforced: false
  docs_only_ms: 3600000
  broad_ms: 3600000
  full_ms: 7200000
report_all: true
reuse_evidence: false

throughput_baseline default

path: .lumenflow/throughput-baseline.json
tolerance_percent: 25

memory

Memory layer configuration

Field	Type	Default	Description
directory	string	"memory-bank/"	Directory backing the shared memory layer.
sessionTtl	integer	604800000	Time-to-live, in milliseconds, for agent session records.
checkpointTtl	integer	2592000000	Time-to-live, in milliseconds, for memory checkpoints.
enableAutoCleanup	boolean	true	Enables automatic TTL-based cleanup of memory entries.
progress_signals	object	-	Progress signal triggers and cadence for sub-agent coordination.
signalCleanup	object	see below	TTL-based cleanup thresholds for signals.jsonl.
delegation_context_max_size	integer	4096	Maximum bytes of memory context injected into delegation prompts.
spawn_context_max_size	unknown	-	Deprecated; rejected at parse time. Use delegation_context_max_size instead.
enforcement	object	-	Auto-checkpoint hooks and checkpoint requirement for wu:done.
decay	object	-	Automated archival of stale memory nodes during lifecycle events.

Field details

signalCleanup default

ttl: 604800000
unreadTtl: 2592000000
maxEntries: 500

memory.progress_signals

Progress signals configuration for sub-agent coordination

Field	Type	Default	Description
enabled	boolean	false	Makes progress signals mandatory (vs. optional) in spawn prompts.
frequency	integer	0	Sends a progress signal every N tool calls; 0 disables frequency-based signals.
on_milestone	boolean	true	Signals after each acceptance criterion is completed.
on_tests_pass	boolean	true	Signals when tests first pass.
before_gates	boolean	true	Signals before running gates.
on_blocked	boolean	true	Signals when work becomes blocked.
auto_checkpoint	boolean	false	Automatically checkpoints memory at signal milestones.

ui

UI configuration

Field	Type	Default	Description
errorBoxWidth	integer	70	Character width of rendered CLI error boxes.
statusPreviewLines	integer	5	Number of lines shown in a status preview.
readinessBoxWidth	integer	50	Character width of rendered CLI readiness boxes.

yaml

YAML serialization configuration

Field	Type	Default	Description
lineWidth	integer	100	Line-wrap width for generated YAML output; -1 disables wrapping.

agents

Agents configuration

Field	Type	Default	Description
defaultClient	string	"claude-code"	Client identity used when a command is not given an explicit —client.
clients	object	see agents.clients.*	Per-client configuration overrides, keyed by client id.
routing	object	-	Vendor-neutral role defaults and initiative-specific model routing overrides.
roster	string[]	see below	Recommended default roster of agent names for orchestration.
mandatory	object	see below	Agents that are mandatory for a claim, and the trigger patterns that require them.
methodology	object	see agents.methodology	Agent-facing project methodology defaults (TDD, architecture, etc.).
stream_watchdog	object	-	Silent-agent kill timeout and heartbeat cadence for orchestrator stream watchdogs.
monitor_quality_signals	object	-	Mid-execution quality signal policy: flags production code committed with no tests.
monitor_trajectory_signals	object	-	Trajectory classifier thresholds for stagnating/thrashing signal detection.
signals	object	-	Idle-orchestrator push-eligible signal types and idle threshold.
context_discipline	object	see below	Advisory context-loading discipline guidance projected into agent surfaces.
lifecycle_enforcement	object	see below	Lifecycle enforcement backstop policy version and integrity manifest path.

Field details

roster default

- general-purpose
- lumenflow-pm
- test-engineer
- code-reviewer
- bug-triage
- lumenflow-enforcer
- initiative-architect

mandatory default

names: []
triggers: {}

context_discipline default

enabled: true
full_file_read_exceptions: []

lifecycle_enforcement default

enabled: true
policy_version: software-delivery-lifecycle-policy/v1
integrity_manifest: .lumenflow/state/packs/software-delivery/lifecycle-enforcement/integrity-manifest.json

agents.methodology

Methodology defaults (agent-facing project defaults)

Field	Type	Default	Description
enabled	boolean	true	Enables the generated Project Defaults methodology output.
enforcement	”required” | “recommended”	"required"	Whether the listed methodology principles are required or merely recommended.
principles	string[]	see below	Methodology principles applied to every WU by default.
notes	string	-	Free-text notes appended to the Project Defaults block.

Field details

principles default

- TDD
- Hexagonal Architecture
- SOLID
- DRY
- YAGNI
- KISS
- Library-First

agents.clients.*

Client configuration (per-client settings)

Field	Type	Default	Description
preamble	unknown	-	Preamble file path for this client, or false to disable it.
skillsDir	string	-	Skills directory path override for this client.
agentsDir	string	-	Agents directory path override for this client.
blocks	object[]	[]	Client-specific content blocks injected into wu:spawn output.
skills	object	-	Recommended and lane-specific skill guidance for wu:spawn.
methodology	object	-	Vendor-neutral methodology delivery facts for this host adapter.
capabilities_map	object	-	Maps abstract classifier capability tags to this client’s skill names.
features	object	-	Per-client activation flags for native pack/runtime features.
routing	object	-	Per-client mapping from the vendor-neutral model_profile vocabulary to this client’s model aliases.
capabilities	object	-	Declarative per-client capability flags, such as harnessPush.

fast_feedback

Advisory mid-turn file-edit feedback hook configuration

Field	Type	Default	Description
enabled	boolean	false	Enables the advisory mid-turn file-edit feedback hook.
command	string	-	Command run to produce advisory mid-turn feedback after a file edit.

Framework Agnostic Configuration

LumenFlow supports different package managers and consumer-owned test runner labels. Configure these inside the software_delivery block:

Field	Type	Default	Description
package_manager	"pnpm" | "npm" | "yarn" | "bun"	"pnpm"	Package manager for CLI operations
test_runner	string	-	Optional label for your configured test runner
build_command	string	"pnpm build"	Custom build command for CLI bootstrap

test_runner is metadata for your workspace, not a production default. LumenFlow does not infer a runner from source files or inject runner-specific behaviour unless you configure matching gate commands or gates.resources rules.

Example: npm + Jest

software_delivery:
  package_manager: npm
  test_runner: jest
  build_command: npm run build
  gates:
    commands:
      test_full: npm test
      test_docs_only: npm test -- --testPathPattern=docs
      test_incremental: npm test -- --onlyChanged

Example: yarn + Nx

software_delivery:
  package_manager: yarn
  test_runner: jest
  build_command: yarn nx build @hellmai/lumenflow-cli
  gates:
    commands:
      test_full: yarn nx run-many --target=test --all
      test_docs_only: yarn nx test docs
      test_incremental: yarn nx affected --target=test

Example: bun

software_delivery:
  package_manager: bun
  test_runner: 'bun:test'
  build_command: bun run --filter @hellmai/lumenflow-cli build
  gates:
    commands:
      test_full: bun test
      test_incremental: bun test

Environment Overrides

Config values can be overridden via environment variables:

LUMENFLOW_MAIN_BRANCH=develop pnpm wu:done --id WU-001

Variable	Overrides
LUMENFLOW_CONFIG	Config file path
LUMENFLOW_MAIN_BRANCH	git.mainBranch
LUMENFLOW_WU_SPECS	directories.wuDir
LUMENFLOW_CLI_DIST_CACHE	CLI build cache root (default ~/.lumenflow/cache/cli-dist)

CLI build cache

Lifecycle commands that require a freshly built CLI resolve the build output by a digest of its inputs (sources, dependencies, build configuration, Node major and ABI) and keep it in a per-machine cache outside every checkout. An output that already matches the current inputs is used as-is, a cached build for the same digest is activated instead of rebuilt, and activation replaces each file by rename so a concurrent reader never sees a missing or partial one.

# Move the cache root (for a sandbox, a test run, or a non-default home)
LUMENFLOW_CLI_DIST_CACHE=/var/tmp/lumenflow-cli-dist pnpm wu:prep --id WU-001

A cache root that resolves inside a checkout is refused with a logged reason and the default root is used instead: cached build outputs written into a checkout appear as untracked files and block the lifecycle dirty-checkout guard for every work unit on that checkout.

Validation

Validate your config:

pnpm validate

---

Next Steps

• CLI Commands – All commands
• WU Schema – WU YAML structure