pi-gsd 1.0.3

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

@@ -0,0 +1,122 @@
+---
+name: gsd-complete-milestone
+description: Archive completed milestone and prepare for next version
+---
+
+<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):**
+
+- @.agent/get-shit-done/workflows/complete-milestone.md (main workflow)
+- @.agent/get-shit-done/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 `/gsd-plan-milestone-gaps` first
+   - 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. Run `/gsd-plan-milestone-gaps` to create
+   phases that close the gaps, or proceed anyway to accept 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
+- 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-debug/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: gsd-debug
+description: Systematic debugging with persistent state across context resets
+---
+
+<objective>
+Debug issues using scientific method with subagent isolation.
+
+**Orchestrator role:** Gather symptoms, spawn gsd-debugger agent, handle checkpoints, spawn continuations.
+
+**Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction.
+</objective>
+
+<available_agent_types>
+Valid GSD subagent types (use exact names - do not fall back to 'general-purpose'):
+
+- gsd-debugger - Diagnoses and fixes issues
+  </available_agent_types>
+
+<context>
+User's issue: $ARGUMENTS
+
+Check for active sessions:
+
+```bash
+ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
+```
+
+</context>
+
+<process>
+
+## 0. Initialize Context
+
+```bash
+INIT=$(node ".agent/get-shit-done/bin/gsd-tools.cjs" state load)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Extract `commit_docs` from init JSON. Resolve debugger model:
+
+```bash
+debugger_model=$(node ".agent/get-shit-done/bin/gsd-tools.cjs" resolve-model gsd-debugger --raw)
+```
+
+## 1. Check Active Sessions
+
+If active sessions exist AND no $ARGUMENTS:
+
+- List sessions with status, hypothesis, next action
+- User picks number to resume OR describes new issue
+
+If $ARGUMENTS provided OR user describes new issue:
+
+- Continue to symptom gathering
+
+## 2. Gather Symptoms (if new issue)
+
+Use AskUserQuestion for each:
+
+1. **Expected behavior** - What should happen?
+2. **Actual behavior** - What happens instead?
+3. **Error messages** - Any errors? (paste or describe)
+4. **Timeline** - When did this start? Ever worked?
+5. **Reproduction** - How do you trigger it?
+
+After all gathered, confirm ready to investigate.
+
+## 3. Spawn gsd-debugger Agent
+
+Fill prompt and spawn:
+
+```markdown
+<objective>
+Investigate issue: {slug}
+
+**Summary:** {trigger}
+</objective>
+
+<symptoms>
+expected: {expected}
+actual: {actual}
+errors: {errors}
+reproduction: {reproduction}
+timeline: {timeline}
+</symptoms>
+
+<mode>
+symptoms_prefilled: true
+goal: find_and_fix
+</mode>
+
+<debug_file>
+Create: .planning/debug/{slug}.md
+</debug_file>
+```
+
+```
+Task(
+  prompt=filled_prompt,
+  subagent_type="gsd-debugger",
+  model="{debugger_model}",
+  description="Debug {slug}"
+)
+```
+
+## 4. Handle Agent Return
+
+**If `## ROOT CAUSE FOUND`:**
+
+- Display root cause and evidence summary
+- Offer options:
+  - "Fix now" - spawn fix subagent
+  - "Plan fix" - suggest /gsd-plan-phase --gaps
+  - "Manual fix" - done
+
+**If `## CHECKPOINT REACHED`:**
+
+- Present checkpoint details to user
+- Get user response
+- If checkpoint type is `human-verify`:
+  - If user confirms fixed: continue so agent can finalize/resolve/archive
+  - If user reports issues: continue so agent returns to investigation/fixing
+- Spawn continuation agent (see step 5)
+
+**If `## INVESTIGATION INCONCLUSIVE`:**
+
+- Show what was checked and eliminated
+- Offer options:
+  - "Continue investigating" - spawn new agent with additional context
+  - "Manual investigation" - done
+  - "Add more context" - gather more symptoms, spawn again
+
+## 5. Spawn Continuation Agent (After Checkpoint)
+
+When user responds to checkpoint, spawn fresh agent:
+
+```markdown
+<objective>
+Continue debugging {slug}. Evidence is in the debug file.
+</objective>
+
+<prior_state>
+<files_to_read>
+
+- .planning/debug/{slug}.md (Debug session state)
+  </files_to_read>
+  </prior_state>
+
+<checkpoint_response>
+**Type:** {checkpoint_type}
+**Response:** {user_response}
+</checkpoint_response>
+
+<mode>
+goal: find_and_fix
+</mode>
+```
+
+```
+Task(
+  prompt=continuation_prompt,
+  subagent_type="gsd-debugger",
+  model="{debugger_model}",
+  description="Continue debug {slug}"
+)
+```
+
+</process>
+
+<success_criteria>
+
+- [ ] Active sessions checked
+- [ ] Symptoms gathered (if new)
+- [ ] gsd-debugger spawned with context
+- [ ] Checkpoints handled correctly
+- [ ] Root cause confirmed before fixing
+      </success_criteria>

