gsd-pi 2.75.0 → 2.76.0-dev.b072ebb73

package/src/resources/skills/security-review/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: security-review
+description: Threat-model-driven security review of a change, feature, or subsystem. Runs a STRIDE-style pass (Spoofing, Tampering, Repudiation, Info disclosure, Denial of service, Elevation of privilege), examines the actual code, and produces a filing-ready report with severity, exploit scenario, and concrete remediation. Use when asked to "security review", "threat model", "check for vulnerabilities", "audit this for security", "secure this", or before shipping any change that touches auth, input handling, data access, or external surfaces.
+---
+
+<objective>
+Produce a security review that names specific exploit paths through the actual code — not a generic checklist. The deliverable is a prioritized list of findings, each with: where the issue lives, the threat category, a concrete exploit scenario, severity, and a remediation the caller can implement. Read-only: does not modify code.
+</objective>
+
+<context>
+GSD-2's general `review` skill covers security as one of several categories. This skill is the deeper pass — triggered deliberately when security is the primary concern. It complements v1's `/gsd-secure-phase` concept, adapted to the gsd-2 artifact model.
+
+Invocation points:
+- Any change touching authentication, authorization, session handling
+- Any change touching user input → database, filesystem, or shell
+- Any change exposing a new external surface (HTTP endpoint, webhook, IPC boundary)
+- Secrets handling, environment variable changes, crypto code
+- Pre-release audit of a feature or milestone
+- Response to a suspected vulnerability
+
+Do NOT use for:
+- General code review (use `review`)
+- Performance audits (use `code-optimizer`)
+</context>
+
+<core_principle>
+**CODE BEFORE CHECKLISTS.** A threat model that doesn't read the code is theater. Find the actual input source, the actual validation (or absence), the actual sink. Cite file:line for every finding.
+
+**THREAT, NOT HYPOTHETICAL.** "SQL injection is possible in theory" is useless. "If an attacker passes `' OR 1=1--` to `getUser(name)` at `src/db/users.ts:42`, the query becomes `SELECT … WHERE name='' OR 1=1--'`, returning every row" is actionable.
+
+**READ-ONLY.** Don't patch while reviewing — you conflate reviewer and author and lose the audit trail. Report, let the user act.
+</core_principle>
+
+<process>
+
+## Step 1: Scope the review
+
+Identify what to review:
+- Recent diff (staged / branch / specific commit)
+- A named subsystem (`src/auth/`, the webhook handler, etc.)
+- A user-provided concern ("I'm worried about our JWT handling")
+
+If the scope is vague, ask one round of clarifying questions (1–3 questions). Otherwise proceed.
+
+## Step 2: Map the attack surface
+
+Before STRIDE: identify every untrusted entry point in the scope:
+
+- HTTP routes / GraphQL resolvers / RPC endpoints
+- CLI flag parsing and argv consumption
+- Webhook handlers, event subscribers
+- Environment variables read at runtime
+- Files read from untrusted locations
+- Third-party library deserialization (YAML, XML, pickle, etc.)
+- IPC boundaries, child processes
+
+For each, note: who can reach this surface? (public internet, authenticated user, same-host process, admin-only).
+
+## Step 3: STRIDE pass
+
+For each attack surface, walk STRIDE:
+
+### Spoofing (identity)
+- Can an attacker pretend to be another user?
+- Are identity tokens verified before they're trusted?
+- Session cookies: HttpOnly, Secure, SameSite set?
+
+### Tampering (integrity)
+- Can an attacker modify data in transit or at rest?
+- Are webhooks signed and signatures verified?
+- Are incoming payloads rehydrated without integrity checks?
+
+### Repudiation (audit trail)
+- Is there a log of who did what?
+- Can an attacker erase their trail?
+- Are logs tamper-evident where it matters?
+
+### Information disclosure
+- Does an error message leak internal state, stack traces, file paths, DB queries?
+- Are secrets logged anywhere?
+- Are authorization checks upstream of data loading, or does the query run first?
+
+### Denial of service
+- Are there unbounded loops, unpaginated queries, or user-controlled recursion?
+- Rate limits on expensive endpoints?
+- Regex-on-user-input vulnerable to ReDoS?
+
+### Elevation of privilege
+- Are admin-only routes actually gated?
+- Can a low-privilege user trigger a high-privilege operation through an unauthenticated webhook?
+- Are role checks enforced at the handler, the service, and the data layer — or just one?
+
+Use `Agent(subagent_type=Explore)` in parallel if the scope is large — one sub-agent per STRIDE category over the same surface list.
+
+## Step 4: OWASP cross-check (web scope)
+
+If the scope includes web surfaces, confirm against the top OWASP patterns that STRIDE doesn't cleanly cover:
+
+- Injection (SQL, NoSQL, command, template, LDAP)
+- XSS (stored, reflected, DOM)
+- SSRF (server makes requests to attacker-controlled URLs)
+- Insecure deserialization
+- Path traversal
+- Open redirects
+- Broken access control at object level (IDOR)
+- CSRF where cookies are used for auth
+
+For each present, find the code path. Same standard: cite file:line.
+
+## Step 5: Triage
+
+For each finding, assign:
+
+- **Severity:** Critical / High / Medium / Low / Informational
+- **Exploitability:** Remote unauthenticated / authenticated user / adjacent user / admin-only / local-only
+- **Business impact:** Data breach / account takeover / service disruption / audit failure / minor
+
+Severity × Exploitability = priority. Sort findings by priority.
+
+## Step 6: Write the report
+
+```markdown
+## Security Review — <scope>
+
+### Summary
+
+<1–3 sentences — biggest finding and overall posture>
+
+### Findings
+
+#### CRITICAL-1: SQL injection in `getUser`
+
+**Location:** `src/db/users.ts:42`
+**Category:** Tampering / Info disclosure (STRIDE) + OWASP A03 Injection
+**Exploit:** Passing `' OR 1=1--` to the `name` parameter produces the query `SELECT * FROM users WHERE name='' OR 1=1--'`, returning every row. `name` arrives from `POST /api/search` without validation.
+**Reachability:** Remote unauthenticated (endpoint has no auth).
+**Remediation:** Use a parameterized query. The codebase's `db.prepare` helper at `src/db/util.ts:17` handles this — switch `getUser` to it.
+
+#### HIGH-2: ...
+
+### Non-findings considered
+
+<brief: what you checked and ruled out — prevents repeat reviews>
+
+### Out of scope
+
+<what wasn't reviewed>
+```
+
+Offer to file as a GitHub issue — requires explicit confirmation per the outward-action rule. Sensitive findings should stay in `.gsd/security-reviews/` and not be pushed to a public tracker; check the repository's security policy first.
+
+## Step 7: Follow-ups
+
+If the review found CRITICAL or HIGH issues:
+- Recommend filing a private security advisory (not a public issue) if the repo is public.
+- Flag the finding for `/gsd start hotfix` if it's in the scope of active work.
+- Append one line to `.gsd/DECISIONS.md` if the remediation involves an architectural change.
+
+</process>
+
+<anti_patterns>
+
+- **Generic checklists.** "Does it validate input?" yes/no without pointing at the code is not a review.
+- **Hypothetical exploits without code.** If you can't name the path, the finding isn't real yet.
+- **Modifying code during review.** Reviewer and author must stay separate.
+- **Treating every theoretical issue as CRITICAL.** Severity requires exploitability.
+- **Skipping reachability.** A "critical" behind admin-only auth is usually not critical.
+- **Filing sensitive findings publicly.** Check the repo's security policy first.
+
+</anti_patterns>
+
+<success_criteria>
+
+- [ ] Every finding cites a file:line.
+- [ ] Every finding has a concrete exploit scenario, not just a category.
+- [ ] Severity, exploitability, and business impact are stated.
+- [ ] At least one non-finding is listed (shows what was ruled out).
+- [ ] No code was modified during the review.
+- [ ] Critical findings are routed through an appropriate disclosure channel, not auto-filed publicly.
+
+</success_criteria>

