gsd-code-first 1.0.0

package/commands/gsd/plan-phase.md

@@ -0,0 +1,47 @@
+---
+name: gsd:plan-phase
+description: Create detailed phase plan (PLAN.md) with verification loop
+argument-hint: "[phase] [--auto] [--research] [--skip-research] [--gaps] [--skip-verify] [--prd <file>] [--reviews] [--text]"
+agent: gsd-planner
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - WebFetch
+  - mcp__context7__*
+---
+<objective>
+Create executable phase prompts (PLAN.md files) for a roadmap phase with integrated research and verification.
+
+**Default flow:** Research (if needed) → Plan → Verify → Done
+
+**Orchestrator role:** Parse arguments, validate phase, research domain (unless skipped), spawn gsd-planner, verify with gsd-plan-checker, iterate until pass or max iterations, present results.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/plan-phase.md
+@~/.claude/get-shit-done/references/ui-brand.md
+</execution_context>
+
+<context>
+Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omitted)
+
+**Flags:**
+- `--research` — Force re-research even if RESEARCH.md exists
+- `--skip-research` — Skip research, go straight to planning
+- `--gaps` — Gap closure mode (reads VERIFICATION.md, skips research)
+- `--skip-verify` — Skip verification loop
+- `--prd <file>` — Use a PRD/acceptance criteria file instead of discuss-phase. Parses requirements into CONTEXT.md automatically. Skips discuss-phase entirely.
+- `--reviews` — Replan incorporating cross-AI review feedback from REVIEWS.md (produced by `/gsd:review`)
+- `--text` — Use plain-text numbered lists instead of TUI menus (required for `/rc` remote sessions)
+
+Normalize phase input in step 2 before any directory lookups.
+</context>
+
+<process>
+Execute the plan-phase workflow from @~/.claude/get-shit-done/workflows/plan-phase.md end-to-end.
+Preserve all workflow gates (validation, research, planning, verification loop, routing).
+</process>

package/commands/gsd/plant-seed.md

@@ -0,0 +1,28 @@
+---
+name: gsd:plant-seed
+description: Capture a forward-looking idea with trigger conditions — surfaces automatically at the right milestone
+argument-hint: "[idea summary]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Capture an idea that's too big for now but should surface automatically when the right
+milestone arrives. Seeds solve context rot: instead of a one-liner in Deferred that nobody
+reads, a seed preserves the full WHY, WHEN to surface, and breadcrumbs to details.
+
+Creates: .planning/seeds/SEED-NNN-slug.md
+Consumed by: /gsd:new-milestone (scans seeds and presents matches)
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/plant-seed.md
+</execution_context>
+
+<process>
+Execute the plant-seed workflow from @~/.claude/get-shit-done/workflows/plant-seed.md end-to-end.
+</process>

package/commands/gsd/pr-branch.md

@@ -0,0 +1,25 @@
+---
+name: gsd:pr-branch
+description: Create a clean PR branch by filtering out .planning/ commits — ready for code review
+argument-hint: "[target branch, default: main]"
+allowed-tools:
+  - Bash
+  - Read
+  - AskUserQuestion
+---
+
+<objective>
+Create a clean branch suitable for pull requests by filtering out .planning/ commits
+from the current branch. Reviewers see only code changes, not GSD planning artifacts.
+
+This solves the problem of PR diffs being cluttered with PLAN.md, SUMMARY.md, STATE.md
+changes that are irrelevant to code review.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/pr-branch.md
+</execution_context>
+
+<process>
+Execute the pr-branch workflow from @~/.claude/get-shit-done/workflows/pr-branch.md end-to-end.
+</process>

package/commands/gsd/profile-user.md

