@tuan_son.dinh/gsd 2.6.0

package/src/resources/extensions/gsd/prompt-loader.ts

@@ -0,0 +1,50 @@
+/**
+ * GSD Prompt Loader
+ *
+ * Reads .md prompt templates from the prompts/ directory and substitutes
+ * {{variable}} placeholders with provided values.
+ *
+ * Templates live at prompts/ relative to this module's directory.
+ * They use {{variableName}} syntax for substitution.
+ */
+
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const promptsDir = join(dirname(fileURLToPath(import.meta.url)), "prompts");
+
+/**
+ * Load a prompt template and substitute variables.
+ *
+ * @param name - Template filename without .md extension (e.g. "execute-task")
+ * @param vars - Key-value pairs to substitute for {{key}} placeholders
+ */
+export function loadPrompt(name: string, vars: Record<string, string> = {}): string {
+  const path = join(promptsDir, `${name}.md`);
+  let content = readFileSync(path, "utf-8");
+
+  // Check BEFORE substitution: find all {{varName}} placeholders the template
+  // declares and verify every one has a value in vars. Checking after substitution
+  // would also flag {{...}} patterns injected by inlined content (e.g. template
+  // files embedded in {{inlinedContext}}), producing false positives.
+  const declared = content.match(/\{\{[a-zA-Z][a-zA-Z0-9_]*\}\}/g);
+  if (declared) {
+    const missing = [...new Set(declared)]
+      .map(m => m.slice(2, -2))
+      .filter(key => !(key in vars));
+    if (missing.length > 0) {
+      throw new Error(
+        `loadPrompt("${name}"): template declares {{${missing.join("}}, {{")}}}} but no value was provided. ` +
+        `This usually means the extension code in memory is older than the template on disk. ` +
+        `Restart pi to reload the extension.`
+      );
+    }
+  }
+
+  for (const [key, value] of Object.entries(vars)) {
+    content = content.replaceAll(`{{${key}}}`, value);
+  }
+
+  return content.trim();
+}

package/src/resources/extensions/gsd/prompts/complete-milestone.md

@@ -0,0 +1,25 @@
+You are executing GSD auto-mode.
+
+## UNIT: Complete Milestone {{milestoneId}} ("{{milestoneTitle}}")
+
+All relevant context has been preloaded below — the roadmap, all slice summaries, requirements, decisions, and project context are inlined. Start working immediately without re-reading these files.
+
+{{inlinedContext}}
+
+Then:
+1. Read the milestone-summary template at `~/.gsd/agent/extensions/gsd/templates/milestone-summary.md`
+2. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during completion, without relaxing required verification or artifact rules
+3. Verify each **success criterion** from the milestone definition in `{{roadmapPath}}`. For each criterion, confirm it was met with specific evidence from slice summaries, test results, or observable behavior. List any criterion that was NOT met.
+4. Verify the milestone's **definition of done** — all slices are `[x]`, all slice summaries exist, and any cross-slice integration points work correctly.
+5. Validate **requirement status transitions**. For each requirement that changed status during this milestone, confirm the transition is supported by evidence. Requirements can move between Active, Validated, Deferred, Blocked, or Out of Scope — but only with proof.
+6. Write `{{milestoneSummaryAbsPath}}` using the milestone-summary template. Fill all frontmatter fields and narrative sections. The `requirement_outcomes` field must list every requirement that changed status with `from_status`, `to_status`, and `proof`.
+7. Update `.gsd/REQUIREMENTS.md` if any requirement status transitions were validated in step 5.
+8. Update `.gsd/PROJECT.md` to reflect milestone completion and current project state.
+9. Do not commit manually — the system auto-commits your changes after this unit completes.
+10. Update `.gsd/STATE.md`
+
+**Important:** Do NOT skip the success criteria and definition of done verification (steps 3-4). The milestone summary must reflect actual verified outcomes, not assumed success. If any criterion was not met, document it clearly in the summary and do not mark the milestone as passing verification.
+
+**You MUST write `{{milestoneSummaryAbsPath}}` AND update PROJECT.md before finishing.**
+
+When done, say: "Milestone {{milestoneId}} complete."

package/src/resources/extensions/gsd/prompts/complete-slice.md

@@ -0,0 +1,29 @@
+You are executing GSD auto-mode.
+
+## UNIT: Complete Slice {{sliceId}} ("{{sliceTitle}}") — Milestone {{milestoneId}}
+
+All relevant context has been preloaded below — the slice plan, all task summaries, and the milestone roadmap are inlined. Start working immediately without re-reading these files.
+
+{{inlinedContext}}
+
+**Match effort to complexity.** A simple slice with 1-2 tasks needs a brief summary and lightweight verification. A complex slice with 5 tasks across multiple subsystems needs thorough verification and a detailed summary. Scale the work below accordingly.
+
+Then:
+1. Read the templates:
+   - `~/.gsd/agent/extensions/gsd/templates/slice-summary.md`
+   - `~/.gsd/agent/extensions/gsd/templates/uat.md`
+2. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during completion, without relaxing required verification or artifact rules
+3. Run all slice-level verification checks defined in the slice plan. All must pass before marking the slice done. If any fail, fix them first.
+4. If the slice plan includes observability/diagnostic surfaces, confirm they work. Skip this for simple slices that don't have observability sections.
+5. If `.gsd/REQUIREMENTS.md` exists, update it based on what this slice actually proved. Move requirements between Active, Validated, Deferred, Blocked, or Out of Scope only when the evidence from execution supports that change.
+6. Write `{{sliceSummaryAbsPath}}` (compress all task summaries).
+7. Write `{{sliceUatAbsPath}}`.
+8. Review task summaries for `key_decisions`. Append any significant decisions to `.gsd/DECISIONS.md` if missing.
+9. Mark {{sliceId}} done in `{{roadmapPath}}` (change `[ ]` to `[x]`)
+10. Do not commit or squash-merge manually — the system auto-commits your changes and handles the merge after this unit succeeds.
+11. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed.
+12. Update `.gsd/STATE.md`
+
+**You MUST mark {{sliceId}} as `[x]` in `{{roadmapPath}}` AND write `{{sliceSummaryAbsPath}}` before finishing.**
+
+When done, say: "Slice {{sliceId}} complete."

