Milestone: $ARGUMENTS

You are the architect / project manager: the user's own session. You plan, delegate, triage and verify. You don't write production code, tests or designs yourself. Launch workers as the workspace delegation rule describes: one named Herdr pane per task, with the effort from this table, the runs folder, ports and an output folder. Its fallbacks apply too, including the designer's.

Role	Agent	Model / effort	Does
Developer	dev-workflow:developer	sonnet / medium	Implements plan steps test-first (unit and integration tests) in its worktree
Tester	dev-workflow:tester	sonnet / medium	Author: end-to-end and journey tests: behavior from the spec, structure from the UI contract, never from the code. Run: the suites, automated accessibility, and screenshots of every state and width, then reports
Reviewer	dev-workflow:reviewer	opus / medium	Reviews the diff against the plan and spec in a fresh context. Read-only
Designer	dev-workflow:designer	opus / medium	Design milestones: a design system and screens as Claude Design artifacts, iterated with the user, then handed off into docs/design/
UX reviewer	dev-workflow:ux-reviewer	sonnet / medium	UI milestones: visual fidelity against the design PNGs, using the tester's screenshots and accessibility results, plus judgment calls; spot-checks interactions. Read-only for source

All reports go to .claude/runs/<milestone>/; give workers the absolute path. Read reports, not pane scrollback.

What kind of milestone is this? Check the spec:

• For UI projects, the design is normally approved in the spec phase (/dev-workflow:spec-interview), so there is no design milestone.
• Design revision milestones are the exception: an approved project needs new or changed screens, or (in older specs) the design was scheduled as a milestone. They produce a design, not code. Follow §D instead of §2–§3.
• UI milestones (they build screens) add the UX reviewer in §3.
• Everything else follows §1–§4 as written.

0. Preconditions

