gsd-opencode 1.20.3 → 1.22.0

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

@@ -6,7 +6,7 @@ Execute a phase prompt (PLAN.md) and create the outcome summary (SUMMARY.md).
 read STATE.md before any operation to load project context.
 read config.json for planning behavior settings.
 
-@~/.config/opencode/get-shit-done/references/git-integration.md
+@$HOME/.config/opencode/get-shit-done/references/git-integration.md
 </required_reading>
 
 <process>
@@ -15,7 +15,8 @@ read config.json for planning behavior settings.
 Load execution context (paths only to minimize orchestrator context):
 
 ```bash
-INIT=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs init execute-phase "${PHASE}")
+INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init execute-phase "${PHASE}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
 Extract from init JSON: `executor_model`, `commit_docs`, `phase_dir`, `phase_number`, `plans`, `summaries`, `incomplete_plans`, `state_path`, `config_path`.
@@ -118,11 +119,13 @@ Pattern B only (verify-only checkpoints). Skip for A/C.
 cat .planning/phases/XX-name/{phase}-{plan}-PLAN.md
 ```
 This IS the execution instructions. Follow exactly. If plan references CONTEXT.md: honor user's vision throughout.
+
+**If plan contains `<interfaces>` block:** These are pre-extracted type definitions and contracts. Use them directly — do NOT re-read the source files to discover types. The planner already extracted what you need.
 </step>
 
 <step name="previous_phase_check">
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs phases list --type summaries --raw
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" phases list --type summaries --raw
 # Extract the second-to-last summary from the JSON result
 ```
 If previous SUMMARY has unresolved "Issues Encountered" or "Next Phase Readiness" blockers: question(header="Previous Issues", options: "Proceed anyway" | "Address first" | "Review previous").
@@ -220,7 +223,7 @@ For `type: tdd` plans — RED-GREEN-REFACTOR:
 
 Errors: RED doesn't fail → investigate test/existing feature. GREEN doesn't pass → debug, iterate. REFACTOR breaks → undo.
 
-See `~/.config/opencode/get-shit-done/references/tdd.md` for structure.
+See `$HOME/.config/opencode/get-shit-done/references/tdd.md` for structure.
 </tdd_plan_execution>
 
 <task_commit>
@@ -272,7 +275,7 @@ Display: `CHECKPOINT: [Type]` box → Progress {X}/{Y} → task name → type-sp
 
 After response: verify if specified. Pass → continue. Fail → inform, wait. WAIT for user — do NOT hallucinate completion.
 
-See ~/.config/opencode/get-shit-done/references/checkpoints.md for details.
+See $HOME/.config/opencode/get-shit-done/references/checkpoints.md for details.
 </step>
 
 <step name="checkpoint_return_for_orchestrator">
@@ -310,11 +313,11 @@ fi
 grep -A 50 "^user_setup:" .planning/phases/XX-name/{phase}-{plan}-PLAN.md | head -50
 ```
 
-If user_setup exists: create `{phase}-USER-SETUP.md` using template `~/.config/opencode/get-shit-done/templates/user-setup.md`. Per service: env vars table, account setup checklist, dashboard config, local dev notes, verification commands. Status "Incomplete". Set `USER_SETUP_CREATED=true`. If empty/missing: skip.
+If user_setup exists: create `{phase}-USER-SETUP.md` using template `$HOME/.config/opencode/get-shit-done/templates/user-setup.md`. Per service: env vars table, account setup checklist, dashboard config, local dev notes, verification commands. Status "Incomplete". Set `USER_SETUP_CREATED=true`. If empty/missing: skip.
 </step>
 
 <step name="create_summary">
