@opengsd/gsd-core 1.6.0-rc.2 → 1.6.0

package/skills/gsd-complete-milestone/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: gsd-complete-milestone
+description: "Archive completed milestone and prepare for next version"
+argument-hint: "<version>"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+
+<objective>
+Mark milestone {{version}} complete, archive to milestones/, and update ROADMAP.md and REQUIREMENTS.md.
+
+Purpose: Create historical record of shipped version, archive milestone artifacts (roadmap + requirements), and prepare for next milestone.
+Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tagged.
+</objective>
+
+<execution_context>
+**Load these files NOW (before proceeding):**
+
+- @~/.claude/gsd-core/workflows/complete-milestone.md (main workflow)
+- @~/.claude/gsd-core/templates/milestone-archive.md (archive template)
+  </execution_context>
+
+<context>
+**Project files:**
+- `.planning/ROADMAP.md`
+- `.planning/REQUIREMENTS.md`
+- `.planning/STATE.md`
+- `.planning/PROJECT.md`
+
+**User input:**
+
+- Version: {{version}} (e.g., "1.0", "1.1", "2.0")
+  </context>
+
+<process>
+
+**Follow complete-milestone.md workflow:**
+
+0. **Check for audit:**
+
+   - Look for `.planning/v{{version}}-MILESTONE-AUDIT.md`
+   - If missing or stale: recommend `/gsd-audit-milestone` first
+   - If audit status is `gaps_found`: recommend closing the gaps inline
+     (the audit output already enumerates them — insert closure phases
+     via `/gsd-phase --insert <N>` plus the standard
+     discuss/plan/execute chain) before proceeding.
+   - If audit status is `passed`: proceed to step 1
+
+   ```markdown
+   ## Pre-flight Check
+
+   {If no v{{version}}-MILESTONE-AUDIT.md:}
+   ⚠ No milestone audit found. Run `/gsd-audit-milestone` first to verify
+   requirements coverage, cross-phase integration, and E2E flows.
+
+   {If audit has gaps:}
+   ⚠ Milestone audit found gaps. The audit output already enumerates the
+   unsatisfied requirements, cross-phase issues, and broken flows — insert
+   a closure phase per gap with `/gsd-phase --insert <N>` and run the
+   standard `/gsd-discuss-phase` → `/gsd-plan-phase` → `/gsd-execute-phase`
+   chain. Or proceed anyway to accept the gaps as tech debt.
+
+   {If audit passed:}
+   ✓ Milestone audit passed. Proceeding with completion.
+   ```
+
+1. **Verify readiness:**
+
+   - Check all phases in milestone have completed plans (SUMMARY.md exists)
+   - Present milestone scope and stats
+   - Wait for confirmation
+
+2. **Gather stats:**
+
+   - Count phases, plans, tasks
+   - Calculate git range, file changes, LOC
+   - Extract timeline from git log
+   - Present summary, confirm
+
+3. **Extract accomplishments:**
+
+   - Read all phase SUMMARY.md files in milestone range
+   - Extract 4-6 key accomplishments
+   - Present for approval
+
+4. **Archive milestone:**
+
+   - Create `.planning/milestones/v{{version}}-ROADMAP.md`
+   - Extract full phase details from ROADMAP.md
+   - Fill milestone-archive.md template
+   - Update ROADMAP.md to one-line summary with link
+
+5. **Archive requirements:**
+
+   - Create `.planning/milestones/v{{version}}-REQUIREMENTS.md`
+   - Mark all v1 requirements as complete (checkboxes checked)
+   - Note requirement outcomes (validated, adjusted, dropped)
+   - Delete `.planning/REQUIREMENTS.md` (fresh one created for next milestone)
+
+6. **Update PROJECT.md:**
+
+   - Add "Current State" section with shipped version
+   - Add "Next Milestone Goals" section
+   - Archive previous content in `<details>` (if v1.1+)
+
+7. **Commit and tag:**
+
+   - Stage: MILESTONES.md, PROJECT.md, ROADMAP.md, STATE.md, archive files
+   - Commit: `chore: archive v{{version}} milestone`
+   - Tag: `git tag -a v{{version}} -m "[milestone summary]"`
+   - Ask about pushing tag
+
+8. **Offer next steps:**
+   - `/gsd-new-milestone` — start next milestone (questioning → research → requirements → roadmap)
+
+</process>
+
+<success_criteria>
+
+- Milestone archived to `.planning/milestones/v{{version}}-ROADMAP.md`
+- Requirements archived to `.planning/milestones/v{{version}}-REQUIREMENTS.md`
+- `.planning/REQUIREMENTS.md` deleted (fresh for next milestone)
+- ROADMAP.md collapsed to one-line entry
+- PROJECT.md updated with current state
+- Git tag v{{version}} created (if `git.create_tag` enabled)
+- Commit successful
+- User knows next steps (including need for fresh requirements)
+  </success_criteria>
+
+<critical_rules>
+
+- **Load workflow first:** Read complete-milestone.md before executing
+- **Verify completion:** All phases must have SUMMARY.md files
+- **User confirmation:** Wait for approval at verification gates
+- **Archive before deleting:** Always create archive files before updating/deleting originals
+- **One-line summary:** Collapsed milestone in ROADMAP.md should be single line with link
+- **Context efficiency:** Archive keeps ROADMAP.md and REQUIREMENTS.md constant size per milestone
+- **Fresh requirements:** Next milestone starts with `/gsd-new-milestone` which includes requirements definition
+  </critical_rules>