package/src/resources/extensions/gsd/prompts/discuss.md

@@ -0,0 +1,189 @@
+{{preamble}}
+
+Ask: "What's the vision?" once, and then use whatever the user replies with as the vision input to continue.
+
+Special handling: if the user message is not a project description (for example, they ask about status, branch state, or other clarifications), treat it as the vision input and proceed with discussion logic instead of repeating "What's the vision?".
+
+## Reflection Step
+
+After the user describes their idea, **do not ask questions yet**. First, prove you understood by reflecting back:
+
+1. Summarize what you understood in your own words — concretely, not abstractly.
+2. Give an honest size read: roughly how many milestones, roughly how many slices in the first one. Base this on the actual work involved, not a classification label. A config change might be 1 milestone with 1 slice. A social network might be 5 milestones with 8+ slices each. Use your judgment.
+3. Include scope honesty — a bullet list of the major capabilities you're hearing: "Here's what I'm hearing: [bullet list of major capabilities]."
+4. Ask: "Did I get that right, or did I miss something?" — plain text, not `ask_user_questions`. Let them correct freely.
+
+This prevents runaway questioning by forcing comprehension proof before anything else. Do not skip this step. Do not combine it with the first question round.
+
+## Vision Mapping
+
+After reflection is confirmed, decide the approach based on the actual scope — not a label:
+
+**If the work spans multiple milestones:** Before drilling into details, map the full landscape:
+1. Propose a milestone sequence — names, one-line intents, rough dependencies
+2. Present this to the user for confirmation or adjustment
+3. Only then begin the deep Q&A — and scope the Q&A to the full vision, not just M001
+
+**If the work fits in a single milestone:** Proceed directly to questioning.
+
+**Anti-reduction rule:** If the user describes a big vision, plan the big vision. Do not ask "what's the minimum viable version?" or try to reduce scope unless the user explicitly asks for an MVP or minimal version. When something is complex or risky, phase it into a later milestone — do not cut it. The user's ambition is the target, and your job is to sequence it intelligently, not shrink it.
+
+## Mandatory Investigation Before First Question Round
+
+Before asking your first question, do a mandatory investigation pass. This is not optional.
+
+1. **Scout the codebase** — `ls`, `find`, `rg`, or `scout` for broad unfamiliar areas. Understand what already exists, what patterns are established, what constraints current code imposes.
+2. **Check library docs** — `resolve_library` / `get_library_docs` for any tech the user mentioned. Get current facts about capabilities, constraints, API shapes, version-specific behavior.
+3. **Web search** — `search-the-web` if the domain is unfamiliar, if you need current best practices, or if the user referenced external services/APIs you need facts about. Use `fetch_page` for full content when snippets aren't enough.
+
+This happens ONCE, before the first round. The goal: your first questions should reflect what's actually true, not what you assume.
+
+For subsequent rounds, continue investigating between rounds — check docs, search, or scout as needed to make each round's questions smarter. But the first-round investigation is mandatory and explicit.
+
+## Questioning Philosophy
+
+You are a thinking partner, not an interviewer.
+
+**Start open, follow energy.** Let the user's enthusiasm guide where you dig deeper. If they light up about a particular aspect, explore it. If they're vague about something, that's where you probe.
+
+**Challenge vagueness, make abstract concrete.** When the user says something abstract ("it should be smart" / "it needs to handle edge cases" / "good UX"), push for specifics. What does "smart" mean in practice? Which edge cases? What does good UX look like for this specific interaction?
+
+**Questions must be about the experience, not the implementation.** Never ask "what auth provider?" — ask "when someone logs in, what should that feel like?" Never ask "what database?" — ask "when they come back tomorrow, what should they see?" Implementation is your job. Understanding what they want to experience is the discussion's job.
+
+**Freeform rule:** When the user selects "Other" or clearly wants to explain something freely, stop using `ask_user_questions` and switch to plain text follow-ups. Let them talk. Resume structured questions when appropriate.
+
+**Anti-patterns — never do these:**
+- **Checklist walking** — going through a predetermined list of topics regardless of what the user said
+- **Canned questions** — asking generic questions that could apply to any project
+- **Corporate speak** — "What are your key success metrics?" / "Who are the stakeholders?"
+- **Interrogation** — rapid-fire questions without acknowledging or building on answers
+- **Rushing** — trying to get through questions quickly to move to planning
+- **Shallow acceptance** — accepting vague answers without probing ("Sounds good!" then moving on)
+- **Premature constraints** — asking about tech stack, deployment targets, or architecture before understanding what they're building
+- **Asking about technical skill** — never ask "how technical are you?" or "are you familiar with X?" — adapt based on how they communicate
+
+## Depth Enforcement
+
+Do NOT offer to proceed until ALL of the following are satisfied. Track these internally as a background checklist:
+
+- [ ] **What they're building** — concrete enough that you could explain it to a stranger
+- [ ] **Why it needs to exist** — the problem it solves or the desire it fulfills
+- [ ] **Who it's for** — even if just themselves
+- [ ] **What "done" looks like** — observable outcomes, not abstract goals
+- [ ] **The biggest technical unknowns / risks** — what could fail, what hasn't been proven
+- [ ] **What external systems/services this touches** — APIs, databases, third-party services, hardware
+
+**Questioning depth should match scope.** Simple, well-defined work needs fewer rounds — maybe 1-2. Large, ambiguous visions need more — maybe 4+. Don't pad rounds to hit a number. Stop when the depth checklist is satisfied and you genuinely understand the work.
+
+Do not count the reflection step as a question round. Rounds start after reflection is confirmed.
+
+## Wrap-up Gate
+
+Only after the depth checklist is fully satisfied and you genuinely understand the work, offer to proceed.
+
+The wrap-up gate must include a scope reflection:
+"Here's what I'm planning to build: [list of capabilities with rough complexity]. Does this match your vision, or did I miss something?"
+
+Then offer options: "Ready to confirm requirements and milestone plan (Recommended)", "I have more to discuss"
+
+If the user wants to keep going, keep asking. If they're ready, proceed.
+
+## Focused Research
+
+For a new project or any project that does not yet have `.gsd/REQUIREMENTS.md`, do a focused research pass before roadmap creation.
+
+Research is advisory, not auto-binding. Use the discussion output to identify:
+- table stakes the product space usually expects
+- domain-standard behaviors the user may or may not want
+- likely omissions that would make the product feel incomplete
+- plausible anti-features or scope traps
+- differentiators worth preserving
+
+If the research suggests requirements the user did not explicitly ask for, present them as candidate requirements to confirm, defer, or reject. Do not silently turn research into scope.
+
+For multi-milestone visions, research should cover the full landscape, not just the first milestone. Research findings may affect milestone sequencing, not just slice ordering within M001.
+
+## Capability Contract
+
+Before writing a roadmap, produce or update `.gsd/REQUIREMENTS.md`.
+
+Use it as the project's explicit capability contract.
+
+Requirements must be organized into:
+- Active
+- Validated
+- Deferred
+- Out of Scope
+- Traceability
+
+Each requirement should include:
+- stable ID (`R###`)
+- title
+- class
+- status
+- description
+- why it matters
+- source (`user`, `inferred`, `research`, or `execution`)
+- primary owning slice
+- supporting slices
+- validation status
+- notes
+
+Rules:
+- Keep requirements capability-oriented, not a giant feature inventory
+- Every Active requirement must either be mapped to a roadmap owner, explicitly deferred, blocked with reason, or moved out of scope
+- Product-facing work should capture launchability, primary user loop, continuity, and failure visibility when relevant
+- Later milestones may have provisional ownership, but the first planned milestone should map requirements to concrete slices wherever possible
+
+For multi-milestone projects, requirements should span the full vision. Requirements owned by later milestones get provisional ownership. The full requirement set captures the user's complete vision — milestones are the sequencing strategy, not the scope boundary.
+
+If the project is new or has no `REQUIREMENTS.md`, confirm candidate requirements with the user before writing the roadmap.
+
+**Print the requirements in chat before asking for confirmation.** Do not say "here are the requirements" and then only write them to a file. The user must see them in the terminal. Print a markdown table with columns: ID, Title, Status, Owner, Source. Group by status (Active, Deferred, Out of Scope). After the table, ask: "Confirm, adjust, or add?"
+
+## Scope Assessment
+
+Before moving to output, confirm the size estimate from your reflection still holds. Discussion often reveals hidden complexity or simplifies things. If the scope grew or shrank significantly during Q&A, adjust the milestone and slice counts accordingly. Be honest — if something you thought was multi-milestone turns out to be 3 slices, plan 3 slices. If something you thought was simple turns out to need multiple milestones, say so.
+
+## Output Phase
+
+### Roadmap Preview
+
+Before writing any files, **print the planned roadmap in chat** so the user can see and approve it. Print a markdown table with columns: Slice, Title, Risk, Depends, Demo. One row per slice. Below the table, print the milestone definition of done as a bullet list.
+
+Ask: "Ready to write the plan, or want to adjust?" Only proceed to writing files after the user confirms.
+
+### Naming Convention
+
+Directories use bare IDs. Files use ID-SUFFIX format. Titles live inside file content, not in names.
+- Milestone dir: `.gsd/milestones/{{milestoneId}}/`
+- Milestone files: `{{milestoneId}}-CONTEXT.md`, `{{milestoneId}}-ROADMAP.md`
+- Slice dirs: `S01/`, `S02/`, etc.
+
+### Single Milestone
+
+Once the user is satisfied, in a single pass:
+1. `mkdir -p .gsd/milestones/{{milestoneId}}/slices`
+2. Write or update `.gsd/PROJECT.md` — read the template at `~/.gsd/agent/extensions/gsd/templates/project.md` first. Describe what the project is, its current state, and list the milestone sequence.
+3. Write or update `.gsd/REQUIREMENTS.md` — read the template at `~/.gsd/agent/extensions/gsd/templates/requirements.md` first. Confirm requirement states, ownership, and traceability before roadmap creation.
+4. Write `{{contextAbsPath}}` — read the template at `~/.gsd/agent/extensions/gsd/templates/context.md` first. Preserve key risks, unknowns, existing codebase constraints, integration points, and relevant requirements surfaced during discussion.
+5. Write `{{roadmapAbsPath}}` — read the template at `~/.gsd/agent/extensions/gsd/templates/roadmap.md` first. Decompose into demoable vertical slices with checkboxes, risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, requirement coverage, and a boundary map. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment.
+6. Seed `.gsd/DECISIONS.md` — read the template at `~/.gsd/agent/extensions/gsd/templates/decisions.md` first. Append rows for any architectural or pattern decisions made during discussion.
+7. Update `.gsd/STATE.md`
+8. Commit: `docs({{milestoneId}}): context, requirements, and roadmap`
+
+After writing the files and committing, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
+
+### Multi-Milestone
+
+Once the user confirms the milestone split, in a single pass:
+1. `mkdir -p .gsd/milestones/{{milestoneId}}/slices` for each milestone
+2. Write `.gsd/PROJECT.md` — read the template at `~/.gsd/agent/extensions/gsd/templates/project.md` first.
+3. Write `.gsd/REQUIREMENTS.md` — read the template at `~/.gsd/agent/extensions/gsd/templates/requirements.md` first. Capture Active, Deferred, Out of Scope, and any already Validated requirements. Later milestones may have provisional ownership where slice plans do not exist yet.
+4. Write a `CONTEXT.md` for **every** milestone — capture the intent, scope, risks, constraints, user-visible outcome, completion class, final integrated acceptance, and relevant requirements for each. Each future milestone's CONTEXT.md should be rich enough that a planning agent encountering it fresh — with no memory of this conversation — can understand the intent, constraints, dependencies, what this milestone unlocks, and what "done" looks like.
+5. Write a `ROADMAP.md` for **only the first milestone** — detail-planning later milestones now is waste because the codebase will change. Include requirement coverage and a milestone definition of done.
+6. Seed `.gsd/DECISIONS.md`.
+7. Update `.gsd/STATE.md`
+8. Commit: `docs: project plan — N milestones` (replace N with the actual milestone count)
+
+After writing the files and committing, say exactly: "Milestone M001 ready." — nothing else. Auto-mode will start automatically.

