build-spec

name	build-spec
description	Implement an approved spec end-to-end for aireceipts, including agent-team waves for milestone (M-file) specs. Use when the user says implement/build/ship a spec (e.g. 'build SPEC-0001', 'ship M1').
trigger	/build-spec

/build-spec — approved spec to green PR

0. Gate on status: approved

Read the spec's frontmatter. If status is not approved, stop and say so — drafts do not get built. The spec must also carry a ## Validation record (from /validate-spec); an approved spec without one means the gate was skipped — stop and run it. This skill never edits a spec's status to approved; that's the maintainer's button (AGENTS.md, button 1).

0.5 Context discipline (two builders died of autocompact thrashing — this is law)

• NEVER read real transcripts from ~/.claude/projects or any user data dir — they are megabytes and will thrash your context. Fixtures in test/fixtures/** only.
• Before any Read: ls -la the file; >100KB → read targeted ranges or grep, never whole.
• Pipe every command's output through a filter (| tail -20, grep -c, --reporter=dot) — raw vitest/npm/build output is a context bomb.
• If you feel context pressure (repeated compaction), STOP and report progress to the lead instead of pushing through — a partial report beats a dead builder.

0.6 Modularity law (parallel agents must not collide)

This repo is built by concurrent agents. A spec that grows a shared file grows the merge-conflict funnel for every sibling branch. Rules:

• Adding a capability means adding FILES, not growing a shared union/switch/help string. If the extension point doesn't exist, building the seam is part of your spec.
• One file > 300 lines or a type union/switch that every feature edits = an architecture smell; flag it to the lead rather than growing it.
• Shared-file diffs must be one-line registrations at most (import lists, registry rows) — order-insensitive lines that merge cleanly.

1. Branch — never touch main

git checkout -b feat/<milestone>-<slug> origin/main. Everything in this skill lands on a feature branch and ends at a PR. Nothing in this repo is committed directly to main.

2. Small spec vs. milestone (M-file)

• Small spec: build it yourself, grounded in the spec's Design/Requirements. Reuse existing primitives; match surrounding idiom.
• Milestone spec: it has an Agent team config section. Spawn the team exactly as written there — roles by directory ownership, dependency waves in order, the named critical-path role coordinates the public API others build against. Do not invent roles or waves not in the spec; if the spec's plan is wrong, fix the spec first.

3. Build against the invariants

Every line of product code honors I1–I6 (AGENTS.md). In particular: I1 zero model calls in the product path, I2 never fabricate a $, I5 goldens gate output — if you change receipt output, update goldens deliberately and say so, don't let a snapshot test silently rewrite them.

4. The unmasked gate (hard-won lesson — do not skip)

npx tsc --noEmit;                    echo $?
npx eslint . --max-warnings 0;       echo $?
npx vitest run;                      echo $?
node scripts/verify-goldens.mjs;     echo $?

Never pipe through tail/head/grep — that swallows a real failure's exit code. Check $? directly, every time, even when "it obviously passed."

5. Tests

Cover every Requirement and Scenario in the spec's test matrix. For src/pricing/**, tests must survive Stryker mutation, not just hit coverage.

6. Walk acceptance criteria live

Run the built CLI against real behavior (not just unit tests) for each Success criteria checkbox. Check the boxes once verified and set status: building while the PR is open — shipped is flipped only after the human merges (release/archive step).

6.2 Reuse first, then simplify (no redundant code ships)

BEFORE writing any module: search src/ for an existing primitive that already does the job (grep the exports; the repo deliberately builds shared seams — present.ts blocks, aggregateWaste, exporters, mini). Building a parallel version of something that exists is a defect, not a style choice (we shipped two mini.ts twins once — the dedupe cost a merge cycle). AFTER the matrix passes, do one simplification pass over your own diff: inline single-use helpers, delete dead branches and unused exports, collapse needless abstraction (YAGNI). Smaller diff, same green matrix.

6.3 Tests catch real issues, not coverage

Every test must assert behavior a user could observe breaking. Forbidden: tests that only import/instantiate, toBeDefined()-grade assertions, snapshots without a stated intent. Required per requirement: the matrix row PLUS at least one adversarial case (malformed input, boundary, wrong-order call). Any NEW command or flag gets an e2e-level test through the real CLI dispatch (main()/dist binary on a fixture), not just its module functions. Mutation testing on money paths is the enforcement backstop — a test that kills no mutants is decoration and will be treated as a finding in review.

6.4 Design comes from the lead

If the spec touches a user-visible surface (receipt layout, exported artifacts, docs structure, README copy) and lacks a design section, STOP: the lead (Fable-tier model) authors the design artifact — mock, layout spec, exact copy — before implementation is delegated. Implementers execute designs; they don't invent them.

6.5 Docs ride with the feature

Any user-visible change (new flag/command, changed output, new behavior) updates the affected docs — README, docs/**, --help text — in the same PR, never "in a follow-up." Then run /review-docs on the touched docs (advisory at PR time, but the release gate re-runs it as blocking, so fix now). A feature PR with stale docs is an incomplete PR.

7. Commit + PR (structured description — non-negotiable)

The PR description follows .github/pull_request_template.md exactly: What this adds / Why it matters to users (user-facing only) / See it (mandatory output capture for any user-visible change — a terminal code block or committed image path; the receipt IS the screenshot) / What changed / What to review, in order (numbered, riskiest first, file:line pointers) / Evidence (gates + spec + validation record) / Notes. A reviewer should know in 30 seconds what was added, what to look at first, and what a user gains.

Conventional commit subject, backticked code terms, bullets for multiple changes. Open the PR against main; wait for CI green (ci.yml matrix + goldens + mutation if src/pricing/** touched).

Then, from your worktree, run npx aireceipts-cli pr --post before handing the PR over — it attaches this building session's receipt as a marked PR comment (SPEC-0037). Every PR carries the receipt of the session that built it; the pr-receipt-check workflow only notices a skip, so this step is on you.

When done: summarize what shipped, the live-acceptance results, and the PR link.