@opengroundplan/core 0.1.1

package/registry/skills/spec-driven/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: spec-driven
+description: "Run a change through the spec → plan → tasks → implement loop under specs/NNN-slug/. Use when the user says spec, write a spec, plan this feature, break into tasks, /spec, /plan, /tasks, resume the spec, or when a change is large enough that jumping straight to code would guess at requirements. NOT for one-line fixes."
+metadata:
+  version: 1.0.0
+  category: workflow
+  updated: 2026-07-18
+---
+
+# Spec-Driven Development
+
+You are an expert at turning a fuzzy request into a reviewable spec, a technical plan, and an ordered task list — before a line of code is written. Your goal is that a reader who was not in the conversation can approve the work *and* a different agent can execute it.
+
+## Before Starting
+
+Read `AGENTS.md` first — it is the source of truth for stack, conventions, boundaries, and `commands.*`. Never restate or contradict it inside a spec.
+
+Then check state:
+- `specs/` — what numbers are taken, is there an unfinished spec dir?
+- `.agent/ACTIVE.md` — is a spec already in flight?
+- `docs/adr/` — has this decision already been made?
+
+Ask only for what those files do not answer: the user-visible outcome, the constraints, and what is explicitly out of scope.
+
+## How This Skill Works
+
+**Mode 1 — New spec.** Nothing exists. Create `specs/NNN-slug/spec.md` and stop at the gate.
+
+**Mode 2 — Advance a phase.** A spec dir exists at some phase. Read everything already in it, produce the *next* artifact only, stop at the next gate.
+
+**Mode 3 — Resume mid-loop.** The loop was interrupted. Reconstruct position from files on disk (below), never from memory of the conversation.
+
+## Directory and naming rules
+
+```
+specs/
+└── 042-payment-retry/
+    ├── spec.md      WHAT and WHY. No HOW.
+    ├── plan.md      HOW. Technical approach, trade-offs, affected modules.
+    └── tasks.md     Ordered, checkable, each task names its files.
+```
+
+- `NNN` — zero-padded to three digits, monotonically increasing, **never reused** even if a spec is abandoned. Highest existing number + 1.
+- `slug` — kebab-case, 2-4 words, describes the outcome not the mechanism. `payment-retry` beats `add-retry-wrapper-to-stripe-client`.
+- One spec = one shippable outcome. If `tasks.md` exceeds ~15 tasks or `spec.md` has two unrelated "so that" clauses, split into two specs.
+
+## The loop
+
+| Phase | Artifact | Contains | Never contains |
+|---|---|---|---|
+| 1 | `spec.md` | user-visible behavior, acceptance criteria, out-of-scope | file names, libraries, schemas |
+| 2 | `plan.md` | approach, affected modules, data/contract changes, risks | task ordering, checkboxes |
+| 3 | `tasks.md` | ordered checkable tasks, each naming its files | new requirements |
+| 4 | code | the change | anything not traceable to a task |
+
+Each phase ends at a **gate**: present the artifact, state what the next phase will do, and stop for explicit approval. Do not chain phases in one pass unless the user says so. See [references/phase-gates.md](references/phase-gates.md) for the gate checklists and the exact approval prompt.
+
+## What makes a spec reviewable
+
+A reviewer must be able to say "yes, that is what I want" without reading code.
+
+- Every requirement is **testable** — "responds within the declared latency budget" not "is fast".
+- Every requirement is **atomic** — one behavior per line, so a task can map to it.
+- Ambiguity is marked `[NEEDS CLARIFICATION: ...]` rather than guessed. A spec with open markers cannot pass its gate.
+- **Out of scope** is populated. An empty out-of-scope section means the boundary was never thought about.
+- No HOW. If a line names a library, a table, or a file path, it belongs in `plan.md`.
+
+## Resuming mid-loop
+
+Determine position from disk, in this order:
+
+1. `tasks.md` exists with unchecked boxes → you are implementing. Resume at the first unchecked task; re-read `plan.md` for context first.
+2. `plan.md` exists, no `tasks.md` → gate 2 was passed or is pending. Ask which, then produce tasks.
+3. `spec.md` only → gate 1. Check for open `[NEEDS CLARIFICATION]` markers before proposing a plan.
+4. Empty or missing dir → start fresh.
+
+Never re-derive an earlier artifact from a later one, and never silently edit `spec.md` while implementing. New requirements discovered during implementation go back through gate 1 — note them under **Discovered during implementation** in `spec.md` and re-request approval.
+
+## Feeding `.agent/ACTIVE.md`
+
+`ACTIVE.md` is the pointer to the current spec, not a copy of it. On entering a phase, set it to the spec id, the phase, and the next unchecked task — one short block, replaced (not appended) each time. When the last task is checked, clear `ACTIVE.md`, append the outcome to `.agent/DONE.md`, and append any decision that outlived the spec to `.agent/DECISIONS.md`. Anything a *different* tool needs to resume goes in `.agent/HANDOFF.md` — see the **handoff** skill.
+
+## Templates
+
+- [references/spec-template.md](references/spec-template.md) — fillable `spec.md`
+- [references/plan-template.md](references/plan-template.md) — fillable `plan.md`
+- [references/tasks-template.md](references/tasks-template.md) — fillable `tasks.md`
+- [references/phase-gates.md](references/phase-gates.md) — gate checklists, splitting rules, anti-patterns
+
+## Proactive Triggers
+
+Surface these without being asked:
+
+- **A request touches 3+ modules or changes a public contract** → propose a spec before writing code.
+- **`specs/NNN-*/tasks.md` has unchecked boxes and the user asks for something unrelated** → flag the abandoned spec and ask whether to resume, split, or close it.
+- **A spec line names a library, file, or schema** → move it to `plan.md`; the spec is leaking HOW.
+- **Implementation reveals a requirement the spec never stated** → stop, record it under Discovered during implementation, re-gate. Do not absorb it silently.
+- **Two specs modify the same file in the same period** → flag the collision before either merges.
+- **A decision inside `plan.md` will constrain future work** (framework, protocol, storage) → propose an ADR via the **adr-write** skill; `plan.md` is not a durable home for it.
+
+## Output Artifacts
+
+| When you ask for... | You get... |
+|---|---|
+| "Write a spec for X" | `specs/NNN-slug/spec.md` — testable requirements, acceptance criteria, out-of-scope, open clarifications listed |
+| "Plan it" | `specs/NNN-slug/plan.md` — approach, affected modules, contract/data changes, rejected alternatives, risks |
+| "Break it into tasks" | `specs/NNN-slug/tasks.md` — ordered checkable tasks, each naming its files and its verification step |
+| "Where did we leave off?" | Position report: spec id, phase, next unchecked task, blocking clarifications |
+| "Is this spec ready?" | Gate checklist result — PASS, or the specific lines that fail and why |
+
+## Communication
+
+Bottom line first: state the phase you finished and the gate you are stopped at. Every finding gets What + Why + How. Tag confidence: 🟢 verified from a file, 🟡 inferred, 🔴 assumed. Never narrate the process — present the artifact.
+
+## Related Skills
+
+- **test-first**: Use when executing a task from `tasks.md` — each task's verification step is a failing test. NOT for deciding *what* to build.
+- **adr-write**: Use when a `plan.md` decision constrains future changes. NOT for choices scoped to one spec.
+- **architecture-guard**: Use to check that `plan.md` respects declared boundaries before tasks are written. NOT for style review.
+- **handoff**: Use when a different tool or session must continue the spec. NOT for in-session state.
+- **onboard**: Use before the first spec in an unfamiliar repo. NOT once `AGENTS.md` is accurate.
+- **perf-budget**: Use when a spec's acceptance criteria include latency, bundle size, or vitals. NOT for correctness criteria.
+- **security-review**: Use on the diff after tasks are implemented. NOT during spec authoring.
+- Commands: `/spec` creates gate 1, `/plan` gate 2, `/tasks` gate 3, `/verify` checks the implemented result, `/handoff` writes the resume file.

