gsd-opencode 1.22.0 → 1.30.0

package/get-shit-done/workflows/map-codebase.md

@@ -1,10 +1,15 @@
-<purpose>
+<objective>
 Orchestrate parallel codebase mapper agents to analyze codebase and produce structured documents in .planning/codebase/
 
 Each agent has fresh context, explores a specific focus area, and **writes documents directly**. The orchestrator only receives confirmation + line counts, then writes a summary.
 
 Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
-</purpose>
+</objective>
+
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general'):
+- gsd-codebase-mapper — Maps project structure and dependencies
+</available_agent_types>
 
 <philosophy>
 **Why dedicated mapper agents:**
@@ -28,6 +33,7 @@ Load codebase mapping context:
 ```bash
 INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init map-codebase)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+AGENT_SKILLS_MAPPER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-codebase-mapper 2>/dev/null)
 ```
 
 Extract from init JSON: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`.
@@ -82,12 +88,22 @@ mkdir -p .planning/codebase
 Continue to spawn_agents.
 </step>
 
-<step name="spawn_agents">
+<step name="detect_runtime_capabilities">
+Before spawning agents, detect whether the current runtime supports the `task` tool for subagent delegation.
+
+**How to detect:** Check if you have access to a `task` tool (may be capitalized as `task` or lowercase as `task` depending on runtime). If you do NOT have a `task`/`task` tool (or only have tools like `browser_subagent` which is for web browsing, NOT code analysis):
+
+→ **Skip `spawn_agents` and `collect_confirmations`** — go directly to `sequential_mapping` instead.
+
+**CRITICAL:** Never use `browser_subagent` or `Explore` as a substitute for `task`. The `browser_subagent` tool is exclusively for web page interaction and will fail for codebase analysis. If `task` is unavailable, perform the mapping sequentially in-context.
+</step>
+
+<step name="spawn_agents" condition="task tool is available">
 Spawn 4 parallel gsd-codebase-mapper agents.
 
 Use task tool with `subagent_type="gsd-codebase-mapper"`, `model="{mapper_model}"`, and `run_in_background=true` for parallel execution.
 
-**CRITICAL:** Use the dedicated `gsd-codebase-mapper` agent, NOT `Explore`. The mapper agent writes documents directly.
+**CRITICAL:** Use the dedicated `gsd-codebase-mapper` agent, NOT `Explore` or `browser_subagent`. The mapper agent writes documents directly.
 
 **Agent 1: Tech Focus**
 
@@ -105,7 +121,8 @@ write these documents to .planning/codebase/:
 - STACK.md - Languages, runtime, frameworks, dependencies, configuration
 - INTEGRATIONS.md - External APIs, databases, auth providers, webhooks
 
-Explore thoroughly. write documents directly using templates. Return confirmation only."
+Explore thoroughly. write documents directly using templates. Return confirmation only.
+${AGENT_SKILLS_MAPPER}"
 )
 ```
 
@@ -125,7 +142,8 @@ write these documents to .planning/codebase/:
 - ARCHITECTURE.md - Pattern, layers, data flow, abstractions, entry points
 - STRUCTURE.md - Directory layout, key locations, naming conventions
 
-Explore thoroughly. write documents directly using templates. Return confirmation only."
+Explore thoroughly. write documents directly using templates. Return confirmation only.
+${AGENT_SKILLS_MAPPER}"
 )
 ```
 
@@ -145,7 +163,8 @@ write these documents to .planning/codebase/:
 - CONVENTIONS.md - Code style, naming, patterns, error handling
 - TESTING.md - Framework, structure, mocking, coverage
 
-Explore thoroughly. write documents directly using templates. Return confirmation only."
+Explore thoroughly. write documents directly using templates. Return confirmation only.
+${AGENT_SKILLS_MAPPER}"
 )
 ```
 
@@ -164,7 +183,8 @@ Analyze this codebase for technical debt, known issues, and areas of concern.
 write this document to .planning/codebase/:
 - CONCERNS.md - Tech debt, bugs, security, performance, fragile areas
 
