get-research-done 1.1.0

package/commands/grd/help.md

@@ -0,0 +1,482 @@
+---
+name: grd: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>
+
+<reference>
+# GSD Command Reference
+
+**GSD** (Get Shit Done) creates hierarchical project plans optimized for solo agentic development with Claude Code.
+
+## Quick Start
+
+1. `/grd:new-project` - Initialize project (includes research, requirements, roadmap)
+2. `/grd:plan-phase 1` - Create detailed plan for first phase
+3. `/grd:execute-phase 1` - Execute the phase
+
+## Staying Updated
+
+GSD evolves fast. Update periodically:
+
+```bash
+npx get-research-done-cc@latest
+```
+
+## Core Workflow
+
+```
+/grd:new-project → /grd:plan-phase → /grd:execute-phase → repeat
+```
+
+### Project Initialization
+
+**`/grd:new-project`**
+Initialize new project through unified flow.
+
+One command takes you from idea to ready-for-planning:
+- Deep questioning to understand what you're building
+- Optional domain research (spawns 4 parallel researcher agents)
+- Requirements definition with v1/v2/out-of-scope scoping
+- Roadmap creation with phase breakdown and success criteria
+
+Creates all `.planning/` artifacts:
+- `PROJECT.md` — vision and requirements
+- `config.json` — workflow mode (interactive/yolo)
+- `research/` — domain research (if selected)
+- `REQUIREMENTS.md` — scoped requirements with REQ-IDs
+- `ROADMAP.md` — phases mapped to requirements
+- `STATE.md` — project memory
+
+Usage: `/grd:new-project`
+
+**`/grd:map-codebase`**
+Map an existing codebase for brownfield projects.
+
+- Analyzes codebase with parallel Explore agents
+- Creates `.planning/codebase/` with 7 focused documents
+- Covers stack, architecture, structure, conventions, testing, integrations, concerns
+- Use before `/grd:new-project` on existing codebases
+
+Usage: `/grd:map-codebase`
+
+### Phase Planning
+
+**`/grd:discuss-phase <number>`**
+Help articulate your vision for a phase before planning.
+
+- Captures how you imagine this phase working
+- Creates CONTEXT.md with your vision, essentials, and boundaries
+- Use when you have ideas about how something should look/feel
+
+Usage: `/grd:discuss-phase 2`
+
+**`/grd:research-phase <number>`**
+Comprehensive ecosystem research for niche/complex domains.
+
+- Discovers standard stack, architecture patterns, pitfalls
+- Creates RESEARCH.md with "how experts build this" knowledge
+- Use for 3D, games, audio, shaders, ML, and other specialized domains
+- Goes beyond "which library" to ecosystem knowledge
+
+Usage: `/grd:research-phase 3`
+
+**`/grd:list-phase-assumptions <number>`**
+See what Claude is planning to do before it starts.
+
+- Shows Claude's intended approach for a phase
+- Lets you course-correct if Claude misunderstood your vision
+- No files created - conversational output only
+
+Usage: `/grd:list-phase-assumptions 3`
+
+**`/grd:plan-phase <number>`**
+Create detailed execution plan for a specific phase.
+
+- Generates `.planning/phases/XX-phase-name/XX-YY-PLAN.md`
+- Breaks phase into concrete, actionable tasks
+- Includes verification criteria and success measures
+- Multiple plans per phase supported (XX-01, XX-02, etc.)
+
+Usage: `/grd:plan-phase 1`
+Result: Creates `.planning/phases/01-foundation/01-01-PLAN.md`
+
+### Execution
+
+**`/grd:execute-phase <phase-number>`**
+Execute all plans in a phase.
+
+- Groups plans by wave (from frontmatter), executes waves sequentially
+- Plans within each wave run in parallel via Task tool
+- Verifies phase goal after all plans complete
+- Updates REQUIREMENTS.md, ROADMAP.md, STATE.md
+
+Usage: `/grd:execute-phase 5`
+
+### Quick Mode
+
+**`/grd:quick`**
+Execute small, ad-hoc tasks with GSD guarantees but skip optional agents.
+
+Quick mode uses the same system with a shorter path:
+- Spawns planner + executor (skips researcher, checker, verifier)
+- Quick tasks live in `.planning/quick/` separate from planned phases
+- Updates STATE.md tracking (not ROADMAP.md)
+
+Use when you know exactly what to do and the task is small enough to not need research or verification.
+
+Usage: `/grd:quick`
+Result: Creates `.planning/quick/NNN-slug/PLAN.md`, `.planning/quick/NNN-slug/SUMMARY.md`
+
+### Roadmap Management
+
+**`/grd:add-phase <description>`**
+Add new phase to end of current milestone.
+
+- Appends to ROADMAP.md
+- Uses next sequential number
+- Updates phase directory structure
+
+Usage: `/grd:add-phase "Add admin dashboard"`
+
+**`/grd:insert-phase <after> <description>`**
+Insert urgent work as decimal phase between existing phases.
+
+- Creates intermediate phase (e.g., 7.1 between 7 and 8)
+- Useful for discovered work that must happen mid-milestone
+- Maintains phase ordering
+
+Usage: `/grd:insert-phase 7 "Fix critical auth bug"`
+Result: Creates Phase 7.1
+
+**`/grd:remove-phase <number>`**
+Remove a future phase and renumber subsequent phases.
+
+- Deletes phase directory and all references
+- Renumbers all subsequent phases to close the gap
+- Only works on future (unstarted) phases
+- Git commit preserves historical record
+
+Usage: `/grd:remove-phase 17`
+Result: Phase 17 deleted, phases 18-20 become 17-19
+
+### Milestone Management
+
+**`/grd:new-milestone <name>`**
+Start a new milestone through unified flow.
+
+- Deep questioning to understand what you're building next
+- Optional domain research (spawns 4 parallel researcher agents)
+- Requirements definition with scoping
+- Roadmap creation with phase breakdown
+
+Mirrors `/grd:new-project` flow for brownfield projects (existing PROJECT.md).
+
+Usage: `/grd:new-milestone "v2.0 Features"`
+
+**`/grd:complete-milestone <version>`**
+Archive completed milestone and prepare for next version.
+
+- Creates MILESTONES.md entry with stats
+- Archives full details to milestones/ directory
+- Creates git tag for the release
+- Prepares workspace for next version
+
+Usage: `/grd:complete-milestone 1.0.0`
+
+### Progress Tracking
+
+**`/grd:progress`**
+Check project status and intelligently route to next action.
+
+- Shows visual progress bar and completion percentage
+- Summarizes recent work from SUMMARY files
+- Displays current position and what's next
+- Lists key decisions and open issues
+- Offers to execute next plan or create it if missing
+- Detects 100% milestone completion
+
+Usage: `/grd:progress`
+
+### Session Management
+
+**`/grd:resume-work`**
+Resume work from previous session with full context restoration.
+
+- Reads STATE.md for project context
+- Shows current position and recent progress
+- Offers next actions based on project state
+
+Usage: `/grd:resume-work`
+
+**`/grd:pause-work`**
+Create context handoff when pausing work mid-phase.
+
+- Creates .continue-here file with current state
+- Updates STATE.md session continuity section
+- Captures in-progress work context
+
+Usage: `/grd:pause-work`
+
+### Debugging
+
+**`/grd:debug [issue description]`**
+Systematic debugging with persistent state across context resets.
+
+- Gathers symptoms through adaptive questioning
+- Creates `.planning/debug/[slug].md` to track investigation
+- Investigates using scientific method (evidence → hypothesis → test)
+- Survives `/clear` — run `/grd:debug` with no args to resume
+- Archives resolved issues to `.planning/debug/resolved/`
+
+Usage: `/grd:debug "login button doesn't work"`
+Usage: `/grd:debug` (resume active session)
+
+### Todo Management
+
+**`/grd:add-todo [description]`**
+Capture idea or task as todo from current conversation.
+
+- Extracts context from conversation (or uses provided description)
+- Creates structured todo file in `.planning/todos/pending/`
+- Infers area from file paths for grouping
+- Checks for duplicates before creating
+- Updates STATE.md todo count
+
+Usage: `/grd:add-todo` (infers from conversation)
+Usage: `/grd:add-todo Add auth token refresh`
+
+**`/grd:check-todos [area]`**
+List pending todos and select one to work on.
+
+- Lists all pending todos with title, area, age
+- Optional area filter (e.g., `/grd:check-todos api`)
+- Loads full context for selected todo
+- Routes to appropriate action (work now, add to phase, brainstorm)
+- Moves todo to done/ when work begins
+
+Usage: `/grd:check-todos`
+Usage: `/grd:check-todos api`
+
+### User Acceptance Testing
+
+**`/grd:verify-work [phase]`**
+Validate built features through conversational UAT.
+
+- Extracts testable deliverables from SUMMARY.md files
+- Presents tests one at a time (yes/no responses)
+- Automatically diagnoses failures and creates fix plans
+- Ready for re-execution if issues found
+
+Usage: `/grd:verify-work 3`
+
+### Milestone Auditing
+
+**`/grd:audit-milestone [version]`**
+Audit milestone completion against original intent.
+
+- Reads all phase VERIFICATION.md files
+- Checks requirements coverage
+- Spawns integration checker for cross-phase wiring
+- Creates MILESTONE-AUDIT.md with gaps and tech debt
+
+Usage: `/grd:audit-milestone`
+
+**`/grd:plan-milestone-gaps`**
+Create phases to close gaps identified by audit.
+
+- Reads MILESTONE-AUDIT.md and groups gaps into phases
+- Prioritizes by requirement priority (must/should/nice)
+- Adds gap closure phases to ROADMAP.md
+- Ready for `/grd:plan-phase` on new phases
+
+Usage: `/grd:plan-milestone-gaps`
+
+### Configuration
+
+**`/grd:settings`**
+Configure workflow toggles and model profile interactively.
+
+- Toggle researcher, plan checker, verifier agents
+- Select model profile (quality/balanced/budget)
+- Updates `.planning/config.json`
+
+Usage: `/grd:settings`
+
+**`/grd:set-profile <profile>`**
+Quick switch model profile for GSD agents.
+
+- `quality` — Opus everywhere except verification
+- `balanced` — Opus for planning, Sonnet for execution (default)
+- `budget` — Sonnet for writing, Haiku for research/verification
+
+Usage: `/grd:set-profile budget`
+
+### Utility Commands
+
+**`/grd:help`**
+Show this command reference.
+
+**`/grd:update`**
+Update GSD to latest version with changelog preview.
+
+- Shows installed vs latest version comparison
+- Displays changelog entries for versions you've missed
+- Highlights breaking changes
+- Confirms before running install
+- Better than raw `npx get-research-done-cc`
+
+Usage: `/grd:update`
+
+**`/grd:join-discord`**
+Join the GSD Discord community.
+
+- Get help, share what you're building, stay updated
+- Connect with other GSD users
+
+Usage: `/grd:join-discord`
+
+## Files & Structure
+
+```
+.planning/
+├── PROJECT.md            # Project vision
+├── ROADMAP.md            # Current phase breakdown
+├── STATE.md              # Project memory & context
+├── config.json           # Workflow mode & gates
+├── todos/                # Captured ideas and tasks
+│   ├── pending/          # Todos waiting to be worked on
+│   └── done/             # Completed todos
+├── debug/                # Active debug sessions
+│   └── resolved/         # Archived resolved issues
+├── codebase/             # Codebase map (brownfield projects)
+│   ├── STACK.md          # Languages, frameworks, dependencies
+│   ├── ARCHITECTURE.md   # Patterns, layers, data flow
+│   ├── STRUCTURE.md      # Directory layout, key files
+│   ├── CONVENTIONS.md    # Coding standards, naming
+│   ├── TESTING.md        # Test setup, patterns
+│   ├── INTEGRATIONS.md   # External services, APIs
+│   └── CONCERNS.md       # Tech debt, known issues
+└── phases/
+    ├── 01-foundation/
+    │   ├── 01-01-PLAN.md
+    │   └── 01-01-SUMMARY.md
+    └── 02-core-features/
+        ├── 02-01-PLAN.md
+        └── 02-01-SUMMARY.md
+```
+
+## Workflow Modes
+
+Set during `/grd:new-project`:
+
+**Interactive Mode**
+
+- Confirms each major decision
+- Pauses at checkpoints for approval
+- More guidance throughout
+
+**YOLO Mode**
+
+- Auto-approves most decisions
+- Executes plans without confirmation
+- Only stops for critical checkpoints
+
+Change anytime by editing `.planning/config.json`
+
+## Planning Configuration
+
+Configure how planning artifacts are managed in `.planning/config.json`:
+
+**`planning.commit_docs`** (default: `true`)
+- `true`: Planning artifacts committed to git (standard workflow)
+- `false`: Planning artifacts kept local-only, not committed
+
+When `commit_docs: false`:
+- Add `.planning/` to your `.gitignore`
+- Useful for OSS contributions, client projects, or keeping planning private
+- All planning files still work normally, just not tracked in git
+
+**`planning.search_gitignored`** (default: `false`)
+- `true`: Add `--no-ignore` to broad ripgrep searches
+- Only needed when `.planning/` is gitignored and you want project-wide searches to include it
+
+Example config:
+```json
+{
+  "planning": {
+    "commit_docs": false,
+    "search_gitignored": true
+  }
+}
+```
+
+## Common Workflows
+
+**Starting a new project:**
+
+```
+/grd:new-project        # Unified flow: questioning → research → requirements → roadmap
+/clear
+/grd:plan-phase 1       # Create plans for first phase
+/clear
+/grd:execute-phase 1    # Execute all plans in phase
+```
+
+**Resuming work after a break:**
+
+```
+/grd:progress  # See where you left off and continue
+```
+
+**Adding urgent mid-milestone work:**
+
+```
+/grd:insert-phase 5 "Critical security fix"
+/grd:plan-phase 5.1
+/grd:execute-phase 5.1
+```
+
+**Completing a milestone:**
+
+```
+/grd:complete-milestone 1.0.0
+/clear
+/grd:new-milestone  # Start next milestone (questioning → research → requirements → roadmap)
+```
+
+**Capturing ideas during work:**
+
+```
+/grd:add-todo                    # Capture from conversation context
+/grd:add-todo Fix modal z-index  # Capture with explicit description
+/grd:check-todos                 # Review and work on todos
+/grd:check-todos api             # Filter by area
+```
+
+**Debugging an issue:**
+
+```
+/grd:debug "form submission fails silently"  # Start debug session
+# ... investigation happens, context fills up ...
+/clear
+/grd:debug                                    # Resume from where you left off
+```
+
+## Getting Help
+
+- Read `.planning/PROJECT.md` for project vision
+- Read `.planning/STATE.md` for current context
+- Check `.planning/ROADMAP.md` for phase status
+- Run `/grd:progress` to check where you're up to
+  </reference>