package/src/resources/skills/spike-wrap-up/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: spike-wrap-up
+description: Package findings from a completed spike into a durable, project-local skill that auto-loads on future similar work. Reads the most recent `.gsd/workflows/spikes/` directory, interviews the user briefly on what's reusable, then writes `.claude/skills/<name>/SKILL.md`. Use when asked to "wrap up the spike", "package this as a skill", "make this reusable", "turn findings into a skill", or at the end of the synthesize phase of `/gsd start spike`. Closes the parity gap with GSD v1's `/gsd-spike-wrap-up`.
+---
+
+<objective>
+Convert the output of a research spike (`SCOPE.md`, `research/*.md`, `RECOMMENDATION.md`) into a project-local skill under `.claude/skills/` so that the next time a similar task comes up, the agent loads the skill automatically. This is how throwaway spikes become durable capital.
+</objective>
+
+<context>
+GSD's spike workflow (`src/resources/extensions/gsd/workflow-templates/spike.md`) produces documents in `.gsd/workflows/spikes/<slug>/`. Those documents are useful once and then forgotten unless something packages them for reuse.
+
+GSD already watches `.claude/skills/` (and `.agents/skills/`) at both user and project levels — see `src/resources/extensions/gsd/skill-discovery.ts`. Any skill written there is picked up on the next session without further wiring. This skill is the bridge from "spike done" to "skill available."
+
+Invocation points:
+- End of Phase 3 (synthesize) in `/gsd start spike` — prompt suggests running this skill
+- User has a spike directory and wants to harvest it
+- Pre-existing `RECOMMENDATION.md` that deserves a permanent home
+</context>
+
+<core_principle>
+**NOT EVERY SPIKE DESERVES A SKILL.** If the recommendation was "don't do X," there may be no reusable guidance. Ask the user first; exit without writing if the answer is no.
+
+**PROJECT-LOCAL, NOT USER-GLOBAL.** Write to `.claude/skills/` in the repo, not `~/.claude/skills/`. The skill encodes project-specific choices that should not leak into unrelated projects.
+
+**DESCRIPTION IS THE DISCOVERABILITY SIGNAL.** The `description` field in frontmatter is the primary signal the agent uses to judge relevance and decide whether to load the skill — it is a heuristic, not a deterministic trigger. Write it as keywords the future agent will plausibly encounter, not a summary.
+</core_principle>
+
+<process>
+
+## Step 1: Find the spike
+
+1. List directories under `.gsd/workflows/spikes/` — sort by mtime, newest first.
+2. If multiple exist, ask the user which to wrap up. Default: the most recent.
+3. If none exist, tell the user and stop. This skill requires a completed spike.
+
+Read the core files:
+- `<spike>/SCOPE.md` — the question that was asked
+- `<spike>/research/*.md` — the angles investigated
+- `<spike>/RECOMMENDATION.md` — the conclusion
+
+## Step 2: Decide if it deserves a skill
+
+Ask the user — one round:
+
+1. **Is the conclusion reusable on future work, or was it specific to one decision?**
+   Recommendation: packaging is worth it if the findings include repeatable guidance (how to evaluate X, a pattern to follow, a library's gotchas). If the spike ended in "we chose library Y, end of story," it probably belongs in `.gsd/DECISIONS.md` instead.
+
+2. **What is the trigger?** When should a future agent load this skill? Give concrete keywords — "adding a new webhook handler", "writing a SQL migration", etc.
+
+If the user says it's not worth packaging, offer instead to append a summary to `.gsd/DECISIONS.md` and stop.
+
+## Step 3: Design the skill
+
+Before writing, sketch in the conversation:
+
+- **Name:** kebab-case, short, unambiguous. Prefix with the project's domain when helpful (`auth-webhook-setup`, not `webhook`).
+- **Description (frontmatter):** one sentence, 120–1024 chars, keyword-rich. Must state when the agent should load it. Rewrite at least twice before settling.
+- **Objective:** one paragraph — what the skill does and what artifact it produces.
+- **Process:** numbered steps. Reference the spike's findings as the source, but the skill itself should be executable without reading the spike.
+- **Anti-patterns:** gotchas the spike surfaced — things that looked right but didn't work.
+- **Success criteria:** checklist the skill's user can confirm against.
+
+Show this sketch to the user. One round of feedback. Iterate.
+
+## Step 4: Write the skill
+
+Write to `.claude/skills/<name>/SKILL.md` (create the directory). Match the frontmatter + XML-tag structure used by other bundled skills — see `src/resources/skills/review/SKILL.md` for the canonical shape.
+
+Minimum structure:
+
+```markdown
+---
+name: <skill-name>
+description: <one sentence with trigger keywords>
+---
+
+<objective>
+<one paragraph — what this skill does>
+</objective>
+
+<context>
+<when to invoke, what produced it (cite the spike), assumptions>
+</context>
+
+<process>
+## Step 1: <action>
+<instructions>
+
+## Step 2: <action>
+<instructions>
+</process>
+
+<anti_patterns>
+- <gotcha from the spike>
+- <another gotcha>
+</anti_patterns>
+
+<success_criteria>
+- [ ] <observable confirmation>
+- [ ] <observable confirmation>
+</success_criteria>
+```
+
+If the spike produced a reusable template (a config file, a starter script), copy it into `.claude/skills/<name>/templates/` or `.claude/skills/<name>/references/` and reference it from the skill body.
+
+## Step 5: Archive the spike, link from the skill
+
+1. In the new SKILL.md, reference the originating spike: "Derived from `.gsd/workflows/spikes/<slug>/RECOMMENDATION.md` (dated YYYY-MM-DD)."
+2. Do NOT delete the spike directory — spikes are research artifacts and retain value for forensics.
+3. Append one line to `.gsd/DECISIONS.md`: `- YYYY-MM-DD [spike]: packaged "<slug>" findings as skill <name>`.
+
+## Step 6: Confirm pickup
+
+Tell the user the skill will be surfaced on the next session via `skill-discovery.ts`. If they want to use it immediately, they can `Read .claude/skills/<name>/SKILL.md` now.
+
+</process>
+
+<anti_patterns>
+
+- **Writing to `~/.claude/skills/`.** That's user-global. Project spikes produce project skills — keep them scoped.
+- **Verbose frontmatter description.** The description is an index entry, not a tutorial. Keywords over prose.
+- **Packaging every spike.** If the outcome was "we decided X once," append to DECISIONS.md and move on.
+- **Copy-pasting the spike verbatim into the skill.** The spike is research; the skill is executable guidance. Re-author.
+- **Deleting the source spike.** Research artifacts should persist.
+
+</anti_patterns>
+
+<success_criteria>
+
+- [ ] A new `.claude/skills/<name>/SKILL.md` exists with well-formed frontmatter.
+- [ ] The `description` field uses keywords that will plausibly match future agent work.
+- [ ] The skill body is executable on its own without re-reading the originating spike.
+- [ ] The originating spike is referenced from the skill.
+- [ ] `.gsd/DECISIONS.md` has a one-line entry recording the packaging.
+- [ ] The spike directory itself is untouched.
+
+</success_criteria>

package/src/resources/skills/tdd/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: tdd
+description: Test-driven development with red-green-refactor loops built around vertical slices (tracer bullets), not horizontal layers. Use when asked to "use TDD", "write test-first", "red-green-refactor", "build this with tests", or whenever a feature has a clear observable contract and would benefit from tests that outlive refactors. Complements the bundled test and add-tests skills — use this for the discipline, use those for the mechanics.
+---
+
+<objective>
+Drive feature implementation through one red-green-refactor cycle per vertical slice. Each cycle produces a single failing test that pins one observable behavior, then the minimal code that makes it pass, then refactoring while GREEN. Never refactor while RED. Never write all tests up front.
+</objective>
+
+<context>
+GSD already organizes work into slices (S##) and tasks (T##). This skill operates at the task level — inside a single T##-PLAN.md, it structures the execution as a sequence of tiny red-green-refactor cycles rather than write-all-then-test or write-all-without-tests.
+
+Invocation points:
+- Task plan calls out behavior with a clear external contract (pure function, API endpoint, module boundary)
+- Bug fix — write the failing repro test first, then fix
+- Refactor into a new module — write the tests against the new interface first
+
+Do not use this skill for:
+- Exploratory spikes (use `/gsd start spike` — no production code ships)
+- Pure UI polish where visual verification beats unit tests
+- Scripts that run once and are deleted
+</context>
+
+<core_principle>
+**TESTS VERIFY BEHAVIOR THROUGH PUBLIC INTERFACES, NOT IMPLEMENTATION DETAILS.** A good test reads like a specification and survives refactors. A test that mocks internals or asserts private state fails every time you clean up the code — that is a bad test pretending to be a good one.
+
+**VERTICAL SLICES, NOT HORIZONTAL LAYERS.** Writing all tests upfront ("horizontal slicing") produces tests for behavior you imagined, not behavior the code actually exhibits. One tracer bullet at a time: write one test, make it pass, learn, write the next.
+
+**NEVER REFACTOR WHILE RED.** Refactoring without a passing test means you are guessing whether you broke something. Get to green first. Then clean up. Then go red again for the next slice.
+</core_principle>
+
+<process>
+
+## Step 1: Confirm the interface
+
+Before writing anything:
+
+1. What is the public interface? (function signature, HTTP route, module exports)
+2. Which behaviors matter most? List them in order of how badly you'd want to know if they broke.
+3. What does a "caller" look like? Write one example call in prose.
+
+If the user has not supplied these, ask — one round, 1–3 questions.
+
+## Step 2: Tracer bullet
+
+Pick the first behavior — usually the happy path for the most common input. Write one test that exercises it end-to-end through the public interface. Run it. It must fail (RED). If it passes, the test is not testing what you think it is — fix the test before writing any code.
+
+Then write the minimum code to make it pass. "Minimum" means: if hard-coding `return 42` makes the test pass, hard-code `return 42`. You will generalize on the next cycle. Run the test. It must pass (GREEN).
+
+This proves the end-to-end path works — test harness, imports, wiring, build. Everything from Step 3 onward is incremental.
+
+## Step 3: Red-green loop
+
+Pick the next behavior. Write one test that pins it. Run — RED. Write the minimum code that makes it pass without breaking prior tests. Run — GREEN.
+
+Guidelines for picking the next behavior:
+
+- Alternate happy-path-variant and edge-case tests — don't do all happy paths then all edges.
+- Stop adding happy paths when they stop revealing new code. Move to errors.
+- If the next test would require no new code, you have hit the end of this slice — skip to Step 4.
+
+Guidelines for writing the test:
+
+- One assertion per concept (multiple `expect` calls that describe one behavior are fine).
+- No mocking of internals. Mock external I/O (network, filesystem, clock) only when necessary.
+- The test name reads as a sentence: "rejects requests missing an auth header".
+
+Guidelines for writing the code:
+
+- Minimum to pass. If there are three cases and two are untested, write only the one that's under test.
+- Copy-paste is fine on the first and second occurrence. Extract on the third.
+
+## Step 4: Refactor while GREEN
+
+Now that the behavior is pinned, clean up. Extract duplicated logic. Rename unclear variables. Deepen the module — move responsibilities behind the interface until the internals stop leaking into the test.
+
+Rules:
+
+- Every refactor keeps every test GREEN. Run tests after each small change.
+- If a refactor would require changing a test, the test was coupled to implementation — either the test is wrong, or the interface you thought you were pinning is actually different. Fix the test first, then refactor.
+- Don't refactor speculatively. Extract around real duplication and real seams, not imagined ones.
+
+## Step 5: Close the slice
+
+When the behavior the task plan specified is fully under test and the code is clean:
+
+1. Run the full test suite — not just the tests you wrote. Verify no regressions.
+2. Append a one-line summary of what is now pinned to `.gsd/KNOWLEDGE.md` if the behavior is non-obvious or the test surfaced a trap future agents should know about.
+3. Use `gsd_*` tools to mark the task complete — do not edit checkboxes by hand.
+
+</process>
+
+<anti_patterns>
+
+- **Writing all tests first.** Horizontal slicing. Produces imagined-behavior tests that decouple from reality.
+- **Mocking internals.** `jest.mock("./internal-helper")` tells you the wiring matches your mental model, not that the behavior is correct.
+- **Refactoring while RED.** You have no signal. Any change could be right or wrong.
+- **"Just one more test" after GREEN without refactoring.** You accumulate duplication and the code rots in place.
+- **Testing implementation detail.** "It calls `fetchUser` three times." Who cares? Test the observable result.
+- **Skipping the failing run.** If you never saw RED, you don't know the test would have caught the bug.
+
+</anti_patterns>
+
+<success_criteria>
+
+- [ ] Every behavior the task plan called out has a test that pins it through the public interface.
+- [ ] Every test went RED before it went GREEN. No test was born passing.
+- [ ] All refactoring happened on GREEN. The final code is not the first draft.
+- [ ] Full test suite runs clean — no regressions.
+- [ ] No test mocks an internal helper or asserts a private field.
+
+</success_criteria>

package/src/resources/skills/verify-before-complete/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: verify-before-complete
+description: Block completion claims until verification evidence has been produced in the current message. Use before marking a task/slice/milestone complete, before creating a commit or PR, before saying "it works" or "tests pass", and any time you are about to claim work is done. The rule is: evidence before claims, always — running the verification must happen now, not "earlier in the session". Fresh output or no claim.
+---
+
+<objective>
+Enforce the GSD "work is not done when code compiles; work is done when verification passes" contract. A completion claim without verification output generated in the current message is a broken claim. This skill is the gate.
+</objective>
+
+<context>
+GSD's system prompt sets the expectation; `guided-complete-slice.md` and `auto-verification.ts` enforce it at the slice boundary. But between slice boundaries — mid-task, mid-debug, mid-review — an agent can drift into "I think it works" mode and ship broken work. This skill is the ritual to break that pattern at any completion point.
+
+Invocation points:
+- About to toggle a checkbox from `[ ]` to `[x]` via a `gsd_*` tool
+- About to commit, push, or open a PR
+- About to summarize a task or slice as complete
+- About to say "tests pass", "build works", "lint clean", "fixed", "done"
+- Replying to a user question with "yes it works" or similar
+</context>
+
+<core_principle>
+**EVIDENCE BEFORE CLAIMS, ALWAYS.** "I ran it earlier" is not evidence. A log from three tool calls ago is not evidence if code has changed since. The verification must have happened *after* the last code change, in this message, with fresh output.
+
+**VIOLATING THE LETTER IS VIOLATING THE SPIRIT.** If the principle feels inconvenient, that is the signal it is load-bearing. Find the verification command. Run it. Read the output.
+</core_principle>
+
+<process>
+
+## Step 1: Identify the claim
+
+What are you about to claim? Name it precisely:
+
+- "Tests pass" → which tests?
+- "Build works" → for which target?
+- "Bug is fixed" → which reproduction?
+- "Task complete" → which acceptance criteria?
+
+## Step 2: Identify the verification command
+
+Match claim → command:
+
+| Claim | Verification |
+|---|---|
+| Tests pass | The specific test command the project uses (`npm test`, `cargo test`, `pytest`, etc.) — scoped to changed code if large suite. |
+| Build works | The project's build command, for real — not `tsc --noEmit` if the project needs a bundle. |
+| Lint clean | `lsp diagnostics` on edited files, plus the project's linter if CI runs one. |
+| Bug fixed | The reproduction steps from the bug report or test, freshly run. |
+| UI works | Browser verification via `browser_snapshot_refs` + `browser_assert` in a running app — not "it looks right in the diff". |
+| Slice complete | Every acceptance criterion in `S##-PLAN.md`, re-checked against live behavior. |
+
+If no verification command exists, the task has not produced a falsifiable claim — it is not complete. Write the verification first (see the `tdd` or `test` skill).
+
+## Step 3: Run it now
+
+Use `async_bash` for one-shot commands, `bg_shell` for long-running servers/watchers. Wait for it to exit. Read the output. Not skim — read.
+
+**If output indicates failure:** you do not have a completion claim. Loop back: inspect the error, fix, re-run until it passes or a real blocker requires user input. Do not partially claim ("tests mostly pass") — either pass or report failure honestly.
+
+**If output indicates success:** quote the relevant line in your reply. "42 tests passing" or "Exit code 0" or "LSP reports 0 errors on the 3 edited files."
+
+## Step 4: Check for staleness
+
+If you ran the verification early in this message, then made further code changes, the output is stale. Re-run. Cancel in-flight `async_bash` jobs that predated the edit (see system prompt: "stale job hygiene").
+
+## Step 5: Now claim
+
+Only now, after fresh output, can you:
+
+- Mark a task/slice/milestone complete via `gsd_*`
+- Commit / push / open PR
+- State "done", "fixed", "passes", "works"
+
+Include the evidence in the claim: "Slice complete — `npm test` passed (84/84), `npm run build` exit 0, acceptance criterion 3 verified against live UI at /dashboard."
+
+</process>
+
+<anti_patterns>
+
+- **"It should work"** — not verification. Run the command.
+- **"Tests passed earlier"** — stale. Run them now.
+- **"The code looks right"** — code review is not verification.
+- **`tsc --noEmit` as the build check** when the project bundles — test what the user experiences.
+- **Silent failures** — "the test was killed by a timeout so I assume it's fine." No.
+- **Partial passes** — 80/84 is not "tests pass." Report the 4 failures.
+- **Skipping because "I know why this works"** — your mental model is not evidence.
+
+</anti_patterns>
+
+<success_criteria>
+
+- [ ] The claim is precise — not "it works" but "`npm test` passed with 84/84 tests."
+- [ ] The verification command ran *after* the last code change, in this message.
+- [ ] Output was read, not skimmed.
+- [ ] Failures would have been caught — the verification actually tests what the claim asserts.
+- [ ] Relevant evidence is quoted in the claim reply.
+
+</success_criteria>

package/src/resources/skills/write-docs/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: write-docs
+description: Collaborative document authoring workflow for proposals, technical specs, decision docs, README sections, ADRs, and long-form prose that must work for fresh readers. Use when asked to "write the docs", "draft a proposal", "write a spec", "write an RFC", "write the README", or when a document needs to be understandable by someone without this session's context. Three stages: gather context, iterate on structure, reader-test for a stranger.
+---
+
+<objective>
+Produce documentation that works for a reader landing cold. Not a summary of what was built, not a dump of the conversation, but a document that transfers intent to someone who wasn't here. Run it through three stages — Context → Refine → Reader-Test — and don't ship until a hypothetical reader could act on it.
+</objective>
+
+<context>
+GSD already produces durable artifacts (`M###-CONTEXT.md`, `S##-SUMMARY.md`, `DECISIONS.md`, `KNOWLEDGE.md`), but those are scaffolded by templates. This skill is for free-form documentation: README changes, public docs, architectural proposals, RFCs, PR descriptions, runbooks, and anything that lives under `docs/`, `mintlify-docs/`, or `gitbook/` in this repo.
+
+Invocation points:
+- User asks to write or rewrite a piece of documentation
+- Before shipping a feature that adds user-facing behavior — docs need updates
+- After `write-milestone-brief` when the brief needs a public-facing summary for non-GSD consumers
+- PR description for a meaningful change
+</context>
+
+<core_principle>
+**WRITE FOR THE FRESH READER.** The test is not "does the maintainer understand it" — you are the maintainer. The test is "can someone who has never seen this code act correctly after reading this?"
+
+**ITERATE STRUCTURE BEFORE PROSE.** An outline that's wrong will not be saved by good sentences. Agree on the sections, what each is for, and in what order before drafting the body.
+
+**NO FILE PATHS IN TRUNK DOCS.** Paths rot. Describe modules, behaviors, and invariants. A README that cites `src/foo.ts:42` is a future broken link.
+</core_principle>
+
+<process>
+
+## Stage 1: Context gathering
+
+1. **Who is the reader?** Internal engineer, open-source contributor, end user, future you at 3am. The answer changes everything.
+2. **What should they be able to do after reading?** Name the single post-read action. "Understand the auth flow" is not an action — "implement a new auth provider using the documented extension points" is.
+3. **What do they already know?** Assume they have docs for the language and framework, not for your codebase. Don't re-explain React; do explain your project's conventions.
+4. **What context from this conversation/codebase belongs in the doc?** Ask the user to dump any missing material. Do not invent examples.
+
+One round of clarifying questions. Then proceed.
+
+## Stage 2: Refine structure
+
+1. **Draft an outline, not prose.** Numbered sections, one-line purpose for each. Show it to the user.
+2. **Iterate the outline.** Remove sections the reader doesn't need. Reorder so the must-knows come first. Flag sections that can't be written without more input.
+3. **Only then, fill sections.** Write the body of each section in order. Keep sentences short. Prefer concrete examples over abstractions. Show small diffs or code snippets where they clarify; skip them where they'd rot.
+4. **Draft in place.** Write directly to the target file — `docs/<name>.md`, `README.md`, `mintlify-docs/…`. Do not keep a scratch draft in the conversation.
+
+## Stage 3: Reader-test
+
+1. **Cold-read it.** Read the doc top to bottom as if you hadn't written it. Stop at every moment you thought "they already know X" — that's a gap.
+2. **Can the named post-read action be taken?** Walk through it. If yes, the doc works. If no, identify the missing piece and add it.
+3. **Cut aggressively.** Anything that isn't serving the post-read action comes out. Documentation bloat kills docs.
+4. **Offer to the user:** "Here's the draft. Want me to run a fresh sub-agent (`Agent(subagent_type=Explore)`) as a cold reader to stress-test it?"
+
+## Stage 4: Wire it in
+
+1. Link to the new doc from relevant entry points (README.md index, docs/ sidebar, mintlify-docs config, etc.).
+2. If it documents a decision, also append a one-line entry to `.gsd/DECISIONS.md` pointing at the doc.
+3. If it's a public-facing change, flag for the next release notes / CHANGELOG update.
+
+</process>
+
+<anti_patterns>
+
+- **"Writing a summary of what we did"** — the reader doesn't care about the journey. Document the destination.
+- **Paths and line numbers in long-lived docs.** They rot. Use module names.
+- **Re-explaining general concepts.** If the reader needs to know what HTTP is, the doc is aimed at the wrong audience.
+- **Starting with prose.** Outline first, always.
+- **Not cold-reading.** Every doc gets one pass as if you've never seen it.
+- **Claiming "done" without the reader-test.** Docs that haven't been cold-read are notes, not docs.
+
+</anti_patterns>
+
+<success_criteria>
+
+- [ ] The reader and their post-read action are named explicitly.
+- [ ] The outline was agreed before prose was written.
+- [ ] A cold-read pass happened; gaps were closed.
+- [ ] No file paths or line numbers in the trunk doc (decision-scoped ADRs may include them).
+- [ ] Doc is linked from a relevant entry point — it is discoverable, not orphaned.
+- [ ] The named action is actually executable after reading.
+
+</success_criteria>