pi-gsd 2.0.21 → 2.0.23

package/.gsd/harnesses/pi/get-shit-done/workflows/add-phase.md

@@ -1,4 +1,4 @@
-<gsd-version v="1.12.4" />
+<gsd-version v="1.12.5" />
 
 <gsd-arguments>
   <settings>
@@ -47,121 +47,89 @@
   </if>
   <shell command="pi-gsd-tools">
     <args>
-      <arg string="state" />
-      <arg string="json" />
-      <arg string="--raw" />
+      <arg string="phase" />
+      <arg string="add-batch" />
+      <arg name="description" wrap='"' />
     </args>
     <outs>
-      <out type="string" name="state" />
+      <out type="string" name="batch-result" />
     </outs>
   </shell>
 </gsd-execute>
 
 ## Context (pre-injected by WXP)
 
-**Description:** <gsd-paste name="description" />
+**Init:**
+<gsd-paste name="init" />
 
-**Project State:**
-<gsd-paste name="state" />
+**Phases added:**
+<gsd-paste name="batch-result" />
 
 <process>
 
 <step name="parse_arguments">
-Parse the command arguments:
-- All arguments become the phase description
-- Example: `/gsd-add-phase Add authentication` → description = "Add authentication"
-- Example: `/gsd-add-phase Fix critical performance issues` → description = "Fix critical performance issues"
-
-If no arguments provided:
+If no description was provided (check `<gsd-paste name="description" />` is empty):
 
 ```
 ERROR: Phase description required
 Usage: /gsd-add-phase <description>
+       /gsd-add-phase <desc1> + <desc2> + ...
 Example: /gsd-add-phase Add authentication system
 ```
 
 Exit.
 </step>
 
-<step name="init_context">
-Load phase operation context:
+<step name="check_result">
+The `batch-result` JSON above was already executed by WXP before this message
+reached you. Parse it:
 
-<!-- Context pre-injected above via WXP - variables available via <gsd-paste name="..."> -->
+- If it contains an error field → report the error and exit.
+- Otherwise extract `phases[]` — each has `phase_number`, `padded`, `name`,
+  `slug`, `directory`.
 
-Check `roadmap_exists` from init JSON. If false:
-```
-ERROR: No roadmap found (.planning/ROADMAP.md)
-Run /gsd-new-project to initialize.
-```
-Exit.
-</step>
-
-<step name="add_phase">
-**Delegate the phase addition to gsd-tools:**
-
-```bash
-RESULT=$(pi-gsd-tools phase add "${description}")
-```
-
-The CLI handles:
-- Finding the highest existing integer phase number
-- Calculating next phase number (max + 1)
-- Generating slug from description
-- Creating the phase directory (`.planning/phases/{NN}-{slug}/`)
-- Inserting the phase entry into ROADMAP.md with Goal, Depends on, and Plans sections
-
-Extract from result: `phase_number`, `padded`, `name`, `slug`, `directory`.
-</step>
-
-<step name="update_project_state">
-Update STATE.md to reflect the new phase:
-
-1. Read `.planning/STATE.md`
-2. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
-   ```
-   - Phase {N} added: {description}
-   ```
-
-If "Roadmap Evolution" section doesn't exist, create it.
+Do NOT run `pi-gsd-tools phase add` again, do NOT inspect `.planning/phases/`
+or ROADMAP.md — everything is already done.
 </step>
 
 <step name="completion">
-Present completion summary:
+Present a completion summary:
 
 ```
-Phase {N} added to current milestone:
-- Description: {description}
-- Directory: .planning/phases/{phase-num}-{slug}/
-- Status: Not planned yet
+Added <count> phase(s):
+
+<for each phase in phases[]>
+• Phase <phase_number>: <name>
+  Directory: <directory>
+</for>
 
 Roadmap updated: .planning/ROADMAP.md
+State updated:   .planning/STATE.md
 
 ---
 
 ## ▶ Next Up
 
-**Phase {N}: {description}**
+**Phase <last phase_number>: <last name>**
 
-`/gsd-plan-phase {N}`
+`/gsd-plan-phase <last phase_number>`
 
 <sub>`/clear` first → fresh context window</sub>
 
 ---
 
 **Also available:**
-- `/gsd-add-phase <description>` - add another phase
-- Review roadmap
-
----
+- `/gsd-add-phase <description>` — add another phase
+- `/gsd-plan-phase <N>` — plan any of the new phases
 ```
 </step>
 
 </process>
 
 <success_criteria>
