gsd-opencode 1.5.2 → 1.6.0

package/get-shit-done/workflows/complete-milestone.md

@@ -8,12 +8,13 @@ This is the ritual that separates "development" from "shipped."
 
 <required_reading>
 
-**Read these files NOW:**
+**read these files NOW:**
 
 1. templates/milestone.md
 2. templates/milestone-archive.md
 3. `.planning/ROADMAP.md`
-4. `.planning/PROJECT.md`
+4. `.planning/REQUIREMENTS.md`
+5. `.planning/PROJECT.md`
 
 </required_reading>
 
@@ -22,24 +23,31 @@ This is the ritual that separates "development" from "shipped."
 When a milestone completes, this workflow:
 
 1. Extracts full milestone details to `.planning/milestones/v[X.Y]-ROADMAP.md`
-2. Updates ROADMAP.md to replace milestone details with one-line summary
-3. Links to archive file for historical reference
-4. Performs full PROJECT.md evolution review
-5. Offers to create next milestone inline
+2. Archives requirements to `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
+3. Updates ROADMAP.md to replace milestone details with one-line summary
+4. Deletes REQUIREMENTS.md (fresh one created for next milestone)
+5. Performs full PROJECT.md evolution review
+6. Offers to create next milestone inline
 
 **Context Efficiency:**
 
 - Completed milestones: One line each (~50 tokens)
 - Full details: In archive files (loaded only when needed)
-- Result: ROADMAP.md stays constant size (~1-2k lines) forever
+- Result: ROADMAP.md stays constant size forever
+- Result: REQUIREMENTS.md is always milestone-scoped (not cumulative)
 
 **Archive Format:**
-Uses `templates/milestone-archive.md` template with:
 
+**ROADMAP archive** uses `templates/milestone-archive.md` template with:
 - Milestone header (status, phases, date)
 - Full phase details from roadmap
 - Milestone summary (decisions, issues, technical debt)
 
+**REQUIREMENTS archive** contains:
+- All v1 requirements marked complete with outcomes
+- Traceability table with final status
+- Notes on any requirements that changed during milestone
+
 </archival_behavior>
 
 <process>
@@ -151,7 +159,7 @@ Milestone Stats:
 
 <step name="extract_accomplishments">
 
-Read all phase SUMMARY.md files in milestone range:
+read all phase SUMMARY.md files in milestone range:
 
 ```bash
 cat .planning/phases/01-*/01-*-SUMMARY.md
@@ -221,7 +229,7 @@ Use template from `templates/milestone.md`:
 
 Perform full PROJECT.md evolution review at milestone completion.
 
-**Read all phase summaries in this milestone:**
+**read all phase summaries in this milestone:**
 
 ```bash
 cat .planning/phases/*-*/*-SUMMARY.md
@@ -230,7 +238,7 @@ cat .planning/phases/*-*/*-SUMMARY.md
 **Full review checklist:**
 
 1. **"What This Is" accuracy:**
-   - Read current description
+   - read current description
    - Compare to what was actually built
    - Update if the product has meaningfully changed
 
@@ -415,7 +423,7 @@ Extract completed milestone details and create archive file.
 
 1. Create archive file path: `.planning/milestones/v[X.Y]-ROADMAP.md`
 
-2. Read `~/.config/opencode/get-shit-done/templates/milestone-archive.md` template
+2. read `~/.config/opencode/get-shit-done/templates/milestone-archive.md` template
 
 3. Extract data from current ROADMAP.md:
    - All phases belonging to this milestone (by phase number range)
@@ -437,26 +445,109 @@ Extract completed milestone details and create archive file.
    - {{PHASES_SECTION}} — Full phase details extracted
    - {{DECISIONS_FROM_PROJECT}} — Key decisions from PROJECT.md
    - {{ISSUES_RESOLVED_DURING_MILESTONE}} — From summaries
-   - {{ISSUES_DEFERRED_TO_LATER}} — From ISSUES.md
 
-6. Write filled template to `.planning/milestones/v[X.Y]-ROADMAP.md`
+6. write filled template to `.planning/milestones/v[X.Y]-ROADMAP.md`
 
-7. Update ROADMAP.md:
-   - Create/update "## Completed Milestones" section if not exists
-   - Add one-line entry: `- ✅ [v[X.Y] [Name]](milestones/v[X.Y]-ROADMAP.md) (Phases [N]-[M]) — SHIPPED [DATE]`
-   - Remove full milestone details from "Current Milestone" section
-   - Move next planned milestone to "Current Milestone" position
+7. Delete ROADMAP.md (fresh one created for next milestone):
+   ```bash
+   rm .planning/ROADMAP.md
+   ```
 
-8. Verify files:
-   - Check archive file exists: `ls .planning/milestones/v[X.Y]-ROADMAP.md`
-   - Validate ROADMAP.md still parseable
+8. Verify archive exists:
+   ```bash
+   ls .planning/milestones/v[X.Y]-ROADMAP.md
+   ```
 
-9. Confirm archive complete:
+9. Confirm roadmap archive complete:
 
    ```
