@therocketcode/gsd-core 1.4.0

package/commands/gsd/debug.md

@@ -0,0 +1,52 @@
+---
+name: gsd:debug
+description: Systematic debugging with persistent state across context resets
+argument-hint: "[list | status <slug> | continue <slug> | --diagnose] [issue description]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Agent
+  - AskUserQuestion
+---
+
+<objective>
+Debug issues using scientific method with subagent isolation.
+
+**Orchestrator role:** Gather symptoms, spawn gsd-debugger agent, handle checkpoints, spawn continuations.
+
+**Flags:**
+- `--diagnose` — Diagnose only. Returns a Root Cause Report without applying a fix.
+
+**Subcommands:** `list` · `status <slug>` · `continue <slug>`
+</objective>
+
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- gsd-debug-session-manager — manages debug checkpoint/continuation loop in isolated context
+- gsd-debugger — investigates bugs using scientific method
+</available_agent_types>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/debug.md
+</execution_context>
+
+<context>
+User's input: $ARGUMENTS
+
+Parse subcommands and flags from $ARGUMENTS BEFORE the active-session check:
+- If $ARGUMENTS starts with "list": SUBCMD=list, no further args
+- If $ARGUMENTS starts with "status ": SUBCMD=status, SLUG=remainder (trim whitespace)
+- If $ARGUMENTS starts with "continue ": SUBCMD=continue, SLUG=remainder (trim whitespace)
+- If $ARGUMENTS contains `--diagnose`: SUBCMD=debug, diagnose_only=true, strip `--diagnose` from description
+- Otherwise: SUBCMD=debug, diagnose_only=false
+
+Check for active sessions (used for non-list/status/continue flows):
+```bash
+ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
+```
+</context>
+
+<process>
+Execute end-to-end.
+</process>

package/commands/gsd/discover-product.md

@@ -0,0 +1,65 @@
+---
+name: gsd:discover-product
+description: Optional product discovery — demand vs interest, the narrowest wedge, four risks, outcome-framed.
+argument-hint: "[--auto] [--text]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+requires: [new-project, model-domain, phase]
+---
+
+<objective>
+Define WHAT to build and WHY before building it — separating real demand from interest, finding the narrowest valuable wedge, and framing success as an outcome. Optional; front-of-funnel.
+
+**Position in workflow:** `discover-product (optional) → new-project → model-domain → recommend-architecture`
+
+**How it works:**
+1. Optionality gate — if requirements are already clear and evidenced, skip to lightweight RICE or exit
+2. Frame the outcome (the behavior/metric to change, not a feature)
+3. Forcing interview: job & specific user → demand-vs-interest (past behavior) → narrowest wedge → four risks → scope/RICE → success metric
+4. Write an outcome-framed PRODUCT-BRIEF.md and commit
+
+**Output:** `.planning/PRODUCT-BRIEF.md` — outcome, target user + wedge, demand evidence, job story, four-risks status, prioritized scope, explicit "not in scope." Feeds PROJECT.md and model-domain.
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/discover-product.md
+@~/.claude/gsd-core/references/product-discovery.md
+@~/.claude/gsd-core/templates/product-brief.md
+</execution_context>
+
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. They are equivalent.
+</runtime_note>
+
+<context>
+**Flags:**
+- `--auto` — Skip the forcing interview; synthesize DISCOVERY.md from any existing PROJECT.md / REQUIREMENTS.md using recommended defaults.
+- `--text` — Use plain-text numbered lists instead of TUI menus (required for `/rc` remote sessions).
+
+**When to run:** when product value is uncertain (new market, no past-behavior evidence, demand asserted from a hypothetical, or a large/irreversible bet). **Skip** when a client/customer has explicit, evidenced requirements — then go straight to `/gsd:new-project` or lightweight prioritization. Runs standalone — does not require an existing project.
+
+Context files (if any) are resolved in-workflow during initialization.
+</context>
+
+<process>
+Execute end-to-end.
+
+**MANDATORY:** Read the workflow file BEFORE taking any action. The workflow contains the complete process including the optionality gate, the forcing interview (push past polished first answers), demand-vs-interest probing, the wedge, the four risks, and DISCOVERY.md generation. Do not improvise from the objective summary above. Ask about the PAST, never hypotheticals; frame the vision as an outcome/opportunity (it must admit more than one solution) so the domain and architecture stay open.
+</process>
+
+<success_criteria>
+- Optionality gate applied (skipped or lightweight path offered when requirements are already evidenced)
+- Outcome framed as a behavior/metric, not a feature
+- Specific user + solution-free job + job story captured
+- Demand separated from interest via past-behavior evidence (not hypotheticals)
+- Narrowest wedge identified; vision admits >1 solution
+- Four risks assessed (unvalidated ones flagged with a cheapest test)
+- Scope prioritized (thin slice + RICE; explicit "not in scope")
+- PRODUCT-BRIEF.md written and committed (when commit_docs is true)
+- User directed to /gsd:new-project or /gsd:model-domain
+</success_criteria>