package/skills/gsd-discuss-phase/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: gsd-discuss-phase
+description: Gather phase context through adaptive questioning before planning. Use --auto to skip interactive questions (the agent picks recommended defaults).
+---
+
+<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>
+@.agent/get-shit-done/workflows/discuss-phase.md
+@.agent/get-shit-done/workflows/discuss-phase-assumptions.md
+@.agent/get-shit-done/templates/context.md
+</execution_context>
+
+<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
+DISCUSS_MODE=$(node ".agent/get-shit-done/bin/gsd-tools.cjs" config-get workflow.discuss_mode 2>/dev/null || echo "discuss")
+```
+
+If `DISCUSS_MODE` is `"assumptions"`: Read and execute @.agent/get-shit-done/workflows/discuss-phase-assumptions.md end-to-end.
+
+If `DISCUSS_MODE` is `"discuss"` (or unset, or any other value): Read and execute @.agent/get-shit-done/workflows/discuss-phase.md end-to-end.
+
+**MANDATORY:** The execution_context files listed above ARE the instructions. Read the 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.
+</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-do/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: gsd-do
+description: Route freeform text to the right GSD command automatically
+---
+
+<objective>
+Analyze freeform natural language input and dispatch to the most appropriate GSD command.
+
+Acts as a smart dispatcher - never does the work itself. Matches intent to the best GSD command using routing rules, confirms the match, then hands off.
+
+Use when you know what you want but don't know which `/gsd-*` command to run.
+</objective>
+
+<execution_context>
+@.agent/get-shit-done/workflows/do.md
+@.agent/get-shit-done/references/ui-brand.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+Execute the do workflow from @.agent/get-shit-done/workflows/do.md end-to-end.
+Route user intent to the best GSD command and invoke it.
+</process>

package/skills/gsd-execute-phase/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: gsd-execute-phase
+description: Execute all plans in a phase with wave-based parallelization
+---
+
+<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>
+@.agent/get-shit-done/workflows/execute-phase.md
+@.agent/get-shit-done/references/ui-brand.md
+</execution_context>
+
+<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 init execute-phase` and per-subagent `<files_to_read>` blocks.
+</context>
+
+<process>
+Execute the execute-phase workflow from @.agent/get-shit-done/workflows/execute-phase.md end-to-end.
+Preserve all workflow gates (wave execution, checkpoint handling, verification, state updates, routing).
+</process>

package/skills/gsd-fast/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: gsd-fast
+description: Execute a trivial task inline - no subagents, no planning overhead
+---
+
+<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>
+@.agent/get-shit-done/workflows/fast.md
+</execution_context>
+
+<process>
+Execute the fast workflow from @.agent/get-shit-done/workflows/fast.md end-to-end.
+</process>

package/skills/gsd-forensics/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: gsd-forensics
+description: Post-mortem investigation for failed GSD workflows - analyzes git history, artifacts, and state to diagnose what went wrong
+---
+
+<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>
+@.agent/get-shit-done/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>
+Read and execute the forensics workflow from @.agent/get-shit-done/workflows/forensics.md 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>

package/skills/gsd-health/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: gsd-health
+description: Diagnose planning directory health and optionally repair issues
+---
+
+<objective>
+Validate `.planning/` directory integrity and report actionable issues. Checks for missing files, invalid configurations, inconsistent state, and orphaned plans.
+</objective>
+
+<execution_context>
+@.agent/get-shit-done/workflows/health.md
+</execution_context>
+
+<process>
+Execute the health workflow from @.agent/get-shit-done/workflows/health.md end-to-end.
+Parse --repair flag from arguments and pass to workflow.
+</process>

