tasks

Break the design into tasks

Input is spec.md and design.md under .brownspec/features/<slug>/. Output is tasks.md from ${CLAUDE_PLUGIN_ROOT}/templates/tasks.md.tmpl, plus trace.json.

If the design's exit checklist does not pass, stop and say so. A task list built on an unfinished design encodes its gaps as work items and hides them.

Sizing

One task is one reviewable unit: half a day to a day for someone who knows the codebase, producing a diff a reviewer can hold in their head. Split anything larger. If a task cannot be sized because the approach is unclear, that is a design gap — name it and go back rather than papering over it with a vague task.

Ordering

By dependency, not by layer. The system stays deployable at every step:

1. Expand — additive, breaks nothing (new columns, new endpoints, flag off)
2. Implement — the behavior itself, behind the flag
3. Migrate — move consumers and data over
4. Contract — remove what is now dead

Mark what can run in parallel, and what must ship in one release together, with why.

Consumer migration from the design's blast radius becomes real tasks here. A breaking change with three known callers is four tasks, not one.

Each task carries

• A verb-first title
• The files or modules it touches — you have read the repo, be specific
• Which acceptance criterion from spec.md it advances
• How it is verified: the test, the check, the observable outcome
• Its blockers, by task ID

Testing and observability are tasks, not footnotes. If the design says a metric is emitted, some task emits it.

trace.json

Write it alongside tasks.md, with files empty. It is filled in as work happens — the agent implementing a task records what it actually touched. That record is what /brownspec:drift will later compare against the spec.

{
  "slug": "<slug>",
  "spec": "spec.md",
  "generated": "<date>",
  "tasks": [
    {
      "id": "T1",
      "title": "<verb-first title>",
      "advances": ["A1"],
      "expected_paths": ["app/api/orders.py"],
      "files": [],
      "status": "todo"
    }
  ]
}