Cookbook

This cookbook provides copy-paste solutions for common LumenFlow scenarios.

WU Lifecycle Patterns

Quick Bug Fix

For small, urgent fixes that don’t need full WU ceremony:

# Create and claim in one flow
pnpm wu:create \
  --title "Fix null check in auth handler" \
  --lane "Framework: Core" \
  --type bug \
  --exposure backend-only \
  --description "Hotfix: Auth handler crashes on null user" \
  --acceptance "Auth handler gracefully handles null user" \
  --code-paths "src/auth/handler.ts" \
  --test-paths-unit "src/auth/__tests__/handler.test.ts"

# Use the generated ID from the output (example: WU-999)
pnpm wu:claim --id WU-999 --lane "Framework: Core"
pnpm wu:brief --id WU-999 --client <client>
cd worktrees/framework-core-wu-999

# Make fix, test, complete
# ... edit files ...
pnpm wu:prep --id WU-999
cd /path/to/main
pnpm wu:done --id WU-999

Parallel WUs (Different Lanes)

Work on multiple WUs simultaneously using different lanes:

# Terminal 1: Framework work
pnpm wu:claim --id WU-100 --lane "Framework: Core"
pnpm wu:brief --id WU-100 --client <client>
cd worktrees/framework-core-wu-100
# Work here...

# Terminal 2: Documentation work
pnpm wu:claim --id WU-101 --lane "Content: Documentation"
pnpm wu:brief --id WU-101 --client <client>
cd worktrees/content-documentation-wu-101
# Work here...

# Run gates in each worktree
pnpm wu:prep --id WU-100
pnpm wu:prep --id WU-101

# Complete each from main
cd /path/to/main
pnpm wu:done --id WU-100
pnpm wu:done --id WU-101

Blocked WU

When a WU can’t proceed due to external dependency:

# Block the WU
pnpm wu:block --id WU-042 --reason "Waiting for API spec from backend team"

# Later, when unblocked
pnpm wu:unblock --id WU-042

# Resume work
cd worktrees/framework-core-wu-042

Resume Orphaned WU

If a WU was abandoned mid-work:

# Check WU state
pnpm wu:status --id WU-042

# If worktree exists but state is inconsistent
pnpm wu:recover --id WU-042

# Follow suggested fix
pnpm wu:recover --id WU-042 --action resume

Git Patterns

Commit Message Format

git commit -m "wu(wu-042): add email validation

- Add validateEmail function
- Cover edge cases for empty strings
- Include unit tests with 95% coverage"

Undo Uncommitted Changes

If you made changes in the wrong place:

# Check where changes are
git status

# If in main checkout, move the changes into the worktree
git diff > /tmp/main-changes.patch
cd worktrees/lane-wu-xxx
git apply /tmp/main-changes.patch
cd /path/to/main
git restore .

Sync Worktree with Main

If main has updates you need:

cd worktrees/lane-wu-xxx

# Fetch latest
git fetch origin main

# Rebase your changes on top
git rebase origin/main

Fix Diverged Branch

If your lane branch diverged from main:

cd worktrees/lane-wu-xxx

# Check divergence
git log --oneline --left-right HEAD...origin/main

# Rebase to fix
git fetch origin main
git rebase origin/main

# Force push lane branch (safe for lane branches)
git push origin lane/framework-core/wu-042 --force-with-lease

Gate Patterns

Fix Format Failures

# Auto-fix formatting
pnpm format

# Stage and amend
git add -A
git commit --amend --no-edit

# Re-run gates in worktree
pnpm wu:prep --id WU-XXX

Fix Lint Failures

# Check lint issues
pnpm lint

# Auto-fix what's possible
pnpm lint -- --fix

# Manual fixes for remaining issues
# Then re-run gates in worktree
pnpm wu:prep --id WU-XXX

Fix Type Errors

# Run typecheck
pnpm typecheck

# Fix first error first (often cascades)
# Then re-run
pnpm typecheck
pnpm wu:prep --id WU-XXX