package/registry/skills/spec-driven/references/phase-gates.md

@@ -0,0 +1,115 @@
+# Phase gates
+
+A gate is a stop. You produce one artifact, present it, and wait. Chaining phases in a single pass is how a wrong assumption in the spec becomes a day of wrong code.
+
+## The gate ritual
+
+At the end of every phase, output exactly this shape:
+
+```
+GATE <n> — <phase name>
+
+Artifact: specs/NNN-slug/<file>
+Summary: <2-3 lines of what it says>
+Open items: <clarifications / assumptions, or "none">
+Next phase will: <one line>
+
+Proceed? (yes / revise / cancel)
+```
+
+Then stop. No "I'll go ahead and also...". Revise means loop on the same artifact; it does not advance the phase.
+
+---
+
+## Gate 1 — spec.md approved
+
+Blocking checklist. Any NO stops the gate.
+
+- [ ] Problem is stated without solution language
+- [ ] Every requirement is atomic — one behavior per line
+- [ ] Every requirement is testable from outside the system
+- [ ] Every requirement has a matching acceptance criterion in Given/When/Then form
+- [ ] Out of scope is non-empty
+- [ ] Zero open `[NEEDS CLARIFICATION]` markers
+- [ ] No file paths, library names, schemas, or signatures anywhere in the file
+- [ ] Non-functional criteria each name a measurement source (or are absent)
+- [ ] The spec would still make sense to someone who joins in six months
+
+**Common failure:** the spec names the solution in the title. `Add Redis cache for user lookups` is a plan. `User profile loads without a round-trip to the primary store` is a spec.
+
+---
+
+## Gate 2 — plan.md approved
+
+- [ ] Every plan item traces to a requirement id
+- [ ] Affected modules table is complete — nothing gets touched that is not listed
+- [ ] Declared boundaries from `AGENTS.md` (`boundaries[]`) were read and the plan states which it crosses
+- [ ] `protectedPaths[]` are not in the affected list, or explicit approval is recorded
+- [ ] Contract / schema / config changes are stated, or explicitly "none"
+- [ ] At least one rejected alternative, with a reason
+- [ ] Risk table has at least one non-low entry, with a mitigation
+- [ ] Rollback step is concrete
+- [ ] New config values have a typed default in one place — no literals at call sites
+- [ ] ADR candidates are identified
+
+**Common failure:** the plan is a restatement of the spec in engineering nouns. If a reviewer cannot disagree with it, it is not a plan.
+
+---
+
+## Gate 3 — tasks.md approved
+
+- [ ] Tasks are ordered, and dependencies are stated
+- [ ] Every task names its files
+- [ ] Every task names its verification
+- [ ] Every task traces to a requirement
+- [ ] No task introduces behavior the spec does not require
+- [ ] Contract/schema/config tasks come before their dependents
+- [ ] `AGENTS.md` update task exists (even if the answer is "no change")
+- [ ] Close-out tasks exist for `.agent/` files
+- [ ] Task count is under ~15, or the spec is split
+
+**Common failure:** tasks that read `Implement the plan`. If a task's Do line is longer than three lines, it is two tasks.
+
+---
+
+## Gate 4 — implementation complete
+
+- [ ] Every box in `tasks.md` is checked, and each was checked because its Verify passed
+- [ ] Full verification green using the declared `commands.*`
+- [ ] No boundary violations introduced
+- [ ] No declared budget regressed
+- [ ] Diff reviewed for security findings if it touches input handling, auth, or dependencies
+- [ ] Discovered-during-implementation entries were each re-gated, not absorbed
+- [ ] `.agent/` files reconciled; stale `HANDOFF.md` deleted
+
+---
+
+## Passing a gate without a human
+
+Only when the user has explicitly said "run the whole loop" or equivalent. Even then:
+
+- Still emit each gate block, so the trail exists.
+- Still hard-stop on any open `[NEEDS CLARIFICATION]`.
+- Still hard-stop on a `protectedPaths[]` collision.
+- Still hard-stop on a boundary violation.
+
+Autonomy speeds up phases; it never removes those four stops.
+
+## Backward movement
+
+Going back a phase is normal and cheap. Going forward with a known gap is expensive.
+
+| Discovery | Go back to |
+|---|---|
+| A requirement is wrong or missing | Gate 1 — amend spec, re-approve |
+| The approach cannot satisfy a requirement | Gate 2 — new alternative, note the rejected one |
+| A task is impossible as written | Gate 3 — strike and replace the task with a reason |
+| A boundary must move to make this work | Stop. That is an ADR (adr-write), not a task. |
+
+## Anti-patterns
+
+- **Gate theater** — printing the block and immediately continuing. The stop is the feature.
+- **Spec drift** — editing `spec.md` mid-implementation so the code matches. Use Discovered during implementation instead.
+- **Plan-as-tasks** — a `plan.md` full of checkboxes. Then gate 3 has nothing to review.
+- **Number reuse** — recycling `NNN` from an abandoned spec. Links and logs then point at the wrong work.
+- **The 40-task spec** — a spec that never ships. Split at the first shippable outcome.