@@ -0,0 +1,46 @@
+---
+name: gsd:profile-user
+description: Generate developer behavioral profile and create Claude-discoverable artifacts
+argument-hint: "[--questionnaire] [--refresh]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Task
+---
+
+<objective>
+Generate a developer behavioral profile from session analysis (or questionnaire) and produce artifacts (USER-PROFILE.md, /gsd:dev-preferences, CLAUDE.md section) that personalize Claude's responses.
+
+Routes to the profile-user workflow which orchestrates the full flow: consent gate, session analysis or questionnaire fallback, profile generation, result display, and artifact selection.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/profile-user.md
+@~/.claude/get-shit-done/references/ui-brand.md
+</execution_context>
+
+<context>
+Flags from $ARGUMENTS:
+- `--questionnaire` -- Skip session analysis entirely, use questionnaire-only path
+- `--refresh` -- Rebuild profile even when one exists, backup old profile, show dimension diff
+</context>
+
+<process>
+Execute the profile-user workflow end-to-end.
+
+The workflow handles all logic including:
+1. Initialization and existing profile detection
+2. Consent gate before session analysis
+3. Session scanning and data sufficiency checks
+4. Session analysis (profiler agent) or questionnaire fallback
+5. Cross-project split resolution
+6. Profile writing to USER-PROFILE.md
+7. Result display with report card and highlights
+8. Artifact selection (dev-preferences, CLAUDE.md sections)
+9. Sequential artifact generation
+10. Summary with refresh diff (if applicable)
+</process>

package/commands/gsd/progress.md

@@ -0,0 +1,24 @@
+---
+name: gsd:progress
+description: Check project progress, show context, and route to next action (execute or plan)
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+  - SlashCommand
+---
+<objective>
+Check project progress, summarize recent work and what's ahead, then intelligently route to the next action - either executing an existing plan or creating the next one.
+
+Provides situational awareness before continuing work.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/progress.md
+</execution_context>
+
+<process>
+Execute the progress workflow from @~/.claude/get-shit-done/workflows/progress.md end-to-end.
+Preserve all routing logic (Routes A through F) and edge case handling.
+</process>

package/commands/gsd/prototype.md

@@ -0,0 +1,56 @@
+---
+name: gsd:prototype
+description: Build a working code prototype with embedded @gsd-tags using gsd-prototyper, then auto-run extract-plan
+argument-hint: "[path] [--phases N]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Task
+  - Glob
+  - Grep
+---
+
+<objective>
+Spawns the `gsd-prototyper` agent to build working prototype code with `@gsd-tags` embedded following the ARC annotation standard. On completion, automatically runs `extract-plan` to produce `.planning/prototype/CODE-INVENTORY.md`.
+
+**Arguments:**
+- `path` — target directory for prototype output (defaults to project root if omitted)
+- `--phases N` — scope the prototype to specific phase numbers from ROADMAP.md (e.g., `--phases 2` or `--phases 2,3`); only requirements belonging to those phases will be prototyped
+
+The prototyper reads `PROJECT.md`, `REQUIREMENTS.md`, and `ROADMAP.md` before building so all generated code reflects actual project goals, requirement IDs, and phase structure.
+</objective>
+
+<context>
+$ARGUMENTS
+
+@.planning/PROJECT.md
+@.planning/REQUIREMENTS.md
+@.planning/ROADMAP.md
+</context>
+
+<process>
+
+1. **Spawn gsd-prototyper agent** via the Task tool, passing `$ARGUMENTS` as context. The agent will:
+   - Read `get-shit-done/references/arc-standard.md` for the ARC tag standard
+   - Read `PROJECT.md`, `REQUIREMENTS.md`, and `ROADMAP.md` for project context and requirement IDs
+   - If `--phases N` is present in `$ARGUMENTS`, filter to only requirements for those phases
+   - Plan and create prototype files with `@gsd-tags` embedded in comments
+   - Write `.planning/prototype/PROTOTYPE-LOG.md` capturing files created, decisions made, and open todos
+
+2. **Wait for gsd-prototyper to complete** and note its summary output (files created, total tags embedded, breakdown by tag type).
+
+3. **Auto-run extract-plan** to produce CODE-INVENTORY.md from the annotated prototype:
+   ```bash
+   node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" extract-tags --format md --output .planning/prototype/CODE-INVENTORY.md
+   ```
+   This scans all prototype files for `@gsd-tags` and writes `.planning/prototype/CODE-INVENTORY.md` grouped by tag type and file, with summary statistics and a phase reference index.
+
+4. **Show the user the results:**
+   - Files created (from gsd-prototyper summary)
+   - Total @gsd-tags embedded (from gsd-prototyper summary)
+   - Path to PROTOTYPE-LOG.md: `.planning/prototype/PROTOTYPE-LOG.md`
+   - Path to CODE-INVENTORY.md: `.planning/prototype/CODE-INVENTORY.md`
+
+</process>

package/commands/gsd/quick.md