-Create `{phase}-{plan}-SUMMARY.md` at `.planning/phases/XX-name/`. Use `~/.config/opencode/get-shit-done/templates/summary.md`.
+Create `{phase}-{plan}-SUMMARY.md` at `.planning/phases/XX-name/`. Use `$HOME/.config/opencode/get-shit-done/templates/summary.md`.
 
 **Frontmatter:** phase, plan, subsystem, tags | requires/provides/affects | tech-stack.added/patterns | key-files.created/modified | key-decisions | requirements-completed (**MUST** copy `requirements` array from PLAN.md frontmatter verbatim) | duration ($DURATION), completed ($PLAN_END_TIME date).
 
@@ -332,13 +335,13 @@ Update STATE.md using gsd-tools:
 
 ```bash
 # Advance plan counter (handles last-plan edge case)
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs state advance-plan
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" state advance-plan
 
 # Recalculate progress bar from disk state
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs state update-progress
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" state update-progress
 
 # Record execution metrics
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs state record-metric \
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" state record-metric \
   --phase "${PHASE}" --plan "${PLAN}" --duration "${DURATION}" \
   --tasks "${TASK_COUNT}" --files "${FILE_COUNT}"
 ```
@@ -349,11 +352,12 @@ From SUMMARY: Extract decisions and add to STATE.md:
 
 ```bash
 # Add each decision from SUMMARY key-decisions
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs state add-decision \
-  --phase "${PHASE}" --summary "${DECISION_TEXT}" --rationale "${RATIONALE}"
+# Prefer file inputs for shell-safe text (preserves `$`, `*`, etc. exactly)
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" state add-decision \
+  --phase "${PHASE}" --summary-file "${DECISION_TEXT_FILE}" --rationale-file "${RATIONALE_FILE}"
 
 # Add blockers if any found
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs state add-blocker "Blocker description"
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" state add-blocker --text-file "${BLOCKER_TEXT_FILE}"
 ```
 </step>
 
@@ -361,7 +365,7 @@ node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs state add-blocker "Block
 Update session info using gsd-tools:
 
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs state record-session \
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" state record-session \
   --stopped-at "Completed ${PHASE}-${PLAN}-PLAN.md" \
   --resume-file "None"
 ```
@@ -375,7 +379,7 @@ If SUMMARY "Issues Encountered" ≠ "None": yolo → log and continue. Interacti
 
 <step name="update_roadmap">
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs roadmap update-plan-progress "${PHASE}"
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap update-plan-progress "${PHASE}"
 ```
 Counts PLAN vs SUMMARY files on disk. Updates progress table row with correct count and status (`In Progress` or `Complete` with date).
 </step>