package/commands/gsd/discuss-phase.md

@@ -0,0 +1,77 @@
+---
+name: gsd:discuss-phase
+description: Gather phase context through adaptive questioning before planning.
+argument-hint: "<phase> [--all] [--auto] [--chain] [--batch] [--analyze] [--text] [--power] [--assumptions]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Agent
+  - mcp__context7__resolve-library-id
+  - mcp__context7__query-docs
+requires: [config, phase]
+---
+
+<objective>
+Extract implementation decisions that downstream agents need — researcher and planner will use CONTEXT.md to know what to investigate and what choices are locked.
+
+**How it works:**
+1. Load prior context (PROJECT.md, REQUIREMENTS.md, STATE.md, prior CONTEXT.md files)
+2. Scout codebase for reusable assets and patterns
+3. Analyze phase — skip gray areas already decided in prior phases
+4. Present remaining gray areas — user selects which to discuss
+5. Deep-dive each selected area until satisfied
+6. Create CONTEXT.md with decisions that guide research and planning
+
+**Output:** `{phase_num}-CONTEXT.md` — decisions clear enough that downstream agents can act without asking the user again
+</objective>
+
+<execution_context>
+Workflow files are loaded on-demand in the <process> section below — not upfront.
+Do not pre-load any workflow files before reading the mode routing instructions.
+</execution_context>
+
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. They are equivalent — `vscode_askquestions` is the VS Code Copilot implementation of the same interactive question API.
+</runtime_note>
+
+<context>
+Phase number: $ARGUMENTS (required)
+
+Context files are resolved in-workflow using `init phase-op` and roadmap/state tool calls.
+</context>
+
+<process>
+**Mode routing:**
+```bash
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @therocketcode/gsd-core@latest --claude --local" >&2; exit 1; fi
+DISCUSS_MODE=$(gsd_run query config-get workflow.discuss_mode 2>/dev/null || echo "discuss")
+```
+
+If `--assumptions` is in $ARGUMENTS:
+Read and execute `~/.claude/gsd-core/workflows/list-phase-assumptions.md` end-to-end.
+Stop here.
+
+Otherwise, if `DISCUSS_MODE` is `"assumptions"`:
+Read and execute `~/.claude/gsd-core/workflows/discuss-phase-assumptions.md` end-to-end.
+
+Otherwise (`"discuss"` / unset / any other value):
+Read and execute `~/.claude/gsd-core/workflows/discuss-phase.md` end-to-end.
+
+**MANDATORY:** Read the appropriate workflow file BEFORE taking any action. The objective and success_criteria sections in this command file are summaries — the workflow file contains the complete step-by-step process with all required behaviors, config checks, and interaction patterns. Do not improvise from the summary.
+
+**Lazy loading:** `templates/context.md` is loaded inside the `write_context` step of the active workflow. `discuss-phase-power.md` is loaded inside `discuss-phase.md` when `--power` is detected. Do not load either here.
+</process>
+
+<success_criteria>
+- Prior context loaded and applied (no re-asking decided questions)
+- Gray areas identified through intelligent analysis
+- User chose which areas to discuss
+- Each selected area explored until satisfied
+- Scope creep redirected to deferred ideas
+- CONTEXT.md captures decisions, not vague vision
+- User knows next steps
+</success_criteria>

package/commands/gsd/docs-update.md

