gsd-opencode 1.10.2 → 1.20.1

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

@@ -1,149 +1,64 @@
 <purpose>
-Execute all plans in a phase using wave-based parallel execution. Orchestrator stays lean by delegating plan execution to subagents.
+Execute all plans in a phase using wave-based parallel execution. Orchestrator stays lean — delegates plan execution to subagents.
 </purpose>
 
 <core_principle>
-The orchestrator's job is coordination, not execution. Each subagent loads the full execute-plan context itself. Orchestrator discovers plans, analyzes dependencies, groups into waves, spawns agents, handles checkpoints, collects results.
+Orchestrator coordinates, not executes. Each subagent loads the full execute-plan context. Orchestrator: discover plans → analyze deps → group waves → spawn agents → handle checkpoints → collect results.
 </core_principle>
 
 <required_reading>
 read STATE.md before any operation to load project context.
-read config.json for planning behavior settings.
 </required_reading>
 
 <process>
 
-<step name="resolve_model_profile" priority="first">
-read model profile for agent spawning:
+<step name="initialize" priority="first">
+Load all context in one call:
 
 ```bash
-MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+INIT=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs init execute-phase "${PHASE_ARG}")
 ```
 
-Default to "balanced" if not set.
+Parse JSON for: `executor_model`, `verifier_model`, `commit_docs`, `parallelization`, `branching_strategy`, `branch_name`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `state_exists`, `roadmap_exists`.
 
-**Model lookup table:**
+**If `phase_found` is false:** Error — phase directory not found.
+**If `plan_count` is 0:** Error — no plans found in phase.
+**If `state_exists` is false but `.planning/` exists:** Offer reconstruct or continue.
 
-| Agent | quality | balanced | budget |
-|-------|---------|----------|--------|
-| gsd-executor | opus | sonnet | sonnet |
-| gsd-verifier | sonnet | sonnet | haiku |
-| general | — | — | — |
-
-Store resolved models for use in Task calls below.
+When `parallelization` is false, plans within a wave execute sequentially.
 </step>
 
-<step name="load_project_state">
-Before any operation, read project state:
-
-```bash
-cat .planning/STATE.md 2>/dev/null
-```
-
-**If file exists:** Parse and internalize:
-- Current position (phase, plan, status)
-- Accumulated decisions (constraints on this execution)
-- Blockers/concerns (things to watch for)
-
-**If file missing but .planning/ exists:**
-```
-STATE.md missing but planning artifacts exist.
-Options:
-1. Reconstruct from existing artifacts
-2. Continue without project state (may lose accumulated context)
-```
-
-**If .planning/ doesn't exist:** Error - project not initialized.
+<step name="handle_branching">
+Check `branching_strategy` from init:
 
-**Load planning config:**
+**"none":** Skip, continue on current branch.
 
+**"phase" or "milestone":** Use pre-computed `branch_name` from init:
 ```bash
-# Check if planning docs should be committed (default: true)
-COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
-# Auto-detect gitignored (overrides config)
-git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
+git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
 ```
 
-Store `COMMIT_PLANNING_DOCS` for use in git operations.
+All subsequent commits go to this branch. User handles merging.
 </step>
 
 <step name="validate_phase">
-Confirm phase exists and has plans:
-
-```bash
-# Match both zero-padded (05-*) and unpadded (5-*) folders
-PADDED_PHASE=$(printf "%02d" ${PHASE_ARG} 2>/dev/null || echo "${PHASE_ARG}")
-PHASE_DIR=$(ls -d .planning/phases/${PADDED_PHASE}-* .planning/phases/${PHASE_ARG}-* 2>/dev/null | head -1)
-if [ -z "$PHASE_DIR" ]; then
-  echo "ERROR: No phase directory matching '${PHASE_ARG}'"
-  exit 1
-fi
-
-PLAN_COUNT=$(ls -1 "$PHASE_DIR"/*-PLAN.md 2>/dev/null | wc -l | tr -d ' ')
-if [ "$PLAN_COUNT" -eq 0 ]; then
-  echo "ERROR: No plans found in $PHASE_DIR"
-  exit 1
-fi
-```
-
-Report: "Found {N} plans in {phase_dir}"
-</step>
-
-<step name="discover_plans">
-List all plans and extract metadata:
-
-```bash
-# Get all plans
-ls -1 "$PHASE_DIR"/*-PLAN.md 2>/dev/null | sort
-
-# Get completed plans (have SUMMARY.md)
-ls -1 "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null | sort
-```
-
-For each plan, read frontmatter to extract:
-- `wave: N` - Execution wave (pre-computed)
-- `autonomous: true/false` - Whether plan has checkpoints
-- `gap_closure: true/false` - Whether plan closes gaps from verification/UAT
-
-Build plan inventory:
-- Plan path
-- Plan ID (e.g., "03-01")
-- Wave number
-- Autonomous flag
-- Gap closure flag
-- Completion status (SUMMARY exists = complete)
+From init JSON: `phase_dir`, `plan_count`, `incomplete_count`.
 
