gsd-opencode 1.5.2 → 1.6.0

package/command/gsd/debug.md

@@ -2,57 +2,147 @@
 name: gsd-debug
 description: Systematic debugging with persistent state across context resets
 argument-hint: [issue description]
-allowed-tools:
+tools:
   - read
-  - write
-  - edit
   - bash
-  - grep
-  - glob
   - question
 ---
 
 <objective>
-Debug issues using scientific method with a persistent debug document that survives `/new`.
+Debug issues using scientific method with subagent isolation.
 
-If resuming (no arguments and active session exists): pick up where you left off.
-If starting new: gather symptoms, then investigate autonomously.
-</objective>
+**Orchestrator role:** Gather symptoms, spawn gsd-debugger agent, handle checkpoints, spawn continuations.
 
-<execution_context>
-@~/.config/opencode/get-shit-done/workflows/debug.md
-@~/.config/opencode/get-shit-done/templates/DEBUG.md
-</execution_context>
+**Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction.
+</objective>
 
 <context>
 User's issue: $ARGUMENTS
 
-Check for active debug sessions:
+Check for active sessions:
 ```bash
-ls .planning/debug/*.md 2>/dev/null | head -5
+ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
 ```
 </context>
 
 <process>
-Follow the workflow in @~/.config/opencode/get-shit-done/workflows/debug.md
 
-**Quick reference:**
+## 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 question 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",
+  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
+- 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:
 
-1. **Check for active sessions** - Offer to resume or start new
-2. **Gather symptoms** - What happened? What should happen? Errors? When?
-3. **Create DEBUG.md** - Document symptoms in `.planning/debug/[slug].md`
-4. **Investigate** - Evidence → Hypothesis → Test → Eliminate or Confirm
-5. **Fix and verify** - Minimal fix, verify against original symptoms
-6. **Archive** - Move to `.planning/debug/resolved/`
+```markdown
+<objective>
+Continue debugging {slug}. Evidence is in the debug file.
+</objective>
+
+<prior_state>
+Debug file: @.planning/debug/{slug}.md
+</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",
+  description="Continue debug {slug}"
+)
+```
 
-**Key principle:** The DEBUG.md is your memory. Update it constantly. It survives `/new`.
 </process>
 
 <success_criteria>
-- [ ] Active sessions checked before starting new
-- [ ] Symptoms gathered through question (not inline questions)
-- [ ] DEBUG.md tracks all investigation state
-- [ ] Scientific method followed (not random fixes)
-- [ ] Root cause confirmed with evidence before fixing
-- [ ] Fix verified and session archived
+- [ ] Active sessions checked
+- [ ] Symptoms gathered (if new)
+- [ ] gsd-debugger spawned with context
+- [ ] Checkpoints handled correctly
+- [ ] Root cause confirmed before fixing
 </success_criteria>

package/command/gsd/discuss-phase.md

@@ -1,15 +1,20 @@
 ---
 name: gsd-discuss-phase
 description: Gather phase context through adaptive questioning before planning
-argument-hint: "[phase]"
+argument-hint: "<phase>"
+tools: [read, write, bash, glob, grep, question]
 ---
 
 <objective>
-Help the user articulate their vision for a phase through collaborative thinking.
+Extract implementation decisions that downstream agents need — researcher and planner will use CONTEXT.md to know what to investigate and what choices are locked.
 
-Purpose: Understand HOW the user imagines this phase working — what it looks like, what's essential. You're a thinking partner helping them crystallize their vision, not an interviewer gathering technical requirements.
+**How it works:**
+1. Analyze the phase to identify gray areas (UI, UX, behavior, etc.)
+2. Present gray areas — user selects which to discuss
+3. Deep-dive each selected area until satisfied
+4. Create CONTEXT.md with decisions that guide research and planning
 
-Output: {phase}-CONTEXT.md capturing the user's vision for the phase
+**Output:** `{phase}-CONTEXT.md` — decisions clear enough that downstream agents can act without asking the user again
 </objective>
 
 <execution_context>
@@ -20,7 +25,7 @@ Output: {phase}-CONTEXT.md capturing the user's vision for the phase
 <context>
 Phase number: $ARGUMENTS (required)
 
-**Load project state first:**
+**Load project state:**
 @.planning/STATE.md
 
 **Load roadmap:**
@@ -28,32 +33,48 @@ Phase number: $ARGUMENTS (required)
 </context>
 
 <process>