-Explore thoroughly. write document directly using template. Return confirmation only."
+Explore thoroughly. write document directly using template. Return confirmation only.
+${AGENT_SKILLS_MAPPER}"
 )
 ```
 
@@ -172,9 +192,19 @@ Continue to collect_confirmations.
 </step>
 
 <step name="collect_confirmations">
-Wait for all 4 agents to complete.
+Wait for all 4 agents to complete using TaskOutput tool.
 
-read each agent's output file to collect confirmations.
+**For each agent task_id returned by the Agent tool calls above:**
+```
+TaskOutput tool:
+  task_id: "{task_id from Agent result}"
+  block: true
+  timeout: 300000
+```
+
+Call TaskOutput for all 4 agents in parallel (single message with 4 TaskOutput calls).
+
+Once all TaskOutput calls return, read each agent's output file to collect confirmations.
 
 **Expected confirmation format from each agent:**
 ```
@@ -195,6 +225,37 @@ If any agent failed, note the failure and continue with successful documents.
 Continue to verify_output.
 </step>
 
+<step name="sequential_mapping" condition="task tool is NOT available (e.g. Antigravity, Gemini CLI, Codex)">
+When the `task` tool is unavailable, perform codebase mapping sequentially in the current context. This replaces `spawn_agents` and `collect_confirmations`.
+
+**IMPORTANT:** Do NOT use `browser_subagent`, `Explore`, or any browser-based tool. Use only file system tools (read, bash, write, grep, glob, list_dir, view_file, grep_search, or equivalent tools available in your runtime).
+
+Perform all 4 mapping passes sequentially:
+
+**Pass 1: Tech Focus**
+- Explore package.json/Cargo.toml/go.mod/requirements.txt, config files, dependency trees
+- write `.planning/codebase/STACK.md` — Languages, runtime, frameworks, dependencies, configuration
+- write `.planning/codebase/INTEGRATIONS.md` — External APIs, databases, auth providers, webhooks
+
+**Pass 2: Architecture Focus**
+- Explore directory structure, entry points, module boundaries, data flow
+- write `.planning/codebase/ARCHITECTURE.md` — Pattern, layers, data flow, abstractions, entry points
+- write `.planning/codebase/STRUCTURE.md` — Directory layout, key locations, naming conventions
+
+**Pass 3: Quality Focus**
+- Explore code style, error handling patterns, test files, CI config
+- write `.planning/codebase/CONVENTIONS.md` — Code style, naming, patterns, error handling
+- write `.planning/codebase/TESTING.md` — Framework, structure, mocking, coverage
+
+**Pass 4: Concerns Focus**
+- Explore TODOs, known issues, fragile areas, security patterns
+- write `.planning/codebase/CONCERNS.md` — Tech debt, bugs, security, performance, fragile areas
+
+Use the same document templates as the `gsd-codebase-mapper` agent. Include actual file paths formatted with backticks.
+
+Continue to verify_output.
+</step>
+
 <step name="verify_output">
 Verify all documents created successfully:
 
@@ -307,10 +368,10 @@ End workflow.
 
 <success_criteria>
 - .planning/codebase/ directory created
