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

If the WU is active or recently active and the worktree is missing while the lane branch still exists, restore before reset/reclaim:

pnpm wu:recover --id WU-042 --action restore

Restore recreates the worktree without resetting WU state, branch, baseline, or completion evidence.

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 only the explicitly named skippable gate (run from main)
pnpm wu:done --id WU-042 --skip-gate lane-health \
  --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

Lane-rule-driven, not an explicit WU list — it auto-assigns orphaned WUs whose lane matches a rule in a config file (default tools/config/initiative-lane-buckets.yaml):

# Dry-run: preview what would be assigned
pnpm initiative:bulk-assign --config tools/config/initiative-lane-buckets.yaml

# Apply the changes
LUMENFLOW_ADMIN=1 pnpm initiative:bulk-assign --apply

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

# Preview already-merged remote lane branches
pnpm wu:prune --remote

# Delete already-merged remote lane branches
pnpm wu:prune --remote --execute

wu:prune --execute is lease-aware. Active and recently active WU leases block cleanup, and recoverable tracked removals write audit evidence under .lumenflow/quarantine/worktrees/cleanup.jsonl. Raw Git pruning is an implementation detail, not LumenFlow lifecycle authority.

wu:prune --remote --execute only deletes remote lane/* branches whose remote tracking ref is already an ancestor of the configured integration target.

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/actions/lumenflow-gates@v4
        with:
          preset: node

Gate with Custom Steps

jobs:
  gates:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hellmai/lumenflow/actions/lumenflow-gates@v4
        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