ragarciaruben 1.20.26 → 1.20.28

package/bin/install.js

@@ -160,6 +160,7 @@ const SRC = {
   opencodeJson:        path.join(PKG_ROOT, 'get-shit-done', 'templates', 'opencode.json'),
   opencodeAgents:      path.join(PKG_ROOT, 'get-shit-done', 'templates', 'opencode', 'agents'),
   opencodeCommands:    path.join(PKG_ROOT, 'get-shit-done', 'templates', 'opencode', 'commands'),
+  opencodeTools:       path.join(PKG_ROOT, 'get-shit-done', 'templates', 'opencode', 'tools'),
 
   // Shared
   planning:            path.join(PKG_ROOT, '.planning'),
@@ -368,7 +369,12 @@ function installOpencode() {
     copyDir(SRC.opencodeCommands, path.join(TARGET, '.opencode', 'commands'), results);
   }
 
-  // 5. .planning/
+  // 5. .opencode/tools/
+  if (fs.existsSync(SRC.opencodeTools)) {
+    copyDir(SRC.opencodeTools, path.join(TARGET, '.opencode', 'tools'), results);
+  }
+
+  // 6. .planning/
   if (fs.existsSync(SRC.planning)) {
     copyDir(SRC.planning, path.join(TARGET, '.planning'), results);
   } else {
@@ -412,6 +418,7 @@ function uninstallOpencode() {
   if (removeFile(path.join(TARGET, 'opencode.json')))           removed++;
   if (removeDir(path.join(TARGET, '.opencode', 'agents')))      removed++;
   if (removeDir(path.join(TARGET, '.opencode', 'commands')))    removed++;
+  if (removeDir(path.join(TARGET, '.opencode', 'tools')))       removed++;
 
   console.log(removed > 0
     ? c.green(`  ✓ Removed ${removed} OpenCode items`)

package/get-shit-done/templates/opencode/agents/codebase-mapper.md

@@ -0,0 +1,94 @@
+---
+description: Analyzes a specific focus area of the codebase and writes structured documents to .planning/codebase/. Invoked by the orchestrator for parallel codebase mapping.
+mode: subagent
+hidden: true
+tools:
+  write: true
+  edit: true
+  bash: true
+permission:
+  bash:
+    "*": ask
+    "grep *": allow
+    "find *": allow
+    "cat *": allow
+    "ls *": allow
+    "head *": allow
+    "tail *": allow
+    "wc *": allow
+    "git log*": allow
+    "git status*": allow
+---
+
+# Codebase Mapper Agent
+
+I am a codebase analysis specialist. I explore a specific focus area of the codebase and **write structured documents directly** to `.planning/codebase/`. I return only confirmation with file paths and line counts — no document content.
+
+## Focus Areas
+
+I handle one of 4 focus areas per invocation:
+
+### Focus: tech
+**Explore:**
+```bash
+cat package.json 2>/dev/null | head -100
+cat requirements.txt 2>/dev/null || cat pyproject.toml 2>/dev/null | head -50
+cat go.mod 2>/dev/null | head -30
+ls -la *.config.* tsconfig.json .nvmrc .python-version 2>/dev/null
+ls .env* 2>/dev/null   # Note existence only — NEVER read .env contents
+grep -r "import.*stripe\|import.*supabase\|import.*aws\|import.*prisma\|import.*redis\|import.*sendgrid\|import.*twilio\|import.*openai" src/ --include="*.ts" --include="*.py" 2>/dev/null | head -40
+```
+**Write:** `.planning/codebase/STACK.md` + `.planning/codebase/INTEGRATIONS.md`
+
+### Focus: arch
+**Explore:**
+```bash
+find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/.planning/*' -not -path '*/.opencode/*' | sort | head -60
+ls src/index.* src/main.* src/app.* src/server.* app/page.* 2>/dev/null
+grep -r "^import\|^from" src/ --include="*.ts" --include="*.py" 2>/dev/null | head -80
+```
+**Write:** `.planning/codebase/ARCHITECTURE.md` + `.planning/codebase/STRUCTURE.md`
+
+### Focus: quality
+**Explore:**
+```bash
+cat .prettierrc .eslintrc.js .eslintrc.json biome.json 2>/dev/null | head -60
+cat pyproject.toml 2>/dev/null | grep -A 20 "\[tool\."
+ls jest.config.* vitest.config.* pytest.ini setup.cfg 2>/dev/null
+find . -name "*.test.*" -o -name "*.spec.*" | grep -v node_modules | head -20
+find src/ -name "*.ts" -not -name "*.test.*" 2>/dev/null | head -5 | xargs head -40 2>/dev/null
+find tests/ -name "*.test.*" 2>/dev/null | head -3 | xargs head -60 2>/dev/null
+```
+**Write:** `.planning/codebase/CONVENTIONS.md` + `.planning/codebase/TESTING.md`
+
+### Focus: concerns
+**Explore:**
+```bash
+grep -rn "TODO\|FIXME\|HACK\|XXX\|TEMP\|@deprecated" src/ --include="*.ts" --include="*.py" 2>/dev/null | head -40
+grep -rn "any\b\|@ts-ignore\|@ts-nocheck\|eslint-disable\|# type: ignore\|# noqa" src/ --include="*.ts" --include="*.py" 2>/dev/null | head -30
+grep -rn "eval\|innerHTML\|dangerouslySetInnerHTML\|exec\|shell=True" src/ --include="*.ts" --include="*.py" 2>/dev/null | head -20
+find src/ -name "*.ts" -o -name "*.py" 2>/dev/null | xargs wc -l 2>/dev/null | sort -rn | head -15
+```
+**Write:** `.planning/codebase/CONCERNS.md`
+
+## My Rules
+
+- **Write documents directly** — don't return content to the orchestrator
+- **Include file paths** — always use backtick-formatted paths: `src/services/user.ts`
+- **Include real code examples** — especially in CONVENTIONS.md
+- **Be prescriptive** — state what the pattern IS, not what it might be
+- **NEVER read .env file contents** — only note existence
+
+## Return Format
+
+When done, return ONLY:
+```
+## Mapping Complete
+
+**Focus:** {focus}
+**Documents written:**
+- `.planning/codebase/{DOC1}.md` ({N} lines)
+- `.planning/codebase/{DOC2}.md` ({N} lines)
+
+Ready for orchestrator summary.
+```

package/get-shit-done/templates/opencode/agents/executor.md

@@ -1,7 +1,6 @@
 ---
-description: Implements planned phases — writes code, runs tests, and makes atomic commits following established conventions. Use me to execute a ready plan.
-mode: primary
-model: anthropic/claude-sonnet-4-20250514
+description: Implements planned phases — writes code, runs tests, and makes atomic commits following established conventions. Invoked by orchestrator for parallel plan execution or used directly for single plans.
+mode: all
 tools:
   write: true
   edit: true

package/get-shit-done/templates/opencode/agents/orchestrator.md

@@ -0,0 +1,128 @@
+---
+description: Coordinates phase execution by discovering plans, grouping into waves, and spawning parallel executor subagents. Use me to run a full phase with wave-based execution.
+mode: primary
+tools:
+  write: true
+  edit: true
+  bash: true
+permission:
+  task:
+    "executor": "allow"
+    "verifier": "allow"
+    "codebase-mapper": "allow"
+    "*": "deny"
+---
+
+# Orchestrator Agent
+
+I am a coordination specialist. I **never write implementation code** — I discover plans, group them into dependency waves, spawn executor subagents in parallel, collect results, and verify outcomes.
+
+## Core Principle
+
+**Orchestrator coordinates, not executes.** Each subagent gets fresh context. I stay lean (~10-15% context) by passing **file paths only** — subagents read files themselves.
+
+## How I Execute a Phase
+
+### 1. Initialize
+
+Read `.planning/ROADMAP.md` to find the target phase and its plans. Read `.planning/STATE.md` for current position.
+
+```bash
+ls .planning/phases/[NN]-[phase-name]/*-PLAN.md 2>/dev/null | sort
+ls .planning/phases/[NN]-[phase-name]/*-SUMMARY.md 2>/dev/null | sort
+```
+
+### 2. Discover & Group Plans
+
+For each plan file, read its frontmatter to find `wave:` and `depends_on:` fields.
+
+**Wave assignment rules:**
+- Plans with no `depends_on` → Wave 1
+- Plans depending on Wave 1 plans → Wave 2
+- Wave N = max(wave of dependencies) + 1
+- If no `wave:` frontmatter, treat all plans as Wave 1 (sequential fallback)
+
+**Skip completed plans:** Any plan that already has a matching SUMMARY.md is skipped.
+
+Report the execution plan:
+```
+## Execution Plan
+
+**Phase {X}: {Name}** — {total} plans across {wave_count} waves
+
+| Wave | Plans | What it builds |
+|------|-------|----------------|
+| 1 | 01-01, 01-02 | {from plan objectives} |
+| 2 | 01-03 | {depends on wave 1 outputs} |
+```
+
+### 3. Execute Waves
+
+Execute each wave in sequence. **Within a wave: spawn all executors in parallel** using the Task tool.
+
+**For each wave:**
+
+1. **Describe what's being built** — read each plan's objective, explain what it does and why it matters
+
+2. **Spawn `@executor` for each plan in the wave:**
+
+   Pass paths only — executors read files themselves with their fresh context.
+
+   For each plan, invoke `@executor` with:
+   ```
+   Execute plan {plan_number} of phase {phase_number}-{phase_name}.
+
+   Files to read at start:
+   - {phase_dir}/{plan_file} (the plan)
+   - .planning/STATE.md (current state)
+   - .planning/codebase/CONVENTIONS.md (coding standards)
+   - .planning/codebase/STRUCTURE.md (file placement)
+   - .planning/codebase/CONCERNS.md (fragile areas)
+
+   Success criteria:
+   - All tasks executed per the plan
+   - Tests pass after each task
+   - Atomic commit per completed plan
+   - ROADMAP.md updated with plan progress
+   ```
+
+3. **Wait for all agents in wave to complete**
+
+4. **Spot-check each completed plan:**
+   - Verify SUMMARY.md or commit exists: `git log --oneline --grep="{phase}-{plan}" | head -3`
+   - Check test suite still passes: `npm test 2>&1 | tail -5`
+
+5. **Report wave completion** — what was built, notable deviations, what it enables for next wave
+
+6. **Proceed to next wave**
+
+### 4. Post-Execution
+
+After all waves complete:
+- Invoke `@verifier` to verify the phase against requirements
+- Report aggregate results
+
+## Spot-Check Protocol
+
+After each wave, for each completed plan:
+- Check `git log --oneline --grep="{plan-id}"` returns ≥1 commit
+- Run `npm test` to confirm no regressions
+- If any check fails: report which plan failed, ask "Retry?" or "Continue?"
+
+## Failure Handling
+
+- **Agent fails mid-plan:** Report which plan failed, ask user how to proceed
+- **Dependency chain breaks:** Wave N fails → Wave N+1 dependents likely fail → user chooses attempt or skip
+- **All agents in wave fail:** Stop, report for investigation
+
+## Resumption
+
+Re-running skips completed plans (those with SUMMARY.md). I resume from the first incomplete plan in the first incomplete wave.
+
+## Context Efficiency
+
+I stay at ~10-15% context usage. Subagents get fresh context each. No content transfer back — I only read confirmations and check file existence.
+
+## Trigger Phrases
+
+"Execute phase [N]", "Run phase [N] with parallel agents", "Orchestrate phase [N]"

package/get-shit-done/templates/opencode/agents/planner.md

@@ -1,7 +1,6 @@
 ---
 description: Plans implementation phases — reads requirements and codebase context to produce executable step-by-step plans. Use me before starting new work.
 mode: primary
-model: anthropic/claude-opus-4-20250514
 tools:
   write: true
   edit: true

package/get-shit-done/templates/opencode/agents/product-owner.md

@@ -1,7 +1,6 @@
 ---
 description: Creates and refines Jira tickets from ideas, epics, or requirements — turns vague requests into well-structured specs. Use me to define WHAT to build.
 mode: subagent
-model: anthropic/claude-sonnet-4-20250514
 tools:
   write: false
   edit: false

package/get-shit-done/templates/opencode/agents/verifier.md

@@ -1,7 +1,6 @@
 ---
 description: Verifies completed work against requirements — checks tests, inspects implementation, and produces a verification report. Use me after implementing a phase.
 mode: subagent
-model: anthropic/claude-sonnet-4-20250514
 tools:
   write: true
   edit: true

package/get-shit-done/templates/opencode/commands/execute-phase.md

@@ -1,120 +1,219 @@
 ---
-description: Execute a planned phase step-by-step, implementing each plan and running tests
-agent: executor
+description: Execute all plans in a phase using wave-based parallel execution with the orchestrator agent
+agent: orchestrator
 ---
 
 # Execute Phase
 
 **Usage:** `/execute-phase [phase-number]` — e.g., `/execute-phase 1`
 
-Implement the planned phase. Execute each plan in sequence, following established conventions and committing after each completed plan.
+Execute a planned phase using wave-based parallel execution. The orchestrator discovers plans, groups them by dependency waves, and spawns executor subagents in parallel.
 
-## Step 1: Load Execution Context
+## Step 1: Initialize
 
-Read these files:
-- `.planning/ROADMAP.md` — find the phase and its plans
-- `.planning/phases/[NN]-[phase-name]/` — load all plan files for this phase
-- `.planning/codebase/CONVENTIONS.md` — coding standards to follow throughout
-- `.planning/codebase/STRUCTURE.md` — where to place new files
-- `.planning/codebase/CONCERNS.md` — fragile areas to handle carefully
+Read all context in a single pass:
+
+```bash
+ls .planning/phases/ 2>/dev/null | sort
+```
+
+Find the target phase directory matching `$ARGUMENTS`. Then load:
+- `.planning/ROADMAP.md` — phase structure and success criteria
 - `.planning/STATE.md` — current position and any blockers
 
 If `.planning/continue-here.md` exists, read it first — it tells you exactly where to resume.
 
-## Step 2: Pre-flight Check
+## Step 2: Discover & Group Plans
 
-Before writing any code:
+```bash
+# List all plans and completed summaries
+ls .planning/phases/[NN]-[phase-name]/*-PLAN.md 2>/dev/null | sort
+ls .planning/phases/[NN]-[phase-name]/*-SUMMARY.md 2>/dev/null | sort
+```
+
+For each plan file:
+1. Read frontmatter for `wave:` and `depends_on:` fields
+2. **Skip** any plan that already has a matching SUMMARY.md (already complete)
+
+**Wave assignment:**
+- Plans with no `depends_on` → **Wave 1**
+- Plans depending on Wave 1 plans → **Wave 2**
+- Wave N = max(wave of dependencies) + 1
+- If no `wave:` frontmatter exists, treat all plans as **Wave 1** (sequential within single wave)
+
+Report the execution plan:
+```
+## Execution Plan
+
+**Phase {X}: {Name}** — {total} plans across {wave_count} waves
+
+| Wave | Plans | What it builds |
+|------|-------|----------------|
+| 1 | 01-01, 01-02 | {from plan objectives} |
+| 2 | 01-03 | {depends on wave 1 outputs} |
+```
+
+If all plans have SUMMARY.md: "All plans already complete. Run `/verify-work {phase}` to verify."
+
+## Step 3: Pre-flight Check
+
+Before spawning any agents:
 ```bash
 npm test 2>&1 | tail -20
-npx tsc --noEmit 2>&1 | head -20
 git status
 git branch --show-current
 ```
 
-If tests are already failing before you start, note them in STATE.md and proceed cautiously.
+If tests are already failing, note them in STATE.md and confirm with user before proceeding.
 
-## Step 3: Execute Plans
+## Step 4: Execute Waves
 
-For each plan file in the phase (in order):
+Execute each wave in sequence. **Within a wave: spawn all executor subagents in parallel.**
 
-### 3a. Read the plan fully before writing any code
+### For each wave:
 
-Understand all steps and success criteria before implementing step 1.
+#### 4a. Describe what's being built (BEFORE spawning)
 
-### 3b. Implement step by step
+Read each plan's objective. Extract what's being built and why.
 
-Follow the plan's steps precisely:
-- Create files in the correct location (check `.planning/codebase/STRUCTURE.md`)
-- Follow naming conventions (check `.planning/codebase/CONVENTIONS.md`)
-- Before touching any file listed in `.planning/codebase/CONCERNS.md` fragile areas — re-read that section
-- Write tests for each piece of functionality before moving to the next
+```
+---
+## Wave {N}
 
-### 3c. Verify after each step
+**{Plan ID}: {Plan Name}**
+{2-3 sentences: what this builds, technical approach, why it matters}
 
-```bash
-npm test
-npx tsc --noEmit
+Spawning {count} agent(s)...
+---
 ```
 
-Fix failures immediately — don't accumulate broken tests.
+- 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."
 
-### 3d. Commit after each completed plan
+#### 4b. Spawn `@executor` for each plan
 
-```bash
-git add -A
-git commit -m "[NN]-[plan]: [descriptive message]
+Pass paths only — executors read files themselves with their fresh context. This keeps orchestrator context lean (~10-15%).
+
+For each plan in the wave, invoke `@executor` with:
 
-- [What was implemented]
-- [Tests written]
-- [Key decisions]"
+```
+Execute plan {plan_number} of phase {phase_number}-{phase_name}.
+Commit each task atomically. Update ROADMAP.md with plan progress.
+
+Files to read at execution start:
+- {phase_dir}/{plan_file} (the plan)
+- .planning/STATE.md (current state)
+- .planning/codebase/CONVENTIONS.md (coding standards)
+- .planning/codebase/STRUCTURE.md (file placement)
+- .planning/codebase/CONCERNS.md (fragile areas)
+- .planning/codebase/TESTING.md (test patterns)
+
+Success criteria:
+- [ ] All tasks executed per the plan
+- [ ] Tests pass after each task
+- [ ] Atomic commit per completed plan
+- [ ] ROADMAP.md updated — mark plan as [x]
 ```
 
-### 3e. Update ROADMAP.md
+**Spawn ALL plans in the wave simultaneously** — multiple `@executor` invocations in a single turn for parallel execution.
 
-Mark the completed plan: `- [x] [NN]-01: [Description]`
+#### 4c. Wait for all agents in wave to complete
 
-## Step 4: Post-Phase Verification
+#### 4d. Spot-check completed plans
 
-After all plans in the phase are complete:
+For each completed plan:
+- Check `git log --oneline --grep="{plan-id}" | head -3` returns ≥1 commit
+- Run `npm test 2>&1 | tail -5` to confirm no regressions
 
-```bash
-npm test
-npm run test:coverage
-npx tsc --noEmit
-npm run lint
+If ANY spot-check fails:
 ```
+⚠ Plan {plan-id} spot-check failed:
+- Missing commit / Tests failing
 
-Verify against the phase's **Success Criteria** in ROADMAP.md.
+Retry this plan? | Continue with remaining waves? | Stop?
+```
 
-## Step 5: Update State
+#### 4e. Report wave completion
+
+```
+---
+## Wave {N} Complete
+
+**{Plan ID}: {Plan Name}**
+{What was built — substantive description}
+{Notable deviations, if any}
+
+{If more waves: what this enables for next wave}
+---
+```
+
+- Bad: "Wave 2 complete. Proceeding to Wave 3."
+- Good: "Auth system complete — JWT tokens, refresh flow, role-based middleware. API routes (Wave 3) can now enforce authentication."
+
+#### 4f. Proceed to next wave
+
+## Step 5: Post-Phase Verification
+
+After all waves complete, invoke `@verifier`:
+
+```
+Verify phase {phase_number} goal achievement.
+Phase directory: {phase_dir}
+Phase goal: {goal from ROADMAP.md}
+Check requirements against actual codebase.
+Create VERIFICATION.md.
+```
+
+| Verifier Result | Action |
+|----------------|--------|
+| **passed** | Update roadmap, mark phase complete |
+| **gaps_found** | Present gap summary, suggest `/plan-phase {X} --gaps` |
+
+## Step 6: Update State
 
 Update `.planning/STATE.md`:
-- Mark phase complete if all plans done
-- Update progress percentage
+- Mark phase complete (if verification passed)
 - Advance to next phase
 
 Update `.planning/ROADMAP.md`:
 - Mark phase checkbox: `- [x] **Phase N: ...**`
+- Record completion date
 
-## Handling Blockers
-
-If you hit a significant blocker:
-1. Document it in `.planning/STATE.md`
-2. Run `/pause-work` to save session state
-3. Describe the blocker clearly for the user to resolve
+```bash
+git add -A
+git commit -m "docs(phase-{X}): complete phase execution"
+```
 
-## Completion
+## Step 7: Aggregate Results
 
-Print a summary:
 ```
-✅ Phase [N] complete: [Phase Name]
+## Phase {X}: {Name} Execution Complete
+
+**Waves:** {N} | **Plans:** {M}/{total} complete
 
-Implemented:
-  - [NN]-01: [Name] — [key outcome]
-  - [NN]-02: [Name] — [key outcome]
+| Wave | Plans | Status |
+|------|-------|--------|
+| 1 | plan-01, plan-02 | ✓ Complete |
+| 2 | plan-03 | ✓ Complete |
 
-Tests: [N] passing, 0 failing
-Coverage: [X]%
+### Plan Details
+1. **{plan-id}**: {one-liner — what was built}
+2. **{plan-id}**: {one-liner — what was built}
 
-Run /verify-work [N] to validate against requirements.
+### Issues Encountered
+{Aggregate from execution, or "None"}
 ```
+
+## Failure Handling
+
+- **Agent fails mid-plan:** Report which plan failed, ask user how to proceed
+- **Dependency chain breaks:** Wave N fails → Wave N+1 dependents likely fail → user chooses attempt or skip
+- **All agents in wave fail:** Stop, report for investigation
+
+## Resumption
+
+Re-running `/execute-phase {phase}` discovers completed SUMMARYs, skips them, and resumes from the first incomplete plan in the first incomplete wave.
+
+## Context Efficiency
+
+Orchestrator: ~10-15% context. Subagents: fresh context each. No content transfer — only file paths and confirmations.

package/get-shit-done/templates/opencode/commands/map-codebase.md

@@ -1,86 +1,132 @@
 ---
-description: Analyze the codebase and generate structured context documents in .planning/codebase/
-agent: executor
+description: Analyze the codebase with parallel mapper agents to produce structured context documents in .planning/codebase/
+agent: orchestrator
 ---
 
 # Map Codebase
 
-Analyze this codebase thoroughly and generate 7 structured context documents in `.planning/codebase/`. These documents will be used on every future request to understand the project's architecture, conventions, and constraints.
+Analyze this codebase using **parallel `@codebase-mapper` subagents** to generate 7 structured context documents in `.planning/codebase/`. Each mapper explores a specific focus area and writes documents directly — the orchestrator only collects confirmations.
 
-## Process
+## Step 1: Check Existing
 
-Work through 4 focus areas in sequence. For each area, explore the codebase using the terminal and search tools, then write the document(s) directly to `.planning/codebase/`.
+```bash
+ls -la .planning/codebase/ 2>/dev/null
+```
 
----
+**If `.planning/codebase/` exists with documents:**
+```
+.planning/codebase/ already exists with these documents:
+{list files found}
+
+1. Refresh — Delete existing and remap codebase
+2. Update — Keep existing, only update specific documents
+3. Skip — Use existing codebase map as-is
+```
+
+Wait for user response. If "Refresh": delete `.planning/codebase/` and continue. If "Skip": exit.
+
+**If doesn't exist:** Continue.
 
-### Focus 1: Technology Stack → STACK.md + INTEGRATIONS.md
+## Step 2: Create Structure
 
-**Explore:**
 ```bash
-cat package.json 2>/dev/null | head -100
-cat requirements.txt 2>/dev/null || cat pyproject.toml 2>/dev/null | head -50
-cat go.mod 2>/dev/null | head -30
-ls -la *.config.* tsconfig.json .nvmrc .python-version 2>/dev/null
-ls .env* 2>/dev/null   # Note existence only — NEVER read .env contents
-grep -r "import.*stripe\|import.*supabase\|import.*aws\|import.*prisma\|import.*redis\|import.*sendgrid\|import.*twilio\|import.*openai" src/ --include="*.ts" --include="*.py" 2>/dev/null | head -40
+mkdir -p .planning/codebase
 ```
 
-**Write `.planning/codebase/STACK.md`** with: runtime, frameworks, key dependencies table, dev toolchain, infrastructure, environment variables.
+## Step 3: Spawn 4 Parallel Mapper Agents
 
-**Write `.planning/codebase/INTEGRATIONS.md`** with: a section per external service.
+Spawn all 4 `@codebase-mapper` subagents **simultaneously** — invoke them all in the same turn for parallel execution.
 
----
+**Agent 1: Tech Focus** — invoke `@codebase-mapper` with:
+```
+Focus: tech
 
-### Focus 2: Architecture + Structure → ARCHITECTURE.md + STRUCTURE.md
+Analyze this codebase for technology stack and external integrations.
 
-**Explore:**
-```bash
-find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/.planning/*' -not -path '*/.github/*' -not -path '*/.opencode/*' | sort | head -60
-ls src/index.* src/main.* src/app.* src/server.* app/page.* 2>/dev/null
-grep -r "^import\|^from" src/ --include="*.ts" --include="*.py" 2>/dev/null | head -80
+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. Return confirmation only.
 ```
 
-**Write `.planning/codebase/ARCHITECTURE.md`** with: architectural style, layer diagram, data flow example, key abstractions, entry points, cross-cutting concerns.
+**Agent 2: Architecture Focus** — invoke `@codebase-mapper` with:
+```
+Focus: arch
 
-**Write `.planning/codebase/STRUCTURE.md`** with: root layout, source tree, and a **"Where to Put New Code"** table.
+Analyze this codebase architecture and directory structure.
 
----
+Write these documents to .planning/codebase/:
+- ARCHITECTURE.md — Pattern, layers, data flow, abstractions, entry points
+- STRUCTURE.md — Directory layout, key locations, naming conventions
 
-### Focus 3: Conventions + Testing → CONVENTIONS.md + TESTING.md
+Explore thoroughly. Write documents directly. Return confirmation only.
+```
 
-**Explore:**
-```bash
-cat .prettierrc .eslintrc.js .eslintrc.json biome.json 2>/dev/null | head -60
-cat pyproject.toml 2>/dev/null | grep -A 20 "\[tool\."
-ls jest.config.* vitest.config.* pytest.ini setup.cfg 2>/dev/null
-find . -name "*.test.*" -o -name "*.spec.*" | grep -v node_modules | head -20
-find src/ -name "*.ts" -not -name "*.test.*" 2>/dev/null | head -5 | xargs head -40 2>/dev/null
-find tests/ -name "*.test.*" 2>/dev/null | head -3 | xargs head -60 2>/dev/null
+**Agent 3: Quality Focus** — invoke `@codebase-mapper` with:
 ```
+Focus: quality
 
-**Write `.planning/codebase/CONVENTIONS.md`** — be prescriptive. Include: naming conventions, import ordering, error handling, function patterns, comment style. Include real code examples.
+Analyze this codebase for coding conventions and testing patterns.
 
-**Write `.planning/codebase/TESTING.md`** with: test framework, run commands, file organization, mocking strategy, what to test and what NOT to test.
+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. Return confirmation only.
+```
+
+**Agent 4: Concerns Focus** — invoke `@codebase-mapper` with:
+```
+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. Return confirmation only.
+```
 
-### Focus 4: Technical Concerns → CONCERNS.md
+## Step 4: Collect Confirmations & Verify
+
+Wait for all 4 agents to complete. Then verify all documents exist:
 
-**Explore:**
 ```bash
-grep -rn "TODO\|FIXME\|HACK\|XXX\|TEMP\|@deprecated" src/ --include="*.ts" --include="*.py" 2>/dev/null | head -40
-grep -rn "any\b\|@ts-ignore\|@ts-nocheck\|eslint-disable\|# type: ignore\|# noqa" src/ --include="*.ts" --include="*.py" 2>/dev/null | head -30
-grep -rn "eval\|innerHTML\|dangerouslySetInnerHTML\|exec\|shell=True" src/ --include="*.ts" --include="*.py" 2>/dev/null | head -20
-find src/ -name "*.ts" -o -name "*.py" 2>/dev/null | xargs wc -l 2>/dev/null | sort -rn | head -15
+echo "=== Codebase Map Verification ==="
+for f in STACK.md INTEGRATIONS.md ARCHITECTURE.md STRUCTURE.md CONVENTIONS.md TESTING.md CONCERNS.md; do
+  if [ -f ".planning/codebase/$f" ]; then
+    echo "✓ $f ($(wc -l < .planning/codebase/$f) lines)"
+  else
+    echo "✗ $f MISSING"
+  fi
+done
 ```
 
-**Write `.planning/codebase/CONCERNS.md`** with: health summary, critical issues, fragile areas, security notes, performance bottlenecks.
+If any document is missing, report which agent failed and offer to retry that focus area.
 
----
+## Step 5: Commit & Report
 
-## Completion
+```bash
+git add .planning/codebase/
+git commit -m "docs: map codebase — 7 structured documents in .planning/codebase/"
+```
+
+```
+✅ Codebase mapping complete
+
+Documents generated in .planning/codebase/:
+- STACK.md ({N} lines) — technology stack
+- INTEGRATIONS.md ({N} lines) — external services
+- ARCHITECTURE.md ({N} lines) — system design
+- STRUCTURE.md ({N} lines) — file organization
+- CONVENTIONS.md ({N} lines) — coding standards
+- TESTING.md ({N} lines) — test patterns
+- CONCERNS.md ({N} lines) — tech debt & risks
+
+Next: /new-project or /plan-phase to continue
+```
 
-After all 7 files are written, update `AGENTS.md`:
-- Fill in the "What This Project Is" section from what you learned
+## Context Efficiency
 
-Then confirm: "Codebase mapping complete. Generated 7 documents in `.planning/codebase/`. Use `/sync-instructions` to update the instructions digest."
+Orchestrator only dispatches and collects confirmations (file paths + line counts). Each mapper agent gets fresh context for deep exploration. No document content flows back to the orchestrator.

package/get-shit-done/templates/opencode/tools/plan-index.ts

@@ -0,0 +1,196 @@
+import { tool } from "@opencode-ai/plugin"
+import fs from "fs"
+import path from "path"
+
+export default tool({
+  description:
+    "Index phase plans, parse wave/dependency frontmatter, and return wave-grouped execution order. Use before executing a phase to discover plan structure.",
+  args: {
+    phase: tool.schema
+      .string()
+      .describe(
+        "Phase number or name to index (e.g., '1', '01', '01-auth-system')"
+      ),
+  },
+  async execute(args, context) {
+    const planningDir = path.join(context.directory, ".planning", "phases")
+
+    if (!fs.existsSync(planningDir)) {
+      return JSON.stringify({ error: ".planning/phases/ directory not found" })
+    }
+
+    // Find phase directory
+    const dirs = fs.readdirSync(planningDir).filter((d) => {
+      const full = path.join(planningDir, d)
+      return fs.statSync(full).isDirectory() && d.includes(args.phase)
+    })
+
+    if (dirs.length === 0) {
+      return JSON.stringify({
+        error: `No phase directory matching "${args.phase}" found`,
+      })
+    }
+
+    const phaseDir = path.join(planningDir, dirs[0])
+    const phaseName = dirs[0]
+
+    // Find all PLAN and SUMMARY files
+    const files = fs.readdirSync(phaseDir)
+    const planFiles = files
+      .filter((f) => f.endsWith("-PLAN.md"))
+      .sort()
+    const summaryFiles = files
+      .filter((f) => f.endsWith("-SUMMARY.md"))
+      .sort()
+
+    const summarySet = new Set(
+      summaryFiles.map((f) => f.replace("-SUMMARY.md", ""))
+    )
+
+    // Parse each plan
+    const plans = []
+    for (const planFile of planFiles) {
+      const planId = planFile.replace("-PLAN.md", "")
+      const content = fs.readFileSync(path.join(phaseDir, planFile), "utf8")
+
+      // Parse YAML frontmatter
+      const fm = parseFrontmatter(content)
+
+      plans.push({
+        id: planId,
+        file: planFile,
+        wave: fm.wave ? parseInt(fm.wave, 10) : null,
+        depends_on: fm.depends_on
+          ? Array.isArray(fm.depends_on)
+            ? fm.depends_on
+            : [fm.depends_on]
+          : [],
+        autonomous: fm.autonomous !== false,
+        objective: fm.objective || extractFirstHeading(content) || planId,
+        has_summary: summarySet.has(planId),
+        gap_closure: fm.gap_closure === true,
+      })
+    }
+
+    // Auto-assign waves if not specified
+    const hasWaves = plans.some((p) => p.wave !== null)
+    if (!hasWaves) {
+      // Simple: plans with no deps → wave 1, compute rest from dependency graph
+      assignWaves(plans)
+    }
+
+    // Group by wave
+    const waves = {}
+    for (const plan of plans) {
+      const w = plan.wave || 1
+      if (!waves[w]) waves[w] = []
+      waves[w].push(plan.id)
+    }
+
+    // Count incomplete
+    const incomplete = plans.filter((p) => !p.has_summary)
+
+    return JSON.stringify(
+      {
+        phase: phaseName,
+        phase_dir: phaseDir,
+        plan_count: plans.length,
+        incomplete_count: incomplete.length,
+        has_checkpoints: plans.some((p) => !p.autonomous),
+        plans,
+        waves,
+        incomplete: incomplete.map((p) => p.id),
+      },
+      null,
+      2
+    )
+  },
+})
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/)
+  if (!match) return {}
+
+  const fm = {}
+  const lines = match[1].split("\n")
+  let currentKey = null
+  let currentList = null
+
+  for (const line of lines) {
+    const kvMatch = line.match(/^(\w[\w_-]*):\s*(.*)$/)
+    if (kvMatch) {
+      if (currentKey && currentList) {
+        fm[currentKey] = currentList
+      }
+      currentKey = kvMatch[1]
+      const val = kvMatch[2].trim()
+      if (val === "") {
+        currentList = []
+      } else if (val === "true") {
+        fm[currentKey] = true
+        currentKey = null
+        currentList = null
+      } else if (val === "false") {
+        fm[currentKey] = false
+        currentKey = null
+        currentList = null
+      } else {
+        fm[currentKey] = val
+        currentKey = null
+        currentList = null
+      }
+    } else if (currentList !== null && line.match(/^\s*-\s+(.+)/)) {
+      currentList.push(line.match(/^\s*-\s+(.+)/)[1].trim())
+    }
+  }
+  if (currentKey && currentList) {
+    fm[currentKey] = currentList
+  }
+
+  return fm
+}
+
+function extractFirstHeading(content) {
+  // Skip frontmatter
+  let text = content
+  if (text.startsWith("---")) {
+    const end = text.indexOf("---", 3)
+    if (end !== -1) text = text.slice(end + 3)
+  }
+  const match = text.match(/^#+\s+(.+)/m)
+  return match ? match[1].trim() : null
+}
+
+function assignWaves(plans) {
+  const planMap = new Map(plans.map((p) => [p.id, p]))
+
+  // Plans with no dependencies → wave 1
+  for (const plan of plans) {
+    if (plan.depends_on.length === 0) {
+      plan.wave = 1
+    }
+  }
+
+  // Iteratively assign waves based on dependency graph
+  let changed = true
+  let iterations = 0
+  while (changed && iterations < 20) {
+    changed = false
+    iterations++
+    for (const plan of plans) {
+      if (plan.wave !== null) continue
+      const depWaves = plan.depends_on
+        .map((dep) => planMap.get(dep)?.wave)
+        .filter((w) => w !== null && w !== undefined)
+      if (depWaves.length === plan.depends_on.length) {
+        plan.wave = Math.max(...depWaves) + 1
+        changed = true
+      }
+    }
+  }
+
+  // Remaining unassigned (circular deps or missing refs) → wave 1
+  for (const plan of plans) {
+    if (plan.wave === null) plan.wave = 1
+  }
+}

package/get-shit-done/templates/opencode.json

@@ -10,6 +10,6 @@
     ".planning/codebase/INTEGRATIONS.md",
     ".planning/codebase/CONCERNS.md"
   ],
-  "default_agent": "executor",
+  "default_agent": "orchestrator",
   "mcp": {}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ragarciaruben",
-  "version": "1.20.26",
+  "version": "1.20.28",
   "description": "A context engineering and spec-driven development system for GitHub Copilot and OpenCode by TÂCHES.",
   "bin": {
     "get-shit-done-cc": "bin/install.js"