-**Filtering:**
-- Skip completed plans (have SUMMARY.md)
-- If `--gaps-only` flag: also skip plans where `gap_closure` is not `true`
-
-If all plans filtered out, report "No matching incomplete plans" and exit.
+Report: "Found {plan_count} plans in {phase_dir} ({incomplete_count} incomplete)"
 </step>
 
-<step name="group_by_wave">
-read `wave` from each plan's frontmatter and group by wave number:
+<step name="discover_and_group_plans">
+Load plan inventory with wave grouping in one call:
 
 ```bash
-# For each plan, extract wave from frontmatter
-for plan in $PHASE_DIR/*-PLAN.md; do
-  wave=$(grep "^wave:" "$plan" | cut -d: -f2 | tr -d ' ')
-  autonomous=$(grep "^autonomous:" "$plan" | cut -d: -f2 | tr -d ' ')
-  echo "$plan:$wave:$autonomous"
-done
+PLAN_INDEX=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs phase-plan-index "${PHASE_NUMBER}")
 ```
 
-**Group plans:**
-```
-waves = {
-  1: [plan-01, plan-02],
-  2: [plan-03, plan-04],
-  3: [plan-05]
-}
-```
+Parse JSON for: `phase`, `plans[]` (each with `id`, `wave`, `autonomous`, `objective`, `files_modified`, `task_count`, `has_summary`), `waves` (map of wave number → plan IDs), `incomplete`, `has_checkpoints`.
 
-**No dependency analysis needed.** Wave numbers are pre-computed during `/gsd-plan-phase`.
+**Filtering:** Skip plans where `has_summary: true`. If `--gaps-only`: also skip non-gap_closure plans. If all filtered: "No matching incomplete plans" → exit.
 
-Report wave structure with context:
+Report:
 ```
 ## Execution Plan
 
@@ -151,461 +66,388 @@ Report wave structure with context:
 
 | Wave | Plans | What it builds |
 |------|-------|----------------|
-| 1 | 01-01, 01-02 | {from plan objectives} |
-| 2 | 01-03 | {from plan objectives} |
-| 3 | 01-04 [checkpoint] | {from plan objectives} |
-
+| 1 | 01-01, 01-02 | {from plan objectives, 3-8 words} |
+| 2 | 01-03 | ... |
 ```
-
-The "What it builds" column comes from skimming plan names/objectives. Keep it brief (3-8 words).
 </step>
 
 <step name="execute_waves">
-Execute each wave in sequence. Autonomous plans within a wave run in parallel.
+Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`, sequential if `false`.
 
 **For each wave:**
 
 1. **Describe what's being built (BEFORE spawning):**
 
-   read each plan's `<objective>` section. Extract what's being built and why it matters.
+   read each plan's `<objective>`. Extract what's being built and why.
 
-   **Output:**
    ```
    ---
-
    ## Wave {N}
 
    **{Plan ID}: {Plan Name}**
-   {2-3 sentences: what this builds, key technical approach, why it matters in context}
-
-   **{Plan ID}: {Plan Name}** (if parallel)
-   {same format}
+   {2-3 sentences: what this builds, technical approach, why it matters}
 
    Spawning {count} agent(s)...