-- [ ] `gsd-tools phase add` executed successfully
-- [ ] Phase directory created
-- [ ] Roadmap updated with new phase entry
-- [ ] STATE.md updated with roadmap evolution note
-- [ ] User informed of next steps
+- [ ] `pi-gsd-tools phase add-batch` executed by WXP (not by the agent)
+- [ ] Phase directories created under `.planning/phases/`
+- [ ] ROADMAP.md updated with all new phase entries
+- [ ] STATE.md Roadmap Evolution updated (handled inside add-batch)
+- [ ] Agent presented the pre-injected result — no filesystem exploration
 </success_criteria>

package/.gsd/harnesses/pi/get-shit-done/workflows/audit-milestone.md

@@ -289,7 +289,7 @@ All requirements covered. Cross-phase integration verified. E2E flows complete.
 
 /gsd-complete-milestone {version}
 
-<sub>/clear first → fresh context window</sub>
+<sub>/new first → fresh context window</sub>
 
 ───────────────────────────────────────────────────────────────
 
@@ -334,7 +334,7 @@ Phases needing validation: run `/gsd-validate-phase {N}` for each flagged phase.
 
 /gsd-plan-milestone-gaps
 
-<sub>/clear first → fresh context window</sub>
+<sub>/new first → fresh context window</sub>
 
 ───────────────────────────────────────────────────────────────
 
@@ -376,7 +376,7 @@ All requirements met. No critical blockers. Accumulated tech debt needs review.
 
 /gsd-plan-milestone-gaps
 
-<sub>/clear first → fresh context window</sub>
+<sub>/new first → fresh context window</sub>
 
 ───────────────────────────────────────────────────────────────
 </offer_next>

package/.gsd/harnesses/pi/get-shit-done/workflows/complete-milestone.md