-- 4 parallel gsd-codebase-mapper agents spawned with run_in_background=true
-- Agents write documents directly (orchestrator doesn't receive document contents)
-- read agent output files to collect confirmations
+- If task tool available: 4 parallel gsd-codebase-mapper agents spawned with run_in_background=true
+- If task tool NOT available: 4 sequential mapping passes performed inline (never using browser_subagent)
 - All 7 codebase documents exist
+- No empty documents (each should have >20 lines)
 - Clear completion summary with line counts
 - User offered clear next steps in GSD style
 </success_criteria>

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

@@ -0,0 +1,223 @@
+# Milestone Summary Workflow
+
+Generate a comprehensive, human-friendly project summary from completed milestone artifacts.
+Designed for team onboarding — a new contributor can read the output and understand the entire project.
+
+---
+
+## Step 1: Resolve Version
+
+```bash
+VERSION="$ARGUMENTS"
+```
+
+If `$ARGUMENTS` is empty:
+1. Check `.planning/STATE.md` for current milestone version
+2. Check `.planning/milestones/` for the latest archived version
+3. If neither found, check if `.planning/ROADMAP.md` exists (project may be mid-milestone)
+4. If nothing found: error "No milestone found. Run /gsd-new-project or /gsd-new-milestone first."
+
+Set `VERSION` to the resolved version (e.g., "1.0").
+
+## Step 2: Locate Artifacts
+
+Determine whether the milestone is **archived** or **current**:
+
+**Archived milestone** (`.planning/milestones/v{VERSION}-ROADMAP.md` exists):
+```
+ROADMAP_PATH=".planning/milestones/v${VERSION}-ROADMAP.md"
+REQUIREMENTS_PATH=".planning/milestones/v${VERSION}-REQUIREMENTS.md"
+AUDIT_PATH=".planning/milestones/v${VERSION}-MILESTONE-AUDIT.md"
+```
+
+**Current/in-progress milestone** (no archive yet):
+```
+ROADMAP_PATH=".planning/ROADMAP.md"
+REQUIREMENTS_PATH=".planning/REQUIREMENTS.md"
+AUDIT_PATH=".planning/v${VERSION}-MILESTONE-AUDIT.md"
+```
+
+Note: The audit file moves to `.planning/milestones/` on archive (per `complete-milestone` workflow). Check both locations as a fallback.
+
+**Always available:**
+```
+PROJECT_PATH=".planning/PROJECT.md"
+RETRO_PATH=".planning/RETROSPECTIVE.md"
+STATE_PATH=".planning/STATE.md"
+```
+
+read all files that exist. Missing files are fine — the summary adapts to what's available.
+
+## Step 3: Discover Phase Artifacts
+
+Find all phase directories:
+
+```bash
+gsd-tools.cjs init progress
+```
+
+This returns phase metadata. For each phase in the milestone scope:
+
+- read `{phase_dir}/{padded}-SUMMARY.md` if it exists — extract `one_liner`, `accomplishments`, `decisions`
+- read `{phase_dir}/{padded}-VERIFICATION.md` if it exists — extract status, gaps, deferred items
+- read `{phase_dir}/{padded}-CONTEXT.md` if it exists — extract key decisions from `<decisions>` section
+- read `{phase_dir}/{padded}-RESEARCH.md` if it exists — note what was researched
+
+Track which phases have which artifacts.
+
+**If no phase directories exist** (empty milestone or pre-build state): skip to Step 5 and generate a minimal summary noting "No phases have been executed yet." Do not error — the summary should still capture PROJECT.md and ROADMAP.md content.
+
+## Step 4: Gather Git Statistics
+
+Try each method in order until one succeeds:
+
+**Method 1 — Tagged milestone** (check first):
+```bash
+git tag -l "v${VERSION}" | head -1
+```
+If the tag exists:
+```bash
+git log v${VERSION} --oneline | wc -l
+git diff --stat $(git log --format=%H --reverse v${VERSION} | head -1)..v${VERSION}
+```
+
+**Method 2 — STATE.md date range** (if no tag):
+read STATE.md and extract the `started_at` or earliest session date. Use it as the `--since` boundary:
+```bash
+git log --oneline --since="<started_at_date>" | wc -l
+```
+
+**Method 3 — Earliest phase commit** (if STATE.md has no date):
+Find the earliest `.planning/phases/` commit:
+```bash
+git log --oneline --diff-filter=A -- ".planning/phases/" | tail -1
+```
+Use that commit's date as the start boundary.
+
+**Method 4 — Skip stats** (if none of the above work):
+Report "Git statistics unavailable — no tag or date range could be determined." This is not an error — the summary continues without the Stats section.
+
+Extract (when available):
+- Total commits in milestone
+- Files changed, insertions, deletions
+- Timeline (start date → end date)
+- Contributors (from git log authors)
+
+## Step 5: Generate Summary Document
+
+write to `.planning/reports/MILESTONE_SUMMARY-v${VERSION}.md`:
+
+```markdown
+# Milestone v{VERSION} — Project Summary
+
+**Generated:** {date}
+**Purpose:** Team onboarding and project review
+
+---
+
+## 1. Project Overview
+
+{From PROJECT.md: "What This Is", core value proposition, target users}
+{If mid-milestone: note which phases are complete vs in-progress}
+
+## 2. Architecture & Technical Decisions
+
+{From CONTEXT.md files across phases: key technical choices}
+{From SUMMARY.md decisions: patterns, libraries, frameworks chosen}
+{From PROJECT.md: tech stack if documented}
+
+Present as a bulleted list of decisions with brief rationale:
+- **Decision:** {what was chosen}
+  - **Why:** {rationale from CONTEXT.md}
+  - **Phase:** {which phase made this decision}
+
+## 3. Phases Delivered
+
+| Phase | Name | Status | One-Liner |
+|-------|------|--------|-----------|
+{For each phase: number, name, status (complete/in-progress/planned), one_liner from SUMMARY.md}
+
+## 4. Requirements Coverage
+
+{From REQUIREMENTS.md: list each requirement with status}
+- ✅ {Requirement met}
+- ⚠️ {Requirement partially met — note gap}
+- ❌ {Requirement not met — note reason}
+
+{If MILESTONE-AUDIT.md exists: include audit verdict}
+
+## 5. Key Decisions Log
+
+{Aggregate from all CONTEXT.md <decisions> sections}
+{Each decision with: ID, description, phase, rationale}
+
+## 6. Tech Debt & Deferred Items
+
+{From VERIFICATION.md files: gaps found, anti-patterns noted}
+{From RETROSPECTIVE.md: lessons learned, what to improve}
+{From CONTEXT.md <deferred> sections: ideas parked for later}
+
+## 7. Getting Started
+
+{Entry points for new contributors:}
+- **Run the project:** {from PROJECT.md or SUMMARY.md}
+- **Key directories:** {from codebase structure}
+- **Tests:** {test command from PROJECT.md or AGENTS.md}
+- **Where to look first:** {main entry points, core modules}
+
+---
+
+## Stats
+
+- **Timeline:** {start} → {end} ({duration})
+- **Phases:** {count complete} / {count total}
+- **Commits:** {count}
+- **Files changed:** {count} (+{insertions} / -{deletions})
+- **Contributors:** {list}
+```
+
+## Step 6: write and Commit
+
+**Overwrite guard:** If `.planning/reports/MILESTONE_SUMMARY-v${VERSION}.md` already exists, ask the user:
+> "A milestone summary for v{VERSION} already exists. Overwrite it, or view the existing one?"
+If "view": display existing file and skip to Step 8 (interactive mode). If "overwrite": proceed.
+
+Create the reports directory if needed:
+```bash
+mkdir -p .planning/reports
+```
+
+write the summary, then commit:
+```bash
+gsd-tools.cjs commit "docs(v${VERSION}): generate milestone summary for onboarding" \
+  --files ".planning/reports/MILESTONE_SUMMARY-v${VERSION}.md"
+```
+
+## Step 7: Present Summary
+
+Display the full summary document inline.
+
+## Step 8: Offer Interactive Mode
+
+After presenting the summary:
+
+> "Summary written to `.planning/reports/MILESTONE_SUMMARY-v{VERSION}.md`.
+>
+> I have full context from the build artifacts. Want to ask anything about the project?
+> Architecture decisions, specific phases, requirements, tech debt — ask away."
+
+If the user asks questions:
+- Answer from the artifacts already loaded (CONTEXT.md, SUMMARY.md, VERIFICATION.md, etc.)
+- Reference specific files and decisions
+- Stay grounded in what was actually built (not speculation)
+
+If the user is done:
+- Suggest next steps: `/gsd-new-milestone`, `/gsd-progress`, or sharing the summary with the team
+
+## Step 9: Update STATE.md
+
+```bash
+gsd-tools.cjs state record-session \
+  --stopped-at "Milestone v${VERSION} summary generated" \
+  --resume-file ".planning/reports/MILESTONE_SUMMARY-v${VERSION}.md"
+```

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

@@ -1,8 +1,8 @@
-<purpose>
+<objective>
 
 Start a new milestone cycle for an existing project. Loads project context, gathers milestone goals (from MILESTONE-CONTEXT.md or conversation), updates PROJECT.md and STATE.md, optionally runs parallel research, defines scoped requirements with REQ-IDs, spawns the roadmapper to create phased execution plan, and commits all artifacts. Brownfield equivalent of new-project.
 
-</purpose>
+</objective>
 
 <required_reading>
 
@@ -10,10 +10,23 @@ read all files referenced by the invoking prompt's execution_context before star
 
 </required_reading>
 
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general'):
+- gsd-project-researcher — Researches project-level technical decisions
+- gsd-research-synthesizer — Synthesizes findings from parallel research agents
+- gsd-roadmapper — Creates phased execution roadmaps
+</available_agent_types>
+
 <process>
 
 ## 1. Load Context
 
+Parse `$ARGUMENTS` before doing anything else:
+- `--reset-phase-numbers` flag → opt into restarting roadmap phase numbering at `1`
+- remaining text → use as milestone name if present
+
+If the flag is absent, keep the current behavior of continuing phase numbering from the previous milestone.
+
 - read PROJECT.md (existing project, validated requirements, decisions)
 - read MILESTONES.md (what shipped previously)
 - read STATE.md (pending todos, blockers)
@@ -37,6 +50,38 @@ read all files referenced by the invoking prompt's execution_context before star
 - Suggest next version (v1.0 → v1.1, or v2.0 for major)
 - Confirm with user
 
+## 3.5. Verify Milestone Understanding
+
+Before writing any files, present a summary of what was gathered and ask for confirmation.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► MILESTONE SUMMARY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Milestone v[X.Y]: [Name]**
+
+**Goal:** [One sentence]
+
+**Target features:**
+- [Feature 1]
+- [Feature 2]
+- [Feature 3]
+
+**Key context:** [Any important constraints, decisions, or notes from questioning]
+```
+
+question:
+- header: "Confirm?"
+- question: "Does this capture what you want to build in this milestone?"
+- options:
+  - "Looks good" — Proceed to write PROJECT.md
+  - "Adjust" — Let me correct or add details
+
+**If "Adjust":** Ask what needs changing (plain text, NOT question). Incorporate changes, re-present the summary. Loop until "Looks good" is selected.
+
+**If "Looks good":** Proceed to Step 4.
+
 ## 4. Update PROJECT.md
 
 Add/update:
@@ -54,6 +99,27 @@ Add/update:
 
 Update Active requirements section and "Last updated" footer.
 
+Ensure the `## Evolution` section exists in PROJECT.md. If missing (projects created before this feature), add it before the footer:
+
+```markdown
+## Evolution
+
+This document evolves at phase transitions and milestone boundaries.
+
+**After each phase transition** (via `/gsd-transition`):
+1. Requirements invalidated? → Move to Out of Scope with reason
+2. Requirements validated? → Move to Validated with phase reference
+3. New requirements emerged? → Add to Active
+4. Decisions to log? → Add to Key Decisions
+5. "What This Is" still accurate? → Update if drifted
+
+**After each milestone** (via `/gsd-complete-milestone`):
+1. Full review of all sections
+2. Core Value check — still the right priority?
+3. Audit Out of Scope — reasons still valid?
+4. Update Context with current state
+```
+
 ## 5. Update STATE.md
 
 ```markdown
@@ -80,27 +146,52 @@ node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: star
 ```bash
 INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init new-milestone)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+AGENT_SKILLS_RESEARCHER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-project-researcher 2>/dev/null)
