gsd-opencode 1.22.1 → 1.33.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,9 +33,10 @@ 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`.
+Extract from init JSON: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`, `subagent_timeout`.
 </step>
 
 <step name="check_existing">
@@ -82,22 +88,27 @@ 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**
 
 ```
-task(
-  subagent_type="gsd-codebase-mapper",
-  model="{mapper_model}",
-  run_in_background=true,
-  description="Map codebase tech stack",
-  prompt="Focus: tech
+@gsd-codebase-mapper "Focus: tech
 
 Analyze this codebase for technology stack and external integrations.
 
@@ -105,19 +116,14 @@ 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}"
 ```
 
 **Agent 2: Architecture Focus**
 
 ```
-task(
-  subagent_type="gsd-codebase-mapper",
-  model="{mapper_model}",
-  run_in_background=true,
-  description="Map codebase architecture",
-  prompt="Focus: arch
+@gsd-codebase-mapper "Focus: arch
 
 Analyze this codebase architecture and directory structure.
 
@@ -125,19 +131,14 @@ 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}"
 ```
 
 **Agent 3: Quality Focus**
 
 ```
-task(
-  subagent_type="gsd-codebase-mapper",
-  model="{mapper_model}",
-  run_in_background=true,
-  description="Map codebase conventions",
-  prompt="Focus: quality
+@gsd-codebase-mapper "Focus: quality
 
 Analyze this codebase for coding conventions and testing patterns.
 
@@ -145,36 +146,43 @@ 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}"
 ```
 
 **Agent 4: Concerns Focus**
 
 ```
-task(
-  subagent_type="gsd-codebase-mapper",
-  model="{mapper_model}",
-  run_in_background=true,
-  description="Map codebase concerns",
-  prompt="Focus: concerns
+@gsd-codebase-mapper "Focus: concerns
 
 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}"
 ```
 
 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: {subagent_timeout from init context, default 300000}
+```
+
+> The timeout is configurable via `workflow.subagent_timeout` in `.planning/config.json` (milliseconds). Default: 300000 (5 minutes). Increase for large codebases or slower models.
+
+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 +203,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:
 
@@ -286,9 +325,9 @@ Created .planning/codebase/:
 
 **Initialize project** — use codebase context for planning
 
-`/gsd-new-project`
+`/new` then:
 
-*`/new` first → fresh context window*
+`/gsd-new-project`
 
 ---
 
@@ -307,10 +346,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"
+```