@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.eed73bea

package/src/resources/extensions/gsd/prompts/audit-uat.md

@@ -0,0 +1,24 @@
+You are running the GSD **audit-uat** workflow — cross-milestone audit of all outstanding UAT and verification items.
+
+## Verify mode
+
+{{verifyMode}}
+
+## Process
+
+1. **Find every outstanding verification item.** Scan all milestones and slices for items in a non-passing state: pending, skipped, blocked, human_needed. Read the slice SUMMARY/ASSESSMENT artifacts and any UAT records.
+
+2. **Classify each item.** For each outstanding item, record: milestone/slice id, the item, its current state, and why it's outstanding (skipped intentionally, blocked by a dependency, awaiting a human, stale).
+
+3. **Verify against the codebase** (only when `--verify` is set): for each item, check whether the code now satisfies it — turning stale "pending" items into pass/fail based on current evidence. Do not modify code; only re-evaluate.
+
+4. **Produce a prioritized test plan.** Order the genuinely-outstanding items into a human test plan: blockers first, then high-risk, then the rest. Each entry has a clear test step and expected result.
+
+5. **Summarize.** Report counts by state, the count turned pass/fail by verification, and the prioritized plan.
+
+## Success criteria
+
+- Every outstanding verification item is listed with its milestone/slice and reason.
+- Stale items are detected (and, in verify mode, re-evaluated against the code).
+- The test plan is prioritized by risk, not alphabetical.
+- No item is silently dropped or assumed resolved.

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