@@ -384,7 +388,7 @@ Counts PLAN vs SUMMARY files on disk. Updates progress table row with correct co
 Mark completed requirements from the PLAN.md frontmatter `requirements:` field:
 
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs requirements mark-complete ${REQ_IDS}
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" requirements mark-complete ${REQ_IDS}
 ```
 
 Extract requirement IDs from the plan's frontmatter (e.g., `requirements: [AUTH-01, AUTH-02]`). If no requirements field, skip.
@@ -394,7 +398,7 @@ Extract requirement IDs from the plan's frontmatter (e.g., `requirements: [AUTH-
 task code already committed per-task. Commit plan metadata:
 
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md .planning/REQUIREMENTS.md
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md .planning/REQUIREMENTS.md
 ```
 </step>
 
@@ -409,7 +413,7 @@ git diff --name-only ${FIRST_TASK}^..HEAD 2>/dev/null
 Update only structural changes: new src/ dir → STRUCTURE.md | deps → STACK.md | file pattern → CONVENTIONS.md | API client → INTEGRATIONS.md | config → STACK.md | renamed → update paths. Skip code-only/bugfix/content changes.
 
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "" --files .planning/codebase/*.md --amend
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "" --files .planning/codebase/*.md --amend
 ```
 </step>
 

package/get-shit-done/workflows/health.md

@@ -25,7 +25,7 @@ fi
 **Run health validation:**
 
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs validate health $REPAIR_FLAG
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" validate health $REPAIR_FLAG
 ```
 
 Parse JSON output:
@@ -112,7 +112,7 @@ If yes, re-run with --repair flag and display results.
 Re-run health check without --repair to confirm issues are resolved:
 
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs validate health
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" validate health
 ```
 
 Report final status.
@@ -136,6 +136,8 @@ Report final status.
 | W005 | warning | Phase directory naming mismatch | No |
 | W006 | warning | Phase in ROADMAP but no directory | No |
 | W007 | warning | Phase on disk but not in ROADMAP | No |
+| W008 | warning | config.json: workflow.nyquist_validation absent (defaults to enabled but agents may skip) | Yes |
+| W009 | warning | Phase has Validation Architecture in RESEARCH.md but no VALIDATION.md | No |
 | I001 | info | Plan without SUMMARY (may be in progress) | No |
 
 </error_codes>
@@ -147,6 +149,7 @@ Report final status.
 | createConfig | Create config.json with defaults | None |
 | resetConfig | Delete + recreate config.json | Loses custom settings |
 | regenerateState | Create STATE.md from ROADMAP structure | Loses session history |
+| addNyquistKey | Add workflow.nyquist_validation: true to config.json | None — matches existing default |
 
 **Not repairable (too risky):**
 - PROJECT.md, ROADMAP.md content

package/get-shit-done/workflows/help.md

@@ -99,6 +99,8 @@ Create detailed execution plan for a specific phase.
 Usage: `/gsd-plan-phase 1`
 Result: Creates `.planning/phases/01-foundation/01-01-PLAN.md`
 
+**PRD Express Path:** Pass `--prd path/to/requirements.md` to skip discuss-phase entirely. Your PRD becomes locked decisions in CONTEXT.md. Useful when you already have clear acceptance criteria.
+
 ### Execution
 
 **`/gsd-execute-phase <phase-number>`**
@@ -296,7 +298,7 @@ Usage: `/gsd-plan-milestone-gaps`
 Configure workflow toggles and model profile interactively.
 
 - Toggle researcher, plan checker, verifier agents
-- Select model profile (simple/smart/custom)
+- Select model profile (simple/smart/genius)
 - Updates `.planning/config.json`
 
 Usage: `/gsd-settings`
@@ -351,6 +353,7 @@ Usage: `/gsd-join-discord`
 ├── PROJECT.md            # Project vision
 ├── ROADMAP.md            # Current phase breakdown
 ├── STATE.md              # Project memory & context
+├── RETROSPECTIVE.md      # Living retrospective (updated per milestone)
 ├── config.json           # Workflow mode & gates
 ├── todos/                # Captured ideas and tasks
 │   ├── pending/          # Todos waiting to be worked on

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

@@ -34,7 +34,8 @@ Validate first argument is an integer.
 Load phase operation context:
 
 ```bash
-INIT=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs init phase-op "${after_phase}")
+INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init phase-op "${after_phase}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
 Check `roadmap_exists` from init JSON. If false:
@@ -48,7 +49,7 @@ Exit.
 **Delegate the phase insertion to gsd-tools:**
 
 ```bash
-RESULT=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs phase insert "${after_phase}" "${description}")
+RESULT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" phase insert "${after_phase}" "${description}")
 ```
 
 The CLI handles:

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

@@ -26,7 +26,8 @@ Documents are reference material for OpenCode when planning/executing. Always in
 Load codebase mapping context:
 
 ```bash
-INIT=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs init map-codebase)
+INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init map-codebase)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
 Extract from init JSON: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`.
@@ -250,7 +251,7 @@ Continue to commit_codebase_map.
 Commit the codebase map:
 
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "docs: map existing codebase" --files .planning/codebase/*.md
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: map existing codebase" --files .planning/codebase/*.md
 ```
 
 Continue to offer_next.

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

@@ -27,8 +27,9 @@ read all files referenced by the invoking prompt's execution_context before star
 
 **If no context file:**
 - Present what shipped in last milestone
