Skip to content
LumenFlow

Visual Overview

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

Kernel Dispatch Pipeline

Section titled “Kernel Dispatch Pipeline”

Every tool call — from CLI, MCP, or programmatic API — passes through the kernel before anything executes.

Diagram

Key points:

  • Steps 2–5 are the authorization gate — denial is still recorded as evidence
  • Scope intersection computes workspace ∩ lane ∩ task ∩ tool permissions
  • Policy evaluation uses deny-wins cascade across 4 layers
  • Packs provide the tool handlers; the kernel is domain-agnostic

Tool Execution Stack

Section titled “Tool Execution Stack”

Inside step 7 (dispatch), tools execute through a three-layer stack. See Tool Execution for the full architecture.

Diagram

Package Dependencies

Section titled “Package Dependencies”

LumenFlow is a monorepo with clear dependency boundaries. See Package Architecture for details.

Diagram

WU Lifecycle

Section titled “WU Lifecycle”

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

Worktree Discipline

Section titled “Worktree Discipline”

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)

State File Relationships

Section titled “State File Relationships”

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

WU Spec Anatomy

Section titled “WU Spec Anatomy”

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

Gates Pipeline

Section titled “Gates Pipeline”

Quality gates are pack policies with trigger: on_completion, evaluated by the kernel before a task can complete.

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

Lane WIP & Locking

Section titled “Lane WIP & Locking”

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

Memory & Agent Coordination

Section titled “Memory & Agent Coordination”

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/

Initiative Wave Orchestration

Section titled “Initiative Wave Orchestration”

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

Next Steps

Section titled “Next Steps”