@@ -0,0 +1,31 @@
+You are running the GSD **autonomous** workflow — run all remaining work on a milestone/slice continuously: discuss → plan → execute per slice, then validate, with minimal human intervention.
+
+## Scope
+
+{{scope}}
+
+## Flags
+
+- `--interactive` — {{interactiveFlag}} (pause for confirmation at key boundaries)
+- `--converge` — {{convergeFlag}} (re-run review cycles until concerns resolve before advancing)
+
+## Process
+
+This workflow is the gsd-pi equivalent of `/gsd auto` with explicit phase-ceremony. It drives the milestone through its lifecycle:
+
+1. **For each pending slice**, in order: discuss (if not done) → plan (if not done) → execute (all tasks) → complete slice.
+2. **Between slices**, honor the closeout boundary stop rule: stop after a slice closeout and leave the closeout surface visible, unless the user opted out of pause-at-boundary.
+3. **`--converge`:** before advancing, run a plan-review-convergence pass on the slice; only advance when concerns resolve.
+4. **`--interactive`:** confirm before each slice's discuss→plan→execute transitions.
+5. **At milestone completion,** run validation (`/gsd dispatch validate`) rather than auto-closing.
+
+Prefer delegating each lifecycle step to gsd-pi's native dispatch (`/gsd dispatch discuss|plan|execute`, `/gsd next`, `/gsd auto`) rather than reimplementing the unit machinery.
+
+Never barrel past a closeout boundary silently; never mark a milestone complete without validation.
+
+## Success criteria
+
+- The milestone advances through its lifecycle in the correct order.
+- Closeout boundaries are respected (stop and surface, don't barrel).
+- `--converge` actually gates advancement on resolved concerns.
+- Milestone completion goes through validation, not auto-close.

package/src/resources/extensions/gsd/prompts/code-review.md

@@ -0,0 +1,37 @@
+You are running the GSD **code-review** workflow — review source files changed during recent work for bugs, security issues, and code quality problems.
+
+## Scope
+
+{{scope}}
+
+## Depth
+
+{{depth}}
+
+## Fix mode
+
+{{fixMode}}
+
+## Process
+
+1. **Determine the file set.** Use the explicit `--files` list if provided. Otherwise derive the changed source files from the active slice's recent commits / SUMMARY, or fall back to the git diff against the base branch. Exclude `.gsd/`, lockfiles, generated/vendored code, and docs unless `--files` names them.
+
+2. **Review each file** at the requested depth:
+   - **quick** — bugs, security, and correctness only.
+   - **standard** (default) — quick + maintainability, error handling, edge cases.
+   - **deep** — standard + performance, concurrency, API design, test coverage gaps.
+
+   Ground every finding in the actual code with file path + line reference. Categorize each by severity (critical / warning / nit) and type (bug, security, quality, performance).
+
+3. **Write the review.** Produce `.gsd/reviews/{{reviewId}}-REVIEW.md` with the findings table and per-finding detail (location, issue, suggested fix).
+
+4. **Present results.** Summarize counts by severity and list the critical findings first.
+
+5. **Fix mode** (only when `--fix` is set): for each finding that is safely auto-fixable (deterministic, no behavior change beyond the fix), apply it. After each fix batch, run the project's tests. Commit atomically with the finding IDs referenced in the message. Do not auto-apply findings that are ambiguous or that change public behavior — surface those for a human decision instead.
+
+## Success criteria
+
+- Every finding cites a concrete file path and line.
+- Findings are categorized by severity and type.
+- The review is written to `.gsd/reviews/`.
+- Fixes only touch safely-auto-fixable findings, and tests run after each batch.

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

@@ -12,6 +12,10 @@ If any inlined plan, summary, verification command, or prior artifact names an a
 
 All slices are complete. Verify the integrated work, persist milestone completion, refresh project state, and write the final record future milestones will rely on.
 
+### Closeout messaging (auto-mode)
+
+You write closeout artifacts; **GSD auto-mode** decides when the milestone is actually **done**. Never say "Milestone {{milestoneId}} is complete" or "Milestone {{milestoneId}} complete." in this unit — not even after `gsd_complete_milestone` succeeds. GSD announces completion only after post-unit verification passes.
+
 Preloaded context includes roadmap, requirements, decisions, project context, and compact slice-summary excerpts. Slice summaries are excerpts, not full files: use them first, then selectively read full SUMMARY.md files listed under "On-demand Slice Summaries" only when section headings indicate needed evidence for LEARNINGS, Decision Re-evaluation, deviations, limitations, or cross-slice narrative.
 
 Start with what the excerpts give you. Read full files when the section heads signal richer context you need.
@@ -31,7 +35,9 @@ Subagents report only; they do not write user source. Fold any findings into Dec
 
 ## Steps
 
-1. **Duplicate completion guard:** Call `gsd_milestone_status` for `{{milestoneId}}` before any durable writes. If the returned milestone **status is `complete`**, this is a stale or duplicate closeout turn: do NOT mutate requirements, do NOT refresh the project document, do NOT write LEARNINGS, and do NOT persist milestone completion again. Say: "Milestone {{milestoneId}} is already complete." and stop.
+1. **Duplicate completion guard:** Call `gsd_milestone_status` for `{{milestoneId}}` before any durable writes. If the returned milestone **status is `complete`**:
+   - **Verification-retry turn** (prompt begins with `VERIFICATION FAILED`): do NOT stop or declare completion. Repair the closeout evidence in the failure context. Skip step 13 if the milestone is already complete in the DB.
+   - **Otherwise** (stale duplicate closeout): do NOT mutate requirements, do NOT refresh the project document, do NOT write LEARNINGS, and do NOT persist milestone completion again. Say: "Milestone {{milestoneId}} closeout already recorded." and stop.
 2. Use the **Milestone Summary** output template from the inlined context above
 3. {{skillActivation}}
 4. **Verify code changes exist.** Compare milestone work against the integration branch (`main`, `master`, or recorded branch), using merge-base as older revision and `HEAD` as newer. If the diff lists non-`.gsd/` files, pass. If `HEAD` equals the integration branch/merge-base, treat it as a self-diff retry: inspect milestone-scoped commit evidence (`GSD-Unit: {{milestoneId}}` or production `GSD-Task: Sxx/Tyy` trailers touching `.gsd/milestones/{{milestoneId}}/`) and verify those commits touched non-`.gsd/` files. Record **verification failure** only when neither source shows implementation files.
@@ -84,7 +90,7 @@ Subagents report only; they do not write user source. Fold any findings into Dec
    - `deviations` (string) — Deviations from the original plan
 
 14. Do not commit manually — the system auto-commits your changes after this unit completes.
-- After `gsd_complete_milestone` succeeds, emit only one closeout line: "Milestone {{milestoneId}} complete." Do not add a second final-status block, repeat the tool result, or restate the closeout summary.
+- After `gsd_complete_milestone` succeeds, emit only one closeout line: "Milestone {{milestoneId}} closeout submitted." Do not say the milestone is complete, do not add a second final-status block, repeat the tool result, or restate the closeout summary.
 
 **Important:** Do NOT skip code-change, success-criteria, or definition-of-done verification (steps 4-6). The summary must reflect verified outcomes. Verification failures block completion; there is no override. If a verification tool fails, errors, or returns unexpected output, treat it as failure.
 

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

@@ -6,17 +6,21 @@ You are executing GSD auto-mode.
 
 Your working directory is `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` to any other directory.
 
-If any inlined plan, summary, verification command, or prior artifact names an absolute path outside `{{workingDirectory}}`, treat that path as stale context. Convert it to the equivalent relative path under `{{workingDirectory}}` before reading, writing, or executing. If no equivalent path exists under `{{workingDirectory}}`, record a verification failure and stop; do not edit or run commands in another checkout.
+If inlined context names an absolute path outside `{{workingDirectory}}`, treat it as stale. Convert to the relative path under `{{workingDirectory}}` before use. If none exists, record a verification failure and stop; do not edit or run commands in another checkout.
 
 ## Your Role in the Pipeline
 
 You are the closer: verify assembled task work delivers the slice goal, then compress it into a downstream-ready summary and UAT.
 
+### Closeout messaging (auto-mode)
+
+You write closeout artifacts; **GSD auto-mode** decides when the slice is actually **done**. Never say "Slice {{sliceId}} complete" in this unit. GSD announces completion only after post-unit verification passes.
+
 {{inlinedContext}}
 
 {{gatesToClose}}
 
-Match effort to complexity. Simple slices need brief summary and light verification; multi-subsystem slices need stronger verification and detail.
+Match complexity: simple slices need brief summary/light verification; multi-subsystem slices need stronger verification/detail.
 
 Use `subagent` only when useful: reviewer, security, or tester. Apply findings before completion.
 
@@ -24,28 +28,34 @@ Use `subagent` only when useful: reviewer, security, or tester. Apply findings b
 
 1. Use the inlined Slice Summary and UAT templates.
 2. {{skillActivation}}
-3. Run all slice-level verification through `gsd_exec` / Context Mode evidence; refresh current state if needed. Do not use direct `bash` for verification commands.
-4. Complete only when every required check passes. If verification fails or source changes are needed, do **not** edit source files in this unit and do **not** call `gsd_slice_complete`.
+3. Run slice-level verification only through `gsd_exec` / Context Mode evidence; refresh current state if needed. Do not use direct `bash` for verification commands. Tool availability is in **Tool Surface**.
+4. Complete only after every required check passes. Exactly one terminal workflow tool is required: pass -> `gsd_slice_complete`; task follow-up -> `gsd_task_reopen`; planning follow-up -> `gsd_replan_slice`. A text-only stop, even one mentioning a tool, is invalid. If checks fail or source changes are needed, do **not** edit source files in this unit and do **not** call `gsd_slice_complete`.
 5. If verification fails:
-   - Task-specific regressions: if the failure is in files the task touched and pre-task verification evidence shows it was absent before that task ran, call `gsd_task_reopen` with that task and reason.
-   - Inherited/out-of-scope failures, including failures present before the task ran or failures without pre-task evidence: do **not** reopen completed tasks; call `gsd_replan_slice` with adjusted verification scope or follow-up tasks.
-   - Other plan-invalidating failures: call `gsd_replan_slice` with the blocker and updated execution tasks.
-   Then stop with: "Slice {{sliceId}} needs execution follow-up."
+   - Task-specific regression: if pre-task verification evidence shows it was absent before that task ran, call `gsd_task_reopen` with task and reason.
+   - Inherited/out-of-scope failure, including failures present before the task ran or no pre-task evidence: do **not** reopen tasks; call `gsd_replan_slice`.
+   - Other plan-invalidating failure: call `gsd_replan_slice` with blocker and updated tasks.
+   After any successful failure-handoff tool call, the unit is done. The `gsd_task_reopen` or `gsd_replan_slice` call is the handoff signal for the orchestrator.
+   - Never call `gsd_replan_slice` after calling `gsd_task_reopen`; reopened tasks are pending.
+   - Do not call `gsd_plan_slice`; that tool belongs to `plan-slice` and is hard-blocked here.
+   - Do not read source code, run `gsd_exec`, invoke subagents, or do implementation/planning work after the first `gsd_task_reopen` or `gsd_replan_slice` handoff call.
+   - Terminal reopen sequence: call `gsd_task_reopen`; after success, final text may only be: "Slice {{sliceId}} needs execution follow-up."
+   - Terminal replan sequence: call `gsd_replan_slice` once; after it succeeds, final text may only be: "Slice {{sliceId}} needs execution follow-up."
 6. Task summaries use a flat file layout under `tasks/` such as `T01-SUMMARY.md`, not inside per-task subdirectories like `tasks/T01/SUMMARY.md`. Never use `tasks/*/SUMMARY.md`.
 7. If observability/diagnostics were planned, verify them unless the slice is simple.
 8. Address every Gate to Close. Q8 = **Operational Readiness**: health signal, failure signal, recovery, monitoring gaps. Omit empty sections.
 9. If requirement status changed, call `gsd_requirement_update`; do not write `.gsd/REQUIREMENTS.md` directly.
-10. Prepare `gsd_slice_complete` content with camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`.
-11. Draft concrete UAT with preconditions, steps, expected outcomes, edge cases, and UAT Type.
-12. Review the inlined task-summary excerpts for DECISIONS.md/KNOWLEDGE.md-worthy decisions and gotchas. Read full `*-SUMMARY.md` only if needed. Capture with `capture_thought`; do not append knowledge files.
+10. Prepare `gsd_slice_complete` camelCase fields: `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, `uatContent`.
+11. Draft concrete UAT: preconditions, steps, expected outcomes, edge cases, and UAT Type. Declare type under `## UAT Type` exactly like `- UAT mode: browser-executable`.
+    **Web apps:** when inlined Web App UAT guidance is present, declare `browser-executable` or `runtime-executable` (not `artifact-driven`) for localhost/browser/screenshot steps; include dev-server preconditions and name Playwright specs when they exist.
+12. Review the inlined task-summary excerpts for DECISIONS.md/KNOWLEDGE.md-worthy decisions/gotchas. Read full `*-SUMMARY.md` only if needed. Capture with MCP-scoped `gsd_capture_thought`, not bare `capture_thought`; do not append knowledge files.
 13. When verification passes, call `gsd_slice_complete`. The DB-backed tool is the canonical write path. Do **not** manually write `{{sliceSummaryPath}}`. Do **not** manually write `{{sliceUatPath}}`. Do not edit roadmap checkboxes.
 14. Do not run git commands.
-15. If the current project state needs refresh, call `gsd_summary_save` with `artifact_type: "PROJECT"` and the full updated project markdown as `content`; omit `milestone_id`. Do not write or edit `.gsd/PROJECT.md` directly.
+15. If project state needs refresh, call `gsd_summary_save` with `artifact_type: "PROJECT"` and full updated project markdown as `content`; omit `milestone_id`. Do not edit `.gsd/PROJECT.md` directly.
 
 **Autonomous execution:** no human is available. Do not call `ask_user_questions` or `secure_env_collect`; make reasonable assumptions and document them.
 
-**File system safety:** if re-reading task summaries, use `find .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks -name "*-SUMMARY.md"`. Never pass `{{slicePath}}` or any directory path directly to the `read` tool.
+**File system safety:** to re-read task summaries, use `find .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks -name "*-SUMMARY.md"`. Never pass `{{slicePath}}` or any directory path directly to the `read` tool.
 
-**You MUST call `gsd_slice_complete` with summary and UAT content only after verification passes.**
+**You MUST call `gsd_slice_complete` after verification passes. If not, MUST call `gsd_task_reopen` or `gsd_replan_slice`. Never finish this unit with plain text only.**
 
-When done, say: "Slice {{sliceId}} complete."
+When done, say exactly once: "Slice {{sliceId}} closeout submitted." Do not say the slice is complete.

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

@@ -0,0 +1,31 @@
+You are running the GSD **discuss-phase** workflow — gather context for upcoming work through adaptive questioning before planning.
+
+## Target
+
+{{target}}
+
+## Flags
+
+- `--auto` — {{autoFlag}} (when ON, infer answers from existing artifacts without asking)
+- `--text` — {{textFlag}} (when ON, use plain-text questions instead of interactive prompts)
+
+## Process
+
+1. **Load context.** Read the target milestone's ROADMAP entry, CONTEXT, RESEARCH, prior SUMMARYs, and the Decisions Register. This preloaded context is authoritative — do not re-read these files; reference them.
+
+2. **Take a codebase snapshot.** A bounded sample of current code reality (≤5 source files, ≤8KB each) to ground questions. Read a specific file only when a question's answer hinges on it.
+
+3. **Ask grounded questions, one at a time.** Questions must be grounded in the preloaded context + snapshot — never an open-ended survey of the codebase before the first round. Probe: scope boundaries, success criteria, risks, unknowns, integration points.
+
+4. **`--auto` mode:** infer answers from the artifacts rather than asking, and record the inferences as assumptions to be confirmed later.
+
+5. **Record outcomes.** When the discussion settles, capture: decisions (to the Decisions Register via `/gsd knowledge rule` where durable), refined scope (to the milestone CONTEXT), open questions (to RESEARCH or `/gsd dispatch research`), and assumptions. Mark the milestone/slice as "Discussion Complete, Planning Pending".
+
+6. **Route.** Recommend the next step: `/gsd dispatch plan` to plan the milestone/slice, or `/gsd dispatch research` if open questions dominate.
+
+## Success criteria
+
+- Questions are grounded and asked one at a time — no upfront survey.
+- The preloaded context is treated as authoritative (not re-read).
+- Outcomes land in the right gsd-pi artifacts.
+- The recommended next step matches where the milestone now sits.

package/src/resources/extensions/gsd/prompts/docs-update.md

@@ -0,0 +1,13 @@
+You are running the GSD **docs-update** workflow — generate, update, and verify project documentation against the live codebase.
+
+## Mode
+
+{{mode}}
+
+## Process
+
+{{process}}
+
+## Success criteria
+
+{{successCriteria}}

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

@@ -0,0 +1,33 @@
+You are running the GSD **execute-phase** workflow — execute all tasks in a milestone/slice with wave-based parallelization.
+
+## Target
+
+{{target}}
+
+## Flags
+
+- `--wave N` — {{waveFlag}} (max parallel tasks per wave)
+- `--gaps-only` — {{gapsOnlyFlag}} (only execute tasks whose verification is incomplete)
+- `--interactive` — {{interactiveFlag}} (confirm each wave)
+- `--tdd` — {{tddFlag}}
+
+## Process
+
+1. **Load the plan.** Read the milestone/slice plan and task list. Determine task dependencies and group independent tasks into waves.
+
+2. **Execute wave-by-wave.** Within a wave, independent tasks can run in parallel (bounded by `--wave`). Each task: implement → run its verification → record outcome. `--gaps-only` restricts to tasks with incomplete verification.
+
+3. **Per-task guarantees.** Each completed task gets an atomic commit and an updated SUMMARY. Failing verification blocks that task's completion (do not mark it done).
+
+4. **Between waves**, confirm if `--interactive`, then proceed to the next wave respecting dependencies.
+
+5. **Honor closeout boundaries.** Stop after the first task/slice/milestone closeout boundary and leave the final closeout surface visible — do not barrel through multiple closeouts.
+
+Prefer delegating single-task execution to gsd-pi's execute machinery (`/gsd next`, `/gsd dispatch execute`) where it fits.
+
+## Success criteria
+
+- Every task attempted is either completed (verified + committed) or left blocked with a clear reason.
+- Wave parallelism respects task dependencies.
+- Closeout boundaries are honored (stop, don't barrel).
+- Atomic commits per task; SUMMARY updated per task.

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

@@ -32,6 +32,8 @@ You execute. The inlined task plan is authoritative. Verify referenced files and
 - Prior task summaries:
 {{priorTaskLines}}
 
+{{onDemandContext}}
+
 ## Execution Rules
 
 1. Tersely narrate transitions, decisions, and verification outcomes between tool-call clusters.
@@ -50,6 +52,7 @@ You execute. The inlined task plan is authoritative. Verify referenced files and
 
 - If task sections exist for Failure Modes (Q5), Load Profile (Q6), Negative Tests (Q7), or Observability Impact, implement and verify them.
 - Verify must-haves with concrete commands or observable behavior.
+- Run verification commands through `gsd_exec` / Context Mode evidence when workflow MCP tools are presented. Use `gsd_exec_search` before rerunning noisy checks, and `gsd_resume` after compaction or resume. Do not call direct `bash` for final verification evidence in this unit.
 - Run slice-level verification from the slice plan. Final tasks need all checks passing; intermediate tasks should record partial passes.
 - Populate `## Verification Evidence` with `formatEvidenceTable` rows: command, exit code, verdict, duration. If no checks were found, say so.
 - For UI/browser/DOM/user-visible web changes, exercise the real flow and record explicit checks.
@@ -60,9 +63,13 @@ Keep about **{{verificationBudget}}** for verification and summary. If context i
 
 ## Completion Contract
 
+### Closeout messaging (auto-mode)
+
+You write task closeout artifacts; **GSD auto-mode** decides when the task is actually **done**. Never say "Task {{taskId}} complete" in this unit — not even after `gsd_task_complete` succeeds. GSD announces completion only after post-unit verification passes.
+
 - If the plan is fundamentally invalid, set `blocker_discovered: true` in the summary and explain.
 - For downstream-impacting ambiguity that cannot be resolved from code, plans, or decisions, include an `escalation` object with question, options, recommendation, rationale, and `continueWithDefault`.
-- Capture meaningful architecture/pattern/observability decisions with `capture_thought`; capture non-obvious gotchas or conventions only when they save future investigation.
+- Capture meaningful architecture/pattern/observability decisions with `gsd_capture_thought` (or MCP-scoped `mcp__...__gsd_capture_thought`) when workflow MCP tools are presented; capture non-obvious gotchas or conventions only when they save future investigation.
 - Use the inlined Task Summary template below. Read `{{taskSummaryTemplatePath}}` only if the inlined template is absent or visibly truncated.
 - Call `gsd_task_complete` with camelCase fields `milestoneId`, `sliceId`, `taskId`, `oneLiner`, `narrative`, `verification`, and `verificationEvidence`. Include `blockerDiscovered: true` when a stale-path safety failure or other plan-invalidating blocker prevents execution.
 - The DB-backed tool is the canonical write path. Do **not** manually write `{{taskSummaryPath}}` or edit PLAN.md checkboxes; the tool renders the summary and updates state.
@@ -74,4 +81,4 @@ Keep about **{{verificationBudget}}** for verification and summary. If context i
 
 **You MUST call `gsd_task_complete` before finishing, including when the stale-path safety rule stops execution.**
 
-When done, say: "Task {{taskId}} complete."
+When done, say: "Task {{taskId}} closeout submitted." Do not say the task is complete. Say this exactly once — if you already said it in a prior message, do not repeat it.

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

@@ -0,0 +1,58 @@
+You are running the GSD **explore** workflow — Socratic ideation that helps the developer think an idea through before committing to plans or milestones.
+
+## Idea
+
+{{topic}}
+
+## Process
+
+### Step 1 — Open the conversation
+
+If a topic was provided, acknowledge it and begin exploring. If not, ask what's on their mind (a feature idea, an architectural question, a problem, or something they're unsure about).
+
+### Step 2 — Socratic conversation (2–5 exchanges)
+
+- Ask **one question at a time** — never a list.
+- Probe: constraints, tradeoffs, users, scope, dependencies, risks.
+- Listen for "or" / "versus" / "tradeoff" signals — competing priorities worth exploring.
+- Reflect back what you hear to confirm understanding before moving on.
+- Follow the developer's energy — go deeper where they're engaged. Natural, not formulaic.
+
+### Step 3 — Mid-conversation research offer (after 2–3 exchanges)
+
+If the conversation surfaces factual questions, technology comparisons, or unknowns that research could resolve, offer a quick research pass. If the developer accepts, dispatch the project's research tooling. Skip entirely if the topic doesn't warrant it — never force it.
+
+### Step 4 — Crystallize outputs (after 3–6 exchanges)
+
+When the conversation reaches natural conclusions (or the developer signals readiness), analyze what was discussed and propose **up to 4 outputs** from:
+
+| Type | Destination (gsd-pi) | When to suggest |
+|------|----------------------|-----------------|
+| Capture | `.gsd/CAPTURES.md` (append) | Observations, context, decisions worth remembering |
+| Backlog item | `/gsd backlog add` | Forward-looking ideas not ready for a milestone |
+| Knowledge | `/gsd knowledge lesson` | A lesson learned worth persisting |
+| Research | `/gsd dispatch research` | Open questions needing deeper investigation |
+| Requirement | `.gsd/CONTEXT.md` (append under "Domain glossary") | Clear requirements that emerged |
+| New milestone | `/gsd new-milestone` | Scope large enough to warrant its own milestone |
+| Spike | `/gsd spike` | Feasibility uncertainty surfaced ("will this API work?") |
+| Sketch | `/gsd brief diagram` | Design direction unclear ("what should this look like?") |
+
+Present the suggestions and ask the developer to pick, modify, or skip.
+
+**Never write artifacts without explicit user selection.**
+
+### Step 5 — Write selected outputs
+
+For each selected output, use the matching gsd-pi command or write to the destination listed above. Prefer invoking the gsd-pi command (e.g. `/gsd backlog add`, `/gsd knowledge lesson`) so state stays canonical.
+
+### Step 6 — Close
+
+Summarize the topic, list the artifacts created, and suggest next steps (`/gsd explore` again, or `/gsd status` to see where to apply the work).
+
+## Success criteria
+
+- Questions asked one at a time, not in batches.
+- Research offered contextually, not forced.
+- Up to 4 outputs proposed, grounded in the actual conversation.
+- User explicitly selects which outputs to create before anything is written.
+- Artifacts go to the gsd-pi destinations above.

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

@@ -0,0 +1,27 @@
+You are running the GSD **graphify** workflow — build, query, and inspect a lightweight project knowledge graph. The graph lives in `.gsd/knowledge/` and is grounded in CODEBASE.md and project memories.
+
+## Action
+
+{{action}}
+
+## Process
+
+The knowledge graph is a set of Markdown + a JSON edge index under `.gsd/knowledge/`:
+- `nodes.md` — entities discovered in the codebase (modules, services, data models, external integrations), each with a stable id, type, file path, and one-line description.
+- `edges.json` — relationships between nodes (`depends-on`, `calls`, `implements`, `produces`, `consumes`).
+
+Parse the action:
+
+- **build** (default when no action): Re-scan the codebase and CODEBASE.md, extract nodes and edges, and write/refresh `nodes.md` and `edges.json`. Preserve human-added annotations where possible. Stamp the build with the current HEAD commit.
+- **query <term>**: Look up nodes matching the term and print their direct relationships (one hop). Show the evidence (file path) for each edge.
+- **status**: Print graph stats — node count by type, edge count by relationship, last build commit. Say if the graph is stale (HEAD moved since last build).
+- **diff**: Compare the current codebase HEAD against the last build commit and report added/removed/changed nodes — a drift report.
+
+Ground extraction in real code. Do not invent nodes. When the codebase has no CODEBASE.md, suggest running `/gsd codebase generate` first.
+
+## Success criteria
+
+- Nodes and edges are backed by real file evidence.
+- The graph lives under `.gsd/knowledge/`.
+- Query/status/diff give accurate, evidence-backed answers.
+- Stale graphs are detected and reported.

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

@@ -36,6 +36,8 @@ After the opening answer, classify project shape as **`simple`** or **`complex`*
 
 Persist the verdict through `gsd_summary_save` with `artifact_type: "PROJECT"` into `## Project Shape`; downstream `discuss-requirements`, `discuss-milestone`, and `discuss-slice` read the rendered projection.
 
+When the project is browser-facing (web app, SPA, static site with UI, Next/React/Vue, etc.), also record **`Web stack:`** under `## Project Shape` (framework + whether Playwright or browser UAT is expected). Downstream planning uses this to choose `browser-executable` / `runtime-executable` UAT instead of deferring UI proof to humans.
+
 ### Before deeper rounds
 
 Ground your questions in the **Preparation Context snapshot above** (stack, structure, greenfield/brownfield and framework signals) plus any prior `.planning/` or `.gsd/` artifacts — those are authoritative. **Do not survey the codebase** with `rg`/`find`/`scout` before asking; read a specific file only when a question's answer genuinely hinges on it.
@@ -103,7 +105,7 @@ Once the user confirms depth:
 
 1. Use the **Project** output template (inlined above).
 2. Call `gsd_summary_save` with `artifact_type: "PROJECT"` and full project markdown as `content`; omit `milestone_id`. The tool persists the DB-backed PROJECT artifact and renders `.gsd/PROJECT.md`. Preserve the user's terms and framing.
-3. The `## Project Shape` section MUST contain `**Complexity:** simple` or `**Complexity:** complex` (matching the verdict you announced) plus a one-line `**Why:**` rationale. Downstream stages read this line.
+3. The `## Project Shape` section MUST contain `**Complexity:** simple` or `**Complexity:** complex` (matching the verdict you announced) plus a one-line `**Why:**` rationale. For browser-facing projects, also include `**Web stack:**` (framework and expected browser/Playwright UAT approach). Downstream stages read these lines.
 4. The `## Capability Contract` section MUST reference `.gsd/REQUIREMENTS.md` — that file does not yet exist; the next stage (`discuss-requirements`) will produce it.
 5. The `## Milestone Sequence` MUST list at least M001 with title and one-liner. Subsequent milestones may be listed as known intents; they will be elaborated in their own discuss-milestone stages.
 6. Do NOT use `artifact_type: "CONTEXT"` and do NOT pass `milestone_id: "PROJECT"`; that creates a fake milestone named PROJECT.

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

@@ -0,0 +1,37 @@
+You are running the GSD **health** workflow — validate `.gsd/` directory integrity and report actionable issues, optionally repairing auto-fixable ones.
+
+## Flags
+
+- `--repair` — {{repairFlag}} (when ON, auto-fix detected issues)
+- `--context` — {{contextFlag}} (when ON, report context-window utilization instead of directory health)
+
+## Process
+
+### Directory integrity (default; skip if `--context`)
+
+Check the canonical `.gsd/` state for:
+
+- **Missing or malformed artifacts:** ROADMAP, milestone/slice markdown projections, CONTEXT, CAPTURES.
+- **DB/disk drift:** rows in the canonical DB that don't match the markdown projections (and vice-versa).
+- **Orphaned artifacts:** slices/tasks referenced nowhere, or projections whose DB rows are gone.
+- **Incomplete/inconsistent state:** an active milestone that's actually complete, a locked milestone with no lease, stale crash locks.
+- **Unmerged completed milestones:** milestones marked complete but never merged/published.
+
+For each issue, classify it: **auto-fixable** (drift repair, projection rebuild) or **needs-human** (data loss, ambiguous state). When `--repair` is ON, apply the auto-fixable fixes (preferring gsd-pi's repair tooling: `/gsd doctor fix`, `/gsd rebuild markdown`). Report exactly what changed.
+
+Prefer delegating the heavy lifting to gsd-pi's existing repair commands rather than hand-editing state.
+
+### Context utilization (only when `--context`)
+
+Report the session's approximate tokens used vs. the active model's context window, and what is consuming it (skills, injections, history). Suggest compaction or pruning if utilization is high.
+
+## Output
+
+Present issues grouped by severity (needs-human first, then auto-fixable). For `--repair`, also list each fix applied with a one-line before/after. If everything is healthy, say so plainly.
+
+## Success criteria
+
+- Every reported issue is concrete and actionable (file/row + what's wrong + how to fix).
+- Repairs use gsd-pi repair tooling where it exists.
+- No silent destructive changes — auto-fixable means reversible/projection-level only.
+- Context mode and directory mode are orthogonal and never mixed.

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

@@ -0,0 +1,30 @@
+You are running the GSD **import** workflow — ingest an external plan with conflict detection against existing project decisions before writing anything.
+
+## Flags
+
+- `--resolve auto|interactive` — {{resolveFlag}}
+
+## Source
+
+{{source}}
+
+## Process
+
+1. **Read the source plan.** From the given filepath (or `--from-gsd2` to migrate a legacy `.planning/` directory laid out as ordered phases). Parse its phases, requirements, decisions, and tasks.
+
+2. **Conflict detection (before writing).** Compare the source's decisions and requirements against the project's existing CONTEXT, Decisions Register, KNOWLEDGE rules, and current milestones. Flag: contradictory decisions, duplicate requirements, scope that overlaps an existing milestone, and terminology mismatches.
+
+3. **Present the conflict report.** List conflicts by severity (blocking / warning / info). Do not write anything yet.
+
+4. **Resolve.** For each conflict, propose a resolution (adopt source, keep ours, merge). In `--resolve auto`, apply the safe merges and flag the rest; in `--resolve interactive`, confirm each resolution with the user.
+
+5. **Import.** On approval, translate the source into gsd-pi artifacts: phases → milestones, requirements → CONTEXT/requirements, decisions → Decisions Register (`/gsd knowledge rule`), tasks → slice tasks. Prefer `/gsd migrate` machinery for whole `.planning/` imports.
+
+Nothing is written until conflicts are resolved.
+
+## Success criteria
+
+- Conflicts are detected and reported before any write.
+- No destructive overwrite of existing decisions without explicit resolution.
+- Phase-based source content is translated to gsd-pi's milestone/slice model.
+- Whole-`.planning/` imports route through `/gsd migrate`.

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

@@ -0,0 +1,27 @@
+You are running the GSD **inbox** workflow — triage and review open GitHub issues and PRs against the project's conventions, using the GitHub Issues tracker referenced in AGENTS.md.
+
+## Flags
+
+- `--issues` / `--prs` — {{focusFlag}} (which to review; default both)
+- `--label <name>` — {{labelFlag}}
+- `--close-incomplete` — {{closeIncompleteFlag}} (close items that don't meet contribution requirements)
+- `--repo <owner/repo>` — {{repo}}
+
+## Process
+
+1. **Fetch open items.** Use the `gh` CLI (or the project's GitHub integration) to list open issues and/or PRs, applying the label and repo filters.
+
+2. **Triage each item** against the project's contribution guide and templates:
+   - **Issues**: is it actionable? Does it have reproduction, labels, expected/actual? Route: promote to backlog (`/gsd backlog add`), request info, or close incomplete.
+   - **PRs**: does it meet the PR checklist (tests, docs, conventional commits, scope)? Route: request changes, request review, or merge-ready.
+
+3. **Present the triage** with the recommended action per item. When `--close-incomplete` is ON, also act on the clear-close items (with a comment explaining why).
+
+4. **Act on confirmation** for non-close actions: add to backlog, request changes, etc. Never merge or close-without-comment automatically.
+
+## Success criteria
+
+- Triage is grounded in the actual issue/PR content, not assumptions.
+- Each item gets a concrete recommended action.
+- Destructive actions (close, merge) require confirmation or an explicit flag.
+- Actionable issues feed the backlog so they aren't lost.

package/src/resources/extensions/gsd/prompts/ingest-docs.md

@@ -0,0 +1,30 @@
+You are running the GSD **ingest-docs** workflow — bootstrap or merge a `.gsd/` setup from existing ADRs, PRDs, SPECs, and docs in the repo.
+
+## Flags
+
+- `--mode new|merge` — {{modeFlag}} (new = fresh .gsd/; merge = fold into existing)
+- `--manifest <file>` — {{manifestFlag}} (a manifest listing which docs to ingest)
+- `--resolve auto|interactive` — {{resolveFlag}}
+
+## Source path
+
+{{path}}
+
+## Process
+
+1. **Discover source docs.** Scan the given path (default: repo root) for decision records (ADRs, MADR, Nygard), PRDs, SPECs, RFCs, and READMEs that carry project knowledge. Apply the manifest filter if given.
+
+2. **Classify each doc**: decision (→ Decisions Register), requirement/spec (→ CONTEXT/requirements), context/narrative (→ CONTEXT), architecture (→ CODEBASE or RESEARCH).
+
+3. **Conflict detection.** When `--mode merge`, detect where ingested decisions contradict the existing Decisions Register and flag them.
+
+4. **Resolve.** In `--resolve auto`, apply safe ingests and flag conflicts; otherwise confirm each.
+
+5. **Bootstrap/merge.** For `--mode new`, run `/gsd init` then write the ingested artifacts. For `--mode merge`, append into the existing `.gsd/` artifacts. Record ingested decisions durably via `/gsd knowledge rule`.
+
+## Success criteria
+
+- Source docs are discovered and classified, not blindly copied.
+- Merge conflicts are detected before writing.
+- Decisions land in the Decisions Register; requirements in CONTEXT — not dumped as raw files.
+- Bootstrap and merge both route through gsd-pi init/knowledge commands.

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

@@ -0,0 +1,21 @@
+You are running the GSD **manager** workflow — an interactive command center for managing multiple milestones from one terminal.
+
+## Flags
+
+- `--analyze-deps` — {{analyzeDepsFlag}} (when ON, also analyze cross-milestone dependencies)
+
+## Process
+
+1. **Load the milestone queue.** Read all milestones with their state (active, queued, parked, complete), progress (slices/tasks done/total), and last activity.
+
+2. **Present the dashboard.** Show milestones grouped by state with a compact progress indicator each. Highlight the active milestone and any blockers.
+
+{{managerActions}}
+
+4. **`--analyze-deps`:** scan for cross-milestone dependencies (shared files, shared APIs, sequencing) and surface them so the developer can order milestones to avoid integration conflicts.
+
+{{managerSelectionStep}}
+
+## Success criteria
+
+{{managerSuccessCriteria}}

package/src/resources/extensions/gsd/prompts/map-codebase.md

@@ -0,0 +1,42 @@
+You are running the GSD **map-codebase** workflow — analyze the codebase and produce structured reference documents that planning and execution can rely on. Output goes to `.gsd/codebase/`.
+
+## Scope
+
+{{scope}}
+
+## Output directory
+
+`{{outputDir}}`
+
+## Philosophy
+
+- **Practical detail over arbitrary brevity.** Include enough to be useful as reference, with real code patterns.
+- **Always include file paths** formatted with backticks (e.g. `src/services/user.ts`). These documents are reference material for planning and execution.
+- Prefer reading the code directly over guessing.
+
+## Documents to produce
+
+Write a well-structured Markdown file in `{{outputDir}}/` for each relevant document:
+
+- **STACK.md** — languages, runtimes, versions; key frameworks/libraries; build tools; package manager.
+- **INTEGRATIONS.md** — third-party APIs/services; databases; auth providers; infra/deploy; comms services.
+- **ARCHITECTURE.md** — architecture style; core data flow; key design patterns; module/package boundaries.
+- **STRUCTURE.md** — directory layout with purpose of each top-level dir; entry points; where tests live.
+- **CONVENTIONS.md** — coding conventions, naming, error handling, logging patterns.
+- **TESTING.md** — test framework(s), how to run tests, test structure, coverage approach.
+- **CONCERNS.md** — technical debt, risk areas, TODO/FIXME clusters, fragile areas.
+
+Only produce documents relevant to this project (skip ones with nothing to say). Stamp each document's YAML frontmatter with `last_mapped_commit: <current HEAD sha>` so drift can be detected later.
+
+## Process
+
+1. Detect the project's stack and structure (read manifests, top-level dirs, entry points).
+2. Read representative source files to ground each document in real evidence.
+3. Write each document with concrete examples and file paths.
+4. Print a short summary of which documents were created/updated and their line counts.
+
+## Success criteria
+
+- Every produced document is grounded in real code with file paths.
+- Documents live under `.gsd/codebase/`.
+- Each document has a `last_mapped_commit` frontmatter stamp.