-- Ask: "What do you want to build next?"
-- Use question to explore features, priorities, constraints, scope
+- Ask inline (freeform, NOT question): "What do you want to build next?"
+- Wait for their response, then use question to probe specifics
+- If user selects "Other" at any point to provide freeform input, ask follow-up as plain text — not another question
 
 ## 3. Determine Milestone Version
 
@@ -71,13 +72,14 @@ Keep Accumulated Context section from previous milestone.
 Delete MILESTONE-CONTEXT.md if exists (consumed).
 
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "docs: start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md
 ```
 
 ## 7. Load Context and Resolve Models
 
 ```bash
-INIT=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs init new-milestone)
+INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init new-milestone)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
 Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`.
@@ -92,10 +94,10 @@ question: "Research the domain ecosystem for new features before defining requir
 
 ```bash
 # If "Research first": persist true
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs config-set workflow.research true
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-set workflow.research true
 
 # If "Skip research": persist false
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs config-set workflow.research false
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-set workflow.research false
 ```
 
 **If "Research first":**
@@ -138,7 +140,7 @@ Focus ONLY on what's needed for the NEW features.
 
 <output>
 write to: .planning/research/{FILE}
-Use template: ~/.config/opencode/get-shit-done/templates/research-project/{FILE}
+Use template: $HOME/.config/opencode/get-shit-done/templates/research-project/{FILE}
 </output>
 ", subagent_type="gsd-project-researcher", model="{researcher_model}", description="{DIMENSION} research")
 ```
@@ -167,7 +169,7 @@ Synthesize research outputs into SUMMARY.md.
 </files_to_read>
 
 write to: .planning/research/SUMMARY.md
-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
 Commit after writing.
 ", subagent_type="gsd-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
 ```
@@ -253,7 +255,7 @@ If "adjust": Return to scoping.
 
 **Commit requirements:**
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "docs: define milestone v[X.Y] requirements" --files .planning/REQUIREMENTS.md
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: define milestone v[X.Y] requirements" --files .planning/REQUIREMENTS.md
 ```
 
 ## 10. Create Roadmap
@@ -330,7 +332,7 @@ Success criteria:
 
 **Commit roadmap** (after approval):
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
 ```
 
 ## 11. Done

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

@@ -14,7 +14,7 @@ Check if `--auto` flag is present in $ARGUMENTS.
 **If auto mode:**
 - Skip brownfield mapping offer (assume greenfield)
 - Skip deep questioning (extract context from provided document)
-- Config: YOLO mode is implicit (skip that question), but ask depth/git/agents FIRST (Step 2a)
+- Config: YOLO mode is implicit (skip that question), but ask granularity/git/agents FIRST (Step 2a)
 - After config: run Steps 6-9 automatically with smart defaults:
   - Research: Always yes
   - Requirements: Include all table stakes + features from provided document
@@ -46,7 +46,8 @@ The document should describe what you want to build.
 **MANDATORY FIRST STEP — Execute these checks before ANY user interaction:**
 
 ```bash
-INIT=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs init new-project)
+INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init new-project)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
 Parse JSON for: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `project_exists`, `has_codebase_map`, `planning_exists`, `has_existing_code`, `has_package_file`, `is_brownfield`, `needs_codebase_map`, `has_git`, `project_path`.