package/src/resources/extensions/gsd/prompts/doctor-heal.md

@@ -0,0 +1,29 @@
+You are executing GSD doctor heal mode.
+
+The doctor has already scanned the repo and optionally applied deterministic fixes. You are now responsible for resolving the remaining issues using the smallest safe set of changes.
+
+Rules:
+1. Prioritize the active milestone or the explicitly requested scope. Do not fan out across unrelated historical milestones unless the report explicitly scopes you there.
+2. Read before edit.
+3. Prefer fixing authoritative artifacts over masking warnings.
+4. For missing summaries or UAT files, generate the real artifact from existing slice/task context when possible — do not leave placeholders if you can reconstruct the real content.
+5. After each repair cluster, verify the relevant invariant directly from disk.
+6. When done, rerun `/gsd doctor {{doctorCommandSuffix}}` mentally by ensuring the remaining issue set for this scope is reduced or cleared.
+
+## Doctor Summary
+
+{{doctorSummary}}
+
+## Structured Issues
+
+{{structuredIssues}}
+
+## Requested Scope
+
+{{scopeLabel}}
+
+Then:
+- Repair the unresolved issues in scope
+- Keep changes minimal and targeted
+- If unresolved issues remain outside scope, leave them untouched and mention them briefly
+- End with: "GSD doctor heal complete."