-   ✅ v[X.Y] archived to milestones/v[X.Y]-ROADMAP.md
+   ✅ v[X.Y] roadmap archived to milestones/v[X.Y]-ROADMAP.md
+   ✅ ROADMAP.md deleted (fresh one for next milestone)
    ```
 
+**Note:** Phase directories (`.planning/phases/`) are NOT deleted. They accumulate across milestones as the raw execution history. Phase numbering continues (v1.0 phases 1-4, v1.1 phases 5-8, etc.).
+
+</step>
+
+<step name="archive_requirements">
+
+Archive requirements and prepare for fresh requirements in next milestone.
+
+**Process:**
+
+1. read current REQUIREMENTS.md:
+   ```bash
+   cat .planning/REQUIREMENTS.md
+   ```
+
+2. Create archive file: `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
+
+3. Transform requirements for archive:
+   - Mark all v1 requirements as `[x]` complete
+   - Add outcome notes where relevant (validated, adjusted, dropped)
+   - Update traceability table status to "Complete" for all shipped requirements
+   - Add "Milestone Summary" section with:
+     - Total requirements shipped
+     - Any requirements that changed scope during milestone
+     - Any requirements dropped and why
+
+4. write archive file with header:
+   ```markdown
+   # Requirements Archive: v[X.Y] [Milestone Name]
+
+   **Archived:** [DATE]
+   **Status:** ✅ SHIPPED
+
+   This is the archived requirements specification for v[X.Y].
+   For current requirements, see `.planning/REQUIREMENTS.md` (created for next milestone).
+
+   ---
+
+   [Full REQUIREMENTS.md content with checkboxes marked complete]
+
+   ---
+
+   ## Milestone Summary
+
+   **Shipped:** [X] of [Y] v1 requirements
+   **Adjusted:** [list any requirements that changed during implementation]
+   **Dropped:** [list any requirements removed and why]
+
+   ---
+   *Archived: [DATE] as part of v[X.Y] milestone completion*
+   ```
+
+5. Delete original REQUIREMENTS.md:
+   ```bash
+   rm .planning/REQUIREMENTS.md
+   ```
+
+6. Confirm:
+   ```
+   ✅ Requirements archived to milestones/v[X.Y]-REQUIREMENTS.md
+   ✅ REQUIREMENTS.md deleted (fresh one needed for next milestone)
+   ```
+
+**Important:** The next milestone workflow starts with `/gsd-new-milestone` which includes requirements definition. PROJECT.md's Validated section carries the cumulative record across milestones.
+
+</step>
+
+<step name="archive_audit">
+
+Move the milestone audit file to the archive (if it exists):
+
+```bash
+# Move audit to milestones folder (if exists)
+[ -f .planning/v[X.Y]-MILESTONE-AUDIT.md ] && mv .planning/v[X.Y]-MILESTONE-AUDIT.md .planning/milestones/
+```
+
+Confirm:
+```
+✅ Audit archived to milestones/v[X.Y]-MILESTONE-AUDIT.md
+```
+
+(Skip silently if no audit file exists — audit is optional)
+
 </step>
 
 <step name="update_state">