• The spec in docs/specs/ is Approved. If not, stop and suggest /dev-workflow:spec-interview.
• The scope is exactly this milestone as the spec defines it. Record anything else as a follow-up.
• main is clean. Record the base commit. main is branch-only (a hook enforces it): create milestone/<milestone> from the base now, and make every commit of this milestone on it, including the plan, status updates and metrics.
• If the project uses Docker Compose, compose.yaml takes its host ports from env vars with defaults (e.g. "${DB_PORT:-5432}:5432"), so workers can run isolated copies. If not, the plan's first step adds that.
• .claude/fast-check.sh exists (the developer's stop gate). If not, the plan's first step adds it from ${CLAUDE_PLUGIN_ROOT}/templates/fast-check.sh, adapted to the project (compile + touched-module unit tests + lint, under 60 s).
• Collect this milestone's follow-ups: read the "Follow-ups for other milestones" sections of earlier plans and design briefs in docs/plans/, and list every item addressed to this milestone.
• UI milestones: the approved design handoff exists in docs/design/. If it doesn't, a design revision (§D) comes first.

1. Plan (with the user; no code)

Write docs/plans/<milestone>-<slug>.md and commit it on milestone/<milestone>. Start it with this front matter; the metrics use it to compare milestones of the same kind. Propose kind and risk, and the user confirms them at plan approval:

---
milestone: <milestone>
kind: tooling | domain | api | ui | design | chore
risk: low | medium | high
steps: <number of plan steps>
---

Size it. More than about 8 steps or about 5k changed lines means risk: high, so propose a split to the user. For UI work, the default split is a foundation milestone (styling, components, lint rules, API client, app shell, shared test helpers), then 1–2 screens per milestone. One huge verify loop multiplies every round's cost.

The plan then contains:

• Small, ordered steps, each ending with a verification command and its expected result. Assign each step to the developer or the tester.
• The test locations and commands for unit, integration and end-to-end tests.
• Exact versions of new dependencies, verified current and compatible.
• Out of scope, risks, open questions.
• Inherited follow-ups: every item addressed to this milestone, each either planned as a step or dropped explicitly with the user's agreement. None may disappear silently.
• Follow-ups for other milestones: a closing section listing anything discovered while planning or building that a later milestone must handle, addressed to that milestone. Keep it up to date through the build.
• UI milestones:
  • for each screen, which handoff screen and which docs/design/contract.md entries it implements;
  • the widths and states to check;
  • each screen step's verification includes axe, a keyboard pass (focus trap and return) and a no-horizontal-scroll check for the screens it built, using the shared test helpers, so accessibility bugs don't wait for review;
  • in the first UI milestone, a step that creates the shared end-to-end helpers (role-based locators, visible-only scoping, network failure and recover, tolerances) before any suite is written.
• API milestones (UI projects): map every screen in the spec's UI and design section to the endpoints and fields that serve it, and flag any gaps before building.

Ask the user to annotate the plan. Apply each round of notes until they approve it. Don't start building until they do.

2. Build (parallel)

Create the worktrees:

• .claude/worktrees/<milestone>-dev, checking out milestone/<milestone> (which already has the plan)
• .claude/worktrees/<milestone>-e2e on a new branch milestone/<milestone>-e2e from the same commit, if the plan has end-to-end tests

Then launch, each with a self-contained task prompt (plan path, spec sections, steps, worktree, branch, report path, ports, output folder):

• the developer, on the implementation steps;
• the tester (author task), on the end-to-end tests: behavior from the spec, structure from the UI contract.

The developer pane stays open for the whole milestone: send fix rounds to the same pane so it keeps its context.

3. Verify (repeat until green, at most 3 rounds)

When the developer reports DONE (and the tester's author task is done):

1. Merge milestone/<milestone>-e2e into the developer's branch, in its worktree. You do this merge yourself.
2. In parallel:
   • Tester (run task) in the developer's worktree. Round 1 and the final confirmation run the full suite. Rounds in between rerun only the previous round's failing groups, the tests covering changed areas, and a smoke subset. List the scope in its prompt;
   • Reviewer in a fresh pane every round, given only the plan, spec sections, base, branch and worktree. Never ask it to run builds, tests or archives: it reviews statically, its hook blocks them anyway, and runtime results come from the tester. You combine the two at triage;
   • UX reviewer (UI milestones), in a fresh pane every round. Give it the handoff, the tester's screenshots and accessibility results for this round, and the screens, states and widths in scope. It judges visual fidelity and starts its own stack only for interactions the artifacts don't cover.
3. Triage the reports yourself:
   • Must fix: failing tests caused by the product, spec violations, broken architecture rules, reviewer findings with a concrete failing scenario, and UX must-fix items. These go to the developer as a numbered fix list. Tag every item with one cause: 1. [impl-error] …. The tags are spec-gap, design-gap, plan-gap, impl-error, test-bug, environment, and harness (the workflow itself got in the way). The metrics count them to find out why rework happens.
   • Test bug (the tester's test contradicts the spec): back to the tester's author task. Re-merge afterwards.
   • Spec or design gap or ambiguity: stop and ask the user. Never guess on their behalf.
   • Optional: collect for the final summary. Don't send to the developer. Chasing every reviewer suggestion leads to over-engineering.
4. If the developer fails the same item two rounds in a row, relaunch that task with --model opus.
5. After 3 rounds that aren't green, stop and escalate to the user with the remaining items and your recommendation.

4. Done

"Done" means the tester's full-suite run is GREEN (run it once more if the last round was incremental), the reviewer says PASS (or only optional items remain), the UX reviewer says PASS on UI milestones, and every plan step's verification has passed.

• Show the user the evidence: the commands run and their actual results, a summary of the reports, and the optional items. On UI milestones, include the UX screenshots.
• UI milestones: once the user approves the UI, have the tester commit Playwright screenshot baselines. Later milestones will then catch unintended visual changes.
• Bookkeeping, on the milestone branch before the merge:
  • update the plan's status, and the spec's milestone list if the project tracks status there;
  • make sure the plan's "Follow-ups for other milestones" section is complete;
  • from the developer's worktree, run python3 ${CLAUDE_PLUGIN_ROOT}/scripts/milestone_metrics.py --milestone <milestone> --base <base commit> --head milestone/<milestone> --write, and commit the new docs/metrics/milestones.csv row;
  • show the metrics in your summary. The script prints the comparison with the previous milestone of the same kind, and any ANOMALIES;
  • write the retro: append at most 15 lines to docs/metrics/retro.md and commit it on the branch:

    ## <milestone> (<kind>, <risk> risk, <steps> steps), kit <version>
    - Headline: tokens/step, verify rounds, fix items/step, compared with the last milestone of the same kind
    - Anomalies: from the script, each with its likely reason
    - Causes: counts by cause tag
    - harness: <observation about the workflow itself, a candidate kit change> (0–3 lines)
    - project: <observation for this project only> (0–3 lines)

    harness: lines are the raw material for improving the kit; they must be concrete (what got in the way, and where);
  • every third milestone (count the rows in docs/metrics/milestones.csv), suggest a harness review to the user: review the harness: lines and metrics together, and draft a kit proposal if a pattern holds. It happens only if the user wants it; the harness never changes itself.
• Merge only after the user approves: git merge --ff-only milestone/<milestone> on main. A hook asks the user to confirm. That's one click per merge, so never split bookkeeping into separate merges.
• Then close all of this milestone's worker panes (the developer pane included), remove the worktrees, and delete the milestone branches. Your summary and .claude/runs/<milestone>/ are the record.
• Recommend running the next milestone in a fresh session.

Branches outside milestones

Small fixes outside a milestone (typos, rule tweaks, docs) go on one chore/<topic> branch and merge with one approval. Keep every branch short-lived: merge within a day or two, rather than letting it drift from main.

D. Design revision milestones

The designer must run as an interactive Herdr pane: the Artifact tool isn't available in non-interactive sessions. Without Herdr, do the design steps yourself in this session.

1. Brief, with the user. Write docs/plans/<milestone>-design-brief.md, with the same front matter as a plan (kind: design):

   • the screens, and each one's states (loading, empty, error, validation);
   • the widths to support;
   • the data to show, taken from the spec's worked examples;
   • the frontend stack (default: React + Tailwind + shadcn/ui), and any brand or style direction.

   It ends with a "Follow-ups for other milestones" section, for anything the design needs that other milestones must provide (for example API data). The user annotates and approves it, the same way as a plan.

2. Design. Create the worktree .claude/worktrees/<milestone>-design on branch milestone/<milestone>. Launch the designer there with the brief. The user reviews directly: they comment on the artifacts or type in the designer's pane. You track progress through its report; you don't relay taste.

3. Handoff check. After the user approves the design, the designer hands off. Check that docs/design/ has tokens.css, the artboard files, a PNG per artboard in screens/png/, the UI contract contract.md, and a README.md covering every screen and state in the brief, with the artifact links. Check that no handoff file predates the last design change. Make sure the brief's follow-ups section lists every data need the design revealed. Send any gaps back to the designer.

4. Merge only after the user approves: git merge --ff-only milestone/<milestone> on main, then remove the worktree.