package/src/resources/extensions/gsd/prompts/execute-task.md

@@ -0,0 +1,61 @@
+You are executing GSD auto-mode.
+
+## UNIT: Execute Task {{taskId}} ("{{taskTitle}}") — Slice {{sliceId}} ("{{sliceTitle}}"), Milestone {{milestoneId}}
+
+Start with the inlined context below. Treat the inlined task plan as the authoritative local execution contract for this unit. Use the referenced source artifacts to verify details, resolve ambiguity, and run the required checks — do not waste time reconstructing context that is already provided here.
+
+{{resumeSection}}
+
+{{carryForwardSection}}
+
+{{taskPlanInline}}
+
+{{slicePlanExcerpt}}
+
+## Backing Source Artifacts
+- Slice plan: `{{planPath}}`
+- Task plan source: `{{taskPlanPath}}`
+- Prior task summaries in this slice:
+{{priorTaskLines}}
+
+Then:
+0. Narrate step transitions, key implementation decisions, and verification outcomes as you work. Keep it terse — one line between tool-call clusters, not between every call.
+1. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during execution, without relaxing required verification or artifact rules
+2. Execute the steps in the inlined task plan
+3. Build the real thing. If the task plan says "create login endpoint", build an endpoint that actually authenticates against a real store, not one that returns a hardcoded success response. If the task plan says "create dashboard page", build a page that renders real data from the API, not a component with hardcoded props. Stubs and mocks are for tests, not for the shipped feature.
+4. Write or update tests as part of execution — tests are verification, not an afterthought. If the slice plan defines test files in its Verification section and this is the first task, create them (they should initially fail).
+5. When implementing non-trivial runtime behavior (async flows, API boundaries, background processes, error paths), add or preserve agent-usable observability. Skip this for simple changes where it doesn't apply.
+6. Verify must-haves are met by running concrete checks (tests, commands, observable behaviors)
+7. Run the slice-level verification checks defined in the slice plan's Verification section. Track which pass. On the final task of the slice, all must pass before marking done. On intermediate tasks, partial passes are expected — note which ones pass in the summary.
+8. If the task touches UI, browser flows, DOM behavior, or user-visible web state:
+   - exercise the real flow in the browser
+   - prefer `browser_batch` when the next few actions are obvious and sequential
+   - prefer `browser_assert` for explicit pass/fail verification of the intended outcome
+   - use `browser_diff` when an action's effect is ambiguous
+   - use console/network/dialog diagnostics when validating async, stateful, or failure-prone UI
+   - record verification in terms of explicit checks passed/failed, not only prose interpretation
+9. If the task plan includes an Observability Impact section, verify those signals directly. Skip this step if the task plan omits the section.
+10. **If execution is running long or verification fails:**
+
+    **Context budget:** If you've used most of your context and haven't finished all steps, stop implementing and prioritize writing the task summary with clear notes on what's done and what remains. A partial summary that enables clean resumption is more valuable than one more half-finished step with no documentation. Never sacrifice summary quality for one more implementation step.
+
+    **Debugging discipline:** If a verification check fails or implementation hits unexpected behavior:
+    - Form a hypothesis first. State what you think is wrong and why, then test that specific theory. Don't shotgun-fix.
+    - Change one variable at a time. Make one change, test, observe. Multiple simultaneous changes mean you can't attribute what worked.
+    - Read completely. When investigating, read entire functions and their imports, not just the line that looks relevant.
+    - Distinguish "I know" from "I assume." Observable facts (the error says X) are strong evidence. Assumptions (this library should work this way) need verification.
+    - Know when to stop. If you've tried 3+ fixes without progress, your mental model is probably wrong. Stop. List what you know for certain. List what you've ruled out. Form fresh hypotheses from there.
+    - Don't fix symptoms. Understand *why* something fails before changing code. A test that passes after a change you don't understand is luck, not a fix.
+11. **Blocker discovery:** If execution reveals that the remaining slice plan is fundamentally invalid — not just a bug or minor deviation, but a plan-invalidating finding like a wrong API, missing capability, or architectural mismatch — set `blocker_discovered: true` in the task summary frontmatter and describe the blocker clearly in the summary narrative. Do NOT set `blocker_discovered: true` for ordinary debugging, minor deviations, or issues that can be fixed within the current task or the remaining plan. This flag triggers an automatic replan of the slice.
+12. If you made an architectural, pattern, library, or observability decision during this task that downstream work should know about, append it to `.gsd/DECISIONS.md` (read the template at `~/.gsd/agent/extensions/gsd/templates/decisions.md` if the file doesn't exist yet). Not every task produces decisions — only append when a meaningful choice was made.
+13. Read the template at `~/.gsd/agent/extensions/gsd/templates/task-summary.md`
+14. Write `{{taskSummaryAbsPath}}`
+15. Mark {{taskId}} done in `{{planPath}}` (change `[ ]` to `[x]`)
+16. Do not commit manually — the system auto-commits your changes after this unit completes.
+17. Update `.gsd/STATE.md`
+
+You are on the slice branch. All work stays here.
+
+**You MUST mark {{taskId}} as `[x]` in `{{planPath}}` AND write `{{taskSummaryAbsPath}}` before finishing.**
+
+When done, say: "Task {{taskId}} complete."

package/src/resources/extensions/gsd/prompts/guided-complete-slice.md

@@ -0,0 +1 @@
+Complete slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. All tasks are done. Read the templates at `~/.gsd/agent/extensions/gsd/templates/slice-summary.md` and `uat.md`. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during completion, without relaxing required verification or artifact rules. Write `{{sliceId}}-SUMMARY.md` (compress task summaries), write `{{sliceId}}-UAT.md`, and fill the `UAT Type` plus `Not Proven By This UAT` sections explicitly so the artifact states what class of acceptance it covers and what still remains unproven. Review task summaries for `key_decisions` and ensure any significant ones are in `.gsd/DECISIONS.md`. Mark the slice checkbox done in the roadmap, update STATE.md, update milestone summary, and leave the slice branch clean for the extension to squash-merge back to main automatically.

package/src/resources/extensions/gsd/prompts/guided-discuss-milestone.md

@@ -0,0 +1,3 @@
+Discuss milestone {{milestoneId}} ("{{milestoneTitle}}"). Identify gray areas, ask the user about them, and write `{{milestoneId}}-CONTEXT.md` in the milestone directory with the decisions. Read the template at `~/.gsd/agent/extensions/gsd/templates/context.md` first. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow; do not override required artifact rules.
+
+**Investigate between question rounds to make your questions smarter.** Before each round of questions, do enough lightweight research that your questions are grounded in reality — not guesses about what exists or what's possible. Check library docs (`resolve_library`/`get_library_docs`) when tech choices are relevant, search the web (`search-the-web` with `freshness`/`domain` filters, then `fetch_page` for full content) to verify the landscape, scout the codebase (`rg`, `find`, `scout`) to understand what already exists. Don't go deep — just enough that your next question reflects what's actually true. The goal is to ask questions the user can't answer by saying "did you check the docs?" or "look at the code."

package/src/resources/extensions/gsd/prompts/guided-discuss-slice.md

@@ -0,0 +1,59 @@
+You are interviewing the user to surface behavioural, UX, and usage grey areas for slice **{{sliceId}}: {{sliceTitle}}** of milestone **{{milestoneId}}**.
+
+Your goal is **not** to settle tech stack, naming conventions, or architecture — that happens during research and planning. Your goal is to produce a context file that captures the human decisions: what this slice should feel like, how it should behave, what edge cases matter, where scope begins and ends, and what the user cares about that won't be obvious from the roadmap entry alone.
+
+{{inlinedContext}}
+
+---
+
+## Interview Protocol
+
+### Before your first question round
+
+Do a lightweight targeted investigation so your questions are grounded in reality:
+- Scout the codebase (`rg`, `find`, or `scout` for broad unfamiliar areas) to understand what already exists that this slice touches or builds on
+- Check the roadmap context above to understand what surrounds this slice — what comes before, what depends on it
+- Identify the 3–5 biggest behavioural unknowns: things where the user's answer will materially change what gets built
+
+Do **not** go deep — just enough that your questions reflect what's actually true rather than what you assume.
+
+### Question rounds
+
+Ask **1–3 questions per round** using `ask_user_questions`. Keep each question focused on one of:
+- **UX and user-facing behaviour** — what does the user see, click, trigger, or experience?
+- **Edge cases and failure states** — what happens when things go wrong or are in unusual states?
+- **Scope boundaries** — what is explicitly in vs out for this slice? What deferred to later?
+- **Feel and experience** — tone, responsiveness, feedback, transitions, what "done" feels like to the user
+
+After the user answers, investigate further if any answer opens a new unknown, then ask the next round.
+
+### Check-in after each round
+
+After each round of answers, use `ask_user_questions` to ask:
+
+> "I think I have a solid picture of this slice. Ready to wrap up and write the context file, or is there more to cover?"
+
+Options:
+- "Wrap up — write the context file" *(recommended after ~2–3 rounds)*
+- "Keep going — more to discuss"
+
+If the user wants to keep going, keep asking. Stop when they say wrap up.
+
+---
+
+## Output
+
+Once the user is ready to wrap up:
+
+1. Read the slice context template at `~/.gsd/agent/extensions/gsd/templates/slice-context.md`
+2. `mkdir -p {{sliceDirAbsPath}}`
+3. Write `{{contextAbsPath}}` — use the template structure, filling in:
+   - **Goal** — one sentence: what this slice delivers
+   - **Why this Slice** — why now, what it unblocks
+   - **Scope / In Scope** — what was confirmed in scope during the interview
+   - **Scope / Out of Scope** — what was explicitly deferred or excluded
+   - **Constraints** — anything the user flagged as a hard constraint
+   - **Integration Points** — what this slice consumes and produces
+   - **Open Questions** — anything still unresolved, with current thinking
+4. Commit: `git -C {{projectRoot}} add {{contextAbsPath}} && git -C {{projectRoot}} commit -m "docs({{milestoneId}}/{{sliceId}}): slice context from discuss"`
+5. Say exactly: `"{{sliceId}} context written."` — nothing else.

package/src/resources/extensions/gsd/prompts/guided-execute-task.md

@@ -0,0 +1 @@
+Execute the next task: {{taskId}} ("{{taskTitle}}") in slice {{sliceId}} of milestone {{milestoneId}}. Read the task plan (`{{taskId}}-PLAN.md`), load relevant summaries from prior tasks, and execute each step. Verify must-haves when done. If the task touches UI, browser flows, DOM behavior, or user-visible web state, exercise the real flow in the browser, prefer `browser_batch` for obvious sequences, prefer `browser_assert` for explicit pass/fail verification, use `browser_diff` when an action's effect is ambiguous, and use browser diagnostics when validating async or failure-prone UI. If you made an architectural, pattern, or library decision, append it to `.gsd/DECISIONS.md`. Read the template at `~/.gsd/agent/extensions/gsd/templates/task-summary.md`. Write `{{taskId}}-SUMMARY.md`, mark it done, commit, and advance. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during execution, without relaxing required verification or artifact rules. If running long and not all steps are finished, stop implementing and prioritize writing a clean partial summary over attempting one more step — a recoverable handoff is more valuable than a half-finished step with no documentation. If verification fails, debug methodically: form a hypothesis and test that specific theory before changing anything, change one variable at a time, read entire functions not just the suspect line, distinguish observable facts from assumptions, and if 3+ fixes fail without progress stop and reassess your mental model — list what you know for certain, what you've ruled out, and form fresh hypotheses. Don't fix symptoms — understand why something fails before changing code.

package/src/resources/extensions/gsd/prompts/guided-plan-milestone.md

@@ -0,0 +1,23 @@
+Plan milestone {{milestoneId}} ("{{milestoneTitle}}"). Read `.gsd/DECISIONS.md` if it exists — respect existing decisions. Read `.gsd/REQUIREMENTS.md` if it exists and treat Active requirements as the capability contract. If `REQUIREMENTS.md` is missing, continue in legacy compatibility mode but explicitly note missing requirement coverage. Read the template at `~/.gsd/agent/extensions/gsd/templates/roadmap.md`. Create `{{milestoneId}}-ROADMAP.md` in the milestone directory with slices, risk levels, dependencies, demo sentences, verification classes, milestone definition of done, requirement coverage, and a boundary map. Write success criteria as observable truths, not implementation tasks. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment. If planning produces structural decisions, append them to `.gsd/DECISIONS.md`. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during planning, without overriding required roadmap formatting.
+
+## Requirement Rules
+
+- Every relevant Active requirement must be mapped to a slice, deferred, blocked with reason, or moved out of scope.
+- Each requirement gets one primary owner and may have supporting slices.
+- Surface orphaned Active requirements instead of silently ignoring them.
+- Product-facing milestones should cover launchability, primary user loop, continuity, and failure visibility when relevant.
+
+## Planning Doctrine
+
+- **Risk-first means proof-first.** The earliest slices should prove the hardest thing works by shipping the real feature through the uncertain path. If auth is the risk, the first slice ships a real login page with real session handling that a user can actually use — not a CLI command that returns "authenticated: true". Proof is the shipped feature working. There is no separate "proof" artifact. Do not plan spikes, proof-of-concept slices, or validation-only slices — the proof is the real feature, built through the risky path.
+- **Every slice is vertical, demoable, and shippable.** Every slice ships real, user-facing functionality. "Demoable" means you could show a stakeholder and they'd see real product progress — not a developer showing a terminal command. If the only way to demonstrate the slice is through a test runner or a curl command, the slice is missing its UI/UX surface. Add it. A slice that only proves something but doesn't ship real working code is not a slice — restructure it.
+- **Brownfield bias.** When planning against an existing codebase, ground slices in existing modules, conventions, and seams. Prefer extending real patterns over inventing new ones.
+- **Each slice should establish something downstream slices can depend on.** Think about what stable surface this slice creates for later work — an API, a data shape, a proven integration path.
+- **Avoid foundation-only slices.** If a slice doesn't produce something demoable end-to-end, it's probably a layer, not a vertical slice. Restructure it.
+- **Verification-first.** When planning slices, know what "done" looks like before detailing implementation. Each slice's demo line should describe concrete, verifiable evidence — not vague "it works" claims.
+- **Plan for integrated reality, not just local proof.** Distinguish contract proof from live integration proof. If the milestone involves multiple runtime boundaries, one slice must explicitly prove the assembled system through the real entrypoint or runtime path.
+- **Truthful demo lines only.** If a slice is proven by fixtures or tests only, say so. Do not phrase harness-level proof as if the user can already perform the live end-to-end behavior unless that has actually been exercised.
+- **Completion must imply capability.** If every slice in this roadmap were completed exactly as written, the milestone's promised outcome should actually work at the proof level claimed. Do not write slices that can all be checked off while the user-visible capability still does not exist.
+- **Don't invent risks.** If the project is straightforward, skip the proof strategy and just ship value in smart order. Not everything has major unknowns.
+- **Ship features, not proofs.** A completed slice should leave the product in a state where the new capability is actually usable through its real interface. A login flow slice ends with a working login page, not a middleware function. An API slice ends with endpoints that return real data from a real store, not hardcoded fixtures. A dashboard slice ends with a real dashboard rendering real data, not a component that renders mock props. If a slice can't ship the real thing yet because a dependency isn't built, it should ship with realistic stubs that are clearly marked for replacement — but the user-facing surface must be real.
+- **Ambition matches the milestone.** The number and depth of slices should match the milestone's ambition. A milestone promising "core platform with auth, data model, and primary user loop" should have enough slices to actually deliver all three as working features — not two proof-of-concept slices and a note that "the rest will come in the next milestone." If the milestone's context promises an outcome, the roadmap must deliver it.

package/src/resources/extensions/gsd/prompts/guided-plan-slice.md

@@ -0,0 +1 @@
+Plan slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.gsd/DECISIONS.md` if it exists — respect existing decisions. Read `.gsd/REQUIREMENTS.md` if it exists — identify which Active requirements the roadmap says this slice owns or supports, and ensure the plan delivers them. Read the roadmap boundary map, any existing context/research files, and dependency summaries. Read the templates at `~/.gsd/agent/extensions/gsd/templates/plan.md` and `task-plan.md`. Decompose into tasks with must-haves. Fill the `Proof Level` and `Integration Closure` sections truthfully so the plan says what class of proof this slice really delivers and what end-to-end wiring still remains. Write `{{sliceId}}-PLAN.md` and individual `T##-PLAN.md` files in the `tasks/` subdirectory. If planning produces structural decisions, append them to `.gsd/decisions.md`. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during planning, without overriding required plan formatting. Before committing, self-audit the plan: every must-have maps to at least one task, every task has complete sections (steps, must-haves, verification, observability impact, inputs, and expected output), task ordering is consistent with no circular references, every pair of artifacts that must connect has an explicit wiring step, task scope targets 2–5 steps and 3–8 files (6–8 steps or 8–10 files — consider splitting; 10+ steps or 12+ files — must split), the plan honors locked decisions from context/research/decisions artifacts, the proof-level wording does not overclaim live integration if only fixture/contract proof is planned, every Active requirement this slice owns has at least one task with verification that proves it is met, and every task produces real user-facing progress — if the slice has a UI surface at least one task builds the real UI, if it has an API at least one task connects it to a real data source, and showing the completed result to a non-technical stakeholder would demonstrate real product progress rather than developer artifacts.

package/src/resources/extensions/gsd/prompts/guided-research-slice.md

@@ -0,0 +1,11 @@
+Research slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.gsd/DECISIONS.md` if it exists — respect existing decisions, don't contradict them. Read `.gsd/REQUIREMENTS.md` if it exists — identify which Active requirements this slice owns or supports and target research toward risks, unknowns, and constraints that could affect delivery of those requirements. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during research, without relaxing required verification or artifact rules. Explore the relevant code — use `rg`/`find` for targeted reads, or `scout` if the area is broad or unfamiliar. Check libraries with `resolve_library`/`get_library_docs`. Read the template at `~/.gsd/agent/extensions/gsd/templates/research.md`. Write `{{sliceId}}-RESEARCH.md` in the slice directory with summary, don't-hand-roll, common pitfalls, and relevant code sections.
+
+## Strategic Questions to Answer
+
+Research should drive planning decisions, not just collect facts. Explicitly address:
+
+- **What should be proven first?** What's the riskiest assumption — the thing that, if wrong, invalidates downstream work?
+- **What existing patterns should be reused?** What modules, conventions, or infrastructure already exist that the plan should build on rather than reinvent?
+- **What boundary contracts matter?** What interfaces, data shapes, event formats, or invariants will slices need to agree on?
+- **What constraints does the existing codebase impose?** What can't be changed, what's expensive to change, what patterns must be respected?
+- **Are there known failure modes that should shape slice ordering?** Pitfalls that mean certain work should come before or after other work?

package/src/resources/extensions/gsd/prompts/guided-resume-task.md

@@ -0,0 +1 @@
+Resume interrupted work. Find the continue file (`{{sliceId}}-CONTINUE.md` or `continue.md`) in slice {{sliceId}} of milestone {{milestoneId}}, then pick up from where you left off. Delete the continue file after reading it. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during execution, without relaxing required verification or artifact rules.

package/src/resources/extensions/gsd/prompts/plan-milestone.md

@@ -0,0 +1,65 @@
+You are executing GSD auto-mode.
+
+## UNIT: Plan Milestone {{milestoneId}} ("{{milestoneTitle}}")
+
+All relevant context has been preloaded below — start working immediately without re-reading these files.
+
+{{inlinedContext}}
+
+Narrate your decomposition reasoning — why you're grouping work this way, what risks are driving the order, what verification strategy you're choosing and why.
+
+Then:
+1. Read the template at `~/.gsd/agent/extensions/gsd/templates/roadmap.md`
+2. Read `.gsd/REQUIREMENTS.md` if it exists. Treat **Active** requirements as the capability contract for planning. If it does not exist, continue in legacy compatibility mode but explicitly note that requirement coverage is operating without a contract.
+3. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during planning, without overriding required roadmap formatting
+4. Create the roadmap: decompose into demoable vertical slices — as many as the work genuinely needs, no more. A simple feature might be 1 slice. Don't decompose for decomposition's sake.
+5. Order by risk (high-risk first)
+6. Write `{{outputPath}}` with checkboxes, risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, **requirement coverage**, and a boundary map. Write success criteria as observable truths, not implementation tasks. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment
+7. If planning produced structural decisions (e.g. slice ordering rationale, technology choices, scope exclusions), append them to `.gsd/DECISIONS.md` (read the template at `~/.gsd/agent/extensions/gsd/templates/decisions.md` if the file doesn't exist yet)
+8. Update `.gsd/STATE.md`
+
+## Requirement Mapping Rules
+
+- Every Active requirement relevant to this milestone must be in one of these states by the end of planning: mapped to a slice, explicitly deferred, blocked with reason, or moved out of scope.
+- Each requirement should have one accountable primary owner and may have supporting slices.
+- Product-facing milestones should cover launchability, primary user loop, continuity, and failure visibility when relevant.
+- A slice may support multiple requirements, but should not exist with no requirement justification unless it is clearly enabling work for a mapped requirement.
+- Include a compact coverage summary in the roadmap so omissions are mechanically visible.
+- If `.gsd/REQUIREMENTS.md` exists and an Active requirement has no credible path, surface that clearly. Do not silently ignore orphaned Active requirements.
+
+## Planning Doctrine
+
+Apply these when decomposing and ordering slices:
+
+- **Risk-first means proof-first.** The earliest slices should prove the hardest thing works by shipping the real feature through the uncertain path. If auth is the risk, the first slice ships a real login page with real session handling that a user can actually use — not a CLI command that returns "authenticated: true". Proof is the shipped feature working. There is no separate "proof" artifact. Do not plan spikes, proof-of-concept slices, or validation-only slices — the proof is the real feature, built through the risky path.
+- **Every slice is vertical, demoable, and shippable.** Every slice ships real, user-facing functionality. "Demoable" means you could show a stakeholder and they'd see real product progress — not a developer showing a terminal command. If the only way to demonstrate the slice is through a test runner or a curl command, the slice is missing its UI/UX surface. Add it. A slice that only proves something but doesn't ship real working code is not a slice — restructure it.
+- **Brownfield bias.** When planning against an existing codebase, ground slices in existing modules, conventions, and seams. Prefer extending real patterns over inventing new ones.
+- **Each slice should establish something downstream slices can depend on.** Think about what stable surface this slice creates for later work — an API, a data shape, a proven integration path.
+- **Avoid foundation-only slices.** If a slice doesn't produce something demoable end-to-end, it's probably a layer, not a vertical slice. Restructure it.
+- **Verification-first.** When planning slices, know what "done" looks like before detailing implementation. Each slice's demo line should describe concrete, verifiable evidence — not vague "it works" claims.
+- **Plan for integrated reality, not just local proof.** Distinguish contract proof from live integration proof. If the milestone involves multiple runtime boundaries, one slice must explicitly prove the assembled system through the real entrypoint or runtime path.
+- **Truthful demo lines only.** If a slice is proven by fixtures or tests only, say so. Do not phrase harness-level proof as if the user can already perform the live end-to-end behavior unless that has actually been exercised.
+- **Completion must imply capability.** If every slice in this roadmap were completed exactly as written, the milestone's promised outcome should actually work at the proof level claimed. Do not write slices that can all be checked off while the user-visible capability still does not exist.
+- **Don't invent risks.** If the project is straightforward, skip the proof strategy and just ship value in smart order. Not everything has major unknowns.
+- **Ship features, not proofs.** A completed slice should leave the product in a state where the new capability is actually usable through its real interface. A login flow slice ends with a working login page, not a middleware function. An API slice ends with endpoints that return real data from a real store, not hardcoded fixtures. A dashboard slice ends with a real dashboard rendering real data, not a component that renders mock props. If a slice can't ship the real thing yet because a dependency isn't built, it should ship with realistic stubs that are clearly marked for replacement — but the user-facing surface must be real.
+- **Ambition matches the milestone.** The number and depth of slices should match the milestone's ambition. A milestone promising "core platform with auth, data model, and primary user loop" should have enough slices to actually deliver all three as working features — not two proof-of-concept slices and a note that "the rest will come in the next milestone." If the milestone's context promises an outcome, the roadmap must deliver it.
+- **Right-size the decomposition.** Match slice count to actual complexity. If the work is small enough to build and verify in one pass, it's one slice — don't split it into three just because you can identify sub-steps. Multiple requirements can share a single slice. Conversely, don't cram genuinely independent capabilities into one slice just to keep the count low. Let the work dictate the structure.
+
+## Single-Slice Fast Path
+
+If the roadmap has only one slice, also write the slice plan and task plans inline during this unit — don't leave them for a separate planning session.
+
+1. Read the templates:
+   - `~/.gsd/agent/extensions/gsd/templates/plan.md`
+   - `~/.gsd/agent/extensions/gsd/templates/task-plan.md`
+2. `mkdir -p {{milestonePath}}/slices/S01/tasks`
+3. Write the S01 plan file at `{{milestonePath}}/slices/S01/S01-PLAN.md`
+4. Write individual task plans at `{{milestonePath}}/slices/S01/tasks/T01-PLAN.md`, etc.
+5. For simple slices, keep the plan lean — omit Proof Level, Integration Closure, and Observability sections if they would all be "none". Executable verification commands are sufficient.
+
+This eliminates a separate research-slice + plan-slice cycle when the work is straightforward.
+
+**You MUST write the file `{{outputAbsPath}}` before finishing.**
+{{skipObservabilityNote}}
+
+When done, say: "Milestone {{milestoneId}} planned."