gsd-pi 2.75.0 → 2.76.0-dev.4100bd590

package/dist/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/dist/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/dist/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/dist/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>

package/dist/resources/skills/write-milestone-brief/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: write-milestone-brief
+description: Synthesize the current conversation into a milestone brief (PRD). Writes to `M###-CONTEXT.md` by default, or files a GitHub issue only with explicit user confirmation. Use when asked to "turn this into a PRD", "draft a milestone brief", "capture this context", "write it up", or when enough has been discussed to commit the plan to paper. Does not interview — it synthesizes what is already known.
+---
+
+<objective>
+Take everything established in the current conversation (plus repo reality) and produce a milestone brief that a future agent can execute from with zero additional context. The output is a populated `M###-CONTEXT.md`, matching the template at `src/resources/extensions/gsd/templates/context.md`. Optionally, with explicit confirmation, also a GitHub issue.
+</objective>
+
+<context>
+This skill runs at the end of a discussion phase, after enough grilling/design has happened that the plan has stabilized. It does NOT interview — use the `grill-me` skill for that. This skill collapses what is already on the page into a durable artifact.
+
+Typical invocation points:
+- User says "capture this" or "write it up" after a planning discussion
+- End of a `discuss` phase before moving to `plan`
+- User wants to hand the work off to another agent or a human teammate
+</context>
+
+<core_principle>
+**SYNTHESIZE, DO NOT RE-INTERVIEW.** Use what is already in this conversation. If a decision is genuinely missing, note it in `Open Questions` — do not relitigate.
+
+**REAL OUTCOMES, NOT TASKS.** `M###-CONTEXT.md` describes what the user can do when the milestone ships, what scenarios must pass for "done," and what architectural decisions were made. It does NOT list tasks or implementation steps — those belong in `M###-ROADMAP.md` and `S##-PLAN.md`.
+
+**NO FILE PATHS OR LINE NUMBERS IN THE BRIEF.** Those go stale. Describe modules, interfaces, and behaviors. The roadmap and plans can cite code locations; the brief should outlive refactors.
+</core_principle>
+
+<process>
+
+## Step 1: Locate the target
+
+Find the active milestone:
+
+1. Read `.gsd/STATE.md` — it names the active milestone.
+2. If no milestone is active, ask the user whether this is a new milestone (create directory + files) or appending to an existing one.
+3. For a new milestone, use `gsd_milestone_new` or the `/gsd new-milestone` flow — do not create directories by hand.
+
+## Step 2: Read the template
+
+Read `src/resources/extensions/gsd/templates/context.md` (the full path is shown in the `templatesDir` system-prompt field). Match its structure exactly — parsers and downstream prompts depend on the headings.
+
+## Step 3: Sketch the modules
+
+Before filling the template, sketch the major modules the milestone will build or modify. Actively look for opportunities to extract **deep modules** — ones that encapsulate a lot of functionality in a simple, testable interface that rarely changes. A deep module is more testable, more AI-navigable, and survives refactors.
+
+If the modules are non-obvious, offer the user a brief check-in: "The milestone touches modules A, B, and C. A can be extracted as a deep module that hides X. Does that match your thinking?" One round. Then proceed.
+
+## Step 4: Fill the template
+
+Populate `M###-CONTEXT.md` using the template. Key sections:
+
+- **Project Description** — one paragraph, plain English, what this milestone is.
+- **Why This Milestone** — the problem it solves and why now, from the user's perspective.
+- **User-Visible Outcome** — literal user actions in the real environment. "User can complete the import flow end-to-end" not "Adds import API."
+- **Completion Class** — contract / integration / operational. Be honest about what level of proof is required.
+- **Final Integrated Acceptance** — the real end-to-end scenarios that must pass. Name things that cannot be simulated.
+- **Architectural Decisions** — one `### Decision Title` block per decision, with rationale and alternatives considered. If there were no architectural decisions, write "None — straightforward execution" and skip the subsections.
+- **Error Handling Strategy** — approach for failures, edge cases, and error propagation. Include retry policies, fallback behaviors, and user-facing error messages where relevant.
+- **Risks and Unknowns** — only real ones. Do not invent risks.
+- **Existing Codebase / Prior Art** — module names, not line numbers. Brief description of how each relates.
+- **Relevant Requirements** — requirement IDs this milestone advances and how.
+- **Scope** — In Scope / Out of Scope / Non-Goals. Be specific about tempting adjacent work that is out.
+- **Technical Constraints** — binding constraints (runtime, platform, dependencies, performance budgets).
+- **Integration Points** — external systems/services this milestone touches and how.
+- **Testing Requirements** — test types (unit, integration, e2e), coverage expectations, and specific scenarios that must pass.
+- **Acceptance Criteria** — per-slice, testable criteria gathered during discussion.
+- **Open Questions** — anything material that is genuinely unresolved. Note current thinking so future agents have a starting point.
+
+> The template headings above are mandatory — do not omit, rename, or reorder them. The exact required order matches `src/resources/extensions/gsd/templates/context.md`: Project Description → Why This Milestone → User-Visible Outcome → Completion Class → Final Integrated Acceptance → Architectural Decisions → Error Handling Strategy → Risks and Unknowns → Existing Codebase / Prior Art → Relevant Requirements → Scope → Technical Constraints → Integration Points → Testing Requirements → Acceptance Criteria → Open Questions.
+
+## Step 5: Write it
+
+Use the `write` tool to create or overwrite `.gsd/milestones/<MID>/<MID>-CONTEXT.md`. Do not ask for approval of the file contents before writing — the user will see the rendered file and can edit directly.
+
+Then append a one-line summary to `.gsd/DECISIONS.md` for any genuinely hard-to-reverse architectural decision: `- YYYY-MM-DD [MID]: <decision> — <one-line rationale>`.
+
+## Step 6: Offer next steps
+
+After writing, offer the user (do not auto-execute):
+
+1. **Proceed to planning** — run `/gsd dispatch plan` to generate `M###-ROADMAP.md` from this brief.
+2. **File as GitHub issue** — use `mcp__github__issue_write` to create a tracking issue. Requires explicit "yes" per the outward-action rule. Use the PRD template below for the body.
+3. **Iterate on the brief** — if something feels wrong, run `grill-me` to stress-test before moving on.
+
+### GitHub issue body template (only if user chooses option 2)
+
+```markdown
+## Problem Statement
+<user-perspective problem — one paragraph>
+
+## Solution
+<user-perspective solution — one paragraph>
+
+## User Stories
+1. As a <actor>, I want <feature>, so that <benefit>.
+2. ...
+<cover all aspects; be exhaustive>
+
+## Architectural Decisions
+<list of decisions with rationale — copy from M###-CONTEXT.md>
+
+## Testing Strategy
+<what a good test looks like here: external behavior only, which modules get tested, prior art>
+
+## Out of Scope
+<things explicitly not covered>
+
+## Further Notes
+<any extra context>
+
+---
+See `.gsd/milestones/<MID>/<MID>-CONTEXT.md` for the full brief.
+```
+
+</process>
+
+<anti_patterns>
+
+- **Re-interviewing the user.** Use context, not fresh questions. If something is missing, put it in Open Questions.
+- **Listing implementation tasks.** The brief describes outcomes and decisions — the roadmap and plans describe tasks.
+- **Citing specific line numbers.** They rot. Cite modules or interfaces.
+- **Inventing risks or decisions.** If the discussion didn't surface a real architectural choice, the Architectural Decisions section is short — that's fine.
+- **Auto-filing the GitHub issue.** Any outward-facing action needs explicit confirmation.
+
+</anti_patterns>
+
+<success_criteria>
+
+- [ ] `M###-CONTEXT.md` exists and follows the template structure.
+- [ ] User-Visible Outcome section names literal user actions, not internal tasks.
+- [ ] Completion Class is honest — no "just unit tests" when the milestone demands live integration.
+- [ ] Every architectural decision has a rationale and named alternatives.
+- [ ] Open Questions captures genuinely unresolved items — not decisions the user already made.
+- [ ] `.gsd/DECISIONS.md` has a dated one-liner for any hard-to-reverse decision.
+
+</success_criteria>