-1. Validate phase number argument (error if missing or invalid)
-2. Check if phase exists in roadmap
-3. Check if CONTEXT.md already exists (offer to update if yes)
-4. Follow discuss-phase.md workflow with **ALL questions using question**:
-   - Present phase from roadmap
-   - Use question: "How do you imagine this working?" with interpretation options
-   - Use question to follow their thread — probe what excites them
-   - Use question to sharpen the core — what's essential for THIS phase
-   - Use question for decision gate (ready / ask more / let me add context)
-   - Create CONTEXT.md capturing their vision
-5. Offer next steps (research or plan the phase)
-
-**CRITICAL: ALL questions use question. Never ask inline text questions.**
-
-User is the visionary, you are the builder:
-- Ask about vision, feel, essential outcomes
-- DON'T ask about technical risks (you figure those out)
-- DON'T ask about codebase patterns (you read the code)
-- DON'T ask about success metrics (too corporate)
-- DON'T interrogate about constraints they didn't mention
+1. Validate phase number (error if missing or not in roadmap)
+2. Check if CONTEXT.md exists (offer update/view/skip if yes)
+3. **Analyze phase** — Identify domain and generate phase-specific gray areas
+4. **Present gray areas** — Multi-select: which to discuss? (NO skip option)
+5. **Deep-dive each area** — 4 questions per area, then offer more/next
+6. **write CONTEXT.md** — Sections match areas discussed
+7. Offer next steps (research or plan)
+
+**CRITICAL: Scope guardrail**
+- Phase boundary from ROADMAP.md is FIXED
+- Discussion clarifies HOW to implement, not WHETHER to add more
+- If user suggests new capabilities: "That's its own phase. I'll note it for later."
+- Capture deferred ideas — don't lose them, don't act on them
+
+**Domain-aware gray areas:**
+Gray areas depend on what's being built. Analyze the phase goal:
+- Something users SEE → layout, density, interactions, states
+- Something users CALL → responses, errors, auth, versioning
+- Something users RUN → output format, flags, modes, error handling
+- Something users READ → structure, tone, depth, flow
+- Something being ORGANIZED → criteria, grouping, naming, exceptions
+
+Generate 3-4 **phase-specific** gray areas, not generic categories.
+
+**Probing depth:**
+- Ask 4 questions per area before checking
+- "More questions about [area], or move to next?"
+- If more → ask 4 more, check again
+- After all areas → "Ready to create context?"
+
+**Do NOT ask about (OpenCode handles these):**
+- Technical implementation
+- Architecture choices
+- Performance concerns
+- Scope expansion
 </process>
 
 <success_criteria>
-
-- Phase validated against roadmap
-- Vision gathered through collaborative thinking (not interrogation)
-- CONTEXT.md captures: how it works, what's essential
-- User knows next steps (research or plan the phase)
+- 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/command/gsd/execute-phase.md

@@ -1,15 +1,14 @@
 ---
 name: gsd-execute-phase
 description: Execute all plans in a phase with wave-based parallelization
-argument-hint: "<phase-number>"
-allowed-tools:
+argument-hint: "<phase-number> [--gaps-only]"
+tools:
   - read
   - write
   - edit
   - glob
   - grep
   - bash
-  - task
   - todowrite
   - question
 ---
@@ -23,13 +22,16 @@ Context budget: ~15% orchestrator, 100% fresh per subagent.
 </objective>
 
 <execution_context>
+@~/.config/opencode/get-shit-done/references/ui-brand.md
 @~/.config/opencode/get-shit-done/workflows/execute-phase.md
-@~/.config/opencode/get-shit-done/templates/subagent-task-prompt.md
 </execution_context>
 
 <context>
 Phase: $ARGUMENTS
 
+**Flags:**
+- `--gaps-only` — Execute only gap closure plans (plans with `gap_closure: true` in frontmatter). Use after verify-work creates fix plans.
+
 @.planning/ROADMAP.md
 @.planning/STATE.md
 </context>
@@ -43,53 +45,208 @@ Phase: $ARGUMENTS
 2. **Discover plans**
    - List all *-PLAN.md files in phase directory
    - Check which have *-SUMMARY.md (already complete)
+   - If `--gaps-only`: filter to only plans with `gap_closure: true`
    - Build list of incomplete plans
 
 3. **Group by wave**
-   - Read `wave` from each plan's frontmatter
+   - read `wave` from each plan's frontmatter
    - Group plans by wave number
    - Report wave structure to user
 
 4. **Execute waves**
    For each wave in order:
