Work items

Work items

Per ADR-0012, a work item has two artefacts:

Artefact	Holds	Why there
GitHub Issue	Status, dependencies, running log	Cheap conflict-free state changes; queryable by gh
docs/work/WI-###-slug.md	The spec	Version history, reviewable in the PR, rendered on the subsite

Creating a work item means creating both. The issue links to the spec; the spec’s frontmatter carries the issue number.

Numbering

WI-###, allocated from the milestone’s block:

Block	Milestone
001–009	M0 Foundation
010–019	M1 Domain core
020–029	M2 Catalogue & clients
030–039	M3 Product
040–049	M4 Social & discovery
050+	Later
H01+	Human-gated (see agent-boundaries.md)

Numbers are never reused, including for deleted items.

Labels

The vocabulary is closed. Materialised in .github/labels.yml.

Group	Labels	Meaning
Status	status:ready status:in-progress status:in-review status:blocked	Exactly one at all times
Needs	needs:human needs:adr needs:spec-review	Agent must not pick these up
Size	size:S size:M size:L	See sizing below
Area	area:api area:web area:mobile area:db area:docs area:infra	May have several
Gate	migration:destructive docs:n-a	Unlocks a gate step that otherwise fails

status:ready means dependencies are closed and a human is not needed. It is the agent’s work queue:

gh issue list --label status:ready --json number,title,labels

Label hygiene is load-bearing, not cosmetic — a mislabelled issue is picked up out of order.

Sizing

Sizing is about reviewability, not effort. Per ADR-0015 a human reviews every PR, so a work item must be small enough to review in one sitting.

Size	Meaning
size:S	One surface, obvious diff
size:M	One vertical slice across a couple of packages
size:L	Needs needs:spec-review before code. Consider splitting first

If you cannot state a Definition of Done as a checklist of independently checkable lines, the item is too big. Split it.

Human-gated items (WI-H##)

Some work cannot be done by an agent at all — spending money, creating accounts, contacting an external party. These are tracked as work items so they stay visible in the backlog, but they differ from agent items in three ways:

	Agent item	Human-gated item
Labels	status:* + size:* + area:*	status:blocked + needs:human + area:* — no size:
Frontmatter	size:	owner: human, no size:
Closed by	A merged PR	Evidence recorded on the issue

No size label. Sizing measures how reviewable a diff is, and these produce no diff. Applying size:S to “enrol in the Apple Developer Program” would be meaningless precision.

Status is always status:blocked + needs:human. Never status:ready — that label means “an agent may pick this up”, which is the opposite of what these are. An agent that sees needs:human skips the item regardless of dependency state.

Definition of done is evidence, not a diff. A written reply quoted on the issue, a dashboard showing an active account, a measured cost figure. The same rule applies as everywhere else: adjectives are not evidence.

The current set is listed in ../work/README.md and enumerated in agent-boundaries.md.

Dependencies

Declared in both places:

• Issue body: Depends on #12, #14 — GitHub renders the link and shows closure
• Spec frontmatter: depends_on: [WI-012, WI-014]

The dependency graph in ../work/README.md is the human-readable view. Keep it current — it is what stops two agents editing the same schema.

Spec template

---
title: "WI-###: Short imperative title"
description: One line, shown on the subsite index.
issue: 42
milestone: M1
size: M
area: [api, db]
depends_on: [WI-011]
---

# WI-###: Short imperative title

## Problem

One sentence. Why this exists.

## In scope

- Bullet per deliverable.

## Out of scope

- Bullet per thing deliberately excluded.
- This section is as important as the one above — it is what stops scope drift
  mid-loop, and what a reviewer checks the diff against.

## Definition of done

- [ ] Each line independently checkable.
- [ ] Each line has an obvious piece of evidence — a test name, a command, an output.
- [ ] No line reading "works correctly" or similar. That is not checkable.

## Verification

Exact commands a reviewer runs to confirm this, copy-pasteable.

## Notes

Relevant ADRs, traps, prior art.

Lifecycle

created (status:blocked or status:ready)
   → agent picks up      status:in-progress
   → PR opened           status:in-review
   → human merges        closed

An item returning to status:ready after being in-progress means the agent hit a stop condition. The issue comment must say which one.