@@ -0,0 +1,49 @@
+---
+name: gsd:docs-update
+description: Generate or update project documentation verified against the codebase
+argument-hint: "[--force] [--verify-only]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+requires: [update]
+---
+<objective>
+Generate and update up to 9 documentation files for the current project. Each doc type is written by a gsd-doc-writer subagent that explores the codebase directly — no hallucinated paths, phantom endpoints, or stale signatures.
+
+Flag handling rule:
+- The optional flags documented below are available behaviors, not implied active behaviors
+- A flag is active only when its literal token appears in `$ARGUMENTS`
+- If a documented flag is absent from `$ARGUMENTS`, treat it as inactive
+- `--force`: skip preservation prompts, regenerate all docs regardless of existing content or GSD markers
+- `--verify-only`: check existing docs for accuracy against codebase, no generation (full verification requires Phase 4 verifier)
+- If `--force` and `--verify-only` both appear in `$ARGUMENTS`, `--force` takes precedence
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/docs-update.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Available optional flags (documentation only — not automatically active):**
+- `--force` — Regenerate all docs. Overwrites hand-written and GSD docs alike. No preservation prompts.
+- `--verify-only` — Check existing docs for accuracy against the codebase. No files are written. Reports VERIFY marker count. Full codebase fact-checking requires the gsd-doc-verifier agent (Phase 4).
+
+**Active flags must be derived from `$ARGUMENTS`:**
+- `--force` is active only if the literal `--force` token is present in `$ARGUMENTS`
+- `--verify-only` is active only if the literal `--verify-only` token is present in `$ARGUMENTS`
+- If neither token appears, run the standard full-phase generation flow
+- Do not infer that a flag is active just because it is documented in this prompt
+</context>
+
+<process>
+Execute end-to-end.
+Preserve all workflow gates (preservation_check, flag handling, wave execution, monorepo dispatch, commit, reporting).
+</process>

package/commands/gsd/eval-review.md

@@ -0,0 +1,33 @@
+---
+name: gsd:eval-review
+description: Audit an executed AI phase's evaluation coverage and produce an EVAL-REVIEW.md remediation plan.
+argument-hint: "[phase number]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+requires: [phase]
+---
+<objective>
+Conduct a retroactive evaluation coverage audit of a completed AI phase.
+Checks whether the evaluation strategy from AI-SPEC.md was implemented.
+Produces EVAL-REVIEW.md with score, verdict, gaps, and remediation plan.
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/eval-review.md
+@~/.claude/gsd-core/references/ai-evals.md
+</execution_context>
+
+<context>
+Phase: $ARGUMENTS — optional, defaults to last completed phase.
+</context>
+
+<process>
+Execute end-to-end.
+Preserve all workflow gates.
+</process>

package/commands/gsd/execute-phase.md

@@ -0,0 +1,66 @@
+---
+name: gsd:execute-phase
+description: Execute all plans in a phase with wave-based parallelization
+argument-hint: "<phase-number> [--wave N] [--gaps-only] [--interactive] [--tdd]"
+context: fork
+effort: xhigh
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Agent
+  - TodoWrite
+  - AskUserQuestion
+requires: [phase, verify-work]
+---
+<objective>
+Execute all plans in a phase using wave-based parallel execution.
+
+Orchestrator stays lean: discover plans, analyze dependencies, group into waves, spawn subagents, collect results. Each subagent loads the full execute-plan context and handles its own plan.
+
+Optional wave filter:
+- `--wave N` executes only Wave `N` for pacing, quota management, or staged rollout
+- phase verification/completion still only happens when no incomplete plans remain after the selected wave finishes
+
+Flag handling rule:
+- The optional flags documented below are available behaviors, not implied active behaviors
+- A flag is active only when its literal token appears in `$ARGUMENTS`
+- If a documented flag is absent from `$ARGUMENTS`, treat it as inactive
+
+Context budget: ~15% orchestrator, 100% fresh per subagent.
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/execute-phase.md
+@~/.claude/gsd-core/references/ui-brand.md
+</execution_context>
+
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. They are equivalent — `vscode_askquestions` is the VS Code Copilot implementation of the same interactive question API.
+</runtime_note>
+
+<context>
+Phase: $ARGUMENTS
+
+**Available optional flags (documentation only — not automatically active):**
+- `--wave N` — Execute only Wave `N` in the phase. Use when you want to pace execution or stay inside usage limits.
+- `--gaps-only` — Execute only gap closure plans (plans with `gap_closure: true` in frontmatter). Use after verify-work creates fix plans.
+- `--interactive` — Execute plans sequentially inline (no subagents) with user checkpoints between tasks. Lower token usage, pair-programming style. Best for small phases, bug fixes, and verification gaps.
+
+**Active flags must be derived from `$ARGUMENTS`:**
+- `--wave N` is active only if the literal `--wave` token is present in `$ARGUMENTS`
+- `--gaps-only` is active only if the literal `--gaps-only` token is present in `$ARGUMENTS`
+- `--interactive` is active only if the literal `--interactive` token is present in `$ARGUMENTS`
+- If none of these tokens appear, run the standard full-phase execution flow with no flag-specific filtering
+- Do not infer that a flag is active just because it is documented in this prompt
+
+Context files are resolved inside the workflow via `gsd-tools query init.execute-phase` and per-subagent `<files_to_read>` blocks.
+</context>
+
+<process>
+Execute end-to-end.
+Preserve all workflow gates (wave execution, checkpoint handling, verification, state updates, routing).
+</process>