@@ -527,26 +618,41 @@ git push origin v[X.Y]
 
 <step name="git_commit_milestone">
 
-Commit milestone completion including archive file.
+Commit milestone completion including archive files and deletions.
 
 ```bash
-# Stage all milestone-related files
+# Stage archive files (new)
+git add .planning/milestones/v[X.Y]-ROADMAP.md
+git add .planning/milestones/v[X.Y]-REQUIREMENTS.md
+git add .planning/milestones/v[X.Y]-MILESTONE-AUDIT.md 2>/dev/null || true
+
+# Stage updated files
 git add .planning/MILESTONES.md
 git add .planning/PROJECT.md
-git add .planning/ROADMAP.md
 git add .planning/STATE.md
-git add .planning/milestones/v[X.Y]-ROADMAP.md
+
+# Stage deletions
+git add -u .planning/
 
 # Commit with descriptive message
 git commit -m "$(cat <<'EOF'
 chore: complete v[X.Y] milestone
 
-- Added MILESTONES.md entry
-- Evolved PROJECT.md with validated requirements
-- Reorganized ROADMAP.md with milestone grouping
-- Created milestone archive: milestones/v[X.Y]-ROADMAP.md
-- Updated STATE.md
-- Tagged v[X.Y]
+Archived:
+- milestones/v[X.Y]-ROADMAP.md
+- milestones/v[X.Y]-REQUIREMENTS.md
+- milestones/v[X.Y]-MILESTONE-AUDIT.md (if audit was run)
+
+Deleted (fresh for next milestone):
+- ROADMAP.md
+- REQUIREMENTS.md
+
+Updated:
+- MILESTONES.md (new entry)
+- PROJECT.md (requirements → Validated)
+- STATE.md (reset for next milestone)
+
+Tagged: v[X.Y]
 EOF
 )"
 ```
@@ -564,6 +670,10 @@ Shipped:
 - [N] phases ([M] plans, [P] tasks)
 - [One sentence of what shipped]
 
+Archived:
+- milestones/v[X.Y]-ROADMAP.md
+- milestones/v[X.Y]-REQUIREMENTS.md
+
 Summary: .planning/MILESTONES.md
 Tag: v[X.Y]
 
@@ -571,17 +681,12 @@ Tag: v[X.Y]
 
 ## ▶ Next Up
 
-**Plan Next Milestone** — define v[X.Y+1] features and scope
+**Start Next Milestone** — questioning → research → requirements → roadmap
 
-`/gsd-discuss-milestone`
+`/gsd-new-milestone`
 
 *`/new` first → fresh context window*
 