-
    ---
    ```
 
-   **Examples:**
    - Bad: "Executing terrain generation plan"
    - Good: "Procedural terrain generator using Perlin noise — creates height maps, biome zones, and collision meshes. Required before vehicle physics can interact with ground."
 
-2. **read files and spawn all autonomous agents in wave simultaneously:**
+2. **Spawn executor agents:**
 
-   Before spawning, read file contents. The `@` syntax does not work across Task() boundaries - content must be inlined.
-
-   ```bash
-   # read each plan in the wave
-   PLAN_CONTENT=$(cat "{plan_path}")
-   STATE_CONTENT=$(cat .planning/STATE.md)
-   CONFIG_CONTENT=$(cat .planning/config.json 2>/dev/null)
-   ```
-
-   Use Task tool with multiple parallel calls. Each agent gets prompt with inlined content:
+   Pass paths only — executors read files themselves with their fresh 200k context.
+   This keeps orchestrator context lean (~10-15%).
 
    ```
-   <objective>
-   Execute plan {plan_number} of phase {phase_number}-{phase_name}.
-
-   Commit each task atomically. Create SUMMARY.md. Update STATE.md.
-   </objective>
-
-   <execution_context>
-   @~/.config/opencode/get-shit-done/workflows/execute-plan.md
-   @~/.config/opencode/get-shit-done/templates/summary.md
-   @~/.config/opencode/get-shit-done/references/checkpoints.md
-   @~/.config/opencode/get-shit-done/references/tdd.md
-   </execution_context>
-
-   <context>
-   Plan:
-   {plan_content}
-
-   Project state:
-   {state_content}
-
-   Config (if exists):
-   {config_content}
-   </context>
-
-   <success_criteria>
-   - [ ] All tasks executed
-   - [ ] Each task committed individually
-   - [ ] SUMMARY.md created in plan directory
-   - [ ] STATE.md updated with position and decisions
-   </success_criteria>
+   task(
+     subagent_type="gsd-executor",
+     model="{executor_model}",
+     prompt="
+       <objective>
+       Execute plan {plan_number} of phase {phase_number}-{phase_name}.
+       Commit each task atomically. Create SUMMARY.md. Update STATE.md and ROADMAP.md.
+       </objective>
+
+       <execution_context>
+       @~/.config/opencode/get-shit-done/workflows/execute-plan.md
+       @~/.config/opencode/get-shit-done/templates/summary.md
+       @~/.config/opencode/get-shit-done/references/checkpoints.md
+       @~/.config/opencode/get-shit-done/references/tdd.md
+       </execution_context>
+
+       <files_to_read>
+       read these files at execution start using the read tool:
+       - {phase_dir}/{plan_file} (Plan)
+       - .planning/STATE.md (State)
+       - .planning/config.json (Config, if exists)
+       - ./AGENTS.md (Project instructions, if exists — follow project-specific guidelines and coding conventions)
+       - .agents/skills/ (Project skills, if exists — list skills, read SKILL.md for each, follow relevant rules during implementation)
+       </files_to_read>
+
+       <success_criteria>
+       - [ ] All tasks executed
+       - [ ] Each task committed individually
+       - [ ] SUMMARY.md created in plan directory
+       - [ ] STATE.md updated with position and decisions
+       - [ ] ROADMAP.md updated with plan progress (via `roadmap update-plan-progress`)
+       </success_criteria>
+     "
+   )
    ```
 
-2. **Wait for all agents in wave to complete:**
+3. **Wait for all agents in wave to complete.**
 
-   Task tool blocks until each agent finishes. All parallel agents return together.
+4. **Report completion — spot-check claims first:**
 
-3. **Report completion and what was built:**
+   For each SUMMARY.md:
+   - Verify first 2 files from `key-files.created` exist on disk
+   - Check `git log --oneline --all --grep="{phase}-{plan}"` returns ≥1 commit
+   - Check for `## Self-Check: FAILED` marker
 
-   For each completed agent:
-   - Verify SUMMARY.md exists at expected path
-   - read SUMMARY.md to extract what was built
-   - Note any issues or deviations
+   If ANY spot-check fails: report which plan failed, route to failure handler — ask "Retry plan?" or "Continue with remaining waves?"
 
