Skip to content

Visual Overview

This page provides visual mental models for the core LumenFlow concepts. Use these diagrams as quick references when working with the framework.

Work Units progress through 5 states with specific transitions.

Diagram

Key points:

  • done is terminal (no outgoing transitions)
  • block requires a reason
  • release enables orphan recovery when agents are interrupted

All work happens in isolated worktrees to prevent the “absolute path trap”.

Diagram

Key points:

  • Work happens ONLY in worktree after wu:claim
  • wu:prep runs gates in the worktree
  • wu:done runs from main (merges + cleanup)

LumenFlow uses a layered state model with YAML specs as the single source of truth.

Diagram

Key points:

  • YAML spec is the single source of truth
  • Stamps are existence proofs (empty marker files)
  • status.md and backlog.md are always regenerable
  • Events provide audit trail, not authority

Fields are populated at different lifecycle stages.

Diagram

Key points:

  • Required fields must exist at creation (no placeholders allowed)
  • Claim adds execution context (worktree, session)
  • Done locks the WU and records completion

Quality gates run in sequence before completion.

Diagram

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

Lanes prevent parallel work conflicts with WIP limits.

Diagram

Key points:

  • Each lane has WIP limit of 1 (configurable)
  • wu:claim checks lane availability before claiming
  • Lock policies: all (blocked holds lock) vs active (only in_progress)
  • Prevents merge conflicts from parallel work in same area

Agents communicate via signals, checkpoints, and recovery.

Diagram

Key points:

  • Signals enable agent-to-agent coordination
  • Checkpoints preserve progress before /clear
  • Recovery restores context after compaction
  • All stored in .lumenflow/memory/

WUs are organized into parallel execution waves based on dependencies.

Diagram

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

  • Work Units - Deep dive into WU structure
  • Lanes - Lane configuration and policies
  • Gates - Quality gate configuration
  • Memory Layer - Memory and coordination details