@ai-agent-lead/skills 1.0.0

package/skills/tdd/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: tdd
+description: Test-driven development with the red-green-refactor loop. Use when implementing a feature, fixing a bug, changing core logic, or when the user mentions "TDD", "test-first", "red-green-refactor", or "integration tests". Skip for trivial UI glue, config changes, or pure docs edits.
+complexity: medium
+expected_duration: 20 minutes
+---
+
+# Test-Driven Development
+
+## When to use
+
+- Implementing a feature, fixing a bug, or changing core logic.
+- Any `tdd-rounds` Builder invocation (mandatory every round).
+- The user mentions "TDD", "test-first", "red-green-refactor", "integration tests".
+
+## When to skip
+
+- Trivial UI glue, framework wiring, config changes, pure docs edits.
+- Trivial getters / setters with no behavior.
+- Bug whose root cause isn't yet known — run [`debug`](../debug/SKILL.md) first; the reproduction crystallises into the failing test.
+
+## Philosophy
+
+Tests verify **behavior through public interfaces**, not implementation details. Code can change entirely; tests shouldn't.
+
+- **Good tests** read like specifications: "user can checkout with valid cart". They use the public API and survive refactors.
+- **Bad tests** are coupled to internals: they mock internal collaborators, assert on call order, or peek at private state. The warning sign — the test breaks during a refactor when behavior didn't change.
+
+See [TESTS.md](TESTS.md) for concrete good/bad examples and a pre-commit checklist.
+
+## Anti-pattern: Horizontal Slicing
+
+**Do not write all tests first, then all implementation.** This is the most common TDD failure mode for AI agents — you write five tests in one shot, then five matching functions. The tests describe *imagined* behavior, become insensitive to real bugs, and lock in the wrong shape.
+
+```
+WRONG (horizontal):
+  RED:   test1, test2, test3, test4, test5
+  GREEN: impl1, impl2, impl3, impl4, impl5
+
+RIGHT (vertical):
+  RED → GREEN: test1 → impl1
+  RED → GREEN: test2 → impl2
+  ...
+```
+
+One test → minimum code to pass → next test. Each cycle informs the next.
+
+## Workflow
+
+### 1. Red — Write a failing test
+
+- Pick one acceptance criterion from the feature doc.
+- Write a single test that asserts the behavior through the public interface.
+- Name the test after the behavior, not the function: `returns_empty_list_when_no_users`, not `test_getUsers`.
+- Run it. Confirm it fails for the **right reason** (assertion failed, not import error).
+
+### 2. Green — Minimum code to pass
+
+- Smallest amount of code that makes the test pass.
+- Hardcoding a return value is acceptable on the first test — the next test forces generalization.
+- Resist adding features the test does not require.
+
+### 3. Refactor — Clean up with the test as a safety net
+
+- Remove duplication, improve names, extract functions.
+- Run tests after every change.
+- Do not add new behavior during refactor.
+- **Never refactor while red.** Get to green first.
+
+### 4. Simplify pass — end-of-round, after green
+
+Before declaring the round done, run the [`simplify`](../simplify/SKILL.md) skill. It walks every changed file with four lenses — reuse, quality, efficiency, test relevance — and is a single sweep, not a license to refactor everything. If you find structural issues that need a dedicated round, surface them as `Open questions for parent` instead.
+
+## Rules
+
+- One behavior per test.
+- No production code without a failing test first (for core logic).
+- Test through public interfaces only — don't peek at private state or internal calls.
+- If a test is hard to write, the design is probably wrong — fix the design, not the test.
+- Test-after is acceptable for: UI wiring, framework glue, trivial getters/setters.
+
+## Test Pyramid (default targets)
+
+- ~70% unit tests — fast, isolated.
+- ~20% integration tests — real dependencies where it matters (DB, HTTP).
+- ~10% end-to-end — only the critical user paths.
+
+## Anti-patterns
+
+- Writing tests after the code "to get coverage" — defeats the design feedback loop.
+- Mocking everything — tests pass but the system is broken. Mock at boundaries only (external APIs, time, randomness).
+- One giant test asserting many things — failures become hard to diagnose.
+- Asserting on internal call counts or order — couples the test to implementation.
+
+## When invoked as a Builder for a multi-round project
+
+If the parent agent dispatched you with a `tdd-rounds`-shaped brief listing "Skills (in order): design, tdd, simplify": **execute all three sequentially in this single invocation. Do not return to the parent between skills.** "In order" means run them in that order WITHIN this run — not handed off across separate invocations. Returning early after only `design` is the most common Builder failure mode and forces the parent to re-dispatch.
+
+The `tdd-rounds` skill captures the full orchestration pattern (Builder brief schema, structured report shape, parent verification ritual). Read it if your brief references it.
+
+## Pairing with other skills
+
+- **[`feature-doc`](../feature-doc/SKILL.md)** — runs *before*. ACs become the test list.
+- **[`debug`](../debug/SKILL.md)** — runs *before* for non-trivial bugs. Reproduction → failing test.
+- **[`design`](../design/SKILL.md)** — runs *alongside*. If TDD feels painful, the design is wrong.
+- **[`simplify`](../simplify/SKILL.md)** — runs *after green*. End-of-slice / end-of-round sweep.
+- **[`prod-ready`](../prod-ready/SKILL.md)** — runs *after green* (single feature) before opening the PR.
+- **[`tdd-rounds`](../tdd-rounds/SKILL.md)** — wraps `tdd` for multi-round projects.
+
+## Done when
+
+- All ACs from the feature doc are green and the tests are committed.
+- Tests assert behavior through public interfaces, not internals.
+- The simplify pass has run.
+- For single-feature flow: `prod-ready` is queued. For `tdd-rounds`: the structured Builder report is emitted.
+
+## Handoff
+
+When all acceptance criteria are green:
+- For a single-feature project: run `prod-ready` before opening the PR. Catches operational, infrastructure, and consistency issues tests don't surface.
+- For a multi-round project orchestrated under `tdd-rounds`: emit the structured Builder report (per `tdd-rounds/templates/builder-report.md`) and stop. The parent runs `prod-ready` and `verify-real-deps` at the project level.