package/registry/skills/spec-driven/references/plan-template.md

@@ -0,0 +1,98 @@
+# plan.md template
+
+Copy into `specs/NNN-slug/plan.md`. This is the HOW. It exists so a reviewer can reject the approach before anyone spends a day on it.
+
+**Rule:** every section here must trace back to a requirement in `spec.md`. If an item traces to nothing, it is scope creep — remove it or amend the spec through its gate.
+
+---
+
+```markdown
+# NNN — Plan
+
+- **Spec:** `./spec.md`
+- **Status:** draft | approved
+- **Approach chosen:** <one sentence>
+
+## Constraints read from AGENTS.md
+
+Restate nothing; cite what applies and why it shapes the approach.
+
+| Source | Value that constrains this plan |
+|---|---|
+| `conventions[]` | <the entries that matter here> |
+| `boundaries[]` | <the declared boundaries this change crosses or must not cross> |
+| `protectedPaths[]` | <paths this change must not touch> |
+| `commands.*` | <the build/test/lint commands tasks will run — by name, not literal> |
+
+## Approach
+
+<3-8 sentences. The shape of the solution: what gets added, what gets changed,
+what gets deleted. A reader should be able to picture the resulting code.>
+
+## Affected modules
+
+| Module / area | Change | Requirement | Risk |
+|---|---|---|---|
+| <module> | add / modify / delete | R1 | low / med / high |
+
+Anything not listed here should not appear in a task.
+
+## Contract and data changes
+
+Fill in or write "none".
+
+- **Public API / interface changes:** <signature-level description, and whether it is breaking>
+- **Schema / storage changes:** <shape change, and whether a migration is needed>
+- **Config surface:** <new settings, their typed defaults, and where the single default lives>
+- **Events / messages:** <new or changed payloads, and consumers affected>
+
+Backward compatibility: <how existing callers/rows/messages keep working, or why a break is acceptable and who signs off>
+
+## Alternatives rejected
+
+The most useful section in this file. One line each on what and why not.
+
+| Alternative | Why rejected |
+|---|---|
+| <the obvious option> | <the specific reason — cost, boundary violation, ops burden> |
+| <do nothing> | <what happens if we ship nothing> |
+
+## Risks and mitigations
+
+| Risk | Likelihood | Blast radius | Mitigation |
+|---|---|---|---|
+| <what could go wrong> | low/med/high | <what breaks if it does> | <the guard: flag, migration order, rollback> |
+
+## Verification strategy
+
+How we will know it works, beyond "tests pass".
+
+- **Behavior under test:** <the behaviors that get tests, per test-first>
+- **Manual / exploratory check:** <what a human must eyeball, if anything>
+- **Budgets touched:** <declared budget names this change must not regress>
+- **Rollback:** <the concrete step to undo this in production>
+
+## Decisions that outlive this spec
+
+Anything here is an ADR candidate — a choice that constrains future changes.
+
+- <decision> → <ADR needed? yes/no, and why>
+
+## Sequencing notes for tasks.md
+
+Ordering constraints only — not the task list itself.
+
+- <X must land before Y because ...>
+- <Z is independently shippable and can be parallelized>
+```
+
+---
+
+## Plan review heuristics
+
+- **No alternatives rejected** → the approach was not chosen, it was defaulted into.
+- **No contract changes and no schema changes and the spec has three requirements** → the plan is probably underspecified.
+- **A module appears in the plan that no requirement needs** → scope creep.
+- **"We'll figure it out during implementation"** → that is an open question; send it back to the spec gate.
+- **Risk table with all "low"** → nobody looked. There is always one medium.
+- **Migration mentioned with no ordering note** → sequencing bug waiting to happen.

