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?

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

id: WU-042
title: Add email validation to login form
lane: 'Experience: UI'
type: feature
status: ready
priority: P2
exposure: ui

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

test_paths:
  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

ready → in_progress → [blocked] → done

Status	Meaning
`ready`	Approved, can be claimed
`in_progress`	Someone is working on it
`blocked`	Waiting on external dependency
`done`	Acceptance met, stamp created

Right-Sizing WUs

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

Too Big

❌ “Implement user authentication system”

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

In LumenFlow:

Traditional	LumenFlow
Create ticket → Code → Open PR → Review → Merge	Create 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

LumenFlow provides two levels of completion evidence:

Kernel-Level Evidence

Every tool call during a WU’s execution is recorded in the evidence store:

Content-addressed inputs — Tool inputs are hashed with SHA-256 and stored as immutable blobs
Tool traces — TOOL_CALL_STARTED and TOOL_CALL_FINISHED entries with timing, scope enforcement results, and policy decisions
Denial records — Even denied tool calls produce evidence, proving what the agent attempted

WU-Level Evidence

At completion, wu:done creates:

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

This audit trail answers: What was the agent asked to do? Was the action authorized? What actually happened? See Evidence Store for the full model.

Creating WUs

# With required flags
pnpm wu:create \
  --title "Add password strength meter" \
  --lane "Experience: UI" \
  --type feature \
  --exposure ui \
  --description "Show password strength indicator during registration" \
  --acceptance "Strength meter shows weak/medium/strong" \
  --acceptance "Meter updates in real-time as user types" \
  --code-paths "src/components/PasswordStrength.tsx" \
  --test-paths-unit "src/components/__tests__/password-strength.test.ts" \
  --plan

The command prints the generated ID. The created WU goes into docs/04-operations/tasks/wu/WU-XXX.yaml with status ready.

Plan-less conversations: If your plan lives in chat or a meeting, keep it lightweight: use --plan to generate a stub at lumenflow://plans/WU-XXX-plan.md, summarize the plan there, and reference it in spec_refs. Feature WUs require spec_refs; notes do not replace the plan link.

Next Steps

Lanes — Organizing work streams with scope boundaries
Gates — Quality enforcement as kernel policies
Evidence Store — The immutable audit trail behind every WU
Kernel Runtime — How WU tasks map to kernel task lifecycle
Sizing Guide — How to size WUs properly