@@ -0,0 +1,47 @@
+---
+name: gsd:quick
+description: Execute a quick task with GSD guarantees (atomic commits, state tracking) but skip optional agents
+argument-hint: "[--full] [--discuss] [--research]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Execute small, ad-hoc tasks with GSD guarantees (atomic commits, STATE.md tracking).
+
+Quick mode is the same system with a shorter path:
+- Spawns gsd-planner (quick mode) + gsd-executor(s)
+- Quick tasks live in `.planning/quick/` separate from planned phases
+- Updates STATE.md "Quick Tasks Completed" table (NOT ROADMAP.md)
+
+**Default:** Skips research, discussion, plan-checker, verifier. Use when you know exactly what to do.
+
+**`--discuss` flag:** Lightweight discussion phase before planning. Surfaces assumptions, clarifies gray areas, captures decisions in CONTEXT.md. Use when the task has ambiguity worth resolving upfront.
+
+**`--full` flag:** Enables plan-checking (max 2 iterations) and post-execution verification. Use when you want quality guarantees without full milestone ceremony.
+
+**`--research` flag:** Spawns a focused research agent before planning. Investigates implementation approaches, library options, and pitfalls for the task. Use when you're unsure of the best approach.
+
+Flags are composable: `--discuss --research --full` gives discussion + research + plan-checking + verification.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/quick.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+
+Context files are resolved inside the workflow (`init quick`) and delegated via `<files_to_read>` blocks.
+</context>
+
+<process>
+Execute the quick workflow from @~/.claude/get-shit-done/workflows/quick.md end-to-end.
+Preserve all workflow gates (validation, task description, planning, execution, state updates, commits).
+</process>

package/commands/gsd/reapply-patches.md