-   **Output:**
+   If pass:
    ```
    ---
-
    ## Wave {N} Complete
 
    **{Plan ID}: {Plan Name}**
-   {What was built — from SUMMARY.md deliverables}
-   {Notable deviations or discoveries, if any}
-
-   **{Plan ID}: {Plan Name}** (if parallel)
-   {same format}
-
-   {If more waves: brief note on what this enables for next wave}
+   {What was built — from SUMMARY.md}
+   {Notable deviations, if any}
 
+   {If more waves: what this enables for next wave}
    ---
    ```
 
-   **Examples:**
    - Bad: "Wave 2 complete. Proceeding to Wave 3."
    - Good: "Terrain system complete — 3 biome types, height-based texturing, physics collision meshes. Vehicle physics (Wave 3) can now reference ground surfaces."
 
-4. **Handle failures:**
-
-   If any agent in wave fails:
-   - Report which plan failed and why
-   - Ask user: "Continue with remaining waves?" or "Stop execution?"
-   - If continue: proceed to next wave (dependent plans may also fail)
-   - If stop: exit with partial completion report
+5. **Handle failures:**
 
-5. **Execute checkpoint plans between waves:**
+   **Known OpenCode bug (classifyHandoffIfNeeded):** If an agent reports "failed" with error containing `classifyHandoffIfNeeded is not defined`, this is a OpenCode runtime bug — not a GSD or agent issue. The error fires in the completion handler AFTER all tool calls finish. In this case: run the same spot-checks as step 4 (SUMMARY.md exists, git commits present, no Self-Check: FAILED). If spot-checks PASS → treat as **successful**. If spot-checks FAIL → treat as real failure below.
 
-   See `<checkpoint_handling>` for details.
+   For real failures: report which plan failed → ask "Continue?" or "Stop?" → if continue, dependent plans may also fail. If stop, partial completion report.
 
-6. **Proceed to next wave**
+6. **Execute checkpoint plans between waves** — see `<checkpoint_handling>`.
 
+7. **Proceed to next wave.**
 </step>
 
 <step name="checkpoint_handling">
 Plans with `autonomous: false` require user interaction.
 
-**Detection:** Check `autonomous` field in frontmatter.
-
-**Execution flow for checkpoint plans:**
-
-1. **Spawn agent for checkpoint plan:**
-   ```
-   Task(prompt="{subagent-task-prompt}", subagent_type="gsd-executor", model="{executor_model}")
-   ```
+**Auto-mode checkpoint handling:**
 
-2. **Agent runs until checkpoint:**
-   - Executes auto tasks normally
-   - Reaches checkpoint task (e.g., `type="checkpoint:human-verify"`) or auth gate
-   - Agent returns with structured checkpoint (see checkpoint-return.md template)
+read auto-advance config:
+```bash
+AUTO_CFG=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs config-get workflow.auto_advance 2>/dev/null || echo "false")
+```
 
-3. **Agent return includes (structured format):**
-   - Completed Tasks table with commit hashes and files
-   - Current task name and blocker
-   - Checkpoint type and details for user
-   - What's awaited from user
+When executor returns a checkpoint AND `AUTO_CFG` is `"true"`:
+- **human-verify** → Auto-spawn continuation agent with `{user_response}` = `"approved"`. Log `⚡ Auto-approved checkpoint`.
+- **decision** → Auto-spawn continuation agent with `{user_response}` = first option from checkpoint details. Log `⚡ Auto-selected: [option]`.
+- **human-action** → Present to user (existing behavior below). Auth gates cannot be automated.
 
-4. **Orchestrator presents checkpoint to user:**
+**Standard flow (not auto-mode, or human-action type):**
 
-   Extract and display the "Checkpoint Details" and "Awaiting" sections from agent return:
+1. Spawn agent for checkpoint plan
+2. Agent runs until checkpoint task or auth gate → returns structured state
+3. Agent return includes: completed tasks table, current task + blocker, checkpoint type/details, what's awaited
+4. **Present to user:**
    ```
    ## Checkpoint: [Type]
 
    **Plan:** 03-03 Dashboard Layout
    **Progress:** 2/3 tasks complete
 
-   [Checkpoint Details section from agent return]
-
+   [Checkpoint Details from agent return]
    [Awaiting section from agent return]
    ```