+AGENT_SKILLS_SYNTHESIZER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-synthesizer 2>/dev/null)
+AGENT_SKILLS_ROADMAPPER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-roadmapper 2>/dev/null)
+```
+
+Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`, `latest_completed_milestone`, `phase_dir_count`, `phase_archive_path`.
+
+## 7.5 Reset-phase safety (only when `--reset-phase-numbers`)
+
+If `--reset-phase-numbers` is active:
+
+1. Set starting phase number to `1` for the upcoming roadmap.
+2. If `phase_dir_count > 0`, archive the old phase directories before roadmapping so new `01-*` / `02-*` directories cannot collide with stale milestone directories.
+
+If `phase_dir_count > 0` and `phase_archive_path` is available:
+
+```bash
+mkdir -p "${phase_archive_path}"
+find .planning/phases -mindepth 1 -maxdepth 1 -type d -exec mv {} "${phase_archive_path}/" \;
 ```
 
-Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`.
+Then verify `.planning/phases/` no longer contains old milestone directories before continuing.
+
+If `phase_dir_count > 0` but `phase_archive_path` is missing:
+- Stop and explain that reset numbering is unsafe without a completed milestone archive target.
+- Tell the user to complete/archive the previous milestone first, then rerun `/gsd-new-milestone --reset-phase-numbers ${GSD_WS}`.
 
 ## 8. Research Decision
 
+Check `research_enabled` from init JSON (loaded from config).
+
+**If `research_enabled` is `true`:**
+
 question: "Research the domain ecosystem for new features before defining requirements?"
 - "Research first (Recommended)" — Discover patterns, features, architecture for NEW capabilities
-- "Skip research" — Go straight to requirements
+- "Skip research for this milestone" — Go straight to requirements (does not change your default)
 
-**Persist choice to config** (so future `/gsd-plan-phase` honors it):
+**If `research_enabled` is `false`:**
 
-```bash
-# If "Research first": persist true
-node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-set workflow.research true
+question: "Research the domain ecosystem for new features before defining requirements?"
+- "Skip research (current default)" — Go straight to requirements
+- "Research first" — Discover patterns, features, architecture for NEW capabilities
 
