gsd-pi 2.76.0 → 2.77.0

package/src/resources/skills/dependency-upgrade/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: dependency-upgrade
+description: Plan, batch, and verify dependency upgrades safely. Triages outdated packages into risk tiers, upgrades in order (dev/minor/patch first, runtime majors last), verifies each batch before moving on, and produces an auditable commit sequence. Use when asked to "upgrade deps", "bump packages", "update node_modules", "fix vulnerabilities", "upgrade React/Node/TypeScript", or after `/gsd start dep-upgrade`. Complements the dep-upgrade workflow template with execution-level rigor.
+---
+
+<objective>
+Turn a pile of outdated packages into a series of small, verifiable upgrades with clean commits. The deliverable is an ordered upgrade plan, executed with verification between batches, and a summary that flags anything risky for follow-up. No big-bang upgrades.
+</objective>
+
+<context>
+GSD-2 ships a `/gsd start dep-upgrade` workflow template (`src/resources/extensions/gsd/workflow-templates/dep-upgrade.md`) that structures the phases: assess → upgrade → fix breaks → verify. This skill is the execution-level detail inside the upgrade phase — how to batch, how to verify, how to recover from a breaking upgrade without losing the good ones.
+
+Invocation points:
+- `/gsd start dep-upgrade` workflow is running
+- Ad-hoc "bump the deps" request
+- Security advisory response (CVE in a direct dep)
+- Framework major-version update (React 18 → 19, Node LTS bump)
+- Monthly hygiene pass
+</context>
+
+<core_principle>
+**BATCH BY RISK, NOT BY LAZINESS.** `npm update` is a shortcut that blends safe and risky changes into one commit. When something breaks, you can't tell which dep caused it. Always separate: patches and dev-deps first, minors next, majors individually.
+
+**VERIFY BETWEEN BATCHES.** Run the test suite after every batch. Don't stack five batches and hope. If a batch breaks something, you need to know which one.
+
+**ONE MAJOR PER COMMIT.** Major version bumps are where real breakage lives. Keep them isolated so the commit history tells the truth.
+</core_principle>
+
+<process>
+
+## Step 1: Take inventory
+
+Run the ecosystem's outdated check. Capture output, don't act on it yet:
+- Node: `npm outdated` or `pnpm outdated` or `yarn outdated`
+- Python: `pip list --outdated` or `uv pip list --outdated`
+- Rust: `cargo outdated`
+- Ruby: `bundle outdated`
+- Go: `go list -m -u all`
+
+Also capture:
+- `npm audit` (or equivalent) — security advisories
+- Current versions of language runtime, build tool, test runner
+
+## Step 2: Classify each outdated package
+
+For each outdated package, note:
+
+- **Type:** direct dep / dev-dep / transitive
+- **Kind of bump:** patch (1.2.3 → 1.2.4), minor (1.2.3 → 1.3.0), major (1.2.3 → 2.0.0)
+- **Risk:** Low (dev-dep, patch), Medium (runtime minor, dev-dep major), High (runtime major, framework, TypeScript compiler)
+- **Blast radius:** How many files in the repo import it? (Rough count via `rg`.)
+- **Has known breaking changes:** Check the CHANGELOG or release notes for any major bumps — do NOT skip this, and do NOT infer "probably fine."
+
+## Step 3: Build the batch plan
+
+Order:
+
+1. **Batch 1 — Dev dep patches and minors.** Lowest risk, fastest feedback. Includes linters, formatters, type definitions, test runners.
+2. **Batch 2 — Runtime patches.** All patch bumps to runtime deps together.
+3. **Batch 3 — Runtime minors.** One batch per semantic group if any minor carries risk notes; otherwise one batch for the rest.
+4. **Batch 4+ — Each major, individually.** One commit per major. Framework bumps (React, Next.js, Vue, TypeScript) each get their own commit.
+5. **Batch N — Language runtime.** If bumping Node/Python/Rust, last — it changes the compile/run env for everything.
+
+Skip (for now):
+- Anything with "unreleased", "pre", "beta", "rc" tags unless the user explicitly wants pre-release tracking
+- Deps you know are blocked by another dep (e.g., can't bump X until Y supports it)
+
+Present the plan to the user. One round of adjustment. Then execute.
+
+## Step 4: Execute a batch
+
+For each batch:
+
+1. **Start from a clean working tree.** `git status` — no uncommitted changes.
+2. **Apply the upgrades** using the ecosystem command (`npm install package@version ...`, `uv add …`, `cargo update -p …`).
+3. **Regenerate the lockfile** fully if necessary.
+4. **Build.** Run the project's real build — not just typecheck.
+5. **Test.** Run the full suite. Not a scoped subset.
+6. **Lint.** `lsp diagnostics` on changed files + the project linter.
+7. **Smoke-test the app** if it has a running surface (dev server, CLI command).
+
+If any step fails:
+- Investigate before moving on. Don't skip the batch.
+- If the failure is trivial (a rename, a deprecated import), fix it in the same commit — the upgrade broke it, the upgrade commit fixes it.
+- If the failure is non-trivial (an API you heavily depend on was removed), either pin back or split: upgrade the other deps in the batch in this commit, and handle the problem dep separately in Step 5.
+
+**Commit with a precise message:**
+
+```
+deps: bump <scope> — <what changed in one line>
+
+- package-a: 1.2.3 → 1.2.9 (patch)
+- package-b: 2.1.0 → 2.4.0 (minor — no breaking changes in CHANGELOG)
+- package-c: 3.0.1 → 3.0.2 (patch)
+
+Verified: npm test (84/84 pass), npm run build exit 0, lsp diagnostics clean.
+```
+
+## Step 5: Handle stuck majors
+
+For each major that breaks something:
+
+1. **Read the migration guide** — do not guess at the API changes.
+2. **Scope the blast radius** — `rg` for the symbols that changed.
+3. **Decide: upgrade now or defer?** If the migration is a weekend's work and not urgent, file a `/gsd start refactor` follow-up and pin the current major for now.
+4. **If upgrading now:** branch the work as its own slice (`S##`). The dep upgrade is only one task; the migration is the rest of the slice.
+5. **Verify end-to-end after migration.** The test suite alone may miss behavior changes.
+
+## Step 6: Summary
+
+After all batches, produce a rollup:
+
+```markdown
+## Dependency Upgrade — <date>
+
+### Completed
+- Batch 1 (dev patches): 12 packages — commit abc1234
+- Batch 2 (runtime patches): 5 packages — commit def5678
+- Batch 3 (runtime minors): 3 packages — commit ...
+- Batch 4 (React 18 → 19): commit ... — required refactors in <files>
+
+### Deferred
+- typescript 5.3 → 5.7 — requires updating 40+ decorator usages. Filed as M005.
+- vite 4 → 5 — config shape changed. Owner assigned: <user>.
+
+### Still outdated (intentional)
+- <package> — pinned because <reason>
+
+### Security advisories
+- <CVE> resolved by <package upgrade>
+- <CVE> still open — not exploitable in our usage (see comment in package.json)
+```
+
+Append to `.gsd/KNOWLEDGE.md` any non-obvious gotcha from the upgrade (API changes that tripped you up, migration rituals for this codebase).
+
+</process>
+
+<anti_patterns>
+
+- **`npm update` blindly.** Mixes safe and risky in one undiagnosable commit.
+- **Multiple majors in one commit.** When it breaks, you don't know which.
+- **No verification between batches.** You stack failures until nothing works.
+- **Skipping the CHANGELOG.** "It's just a minor" — until it isn't.
+- **Force-merging a failing batch with `--force`.** Leave it broken or roll back; don't lie to git.
+- **Ignoring `--legacy-peer-deps` warnings.** They're telling you the dep graph is incoherent.
+
+</anti_patterns>
+
+<success_criteria>
+
+- [ ] Each batch is in its own commit with a precise message.
+- [ ] Majors are one-per-commit.
+- [ ] Test suite, build, and lint passed after every batch (per `verify-before-complete`).
+- [ ] Stuck upgrades are documented with a concrete next step (filed as slice/milestone, or pinned with a reason).
+- [ ] Security advisories are addressed or explicitly triaged.
+- [ ] Summary report exists for the user to review.
+
+</success_criteria>

package/src/resources/skills/design-an-interface/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: design-an-interface
+description: Produce 3+ radically different designs for a module, API, or interface, compare them in prose, and synthesize a recommendation. Use when asked to "design an interface", "shape this API", "design it twice", "explore module boundaries", or when planning a new deep module and the first idea is unlikely to be the best. Based on "Design It Twice" from A Philosophy of Software Design — the value is the contrast, not the first draft.
+---
+
+<objective>
+Generate at least three radically different interface designs for a single module or API, present them sequentially, compare them honestly, and recommend one (or a hybrid). The goal is to surface the design space — not to pick fast. A small interface hiding significant complexity is a deep module; a large interface with thin implementation is a shallow one. Optimize for the former.
+</objective>
+
+<context>
+This skill runs during planning — before `S##-PLAN.md` task decomposition, or mid-slice when a seam turns out to be more load-bearing than the roadmap assumed. It is not for picking between two libraries. It is for shaping the interface your own code will expose.
+
+Typical invocation points:
+- A slice plan says "add module X" and the shape of X is not obvious.
+- Two callers are about to grow coupled to an interface that has not been designed on purpose.
+- A refactor surfaces a seam that needs to be re-cut deliberately.
+</context>
+
+<core_principle>
+**RADICALLY DIFFERENT, NOT VARIANTS.** Three designs with different method names are one design. Three designs that hide different things, expose different axes of control, or invert the caller/callee relationship are three designs. Enforce real divergence by assigning each sub-agent a constraint that would force a different shape.
+
+**INTERFACE, NOT IMPLEMENTATION.** Do not estimate effort. Do not argue about how hard it is to build. Argue about how the interface behaves from the caller's side and what it hides internally.
+</core_principle>
+
+<process>
+
+## Step 1: Gather requirements
+
+Before spawning anything, answer in the conversation:
+
+- What problem does the module solve?
+- Who calls it? (other modules, external users, tests)
+- What are the key operations?
+- What constraints exist? (performance, compatibility, existing patterns)
+- What should stay hidden inside vs be exposed?
+
+If the user did not supply all of these, ask — one round, 1–3 questions max, per the ask-vs-infer rule.
+
+## Step 2: Spawn parallel design agents
+
+Use `Agent(subagent_type=general-purpose)` for 3–4 agents in one message so they run concurrently. Each agent gets the same requirements brief plus one divergent constraint:
+
+- Agent 1: "Minimize method count — 1 to 3 entry points max."
+- Agent 2: "Maximize flexibility — support many extension points and composition."
+- Agent 3: "Optimize for the single most common caller — make the default case trivial and the advanced case possible."
+- Agent 4 (optional): "Design around a ports-and-adapters boundary — interface is the port, concrete implementations are adapters."
+
+Each agent returns:
+
+1. Interface signature (types, methods, params)
+2. One worked usage example showing a real caller
+3. What complexity this design keeps internal
+4. Trade-offs — what it's bad at
+
+## Step 3: Present sequentially
+
+Show the three designs one after another. Let the user read each before the next. Do not lead with the comparison — the value is in feeling the shape of each option first.
+
+## Step 4: Compare in prose
+
+After all three are on the page, compare them on:
+
+- **Simplicity** — fewer methods and simpler params are easier to learn and harder to misuse
+- **Depth** — small interface hiding significant complexity (good) vs large interface with thin implementation (bad)
+- **Generality vs specialization** — does it cover the real use case without overfitting?
+- **Efficiency of the shape** — does the interface let the implementation be efficient, or force awkward internals?
+- **Misuse surface** — what can a caller do wrong?
+
+Prose, not a table. Highlight where the designs diverge most sharply — that is where the interesting trade-off lives.
+
+## Step 5: Recommend
+
+Be opinionated. Pick one, or propose a hybrid that takes specific elements from multiple designs. State the reason in one paragraph. The user wants a strong read, not a menu.
+
+## Step 6: Capture the decision
+
+Once the user picks:
+
+- Append to `.gsd/DECISIONS.md` with the chosen shape and the reason.
+- If a slice is active, update `S##-CONTEXT.md` with the interface sketch.
+- Do not write the implementation — that happens during execute.
+
+</process>
+
+<anti_patterns>
+
+- **Three-variants-of-the-same-idea:** all three use a builder, all three return the same object, etc. Kill and re-spawn.
+- **Implementation creep:** proposing file paths, call graphs, or internal data structures. Keep it at interface shape.
+- **Skipping comparison:** presenting three designs and asking "which do you like?" The comparison is the whole skill.
+- **Effort-based ranking:** "#2 is easiest to build" is not an interface argument. Rank by what the caller experiences.
+
+</anti_patterns>
+
+<success_criteria>
+
+- [ ] 3+ genuinely different interface shapes were produced.
+- [ ] Each design shows a real usage example, not a type signature in isolation.
+- [ ] Trade-offs are named per design.
+- [ ] A specific recommendation (or hybrid) is on the page with a reason.
+- [ ] The decision is captured in `.gsd/DECISIONS.md` or the active `S##-CONTEXT.md`.
+
+</success_criteria>

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

@@ -0,0 +1,153 @@
+---
+name: forensics
+description: Post-mortem a failed GSD auto-mode run. Traces from symptom to root cause using `.gsd/activity/*.jsonl`, `.gsd/journal/YYYY-MM-DD.jsonl`, `.gsd/metrics.json`, and `.gsd/auto.lock`. Produces a filing-ready bug report with file:line references and a concrete fix suggestion. Use when asked to "forensics", "post-mortem", "why did auto-mode fail", "trace the stuck loop", "debug the crash", after `/gsd forensics` is invoked, or when a session ended in an unexpected terminal state. Reads existing artifacts — does NOT re-run anything.
+---
+
+<objective>
+Turn scattered GSD runtime artifacts into one coherent cause chain. The deliverable is a GitHub-issue-ready report that names the file and line where the bug lives, cites the evidence, and proposes a fix. Forensics is archaeology, not re-run — no modifying state, no triggering commands, just reading the paper trail.
+</objective>
+
+<context>
+GSD persists a lot of runtime evidence under `.gsd/`:
+
+- `activity/{seq}-{unitType}-{unitId}.jsonl` — full tool-call and message stream per unit
+- `journal/YYYY-MM-DD.jsonl` — iteration-level events (dispatch-match, stuck-detected, guard-block, unit-start/end, terminal)
+- `metrics.json` — token/cost ledger; duplicate `type/id` entries indicate a stuck loop
+- `auto.lock` — JSON snapshot of the currently-owning PID; stale lock = crash mid-unit
+- `forensics/` — saved prior reports
+- `debug/` — debug logs if enabled
+- `runtime/paused-session.json` — serialized session when auto-mode paused
+- `doctor-history.jsonl` — doctor check history
+
+The `/gsd forensics` command pre-computes a forensic report with anomalies flagged. This skill is the manual investigation that goes deeper, or runs when the automated report isn't enough.
+
+Invocation points:
+- `/gsd forensics` has been run and user wants deeper analysis
+- Auto-mode exited unexpectedly, no obvious cause
+- Same unit dispatched multiple times (stuck loop suspected)
+- A session crashed and `auto.lock` is stale
+- User reports "it just stopped" or "it did the wrong thing"
+</context>
+
+<core_principle>
+**READ-ONLY.** Forensics touches no live state. Non-mutating inspection commands (e.g., `ps`, `top -b`, `cat /proc/*`) are allowed for checking process status or reading system files. Strictly prohibited: `gsd_*` writes, commands that modify state, executing binaries that produce side effects, writing to files (outside the final report), or re-running the failed unit. The evidence must stay pristine for future investigations.
+
+**SYMPTOM → ROOT CAUSE, WITH CITATIONS.** Every claim in the report is backed by an artifact path and either a line number or a JSONL field. "The loop got stuck because of a race" is not useful; "`.gsd/journal/2026-04-19.jsonl:142` shows `stuck-detected` with flowId X, caused by `dispatch-guard.ts:87` returning the same unit after `unit-end`" is.
+
+**PRE-PARSED LEADS, NOT CONCLUSIONS.** If `/gsd forensics` has surfaced anomalies, treat them as hypotheses to verify, not answers.
+</core_principle>
+
+<process>
+
+## Step 1: Locate the evidence
+
+Read what's in `.gsd/`:
+
+1. `auto.lock` — is it stale? Check PID against `ps` (read-only inspection, allowed). Stale = crash.
+2. Most recent `.gsd/activity/*.jsonl` — sort by mtime, newest first. That's the last unit that ran.
+3. Today's `.gsd/journal/YYYY-MM-DD.jsonl` — the iteration-level view.
+4. `.gsd/metrics.json` — does any `type/id` appear more than once? (stuck loop signal)
+5. `.gsd/runtime/paused-session.json` — if present, what was the pause reason?
+
+## Step 2: Reconstruct the failure from the activity log
+
+Activity JSONL format:
+- Each line is `{type: "message", message: {...}}`.
+- `message.role: "assistant"` → `content[]` with `type: "text"` reasoning and `type: "toolCall"` invocations.
+- `message.role: "toolResult"` → `{toolCallId, toolName, isError, content}`.
+- `usage` on assistant messages tracks tokens and cost.
+
+To trace a failure:
+1. Search for `isError: true` tool results in the last activity log. That's usually the proximate symptom.
+2. Walk backwards to the assistant message that made the call. Read the `text` content — that's the agent's reasoning at the moment of failure.
+3. Keep walking back. Find where the agent's model of the state diverged from reality.
+
+## Step 3: Cross-reference the journal
+
+For each symptom from the activity log, find the matching journal events:
+- `stuck-detected` + same `flowId` → the loop detected repetition. `data.reason` says why.
+- `guard-block` → a dispatch guard refused to run a unit. Check `data.reason` and trace to `dispatch-guard.ts` logic.
+- `unit-end` followed by another `unit-start` for the same `unitId` → re-dispatch. If tied to `stuck-detected`, the artifact verification failed after the unit succeeded.
+- `terminal` → auto-mode decided to stop. `data.reason` tells you why.
+
+Use `flowId` to reconstruct one iteration; use `causedBy` to follow causal chains across iterations.
+
+## Step 4: Name the root cause
+
+A good root cause is:
+- Specific: a function, a state transition, a missing guard.
+- Falsifiable: if we changed X, would the failure go away?
+- Sourced: cites a file and (where applicable) a line number.
+
+Bad root cause: "Auto-mode got stuck in a loop." Good root cause: "After slice completion, `auto-unit-closeout.ts` emits `unit-end` before `auto-post-unit.ts` updates the roadmap checkbox. The next `iteration-start` finds the same unit `[ ]` and re-dispatches — `dispatch-guard.ts:42` has no check against the freshly-ended `unitId`."
+
+Consult the source map in `src/resources/extensions/gsd/prompts/forensics.md` to map symptoms to the likely domain files.
+
+## Step 5: Propose a fix
+
+For the root cause:
+- Which file and function holds the bug?
+- What minimal change would eliminate it?
+- What test would have caught it? Can one be added?
+- Is this a regression from a recent commit? (Run `git log -- path/to/file.ts` mentally; do NOT run git commands that could modify state.)
+
+## Step 6: Write the report
+
+Format the output as a GitHub-issue-ready report:
+
+```markdown
+## Symptom
+
+<what the user saw — quote the error or describe the observed behavior>
+
+## Evidence Trail
+
+1. `.gsd/auto.lock` — <state: stale / fresh>
+2. `.gsd/activity/042-slice-S02.jsonl:128` — <isError: true from `gsd_task_complete`>
+3. `.gsd/journal/2026-04-19.jsonl:87` — <stuck-detected flowId 7a3c…>
+4. `.gsd/metrics.json` — <unit type/id "slice/S02" appears 3 times>
+
+## Root Cause
+
+<specific named cause — file, function, state transition>
+
+`src/resources/extensions/gsd/auto-unit-closeout.ts:<line>`: <exactly what goes wrong>
+
+## Proposed Fix
+
+<minimal change — file, function, what to change>
+
+## Test
+
+<what test would have caught this; whether one should be added>
+
+## Confidence
+
+<high / medium / low> — <what would change this confidence>
+```
+
+Offer to file this as a GitHub issue via `mcp__github__issue_write` — explicit confirmation required per the outward-action rule. Also save a copy to `.gsd/forensics/<slug>.md` for future reference.
+
+</process>
+
+<anti_patterns>
+
+- **Running any `gsd_*` write tool during forensics.** Evidence stays pristine.
+- **Re-running the auto-mode loop to "reproduce."** That overwrites the activity log. Read the existing one.
+- **Vague root cause.** "There's a race" is not a root cause. Name the race.
+- **No citations.** Every claim gets an artifact path.
+- **Skipping the journal.** The journal is the only view that shows dispatch-level decisions.
+- **Auto-filing the GitHub issue.** Outward actions need confirmation.
+
+</anti_patterns>
+
+<success_criteria>
+
+- [ ] The symptom is quoted, not paraphrased.
+- [ ] Every claim in the evidence trail cites a file and a line or field.
+- [ ] The root cause names a specific file, function, or state transition.
+- [ ] The proposed fix is minimal and falsifiable.
+- [ ] Confidence is stated honestly.
+- [ ] Report is saved under `.gsd/forensics/` even if not filed as an issue.
+
+</success_criteria>

package/src/resources/skills/grill-me/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: grill-me
+description: Relentless sequential interview that stress-tests a plan or design until every decision branch is resolved. Use when the user wants to "grill me", "stress-test the plan", "interrogate my design", "resolve the decision tree", or whenever a plan feels hand-wavy, under-specified, or carries hidden coupling that planning phases must surface before execution. Pairs with the discuss phase and blocks execution until alignment is reached.
+---
+
+<objective>
+Interview the user one question at a time until every material branch of the decision tree is resolved and you both share one mental model of the plan. Output is not a document — it is alignment. Surface hidden assumptions, kill fuzzy language, and walk the dependencies between decisions instead of asking everything in parallel.
+</objective>
+
+<context>
+Planning conversations in GSD ship to `M###-CONTEXT.md`, `S##-CONTEXT.md`, or `.gsd/DECISIONS.md`. Those artifacts are only as good as the interview that produced them. This skill is the interview. It runs during the `discuss` phase, after `research`, or any time a plan has open branches the user has not actually thought through.
+
+Use this skill when:
+- The user asks to be grilled, stress-tested, or interrogated
+- A plan reads like a list of happy paths with no failure modes
+- Two or more sections of a plan implicitly depend on one undecided choice
+- The user says "I think" or "probably" about something that will bind the design
+</context>
+
+<core_principle>
+**ONE QUESTION AT A TIME.** Parallel questions destroy dependency order — the answer to Q2 is often contingent on the answer to Q1, and asking both at once forces the user to reason about a combinatoric space instead of a single fork. Ask, wait, absorb, ask the next.
+
+**RECOMMEND AN ANSWER.** Every question ships with your recommendation and a one-line reason. The user's job is to confirm, override, or redirect — not to generate answers from scratch.
+
+**CODEBASE BEFORE QUESTION.** If the answer exists in the repo — a convention, an existing pattern, a prior decision — find it and cite it rather than asking.
+</core_principle>
+
+<process>
+
+## Step 1: Map the decision tree silently
+
+Before asking anything, read what the user has already said in this conversation plus any existing `M###-CONTEXT.md`, `S##-CONTEXT.md`, and `.gsd/DECISIONS.md`. Build a private list of every decision the plan depends on, in dependency order. Do not show this list — it is scaffolding.
+
+If the plan touches unfamiliar code, spawn `Agent(subagent_type=Explore)` in parallel to map the relevant modules while you prepare Question 1. Do not wait for it to finish before starting the interview.
+
+## Step 2: Ask Question 1
+
+Pick the root decision — the one that the most other decisions depend on. Format:
+
+```text
+**Q1:** <precise question>.
+
+**Recommendation:** <your pick>, because <one sentence>.
+
+Alternatives worth considering: <A | B | C>.
+```
+
+Stop. Wait for the answer.
+
+## Step 3: Absorb and branch
+
+Take the answer. If it kills branches of the tree, cross them off your private map. If it opens new branches, add them. Do not move on to Q2 until the current answer has been integrated. If the answer is ambiguous, ask one clarifying follow-up — not three.
+
+## Step 4: Continue until the tree is closed
+
+Repeat Q2, Q3, … in dependency order. Each question follows the same format (question, recommendation, alternatives). Cap at the natural end of the decision tree, not a round number.
+
+Stop the interview when:
+- Every remaining open decision is either deferred by explicit user choice ("decide at execution time") or out of scope
+- The user says to stop
+- You have nothing left where the answer would materially change the plan
+
+## Step 5: Offer to write it up
+
+At the end, offer the user one of:
+
+1. Append resolved decisions to `.gsd/DECISIONS.md` (one line each, dated).
+2. Write or update `M###-CONTEXT.md` or `S##-CONTEXT.md` for the active milestone/slice.
+3. Draft a GitHub issue via `mcp__github__issue_write` (only with explicit confirmation per the outward-action rule).
+4. Leave it as conversation context if the work is ephemeral.
+
+Default: ask which they want. Do not auto-write.
+
+</process>
+
+<anti_patterns>
+
+- **Parallel questions:** "What's the schema? And the API? And the auth model?" — ask one.
+- **Yes/no railroading:** "Should we use X?" instead of "Between X and Y, which fits — given Z constraint?"
+- **Recommendation-free questions:** forces the user to generate from scratch; you have more context than you think.
+- **Asking what the code already answers:** check the repo first.
+- **Grilling past the useful horizon:** if the next question is about an implementation detail that will be decided during execution, stop.
+
+</anti_patterns>
+
+<success_criteria>
+
+- [ ] Every decision with cross-cutting impact has an answer.
+- [ ] No "probably", "I think", or "we'll figure it out" remains on load-bearing decisions.
+- [ ] The user has confirmed the shape of the plan, not just each individual answer.
+- [ ] Resolved decisions are captured in an enduring artifact or explicitly left ephemeral.
+
+</success_criteria>

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

@@ -0,0 +1,121 @@
+---
+name: handoff
+description: Prepare a clean cross-session handoff so the next agent (or you tomorrow) can pick up exactly where you left off. Writes a focused `continue.md` in the active slice directory and ensures `STATE.md` + summary artifacts are current. Use when asked to "hand off", "prepare handoff", "pause work", "bookmark this", "I'll come back to this later", before running out of context budget, or at the end of a long session with unfinished work. Closes the v1 `/gsd-pause-work` parity gap.
+---
+
+<objective>
+Leave the project in a state where a fresh agent with no memory of this session can read two or three files and be productive within one minute. The deliverable is `continue.md` in the active slice directory plus up-to-date summary artifacts — not a chat recap.
+</objective>
+
+<context>
+GSD already writes `STATE.md` (rebuilt after each unit) and summary files (`M###-SUMMARY.md`, `S##-SUMMARY.md`, `T##-SUMMARY.md`). The gap is the *mid-task* handoff: you're partway through a task, context is getting long, and the next session shouldn't start by re-deriving your mental state.
+
+`continue.md` exists for exactly this — see `auto-prompts.ts`, `guided-flow.ts`, `phase-anchor.ts`, `state.ts`. This skill is the deliberate authoring ritual.
+
+Invocation points:
+- User says "pause", "hand off", "I'll come back later", "this is a good stopping point"
+- Context usage nearing budget — better to hand off cleanly than truncate mid-thought
+- Before a risky operation (dependency upgrade, major refactor) where you want a known-good checkpoint
+- End of a long session, multi-day work
+</context>
+
+<core_principle>
+**WRITE FOR A STRANGER.** The next reader is not you. They do not have this conversation. They have `STATE.md`, `continue.md`, the last summary, and the code. That has to be enough.
+
+**CURRENT STATE ONLY.** `continue.md` is ephemeral — it says "pick up HERE." It is not a log of what you did; that goes in summaries. It is not a plan for future work; that lives in the plan files.
+
+**NO SECRETS, NO STALE PATHS.** Do not inline env values, tokens, or paths that only exist in your working directory. Cite artifacts by relative path from the project root.
+</core_principle>
+
+<process>
+
+## Step 1: Identify what's in flight
+
+Answer briefly:
+1. What task (`T##`) am I on? What's its current plan file?
+2. What have I completed since the last summary?
+3. What's the next concrete action? (Not a goal — an action: "Run X. If Y, do Z.")
+4. What, if anything, is blocking or uncertain?
+
+## Step 2: Update the summaries, not the handoff
+
+Before writing `continue.md`:
+
+- **Any task that's actually done?** Use `gsd_task_complete` (or the equivalent tool) to toggle state. Do NOT edit checkboxes by hand. This triggers `STATE.md` rebuild and `T##-SUMMARY.md` generation.
+- **Any slice-level decisions worth preserving?** Append to `S##-CONTEXT.md` if the slice has one, or `.gsd/DECISIONS.md` if the decision was project-wide.
+- **Any patterns or traps future agents should know about?** Append a single line to `.gsd/KNOWLEDGE.md`.
+
+This shrinks what `continue.md` has to carry.
+
+## Step 3: Write continue.md
+
+Create `.gsd/milestones/<MID>/slices/<SID>/continue.md` with the following shape. Keep it tight — one screenful max.
+
+```markdown
+# Continue — S02 / T03
+
+## Last action
+
+<one sentence — what you just did, with evidence>
+Example: "Ran `npm test` after editing `src/auth/session.ts`; 2 failures in `session.test.ts` — both complain about a missing `expiresAt` field in the mock fixture."
+
+## Next action
+
+<one concrete action the next agent should take>
+Example: "Update `fixtures/sessions.ts` to include `expiresAt: Date.now() + 3600_000` on every fixture, then re-run `npm test`."
+
+## Why
+
+<one or two sentences — why this next step, not something else>
+Example: "The session refactor moved `expiresAt` from optional to required in `Session`; fixtures were never updated."
+
+## Open threads
+
+<list of things you noticed but deliberately didn't act on>
+- Validator in `src/auth/validator.ts` still accepts unbounded session lengths — file as a separate issue after T03 lands.
+
+## Do not
+
+<traps and false paths the next agent might stumble into>
+- Do NOT revert the `Session` interface change — it's required for T04.
+- Do NOT run `npm run db:reset` in this branch; dev data is still needed for manual UAT.
+```
+
+## Step 4: Sanity check
+
+Read `STATE.md` + `continue.md` + the most recent summary as if you were a fresh agent. Ask:
+1. Do I know what to do next?
+2. Do I know why?
+3. Do I know what not to do?
+
+If any answer is no, the handoff is incomplete. Fix it before stopping.
+
+## Step 5: Stop cleanly
+
+- Do not leave in-flight `async_bash` or `bg_shell` jobs. Cancel or wait for them.
+- Do not leave uncommitted changes without flagging them in `continue.md` — note which files are modified and why.
+- Do not push mid-task commits to remote unless that was the plan — they create noise for reviewers.
+
+</process>
+
+<anti_patterns>
+
+- **Chat-log handoffs.** "First I did X, then Y, then Z…" The next agent doesn't need the journey.
+- **`continue.md` that summarizes the whole slice.** That's what `S##-SUMMARY.md` is for, at slice completion.
+- **No "Next action".** A handoff without a concrete next action is a journal entry.
+- **Implicit assumptions.** "Obviously the next thing is…" — write it down.
+- **Leaving background processes running.** They'll be orphaned when the session ends.
+- **Handoff without updating summaries.** `continue.md` should be thin because the summaries carry the weight.
+
+</anti_patterns>
+
+<success_criteria>
+
+- [ ] `continue.md` exists in the active slice directory.
+- [ ] The "Next action" is concrete and executable without this session's context.
+- [ ] Completed tasks were marked done via `gsd_*` tools, not by hand-edited checkboxes.
+- [ ] `KNOWLEDGE.md` and `DECISIONS.md` have been updated if anything notable was learned.
+- [ ] Background processes are not orphaned.
+- [ ] A cold-read of `STATE.md` + `continue.md` + latest summary would produce the right next action.
+
+</success_criteria>