gsd-opencode 1.3.31

package/command/gsd/help.md

@@ -0,0 +1,315 @@
+---
+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>
+
+<reference>
+# GSD Command Reference
+
+**GSD** (Get Shit Done) creates hierarchical project plans optimized for solo agentic development with OpenCode.
+
+## Quick Start
+
+1. `/gsd:new-project` - Initialize project with brief
+2. `/gsd:create-roadmap` - Create roadmap and phases
+3. `/gsd:plan-phase <number>` - Create detailed plan for first phase
+4. `/gsd:execute-plan <path>` - Execute the plan
+
+## Core Workflow
+
+```
+Initialization → Planning → Execution → Milestone Completion
+```
+
+### Project Initialization
+
+**`/gsd:new-project`**
+Initialize new project with brief and configuration.
+
+- Creates `.planning/PROJECT.md` (vision and requirements)
+- Creates `.planning/config.json` (workflow mode)
+- Asks for workflow mode (interactive/yolo) upfront
+- Commits initialization files to git
+
+Usage: `/gsd:new-project`
+
+**`/gsd:create-roadmap`**
+Create roadmap and state tracking for initialized project.
+
+- Creates `.planning/ROADMAP.md` (phase breakdown)
+- Creates `.planning/STATE.md` (project memory)
+- Creates `.planning/phases/` directories
+
+Usage: `/gsd:create-roadmap`
+
+**`/gsd: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 `/gsd:new-project` on existing codebases
+
+Usage: `/gsd:map-codebase`
+
+### Phase Planning
+
+**`/gsd: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: `/gsd:discuss-phase 2`
+
+**`/gsd: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: `/gsd:research-phase 3`
+
+**`/gsd: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: `/gsd:list-phase-assumptions 3`
+
+**`/gsd: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: `/gsd:plan-phase 1`
+Result: Creates `.planning/phases/01-foundation/01-01-PLAN.md`
+
+### Execution
+
+**`/gsd:execute-plan <path>`**
+Execute a PLAN.md file directly.
+
+- Runs plan tasks sequentially
+- Creates SUMMARY.md after completion
+- Updates STATE.md with accumulated context
+- Fast execution without loading full skill context
+
+Usage: `/gsd:execute-plan .planning/phases/01-foundation/01-01-PLAN.md`
+
+### Roadmap Management
+
+**`/gsd:add-phase <description>`**
+Add new phase to end of current milestone.
+
+- Appends to ROADMAP.md
+- Uses next sequential number
+- Updates phase directory structure
+
+Usage: `/gsd:add-phase "Add admin dashboard"`
+
+**`/gsd: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: `/gsd:insert-phase 7 "Fix critical auth bug"`
+Result: Creates Phase 7.1
+
+**`/gsd: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: `/gsd:remove-phase 17`
+Result: Phase 17 deleted, phases 18-20 become 17-19
+
+### Milestone Management
+
+**`/gsd:discuss-milestone`**
+Figure out what you want to build in the next milestone.
+
+- Reviews what shipped in previous milestone
+- Helps you identify features to add, improve, or fix
+- Routes to /gsd:new-milestone when ready
+
+Usage: `/gsd:discuss-milestone`
+
+**`/gsd:new-milestone <name>`**
+Create a new milestone with phases for an existing project.
+
+- Adds milestone section to ROADMAP.md
+- Creates phase directories
+- Updates STATE.md for new milestone
+
+Usage: `/gsd:new-milestone "v2.0 Features"`
+
+**`/gsd: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: `/gsd:complete-milestone 1.0.0`
+
+### Progress Tracking
+
+**`/gsd: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: `/gsd:progress`
+
+### Session Management
+
+**`/gsd: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: `/gsd:resume-work`
+
+**`/gsd: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: `/gsd:pause-work`
+
+### Issue Management
+
+**`/gsd:consider-issues`**
+Review deferred issues with codebase context.
+
+- Analyzes all open issues against current codebase state
+- Identifies resolved issues (can close)
+- Identifies urgent issues (should address now)
+- Identifies natural fits for upcoming phases
+- Offers batch actions (close, insert phase, note for planning)
+
+Usage: `/gsd:consider-issues`
+
+### Utility Commands
+
+**`/gsd:help`**
+Show this command reference.
+
+## Files & Structure
+
+```
+.planning/
+├── PROJECT.md            # Project vision
+├── ROADMAP.md            # Current phase breakdown
+├── STATE.md              # Project memory & context
+├── ISSUES.md             # Deferred enhancements (created when needed)
+├── config.json           # Workflow mode & gates
+├── 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 `/gsd: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`
+
+## Common Workflows
+
+**Starting a new project:**
+
+```
+/gsd:new-project
+/gsd:create-roadmap
+/gsd:plan-phase 1
+/gsd:execute-plan .planning/phases/01-foundation/01-01-PLAN.md
+```
+
+**Resuming work after a break:**
+
+```
+/gsd:progress  # See where you left off and continue
+```
+
+**Adding urgent mid-milestone work:**
+
+```
+/gsd:insert-phase 5 "Critical security fix"
+/gsd:plan-phase 5.1
+/gsd:execute-plan .planning/phases/05.1-critical-security-fix/05.1-01-PLAN.md
+```
+
+**Completing a milestone:**
+
+```
+/gsd:complete-milestone 1.0.0
+/gsd:new-project  # Start next milestone
+```
+
+## Getting Help
+
+- Read `.planning/PROJECT.md` for project vision
+- Read `.planning/STATE.md` for current context
+- Check `.planning/ROADMAP.md` for phase status
+- Run `/gsd:progress` to check where you're up to
+  </reference>