-   - Fill subagent-task-prompt template for each plan
-   - Spawn all agents in wave simultaneously (parallel task calls)
-   - Wait for completion (task blocks)
+   - Spawn `gsd-executor` for each plan in wave (parallel Task calls)
+   - Wait for completion (Task blocks)
    - Verify SUMMARYs created
    - Proceed to next wave
 
 5. **Aggregate results**
    - Collect summaries from all plans
    - Report phase completion status
-   - Update ROADMAP.md
 
-6. **Offer next steps**
-   - More phases → `/gsd-plan-phase {next}`
-   - Milestone complete → `/gsd-complete-milestone`
+6. **Commit any orchestrator corrections**
+   Check for uncommitted changes before verification:
+   ```bash
+   git status --porcelain
+   ```
+
+   **If changes exist:** Orchestrator made corrections between executor completions. Commit them:
+   ```bash
+   git add -u && git commit -m "fix({phase}): orchestrator corrections"
+   ```
+
+   **If clean:** Continue to verification.
+
+7. **Verify phase goal**
+   - Spawn `gsd-verifier` subagent with phase directory and goal
+   - Verifier checks must_haves against actual codebase (not SUMMARY claims)
+   - Creates VERIFICATION.md with detailed report
+   - Route by status:
+     - `passed` → continue to step 8
+     - `human_needed` → present items, get approval or feedback
+     - `gaps_found` → present gaps, offer `/gsd-plan-phase {X} --gaps`
+
+8. **Update roadmap and state**
+   - Update ROADMAP.md, STATE.md
+
+9. **Update requirements**
+   Mark phase requirements as Complete:
+   - read ROADMAP.md, find this phase's `Requirements:` line (e.g., "AUTH-01, AUTH-02")
+   - read REQUIREMENTS.md traceability table
+   - For each REQ-ID in this phase: change Status from "Pending" to "Complete"
+   - write updated REQUIREMENTS.md
+   - Skip if: REQUIREMENTS.md doesn't exist, or phase has no Requirements line
+
+10. **Commit phase completion**
+    Bundle all phase metadata updates in one commit:
+    - Stage: `git add .planning/ROADMAP.md .planning/STATE.md`
+    - Stage REQUIREMENTS.md if updated: `git add .planning/REQUIREMENTS.md`
+    - Commit: `docs({phase}): complete {phase-name} phase`
+
+11. **Offer next steps**
+    - Route to next action (see `<offer_next>`)
 </process>
 
+<offer_next>
+Output this markdown directly (not as a code block). Route based on status:
+
+| Status | Route |
+|--------|-------|
+| `gaps_found` | Route C (gap closure) |
+| `human_needed` | Present checklist, then re-route based on approval |
+| `passed` + more phases | Route A (next phase) |
+| `passed` + last phase | Route B (milestone complete) |
+
+---
+
+**Route A: Phase verified, more phases remain**
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► PHASE {Z} COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Phase {Z}: {Name}**
+
+{Y} plans executed
+Goal verified ✓
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Phase {Z+1}: {Name}** — {Goal from ROADMAP.md}
+
+/gsd-discuss-phase {Z+1} — gather context and clarify approach
+
+*/new first → fresh context window*
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- /gsd-plan-phase {Z+1} — skip discussion, plan directly
+- /gsd-verify-work {Z} — manual acceptance testing before continuing
+
+───────────────────────────────────────────────────────────────
+
+---
+
+**Route B: Phase verified, milestone complete**
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► MILESTONE COMPLETE 🎉
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**v1.0**
+
+{N} phases completed
+All phase goals verified ✓
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Audit milestone** — verify requirements, cross-phase integration, E2E flows
+
+/gsd-audit-milestone
+
+*/new first → fresh context window*
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- /gsd-verify-work — manual acceptance testing
+- /gsd-complete-milestone — skip audit, archive directly
+
+───────────────────────────────────────────────────────────────
+
+---
+
+**Route C: Gaps found — need additional planning**
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► PHASE {Z} GAPS FOUND ⚠
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Phase {Z}: {Name}**
+
+Score: {N}/{M} must-haves verified
+Report: .planning/phases/{phase_dir}/{phase}-VERIFICATION.md
+
+### What's Missing
+
+{Extract gap summaries from VERIFICATION.md}
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Plan gap closure** — create additional plans to complete the phase
+
+/gsd-plan-phase {Z} --gaps
+
+*/new first → fresh context window*
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- cat .planning/phases/{phase_dir}/{phase}-VERIFICATION.md — see full report
+- /gsd-verify-work {Z} — manual testing before planning
+
+───────────────────────────────────────────────────────────────
+
+---
+
+After user runs /gsd-plan-phase {Z} --gaps:
+1. Planner reads VERIFICATION.md gaps
+2. Creates plans 04, 05, etc. to close gaps
+3. User runs /gsd-execute-phase {Z} again
+4. Execute-phase runs incomplete plans (04, 05...)
+5. Verifier runs again → loop until passed
+</offer_next>
+
 <wave_execution>
 **Parallel spawning:**
 