+5. User responds: "approved"/"done" | issue description | decision selection
+6. **Spawn continuation agent (NOT resume)** using continuation-prompt.md template:
+   - `{completed_tasks_table}`: From checkpoint return
+   - `{resume_task_number}` + `{resume_task_name}`: Current task
+   - `{user_response}`: What user provided
+   - `{resume_instructions}`: Based on checkpoint type
+7. Continuation agent verifies previous commits, continues from resume point
+8. Repeat until plan completes or user stops
 
-5. **User responds:**
-   - "approved" / "done" → spawn continuation agent
-   - Description of issues → spawn continuation agent with feedback
-   - Decision selection → spawn continuation agent with choice
-
-6. **Spawn continuation agent (NOT resume):**
-
-   Use the continuation-prompt.md template:
-   ```
-   Task(
-     prompt=filled_continuation_template,
-     subagent_type="gsd-executor",
-     model="{executor_model}"
-   )
-   ```
+**Why fresh agent, not resume:** Resume relies on internal serialization that breaks with parallel tool calls. Fresh agents with explicit state are more reliable.
 
-   Fill template with:
-   - `{completed_tasks_table}`: From agent's checkpoint return
-   - `{resume_task_number}`: Current task from checkpoint
-   - `{resume_task_name}`: Current task name from checkpoint
-   - `{user_response}`: What user provided
-   - `{resume_instructions}`: Based on checkpoint type (see continuation-prompt.md)
-
-7. **Continuation agent executes:**
-   - Verifies previous commits exist
-   - Continues from resume point
-   - May hit another checkpoint (repeat from step 4)
-   - Or completes plan
-
-8. **Repeat until plan completes or user stops**
-
-**Why fresh agent instead of resume:**
-Resume relies on OpenCode's internal serialization which breaks with parallel tool calls.
-Fresh agents with explicit state are more reliable and maintain full context.
-
-**Checkpoint in parallel context:**
-If a plan in a parallel wave has a checkpoint:
-- Spawn as normal
-- Agent pauses at checkpoint and returns with structured state
-- Other parallel agents may complete while waiting
-- Present checkpoint to user
-- Spawn continuation agent with user response
-- Wait for all agents to finish before next wave
+**Checkpoints in parallel waves:** Agent pauses and returns while other parallel agents may complete. Present checkpoint, spawn continuation, wait for all before next wave.
 </step>
 
 <step name="aggregate_results">