@@ -234,7 +234,7 @@ Tag: v[X.Y]
 
 `/gsd-new-milestone`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>`/new` first → fresh context window</sub>
 
 ---
 ```

package/.gsd/harnesses/pi/get-shit-done/workflows/debug.md

@@ -0,0 +1,250 @@
+<gsd-version v="1.12.4" />
+
+<gsd-arguments>
+  <settings>
+    <keep-extra-args />
+  </settings>
+  <arg name="description" type="string" optional />
+</gsd-arguments>
+
+<gsd-execute>
+  <display msg="Loading debug context..." />
+  <shell command="pi-gsd-tools">
+    <args>
+      <arg string="state" />
+      <arg string="json" />
+      <arg string="--raw" />
+    </args>
+    <outs>
+      <suppress-errors />
+      <out type="string" name="state" />
+    </outs>
+  </shell>
+  <shell command="pi-gsd-tools">
+    <args>
+      <arg string="current-timestamp" />
+      <arg string="--raw" />
+    </args>
+    <outs>
+      <out type="string" name="timestamp" />
+    </outs>
+  </shell>
+  <shell command="pi-gsd-tools">
+    <args>
+      <arg string="agent-skills" />
+      <arg string="gsd-debugger" />
+    </args>
+    <outs>
+      <suppress-errors />
+      <out type="string" name="agent-skills-debugger" />
+    </outs>
+  </shell>
+</gsd-execute>
+
+## Debug Context (pre-injected by WXP)
+
+**Problem:** <gsd-paste name="description" />
+
+**Timestamp:** <gsd-paste name="timestamp" />
+
+**Project State:**
+<gsd-paste name="state" />
+
+**Debugger Skills:**
+<gsd-paste name="agent-skills-debugger" />
+
+---
+
+<purpose>
+Systematic debugging session. Diagnoses failures, errors, and unexpected behavior using structured root-cause analysis. Spawns gsd-debugger with full project context for focused investigation.
+
+For post-mortem investigation of completed phases, use `/gsd-forensics` instead.
+</purpose>
+
+<available_agent_types>
+Valid GSD subagent types (use exact names - do not fall back to 'general-purpose'):
+- gsd-debugger - Diagnoses and fixes issues
+</available_agent_types>
+
+<process>
+
+<step name="gather_context">
+<!-- State, timestamp, and description pre-injected above via WXP -->
+
+Load current phase context:
+
+```bash
+PHASE_INFO=$(pi-gsd-tools roadmap analyze --raw 2>/dev/null || echo "{}")
+```
+
+Extract from state JSON:
+- `current_phase` - what's being worked on
+- `last_activity` - when was the last change
+- `milestone` - current milestone name
+
+If `description` is empty, ask the user:
+```
+What's broken? Describe the symptom in one sentence:
+(e.g. "auth tokens expire immediately", "build fails with missing module", "tests pass locally but fail in CI")
+```
+Store response as `description`.
+</step>
+
+<step name="classify_issue">
+Classify the issue from the description:
+
+| Symptom pattern | Issue type |
+|----------------|------------|
+| Error/exception message | `runtime_error` |
+| Test failures | `test_failure` |
+| Build/compile error | `build_error` |
+| Wrong behavior (no error) | `logic_error` |
+| Performance problem | `performance` |
+| Integration failure | `integration` |
+| Unclear | `unknown` |
+
+Set `ISSUE_TYPE`.
+</step>
+
+<step name="spawn_debugger">
+Display banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► DEBUG SESSION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Issue: {description}
+Type:  {ISSUE_TYPE}
+Phase: {current_phase || "not set"}
+
+◆ Spawning debugger...
+```
+
+Resolve model:
+```bash
+DEBUGGER_MODEL=$(pi-gsd-tools resolve-model gsd-debugger --raw 2>/dev/null || echo "")
+```
+
+Debug prompt:
+```markdown
+<objective>
+Debug the following issue in this project:
+{description}
+
+Issue type: {ISSUE_TYPE}
+Current phase: {current_phase}
+Milestone: {milestone}
+</objective>
+
+<files_to_read>
+- .planning/STATE.md (Project state and recent decisions)
+- .planning/ROADMAP.md (Phase context)
+- ./GEMINI.md or ./CLAUDE.md (Project-specific guidelines, if exists)
+</files_to_read>
+
+${AGENT_SKILLS_DEBUGGER}
+
+<investigation_protocol>
+1. Reproduce: Identify the minimal steps to trigger the issue
+2. Isolate: Narrow down to the failing component/file/function
+3. Root cause: Identify WHY it fails, not just WHERE
+4. Fix: Implement the smallest change that solves the root cause
+5. Verify: Confirm the fix works and doesn't introduce regressions
+
+Always check:
+- Recent commits (git log --oneline -10) for what changed
+- Related files for mismatched interfaces or broken contracts
+- Test suite for existing coverage that should have caught this
+</investigation_protocol>
+
+<output_format>
+## DEBUG COMPLETE
+
+**Root cause:** [one sentence]
+**Fix applied:** [what was changed]
+**Files modified:** [list]
+**Verification:** [how to confirm it's fixed]
+
+OR
+
+## DEBUG BLOCKED
+
+**Investigated:** [what was tried]
+**Blocker:** [what additional info is needed]
+**Next step:** [what the human should provide or check]
+</output_format>
+```
+
+```
+Task(
+  prompt=debug_prompt,
+  subagent_type="gsd-debugger",
+  model="{DEBUGGER_MODEL}",
+  description="Debug: {description}"
+)
+```
+</step>
+
+<step name="handle_return">
+**`## DEBUG COMPLETE`:**
+
+Display root cause, fix, and verification steps. Offer:
+```
+1. Capture as todo (/gsd-add-todo) - if fix not yet applied
+2. Continue with current phase (/gsd-execute-phase)
+3. Done
+```
+
+**`## DEBUG BLOCKED`:**
+
+Display blocker and next steps. Offer:
+```
+1. Provide additional context and retry
+2. Try forensics mode (/gsd-forensics) - deeper investigation
+3. Capture as todo and investigate later
+```
+</step>
+
+<step name="persist_session">
+If the debug session produced a fix or useful findings, offer to save:
+
+```bash
+mkdir -p .planning/debug
+```
+
+Write `.planning/debug/{YYYY-MM-DD}-{slug}.md`:
+```markdown
+---
+created: {timestamp}
+issue: {description}
+type: {ISSUE_TYPE}
+phase: {current_phase}
+status: {resolved|blocked}
+---
+
+## Root Cause
+{root cause summary}
+
+## Fix
+{what was changed}
+
+## Verification
+{how to confirm}
+```
+
+Commit:
+```bash
+pi-gsd-tools commit "docs: debug session - {description_slug}" --files .planning/debug/{filename}
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Problem description captured (from arg or prompt)
+- [ ] Issue classified by type
+- [ ] gsd-debugger spawned with full project context
+- [ ] Root cause identified or blocker surfaced
+- [ ] Fix applied or next steps clear
+- [ ] Session optionally persisted in .planning/debug/
+</success_criteria>

package/.gsd/harnesses/pi/get-shit-done/workflows/discuss-phase-assumptions.md

@@ -653,7 +653,7 @@ Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md
 
 `/gsd-plan-phase ${PHASE}`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>`/new` first → fresh context window</sub>
 
 ---
 

package/.gsd/harnesses/pi/get-shit-done/workflows/discuss-phase.md

@@ -913,7 +913,7 @@ Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md
 
 `/gsd-plan-phase ${PHASE} ${GSD_WS}`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>`/new` first → fresh context window</sub>
 
 ---
 
@@ -1045,7 +1045,7 @@ This keeps the auto-advance chain flat - discuss, plan, and execute all run at t
   Auto-advance pipeline finished: discuss → plan → execute
 
   Next: /gsd-discuss-phase ${NEXT_PHASE} --auto ${GSD_WS}
-  <sub>/clear first → fresh context window</sub>
+  <sub>/new first → fresh context window</sub>
   ```
 - **PLANNING COMPLETE** → Planning done, execution didn't complete:
   ```

package/.gsd/harnesses/pi/get-shit-done/workflows/discuss-phase.md.bak

@@ -875,7 +875,7 @@ Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md
 
 `/gsd-plan-phase ${PHASE} ${GSD_WS}`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>`/new` first → fresh context window</sub>
 
 ---
 
@@ -1007,7 +1007,7 @@ This keeps the auto-advance chain flat - discuss, plan, and execute all run at t
   Auto-advance pipeline finished: discuss → plan → execute
 
   Next: /gsd-discuss-phase ${NEXT_PHASE} --auto ${GSD_WS}
-  <sub>/clear first → fresh context window</sub>
+  <sub>/new first → fresh context window</sub>
   ```
 - **PLANNING COMPLETE** → Planning done, execution didn't complete:
   ```

package/.gsd/harnesses/pi/get-shit-done/workflows/execute-phase.md

@@ -8,6 +8,9 @@
     </delimiters>
   </settings>
   <arg name="auto-chain-active" type="flag" flag="--auto" optional />
+  <arg name="no-transition" type="flag" flag="--no-transition" optional />
+  <arg name="gaps-only" type="flag" flag="--gaps-only" optional />
+  <arg name="interactive" type="flag" flag="--interactive" optional />
   <arg name="phase" type="number" />
   <arg name="user-text" type="string" optional />
 </gsd-arguments>
@@ -748,7 +751,7 @@ Items saved to `{phase_num}-HUMAN-UAT.md` - they will appear in `/gsd-progress`
 
 `/gsd-plan-phase {X} --gaps ${GSD_WS}`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>`/new` first → fresh context window</sub>
 
 Also: `cat {phase_dir}/{phase_num}-VERIFICATION.md` - full report
 Also: `/gsd-verify-work {X} ${GSD_WS}` - manual testing first
@@ -886,7 +889,7 @@ Subagents: fresh context each (200k-1M depending on model). No polling (Task blo
 For 1M+ context models, consider:
 - Passing richer context (code snippets, dependency outputs) directly to executors instead of just file paths
 - Running small phases (≤3 plans, no dependencies) inline without subagent spawning overhead
-- Relaxing /clear recommendations - context rot onset is much further out with 5x window
+- Relaxing /new recommendations - context rot onset is much further out with 5x window
 </context_efficiency>
 
 <failure_handling>

package/.gsd/harnesses/pi/get-shit-done/workflows/execute-phase.md.bak

@@ -690,7 +690,7 @@ Items saved to `{phase_num}-HUMAN-UAT.md` - they will appear in `/gsd-progress`
 
 `/gsd-plan-phase {X} --gaps ${GSD_WS}`
 
-<sub>`/clear` first → fresh context window</sub>
+<sub>`/new` first → fresh context window</sub>
 
 Also: `cat {phase_dir}/{phase_num}-VERIFICATION.md` - full report
 Also: `/gsd-verify-work {X} ${GSD_WS}` - manual testing first
@@ -828,7 +828,7 @@ Subagents: fresh context each (200k-1M depending on model). No polling (Task blo
 For 1M+ context models, consider:
 - Passing richer context (code snippets, dependency outputs) directly to executors instead of just file paths
 - Running small phases (≤3 plans, no dependencies) inline without subagent spawning overhead
-- Relaxing /clear recommendations - context rot onset is much further out with 5x window
+- Relaxing /new recommendations - context rot onset is much further out with 5x window
 </context_efficiency>
 
 <failure_handling>

package/.gsd/harnesses/pi/get-shit-done/workflows/execute-plan.md

@@ -533,7 +533,7 @@ If `USER_SETUP_CREATED=true`: display `⚠️ USER SETUP REQUIRED` with path + e
 | summaries = plans, current < highest phase | **B: Phase done**     | Show completion, suggest `/gsd-plan-phase {Z+1}` + `/gsd-verify-work {Z}` + `/gsd-discuss-phase {Z+1}`                                                  |
 | summaries = plans, current = highest phase | **C: Milestone done** | Show banner, suggest `/gsd-complete-milestone` + `/gsd-verify-work` + `/gsd-add-phase`                                                                  |
 
-All routes: `/clear` first for fresh context.
+All routes: `/new` first for fresh context.
 </step>
 
 </process>

package/.gsd/harnesses/pi/get-shit-done/workflows/help.md

@@ -270,7 +270,7 @@ 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 `/gsd-debug` with no args to resume
+- Survives `/new` - run `/gsd-debug` with no args to resume
 - Archives resolved issues to `.planning/debug/resolved/`
 
 Usage: `/gsd-debug "login button doesn't work"`
@@ -553,9 +553,9 @@ Example config:
 
 ```
 /gsd-new-project        # Unified flow: questioning → research → requirements → roadmap
-/clear
+/new
 /gsd-plan-phase 1       # Create plans for first phase
-/clear
+/new
 /gsd-execute-phase 1    # Execute all plans in phase
 ```
 
@@ -577,7 +577,7 @@ Example config:
 
 ```
 /gsd-complete-milestone 1.0.0
-/clear
+/new
 /gsd-new-milestone  # Start next milestone (questioning → research → requirements → roadmap)
 ```
 
@@ -595,7 +595,7 @@ Example config:
 ```
 /gsd-debug "form submission fails silently"  # Start debug session
 # ... investigation happens, context fills up ...
-/clear
+/new
 /gsd-debug                                    # Resume from where you left off
 ```
 

package/.gsd/harnesses/pi/get-shit-done/workflows/insert-phase.md

@@ -153,7 +153,7 @@ Project state updated: .planning/STATE.md
 
 `/gsd-plan-phase {decimal_phase}`
 
-<sub>`/clear` first -> fresh context window</sub>
+<sub>`/new` first -> fresh context window</sub>
 
 ---