Visual Overview
This page provides visual mental models for the core LumenFlow concepts. Use these diagrams as quick references when working with the framework.
WU Lifecycle
Section titled “WU Lifecycle”Work Units progress through 5 states with specific transitions.
Key points:
doneis terminal (no outgoing transitions)blockrequires a reasonreleaseenables orphan recovery when agents are interrupted
Worktree Discipline
Section titled “Worktree Discipline”All work happens in isolated worktrees to prevent the “absolute path trap”.
Key points:
- Work happens ONLY in worktree after
wu:claim wu:prepruns gates in the worktreewu:doneruns from main (merges + cleanup)
State File Relationships
Section titled “State File Relationships”LumenFlow uses a layered state model with YAML specs as the single source of truth.
Key points:
- YAML spec is the single source of truth
- Stamps are existence proofs (empty marker files)
status.mdandbacklog.mdare always regenerable- Events provide audit trail, not authority
WU Spec Anatomy
Section titled “WU Spec Anatomy”Fields are populated at different lifecycle stages.
Key points:
- Required fields must exist at creation (no placeholders allowed)
- Claim adds execution context (worktree, session)
- Done locks the WU and records completion
Gates Pipeline
Section titled “Gates Pipeline”Quality gates run in sequence before completion.
Key points:
- Gates run in sequence: format → lint → typecheck → test
- Each gate must pass before the next runs
- Format failures can auto-fix; others require manual intervention
- All gates must pass before
wu:prep/wu:done
Lane WIP & Locking
Section titled “Lane WIP & Locking”Lanes prevent parallel work conflicts with WIP limits.
Key points:
- Each lane has WIP limit of 1 (configurable)
wu:claimchecks lane availability before claiming- Lock policies:
all(blocked holds lock) vsactive(only in_progress) - Prevents merge conflicts from parallel work in same area
Memory & Agent Coordination
Section titled “Memory & Agent Coordination”Agents communicate via signals, checkpoints, and recovery.
Key points:
- Signals enable agent-to-agent coordination
- Checkpoints preserve progress before
/clear - Recovery restores context after compaction
- All stored in
.lumenflow/memory/
Initiative Wave Orchestration
Section titled “Initiative Wave Orchestration”WUs are organized into parallel execution waves based on dependencies.
Key points:
- WUs in same wave run in parallel
- Max 1 WU per lane per wave (prevents contention)
- Waves execute sequentially
- Stamp files (
.lumenflow/stamps/WU-XXXX.done) mark completion for dependency resolution
Next Steps
Section titled “Next Steps”- Work Units - Deep dive into WU structure
- Lanes - Lane configuration and policies
- Gates - Quality gate configuration
- Memory Layer - Memory and coordination details