Skip to content
LumenFlow

Work Units (WUs)

A Work Unit (WU) is a small, well-defined piece of work with clear acceptance criteria and proof of completion.

Why WUs?

Section titled “Why WUs?”

Traditional tickets are:

  • Vague (“Fix the login bug”)
  • Unbounded (no clear definition of done)
  • Trust-based (marked done without proof)

WUs are:

  • Specific (“Add email validation to login form”)
  • Bounded (completable in a single session, <50 tool calls)
  • Evidence-based (tests and artifacts prove completion)

Anatomy of a WU

Section titled “Anatomy of a WU”
id: WU-042
title: Add email validation to login form
lane: UI
type: feature
status: ready


description: |
  Add client-side email validation before form submission.
  Show inline error message for invalid formats.


acceptance:
  - Email field validates on blur
  - Invalid emails show "Please enter a valid email"
  - Valid emails allow form submission
  - Unit test covers validation logic


tests:
  unit:
    - src/components/__tests__/login-form.test.ts
  e2e:
    - e2e/login.spec.ts


code_paths:
  - src/components/LoginForm.tsx
  - src/utils/validation.ts

WU Lifecycle

Section titled “WU Lifecycle”
ready → in_progress → [blocked] → done
StatusMeaning
readyApproved, can be claimed
in_progressSomeone is working on it
blockedWaiting on external dependency
doneAcceptance met, stamp created

Right-Sizing WUs

Section titled “Right-Sizing WUs”

WUs should be completable in a single session (<50 tool calls, <30% context). If bigger, split them.

Too Big

Section titled “Too Big”

❌ “Implement user authentication system”

Right-Sized

Section titled “Right-Sized”

✅ “Add login form UI” ✅ “Add password validation” ✅ “Connect login to auth API” ✅ “Add session persistence”

See Sizing Guide for detailed heuristics.

WU vs PR

Section titled “WU vs PR”

In LumenFlow:

TraditionalLumenFlow
Create ticket → Code → Open PR → Review → MergeCreate WU → Claim → Code in worktree → Gates → Done

The “review” is automated gates, not human PR review. This unblocks flow while maintaining quality.

Evidence, Not Claims

Section titled “Evidence, Not Claims”

Every WU completion creates:

  1. Stamp file in .beacon/stamps/WU-XXX.done
  2. Test results proving acceptance criteria
  3. Git history linking to the WU spec

This audit trail is valuable for:

  • Compliance reviews
  • Team retrospectives
  • Understanding “why was this built?”

Creating WUs

Section titled “Creating WUs”
Terminal window
# Interactive creation
pnpm wu:create


# With flags
pnpm wu:create \
  --id WU-043 \
  --title "Add password strength meter" \
  --lane UI \
  --type feature

The created WU goes into docs/tasks/wu/WU-043.yaml with status ready.

Next Steps

Section titled “Next Steps”