package/skills/gsd-help/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: gsd-help
+description: Show available GSD commands and usage guide
+---
+
+<objective>
+Display the complete GSD command reference.
+
+Output ONLY the reference content below. Do NOT add:
+
+- Project-specific analysis
+- Git status or file context
+- Next-step suggestions
+- Any commentary beyond the reference
+  </objective>
+
+<execution_context>
+@.agent/get-shit-done/workflows/help.md
+</execution_context>
+
+<process>
+Output the complete GSD command reference from @.agent/get-shit-done/workflows/help.md.
+Display the reference content directly - no additions or modifications.
+</process>

package/skills/gsd-insert-phase/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: gsd-insert-phase
+description: Insert urgent work as decimal phase (e.g., 72.1) between existing phases
+---
+
+
+<objective>
+Insert a decimal phase for urgent work discovered mid-milestone that must be completed between existing integer phases.
+
+Uses decimal numbering (72.1, 72.2, etc.) to preserve the logical sequence of planned phases while accommodating urgent insertions.
+
+Purpose: Handle urgent work discovered during execution without renumbering entire roadmap.
+</objective>
+
+<execution_context>
+@.agent/get-shit-done/workflows/insert-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (format: <after-phase-number> <description>)
+
+Roadmap and state are resolved in-workflow via `init phase-op` and targeted tool calls.
+</context>
+
+<process>
+Execute the insert-phase workflow from @.agent/get-shit-done/workflows/insert-phase.md end-to-end.
+Preserve all validation gates (argument parsing, phase verification, decimal calculation, roadmap updates).
+</process>

package/skills/gsd-join-discord/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: gsd-join-discord
+description: Join the GSD Discord community
+---
+
+
+<objective>
+Display the Discord invite link for the GSD community server.
+</objective>
+
+<output>
+# Join the GSD Discord
+
+Connect with other GSD users, get help, share what you're building, and stay updated.
+
+**Invite link:** https://discord.gg/gsd
+
+Click the link or paste it into your browser to join.
+</output>

package/skills/gsd-list-phase-assumptions/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: gsd-list-phase-assumptions
+description: Surface the agent's assumptions about a phase approach before planning
+---
+
+
+<objective>
+Analyze a phase and present the agent's assumptions about technical approach, implementation order, scope boundaries, risk areas, and dependencies.
+
+Purpose: Help users see what the agent thinks BEFORE planning begins - enabling course correction early when assumptions are wrong.
+Output: Conversational output only (no file creation) - ends with "What do you think?" prompt
+</objective>
+
+<execution_context>
+@.agent/get-shit-done/workflows/list-phase-assumptions.md
+</execution_context>
+
+<context>
+Phase number: $ARGUMENTS (required)
+
+Project state and roadmap are loaded in-workflow using targeted reads.
+</context>
+
+<process>
+1. Validate phase number argument (error if missing or invalid)
+2. Check if phase exists in roadmap
+3. Follow list-phase-assumptions.md workflow:
+   - Analyze roadmap description
+   - Surface assumptions about: technical approach, implementation order, scope, risks, dependencies
+   - Present assumptions clearly
+   - Prompt "What do you think?"
+4. Gather feedback and offer next steps
+</process>
+
+<success_criteria>
+
+- Phase validated against roadmap
+- Assumptions surfaced across five areas
+- User prompted for feedback
+- User knows next steps (discuss context, plan phase, or correct assumptions)
+  </success_criteria>

package/skills/gsd-list-workspaces/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: gsd-list-workspaces
+description: List active GSD workspaces and their status
+---
+
+<objective>
+Scan `~/gsd-workspaces/` for workspace directories containing `WORKSPACE.md` manifests. Display a summary table with name, path, repo count, strategy, and GSD project status.
+</objective>
+
+<execution_context>
+@.agent/get-shit-done/workflows/list-workspaces.md
+@.agent/get-shit-done/references/ui-brand.md
+</execution_context>
+
+<process>
+Execute the list-workspaces workflow from @.agent/get-shit-done/workflows/list-workspaces.md end-to-end.
+</process>