@@ -90,13 +91,13 @@ YOLO mode is implicit (auto = YOLO). Ask remaining config questions:
 ```
 question([
   {
-    header: "Depth",
-    question: "How thorough should planning be?",
+    header: "Granularity",
+    question: "How finely should scope be sliced into phases?",
     multiSelect: false,
     options: [
-      { label: "Quick (Recommended)", description: "Ship fast (3-5 phases, 1-3 plans each)" },
-      { label: "Standard", description: "Balanced scope and speed (5-8 phases, 3-5 plans each)" },
-      { label: "Comprehensive", description: "Thorough coverage (8-12 phases, 5-10 plans each)" }
+      { label: "Coarse (Recommended)", description: "Fewer, broader phases (3-5 phases, 1-3 plans each)" },
+      { label: "Standard", description: "Balanced phase size (5-8 phases, 3-5 plans each)" },
+      { label: "Fine", description: "Many focused phases (8-12 phases, 5-10 plans each)" }
     ]
   },
   {
@@ -158,7 +159,7 @@ question([
     options: [
       { label: "Smart (Recommended)", description: "Two models: one for reseach and planing, other for execution and verification" },
       { label: "Simple", description: Description: "One model for all agents (not flexible)" },
-      { label: "Custom (most flexible)", description: "Three models: different for every stage" }
+      { label: "Genius (most flexible)", description: "Three models: different for every stage" }
     ]
   }
 ])
@@ -169,14 +170,15 @@ Create `.planning/config.json` with mode set to "yolo":
 ```json
 {
   "mode": "yolo",
-  "depth": "[selected]",
+  "granularity": "[selected]",
   "parallelization": true|false,
   "commit_docs": true|false,
-  "model_profile": "simple|smart|custom",
+  "model_profile": "simple|smart|genius",
   "workflow": {
     "research": true|false,
     "plan_check": true|false,
     "verifier": true|false,
+    "nyquist_validation": depth !== "quick",
     "auto_advance": true
   }
 }
@@ -188,13 +190,13 @@ Create `.planning/config.json` with mode set to "yolo":
 
 ```bash
 mkdir -p .planning
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "chore: add project config" --files .planning/config.json
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "chore: add project config" --files .planning/config.json
 ```
 
-**Persist auto-advance to config (survives context compaction):**
+**Persist auto-advance chain flag to config (survives context compaction):**
 
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs config-set workflow.auto_advance true
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-set workflow._auto_chain_active true
 ```
 
 Proceed to Step 4 (skip Steps 3 and 5).
@@ -338,7 +340,7 @@ Do not compress. Capture everything gathered.
 
 ```bash
 mkdir -p .planning
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "docs: initialize project" --files .planning/PROJECT.md
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: initialize project" --files .planning/PROJECT.md
 ```
 
 ## 5. Workflow Preferences
@@ -379,13 +381,13 @@ questions: [
     ]
   },
   {
-    header: "Depth",
-    question: "How thorough should planning be?",
+    header: "Granularity",
+    question: "How finely should scope be sliced into phases?",
     multiSelect: false,
     options: [
-      { label: "Quick", description: "Ship fast (3-5 phases, 1-3 plans each)" },
-      { label: "Standard", description: "Balanced scope and speed (5-8 phases, 3-5 plans each)" },
-      { label: "Comprehensive", description: "Thorough coverage (8-12 phases, 5-10 plans each)" }
+      { label: "Coarse", description: "Fewer, broader phases (3-5 phases, 1-3 plans each)" },
+      { label: "Standard", description: "Balanced phase size (5-8 phases, 3-5 plans each)" },
+      { label: "Fine", description: "Many focused phases (8-12 phases, 5-10 plans each)" }
     ]
   },
   {
@@ -457,7 +459,7 @@ questions: [
     options: [
       { label: "Smart (Recommended)", description: "Two models: one for reseach and planing, other for execution and verification" },
       { label: "Simple", description: Description: "One model for all agents (not flexible)" },
-      { label: "Custom (most flexible)", description: "Three models: different for every stage" }
+      { label: "Genius (most flexible)", description: "Three models: different for every stage" }
     ]
   }
 ]
@@ -468,14 +470,15 @@ Create `.planning/config.json` with all settings:
 ```json
 {
   "mode": "yolo|interactive",
-  "depth": "quick|standard|comprehensive",
+  "granularity": "coarse|standard|fine",
   "parallelization": true|false,
   "commit_docs": true|false,
-  "model_profile": "simple|smart|custom",
+  "model_profile": "simple|smart|genius",
   "workflow": {
     "research": true|false,
     "plan_check": true|false,
-    "verifier": true|false
+    "verifier": true|false,
+    "nyquist_validation": depth !== "quick"
   }
 }
 ```
@@ -490,7 +493,7 @@ Create `.planning/config.json` with all settings:
 **Commit config.json:**
 
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "chore: add project config" --files .planning/config.json
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "chore: add project config" --files .planning/config.json
 ```
 
 **Note:** Run `/gsd-settings` anytime to update these preferences.