package/skills/tdd/TESTS.md

@@ -0,0 +1,93 @@
+# Good and Bad Tests
+
+Companion to [SKILL.md](SKILL.md). Concrete examples of the philosophy "test behavior, not implementation."
+
+Examples use TypeScript-ish syntax for readability — the principles apply to any language and any test framework (pytest, JUnit, Go's `testing`, Jest, RSpec, etc.). Replace `expect(x).toBe(y)` with the equivalent assertion in your stack; the structure (Arrange / Act / Assert through the public interface) is what matters.
+
+## Good tests
+
+Test through the public interface. Read like a specification.
+
+```ts
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Properties:
+
+- Describes *what* the system does, not *how*.
+- Uses only public APIs.
+- Survives internal refactors.
+- One logical assertion per test.
+
+## Bad tests
+
+### 1. Asserting on internal calls
+
+```ts
+// BAD — couples the test to the implementation
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+If you rename `process` or split it into two calls, the test breaks even though behavior is identical. Test the *outcome*, not the call.
+
+### 2. Bypassing the interface to verify
+
+```ts
+// BAD — peeks into the database directly
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+```
+
+```ts
+// GOOD — verifies through the public interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```
+
+If the storage layer changes (different table, new ORM, in-memory cache), the good version still works.
+
+### 3. Testing the shape, not the behavior
+
+```ts
+// BAD — asserts structure, not meaning
+test("getUser returns object with id and name fields", async () => {
+  const user = await getUser("123");
+  expect(user).toHaveProperty("id");
+  expect(user).toHaveProperty("name");
+});
+```
+
+```ts
+// GOOD — asserts the behavior the caller depends on
+test("getUser returns the user matching the requested id", async () => {
+  const created = await createUser({ name: "Alice" });
+  const fetched = await getUser(created.id);
+  expect(fetched.name).toBe("Alice");
+});
+```
+
+## Quick checklist
+
+Before committing a test, ask:
+
+- [ ] Would this test still pass if I rewrote the implementation while keeping behavior the same?
+- [ ] Does the test name describe a behavior, not a function?
+- [ ] Does it use only public APIs (no private fields, no DB peeking, no internal mocks)?
+- [ ] Is there exactly one logical thing being asserted?
+
+If any answer is no, revise before merging.

package/skills/tdd-rounds/COMMITS.md

@@ -0,0 +1,122 @@
+# Commit cadence and message style
+
+The Builder's commits are the parent's review surface. A round that ships as one big commit forces the parent to read everything at once; a round that ships as a clean per-slice sequence is reviewable one diff at a time. The shape below was load-bearing across 14 rounds in the project this skill was distilled from.
+
+## The rules
+
+### 1. Every code commit gets an `R<N>:` prefix
+
+`git log --oneline` then reads as round history. A reviewer or future contributor scanning the log can see "this is round 5; this is the simplify pass at end of round 6.7; this is the final round before tag" without opening any commit.
+
+### 2. Bug-fix commits also reference the issue ledger
+
+Format: `R<N>: #<X> <title>`. Each bug-fix commit ties one-to-one to an entry in `docs/known-issues.md`. The ledger entry doubles as the brief; the commit closes it.
+
+```
+R12: #3 strip models/ prefix from parsed model id
+R14: #8 forwarder rewrites body's project field to chosen pool account
+```
+
+### 3. One commit per AC slice when slices are independent
+
+Round delivers 5 ACs with no dependency between them → 5 commits + 1 simplify-pass commit + 1 doc tick commit. Each commit is a clean unit a parent reviews in isolation.
+
+```
+R12: #1 add g1-pro-tier to routing tier order
+R12: #2 seed quota cache on accounts add
+R12: #3 strip models/ prefix from parsed model id
+R12: #4 add POST /v1/accounts/{handle}/refresh-quota endpoint
+R12: #5 dual-mode audit parser dispatches on Content-Type
+R12: simplify — factor applyFrame, extractModel; close known-issues
+```
+
+A single mono-commit "R12: smoke-test fixes" of the same content forces the parent to mentally separate five unrelated changes from one diff. Avoid.
+
+### 4. Simplify pass is its own commit
+
+End-of-round refactoring (extracting helpers, removing dead branches, tightening names) is mechanically separate from the AC work that motivated it. Bundling them hides the "what changed because the AC required it" from "what changed because we cleaned up after." Reviewers care about the distinction; a separate commit preserves it.
+
+### 5. Doc-only commits stay separate from code
+
+`docs/STATE.md`, `docs/known-issues.md`, ADR patches — never bundle into a code commit. Mixing makes both diffs harder to read. Doc-only commits get a `docs:` prefix (no `R<N>:`):
+
+```
+docs: append actual R14 entry to STATE.md
+docs: add public README
+```
+
+### 6. Single-commit rounds are OK when justified
+
+A refactor round (no AC slices) or a single-issue fix can land in one commit if splitting would create non-buildable intermediate states. The Builder's report MUST justify the lump in `Deviations`:
+
+> Single commit instead of multiple `R13:` slices. The change is small (one interface method + one Service-level helper + four targeted tests) and the slices are tightly coupled (interface change forces Stub method to land in the same commit); splitting would create a non-buildable intermediate state.
+
+If you can't justify it, don't lump it.
+
+### 7. Commit messages are honest
+
+The commit message states what the commit actually does, not what you wished it did. The lesson from this skill's source project: an R14 commit message claimed "STATE.md updated" but the Builder had forgotten that file — a follow-up commit was needed to restore truth. **Cost of an honest message: one extra line of typing. Cost of a lying message: a follow-up commit, a smudged history, and a lost minute the next time someone wonders why the round entry is missing.**
+
+If a step you described in the brief didn't actually land, say so in `Deviations`. If a commit's diff doesn't match its message, fix the message before committing — or split into two commits if the message's intent really was two things.
+
+## Message body shape
+
+The first line is the subject (~50–72 chars). The body explains:
+
+- **What** the commit does (one or two sentences).
+- **Why** the change was needed (the AC, the bug, the constraint).
+- **Tradeoff being accepted** if the change picked one path over another.
+
+Keep it short. Three short paragraphs > one long one. Bullets are fine.
+
+Real example from R8:
+
+```
+R8: AC-CLI1/3/4/5 + AC-OP1/3 — cobra CLI + start subcommand
+
+Wraps the admin API with a cobra-driven command tree:
+- accounts {list, add, remove, cooldown, rename}
+- stats / usage with --since, --until, --group_by, --json
+- start subcommand wires app.NewDaemon + admin.NewServer under
+  shared ctx with SIGINT/SIGTERM cancel.
+
+Read commands precheck /v1/healthz; daemon-down surfaces the
+documented "Run gemini-proxy start first" remediation instead of a
+raw connection-refused stack.
+
+--group_by uses snake_case to match the AC text. table-by-default,
+--json for machine-readable; same data both formats.
+```
+
+Counter-example that fails the rules:
+
+```
+R8: stuff
+```
+
+(no scope, no why, no shape).
+
+## Footer
+
+Co-authored-by line for agent contributions:
+
+```
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+```
+
+Use whatever model line matches the actual driver. Match exactly the convention the project's CLAUDE.md (or root agent doc) prescribes — don't invent variations.
+
+## Anti-patterns
+
+- **Mono-commit at end of round.** "R<N>: round done." Defeats the per-slice review story.
+- **Bundling docs with code.** STATE.md updates ride along with the code change. Diffs become harder to read.
+- **Imperative-mood squashing.** Four sequential "wip" commits eventually amended into one. The journey isn't the commit; the destination is. Don't force-amend; commit cleanly the first time.
+- **Empty bodies on non-trivial commits.** "fix bug" with no body. The body is where the *why* lives.
+- **Lying about scope.** A commit message saying "also updates X" when the diff has no X. Worse than no message.
+- **Skipping the prefix.** A round commit without `R<N>:` is a hidden commit — the log loses its round structure.
+
+## When to skip these rules
+
+- **Pre-round scaffolding** (initial repo setup, before round 1) — no `R<N>:` prefix yet, no AC contract. Plain conventional commits work.
+- **Hot-fix to a tagged release** (post-v1, urgent) — the `R<N>:` cadence is for active development; emergency fixes can use `fix:` or `hotfix:` prefixes per the project's release-engineering norms. Document in the project's CLAUDE.md.
+- **Squash merges to main** — if the project's branching model squashes feature branches, the per-slice commits live on the feature branch only. The squashed commit message should still preserve the per-slice summary in its body.

package/skills/tdd-rounds/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: tdd-rounds
+description: Multi-round TDD orchestration. Use when delivering a feature larger than one TDD slice — typically 5-15 acceptance criteria across multiple packages — by dispatching Builder sub-agents per round, with the parent maintaining state and verifying. Triggered when the user mentions "drive the sub-agent team", "multi-round TDD", "orchestrate rounds", "Builder agents", or when a plan from `feature-doc` lists more ACs than one agent should reasonably tackle in a single invocation. Pairs with `tdd` (Builders invoke that skill per round) and `prod-ready` (final round before tag).
+complexity: high
+expected_duration: 1 hour
+---
+
+# Multi-Round TDD Orchestration
+
+Distills the pattern of a parent agent driving Builder sub-agents through a feature's acceptance criteria, one round per AC slice. The parent does not write code; the parent writes briefs, reviews diffs, runs verification, and keeps the running summary.
+
+## When to use
+
+- A feature doc has more ACs (say, ≥10) than one agent invocation can hold cleanly.
+- Multiple packages are involved; serial rounds let each one land cleanly before the next builds on top.
+- Cross-round invariants matter (test green every round, not just at the end).
+
+## When to skip
+
+- Single-AC bug fix or single-package feature — invoke `tdd` directly, no round overhead.
+- Pure refactor with no AC changes — use the `improve-codebase-architecture` flow instead.
+
+## The parent's contract
+
+- **Plan once.** The plan file lists rounds, each round's ACs, the dependency order, and the skills cadence per round (which rounds need `design`; when to invoke `improve-codebase-architecture` mid-project; when to invoke `prod-ready`).
+- **Brief per round.** A self-contained brief — the Builder shouldn't need conversation history. 
+  - **Briefing Sub-agent**: For complex rounds, invoke a sub-agent to autonomously generate the brief by analyzing `docs/STATE.md`, the `feature-doc`, and the results of the previous round. See `templates/builder-brief.md` for the schema.
+- **Verify after each round.** Run the test command independently (don't trust the Builder's pasted output), read the diff, tick AC checkboxes in the feature doc with the test name, append a round summary to `docs/STATE.md`.
+- **Never write code yourself.** If you find yourself doing it directly under time pressure, that's a signal the round was misscoped — split it.
+
+## The Builder's contract
+
+When dispatched for a round, the Builder:
+
+1. Reads the brief, the plan file, `docs/STATE.md`, and any ADRs / feature docs the brief cites.
+2. **Executes the listed skills sequentially in this single invocation.** When a brief says "Skills (in order): design, tdd, simplify" — that means run all three in this run, not return to the parent between them. This rule is non-obvious; the brief template makes it explicit.
+3. Commits per AC slice (or per behavior slice for refactor rounds), prefix `R<N>:`. **Read [`COMMITS.md`](COMMITS.md) before the first commit** — it captures the seven rules (`R<N>:` prefix, `#<X>` for bug fixes, per-AC slicing, separate simplify-pass commit, separate doc commits, single-commit-with-justification, honest messages) and the message-body shape. The parent reads commits as the review surface; a clean sequence is reviewable one diff at a time, a mono-commit isn't.
+4. Returns the structured report from `templates/builder-report.md`.
+5. Does NOT push, does NOT touch files outside the brief's allowlist.
+
+## Skills cadence
+
+| Skill | Invoked by | When |
+|---|---|---|
+| [`design`](../design/SKILL.md) | Builder | Rounds introducing a new package or non-trivial interface. Skip on rounds that only extend existing modules. |
+| [`tdd`](../tdd/SKILL.md) | Builder | **Every** code-writing round. Mandatory. |
+| [`simplify`](../simplify/SKILL.md) | Builder | End of every round, after green. Single sweep — reuse / quality / efficiency / test relevance. Lands as its own commit ([COMMITS.md rule 4](COMMITS.md)). |
+| [`improve-codebase-architecture`](../improve-codebase-architecture/SKILL.md) | **Parent** | Once mid-project, after the load-bearing seams exist. Surfaced opportunities become dedicated refactor rounds (no behavior change; ACs are "all existing tests still green"). |
+| [`prod-ready`](../prod-ready/SKILL.md) | Builder, final round only | Pre-tag operational checklist. Output the filled checklist verbatim in the Builder's report. |
+| [`verify-real-deps`](../verify-real-deps/SKILL.md) | **Parent** | After `prod-ready` clean, before tagging. Catches what unit/integration tests can't see — wire-shape mismatches against real third-party APIs. |
+
+## State tracking
+
+`docs/STATE.md` is the parent-maintained running summary, append-only, ~one entry per round. The Builder reads it as pre-flight context for the round; the parent appends after each round closes. Single source of truth for "what we have so far" between Builder invocations.
+
+Format per round:
+
+```
+## Round N — <title> (DONE YYYY-MM-DD)
+Delivered: AC-NN, AC-NN
+New packages: <list>
+Public types: <one line>
+Invariants now enforced: <one line>
+Known follow-ups: <one line>
+```
+
+## Failure modes and recovery
+
+- **Builder stuck (test won't go green / design feels wrong).** Builder reports a *blocking* open question instead of thrashing. Hard rule: **Builder must not silently descope an AC.**
+  - **Concrete escalation signals** (any one fires → stop and surface):
+    - 3 consecutive failed attempts at making the same test green with the same approach.
+    - 2 design-level questions that the brief + STATE.md + cited ADRs don't answer.
+    - The Builder finds itself wanting to modify a file in the "must NOT touch" allowlist to make progress.
+    - A new test would require mocking >3 internal collaborators (smell: design is wrong, not the test).
+  - **Parent's response**: shrink scope (split the round), or invoke `design` explicitly with the friction described, or run `grill-plan` if a load-bearing decision is wobbling. Don't push the Builder to keep trying.
+- **Round breaks earlier rounds' tests.** Parent-review failure. Fix is a follow-up round, scope = "restore green for tests X, Y; explain what regressed; adjust ADR if needed." Never amend prior commits.
+- **ADR turns out wrong mid-round.** Builder stops with a blocking open question. Parent runs `grill-plan` or writes a superseding ADR. The current round restarts with the new ADR as input.
+- **User redirects mid-round.** Cancel the in-flight Task. No partial-round commit. Re-brief and re-run. Sub-agent state is ephemeral by design.
+- **Brief was wrong.** Parent rewrites the brief, re-dispatches. Don't try to "fix it up" through follow-up messages — sub-agents work better from a clean self-contained brief.
+
+## Templates
+
+- [`templates/builder-brief.md`](templates/builder-brief.md) — the self-contained brief shape the parent fills in per round.
+- [`templates/builder-report.md`](templates/builder-report.md) — the structured report shape the Builder returns.
+
+## Supporting docs
+
+- [`COMMITS.md`](COMMITS.md) — commit cadence and message style (per-AC slicing, `R<N>:` prefix, when single-commit is OK, honesty rule). Builders read this before the first commit.
+
+## Handoff
+
+When the final round completes:
+
+1. Run `verify-real-deps`. Capture surfaced bugs into `docs/known-issues.md`.
+2. Iterate fix-rounds until clean, or document deferrals to vN.1 with rationale.
+3. Tag and publish via whatever release / distribution channel applies.

package/skills/tdd-rounds/templates/builder-brief.md

@@ -0,0 +1,73 @@
+# ROUND N — <title>
+
+You are a Builder sub-agent in a multi-round TDD project. Read the orchestration plan and `docs/STATE.md` first. **Execute design + tdd + simplify in THIS invocation. Do not stop after design.**
+
+## Scope
+
+<one paragraph in plain English: what behavior ships this round, what it does NOT cover>
+
+## ACs in scope (verbatim from feature doc)
+
+- **AC-XX1** Given ..., when ..., then ....
+- **AC-XX2** ...
+
+## ACs explicitly out of scope this round
+
+- AC-YYY (defer to Round M).
+- All other ACs.
+
+## ADR refs (load-bearing constraints, restated in 1 line each)
+
+- **ADR-NNN** (`docs/adr/NNN-*.md`): <one-line summary of the constraint this round must respect>.
+- **ADR-NNN** (...): ...
+
+## Files you may create
+
+- `<path>/*.go` and `*_test.go`
+- ...
+
+## Files you may modify
+
+- `<path>` (specific reason)
+- ...
+
+## Files you must NOT touch
+
+- closed packages: `<list>`
+- `cli/`, `creds/`, `.claude/`, `docs/STATE.md` (parent owns)
+- ...
+
+## Skills (in order — execute ALL in this invocation)
+
+1. **`design`** — REQUIRED if introducing a new package or non-trivial interface. Decisions to make: <list>.
+2. **`tdd`** — REQUIRED. Vertical slicing per AC; commit prefix `R<N>:`. Read [`tdd-rounds/COMMITS.md`](../COMMITS.md) before the first commit — it captures the per-AC slicing rule, the simplify-pass-gets-its-own-commit rule, the doc-commits-stay-separate rule, when single-commit is justified, and the message-body shape.
+3. **[`simplify`](../../simplify/SKILL.md)** — REQUIRED end-of-round. Walk every changed file with four lenses: reuse, quality, efficiency, test relevance. Land as its own commit (`R<N>: simplify — <summary>`).
+
+## Pre-flight reading (in order)
+
+1. `docs/STATE.md` — what previous rounds delivered.
+2. `docs/features/<feature>.md` — the AC contract.
+3. The ADRs cited above.
+4. <specific files the Builder needs to read before starting>
+
+## Concrete deliverables
+
+<per-AC or per-component, what the Builder must produce — function signatures, schema, etc.>
+
+## Success criteria
+
+- `make test` (or equivalent) exits 0. **All previously-ticked ACs remain green.**
+- `make lint` clean.
+- New tests cover: <specific behaviors>.
+- Per-AC commits prefixed `R<N>:`.
+- AC-XX1, AC-XX2, ... ticked in `docs/features/<feature>.md` with the test names.
+
+## Output (REQUIRED — paste verbatim shape from `templates/builder-report.md`)
+
+## Reminders
+
+- **Use the project's dev-environment commands** (e.g., Docker via `make`). Do not pollute the host.
+- **No `time.Sleep` in tests.**
+- **Don't `git push`.**
+- **Don't break existing tests.**
+- **Don't silently descope an AC.** If blocked, surface as a blocking open question and stop.

package/skills/tdd-rounds/templates/builder-report.md

@@ -0,0 +1,21 @@
+## Summary
+<one paragraph — what changed, why, what's now enforced>
+
+## ACs covered
+AC-XX1: <test name(s)> — green
+AC-XX2: <test name(s)> — green
+...
+
+## Files changed
+<path> — created|modified — <one-line purpose>
+<path> — created|modified — <one-line purpose>
+...
+
+## Test run
+<paste last 30 lines of the test command output>
+
+## Deviations
+<anything done that the brief did not explicitly authorize, with reason; or "none">
+
+## Open questions for parent
+<blocking | non-blocking, each with a concrete decision needed; or "none">

package/skills/verify-real-deps/MOTIVATION.md

@@ -0,0 +1,18 @@
+# Why verify-real-deps exists — a worked example
+
+A motivating example from a real session: a proxy for a third-party AI API shipped **25 / 25 acceptance criteria green**, lint clean, prod-ready clean. First end-to-end run against the live upstream surfaced **eight bugs** across four follow-up sessions:
+
+- Body shape was `{models: [...]}`; the real API takes `{project: "..."}`.
+- Tier enum had 3 values; the real API returns more.
+- Cache wasn't populated at credential-add time → first request returned 503.
+- Response body had `"models/X"` prefix; cache stored bare names → cache miss.
+- Non-streaming responses bypassed the SSE parser → all-zero token counts.
+- *(Three more in the same class — wire-shape mismatches the fake accepted but the upstream rejected.)*
+
+Every one of those passed unit + integration tests because the fake harness accepted whatever the code sent. None survived contact with the real API.
+
+## The lesson, generalized
+
+A fake server is a *hypothesis* about the contract; the real upstream **is** the contract. Until you run code against the real upstream at least once, every test that uses the fake is testing your hypothesis — not the contract.
+
+Whatever the domain — payments, AI inference, search, geolocation, telephony, OAuth — the same class of wire-shape bug exists. `verify-real-deps` is the discipline that finds it before users do.