gsd-opencode 1.30.0 → 1.33.0

package/agents/gsd-ui-auditor.md

@@ -92,6 +92,46 @@ This gate runs unconditionally on every audit. The .gitignore ensures screenshot
 
 </gitignore_gate>
 
+<playwright_mcp_approach>
+
+## Automated Screenshot Capture via Playwright-MCP (preferred when available)
+
+Before attempting the CLI screenshot approach, check whether `mcp__playwright__*`
+tools are available in this session. If they are, use them instead of the CLI approach:
+
+```
+# Preferred: Playwright-MCP automated verification
+# 1. Navigate to the component URL
+mcp__playwright__navigate(url="http://localhost:3000")
+
+# 2. Take desktop screenshot
+mcp__playwright__screenshot(name="desktop", width=1440, height=900)
+
+# 3. Take mobile screenshot
+mcp__playwright__screenshot(name="mobile", width=375, height=812)
+
+# 4. For specific components listed in UI-SPEC.md, navigate to each
+#    component route and capture targeted screenshots for comparison
+#    against the spec's stated dimensions, colors, and layout.
+
+# 5. Compare screenshots against UI-SPEC.md requirements:
+#    - Dimensions: Is component X width 70vw as specified?
+#    - Color: Is the accent color applied only on declared elements?
+#    - Layout: Are spacing values within the declared spacing scale?
+#    Report any visual discrepancies as automated findings.
+```
+
+**When Playwright-MCP is available:**
+- Use it for all screenshot capture (skip the CLI approach below)
+- Each UI checkpoint from UI-SPEC.md can be verified automatically
+- Discrepancies are reported as pillar findings with screenshot evidence
+- Items requiring subjective judgment are flagged as `needs_human_review: true`
+
+**When Playwright-MCP is NOT available:** fall back to the CLI screenshot approach
+below. Behavior is unchanged from the standard code-only audit path.
+
+</playwright_mcp_approach>
+
 <screenshot_approach>
 
 ## Screenshot Capture (CLI only — no MCP, no persistent browser)

package/agents/gsd-user-profiler.md

@@ -40,7 +40,7 @@ Key characteristics of the input:
 </input>
 
 <reference>
-@get-shit-done/references/user-profiling.md
+@$HOME/.config/opencode/get-shit-done/references/user-profiling.md
 
 This is the detection heuristics rubric. read it in full before analyzing any messages. It defines:
 - The 8 dimensions and their rating spectrums
@@ -54,7 +54,7 @@ This is the detection heuristics rubric. read it in full before analyzing any me
 <process>
 
 <step name="load_rubric">
-read the user-profiling reference document at `get-shit-done/references/user-profiling.md` to load:
+read the user-profiling reference document at `$HOME/.config/opencode/get-shit-done/references/user-profiling.md` to load:
 - All 8 dimension definitions with rating spectrums
 - Signal patterns and detection heuristics per dimension
 - Confidence scoring thresholds (HIGH: 10+ signals across 2+ projects, MEDIUM: 5-9, LOW: <5, UNSCORED: 0)

package/agents/gsd-verifier.md

@@ -94,13 +94,21 @@ Extract phase goal from ROADMAP.md — this is the outcome to verify, not the ta
 
 In re-verification mode, must-haves come from Step 0.
 
-**Option A: Must-haves in PLAN frontmatter**
+**Step 2a: Always load ROADMAP Success Criteria**
+
+```bash
+PHASE_DATA=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "$PHASE_NUM" --raw)
+```
+
+Parse the `success_criteria` array from the JSON output. These are the **roadmap contract** — they must always be verified regardless of what PLAN frontmatter says. Store them as `roadmap_truths`.
+
+**Step 2b: Load PLAN frontmatter must-haves (if present)**
 
 ```bash
 grep -l "must_haves:" "$PHASE_DIR"/*-PLAN.md 2>/dev/null
 ```
 
-If found, extract and use:
+If found, extract:
 
 ```yaml
 must_haves:
@@ -116,25 +124,20 @@ must_haves:
       via: "fetch in useEffect"
 ```
 
-**Option B: Use Success Criteria from ROADMAP.md**
+**Step 2c: Merge must-haves**
 
-If no must_haves in frontmatter, check for Success Criteria:
+Combine all sources into a single must-haves list:
 