package/dist/rtk-shared.d.ts

@@ -0,0 +1,10 @@
+export declare const GSD_RTK_DISABLED_ENV = "GSD_RTK_DISABLED";
+export declare const GSD_RTK_PATH_ENV = "GSD_RTK_PATH";
+export declare const RTK_TELEMETRY_DISABLED_ENV = "RTK_TELEMETRY_DISABLED";
+export declare function isTruthy(value: string | undefined): boolean;
+export declare function isRtkEnabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function getManagedRtkDir(env?: NodeJS.ProcessEnv): string;
+export declare function getRtkBinaryName(platform?: NodeJS.Platform): string;
+export declare function getPathValue(env: NodeJS.ProcessEnv): string | undefined;
+export declare function resolvePathCandidates(pathValue: string | undefined): string[];
+export declare function resolveSystemRtkPath(pathValue: string | undefined, platform?: NodeJS.Platform): string | null;

package/dist/rtk-shared.js

@@ -0,0 +1,47 @@
+import { existsSync } from "node:fs";
+import { homedir as osHomedir } from "node:os";
+import { delimiter, join } from "node:path";
+export const GSD_RTK_DISABLED_ENV = "GSD_RTK_DISABLED";
+export const GSD_RTK_PATH_ENV = "GSD_RTK_PATH";
+export const RTK_TELEMETRY_DISABLED_ENV = "RTK_TELEMETRY_DISABLED";
+export function isTruthy(value) {
+    if (!value)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    return normalized === "1" || normalized === "true" || normalized === "yes";
+}
+export function isRtkEnabled(env = process.env) {
+    return !isTruthy(env[GSD_RTK_DISABLED_ENV]);
+}
+export function getManagedRtkDir(env = process.env) {
+    return join(env.GSD_HOME || join(osHomedir(), ".gsd"), "agent", "bin");
+}
+export function getRtkBinaryName(platform = process.platform) {
+    return platform === "win32" ? "rtk.exe" : "rtk";
+}
+export function getPathValue(env) {
+    const pathKey = Object.keys(env).find((key) => key.toLowerCase() === "path");
+    return pathKey ? env[pathKey] : env.PATH;
+}
+export function resolvePathCandidates(pathValue) {
+    if (!pathValue)
+        return [];
+    return pathValue
+        .split(delimiter)
+        .map((part) => part.trim())
+        .filter(Boolean);
+}
+export function resolveSystemRtkPath(pathValue, platform = process.platform) {
+    const candidates = platform === "win32"
+        ? ["rtk.exe", "rtk.cmd", "rtk.bat", "rtk"]
+        : ["rtk"];
+    for (const dir of resolvePathCandidates(pathValue)) {
+        for (const candidate of candidates) {
+            const fullPath = join(dir, candidate);
+            if (existsSync(fullPath)) {
+                return fullPath;
+            }
+        }
+    }
+    return null;
+}