package/skills/gsd-config/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: gsd-config
+description: "Configure GSD settings — workflow toggles, advanced knobs, integrations, and model profile"
+argument-hint: "[--advanced | --integrations | --profile <name>]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+
+<objective>
+Configure GSD settings interactively with a single consolidated command.
+
+Mode routing:
+- **default** (no flag): Common-case toggles (model, research, plan_check, verifier, branching) → settings workflow
+- **--advanced**: Power-user knobs (planning tuning, timeouts, branch templates, cross-AI execution) → settings-advanced workflow
+- **--integrations**: Third-party API keys, code-review CLI routing, agent-skill injection → settings-integrations workflow
+- **--profile <name>**: Switch model profile (quality|balanced|budget|inherit) → set-profile (inline)
+</objective>
+
+<routing>
+
+| Flag | Action | Workflow |
+|------|--------|----------|
+| (none) | Interactive 5-question common-case config prompt | settings |
+| --advanced | Power-user knobs: planning, execution, discussion, cross-AI, git, runtime | settings-advanced |
+| --integrations | API keys (Brave/Firecrawl/Exa), review CLI routing, agent skills | settings-integrations |
+| --profile &lt;name&gt; | Switch model profile without interactive prompt | gsd-tools query config-set-model-profile |
+
+</routing>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/settings.md
+@~/.claude/gsd-core/workflows/settings-advanced.md
+@~/.claude/gsd-core/workflows/settings-integrations.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+
+Parse the first token of $ARGUMENTS:
+- If it is `--advanced`: strip the flag, execute settings-advanced workflow
+- If it is `--integrations`: strip the flag, execute settings-integrations workflow
+- If it starts with `--profile`: extract the profile name (remainder after `--profile`), then:
+  1. Verify `gsd-tools` is on PATH via `command -v gsd-tools`; if absent, emit the install hint `Install GSD via 'npm i -g @opengsd/gsd-core'` and stop.
+  2. Run: `gsd-tools query config-set-model-profile <profile-name> --raw` and display the output verbatim.
+- Otherwise: execute settings workflow (no argument needed)
+</context>
+
+<process>
+1. Parse the leading flag (if any) from $ARGUMENTS.
+2. Load and execute the appropriate workflow end-to-end, or run the inline SDK command for --profile.
+3. Preserve all workflow gates from the target workflow.
+</process>

package/skills/gsd-debug/SKILL.md

@@ -0,0 +1,53 @@
+---
+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/skills/gsd-discuss-phase/SKILL.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
+---
+
+
+<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 @opengsd/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/skills/gsd-docs-update/SKILL.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
+---
+
+<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/skills/gsd-eval-review/SKILL.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
+---
+
+<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/skills/gsd-execute-phase/SKILL.md

@@ -0,0 +1,65 @@
+---
+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]"
+effort: max
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Agent
+  - TodoWrite
+  - AskUserQuestion
+---
+
+<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/skills/gsd-explore/SKILL.md

@@ -0,0 +1,28 @@
+---
+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/skills/gsd-extract-learnings/SKILL.md

@@ -0,0 +1,22 @@
+---
+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
+---
+
+<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/skills/gsd-fast/SKILL.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
+---
+
+
+<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/skills/gsd-forensics/SKILL.md

@@ -0,0 +1,56 @@
+---
+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
+---
+
+
+<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>