package/commands/gsd/explore.md

@@ -0,0 +1,27 @@
+---
+name: gsd:explore
+description: Socratic ideation and idea routing — think through ideas before committing to plans
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - Agent
+  - AskUserQuestion
+---
+<objective>
+Open-ended Socratic ideation session. Guides the developer through exploring an idea via
+probing questions, optionally spawns research, then routes outputs to the appropriate GSD
+artifacts (notes, todos, seeds, research questions, requirements, or new phases).
+
+Accepts an optional topic argument: `/gsd:explore authentication strategy`
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/explore.md
+</execution_context>
+
+<process>
+Execute end-to-end.
+</process>

package/commands/gsd/extract-learnings.md

@@ -0,0 +1,23 @@
+---
+name: gsd:extract-learnings
+description: Extract decisions, lessons, patterns, and surprises from completed phase artifacts
+argument-hint: <phase-number>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - Agent
+type: prompt
+requires: [phase]
+---
+<objective>
+Extract structured learnings from completed phase artifacts (PLAN.md, SUMMARY.md, VERIFICATION.md, UAT.md, STATE.md) into a LEARNINGS.md file that captures decisions, lessons learned, patterns discovered, and surprises encountered.
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/extract-learnings.md
+</execution_context>
+
+Execute the extract-learnings workflow from @~/.claude/gsd-core/workflows/extract-learnings.md end-to-end.

package/commands/gsd/fast.md

@@ -0,0 +1,31 @@
+---
+name: gsd:fast
+description: Execute a trivial task inline — no subagents, no planning overhead
+argument-hint: "[task description]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+requires: [config, quick]
+---
+
+<objective>
+Execute a trivial task directly in the current context without spawning subagents
+or generating PLAN.md files. For tasks too small to justify planning overhead:
+typo fixes, config changes, small refactors, forgotten commits, simple additions.
+
+This is NOT a replacement for /gsd:quick — use /gsd:quick for anything that
+needs research, multi-step planning, or verification. /gsd:fast is for tasks
+you could describe in one sentence and execute in under 2 minutes.
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/fast.md
+</execution_context>
+
+<process>
+Execute end-to-end.
+</process>

package/commands/gsd/forensics.md

@@ -0,0 +1,57 @@
+---
+type: prompt
+name: gsd:forensics
+description: Post-mortem investigation for failed GSD workflows — diagnoses what went wrong.
+argument-hint: "[problem description]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+requires: [phase, progress, update]
+---
+
+<objective>
+Investigate what went wrong during a GSD workflow execution. Analyzes git history, `.planning/` artifacts, and file system state to detect anomalies and generate a structured diagnostic report.
+
+Purpose: Diagnose failed or stuck workflows so the user can understand root cause and take corrective action.
+Output: Forensic report saved to `.planning/forensics/`, presented inline, with optional issue creation.
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/forensics.md
+</execution_context>
+
+<context>
+**Data sources:**
+- `git log` (recent commits, patterns, time gaps)
+- `git status` / `git diff` (uncommitted work, conflicts)
+- `.planning/STATE.md` (current position, session history)
+- `.planning/ROADMAP.md` (phase scope and progress)
+- `.planning/phases/*/` (PLAN.md, SUMMARY.md, VERIFICATION.md, CONTEXT.md)
+- `.planning/reports/SESSION_REPORT.md` (last session outcomes)
+
+**User input:**
+- Problem description: $ARGUMENTS (optional — will ask if not provided)
+</context>
+
+<process>
+Execute end-to-end.
+</process>
+
+<success_criteria>
+- Evidence gathered from all available data sources
+- At least 4 anomaly types checked (stuck loop, missing artifacts, abandoned work, crash/interruption)
+- Structured forensic report written to `.planning/forensics/report-{timestamp}.md`
+- Report presented inline with findings, anomalies, and recommendations
+- Interactive investigation offered for deeper analysis
+- GitHub issue creation offered if actionable findings exist
+</success_criteria>
+
+<critical_rules>
+- **Read-only investigation:** Do not modify project source files during forensics. Only write the forensic report and update STATE.md session tracking.
+- **Redact sensitive data:** Strip absolute paths, API keys, tokens from reports and issues.
+- **Ground findings in evidence:** Every anomaly must cite specific commits, files, or state data.
+- **No speculation without evidence:** If data is insufficient, say so — do not fabricate root causes.
+</critical_rules>