package/registry/skills/spec-driven/references/spec-template.md

@@ -0,0 +1,101 @@
+# spec.md template
+
+Copy into `specs/NNN-slug/spec.md`. Replace every `<...>`. Delete a section only if you can say why it does not apply — do not leave it empty.
+
+**Rule: WHAT and WHY only.** No file paths, library names, table names, or function signatures. If you catch yourself writing one, it belongs in `plan.md`.
+
+---
+
+```markdown
+# NNN — <Outcome in 2-6 words>
+
+- **Status:** draft | approved | implementing | shipped
+- **Created:** <YYYY-MM-DD>
+- **Owner:** <who approves this>
+
+## Problem
+
+<2-4 sentences. What is broken or missing today, and for whom. Written so someone
+outside the team understands it. No solution language.>
+
+## Why now
+
+<What forces the change: a user complaint, a compliance date, a cost, a blocked
+roadmap item. If the honest answer is "it would be nice", say so — that is a valid
+answer that changes the priority.>
+
+## Users and scenarios
+
+| Actor | Scenario | Today | After this change |
+|---|---|---|---|
+| <role> | <what they are trying to do> | <what happens now> | <what happens then> |
+
+## Requirements
+
+Each line is atomic, testable, and observable from outside the system.
+
+- **R1** — <The system MUST ...>
+- **R2** — <The system MUST ...>
+- **R3** — <When <condition>, the system MUST <observable behavior>>
+
+## Acceptance criteria
+
+One per requirement, phrased so a test can be written from it without further questions.
+
+- **AC1 (R1)** — Given <state>, when <action>, then <observable result>.
+- **AC2 (R2)** — Given <state>, when <action>, then <observable result>.
+- **AC3 (R3)** — Given <error condition>, when <action>, then <observable failure mode>.
+
+## Non-functional criteria
+
+Only ones this change is accountable for. Each must name its measurement source, or drop it.
+
+| Criterion | Target | Measured by |
+|---|---|---|
+| <latency / bundle size / vitals> | <declared budget name, not a literal number> | <where the number comes from> |
+
+## Out of scope
+
+Explicitly NOT part of this spec. An empty list means the boundary was never considered.
+
+- <thing a reader would reasonably assume is included, but is not>
+- <adjacent improvement deliberately deferred>
+
+## Open questions
+
+Blocking. This spec cannot pass its gate while any remain.
+
+- **[NEEDS CLARIFICATION: <question>]** — blocks <R#>. Default if unanswered: <fallback>.
+
+## Discovered during implementation
+
+Append-only. Anything found after approval that changes scope. Each entry re-opens the gate.
+
+- <YYYY-MM-DD> — <what was discovered> → <re-approved | deferred to spec NNN | dropped>
+
+## Links
+
+- Plan: `./plan.md`
+- Tasks: `./tasks.md`
+- ADRs: <docs/adr/NNNN-... if a decision here earned one>
+```
+
+---
+
+## Requirement phrasing
+
+| Bad | Why | Better |
+|---|---|---|
+| The API should be fast | untestable | Responds within the declared p95 latency budget for read endpoints |
+| Handle errors gracefully | unobservable | On upstream timeout, returns a typed error and the request is not retried more than the declared retry limit |
+| Refactor the payment module | HOW, not WHAT | Payment failures are retried without double-charging the customer |
+| Users can manage their settings | not atomic | Split: users can view settings; users can change notification preference; changes take effect without re-login |
+
+## Sizing check
+
+Split the spec if any of these are true:
+
+- Two requirements have unrelated "so that" clauses.
+- Removing one requirement would still leave a shippable outcome.
+- The task list would exceed ~15 items.
+- Two different reviewers own different requirements.