----
-
-**Also available:**
-- `/gsd-new-milestone` — create directly if scope is clear
-
 ---
 ```
 
@@ -631,13 +736,15 @@ Milestone completion is successful when:
 
 - [ ] MILESTONES.md entry created with stats and accomplishments
 - [ ] PROJECT.md full evolution review completed
-- [ ] All shipped requirements moved to Validated
+- [ ] All shipped requirements moved to Validated in PROJECT.md
 - [ ] Key Decisions updated with outcomes
 - [ ] ROADMAP.md reorganized with milestone grouping
-- [ ] Milestone archive created
+- [ ] Roadmap archive created (milestones/v[X.Y]-ROADMAP.md)
+- [ ] Requirements archive created (milestones/v[X.Y]-REQUIREMENTS.md)
+- [ ] REQUIREMENTS.md deleted (fresh for next milestone)
 - [ ] STATE.md updated with fresh project reference
 - [ ] Git tag created (v[X.Y])
-- [ ] Milestone commit made
-- [ ] User knows next steps
+- [ ] Milestone commit made (includes archive files and deletion)
+- [ ] User knows next step (/gsd-new-milestone)
 
 </success_criteria>

package/get-shit-done/workflows/diagnose-issues.md

@@ -0,0 +1,233 @@
+<purpose>
+Orchestrate parallel debug agents to investigate UAT gaps and find root causes.
+
+After UAT finds gaps, spawn one debug agent per gap. Each agent investigates autonomously with symptoms pre-filled from UAT. Collect root causes, update UAT.md gaps with diagnosis, then hand off to plan-phase --gaps with actual diagnoses.
+
+Orchestrator stays lean: parse gaps, spawn agents, collect results, update UAT.
+</purpose>
+
+<paths>
+DEBUG_DIR=.planning/debug
+
+Debug files use the `.planning/debug/` path (hidden directory with leading dot).
+</paths>
+
+<core_principle>
+**Diagnose before planning fixes.**
+
+UAT tells us WHAT is broken (symptoms). Debug agents find WHY (root cause). plan-phase --gaps then creates targeted fixes based on actual causes, not guesses.
+
+Without diagnosis: "Comment doesn't refresh" → guess at fix → maybe wrong
+With diagnosis: "Comment doesn't refresh" → "useEffect missing dependency" → precise fix
+</core_principle>
+
+<process>
+
+<step name="parse_gaps">
+**Extract gaps from UAT.md:**
+
+read the "Gaps" section (YAML format):
+```yaml
+- truth: "Comment appears immediately after submission"
+  status: failed
+  reason: "User reported: works but doesn't show until I refresh the page"
+  severity: major
+  test: 2
+  artifacts: []
+  missing: []
+```
+
+For each gap, also read the corresponding test from "Tests" section to get full context.
+
+Build gap list:
+```
+gaps = [
+  {truth: "Comment appears immediately...", severity: "major", test_num: 2, reason: "..."},
+  {truth: "Reply button positioned correctly...", severity: "minor", test_num: 5, reason: "..."},
+  ...
+]
+```
+</step>
+
+<step name="report_plan">
+**Report diagnosis plan to user:**
+
+```
+## Diagnosing {N} Gaps
+
+Spawning parallel debug agents to investigate root causes:
+
+| Gap (Truth) | Severity |
+|-------------|----------|
+| Comment appears immediately after submission | major |
+| Reply button positioned correctly | minor |
+| Delete removes comment | blocker |
+
+Each agent will:
+1. Create DEBUG-{slug}.md with symptoms pre-filled
+2. Investigate autonomously (read code, form hypotheses, test)
+3. Return root cause
+
+This runs in parallel - all gaps investigated simultaneously.
+```
+</step>
+
+<step name="spawn_agents">
+**Spawn debug agents in parallel:**
+
+For each gap, fill the debug-subagent-prompt template and spawn:
+
+```
+Task(
+  prompt=filled_debug_subagent_prompt,
+  subagent_type="general",
+  description="Debug: {truth_short}"
+)
+```
+
+**All agents spawn in single message** (parallel execution).
+
+Template placeholders:
+- `{truth}`: The expected behavior that failed
+- `{expected}`: From UAT test
+- `{actual}`: Verbatim user description from reason field
+- `{errors}`: Any error messages from UAT (or "None reported")
+- `{reproduction}`: "Test {test_num} in UAT"
+- `{timeline}`: "Discovered during UAT"
+- `{goal}`: `find_root_cause_only` (UAT flow - plan-phase --gaps handles fixes)
+- `{slug}`: Generated from truth
+</step>
+
+<step name="collect_results">
+**Collect root causes from agents:**
+
+Each agent returns with:
+```
+## ROOT CAUSE FOUND
+
+**Debug Session:** ${DEBUG_DIR}/{slug}.md
+
+**Root Cause:** {specific cause with evidence}
+
+**Evidence Summary:**
+- {key finding 1}
+- {key finding 2}
+- {key finding 3}
+
+**Files Involved:**
+- {file1}: {what's wrong}
+- {file2}: {related issue}
+
+**Suggested Fix Direction:** {brief hint for plan-phase --gaps}
+```
+
+Parse each return to extract:
+- root_cause: The diagnosed cause
+- files: Files involved
+- debug_path: Path to debug session file
+- suggested_fix: Hint for gap closure plan
+
+If agent returns `## INVESTIGATION INCONCLUSIVE`:
+- root_cause: "Investigation inconclusive - manual review needed"
+- Note which issue needs manual attention
+- Include remaining possibilities from agent return
+</step>
+
+<step name="update_uat">
+**Update UAT.md gaps with diagnosis:**
+
+For each gap in the Gaps section, add artifacts and missing fields:
+
+```yaml
+- truth: "Comment appears immediately after submission"
+  status: failed
+  reason: "User reported: works but doesn't show until I refresh the page"
+  severity: major
+  test: 2
+  root_cause: "useEffect in CommentList.tsx missing commentCount dependency"
+  artifacts:
+    - path: "src/components/CommentList.tsx"
+      issue: "useEffect missing dependency"
+  missing:
+    - "Add commentCount to useEffect dependency array"
+    - "Trigger re-render when new comment added"
+  debug_session: .planning/debug/comment-not-refreshing.md
+```
+
+Update status in frontmatter to "diagnosed".
+
+Commit the updated UAT.md:
+```bash
+git add ".planning/phases/XX-name/{phase}-UAT.md"
+git commit -m "docs({phase}): add root causes from diagnosis"
+```
+</step>
+
+<step name="report_results">
+**Report diagnosis results and hand off:**
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► DIAGNOSIS COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+| Gap (Truth) | Root Cause | Files |
+|-------------|------------|-------|
+| Comment appears immediately | useEffect missing dependency | CommentList.tsx |
+| Reply button positioned correctly | CSS flex order incorrect | ReplyButton.tsx |
+| Delete removes comment | API missing auth header | api/comments.ts |
+
+Debug sessions: ${DEBUG_DIR}/
+
+Proceeding to plan fixes...
+```
+
+Return to verify-work orchestrator for automatic planning.
+Do NOT offer manual next steps - verify-work handles the rest.
+</step>
+
+</process>
+
+<context_efficiency>
+**Orchestrator context:** ~15%
+- Parse UAT.md gaps
+- Fill template strings
+- Spawn parallel Task calls
+- Collect results
+- Update UAT.md
+
+**Each debug agent:** Fresh 200k context
+- Loads full debug workflow
+- Loads debugging references
+- Investigates with full capacity
+- Returns root cause
+
+**No symptom gathering.** Agents start with symptoms pre-filled from UAT.
+**No fix application.** Agents only diagnose - plan-phase --gaps handles fixes.
+</context_efficiency>
+
+<failure_handling>
+**Agent fails to find root cause:**
+- Mark gap as "needs manual review"
+- Continue with other gaps
+- Report incomplete diagnosis
+
+**Agent times out:**
+- Check DEBUG-{slug}.md for partial progress
+- Can resume with /gsd-debug
+
+**All agents fail:**
+- Something systemic (permissions, git, etc.)
+- Report for manual investigation
+- Fall back to plan-phase --gaps without root causes (less precise)
+</failure_handling>
+
+<success_criteria>
+- [ ] Gaps parsed from UAT.md
+- [ ] Debug agents spawned in parallel
+- [ ] Root causes collected from all agents
+- [ ] UAT.md gaps updated with artifacts and missing
+- [ ] Debug sessions saved to ${DEBUG_DIR}/
+- [ ] Hand off to verify-work for automatic planning
+</success_criteria>

package/get-shit-done/workflows/discovery-phase.md

@@ -20,13 +20,13 @@ NOTE: For comprehensive ecosystem research ("how do experts build this"), use /g
 </depth_levels>
 
 <source_hierarchy>
-**MANDATORY: Context7 BEFORE WebSearch**
+**MANDATORY: Context7 BEFORE webfetch**
 
 OpenCode's training data is 6-18 months stale. Always verify.
 
 1. **Context7 MCP FIRST** - Current docs, no hallucination
 2. **Official docs** - When Context7 lacks coverage
-3. **WebSearch LAST** - For comparisons and trends only
+3. **webfetch LAST** - For comparisons and trends only
 
 See ~/.config/opencode/get-shit-done/templates/discovery.md `<discovery_protocol>` for full protocol.
 </source_hierarchy>
@@ -99,15 +99,15 @@ For: Choosing between options, new external integration.
 
 3. **Official docs** for anything Context7 lacks.
 
-4. **WebSearch** for comparisons:
+4. **webfetch** for comparisons:
 
    - "[option A] vs [option B] {current_year}"
    - "[option] known issues"
    - "[option] with [our stack]"
 
-5. **Cross-verify:** Any WebSearch finding → confirm with Context7/official docs.
+5. **Cross-verify:** Any webfetch finding → confirm with Context7/official docs.
 
-6. **Quality check:** Before finalizing findings, consult ~/.config/opencode/get-shit-done/references/research-pitfalls.md to avoid common research gaps.
+6. **Quality check:** Before finalizing findings, consult the gsd-researcher agent's verification protocols to avoid common research gaps.
 
 7. **Create DISCOVERY.md** using ~/.config/opencode/get-shit-done/templates/discovery.md structure:
 
@@ -147,7 +147,7 @@ For: Architectural decisions, novel problems, high-risk choices.
    - Migration/upgrade guides
    - Known limitations
 
-4. **WebSearch for ecosystem context:**
+4. **webfetch for ecosystem context:**
 
    - How others solved similar problems
    - Production experiences
@@ -156,11 +156,11 @@ For: Architectural decisions, novel problems, high-risk choices.
 
 5. **Cross-verify ALL findings:**
 
-   - Every WebSearch claim → verify with authoritative source
+   - Every webfetch claim → verify with authoritative source
    - Mark what's verified vs assumed
    - Flag contradictions
 
-6. **Quality check:** Before finalizing findings, consult ~/.config/opencode/get-shit-done/references/research-pitfalls.md to ensure comprehensive coverage and avoid common research gaps.
+6. **Quality check:** Before finalizing findings, consult the gsd-researcher agent's verification protocols to ensure comprehensive coverage and avoid common research gaps.
 
 7. **Create comprehensive DISCOVERY.md:**
 
@@ -207,7 +207,7 @@ Run the discovery:
 </step>
 
 <step name="create_discovery_output">
-Write `.planning/phases/XX-name/DISCOVERY.md`:
+write `.planning/phases/XX-name/DISCOVERY.md`:
 - Summary with recommendation
 - Key findings with sources
 - Code examples if applicable
@@ -276,15 +276,10 @@ NOTE: DISCOVERY.md is NOT committed separately. It will be committed with phase
 
 **Level 2 (Standard):**
 - Context7 consulted for all options
-- WebSearch findings cross-verified
-- DISCOVERY.md created with recommendation
-- Confidence level MEDIUM or higher
-- Ready to inform PLAN.md creation
+- webfetch findings cross-verified
 
-**Level 3 (Deep Dive):**
-- Discovery scope defined
-- Context7 exhaustively consulted
-- All WebSearch findings verified against authoritative sources
+7. Quality gate
+- All webfetch findings verified against authoritative sources
 - DISCOVERY.md created with comprehensive analysis
 - Quality report with source attribution
 - If LOW confidence findings → validation checkpoints defined