-Spawn all plans in a wave with a single message containing multiple task calls:
+Spawn all plans in a wave with a single message containing multiple Task calls:
 
 ```
-task(prompt=filled_template_for_plan_01, subagent_type="general")
-task(prompt=filled_template_for_plan_02, subagent_type="general")
-task(prompt=filled_template_for_plan_03, subagent_type="general")
+Task(prompt="Execute plan at {plan_01_path}\n\nPlan: @{plan_01_path}\nProject state: @.planning/STATE.md", subagent_type="gsd-executor")
+Task(prompt="Execute plan at {plan_02_path}\n\nPlan: @{plan_02_path}\nProject state: @.planning/STATE.md", subagent_type="gsd-executor")
+Task(prompt="Execute plan at {plan_03_path}\n\nPlan: @{plan_03_path}\nProject state: @.planning/STATE.md", subagent_type="gsd-executor")
 ```
 
-All three run in parallel. task tool blocks until all complete.
+All three run in parallel. Task tool blocks until all complete.
 
-**No polling.** No background agents.
+**No polling.** No background agents. No TaskOutput loops.
 </wave_execution>
 
 <checkpoint_handling>
-Plans with `autonomous: false` in frontmatter have checkpoints:
-- Run in their assigned wave (can be parallel with other plans)
-- Pause at checkpoint, return to orchestrator
-- Orchestrator presents checkpoint to user
-- User responds, orchestrator resumes agent
+Plans with `autonomous: false` have checkpoints. The execute-phase.md workflow handles the full checkpoint flow:
+- Subagent pauses at checkpoint, returns structured state
+- Orchestrator presents to user, collects response
+- Spawns fresh continuation agent (not resume)
+
+See `@~/.config/opencode/get-shit-done/workflows/execute-phase.md` step `checkpoint_handling` for complete details.
 </checkpoint_handling>
 
 <deviation_rules>
@@ -99,7 +256,6 @@ During execution, handle discoveries automatically:
 2. **Auto-add critical** - Security/correctness gaps, add and document
 3. **Auto-fix blockers** - Can't proceed without fix, do it and document
 4. **Ask about architectural** - Major structural changes, stop and ask user
-5. **Log enhancements** - Nice-to-haves, log to ISSUES.md, continue
 
 Only rule 4 requires user intervention.
 </deviation_rules>
@@ -115,11 +271,18 @@ After each task completes:
 
 **Plan Metadata Commit:**
 
-After all tasks complete:
-1. Stage planning artifacts only: PLAN.md, SUMMARY.md, STATE.md, ROADMAP.md
+After all tasks in a plan complete:
+1. Stage plan artifacts only: PLAN.md, SUMMARY.md
 2. Commit with format: `docs({phase}-{plan}): complete [plan-name] plan`
 3. NO code files (already committed per-task)
 
+**Phase Completion Commit:**
+
+After all plans in phase complete (step 7):
+1. Stage: ROADMAP.md, STATE.md, REQUIREMENTS.md (if updated), VERIFICATION.md
+2. Commit with format: `docs({phase}): complete {phase-name} phase`
+3. Bundles all phase-level state updates in one commit
+
 **NEVER use:**
 - `git add .`
 - `git add -A`
@@ -131,7 +294,10 @@ After all tasks complete:
 <success_criteria>
 - [ ] All incomplete plans in phase executed
 - [ ] Each plan has SUMMARY.md
+- [ ] Phase goal verified (must_haves checked against codebase)
+- [ ] VERIFICATION.md created in phase directory
 - [ ] STATE.md reflects phase completion
 - [ ] ROADMAP.md updated
+- [ ] REQUIREMENTS.md updated (phase requirements marked Complete)
 - [ ] User informed of next steps
 </success_criteria>