-# If "Skip research": persist false
-node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-set workflow.research false
-```
+**IMPORTANT:** Do NOT persist this choice to config.json. The `workflow.research` setting is a persistent user preference that controls plan-phase behavior across the project. Changing it here would silently alter future `/gsd-plan-phase` behavior. To change the default, use `/gsd-settings`.
 
-**If "Research first":**
+**If user chose "Research first":**
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -134,6 +225,8 @@ Focus ONLY on what's needed for the NEW features.
 - .planning/PROJECT.md (Project context)
 </files_to_read>
 
+${AGENT_SKILLS_RESEARCHER}
+
 <downstream_consumer>{CONSUMER}</downstream_consumer>
 
 <quality_gate>{GATES}</quality_gate>
@@ -168,6 +261,8 @@ Synthesize research outputs into SUMMARY.md.
 - .planning/research/PITFALLS.md
 </files_to_read>
 
+${AGENT_SKILLS_SYNTHESIZER}
+
 write to: .planning/research/SUMMARY.md
 Use template: $HOME/.config/opencode/get-shit-done/templates/research-project/SUMMARY.md
 Commit after writing.
@@ -268,7 +363,9 @@ node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: defi
 ◆ Spawning roadmapper...
 ```
 
-**Starting phase number:** read MILESTONES.md for last phase number. Continue from there (v1.0 ended at phase 5 → v1.1 starts at phase 6).
+**Starting phase number:**
+- If `--reset-phase-numbers` is active, start at **Phase 1**
+- Otherwise, continue from the previous milestone's last phase number (v1.0 ended at phase 5 → v1.1 starts at phase 6)
 
 ```
 task(prompt="
@@ -280,11 +377,16 @@ task(prompt="
 - .planning/config.json
 - .planning/MILESTONES.md
 </files_to_read>
+
+${AGENT_SKILLS_ROADMAPPER}
+
 </planning_context>
 
 <instructions>
 Create roadmap for milestone v[X.Y]:
-1. Start phase numbering from [N]
+1. Respect the selected numbering mode:
+   - `--reset-phase-numbers` → start at Phase 1
+   - default behavior → continue from the previous milestone's last phase number
 2. Derive phases from THIS MILESTONE's requirements only
 3. Map every requirement to exactly one phase
 4. Derive 2-5 success criteria per phase (observable user behaviors)
@@ -357,11 +459,11 @@ node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: crea
 
 **Phase [N]: [Phase Name]** — [Goal]
 
-`/gsd-discuss-phase [N]` — gather context and clarify approach
+`/gsd-discuss-phase [N] ${GSD_WS}` — gather context and clarify approach
 
 *`/new` first → fresh context window*
 
-Also: `/gsd-plan-phase [N]` — skip discussion, plan directly
+Also: `/gsd-plan-phase [N] ${GSD_WS}` — skip discussion, plan directly
 ```
 
 </process>
@@ -376,9 +478,9 @@ Also: `/gsd-plan-phase [N]` — skip discussion, plan directly
 - [ ] gsd-roadmapper spawned with phase numbering context
 - [ ] Roadmap files written immediately (not draft)
 - [ ] User feedback incorporated (if any)
-- [ ] ROADMAP.md phases continue from previous milestone
+- [ ] Phase numbering mode respected (continued or reset)
 - [ ] All commits made (if planning docs committed)
-- [ ] User knows next step: `/gsd-discuss-phase [N]`
+- [ ] User knows next step: `/gsd-discuss-phase [N] ${GSD_WS}`
 
 **Atomic commits:** Each phase commits its artifacts immediately.
 </success_criteria>