Skip to content
LumenFlow

WU Schema

Work Units are defined in YAML files under docs/tasks/wu/ by default. This path is configurable via software_delivery.directories.wuDir in workspace.yaml.

YAML parsing notes

Section titled “YAML parsing notes”
  • LumenFlow tooling parses and serializes WU YAML using the yaml library.
  • Unquoted YYYY-MM-DD values are treated as strings (no Date coercion).

Minimal (Claim-Ready) WU

Section titled “Minimal (Claim-Ready) WU”
id: WU-001
title: Add email validation
lane: Framework: Core
type: feature
status: ready
priority: P2
created: 2026-01-21
assigned_to: engineer@example.com

description: |
  Context: Login accepts invalid emails.
  Problem: Users submit bad addresses and fail later.
  Solution: Add client-side validation with tests.

acceptance:
  - Invalid format shows error on blur
  - Valid email allows submission
  - Unit test covers validation

spec_refs:
  - docs/plans/WU-001-plan.md

code_paths:
  - packages/@lumenflow/core/src/validation/email.ts

tests:
  unit:
    - packages/@lumenflow/core/__tests__/email-validation.test.ts
  manual: []
  e2e: []
  integration: []

exposure: backend-only

artifacts:
  - .lumenflow/stamps/WU-001.done

Full WU Schema (Common Fields)

Section titled “Full WU Schema (Common Fields)”
id: WU-001
title: Add email validation
lane: Framework: Core
type: feature
status: ready
priority: P2
created: 2026-01-21
assigned_to: engineer@example.com

description: |
  Context: ...
  Problem: ...
  Solution: ...

acceptance:
  - Criterion 1
  - Criterion 2

spec_refs:
  - docs/plans/WU-001-plan.md

code_paths:
  - packages/@lumenflow/core/src/example.ts

tests:
  manual:
    - Manual test: Verify behavior
  unit:
    - packages/@lumenflow/core/__tests__/example.test.ts
  e2e: []
  integration: []

exposure: backend-only # ui | api | backend-only | documentation
user_journey: |
  Optional user flow for ui/api exposure.
ui_pairing_wus:
  - WU-1234
navigation_path: /settings

artifacts:
  - .lumenflow/stamps/WU-001.done

dependencies: []
risks:
  - Risk 1
notes: ''
requires_review: false

# Optional lifecycle fields (auto-managed)
claimed_mode: worktree
worktree_path: worktrees/framework-core-wu-001
claimed_at: 2026-01-21T12:00:00Z
completed_at: 2026-01-22T09:00:00Z

Required Fields for New WUs

Section titled “Required Fields for New WUs”

| Field | Type | Description | | ------------- | -------- | ---------------------------------------------------------------------------- | | id | string | Unique identifier (e.g., WU-001) | | title | string | Short description | | lane | string | Parent: Sublane (e.g., Framework: CLI) | | type | enum | feature, bug, documentation, process, tooling, chore, refactor | | status | enum | ready, in_progress, blocked, waiting, done, cancelled | | priority | enum | P0, P1, P2, P3 | | created | date | YYYY-MM-DD | | assigned_to | string | Assignee email | | description | string | Context/Problem/Solution | | acceptance | string[] | Testable criteria | | code_paths | string[] | Required for non-doc WUs | | tests | object | At least one test path for non-doc WUs | | exposure | enum | ui, api, backend-only, documentation | | spec_refs | list | Required for feature WUs | | artifacts | list | Usually includes stamp path |

Validation

Section titled “Validation”

WU specs are validated on:

  • wu:create – creation requires a complete spec (no placeholders)
  • wu:claim – blocks incomplete specs
  • wu:done – enforces completeness and code path validity

Validation checks include:

  • Required fields present
  • No [PLACEHOLDER] markers
  • Code paths and tests for non-doc WUs
  • Exposure and spec_refs (feature)
  • Schema conformity

Status Lifecycle

Section titled “Status Lifecycle”
ready → in_progress → done
            ↓      ↓
         blocked  waiting
            ↓      ↓
         in_progress → done

| Status | Meaning | | ------------- | ------------------------------------------ | | ready | Approved, awaiting claim | | in_progress | Claimed, being worked on | | blocked | Waiting on dependency | | waiting | Implementation complete, awaiting sign-off | | done | Acceptance met, stamped | | cancelled | Dropped/obsolete |

Auto-Managed Fields

Section titled “Auto-Managed Fields”

These fields are set automatically by CLI tooling during the WU lifecycle. Do not set them manually.

| Field | Type | Set By | Description | | --------------------------- | -------- | ----------- | -------------------------------------- | | locked | boolean | wu:claim | Whether the WU is locked to a worktree | | claimed_mode | string | wu:claim | Claim mode (worktree or branch) | | worktree_path | string | wu:claim | Path to the worktree directory | | baseline_main_sha | string | wu:claim | Git SHA of main at time of claim | | session_id | string | wu:claim | Agent session identifier | | approved_by | string[] | wu:done | Approvers list | | approved_at | datetime | wu:done | Approval timestamp | | requires_human_escalation | boolean | wu:create | Whether human approval is required | | requires_cso_approval | boolean | wu:create | CSO approval required | | requires_cto_approval | boolean | wu:create | CTO approval required | | requires_design_approval | boolean | wu:create | Design approval required | | escalation_triggers | string[] | wu:create | Conditions that trigger escalation |