Skip to content
LumenFlow

Configuration

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

Minimal Config

Section titled “Minimal Config”
software_delivery:
  lanes:
    definitions:
      - name: 'Framework: Core'
        code_paths: ['src/**']
  gates:
    format: true
    lint: true
    typecheck: true
    test: true

Config Sections

Section titled “Config Sections”

directories

Section titled “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 | ".lumenflow/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

Section titled “state”

State paths configuration (.lumenflow directory structure)

| Field | Type | Default | Description | | --------------- | ------ | -------------------------------- | ----------- | | base | string | ".lumenflow" | | | stateDir | string | ".lumenflow/state/packs/sof... | | | archiveDir | string | ".lumenflow/state/packs/sof... | | | stampsDir | string | ".lumenflow/state/packs/sof... | | | mergeLock | string | ".lumenflow/state/packs/sof... | | | telemetry | string | ".lumenflow/state/packs/sof... | | | sessions | string | ".lumenflow/sessions" | | | incidents | string | ".lumenflow/state/packs/sof... | | | commandsLog | string | ".lumenflow/state/packs/sof... | | | eventArchival | object | [object Object] | |

git

Section titled “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

Section titled “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

Section titled “gates”

Quality gates configuration

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

memory

Section titled “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

Section titled “memory.progress_signals”

Progress signals configuration for sub-agent coordination

| 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

Section titled “ui”

UI configuration

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

yaml

Section titled “yaml”

YAML serialization configuration

| Field | Type | Default | Description | | ----------- | ------- | ------- | ----------- | | lineWidth | integer | 100 | |

agents

Section titled “agents”

Agents configuration

| Field | Type | Default | Description | | ------------------------- | -------- | -------------------------------- | ----------- | | defaultClient | string | "claude-code" | | | clients | object | [object Object] | | | roster | string[] | ["general-purpose","lumenfl... | | | mandatory | object | [object Object] | | | methodology | object | [object Object] | | | stream_watchdog | object | - | | | monitor_quality_signals | object | - | | | context_discipline | object | [object Object] | |

agents.methodology

Section titled “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.*

Section titled “agents.clients.*”

Client configuration (per-client settings)

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

fast_feedback

Section titled “fast_feedback”

Advisory mid-turn file-edit feedback hook configuration

| Field | Type | Default | Description | | --------- | ------- | ------- | ----------- | | enabled | boolean | false | | | command | string | - | |

Framework Agnostic Configuration

Section titled “Framework Agnostic Configuration”

LumenFlow supports different package managers and consumer-owned test runner labels. 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 | 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

Section titled “Example: npm + Jest”
version: '2.0'

# 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

Section titled “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

Section titled “Example: bun”
version: '2.0'

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

gates:
  commands:
    test_full: bun test
    test_incremental: bun test

Environment Overrides

Section titled “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

Section titled “Validation”

Validate your config:

pnpm exec lumenflow validate

Next Steps

Section titled “Next Steps”