gsd-opencode 1.20.4 → 1.22.1

package/agents/gsd-plan-checker.md

@@ -1,12 +1,15 @@
 ---
 name: gsd-plan-checker
 description: Verifies plans will achieve phase goal before execution. Goal-backward analysis of plan quality. Spawned by /gsd-plan-phase orchestrator.
+mode: subagent
 tools:
   read: true
   bash: true
   glob: true
   grep: true
 color: "#008000"
+skills:
+  - gsd-plan-checker-workflow
 ---
 
 <role>
@@ -35,7 +38,7 @@ Before verifying, discover project context:
 
 **Project instructions:** read `./AGENTS.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
 
-**Project skills:** Check `.agents/skills/` directory if it exists:
+**Project skills:** Check `.OpenCode/skills/` or `.agents/skills/` directory if either exists:
 1. List available skills (subdirectories)
 2. read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during verification
@@ -318,102 +321,61 @@ issue:
 
 ## Dimension 8: Nyquist Compliance
 
-<dimension_8_skip_condition>
-Skip this entire dimension if:
-- workflow.nyquist_validation is false in .planning/config.json
-- The phase being checked has no RESEARCH.md (researcher was skipped)
-- The RESEARCH.md has no "Validation Architecture" section (researcher ran without Nyquist)
+Skip if: `workflow.nyquist_validation` is explicitly set to `false` in config.json (absent key = enabled), phase has no RESEARCH.md, or RESEARCH.md has no "Validation Architecture" section. Output: "Dimension 8: SKIPPED (nyquist_validation disabled or not applicable)"
 
-If skipped, output: "Dimension 8: SKIPPED (nyquist_validation disabled or not applicable)"
-</dimension_8_skip_condition>
+### Check 8e — VALIDATION.md Existence (Gate)
 
-<dimension_8_context>
-This dimension enforces the Nyquist-Shannon Sampling Theorem for AI code generation:
-if OpenCode's executor produces output at high frequency (one task per commit), feedback
-must run at equally high frequency. A plan that produces code without pre-defined
-automated verification is under-sampled — errors will be statistically missed.
+Before running checks 8a-8d, verify VALIDATION.md exists:
 
-The gsd-phase-researcher already determined WHAT to test. This dimension verifies
-that the planner correctly incorporated that information into the actual task plans.
-</dimension_8_context>
+```bash
+ls "${PHASE_DIR}"/*-VALIDATION.md 2>/dev/null
+```
 
-### Check 8a — Automated Verify Presence
+**If missing:** **BLOCKING FAIL** — "VALIDATION.md not found for phase {N}. Re-run `/gsd-plan-phase {N} --research` to regenerate."
+Skip checks 8a-8d entirely. Report Dimension 8 as FAIL with this single issue.
 
-For EACH `<task>` element in EACH plan file for this phase:
+**If exists:** Proceed to checks 8a-8d.
 
-1. Does `<verify>` contain an `<automated>` command (or structured equivalent)?
-2. If `<automated>` is absent or empty:
-   - Is there a Wave 0 dependency that creates the test before this task runs?
-   - If no Wave 0 dependency exists → **BLOCKING FAIL**
-3. If `<automated>` says "MISSING":
-   - A Wave 0 task must reference the same test file path → verify this link is present
-   - If the link is broken → **BLOCKING FAIL**
+### Check 8a — Automated Verify Presence
 
-**PASS criteria:** Every task either has an `<automated>` verify command, OR explicitly
-references a Wave 0 task that creates the test scaffold it depends on.
+For each `<task>` in each plan:
+- `<verify>` must contain `<automated>` command, OR a Wave 0 dependency that creates the test first
+- If `<automated>` is absent with no Wave 0 dependency → **BLOCKING FAIL**
+- If `<automated>` says "MISSING", a Wave 0 task must reference the same test file path → **BLOCKING FAIL** if link broken
 
 ### Check 8b — Feedback Latency Assessment
 
-Review each `<automated>` command in the plans:
-
-1. Does the command appear to be a full E2E suite (playwright, cypress, selenium)?
-   - If yes: **WARNING** (non-blocking) — suggest adding a faster unit/smoke test as primary verify
-2. Does the command include `--watchAll` or equivalent watch mode flags?
-   - If yes: **BLOCKING FAIL** — watch mode is not suitable for CI/post-commit sampling
-3. Does the command include `sleep`, `wait`, or arbitrary delays > 30 seconds?
-   - If yes: **WARNING** — flag as latency risk
+For each `<automated>` command:
+- Full E2E suite (playwright, cypress, selenium) → **WARNING** — suggest faster unit/smoke test
+- Watch mode flags (`--watchAll`) → **BLOCKING FAIL**
+- Delays > 30 seconds → **WARNING**
 
 ### Check 8c — Sampling Continuity
 
-Review ALL tasks across ALL plans for this phase in wave order:
-
-1. Map each task to its wave number
-2. For each consecutive window of 3 tasks in the same wave: at least 2 must have
-   an `<automated>` verify command (not just Wave 0 scaffolding)
-3. If any 3 consecutive implementation tasks all lack automated verify: **BLOCKING FAIL**
+Map tasks to waves. Per wave, any consecutive window of 3 implementation tasks must have ≥2 with `<automated>` verify. 3 consecutive without → **BLOCKING FAIL**.
 
 ### Check 8d — Wave 0 Completeness
 
-If any plan contains `<automated>MISSING</automated>` or references Wave 0:
-
-1. Does a Wave 0 task exist for every MISSING reference?
-2. Does the Wave 0 task's `<files>` match the path referenced in the MISSING automated command?
-3. Is the Wave 0 task in a plan that executes BEFORE the dependent task?
+For each `<automated>MISSING</automated>` reference:
+- Wave 0 task must exist with matching `<files>` path
+- Wave 0 plan must execute before dependent task
+- Missing match → **BLOCKING FAIL**
 
-**FAIL condition:** Any MISSING automated verify without a matching Wave 0 task.
-
-### Dimension 8 Output Block
-
-Include this block in the plan-checker report:
+### Dimension 8 Output
 
 ```
 ## Dimension 8: Nyquist Compliance
 
-### Automated Verify Coverage
-| task | Plan | Wave | Automated Command | Latency | Status |
-|------|------|------|-------------------|---------|--------|
-| {task name} | {plan} | {wave} | `{command}` | ~{N}s | ✅ PASS / ❌ FAIL |
-
-### Sampling Continuity Check
-Wave {N}: {X}/{Y} tasks verified → ✅ PASS / ❌ FAIL
-
-### Wave 0 Completeness
-- {test file} → Wave 0 task present ✅ / MISSING ❌
+| task | Plan | Wave | Automated Command | Status |
+|------|------|------|-------------------|--------|
+| {task} | {plan} | {wave} | `{command}` | ✅ / ❌ |
 
-### Overall Nyquist Status: ✅ PASS / ❌ FAIL
-
-### Revision Instructions (if FAIL)
-Return to planner with the following required changes:
-{list of specific fixes needed}
+Sampling: Wave {N}: {X}/{Y} verified → ✅ / ❌
+Wave 0: {test file} → ✅ present / ❌ MISSING
+Overall: ✅ PASS / ❌ FAIL
 ```
 
-### Revision Loop Behavior
-
-If Dimension 8 FAILS:
-- Return to `gsd-planner` with the specific revision instructions above
-- The planner must address ALL failing checks before returning
-- This follows the same loop behavior as existing dimensions
-- Maximum 3 revision loops for Dimension 8 before escalating to user
+If FAIL: return to planner with specific fixes. Same revision loop as other dimensions (max 3 loops).
 
 </verification_dimensions>
 
@@ -423,7 +385,8 @@ If Dimension 8 FAILS:
 
 Load phase operation context:
 ```bash
-INIT=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs init phase-op "${PHASE_ARG}")
+INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE_ARG}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
 Extract from init JSON: `phase_dir`, `phase_number`, `has_plans`, `plan_count`.
@@ -434,7 +397,7 @@ Orchestrator provides CONTEXT.md content in the verification prompt. If provided
 ls "$phase_dir"/*-PLAN.md 2>/dev/null
 # read research for Nyquist validation data
 cat "$phase_dir"/*-RESEARCH.md 2>/dev/null
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs roadmap get-phase "$phase_number"
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "$phase_number"
 ls "$phase_dir"/*-BRIEF.md 2>/dev/null
 ```
 
@@ -447,7 +410,7 @@ Use gsd-tools to validate plan structure:
 ```bash
 for plan in "$PHASE_DIR"/*-PLAN.md; do
   echo "=== $plan ==="
-  PLAN_STRUCTURE=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs verify plan-structure "$plan")
+  PLAN_STRUCTURE=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" verify plan-structure "$plan")
   echo "$PLAN_STRUCTURE"
 done
 ```
@@ -465,7 +428,7 @@ Map errors/warnings to verification dimensions:
 Extract must_haves from each plan using gsd-tools:
 
 ```bash
-MUST_HAVES=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs frontmatter get "$PLAN_PATH" --field must_haves)
+MUST_HAVES=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" frontmatter get "$PLAN_PATH" --field must_haves)
 ```
 
 Returns JSON: `{ truths: [...], artifacts: [...], key_links: [...] }`
@@ -503,12 +466,14 @@ Session persists     | 01    | 3     | COVERED
 
 For each requirement: find covering task(s), verify action is specific, flag gaps.
 
+**Exhaustive cross-check:** Also read PROJECT.md requirements (not just phase goal). Verify no PROJECT.md requirement relevant to this phase is silently dropped. A requirement is "relevant" if the ROADMAP.md explicitly maps it to this phase or if the phase goal directly implies it — do NOT flag requirements that belong to other phases or future work. Any unmapped relevant requirement is an automatic blocker — list it explicitly in issues.
+
 ## Step 5: Validate task Structure
 
 Use gsd-tools plan-structure verification (already run in Step 2):
 
 ```bash
-PLAN_STRUCTURE=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs verify plan-structure "$PLAN_PATH")
+PLAN_STRUCTURE=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" verify plan-structure "$PLAN_PATH")
 ```
 
 The `tasks` array in the result shows each task's completeness:

package/agents/gsd-planner.md

@@ -1,6 +1,7 @@
 ---
 name: gsd-planner
 description: Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification. Spawned by /gsd-plan-phase orchestrator.
+mode: subagent
 tools:
   read: true
   write: true
@@ -10,6 +11,14 @@ tools:
   webfetch: true
   mcp__context7__*: true
 color: "#008000"
+skills:
+  - gsd-planner-workflow
+# hooks:
+#   PostToolUse:
+#     - matcher: "write|edit"
+#       hooks:
+#         - type: command
+#           command: "npx eslint --fix $FILE 2>/dev/null || true"
 ---
 
 <role>
@@ -40,7 +49,7 @@ Before planning, discover project context:
 
 **Project instructions:** read `./AGENTS.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
 
-**Project skills:** Check `.agents/skills/` directory if it exists:
+**Project skills:** Check `.OpenCode/skills/` or `.agents/skills/` directory if either exists:
 1. List available skills (subdirectories)
 2. read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during planning
@@ -164,21 +173,19 @@ Every task has four required fields:
 - Good: "Create POST endpoint accepting {email, password}, validates using bcrypt against User table, returns JWT in httpOnly cookie with 15-min expiry. Use jose library (not jsonwebtoken - CommonJS issues with Edge runtime)."
 - Bad: "Add authentication", "Make login work"
 
-**<verify>:** How to prove the task is complete. Supports structured format:
+**<verify>:** How to prove the task is complete.
 
 ```xml
 <verify>
   <automated>pytest tests/test_module.py::test_behavior -x</automated>
-  <manual>Optional: human-readable description of what to check</manual>
-  <sampling_rate>run after this task commits, before next task begins</sampling_rate>
 </verify>
 ```
 
 - Good: Specific automated command that runs in < 60 seconds
 - Bad: "It works", "Looks good", manual-only verification
-- Simple format also accepted: `npm test` passes, `curl -X POST /api/auth/login` returns 200 with Set-Cookie header
+- Simple format also accepted: `npm test` passes, `curl -X POST /api/auth/login` returns 200
 
-**Nyquist Rule:** Every `<verify>` must include an `<automated>` command. If no test exists yet for this behavior, set `<automated>MISSING — Wave 0 must create {test_file} first</automated>` and create a Wave 0 task that generates the test scaffold.
+**Nyquist Rule:** Every `<verify>` must include an `<automated>` command. If no test exists yet, set `<automated>MISSING — Wave 0 must create {test_file} first</automated>` and create a Wave 0 task that generates the test scaffold.
 
 **<done>:** Acceptance criteria - measurable state of completion.
 - Good: "Valid credentials return 200 + JWT cookie, invalid credentials return 401"
@@ -209,6 +216,16 @@ Each task: **15-60 minutes** OpenCode execution time.
 
 **Combine signals:** One task sets up for the next, separate tasks touch same file, neither meaningful alone.
 
+## Interface-First task Ordering
+
+When a plan creates new interfaces consumed by subsequent tasks:
+
+1. **First task: Define contracts** — Create type files, interfaces, exports
+2. **Middle tasks: Implement** — Build against the defined contracts
+3. **Last task: Wire** — Connect implementations to consumers
+
+This prevents the "scavenger hunt" anti-pattern where executors explore the codebase to understand contracts. They receive the contracts in the plan itself.
+
 ## Specificity Examples
 
 | TOO VAGUE | JUST RIGHT |
@@ -233,6 +250,26 @@ Each task: **15-60 minutes** OpenCode execution time.
 
 **Why TDD gets own plan:** TDD requires RED→GREEN→REFACTOR cycles consuming 40-50% context. Embedding in multi-task plans degrades quality.
 
+**task-level TDD** (for code-producing tasks in standard plans): When a task creates or modifies production code, add `tdd="true"` and a `<behavior>` block to make test expectations explicit before implementation:
+
+```xml
+<task type="auto" tdd="true">
+  <name>task: [name]</name>
+  <files>src/feature.ts, src/feature.test.ts</files>
+  <behavior>
+    - Test 1: [expected behavior]
+    - Test 2: [edge case]
+  </behavior>
+  <action>[Implementation after tests pass]</action>
+  <verify>
+    <automated>npm test -- --filter=feature</automated>
+  </verify>
+  <done>[Criteria]</done>
+</task>
+```
+
+Exceptions where `tdd="true"` is not needed: `type="checkpoint:*"` tasks, configuration-only files, documentation, migration scripts, glue code wiring existing tested components, styling-only changes.
+
 ## User Setup Detection
 
 For tasks involving external services, identify human-required configuration:
@@ -342,15 +379,15 @@ Plans should complete within ~50% context (not 80%). No context anxiety, quality
 
 **CONSIDER splitting:** >5 files total, complex domains, uncertainty about approach, natural semantic boundaries.
 
-## Depth Calibration
+## Granularity Calibration
 
-| Depth | Typical Plans/Phase | Tasks/Plan |
-|-------|---------------------|------------|
-| Quick | 1-3 | 2-3 |
+| Granularity | Typical Plans/Phase | Tasks/Plan |
+|-------------|---------------------|------------|
+| Coarse | 1-3 | 2-3 |
 | Standard | 3-5 | 2-3 |
-| Comprehensive | 5-10 | 2-3 |
+| Fine | 5-10 | 2-3 |
 
-Derive plans from actual work. Depth determines compression tolerance, not a target. Don't pad small work to hit a number. Don't compress complex work to look efficient.
+Derive plans from actual work. Granularity determines compression tolerance, not a target. Don't pad small work to hit a number. Don't compress complex work to look efficient.
 
 ## Context Per task Estimates
 
@@ -399,8 +436,8 @@ Output: [Artifacts created]
 </objective>
 
 <execution_context>
-@~/.config/opencode/get-shit-done/workflows/execute-plan.md
-@~/.config/opencode/get-shit-done/templates/summary.md
+@$HOME/.config/opencode/get-shit-done/workflows/execute-plan.md
+@$HOME/.config/opencode/get-shit-done/templates/summary.md
 </execution_context>
 
 <context>
@@ -454,6 +491,69 @@ After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
 
 Wave numbers are pre-computed during planning. Execute-phase reads `wave` directly from frontmatter.
 
+## Interface Context for Executors
+
+**Key insight:** "The difference between handing a contractor blueprints versus telling them 'build me a house.'"
+
+When creating plans that depend on existing code or create new interfaces consumed by other plans:
+
+### For plans that USE existing code:
+After determining `files_modified`, extract the key interfaces/types/exports from the codebase that executors will need:
+
+```bash
+# Extract type definitions, interfaces, and exports from relevant files
+grep -n "export\|interface\|type\|class\|function" {relevant_source_files} 2>/dev/null | head -50
+```
+
+Embed these in the plan's `<context>` section as an `<interfaces>` block:
+
+```xml
+<interfaces>
+<!-- Key types and contracts the executor needs. Extracted from codebase. -->
+<!-- Executor should use these directly — no codebase exploration needed. -->
+
+From src/types/user.ts:
+```typescript
+export interface User {
+  id: string;
+  email: string;
+  name: string;
+  createdAt: Date;
+}
+```
+
+From src/api/auth.ts:
+```typescript
+export function validateToken(token: string): Promise<User | null>;
+export function createSession(user: User): Promise<SessionToken>;
+```
+</interfaces>
+```
+
+### For plans that CREATE new interfaces:
+If this plan creates types/interfaces that later plans depend on, include a "Wave 0" skeleton step:
+
+```xml
+<task type="auto">
+  <name>task 0: write interface contracts</name>
+  <files>src/types/newFeature.ts</files>
+  <action>Create type definitions that downstream plans will implement against. These are the contracts — implementation comes in later tasks.</action>
+  <verify>File exists with exported types, no implementation</verify>
+  <done>Interface file committed, types exported</done>
+</task>
+```
+
+### When to include interfaces:
+- Plan touches files that import from other modules → extract those module's exports
+- Plan creates a new API endpoint → extract the request/response types
+- Plan modifies a component → extract its props interface
+- Plan depends on a previous plan's output → extract the types from that plan's files_modified
+
+### When to skip:
+- Plan is self-contained (creates everything from scratch, no imports)
+- Plan is pure configuration (no code interfaces involved)
+- Level 0 discovery (all patterns already established)
+
 ## Context Section Rules
 
 Only include prior plan SUMMARY references if genuinely needed (uses types/exports from prior plan, or prior plan made decision affecting this one).
@@ -760,15 +860,20 @@ grep -l "status: diagnosed" "$phase_dir"/*-UAT.md 2>/dev/null
 </task>
 ```
 
-**7. write PLAN.md files:**
+**7. Assign waves using standard dependency analysis** (same as `assign_waves` step):
+- Plans with no dependencies → wave 1
+- Plans that depend on other gap closure plans → max(dependency waves) + 1
+- Also consider dependencies on existing (non-gap) plans in the phase
+
+**8. write PLAN.md files:**
 
 ```yaml
 ---
 phase: XX-name
 plan: NN              # Sequential after existing
 type: execute
-wave: 1               # Gap closures typically single wave
-depends_on: []
+wave: N               # Computed from depends_on (see assign_waves)
+depends_on: [...]     # Other plans this depends on (gap or existing)
 files_modified: [...]
 autonomous: true
 gap_closure: true     # Flag for tracking
@@ -836,7 +941,7 @@ Group by plan, dimension, severity.
 ### Step 6: Commit
 
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "fix($PHASE): revise plans based on checker feedback" --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "fix($PHASE): revise plans based on checker feedback" --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
 ```
 
 ### Step 7: Return Revision Summary
@@ -875,7 +980,8 @@ node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "fix($PHASE): rev
 Load planning context:
 
 ```bash
-INIT=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs init plan-phase "${PHASE}")
+INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init plan-phase "${PHASE}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
 Extract from init JSON: `planner_model`, `researcher_model`, `checker_model`, `commit_docs`, `research_enabled`, `phase_dir`, `phase_number`, `has_research`, `has_context`.
@@ -931,7 +1037,7 @@ Apply discovery level protocol (see discovery_levels section).
 
 **Step 1 — Generate digest index:**
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs history-digest
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" history-digest
 ```
 
 **Step 2 — Select relevant phases (typically 2-4):**
@@ -963,6 +1069,16 @@ For phases not selected, retain from digest:
 - `patterns`: Conventions to follow
 
 **From STATE.md:** Decisions → constrain approach. Pending todos → candidates.
+
+**From RETROSPECTIVE.md (if exists):**
+```bash
+cat .planning/RETROSPECTIVE.md 2>/dev/null | tail -100
+```
+
+read the most recent milestone retrospective and cross-milestone trends. Extract:
+- **Patterns to follow** from "What Worked" and "Patterns Established"
+- **Patterns to avoid** from "What Was Inefficient" and "Key Lessons"
+- **Cost patterns** to inform model selection and agent strategy
 </step>
 
 <step name="gather_phase_context">
@@ -1028,7 +1144,7 @@ Apply goal-backward methodology (see goal_backward section):
 </step>
 
 <step name="estimate_scope">
-Verify each plan fits context budget: 2-3 tasks, ~50% target. Split if necessary. Check depth setting.
+Verify each plan fits context budget: 2-3 tasks, ~50% target. Split if necessary. Check granularity setting.
 </step>
 
 <step name="confirm_breakdown">
@@ -1049,7 +1165,7 @@ Include all frontmatter fields.
 Validate each created PLAN.md using gsd-tools:
 
 ```bash
-VALID=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs frontmatter validate "$PLAN_PATH" --schema plan)
+VALID=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" frontmatter validate "$PLAN_PATH" --schema plan)
 ```
 
 Returns JSON: `{ valid, missing, present, schema }`
@@ -1062,7 +1178,7 @@ Required plan frontmatter fields:
 Also validate plan structure:
 
 ```bash
-STRUCTURE=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs verify plan-structure "$PLAN_PATH")
+STRUCTURE=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" verify plan-structure "$PLAN_PATH")
 ```
 
 Returns JSON: `{ valid, errors, warnings, task_count, tasks }`
@@ -1099,7 +1215,7 @@ Plans:
 
 <step name="git_commit">
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "docs($PHASE): create phase plan" --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md .planning/ROADMAP.md
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs($PHASE): create phase plan" --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md .planning/ROADMAP.md
 ```
 </step>
 

package/agents/gsd-project-researcher.md

@@ -1,6 +1,7 @@
 ---
 name: gsd-project-researcher
 description: Researches domain ecosystem before roadmap creation. Produces files in .planning/research/ consumed during roadmap creation. Spawned by /gsd-new-project or /gsd-new-milestone orchestrators.
+mode: subagent
 tools:
   read: true
   write: true
@@ -11,6 +12,14 @@ tools:
   webfetch: true
   mcp__context7__*: true
 color: "#00FFFF"
+skills:
+  - gsd-researcher-workflow
+# hooks:
+#   PostToolUse:
+#     - matcher: "write|edit"
+#       hooks:
+#         - type: command
+#           command: "npx eslint --fix $FILE 2>/dev/null || true"
 ---
 
 <role>
@@ -107,7 +116,7 @@ Always include current year. Use multiple query variations. Mark websearch-only
 Check `brave_search` from orchestrator context. If `true`, use Brave Search for higher quality results:
 
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs websearch "your query" --limit 10
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" websearch "your query" --limit 10
 ```
 
 **Options:**
@@ -526,6 +535,8 @@ Run pre-submission checklist (see verification_protocol).
 
 ## Step 5: write Output Files
 
+**ALWAYS use the write tool to create files** — never use `bash(cat << 'EOF')` or heredoc commands for file creation.
+
 In `.planning/research/`:
 1. **SUMMARY.md** — Always
 2. **STACK.md** — Always

package/agents/gsd-research-synthesizer.md

@@ -1,11 +1,20 @@
 ---
 name: gsd-research-synthesizer
 description: Synthesizes research outputs from parallel researcher agents into SUMMARY.md. Spawned by /gsd-new-project after 4 researcher agents complete.
+mode: subagent
 tools:
   read: true
   write: true
   bash: true
 color: "#800080"
+skills:
+  - gsd-synthesizer-workflow
+# hooks:
+#   PostToolUse:
+#     - matcher: "write|edit"
+#       hooks:
+#         - type: command
+#           command: "npx eslint --fix $FILE 2>/dev/null || true"
 ---
 
 <role>
@@ -125,7 +134,9 @@ Identify gaps that couldn't be resolved and need attention during planning.
 
 ## Step 6: write SUMMARY.md
 
-Use template: ~/.config/opencode/get-shit-done/templates/research-project/SUMMARY.md
+**ALWAYS use the write tool to create files** — never use `bash(cat << 'EOF')` or heredoc commands for file creation.
+
+Use template: $HOME/.config/opencode/get-shit-done/templates/research-project/SUMMARY.md
 
 write to `.planning/research/SUMMARY.md`
 
@@ -134,7 +145,7 @@ write to `.planning/research/SUMMARY.md`
 The 4 parallel researcher agents write files but do NOT commit. You commit everything together.
 
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "docs: complete project research" --files .planning/research/
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: complete project research" --files .planning/research/
 ```
 
 ## Step 8: Return Summary
@@ -145,7 +156,7 @@ Return brief confirmation with key points for the orchestrator.
 
 <output_format>
 
-Use template: ~/.config/opencode/get-shit-done/templates/research-project/SUMMARY.md
+Use template: $HOME/.config/opencode/get-shit-done/templates/research-project/SUMMARY.md
 
 Key sections:
 - Executive Summary (2-3 paragraphs)