-After all waves complete, aggregate results:
+After all waves:
 
 ```markdown
 ## Phase {X}: {Name} Execution Complete
 
-**Waves executed:** {N}
-**Plans completed:** {M} of {total}
-
-### Wave Summary
+**Waves:** {N} | **Plans:** {M}/{total} complete
 
 | Wave | Plans | Status |
 |------|-------|--------|
 | 1 | plan-01, plan-02 | ✓ Complete |
 | CP | plan-03 | ✓ Verified |
 | 2 | plan-04 | ✓ Complete |
-| 3 | plan-05 | ✓ Complete |
 
 ### Plan Details
-
 1. **03-01**: [one-liner from SUMMARY.md]
 2. **03-02**: [one-liner from SUMMARY.md]
-...
 
 ### Issues Encountered
-[Aggregate from all SUMMARYs, or "None"]
+[Aggregate from SUMMARYs, or "None"]
+```
+</step>
+
+<step name="close_parent_artifacts">
+**For decimal/polish phases only (X.Y pattern):** Close the feedback loop by resolving parent UAT and debug artifacts.
+
+**Skip if** phase number has no decimal (e.g., `3`, `04`) — only applies to gap-closure phases like `4.1`, `03.1`.
+
+**1. Detect decimal phase and derive parent:**
+```bash
+# Check if phase_number contains a decimal
+if [[ "$PHASE_NUMBER" == *.* ]]; then
+  PARENT_PHASE="${PHASE_NUMBER%%.*}"
+fi
+```
+
+**2. Find parent UAT file:**
+```bash
+PARENT_INFO=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs find-phase "${PARENT_PHASE}" --raw)
+# Extract directory from PARENT_INFO JSON, then find UAT file in that directory
+```
+
+**If no parent UAT found:** Skip this step (gap-closure may have been triggered by VERIFICATION.md instead).
+
+**3. Update UAT gap statuses:**
+
+read the parent UAT file's `## Gaps` section. For each gap entry with `status: failed`:
+- Update to `status: resolved`
+
+**4. Update UAT frontmatter:**
+
+If all gaps now have `status: resolved`:
+- Update frontmatter `status: diagnosed` → `status: resolved`
+- Update frontmatter `updated:` timestamp
+
+**5. Resolve referenced debug sessions:**
+
+For each gap that has a `debug_session:` field:
+- read the debug session file
+- Update frontmatter `status:` → `resolved`
+- Update frontmatter `updated:` timestamp
+- Move to resolved directory:
+```bash
+mkdir -p .planning/debug/resolved
+mv .planning/debug/{slug}.md .planning/debug/resolved/
+```
+
+**6. Commit updated artifacts:**
+```bash
+node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "docs(phase-${PARENT_PHASE}): resolve UAT gaps and debug sessions after ${PHASE_NUMBER} gap closure" --files .planning/phases/*${PARENT_PHASE}*/*-UAT.md .planning/debug/resolved/*.md
 ```
 </step>
 
 <step name="verify_phase_goal">
-Verify phase achieved its GOAL, not just completed its TASKS.
+Verify phase achieved its GOAL, not just completed tasks.
 
-**Spawn verifier:**
+```bash
+PHASE_REQ_IDS=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs roadmap get-phase "${PHASE_NUMBER}" | jq -r '.section' | grep -i "Requirements:" | sed 's/.*Requirements:\*\*\s*//' | sed 's/[\[\]]//g')
+```
 
 ```
-Task(
+task(
   prompt="Verify phase {phase_number} goal achievement.
-
 Phase directory: {phase_dir}
 Phase goal: {goal from ROADMAP.md}
-
-Check must_haves against actual codebase. Create VERIFICATION.md.
-Verify what actually exists in the code.",
+Phase requirement IDs: {phase_req_ids}
+Check must_haves against actual codebase.
+Cross-reference requirement IDs from PLAN frontmatter against REQUIREMENTS.md — every ID MUST be accounted for.
+Create VERIFICATION.md.",
   subagent_type="gsd-verifier",
   model="{verifier_model}"
 )
 ```
 
-**read verification status:**
-
+read status:
 ```bash
 grep "^status:" "$PHASE_DIR"/*-VERIFICATION.md | cut -d: -f2 | tr -d ' '
 ```
 
-**Route by status:**
-
 | Status | Action |
 |--------|--------|
-| `passed` | Continue to update_roadmap |
-| `human_needed` | Present items to user, get approval or feedback |
+| `passed` | → update_roadmap |
+| `human_needed` | Present items for human testing, get approval or feedback |
 | `gaps_found` | Present gap summary, offer `/gsd-plan-phase {phase} --gaps` |
 
-**If passed:**
-
-Phase goal verified. Proceed to update_roadmap.
-
 **If human_needed:**
-
-```markdown
+```
 ## ✓ Phase {X}: {Name} — Human Verification Required
 
 All automated checks passed. {N} items need human testing:
 
-### Human Verification Checklist
-
-{Extract from VERIFICATION.md human_verification section}
-
----
+{From VERIFICATION.md human_verification section}
 