package/registry/skills/spec-driven/references/tasks-template.md

@@ -0,0 +1,96 @@
+# tasks.md template
+
+Copy into `specs/NNN-slug/tasks.md`. This is the execution list. A different agent, with no memory of the conversation, must be able to pick up the first unchecked box and make progress.
+
+**Rules**
+- Every task names the **files** it touches.
+- Every task names its **verification** — how you know it is done.
+- Every task traces to a requirement (`R#`) from `spec.md`.
+- Tasks are ordered. If two are independent, mark them `[parallel]`.
+- No task introduces a requirement. New requirements go back through the spec gate.
+- A task should be completable without re-reading the whole plan. If it can't, split it.
+
+---
+
+```markdown
+# NNN — Tasks
+
+- **Spec:** `./spec.md` · **Plan:** `./plan.md`
+- **Progress:** 0 / <N>
+
+## Preconditions
+
+- [ ] `plan.md` approved at gate 2
+- [ ] Working tree clean, or uncommitted work recorded in `.agent/HANDOFF.md`
+- [ ] Baseline verification green using the `commands.*` entries declared in AGENTS.md
+
+## Tasks
+
+- [ ] **T1 — <imperative, one outcome>** (R1)
+  - Files: `<path/to/file>`, `<path/to/other>`
+  - Do: <the change, one or two lines>
+  - Verify: <failing test name that must go green, or the command class to run>
+
+- [ ] **T2 — <...>** (R1)
+  - Files: `<path>`
+  - Do: <...>
+  - Verify: <...>
+  - Depends on: T1
+
+- [ ] **T3 — <...>** (R2) `[parallel with T2]`
+  - Files: `<path>`
+  - Do: <...>
+  - Verify: <...>
+
+- [ ] **T4 — Wire config** (R3)
+  - Files: `<config module>`, `<call site>`
+  - Do: add the setting with its typed default in the single config location; call site reads it
+  - Verify: no literal value remains at the call site; default resolves when the env var is absent
+
+- [ ] **T5 — Update AGENTS.md**
+  - Files: `AGENTS.md`
+  - Do: record the new convention / boundary / command if this change introduced one; otherwise check and note "no change"
+  - Verify: AGENTS.md describes the repo as it now is
+
+## Verification gate
+
+- [ ] All boxes above checked
+- [ ] Full verification suite green via the declared `commands.*`
+- [ ] No declared boundary crossed (architecture-guard)
+- [ ] No budget regressed (perf-budget), if the spec declared one
+- [ ] Diff reviewed for security findings (security-review), if the change touches input, auth, or dependencies
+
+## Close-out
+
+- [ ] `spec.md` status → shipped
+- [ ] `.agent/DONE.md` appended with the outcome
+- [ ] `.agent/DECISIONS.md` appended, if a decision here outlives the spec
+- [ ] `.agent/ACTIVE.md` cleared
+- [ ] `.agent/HANDOFF.md` deleted if the work is complete — a stale handoff is worse than none
+```
+
+---
+
+## Task granularity
+
+| Too big | Right size | Too small |
+|---|---|---|
+| Implement retry logic | Add retry wrapper around the upstream call, capped at the declared retry limit | Import the retry module |
+| Fix the auth flow | Reject expired tokens at the middleware boundary and return the typed 401 | Rename a variable |
+
+Rule of thumb: one task = one coherent commit = one failing test going green.
+
+## Ordering rules
+
+1. Contract and schema changes before the code that depends on them.
+2. Config plumbing before the first call site that reads it.
+3. Anything with a migration before anything that reads the migrated shape.
+4. Tests before implementation *within* a task, not as separate tasks — see the **test-first** skill.
+5. Docs (`AGENTS.md`, ADR) last, so they describe what actually landed.
+
+## Progress discipline
+
+- Check a box only when its **Verify** line passes — not when the code is written.
+- If a task turns out to be wrong, do not silently rewrite it. Strike it, add the replacement, and note why:
+  `- [x] ~~T3 — old approach~~ → replaced by T3a; upstream API does not expose the field.`
+- Update the `Progress:` counter and `.agent/ACTIVE.md` as you go, so an interrupted session resumes from disk.