@@ -0,0 +1,123 @@
+---
+description: Reapply local modifications after a GSD update
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+After a GSD update wipes and reinstalls files, this command merges user's previously saved local modifications back into the new version. Uses intelligent comparison to handle cases where the upstream file also changed.
+</purpose>
+
+<process>
+
+## Step 1: Detect backed-up patches
+
+Check for local patches directory:
+
+```bash
+# Global install — detect runtime config directory
+if [ -d "$HOME/.config/opencode/gsd-local-patches" ]; then
+  PATCHES_DIR="$HOME/.config/opencode/gsd-local-patches"
+elif [ -d "$HOME/.opencode/gsd-local-patches" ]; then
+  PATCHES_DIR="$HOME/.opencode/gsd-local-patches"
+elif [ -d "$HOME/.gemini/gsd-local-patches" ]; then
+  PATCHES_DIR="$HOME/.gemini/gsd-local-patches"
+else
+  PATCHES_DIR="$HOME/.claude/gsd-local-patches"
+fi
+# Local install fallback — check all runtime directories
+if [ ! -d "$PATCHES_DIR" ]; then
+  for dir in .config/opencode .opencode .gemini .claude; do
+    if [ -d "./$dir/gsd-local-patches" ]; then
+      PATCHES_DIR="./$dir/gsd-local-patches"
+      break
+    fi
+  done
+fi
+```
+
+Read `backup-meta.json` from the patches directory.
+
+**If no patches found:**
+```
+No local patches found. Nothing to reapply.
+
+Local patches are automatically saved when you run /gsd:update
+after modifying any GSD workflow, command, or agent files.
+```
+Exit.
+
+## Step 2: Show patch summary
+
+```
+## Local Patches to Reapply
+
+**Backed up from:** v{from_version}
+**Current version:** {read VERSION file}
+**Files modified:** {count}
+
+| # | File | Status |
+|---|------|--------|
+| 1 | {file_path} | Pending |
+| 2 | {file_path} | Pending |
+```
+
+## Step 3: Merge each file
+
+For each file in `backup-meta.json`:
+
+1. **Read the backed-up version** (user's modified copy from `gsd-local-patches/`)
+2. **Read the newly installed version** (current file after update)
+3. **Compare and merge:**
+
+   - If the new file is identical to the backed-up file: skip (modification was incorporated upstream)
+   - If the new file differs: identify the user's modifications and apply them to the new version
+
+   **Merge strategy:**
+   - Read both versions fully
+   - Identify sections the user added or modified (look for additions, not just differences from path replacement)
+   - Apply user's additions/modifications to the new version
+   - If a section the user modified was also changed upstream: flag as conflict, show both versions, ask user which to keep
+
+4. **Write merged result** to the installed location
+5. **Report status:**
+   - `Merged` — user modifications applied cleanly
+   - `Skipped` — modification already in upstream
+   - `Conflict` — user chose resolution
+
+## Step 4: Update manifest
+
+After reapplying, regenerate the file manifest so future updates correctly detect these as user modifications:
+
+```bash
+# The manifest will be regenerated on next /gsd:update
+# For now, just note which files were modified
+```
+
+## Step 5: Cleanup option
+
+Ask user:
+- "Keep patch backups for reference?" → preserve `gsd-local-patches/`
+- "Clean up patch backups?" → remove `gsd-local-patches/` directory
+
+## Step 6: Report
+
+```
+## Patches Reapplied
+
+| # | File | Status |
+|---|------|--------|
+| 1 | {file_path} | ✓ Merged |
+| 2 | {file_path} | ○ Skipped (already upstream) |
+| 3 | {file_path} | ⚠ Conflict resolved |
+
+{count} file(s) updated. Your local modifications are active again.
+```
+
+</process>
+
+<success_criteria>
+- [ ] All backed-up patches processed
+- [ ] User modifications merged into new version
+- [ ] Conflicts resolved with user input
+- [ ] Status reported for each file
+</success_criteria>

package/commands/gsd/remove-phase.md

@@ -0,0 +1,31 @@
+---
+name: gsd:remove-phase
+description: Remove a future phase from roadmap and renumber subsequent phases
+argument-hint: <phase-number>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+---
+<objective>
+Remove an unstarted future phase from the roadmap and renumber all subsequent phases to maintain a clean, linear sequence.
+
+Purpose: Clean removal of work you've decided not to do, without polluting context with cancelled/deferred markers.
+Output: Phase deleted, all subsequent phases renumbered, git commit as historical record.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/remove-phase.md
+</execution_context>
+
+<context>
+Phase: $ARGUMENTS
+
+Roadmap and state are resolved in-workflow via `init phase-op` and targeted reads.
+</context>
+
+<process>
+Execute the remove-phase workflow from @~/.claude/get-shit-done/workflows/remove-phase.md end-to-end.
+Preserve all validation gates (future phase check, work check), renumbering logic, and commit.
+</process>

package/commands/gsd/remove-workspace.md

@@ -0,0 +1,26 @@
+---
+name: gsd:remove-workspace
+description: Remove a GSD workspace and clean up worktrees
+argument-hint: "<workspace-name>"
+allowed-tools:
+  - Bash
+  - Read
+  - AskUserQuestion
+---
+<context>
+**Arguments:**
+- `<workspace-name>` (required) — Name of the workspace to remove
+</context>
+
+<objective>
+Remove a workspace directory after confirmation. For worktree strategy, runs `git worktree remove` for each member repo first. Refuses if any repo has uncommitted changes.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/remove-workspace.md
+@~/.claude/get-shit-done/references/ui-brand.md
+</execution_context>
+
+<process>
+Execute the remove-workspace workflow from @~/.claude/get-shit-done/workflows/remove-workspace.md end-to-end.
+</process>

package/commands/gsd/research-phase.md

@@ -0,0 +1,195 @@
+---
+name: gsd:research-phase
+description: Research how to implement a phase (standalone - usually use /gsd:plan-phase instead)
+argument-hint: "[phase]"
+allowed-tools:
+  - Read
+  - Bash
+  - Task
+---
+
+<objective>
+Research how to implement a phase. Spawns gsd-phase-researcher agent with phase context.
+
+**Note:** This is a standalone research command. For most workflows, use `/gsd:plan-phase` which integrates research automatically.
+
+**Use this command when:**
+- You want to research without planning yet
+- You want to re-research after planning is complete
+- You need to investigate before deciding if a phase is feasible
+
+**Orchestrator role:** Parse phase, validate against roadmap, check existing research, gather context, spawn researcher agent, present results.
+
+**Why subagent:** Research burns context fast (WebSearch, Context7 queries, source verification). Fresh 200k context for 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-phase-researcher — Researches technical approaches for a phase
+</available_agent_types>
+
+<context>
+Phase number: $ARGUMENTS (required)
+
+Normalize phase input in step 1 before any directory lookups.
+</context>
+
+<process>
+
+## 0. Initialize Context
+
+```bash
+INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op "$ARGUMENTS")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `phase_found`, `commit_docs`, `has_research`, `state_path`, `requirements_path`, `context_path`, `research_path`.
+
+Resolve researcher model:
+```bash
+RESEARCHER_MODEL=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" resolve-model gsd-phase-researcher --raw)
+```
+
+## 1. Validate Phase
+
+```bash
+PHASE_INFO=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "${phase_number}")
+```
+
+**If `found` is false:** Error and exit. **If `found` is true:** Extract `phase_number`, `phase_name`, `goal` from JSON.
+
+## 2. Check Existing Research
+
+```bash
+ls .planning/phases/${PHASE}-*/RESEARCH.md 2>/dev/null
+```
+
+**If exists:** Offer: 1) Update research, 2) View existing, 3) Skip. Wait for response.
+
+**If doesn't exist:** Continue.
+
+## 3. Gather Phase Context
+
+Use paths from INIT (do not inline file contents in orchestrator context):
+- `requirements_path`
+- `context_path`
+- `state_path`
+
+Present summary with phase description and what files the researcher will load.
+
+## 4. Spawn gsd-phase-researcher Agent
+
+Research modes: ecosystem (default), feasibility, implementation, comparison.
+
+```markdown
+<research_type>
+Phase Research — investigating HOW to implement a specific phase well.
+</research_type>
+
+<key_insight>
+The question is NOT "which library should I use?"
+
+The question is: "What do I not know that I don't know?"
+
+For this phase, discover:
+- What's the established architecture pattern?
+- What libraries form the standard stack?
+- What problems do people commonly hit?
+- What's SOTA vs what Claude's training thinks is SOTA?
+- What should NOT be hand-rolled?
+</key_insight>
+
+<objective>
+Research implementation approach for Phase {phase_number}: {phase_name}
+Mode: ecosystem
+</objective>
+
+<files_to_read>
+- {requirements_path} (Requirements)
+- {context_path} (Phase context from discuss-phase, if exists)
+- {state_path} (Prior project decisions and blockers)
+</files_to_read>
+
+<additional_context>
+**Phase description:** {phase_description}
+</additional_context>
+
+<downstream_consumer>
+Your RESEARCH.md will be loaded by `/gsd:plan-phase` which uses specific sections:
+- `## Standard Stack` → Plans use these libraries
+- `## Architecture Patterns` → Task structure follows these
+- `## Don't Hand-Roll` → Tasks NEVER build custom solutions for listed problems
+- `## Common Pitfalls` → Verification steps check for these
+- `## Code Examples` → Task actions reference these patterns
+
+Be prescriptive, not exploratory. "Use X" not "Consider X or Y."
+</downstream_consumer>
+
+<quality_gate>
+Before declaring complete, verify:
+- [ ] All domains investigated (not just some)
+- [ ] Negative claims verified with official docs
+- [ ] Multiple sources for critical claims
+- [ ] Confidence levels assigned honestly
+- [ ] Section names match what plan-phase expects
+</quality_gate>
+
+<output>
+Write to: .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md
+</output>
+```
+
+```
+Task(
+  prompt=filled_prompt,
+  subagent_type="gsd-phase-researcher",
+  model="{researcher_model}",
+  description="Research Phase {phase}"
+)
+```
+
+## 5. Handle Agent Return
+
+**`## RESEARCH COMPLETE`:** Display summary, offer: Plan phase, Dig deeper, Review full, Done.
+
+**`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation.
+
+**`## RESEARCH INCONCLUSIVE`:** Show what was attempted, offer: Add context, Try different mode, Manual.
+
+## 6. Spawn Continuation Agent
+
+```markdown
+<objective>
+Continue research for Phase {phase_number}: {phase_name}
+</objective>
+
+<prior_state>
+<files_to_read>
+- .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md (Existing research)
+</files_to_read>
+</prior_state>
+
+<checkpoint_response>
+**Type:** {checkpoint_type}
+**Response:** {user_response}
+</checkpoint_response>
+```
+
+```
+Task(
+  prompt=continuation_prompt,
+  subagent_type="gsd-phase-researcher",
+  model="{researcher_model}",
+  description="Continue research Phase {phase}"
+)
+```
+
+</process>
+
+<success_criteria>
+- [ ] Phase validated against roadmap
+- [ ] Existing research checked
+- [ ] gsd-phase-researcher spawned with context
+- [ ] Checkpoints handled correctly
+- [ ] User knows next steps
+</success_criteria>