@@ -544,9 +547,7 @@ Display spawning indicator:
 Spawn 4 parallel gsd-project-researcher agents with path references:
 
 ```
-task(prompt="First, read ~/.config/opencode/agents/gsd-project-researcher.md for your role and instructions.
-
-<research_type>
+task(prompt="<research_type>
 Project Research — Stack dimension for [domain].
 </research_type>
 
@@ -580,13 +581,11 @@ Your STACK.md feeds into roadmap creation. Be prescriptive:
 
 <output>
 write to: .planning/research/STACK.md
-Use template: ~/.config/opencode/get-shit-done/templates/research-project/STACK.md
+Use template: $HOME/.config/opencode/get-shit-done/templates/research-project/STACK.md
 </output>
-", subagent_type="general", model="{researcher_model}", description="Stack research")
-
-task(prompt="First, read ~/.config/opencode/agents/gsd-project-researcher.md for your role and instructions.
+", subagent_type="gsd-project-researcher", model="{researcher_model}", description="Stack research")
 
-<research_type>
+task(prompt="<research_type>
 Project Research — Features dimension for [domain].
 </research_type>
 
@@ -620,13 +619,11 @@ Your FEATURES.md feeds into requirements definition. Categorize clearly:
 
 <output>
 write to: .planning/research/FEATURES.md
-Use template: ~/.config/opencode/get-shit-done/templates/research-project/FEATURES.md
+Use template: $HOME/.config/opencode/get-shit-done/templates/research-project/FEATURES.md
 </output>
-", subagent_type="general", model="{researcher_model}", description="Features research")
+", subagent_type="gsd-project-researcher", model="{researcher_model}", description="Features research")
 
-task(prompt="First, read ~/.config/opencode/agents/gsd-project-researcher.md for your role and instructions.
-
-<research_type>
+task(prompt="<research_type>
 Project Research — Architecture dimension for [domain].
 </research_type>
 
@@ -660,13 +657,11 @@ Your ARCHITECTURE.md informs phase structure in roadmap. Include:
 
 <output>
 write to: .planning/research/ARCHITECTURE.md
-Use template: ~/.config/opencode/get-shit-done/templates/research-project/ARCHITECTURE.md
+Use template: $HOME/.config/opencode/get-shit-done/templates/research-project/ARCHITECTURE.md
 </output>
-", subagent_type="general", model="{researcher_model}", description="Architecture research")
-
-task(prompt="First, read ~/.config/opencode/agents/gsd-project-researcher.md for your role and instructions.
+", subagent_type="gsd-project-researcher", model="{researcher_model}", description="Architecture research")
 
-<research_type>
+task(prompt="<research_type>
 Project Research — Pitfalls dimension for [domain].
 </research_type>
 
@@ -700,9 +695,9 @@ Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
 
 <output>
 write to: .planning/research/PITFALLS.md
-Use template: ~/.config/opencode/get-shit-done/templates/research-project/PITFALLS.md
+Use template: $HOME/.config/opencode/get-shit-done/templates/research-project/PITFALLS.md
 </output>
-", subagent_type="general", model="{researcher_model}", description="Pitfalls research")
+", subagent_type="gsd-project-researcher", model="{researcher_model}", description="Pitfalls research")
 ```
 
 After all 4 agents complete, spawn synthesizer to create SUMMARY.md:
@@ -722,7 +717,7 @@ Synthesize research outputs into SUMMARY.md.
 
 <output>
 write to: .planning/research/SUMMARY.md
-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
 Commit after writing.
 </output>
 ", subagent_type="gsd-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