Skip Gates (Emergency Only)

Danger

Only use when failures are pre-existing, not caused by your changes.

# Verify failure exists on main
cd /path/to/main
pnpm gates
# Confirm same failure exists

# Return to worktree
cd worktrees/lane-wu-xxx

# Skip with reason and fix WU (run from main)
pnpm wu:done --id WU-042 --skip-gates \
  --reason "Pre-existing lint failure in unrelated file" \
  --fix-wu WU-050

Testing Patterns

Run Tests for Single Package

pnpm test --filter @lumenflow/core

Run Tests with Coverage

pnpm test --filter @lumenflow/core -- --coverage

Run Specific Test File

pnpm test --filter @lumenflow/core -- src/__tests__/validation/email.test.ts

Watch Mode During Development

pnpm test --filter @lumenflow/core -- --watch

Update Snapshots

pnpm test --filter @lumenflow/core -- --update-snapshots

Memory Layer Patterns

Start Agent Session

# Begin tracking work
pnpm agent:session --wu WU-042 --tier 2

# Signal progress
pnpm mem:signal "Tests written, starting implementation" --wu WU-042

# Create checkpoint before risky changes
pnpm mem:checkpoint --wu WU-042

Recover Context After Break

# Check what's pending
pnpm mem:ready --wu WU-042

# Output shows:
# - Active WUs
# - Last signals
# - Files touched
# - Next steps

Coordinate Multiple Agents

# Agent 1 signals
pnpm mem:signal "Completed API routes" --wu WU-100

# Agent 2 checks inbox
pnpm mem:inbox --since 1h

# Agent 2 sees signal and can proceed

Initiative Patterns

Link WU to Initiative

pnpm initiative:add-wu --initiative INIT-007 --wu WU-042

Check Initiative Status

pnpm initiative:status --id INIT-007

Bulk Assign WUs

pnpm initiative:bulk-assign \
  --initiative INIT-007 \
  --wus WU-042,WU-043,WU-044

Bug Triage Patterns

Severity Classification

Severity	Description	Response
P0	Production down, data loss	Drop everything. Fix immediately.
P1	Major feature broken, no hotfix	Fix within current session.
P2	Degraded experience, workaround	Create Bug WU, schedule next.
P3	Minor issue, cosmetic	Create Bug WU, add to backlog.

Fix-in-Place vs Bug WU

When you discover a bug while working on a WU:

Fix in place if ALL are true:

• Bug is in your WU’s code_paths
• Fix is under 10 lines
• No new test file needed
• Under 30 minutes of work

Create a separate Bug WU if ANY are true:

• Bug is outside your code_paths
• Fix requires significant testing
• P0/P1 that needs its own evidence trail
• Would blow your WU’s sizing budget

Create a Bug WU

pnpm wu:create \
  --title "Fix: null crash in payment handler" \
  --lane "Framework: Core" \
  --type bug \
  --exposure backend-only \
  --description "Payment handler crashes when user has no saved cards" \
  --acceptance "Handler returns empty array instead of crashing" \
  --code-paths "src/payments/handler.ts" \
  --test-paths-unit "src/payments/__tests__/handler.test.ts"

Debugging Patterns

Check WU Status

# Full status with suggested commands
pnpm wu:status --id WU-042

List Active WUs

# In progress
cat docs/operations/tasks/status.md

# Ready/backlog
cat docs/operations/tasks/backlog.md

View Event History

# Recent events for a WU
cat .lumenflow/state/wu-events.jsonl | grep WU-042

Clean Up Stale Worktrees

# Preview what would be cleaned
pnpm wu:prune

# Execute cleanup
pnpm wu:prune --execute

Configuration Patterns

Minimal Config for Solo Dev

# workspace.yaml
version: '2.0'

lanes:
  definitions:
    - name: 'main'
      wip_limit: 3

gates:
  execution:
    preset: 'node'

Full Team Config

# workspace.yaml
version: '2.0'