-```bash
-PHASE_DATA=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "$PHASE_NUM" --raw)
-```
+1. **Start with `roadmap_truths`** from Step 2a (these are non-negotiable)
+2. **Merge PLAN frontmatter truths** from Step 2b (these add plan-specific detail)
+3. **Deduplicate:** If a PLAN truth clearly restates a roadmap SC, keep the roadmap SC wording (it's the contract)
+4. **If neither 2a nor 2b produced any truths**, fall back to Option C below
 
-Parse the `success_criteria` array from the JSON output. If non-empty:
-1. **Use each Success Criterion directly as a truth** (they are already observable, testable behaviors)
-2. **Derive artifacts:** For each truth, "What must EXIST?" — map to concrete file paths
-3. **Derive key links:** For each artifact, "What must be CONNECTED?" — this is where stubs hide
-4. **Document must-haves** before proceeding
-
-Success Criteria from ROADMAP.md are the contract — they take priority over Goal-derived truths.
+**CRITICAL:** PLAN frontmatter must-haves must NOT reduce scope. If ROADMAP.md defines 5 Success Criteria but the plan only lists 3 in must_haves, all 5 must still be verified. The plan can ADD must-haves but never subtract roadmap SCs.
 
 **Option C: Derive from phase goal (fallback)**
 
-If no must_haves in frontmatter AND no Success Criteria in ROADMAP:
+If no Success Criteria in ROADMAP AND no must_haves in frontmatter:
 
 1. **State the goal** from ROADMAP.md
 2. **Derive truths:** "What must be TRUE?" — list 3-7 observable, testable behaviors
@@ -448,16 +451,53 @@ npm test -- --grep "$PHASE_TEST_PATTERN" 2>&1 | grep -q "passing"
 
 ## Step 9: Determine Overall Status
 
-**Status: passed** — All truths VERIFIED, all artifacts pass levels 1-3, all key links WIRED, no blocker anti-patterns.
+Classify status using this decision tree IN ORDER (most restrictive first):
+
+1. IF any truth FAILED, artifact MISSING/STUB, key link NOT_WIRED, or blocker anti-pattern found:
+   → **status: gaps_found**
 
-**Status: gaps_found** — One or more truths FAILED, artifacts MISSING/STUB, key links NOT_WIRED, or blocker anti-patterns found.
+2. IF Step 8 produced ANY human verification items (section is non-empty):
+   → **status: human_needed**
+   (Even if all truths are VERIFIED and score is N/N — human items take priority)
 
-**Status: human_needed** — All automated checks pass but items flagged for human verification.
+3. IF all truths VERIFIED, all artifacts pass, all links WIRED, no blockers, AND no human verification items:
+   → **status: passed**
+
+**passed is ONLY valid when the human verification section is empty.** If you identified items requiring human testing in Step 8, status MUST be human_needed.
 
 **Score:** `verified_truths / total_truths`
 
+## Step 9b: Filter Deferred Items
+
+Before reporting gaps, check if any identified gaps are explicitly addressed in later phases of the current milestone. This prevents false-positive gap reports for items intentionally scheduled for future work.
+
+**Load the full milestone roadmap:**
+
+```bash
+ROADMAP_DATA=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap analyze --raw)
+```
+
+Parse the JSON to extract all phases. Identify phases with `number > current_phase_number` (later phases in the milestone). For each later phase, extract its `goal` and `success_criteria`.
+
+**For each potential gap identified in Step 9:**
+
+1. Check if the gap's failed truth or missing item is covered by a later phase's goal or success criteria
+2. **Match criteria:** The gap's concern appears in a later phase's goal text, success criteria text, or the later phase's name clearly suggests it covers this area of work
+3. If a match is found → move the gap to the `deferred` list, recording which phase addresses it and the matching evidence (goal text or success criterion)
+4. If the gap does not match any later phase → keep it as a real `gap`
+
+**Important:** Be conservative when matching. Only defer a gap when there is clear, specific evidence in a later phase's roadmap section. Vague or tangential matches should NOT cause a gap to be deferred — when in doubt, keep it as a real gap.
+
+**Deferred items do NOT affect the status determination.** After filtering, recalculate:
+
+- If the gaps list is now empty and no human verification items exist → `passed`
+- If the gaps list is now empty but human verification items exist → `human_needed`
+- If the gaps list still has items → `gaps_found`
+
 ## Step 10: Structure Gap Output (If Gaps Found)
 
+Before writing VERIFICATION.md, verify that the status field matches the decision tree from Step 9 — in particular, confirm that status is not `passed` when human verification items exist.
+
 Structure gaps in YAML frontmatter for `/gsd-plan-phase --gaps`:
 
 ```yaml
@@ -478,6 +518,17 @@ gaps:
 - `artifacts`: Files with issues
 - `missing`: Specific things to add/fix
 
+If Step 9b identified deferred items, add a `deferred` section after `gaps`:
+
+```yaml
+deferred:  # Items addressed in later phases — not actionable gaps
+  - truth: "Observable truth not yet met"
+    addressed_in: "Phase 5"
+    evidence: "Phase 5 success criteria: 'Implement RuntimeConfigC FFI bindings'"
+```
+
+Deferred items are informational only — they do not require closure plans.
+
 **Group related gaps by concern** — if multiple truths fail from the same root cause, note this to help the planner create focused plans.
 
 </verification_process>
@@ -512,6 +563,10 @@ gaps: # Only if status: gaps_found
         issue: "What's wrong"
     missing:
       - "Specific thing to add/fix"
+deferred: # Only if deferred items exist (Step 9b)
+  - truth: "Observable truth addressed in a later phase"
+    addressed_in: "Phase N"
+    evidence: "Matching goal or success criteria text"
 human_verification: # Only if status: human_needed
   - test: "What to do"
     expected: "What should happen"
@@ -536,6 +591,15 @@ human_verification: # Only if status: human_needed
 
 **Score:** {N}/{M} truths verified
 
+### Deferred Items
+
+Items not yet met but explicitly addressed in later milestone phases.
+Only include this section if deferred items exist (from Step 9b).
+
+| # | Item | Addressed In | Evidence |
+|---|------|-------------|----------|
+| 1 | {truth} | Phase {N} | {matching goal or success criteria} |
+
 ### Required Artifacts
 
 | Artifact | Expected    | Status | Details |
@@ -699,7 +763,9 @@ return <div>No messages</div>  // Always shows "no messages"
 - [ ] Behavioral spot-checks run on runnable code (or skipped with reason)
 - [ ] Human verification items identified
 - [ ] Overall status determined
+- [ ] Deferred items filtered against later milestone phases (Step 9b)
 - [ ] Gaps structured in YAML frontmatter (if gaps_found)
+- [ ] Deferred items structured in YAML frontmatter (if deferred items exist)
 - [ ] Re-verification metadata included (if previous existed)
 - [ ] VERIFICATION.md created with complete report
 - [ ] Results returned to orchestrator (NOT committed)

package/commands/gsd/gsd-add-backlog.md

@@ -29,7 +29,7 @@ the normal phase sequence and accumulate context over time.
 
 3. **Create the phase directory:**
    ```bash
-   SLUG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" generate-slug "$ARGUMENTS")
+   SLUG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" generate-slug "$ARGUMENTS" --raw)
    mkdir -p ".planning/phases/${NEXT}-${SLUG}"
    touch ".planning/phases/${NEXT}-${SLUG}/.gitkeep"
    ```

package/commands/gsd/gsd-analyze-dependencies.md

@@ -0,0 +1,34 @@
+---
+name: gsd-analyze-dependencies
+description: Analyze phase dependencies and suggest Depends on entries for ROADMAP.md
+permissions:
+   read: true
+   write: true
+   bash: true
+   glob: true
+   grep: true
+   question: true
+---
+<objective>
+Analyze the phase dependency graph for the current milestone. For each phase pair, determine if there is a dependency relationship based on:
+- File overlap (phases that modify the same files must be ordered)
+- Semantic dependencies (a phase that uses an API built by another phase)
+- Data flow (a phase that consumes output from another phase)
+
+Then suggest `Depends on` updates to ROADMAP.md.
+</objective>
+
+<execution_context>
+@$HOME/.config/opencode/get-shit-done/workflows/analyze-dependencies.md
+</execution_context>
+
+<context>
+No arguments required. Requires an active milestone with ROADMAP.md.
+
+Run this command BEFORE `/gsd-manager` to fill in missing `Depends on` fields and prevent merge conflicts from unordered parallel execution.
+</context>
+
+<process>
+Execute the analyze-dependencies workflow from @$HOME/.config/opencode/get-shit-done/workflows/analyze-dependencies.md end-to-end.
+Present dependency suggestions clearly and apply confirmed updates to ROADMAP.md.
+</process>

package/commands/gsd/gsd-autonomous.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-autonomous
 description: Run all remaining phases autonomously — discuss→plan→execute per phase
-argument-hint: "[--from N]"
+argument-hint: "[--from N] [--to N] [--only N] [--interactive]"
 permissions:
    read: true
    write: true
@@ -30,7 +30,11 @@ Uses ROADMAP.md phase discovery and skill() flat invocations for each phase comm
 </execution_context>
 
 <context>
-Optional flag: `--from N` — start from phase N instead of the first incomplete phase.
+Optional flags:
+- `--from N` — start from phase N instead of the first incomplete phase.
+- `--to N` — stop after phase N completes (halt instead of advancing to next phase).
+- `--only N` — execute only phase N (single-phase mode).
+- `--interactive` — run discuss inline with questions (not auto-answered), then dispatch plan→execute as background agents. Keeps the main context lean while preserving user input on decisions.
 
 Project context, phase list, and state are resolved inside the workflow using init commands (`gsd-tools.cjs init milestone-op`, `gsd-tools.cjs roadmap analyze`). No upfront context loading needed.
 </context>

package/commands/gsd/gsd-cleanup.md

@@ -1,6 +1,11 @@
 ---
 name: gsd-cleanup
 description: Archive accumulated phase directories from completed milestones
+permissions:
+   read: true
+   write: true
+   bash: true
+   question: true
 ---
 <objective>
 Archive phase directories from completed milestones into `.planning/milestones/v{X.Y}-phases/`.

package/commands/gsd/gsd-debug.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-debug
 description: Systematic debugging with persistent state across context resets
-argument-hint: [issue description]
+argument-hint: [--diagnose] [issue description]
 permissions:
    read: true
    bash: true
@@ -15,6 +15,9 @@ Debug issues using scientific method with subagent isolation.
 **Orchestrator role:** Gather symptoms, spawn gsd-debugger agent, handle checkpoints, spawn continuations.
 
 **Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction.
+
+**Flags:**
+- `--diagnose` — Diagnose only. Find root cause without applying a fix. Returns a structured Root Cause Report. Use when you want to validate the diagnosis before committing to a fix.
 </objective>
 
 <available_agent_types>
@@ -25,6 +28,10 @@ Valid GSD subagent types (use exact names — do not fall back to 'general'):
 <context>
 User's issue: $ARGUMENTS
 
+Parse flags from $ARGUMENTS:
+- If `--diagnose` is present, set `diagnose_only=true` and remove the flag from the issue description.
+- Otherwise, `diagnose_only=false`.
+
 Check for active sessions:
 ```bash
 ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
@@ -87,7 +94,7 @@ timeline: {timeline}
 
 <mode>
 symptoms_prefilled: true
-goal: find_and_fix
+goal: {if diagnose_only: "find_root_cause_only", else: "find_and_fix"}
 </mode>
 
 <debug_file>
@@ -96,22 +103,23 @@ Create: .planning/debug/{slug}.md
 ```
 
 ```
-task(
-  prompt=filled_prompt,
-  subagent_type="gsd-debugger",
-  model="{debugger_model}",
-  description="Debug {slug}"
-)
+@gsd-debugger filled_prompt
 ```
 
 ## 4. Handle Agent Return
 
-**If `## ROOT CAUSE FOUND`:**
-- Display root cause and evidence summary
+**If `## ROOT CAUSE FOUND` (diagnose-only mode):**
+- Display root cause, confidence level, files involved, and suggested fix strategies
+- Offer options:
+  - "Fix now" — spawn a continuation agent with `goal: find_and_fix` to apply the fix (see step 5)
+  - "Plan fix" — suggest `/gsd-plan-phase --gaps`
+  - "Manual fix" — done
+
+**If `## DEBUG COMPLETE` (find_and_fix mode):**
+- Display root cause and fix summary
 - Offer options:
-  - "Fix now" - spawn fix subagent
-  - "Plan fix" - suggest /gsd-plan-phase --gaps
-  - "Manual fix" - done
+  - "Plan fix" — suggest `/gsd-plan-phase --gaps` if further work needed
+  - "Done" — mark resolved
 
 **If `## CHECKPOINT REACHED`:**
 - Present checkpoint details to user
@@ -128,9 +136,9 @@ task(
   - "Manual investigation" - done
   - "Add more context" - gather more symptoms, spawn again
 
-## 5. Spawn Continuation Agent (After Checkpoint)
+## 5. Spawn Continuation Agent (After Checkpoint or "Fix now")
 
-When user responds to checkpoint, spawn fresh agent:
+When user responds to checkpoint OR selects "Fix now" from diagnose-only results, spawn fresh agent:
 
 ```markdown
 <objective>
@@ -154,12 +162,7 @@ goal: find_and_fix
 ```
 
 ```
-task(
-  prompt=continuation_prompt,
-  subagent_type="gsd-debugger",
-  model="{debugger_model}",
-  description="Continue debug {slug}"
-)
+@gsd-debugger continuation_prompt
 ```
 
 </process>

package/commands/gsd/gsd-discuss-phase.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-discuss-phase
-description: Gather phase context through adaptive questioning before planning. Use --auto to skip interactive questions (OpenCode picks recommended defaults).
-argument-hint: "<phase> [--auto] [--batch] [--analyze] [--text]"
+description: Gather phase context through adaptive questioning before planning. Use --auto to skip interactive questions (OpenCode picks recommended defaults). Use --chain for interactive discuss followed by automatic plan+execute. Use --power for bulk question generation into a file-based UI (answer at your own pace).
+argument-hint: "<phase> [--auto] [--chain] [--batch] [--analyze] [--text] [--power]"
 permissions:
    read: true
    write: true
@@ -31,9 +31,14 @@ Extract implementation decisions that downstream agents need — researcher and
 <execution_context>
 @$HOME/.config/opencode/get-shit-done/workflows/discuss-phase.md
 @$HOME/.config/opencode/get-shit-done/workflows/discuss-phase-assumptions.md
+@$HOME/.config/opencode/get-shit-done/workflows/discuss-phase-power.md
 @$HOME/.config/opencode/get-shit-done/templates/context.md
 </execution_context>
 
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `question`. They are equivalent — `vscode_askquestions` is the VS Code Copilot implementation of the same interactive question API.
+</runtime_note>
+
 <context>
 Phase number: $ARGUMENTS (required)
 

package/commands/gsd/gsd-docs-update.md

@@ -0,0 +1,48 @@
+---
+name: gsd-docs-update
+description: Generate or update project documentation verified against the codebase
+argument-hint: "[--force] [--verify-only]"
+permissions:
+   read: true
+   write: true
+   edit: true
+   bash: true
+   glob: true
+   grep: true
+   task: true
+   question: true
+---
+<objective>
+Generate and update up to 9 documentation files for the current project. Each doc type is written by a gsd-doc-writer subagent that explores the codebase directly — no hallucinated paths, phantom endpoints, or stale signatures.
+
+Flag handling rule:
+- The optional flags documented below are available behaviors, not implied active behaviors
+- A flag is active only when its literal token appears in `$ARGUMENTS`
+- If a documented flag is absent from `$ARGUMENTS`, treat it as inactive
+- `--force`: skip preservation prompts, regenerate all docs regardless of existing content or GSD markers
+- `--verify-only`: check existing docs for accuracy against codebase, no generation (full verification requires Phase 4 verifier)
+- If `--force` and `--verify-only` both appear in `$ARGUMENTS`, `--force` takes precedence
+</objective>
+
+<execution_context>
+@$HOME/.config/opencode/get-shit-done/workflows/docs-update.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Available optional flags (documentation only — not automatically active):**
+- `--force` — Regenerate all docs. Overwrites hand-written and GSD docs alike. No preservation prompts.
+- `--verify-only` — Check existing docs for accuracy against the codebase. No files are written. Reports VERIFY marker count. Full codebase fact-checking requires the gsd-doc-verifier agent (Phase 4).
+
+**Active flags must be derived from `$ARGUMENTS`:**
+- `--force` is active only if the literal `--force` token is present in `$ARGUMENTS`
+- `--verify-only` is active only if the literal `--verify-only` token is present in `$ARGUMENTS`
+- If neither token appears, run the standard full-phase generation flow
+- Do not infer that a flag is active just because it is documented in this prompt
+</context>
+
+<process>
+Execute the docs-update workflow from @$HOME/.config/opencode/get-shit-done/workflows/docs-update.md end-to-end.
+Preserve all workflow gates (preservation_check, flag handling, wave execution, monorepo dispatch, commit, reporting).
+</process>

package/commands/gsd/gsd-execute-phase.md

@@ -35,6 +35,10 @@ Context budget: ~15% orchestrator, 100% fresh per subagent.
 @$HOME/.config/opencode/get-shit-done/references/ui-brand.md
 </execution_context>
 
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `question`. They are equivalent — `vscode_askquestions` is the VS Code Copilot implementation of the same interactive question API.
+</runtime_note>
+
 <context>
 Phase: $ARGUMENTS
 

package/commands/gsd/gsd-help.md

@@ -1,6 +1,8 @@
 ---
 name: gsd-help
 description: Show available GSD commands and usage guide
+permissions:
+   read: true
 ---
 <objective>
 Display the complete GSD command reference.

package/commands/gsd/gsd-join-discord.md

@@ -1,6 +1,7 @@
 ---
 name: gsd-join-discord
 description: Join the GSD Discord community
+permissions: []
 ---
 
 <objective>
@@ -12,7 +13,7 @@ Display the Discord invite link for the GSD community server.
 
 Connect with other GSD users, get help, share what you're building, and stay updated.
 
-**Invite link:** https://discord.gg/gsd
+**Invite link:** https://discord.gg/mYgfVNfA2r
 
 Click the link or paste it into your browser to join.
 </output>

package/commands/gsd/gsd-manager.md

@@ -8,6 +8,7 @@ permissions:
    glob: true
    grep: true
    question: true
+  - skill
    task: true
 ---
 <objective>

package/commands/gsd/gsd-new-project.md

@@ -9,6 +9,10 @@ permissions:
    task: true
    question: true
 ---
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `question`. They are equivalent — `vscode_askquestions` is the VS Code Copilot implementation of the same interactive question API.
+</runtime_note>
+
 <context>
 **Flags:**
 - `--auto` — Automatic mode. After config questions, runs research → requirements → roadmap without further interaction. Expects idea document via @ reference.

package/commands/gsd/gsd-plan-phase.md

@@ -10,6 +10,7 @@ permissions:
    glob: true
    grep: true
    task: true
+   question: true
    webfetch: true
    mcp__context7__*: true
 ---
@@ -26,6 +27,10 @@ Create executable phase prompts (PLAN.md files) for a roadmap phase with integra
 @$HOME/.config/opencode/get-shit-done/references/ui-brand.md
 </execution_context>
 
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `question`. They are equivalent — `vscode_askquestions` is the VS Code Copilot implementation of the same interactive question API. Do not skip questioning steps because `question` appears unavailable; use `vscode_askquestions` instead.
+</runtime_note>
+
 <context>
 Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omitted)
 

package/commands/gsd/gsd-quick.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-quick
 description: Execute a quick task with GSD guarantees (atomic commits, state tracking) but skip optional agents
-argument-hint: "[--full] [--discuss] [--research]"
+argument-hint: "[--full] [--validate] [--discuss] [--research]"
 permissions:
    read: true
    write: true
@@ -24,11 +24,13 @@ Quick mode is the same system with a shorter path:
 
 **`--discuss` flag:** Lightweight discussion phase before planning. Surfaces assumptions, clarifies gray areas, captures decisions in CONTEXT.md. Use when the task has ambiguity worth resolving upfront.
 
-**`--full` flag:** Enables plan-checking (max 2 iterations) and post-execution verification. Use when you want quality guarantees without full milestone ceremony.
+**`--full` flag:** Enables the complete quality pipeline — discussion + research + plan-checking + verification. One flag for everything.
+
+**`--validate` flag:** Enables plan-checking (max 2 iterations) and post-execution verification only. Use when you want quality guarantees without discussion or research.
 
 **`--research` flag:** Spawns a focused research agent before planning. Investigates implementation approaches, library options, and pitfalls for the task. Use when you're unsure of the best approach.
 
-Flags are composable: `--discuss --research --full` gives discussion + research + plan-checking + verification.
+Granular flags are composable: `--discuss --research --validate` gives the same result as `--full`.
 </objective>
 
 <execution_context>