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	""
worktrees	string	"worktrees/"
ai	string	"ai/"
claude	string	".claude/"
docs	string	"docs/"
packages	string	"packages/"
tools	string	"tools/"
memoryBank	string	"memory-bank/"
wuDir	string	"docs/tasks/wu"
initiativesDir	string	"docs/tasks/initiatives"
backlogPath	string	"docs/tasks/backlog.md"
statusPath	string	"docs/tasks/status.md"
skillsDir	string	".claude/skills"
agentsDir	string	".claude/agents"
adrDir	string	"docs/architecture-decisions"
plansDir	string	"docs/plans"
templatesDir	string	".lumenflow/templates"
onboardingDir	string	"docs/_frameworks/lumenflow...
completeGuidePath	string	"docs/_frameworks/lumenflow...
quickRefPath	string	"docs/_frameworks/lumenflow...
startingPromptPath	string	"docs/_frameworks/lumenflow...
sizingGuidePath	string	"docs/_frameworks/lumenflow...
governancePath	string	"docs/governance/project-go...
safeGitPath	string	"scripts/safe-git"

state

State paths configuration (.lumenflow directory structure)

Field	Type	Default	Description
base	string	".lumenflow"
stateDir	string	".lumenflow/state"
archiveDir	string	".lumenflow/archive"
stampsDir	string	".lumenflow/stamps"
mergeLock	string	".lumenflow/merge.lock"
telemetry	string	".lumenflow/telemetry"
flowLog	string	".lumenflow/flow.log"
sessions	string	".lumenflow/sessions"
incidents	string	".lumenflow/incidents"
commandsLog	string	".lumenflow/commands.log"
eventArchival	object	[object Object]

git

Git configuration

Field	Type	Default	Description
mainBranch	string	"main"
defaultRemote	string	"origin"
laneBranchPrefix	string	"lane/"
tempBranchPrefix	string	"tmp/"
realGitPath	string	"/usr/bin/git"
maxBranchDrift	integer	20
branchDriftWarning	integer	15
branchDriftInfo	integer	10
requireRemote	boolean	true
agentBranchPatterns	string[]	[]
agentBranchPatternsOverride	string[]	-
disableAgentPatternRegistry	boolean	false
push_retry	object	[object Object]

wu

WU (Work Unit) configuration

Field	Type	Default	Description
idPattern	string	"^WU-\d+$"
minDescriptionLength	integer	50
maxCommitSubject	integer	100
defaultPriority	string	"P2"
defaultStatus	string	"ready"
defaultType	string	"feature"
brief	object	[object Object]

gates

Quality gates configuration

Field	Type	Default	Description
maxEslintWarnings	integer	100
enableCoverage	boolean	true
minCoverage	number	90
enableSafetyCriticalTests	boolean	true
enableInvariants	boolean	true
execution	object	-
commands	object	[object Object]
ignore_patterns	string[]	-
lane_health	”warn” | “error” | “off”	"warn"
co_change	object[]	[]
include_builtin_co_change_defaults	boolean	true

memory

Memory layer configuration

Field	Type	Default	Description
directory	string	"memory-bank/"
sessionTtl	integer	604800000
checkpointTtl	integer	2592000000
enableAutoCleanup	boolean	true
progress_signals	object	-
signalCleanup	object	[object Object]
delegation_context_max_size	integer	4096
spawn_context_max_size	unknown	-
enforcement	object	-
decay	object	-

memory.progress_signals

Progress signals configuration for sub-agent coordination (WU-1203)

Field	Type	Default	Description
enabled	boolean	false
frequency	integer	0
on_milestone	boolean	true
on_tests_pass	boolean	true
before_gates	boolean	true
on_blocked	boolean	true
auto_checkpoint	boolean	false

ui

UI configuration

Field	Type	Default	Description
errorBoxWidth	integer	70
statusPreviewLines	integer	5
readinessBoxWidth	integer	50

yaml

YAML serialization configuration

Field	Type	Default	Description
lineWidth	integer	100

agents

Agents configuration

Field	Type	Default	Description
defaultClient	string	"claude-code"
clients	object	[object Object]
methodology	object	[object Object]

agents.methodology

Methodology defaults (agent-facing project defaults)

Field	Type	Default	Description
enabled	boolean	true
enforcement	”required” | “recommended”	"required"
principles	string[]	["TDD","Hexagonal Architect...
notes	string	-

agents.clients.*

Client configuration (per-client settings)

Field	Type	Default	Description
preamble	unknown	-
skillsDir	string	-
agentsDir	string	-
blocks	object[]	[]
skills	object	-
enforcement	object	-
capabilities_map	object	-

Framework Agnostic Configuration

LumenFlow supports different package managers and test runners. Configure these at the top level of your config file:

Field	Type	Default	Description
package_manager	"pnpm" | "npm" | "yarn" | "bun"	"pnpm"	Package manager for CLI operations
test_runner	"vitest" | "jest" | "mocha"	"vitest"	Test runner for incremental test detection
build_command	string	"pnpm --filter @lumenflow/cli build"	Custom build command for CLI bootstrap

Example: npm + Jest

version: '2.0'

# WU-1356: Framework agnostic settings
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

version: '2.0'

package_manager: yarn
test_runner: jest
build_command: yarn nx build @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

version: '2.0'

package_manager: bun
test_runner: vitest
build_command: bun run --filter @lumenflow/cli build

gates:
  commands:
    test_full: bun test
    test_incremental: bun test --changed

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

Validation

Validate your config:

pnpm exec lumenflow validate

---

Next Steps

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