directories:
  wu_specs: docs/operations/tasks/wu
  stamps: .lumenflow/stamps

lanes:
  enforcement:
    require_parent: true
    allow_custom: false
  definitions:
    - name: 'Framework: Core'
      wip_limit: 1
      code_paths: ['packages/@app/core/**']
    - name: 'Experience: Web'
      wip_limit: 1
      code_paths: ['apps/web/**']
    - name: 'Content: Documentation'
      wip_limit: 2
      code_paths: ['docs/**']

gates:
  execution:
    preset: 'node'
    format: 'pnpm prettier --check .'
    lint: 'pnpm eslint .'
    typecheck: 'pnpm tsc --noEmit'
    test: 'pnpm vitest run'

git:
  mainBranch: main
  defaultRemote: origin

Python Project Config

# workspace.yaml
version: '2.0'

gates:
  execution:
    preset: 'python'
    format: 'ruff format --check .'
    lint: 'ruff check . && mypy .'
    test: 'pytest'

Multi-Language Monorepo

# workspace.yaml
version: '2.0'

gates:
  execution:
    # Custom script that runs appropriate gates per package
    format: './scripts/format-check.sh'
    lint: './scripts/lint-all.sh'
    typecheck: './scripts/typecheck-all.sh'
    test: './scripts/test-all.sh'

CI/CD Patterns

GitHub Action for Gates

# .github/workflows/gates.yml
name: LumenFlow Gates
on: [push, pull_request]

jobs:
  gates:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hellmai/lumenflow-gates@v1
        with:
          preset: node

Gate with Custom Steps

jobs:
  gates:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hellmai/lumenflow-gates@v1
        with:
          format: 'pnpm prettier --check .'
          lint: 'pnpm eslint . --max-warnings 0'
          typecheck: 'pnpm tsc --noEmit'
          test: 'pnpm vitest run --coverage'

Troubleshooting Recipes

”Not in a worktree"

# Check current location
pwd

# If in main
cd worktrees/lane-wu-xxx

# If worktree doesn't exist
pnpm wu:claim --id WU-XXX --lane "Your Lane"
cd worktrees/lane-wu-xxx

"WU already claimed"

# Check who/what claimed it
pnpm wu:status --id WU-042

# If stale, release it
pnpm wu:release --id WU-042

# Then reclaim
pnpm wu:claim --id WU-042 --lane "Your Lane"

"Merge conflict in wu:done"

# Stay in worktree
cd worktrees/lane-wu-xxx

# Fetch and rebase
git fetch origin main
git rebase origin/main

# Resolve conflicts
# Then force push lane branch
git push origin lane/lane-name/wu-xxx --force-with-lease

# Retry wu:done
cd ../..
pnpm wu:done --id WU-XXX

"Gates pass locally but fail in CI”

# Common causes:
# 1. Node version mismatch
node --version  # Check matches CI

# 2. Missing dependencies
rm -rf node_modules
pnpm install

# 3. Cached build artifacts
pnpm clean
pnpm build

# Re-run gates in worktree
pnpm wu:prep --id WU-XXX

Quick Reference

Task	Command
Create WU	pnpm wu:create --title "..." --lane "..." --description "..." --acceptance "..." --exposure ... --code-paths ... --test-paths-unit ...
Claim WU	pnpm wu:claim --id WU-XXX --lane "Lane"
Run gates	pnpm wu:prep --id WU-XXX
Complete WU	pnpm wu:done --id WU-XXX
Block WU	pnpm wu:block --id WU-XXX --reason "..."
Check status	pnpm wu:status --id WU-XXX
Fix format	pnpm format
Run tests	pnpm test
Memory checkpoint	pnpm mem:checkpoint --wu WU-XXX
Check ready work	pnpm mem:ready --wu WU-XXX

Next Steps

• A Day with LumenFlow - Complete workflow walkthrough
• Troubleshooting - More detailed solutions
• CLI Reference - Full command documentation