-**After testing:**
-- "approved" → continue to update_roadmap
-- Report issues → will route to gap closure planning
+"approved" → continue | Report issues → gap closure
 ```
 
-If user approves → continue to update_roadmap.
-If user reports issues → treat as gaps_found.
-
 **If gaps_found:**
-
-Present gaps and offer next command:
-
-```markdown
+```
 ## ⚠ Phase {X}: {Name} — Gaps Found
 
 **Score:** {N}/{M} must-haves verified
-**Report:** {phase_dir}/{phase}-VERIFICATION.md
+**Report:** {phase_dir}/{phase_num}-VERIFICATION.md
 
 ### What's Missing
-
-{Extract gap summaries from VERIFICATION.md gaps section}
+{Gap summaries from VERIFICATION.md}
 
 ---
-
 ## ▶ Next Up
 
-**Plan gap closure** — create additional plans to complete the phase
-
 `/gsd-plan-phase {X} --gaps`
 
 *`/new` first → fresh context window*
 
----
-
-**Also available:**
-- `cat {phase_dir}/{phase}-VERIFICATION.md` — see full report
-- `/gsd-verify-work {X}` — manual testing before planning
+Also: `cat {phase_dir}/{phase_num}-VERIFICATION.md` — full report
+Also: `/gsd-verify-work {X}` — manual testing first
 ```
 
-User runs `/gsd-plan-phase {X} --gaps` which:
-1. Reads VERIFICATION.md gaps
-2. Creates additional plans (04, 05, etc.) with `gap_closure: true` to close gaps
-3. User then runs `/gsd-execute-phase {X} --gaps-only`
-4. Execute-phase runs only gap closure plans (04-05)
-5. Verifier runs again after new plans complete
-
-User stays in control at each decision point.
+Gap closure cycle: `/gsd-plan-phase {X} --gaps` reads VERIFICATION.md → creates gap plans with `gap_closure: true` → user runs `/gsd-execute-phase {X} --gaps-only` → verifier re-runs.
 </step>
 
 <step name="update_roadmap">
-Update ROADMAP.md to reflect phase completion:
+**Mark phase complete and update all tracking files:**
 
 ```bash
-# Mark phase complete
-# Update completion date
-# Update status
+COMPLETION=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs phase complete "${PHASE_NUMBER}")
 ```
 
-**Check planning config:**
-
-If `COMMIT_PLANNING_DOCS=false` (set in load_project_state):
-- Skip all git operations for .planning/ files
-- Planning docs exist locally but are gitignored
-- Log: "Skipping planning docs commit (commit_docs: false)"
-- Proceed to offer_next step
+The CLI handles:
+- Marking phase checkbox `[x]` with completion date
+- Updating Progress table (Status → Complete, date)
+- Updating plan count to final
+- Advancing STATE.md to next phase
+- Updating REQUIREMENTS.md traceability
 
-If `COMMIT_PLANNING_DOCS=true` (default):
-- Continue with git operations below
+Extract from result: `next_phase`, `next_phase_name`, `is_last_phase`.
 
-Commit phase completion (roadmap, state, verification):
 ```bash
-git add .planning/ROADMAP.md .planning/STATE.md .planning/phases/{phase_dir}/*-VERIFICATION.md
-git add .planning/REQUIREMENTS.md  # if updated
-git commit -m "docs(phase-{X}): complete phase execution"
+node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "docs(phase-{X}): complete phase execution" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md {phase_dir}/*-VERIFICATION.md
 ```
 </step>
 
 <step name="offer_next">
-Present next steps based on milestone status:
 
-**If more phases remain:**
-```
-## Next Up
+**Exception:** If `gaps_found`, the `verify_phase_goal` step already presents the gap-closure path (`/gsd-plan-phase {X} --gaps`). No additional routing needed — skip auto-advance.
+
+**No-transition check (spawned by auto-advance chain):**
 
-**Phase {X+1}: {Name}** — {Goal}
+Parse `--no-transition` flag from $ARGUMENTS.
 
-`/gsd-plan-phase {X+1}`
+**If `--no-transition` flag present:**
+
+Execute-phase was spawned by plan-phase's auto-advance. Do NOT run transition.md.
+After verification passes and roadmap is updated, return completion status to parent:
 
-*`/new` first for fresh context*
 ```
+## PHASE COMPLETE
+
+Phase: ${PHASE_NUMBER} - ${PHASE_NAME}
+Plans: ${completed_count}/${total_count}
+Verification: {Passed | Gaps Found}
 