package/commands/grd/insert-phase.md

@@ -0,0 +1,227 @@
+---
+name: grd:insert-phase
+description: Insert urgent work as decimal phase (e.g., 72.1) between existing phases
+argument-hint: <after> <description>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<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>
+@.planning/ROADMAP.md
+@.planning/STATE.md
+</execution_context>
+
+<process>
+
+<step name="parse_arguments">
+Parse the command arguments:
+- First argument: integer phase number to insert after
+- Remaining arguments: phase description
+
+Example: `/grd:insert-phase 72 Fix critical auth bug`
+→ after = 72
+→ description = "Fix critical auth bug"
+
+Validation:
+
+```bash
+if [ $# -lt 2 ]; then
+  echo "ERROR: Both phase number and description required"
+  echo "Usage: /grd:insert-phase <after> <description>"
+  echo "Example: /grd:insert-phase 72 Fix critical auth bug"
+  exit 1
+fi
+```
+
+Parse first argument as integer:
+
+```bash
+after_phase=$1
+shift
+description="$*"
+
+# Validate after_phase is an integer
+if ! [[ "$after_phase" =~ ^[0-9]+$ ]]; then
+  echo "ERROR: Phase number must be an integer"
+  exit 1
+fi
+```
+
+</step>
+
+<step name="load_roadmap">
+Load the roadmap file:
+
+```bash
+if [ -f .planning/ROADMAP.md ]; then
+  ROADMAP=".planning/ROADMAP.md"
+else
+  echo "ERROR: No roadmap found (.planning/ROADMAP.md)"
+  exit 1
+fi
+```
+
+Read roadmap content for parsing.
+</step>
+
+<step name="verify_target_phase">
+Verify that the target phase exists in the roadmap:
+
+1. Search for "### Phase {after_phase}:" heading
+2. If not found:
+
+   ```
+   ERROR: Phase {after_phase} not found in roadmap
+   Available phases: [list phase numbers]
+   ```
+
+   Exit.
+
+3. Verify phase is in current milestone (not completed/archived)
+   </step>
+
+<step name="find_existing_decimals">
+Find existing decimal phases after the target phase:
+
+1. Search for all "### Phase {after_phase}.N:" headings
+2. Extract decimal suffixes (e.g., for Phase 72: find 72.1, 72.2, 72.3)
+3. Find the highest decimal suffix
+4. Calculate next decimal: max + 1
+
+Examples:
+
+- Phase 72 with no decimals → next is 72.1
+- Phase 72 with 72.1 → next is 72.2
+- Phase 72 with 72.1, 72.2 → next is 72.3
+
+Store as: `decimal_phase="$(printf "%02d" $after_phase).${next_decimal}"`
+</step>
+
+<step name="generate_slug">
+Convert the phase description to a kebab-case slug:
+
+```bash
+slug=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+```
+
+Phase directory name: `{decimal-phase}-{slug}`
+Example: `06.1-fix-critical-auth-bug` (phase 6 insertion)
+</step>
+
+<step name="create_phase_directory">
+Create the phase directory structure:
+
+```bash
+phase_dir=".planning/phases/${decimal_phase}-${slug}"
+mkdir -p "$phase_dir"
+```
+
+Confirm: "Created directory: $phase_dir"
+</step>
+
+<step name="update_roadmap">
+Insert the new phase entry into the roadmap:
+
+1. Find insertion point: immediately after Phase {after_phase}'s content (before next phase heading or "---")
+2. Insert new phase heading with (INSERTED) marker:
+
+   ```
+   ### Phase {decimal_phase}: {Description} (INSERTED)
+
+   **Goal:** [Urgent work - to be planned]
+   **Depends on:** Phase {after_phase}
+   **Plans:** 0 plans
+
+   Plans:
+   - [ ] TBD (run /grd:plan-phase {decimal_phase} to break down)
+
+   **Details:**
+   [To be added during planning]
+   ```
+
+3. Write updated roadmap back to file
+
+The "(INSERTED)" marker helps identify decimal phases as urgent insertions.
+
+Preserve all other content exactly (formatting, spacing, other phases).
+</step>
+
+<step name="update_project_state">
+Update STATE.md to reflect the inserted phase:
+
+1. Read `.planning/STATE.md`
+2. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
+   ```
+   - Phase {decimal_phase} inserted after Phase {after_phase}: {description} (URGENT)
+   ```
+
+If "Roadmap Evolution" section doesn't exist, create it.
+
+Add note about insertion reason if appropriate.
+</step>
+
+<step name="completion">
+Present completion summary:
+
+```
+Phase {decimal_phase} inserted after Phase {after_phase}:
+- Description: {description}
+- Directory: .planning/phases/{decimal-phase}-{slug}/
+- Status: Not planned yet
+- Marker: (INSERTED) - indicates urgent work
+
+Roadmap updated: {roadmap-path}
+Project state updated: .planning/STATE.md
+
+---
+
+## ▶ Next Up
+
+**Phase {decimal_phase}: {description}** — urgent insertion
+
+`/grd:plan-phase {decimal_phase}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Review insertion impact: Check if Phase {next_integer} dependencies still make sense
+- Review roadmap
+
+---
+```
+</step>
+
+</process>
+
+<anti_patterns>
+
+- Don't use this for planned work at end of milestone (use /grd:add-phase)
+- Don't insert before Phase 1 (decimal 0.1 makes no sense)
+- Don't renumber existing phases
+- Don't modify the target phase content
+- Don't create plans yet (that's /grd:plan-phase)
+- Don't commit changes (user decides when to commit)
+  </anti_patterns>
+
+<success_criteria>
+Phase insertion is complete when:
+
+- [ ] Phase directory created: `.planning/phases/{N.M}-{slug}/`
+- [ ] Roadmap updated with new phase entry (includes "(INSERTED)" marker)
+- [ ] Phase inserted in correct position (after target phase, before next integer phase)
+- [ ] STATE.md updated with roadmap evolution note
+- [ ] Decimal number calculated correctly (based on existing decimals)
+- [ ] User informed of next steps and dependency implications
+      </success_criteria>