package/registry/skills/spec-driven/skill.yaml

@@ -0,0 +1,7 @@
+id: spec-driven
+kind: skill
+name: Spec-Driven Development
+description: Drive a change through spec → plan → tasks → implement over specs/NNN-slug/, with a review gate between each phase.
+tags: [workflow, specs, planning, tasks]
+targets: [claude-code, cursor, github-copilot, windsurf, cline, codex, gemini-cli, agents-md]
+requiresCapability: [instructions]

package/registry/skills/test-first/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: test-first
+description: "Drive a change through the TDD red → green → refactor loop. Use when the user says TDD, test first, write a failing test, write tests for this, improve coverage, is this tested — or when implementing a task from tasks.md. Targets behavior coverage and mutation resistance, not a coverage number. NOT for reviewing an existing diff."
+metadata:
+  version: 1.0.0
+  category: testing
+  updated: 2026-07-18
+---
+
+# Test-First Development
+
+You are an expert at using tests as a design tool, not a compliance exercise. Your goal is code whose behavior is pinned by tests that would actually fail if the behavior broke.
+
+## Before Starting
+
+Read `AGENTS.md` for the declared test command (`commands.test`) and any testing conventions. Then look at 2-3 existing tests in the area you are changing — the repo's real conventions live there, not in its docs. Match the existing naming, structure, and fixture style unless it is actively bad, and say so if it is.
+
+If a spec is in flight, the acceptance criteria in `specs/NNN-slug/spec.md` are your test list. Each `AC` should become at least one test.
+
+## How This Skill Works
+
+**Mode 1 — Drive new behavior.** The loop below, one behavior at a time.
+
+**Mode 2 — Characterize existing code.** No tests, and the code must change. Write tests that pin *current* behavior first — including behavior that looks wrong. Then change with a safety net. Do not "fix" anything while characterizing.
+
+**Mode 3 — Strengthen a weak suite.** Tests exist and pass, but you do not trust them. Probe with mutations (below) and rewrite the tests that survive.
+
+## The loop
+
+**RED — write the failing test.**
+
+- One behavior. Name it after the behavior, not the method: `rejects_expired_token`, not `test_validate`.
+- **Run it and watch it fail.** A test never observed failing is not known to test anything.
+- Check the failure message. If it does not tell you what went wrong, fix the assertion now — you will read it under pressure later.
+- Assert on observable outcomes: return values, raised errors, persisted state, emitted messages. Not on internal call sequences.
+
+**GREEN — the minimum that passes.**
+
+- Write the least code that makes it pass. Yes, that sometimes means a hardcoded return — the next test removes it.
+- Do not add error handling, logging, or generality the current tests do not demand. Untested speculative code is where bugs hide.
+- Run the full declared test command, not just the new test. Green means everything green.
+
+**REFACTOR — under green.**
+
+- Now improve names, structure, and duplication. Tests must stay green the whole time.
+- Refactor the tests too — duplicated setup, unclear names, oversized fixtures.
+- **Never change behavior here.** If you need to, that is a new RED.
+
+Then repeat. Small loops. If a loop is taking long, the step was too big — revert to green and take a smaller bite.
+
+## Coverage is a trap
+
+**Do not target a coverage percentage.** A hard threshold is a Goodhart's-Law failure: the moment the number becomes the goal, it stops measuring quality. 100% line coverage is trivially achievable with tests that contain no assertions at all — they execute every line and verify nothing. Teams under a threshold reliably produce exactly those tests, and the number reports a well-tested system that would not notice if the logic were deleted.
+
+Target these instead:
+
+| Target | Question it answers |
+|---|---|
+| **Behavior coverage** | Does every acceptance criterion have a test that fails when it breaks? |
+| **Mutation resistance** | If I change a `>` to `>=`, delete a line, or invert a condition — does a test fail? |
+| **Failure-mode coverage** | Are the error paths tested, not just the happy path? |
+| **Boundary coverage** | Empty, one, many, max, null, malformed, concurrent? |
+
+Use coverage as a **detector, not a target**: uncovered lines are worth a look, high coverage proves nothing. If the repo declares a coverage gate, treat it as a floor to satisfy and never as evidence of quality. Full argument and the mutation-probe technique in [references/test-design.md](references/test-design.md).
+
+## When the test is hard to write
+
+This is the most valuable signal TDD gives you. **It is a design problem, not a testing problem.** Do not reach for heavier mocking — fix the design.
+
+| Symptom | Design smell | Fix |
+|---|---|---|
+| Setup needs 10 lines before you can assert | too many collaborators | split responsibilities |
+| You must mock a static, a clock, or a global | hidden dependency | inject it |
+| The test needs real network, disk, or time | no seam at the boundary | put the side effect behind a port |
+| Asserting requires reaching into internals | wrong public surface, or the logic is in the wrong place | move the behavior or widen the surface deliberately |
+| The test needs the whole app booted | logic tangled with the framework | extract the decision from the plumbing |
+| You cannot name the test without "and" | the unit does two things | split it |
+
+If the fix crosses an architectural boundary, stop and route to **architecture-guard** — a hard-to-test seam is frequently a misplaced boundary.
+
+## What to test, and at which level
+
+- **Test behavior, not implementation.** A test that breaks on every refactor is a liability. If the observable outcome is unchanged, the test should stay green.
+- **One reason to fail per test.** Multiple unrelated assertions make failures ambiguous.
+- **Prefer the lowest level that can express the behavior**, but do not push an integration concern into a unit test with five mocks — that tests the mocks.
+- **Do not test the framework, the language, or third-party libraries.** Test *your* use of them at the boundary.
+- **Test the error paths.** Most production incidents live on paths nobody wrote a test for.
+- **Don't-test list:** generated code, pure configuration, trivial accessors, and anything whose test would be a restatement of the implementation.
+
+Anti-patterns catalog — assertion-free tests, mock theater, snapshot rot, flaky-test tolerance and the rest — in [references/anti-patterns.md](references/anti-patterns.md).
+
+## Proactive Triggers
+
+- **A test was never observed failing** → flag it; it may pass for the wrong reason.
+- **A test has no assertion, or asserts only "did not throw"** → flag it; it inflates coverage and verifies nothing.
+- **Setup is longer than the assertion by 3× or more** → flag the design smell before writing more tests around it.
+- **A bug is being fixed with no reproducing test** → stop; write the failing test first, or the bug returns with nothing to catch it.
+- **A test asserts on mock call order rather than an outcome** → flag it; it will break on the next refactor and catch nothing.
+- **The team is chasing a coverage number** → say plainly what the number does and does not measure, and propose mutation probing instead.
+- **A test is skipped, quarantined, or retried on failure** → flag it; a tolerated flaky test trains everyone to ignore red.
+
+## Output Artifacts
+
+| When you ask for... | You get... |
+|---|---|
+| "Implement X test-first" | Failing test → minimal implementation → refactor, with the red observed at each step |
+| "Write tests for this code" | Behavior-pinned tests grouped by outcome, including error paths and boundaries |
+| "Is this well tested?" | Mutation-probe report — which mutations survive, which behaviors are unpinned |
+| "This is hard to test" | The design smell named, plus the specific refactor that removes it |
+| "Fix this bug" | Reproducing failing test first, then the fix, then the refactor |
+
+## Communication
+
+Bottom line first: what behavior is now pinned, and what is still unpinned. Tag confidence: 🟢 test observed failing then passing, 🟡 test passes but was never seen red, 🔴 behavior asserted without a test. Never report coverage as a quality claim — report which behaviors are pinned.
+
+## Related Skills
+
+- **spec-driven**: Use for the behaviors worth testing — each acceptance criterion becomes a test. NOT for how to write them.
+- **architecture-guard**: Use when a hard-to-test seam turns out to be a boundary problem. NOT for test quality itself.
+- **security-review**: Use for threat-driven cases — malformed input, authz bypass, injection payloads — which belong in the suite as tests.
+- **perf-budget**: Use for performance assertions; those are budget checks against a measurement source, not unit tests.
+- **onboard**: Use to discover where tests live and how they run in an unfamiliar repo. NOT once conventions are known.
+- **handoff**: Use when pausing mid-loop — a named failing test is the clearest possible "next action".
+- **adr-write**: Use when a testing strategy decision constrains future work (e.g. no mocks at the boundary, contract tests between modules).
+- Commands: `/verify` runs the declared suite, `/tasks` produces the task whose verification step is the failing test, `/review` checks the resulting diff, `/handoff` records the current red test.