-**If milestone complete:**
+[Include aggregate_results output]
 ```
-MILESTONE COMPLETE!
 
-All {N} phases executed.
+STOP. Do not proceed to auto-advance or transition.
+
+**If `--no-transition` flag is NOT present:**
+
+**Auto-advance detection:**
+
+1. Parse `--auto` flag from $ARGUMENTS
+2. read `workflow.auto_advance` from config:
+   ```bash
+   AUTO_CFG=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs config-get workflow.auto_advance 2>/dev/null || echo "false")
+   ```
+
+**If `--auto` flag present OR `AUTO_CFG` is true (AND verification passed with no gaps):**
 
-`/gsd-complete-milestone`
 ```
-</step>
+╔══════════════════════════════════════════╗
+║  AUTO-ADVANCING → TRANSITION             ║
+║  Phase {X} verified, continuing chain    ║
+╚══════════════════════════════════════════╝
+```
 
-</process>
+Execute the transition workflow inline (do NOT use task — orchestrator context is ~10-15%, transition needs phase completion data already in context):
 
-<context_efficiency>
-**Why this works:**
+read and follow `~/.config/opencode/get-shit-done/workflows/transition.md`, passing through the `--auto` flag so it propagates to the next phase invocation.
 
-Orchestrator context usage: ~10-15%
-- read plan frontmatter (small)
-- Analyze dependencies (logic, no heavy reads)
-- Fill template strings
-- Spawn Task calls
-- Collect results
+**If neither `--auto` nor `AUTO_CFG` is true:**
 
-Each subagent: Fresh 200k context
-- Loads full execute-plan workflow
-- Loads templates, references
-- Executes plan with full capacity
-- Creates SUMMARY, commits
+The workflow ends. The user runs `/gsd-progress` or invokes the transition workflow manually.
+</step>
 
-**No polling.** Task tool blocks until completion. No TaskOutput loops.
+</process>
 
-**No context bleed.** Orchestrator never reads workflow internals. Just paths and results.
+<context_efficiency>
+Orchestrator: ~10-15% context. Subagents: fresh 200k each. No polling (task blocks). No context bleed.
 </context_efficiency>
 
 <failure_handling>
-**Subagent fails mid-plan:**
-- SUMMARY.md won't exist
-- Orchestrator detects missing SUMMARY
-- Reports failure, asks user how to proceed
-
-**Dependency chain breaks:**
-- Wave 1 plan fails
-- Wave 2 plans depending on it will likely fail
-- Orchestrator can still attempt them (user choice)
-- Or skip dependent plans entirely
-
-**All agents in wave fail:**
-- Something systemic (git issues, permissions, etc.)
-- Stop execution
-- Report for manual investigation
-
-**Checkpoint fails to resolve:**
-- User can't approve or provides repeated issues
-- Ask: "Skip this plan?" or "Abort phase execution?"
-- Record partial progress in STATE.md
+- **classifyHandoffIfNeeded false failure:** Agent reports "failed" but error is `classifyHandoffIfNeeded is not defined` → OpenCode bug, not GSD. Spot-check (SUMMARY exists, commits present) → if pass, treat as success
+- **Agent fails mid-plan:** Missing SUMMARY.md → report, ask user how to proceed
+- **Dependency chain breaks:** Wave 1 fails → Wave 2 dependents likely fail → user chooses attempt or skip
+- **All agents in wave fail:** Systemic issue → stop, report for investigation
+- **Checkpoint unresolvable:** "Skip this plan?" or "Abort phase execution?" → record partial progress in STATE.md
 </failure_handling>
 
 <resumption>
-**Resuming interrupted execution:**
-
-If phase execution was interrupted (context limit, user exit, error):
-
-1. Run `/gsd-execute-phase {phase}` again
-2. discover_plans finds completed SUMMARYs
-3. Skips completed plans
-4. Resumes from first incomplete plan
-5. Continues wave-based execution
+Re-run `/gsd-execute-phase {phase}` → discover_plans finds completed SUMMARYs → skips them → resumes from first incomplete plan → continues wave execution.
 
-**STATE.md tracks:**
-- Last completed plan
-- Current wave
-- Any pending checkpoints
+STATE.md tracks: last completed plan, current wave, pending checkpoints.
 </resumption>