@@ -887,7 +882,7 @@ If "adjust": Return to scoping.
 **Commit requirements:**
 
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "docs: define v1 requirements" --files .planning/REQUIREMENTS.md
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: define v1 requirements" --files .planning/REQUIREMENTS.md
 ```
 
 ## 8. Create Roadmap
@@ -911,7 +906,7 @@ task(prompt="
 - .planning/PROJECT.md (Project context)
 - .planning/REQUIREMENTS.md (v1 Requirements)
 - .planning/research/SUMMARY.md (Research findings - if exists)
-- .planning/config.json (Depth and mode settings)
+- .planning/config.json (Granularity and mode settings)
 </files_to_read>
 
 </planning_context>
@@ -1017,7 +1012,7 @@ Use question:
 **Commit roadmap (after approval or auto mode):**
 
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "docs: create roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: create roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
 ```
 
 ## 9. Done
@@ -1098,7 +1093,7 @@ Exit skill and invoke command("/gsd-discuss-phase 1 --auto")
 - [ ] Brownfield detection completed
 - [ ] Deep questioning completed (threads followed, not rushed)
 - [ ] PROJECT.md captures full context → **committed**
-- [ ] config.json has workflow mode, depth, parallelization → **committed**
+- [ ] config.json has workflow mode, granularity, parallelization → **committed**
 - [ ] Research completed (if selected) — 4 parallel agents spawned → **committed**
 - [ ] Requirements gathered (from research or conversation)
 - [ ] User scoped each category (v1/v2/out of scope)

package/get-shit-done/workflows/oc-set-profile.md

@@ -5,6 +5,7 @@ You are executing the `/gsd-set-profile` command. Switch the project's active mo
 This command reads/writes:
 - `.planning/oc_config.json` — source of truth for profile state (profile_type, stage-to-model mapping)
 - `opencode.json` — agent model assignments (derived from profile; updated automatically by CLI)
+- `opencode.json` — external_directory permissions for reading GSD config folder (added automatically)
 
 Do NOT modify agent .md files. Profile switching only updates these two JSON files.
 </role>
@@ -48,6 +49,27 @@ Active profile: **{profile_name}**
 
 <behavior>
 
+## Step 0: Ensure GSD config read permission
+
+Before any profile operations, ensure opencode.json has permission to read the GSD config folder:
+
+```bash
+node ~/.config/opencode/get-shit-done/bin/gsd-oc-tools.cjs allow-read-config --dry-run
+```
+
+Parse the response:
+- **`success: true` with `action: "permission_exists"`** — Permission already configured. Continue to Step 1.
+- **`success: true` with `action: "add_permission"`** — Permission would be added. Execute without `--dry-run`:
+
+Attempt to switch to the saved profile:
+```bash
+node ~/.config/opencode/get-shit-done/bin/gsd-oc-tools.cjs allow-read-config
+```
+
+- **`success: false`** — Handle error appropriately.
+
+This ensures gsd-opencode can access workflow files, templates, and configuration from `~/.config/opencode/get-shit-done/`.
+
 ## Step 1: Load current profile
 
 Run `get-profile` to read the current state from `.planning/oc_config.json`:
@@ -148,6 +170,8 @@ Done! Updated {profile_name} profile:
 
 We just updated the `./opencode.json` file. Apply the agent settings you need to **restart your opencode**.
 
+Note: GSD config read permission has been configured to allow access to `~/.config/opencode/get-shit-done/`.
+
 </behavior>
 
 <notes>

package/get-shit-done/workflows/pause-work.md

@@ -86,13 +86,13 @@ Be specific enough for a fresh OpenCode to understand immediately.
 
 Use `current-timestamp` for last_updated field. You can use init todos (which provides timestamps) or call directly:
 ```bash
-timestamp=$(node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs current-timestamp full --raw)
+timestamp=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" current-timestamp full --raw)
 ```
 </step>
 
 <step name="commit">
 ```bash
-node ~/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/phases/*/.continue-here.md
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/phases/*/.continue-here.md
 ```
 </step>