package/dist/rtk.d.ts

@@ -1,9 +1,8 @@
 import { spawnSync } from "node:child_process";
+import { GSD_RTK_DISABLED_ENV, GSD_RTK_PATH_ENV, RTK_TELEMETRY_DISABLED_ENV, getManagedRtkDir, getRtkBinaryName, isRtkEnabled } from "./rtk-shared.js";
 export declare const RTK_VERSION = "0.33.1";
-export declare const GSD_RTK_DISABLED_ENV = "GSD_RTK_DISABLED";
 export declare const GSD_SKIP_RTK_INSTALL_ENV = "GSD_SKIP_RTK_INSTALL";
-export declare const GSD_RTK_PATH_ENV = "GSD_RTK_PATH";
-export declare const RTK_TELEMETRY_DISABLED_ENV = "RTK_TELEMETRY_DISABLED";
+export { GSD_RTK_DISABLED_ENV, GSD_RTK_PATH_ENV, RTK_TELEMETRY_DISABLED_ENV, getManagedRtkDir, getRtkBinaryName, isRtkEnabled, };
 export interface EnsureRtkOptions {
     targetDir?: string;
     allowDownload?: boolean;
@@ -20,9 +19,6 @@ export interface EnsureRtkResult {
     binaryPath?: string;
     reason?: string;
 }
-export declare function isRtkEnabled(env?: NodeJS.ProcessEnv): boolean;
-export declare function getManagedRtkDir(env?: NodeJS.ProcessEnv): string;
-export declare function getRtkBinaryName(platform?: NodeJS.Platform): string;
 export declare function getManagedRtkPath(platform?: NodeJS.Platform, targetDir?: string): string;
 export declare function prependPathEntry(env: NodeJS.ProcessEnv, entry: string): NodeJS.ProcessEnv;
 export declare function applyRtkProcessEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;