package/command/gsd/insert-phase.md

@@ -0,0 +1,227 @@
+---
+name: gsd:insert-phase
+description: Insert urgent work as decimal phase (e.g., 7.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 (7.1, 7.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: `/gsd:insert-phase 7 Fix critical auth bug`
+→ after = 7
+→ description = "Fix critical auth bug"
+
+Validation:
+
+```bash
+if [ $# -lt 2 ]; then
+  echo "ERROR: Both phase number and description required"
+  echo "Usage: /gsd:insert-phase <after> <description>"
+  echo "Example: /gsd:insert-phase 7 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 7: find 7.1, 7.2, 7.3)
+3. Find the highest decimal suffix
+4. Calculate next decimal: max + 1
+
+Examples:
+
+- Phase 7 with no decimals → next is 7.1
+- Phase 7 with 7.1 → next is 7.2
+- Phase 7 with 7.1, 7.2 → next is 7.3
+
+Store as: `decimal_phase="${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: `7.1-fix-critical-auth-bug`
+</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 /gsd: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
+
+`/gsd:plan-phase {decimal_phase}`
+
+*`/clear` first → fresh context window*
+
+---
+
+**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 /gsd: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 /gsd: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>

package/command/gsd/list-phase-assumptions.md

@@ -0,0 +1,50 @@
+---
+name: gsd:list-phase-assumptions
+description: Surface Claude's assumptions about a phase approach before planning
+argument-hint: "[phase]"
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+---
+
+<objective>
+Analyze a phase and present Claude's assumptions about technical approach, implementation order, scope boundaries, risk areas, and dependencies.
+
+Purpose: Help users see what Claude 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>
+@~/.config/opencode/get-shit-done/workflows/list-phase-assumptions.md
+</execution_context>
+
+<context>
+Phase number: $ARGUMENTS (required)
+
+**Load project state first:**
+@.planning/STATE.md
+
+**Load roadmap:**
+@.planning/ROADMAP.md
+</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/command/gsd/map-codebase.md

@@ -0,0 +1,84 @@
+---
+name: gsd:map-codebase
+description: Analyze codebase with parallel Explore agents to produce .planning/codebase/ documents
+argument-hint: "[optional: specific area to map, e.g., 'api' or 'auth']"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+<objective>
+Analyze existing codebase using parallel Explore agents to produce structured codebase documents.
+
+This command spawns multiple Explore agents to analyze different aspects of the codebase in parallel, each with fresh context.
+
+Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
+</objective>
+
+<execution_context>
+@~/.config/opencode/get-shit-done/workflows/map-codebase.md
+@~/.config/opencode/get-shit-done/templates/codebase/stack.md
+@~/.config/opencode/get-shit-done/templates/codebase/architecture.md
+@~/.config/opencode/get-shit-done/templates/codebase/structure.md
+@~/.config/opencode/get-shit-done/templates/codebase/conventions.md
+@~/.config/opencode/get-shit-done/templates/codebase/testing.md
+@~/.config/opencode/get-shit-done/templates/codebase/integrations.md
+@~/.config/opencode/get-shit-done/templates/codebase/concerns.md
+</execution_context>
+
+<context>
+Focus area: $ARGUMENTS (optional - if provided, tells agents to focus on specific subsystem)
+
+**Load project state if exists:**
+Check for .planning/STATE.md - loads context if project already initialized
+
+**This command can run:**
+- Before /gsd:new-project (brownfield codebases) - creates codebase map first
+- After /gsd:new-project (greenfield codebases) - updates codebase map as code evolves
+- Anytime to refresh codebase understanding
+</context>
+
+<when_to_use>
+**Use map-codebase for:**
+- Brownfield projects before initialization (understand existing code first)
+- Refreshing codebase map after significant changes
+- Onboarding to an unfamiliar codebase
+- Before major refactoring (understand current state)
+- When STATE.md references outdated codebase info
+
+**Skip map-codebase for:**
+- Greenfield projects with no code yet (nothing to map)
+- Trivial codebases (<5 files)
+</when_to_use>
+
+<process>
+1. Check if .planning/codebase/ already exists (offer to refresh or skip)
+2. Create .planning/codebase/ directory structure
+3. Spawn 4 parallel Explore agents to analyze codebase:
+   - Agent 1: Stack + Integrations (technology focus)
+   - Agent 2: Architecture + Structure (organization focus)
+   - Agent 3: Conventions + Testing (quality focus)
+   - Agent 4: Concerns (issues focus)
+4. Wait for all agents to complete, collect findings
+5. Write 7 codebase documents using templates:
+   - STACK.md - Languages, frameworks, key dependencies
+   - ARCHITECTURE.md - System design, patterns, data flow
+   - STRUCTURE.md - Directory layout, module organization
+   - CONVENTIONS.md - Code style, naming, patterns
+   - TESTING.md - Test structure, coverage, practices
+   - INTEGRATIONS.md - APIs, databases, external services
+   - CONCERNS.md - Technical debt, risks, issues
+6. Offer next steps (typically: /gsd:new-project or /gsd:plan-phase)
+</process>
+
+<success_criteria>
+- [ ] .planning/codebase/ directory created
+- [ ] All 7 codebase documents written
+- [ ] Documents follow template structure
+- [ ] Parallel agents completed without errors
+- [ ] User knows next steps
+</success_criteria>