@bhargavvc/sdd-cc 1.30.1 → 1.42.3

package/sdd/workflows/plan-review-convergence.md

@@ -0,0 +1,329 @@
+<purpose>
+Cross-AI plan convergence loop — automates the manual chain:
+sdd-plan-phase N → sdd-review N --codex → sdd-plan-phase N --reviews → sdd-review N --codex → ...
+Each step runs inside an isolated Agent that calls the corresponding Skill.
+Orchestrator only does: init, loop control, parse CYCLE_SUMMARY for HIGH count, stall detection, escalation.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+
+@$HOME/.claude/sdd/references/revision-loop.md
+@$HOME/.claude/sdd/references/gates.md
+@$HOME/.claude/sdd/references/agent-contracts.md
+</required_reading>
+
+<process>
+
+## 1. Parse and Normalize Arguments
+
+Extract from $ARGUMENTS: phase number, reviewer flags (`--codex`, `--gemini`, `--claude`, `--opencode`, `--ollama`, `--lm-studio`, `--llama-cpp`, `--all`), `--max-cycles N`, `--text`, `--ws`.
+
+```bash
+PHASE=$(echo "$ARGUMENTS" | grep -oE '[0-9]+\.?[0-9]*' | head -1)
+
+REVIEWER_FLAGS=""
+echo "$ARGUMENTS" | grep -q '\-\-codex' && REVIEWER_FLAGS="$REVIEWER_FLAGS --codex"
+echo "$ARGUMENTS" | grep -q '\-\-gemini' && REVIEWER_FLAGS="$REVIEWER_FLAGS --gemini"
+echo "$ARGUMENTS" | grep -q '\-\-claude' && REVIEWER_FLAGS="$REVIEWER_FLAGS --claude"
+echo "$ARGUMENTS" | grep -q '\-\-opencode' && REVIEWER_FLAGS="$REVIEWER_FLAGS --opencode"
+echo "$ARGUMENTS" | grep -q '\-\-ollama' && REVIEWER_FLAGS="$REVIEWER_FLAGS --ollama"
+echo "$ARGUMENTS" | grep -q '\-\-lm-studio' && REVIEWER_FLAGS="$REVIEWER_FLAGS --lm-studio"
+echo "$ARGUMENTS" | grep -q '\-\-llama-cpp' && REVIEWER_FLAGS="$REVIEWER_FLAGS --llama-cpp"
+echo "$ARGUMENTS" | grep -q '\-\-all' && REVIEWER_FLAGS="$REVIEWER_FLAGS --all"
+if [ -z "$REVIEWER_FLAGS" ]; then REVIEWER_FLAGS="--codex"; fi
+
+MAX_CYCLES=$(echo "$ARGUMENTS" | grep -oE '\-\-max-cycles\s+[0-9]+' | awk '{print $2}')
+if [ -z "$MAX_CYCLES" ]; then MAX_CYCLES=3; fi
+
+SDD_WS=""
+echo "$ARGUMENTS" | grep -qE '\-\-ws\s+\S+' && SDD_WS=$(echo "$ARGUMENTS" | grep -oE '\-\-ws\s+\S+')
+```
+
+## 1.5. Config Gate (feature disabled by default)
+
+```bash
+CONVERGENCE_ENABLED=$(sdd-sdk query config-get workflow.plan_review_convergence 2>/dev/null || echo "false")
+```
+
+**If `CONVERGENCE_ENABLED` is not `"true"`:** Display and exit:
+
+```text
+sdd-plan-review-convergence is disabled (workflow.plan_review_convergence=false).
+
+This feature automates the plan→review→replan loop using external AI reviewers.
+Enable it with:
+
+  sdd config-set workflow.plan_review_convergence true
+
+Then re-run: /sdd:plan-review-convergence {PHASE}
+```
+
+## 2. Initialize
+
+```bash
+INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init plan-phase "$PHASE")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse JSON for: `phase_dir`, `phase_number`, `padded_phase`, `phase_name`, `has_plans`, `plan_count`, `commit_docs`, `text_mode`, `response_language`.
+
+**If `response_language` is set:** All user-facing output should be in `{response_language}`.
+
+Set `TEXT_MODE=true` if `--text` is present in $ARGUMENTS OR `text_mode` from init JSON is `true`. When `TEXT_MODE` is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number.
+
+## 3. Validate Phase + Pre-flight Gate
+
+```bash
+PHASE_INFO=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" roadmap get-phase "${PHASE}")
+```
+
+**If `found` is false:** Error with available phases. Exit.
+
+Display startup banner:
+
+```text
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SDD ► PLAN CONVERGENCE — Phase {phase_number}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Reviewers: {REVIEWER_FLAGS}
+ Max cycles: {MAX_CYCLES}
+```
+
+## 4. Initial Planning (if no plans exist)
+
+**If `has_plans` is true:** Skip to step 5. Display: `Plans found: {plan_count} PLAN.md files — skipping initial planning.`
+
+**If `has_plans` is false:**
+
+Display: `◆ No plans found — spawning initial planning agent...`
+
+```text
+Agent(
+  description="Initial planning Phase {PHASE}",
+  prompt="Run /sdd:plan-phase for Phase {PHASE}.
+
+Execute: Skill(skill='sdd-plan-phase', args='{PHASE} {SDD_WS}')
+
+Complete the full planning workflow. Do NOT return until planning is complete and PLAN.md files are committed.",
+  mode="auto"
+)
+```
+
+After agent returns, verify plans were created:
+```bash
+PLAN_COUNT=$(ls ${phase_dir}/${padded_phase}-*-PLAN.md 2>/dev/null | wc -l)
+```
+
+If PLAN_COUNT == 0: Error — initial planning failed. Exit.
+
+Display: `Initial planning complete: ${PLAN_COUNT} PLAN.md files created.`
+
+## 5. Convergence Loop
+
+Initialize loop variables:
+
+```text
+cycle = 0
+prev_high_count = Infinity
+```
+
+### 5a. Review (Spawn Agent)
+
+Increment `cycle`.
+
+Display: `◆ Cycle {cycle}/{MAX_CYCLES} — spawning review agent...`
+
+```text
+Agent(
+  description="Cross-AI review Phase {PHASE} cycle {cycle}",
+  prompt="Run /sdd:review for Phase {PHASE}.
+
+Execute: Skill(skill='sdd-review', args='--phase {PHASE} {REVIEWER_FLAGS} {SDD_WS}')
+
+Complete the full review workflow. Do NOT return until REVIEWS.md is committed.
+
+IMPORTANT — CYCLE_SUMMARY contract (required):
+Your final response MUST include a machine-readable line of exactly this form:
+
+  CYCLE_SUMMARY: current_high=<N>
+
+Where <N> is the integer count of HIGH-severity concerns that REMAIN UNRESOLVED in this cycle's findings.
+
+Counting rules:
+  INCLUDE in the count:
+    - Newly raised HIGHs in this cycle
+    - PARTIALLY RESOLVED HIGHs: concern acknowledged and a mitigation is in progress, but not yet verified/completed
+    - Previously raised HIGHs that are still unresolved
+
+  EXCLUDE from the count:
+    - FULLY RESOLVED HIGHs: concern addressed with verification complete (closed ticket, verification log, or reviewer sign-off)
+    - HIGH mentions in retrospective/summary tables comparing cycles
+    - Quoted excerpts from prior reviews referencing past HIGH items
+
+Definitions:
+  PARTIALLY RESOLVED — concern acknowledged and mitigation is in progress but not yet verified/completed (e.g., open ticket exists but fix not landed).
+  FULLY RESOLVED — concern addressed with verification complete (closed ticket, verification log, or explicit reviewer sign-off confirming closure).
+
+Your final response MUST also include this section immediately after the CYCLE_SUMMARY line:
+
+## Current HIGH Concerns
+[List each unresolved HIGH with a brief description, one per bullet]
+[If none: write exactly 'None.']",
+  mode="auto"
+)
+```
+
+After agent returns, verify REVIEWS.md exists:
+```bash
+REVIEWS_FILE=$(ls ${phase_dir}/${padded_phase}-REVIEWS.md 2>/dev/null)
+```
+
+If REVIEWS_FILE is empty: Error — review agent did not produce REVIEWS.md. Exit.
+
+### 5b. Extract HIGH Count from CYCLE_SUMMARY Contract
+
+**Do NOT grep REVIEWS.md for HIGH count.** REVIEWS.md accumulates history across cycles — resolved HIGHs from prior cycles remain in the file as audit trail, inflating a raw grep count and causing false stall detection.
+
+Parse HIGH_COUNT from the review agent's return message via the CYCLE_SUMMARY contract:
+
+```bash
+# Extract the integer from "CYCLE_SUMMARY: current_high=N" in the agent's return message
+HIGH_COUNT=$(echo "$REVIEW_AGENT_RETURN" | grep -oE 'CYCLE_SUMMARY:\s*current_high=[0-9]+' | head -1 | grep -oE '[0-9]+$')
+
+if [ -z "$HIGH_COUNT" ]; then
+  # Distinguish malformed contract from completely absent contract
+  if echo "$REVIEW_AGENT_RETURN" | grep -q 'CYCLE_SUMMARY:'; then
+    echo "CYCLE_SUMMARY present but current_high is malformed — expected integer, got non-numeric value. Retry or switch reviewer."
+  else
+    echo "Review agent did not honor the CYCLE_SUMMARY contract — cannot determine HIGH count. Retry or switch reviewer."
+  fi
+  exit 1
+fi
+
+# Extract the ## Current HIGH Concerns section from the agent's return message
+HIGH_LINES=$(echo "$REVIEW_AGENT_RETURN" | awk '/^## Current HIGH Concerns/{found=1; next} found && /^##/{exit} found{print}')
+
+if [ "${HIGH_COUNT}" -gt 0 ] && [ -z "${HIGH_LINES}" ]; then
+  echo "⚠ Review agent's CYCLE_SUMMARY reports ${HIGH_COUNT} HIGHs but did not provide ## Current HIGH Concerns section — continuing with incomplete escalation details."
+fi
+```
+
+**If HIGH_COUNT == 0 (converged):**
+
+```bash
+node "$HOME/.claude/sdd/bin/sdd-tools.cjs" state planned-phase --phase "${PHASE}" --name "${phase_name}" --plans "${PLAN_COUNT}"
+```
+
+Display:
+```text
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SDD ► CONVERGENCE COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Phase {phase_number} converged in {cycle} cycle(s).
+ No HIGH concerns remaining.
+
+ REVIEWS.md: {REVIEWS_FILE}
+ Next: /sdd:execute-phase {PHASE}
+```
+
+Exit — convergence achieved.
+
+**If HIGH_COUNT > 0:** Continue to 5c.
+
+### 5c. Stall Detection + Escalation Check
+
+Display: `◆ Cycle {cycle}/{MAX_CYCLES} — {HIGH_COUNT} HIGH concerns found`
+
+**Stall detection:** If `HIGH_COUNT >= prev_high_count`:
+```text
+⚠ Convergence stalled — HIGH concern count not decreasing
+  ({HIGH_COUNT} HIGH concerns, previous cycle had {prev_high_count})
+```
+
+**Max cycles check:** If `cycle >= MAX_CYCLES`:
+
+If `TEXT_MODE` is true, present as plain-text numbered list:
+```text
+Plan convergence did not complete after {MAX_CYCLES} cycles.
+{HIGH_COUNT} HIGH concerns remain:
+
+{HIGH_LINES}
+
+How would you like to proceed?
+
+1. Proceed anyway — Accept plans with remaining HIGH concerns and move to execution
+2. Manual review — Stop here, review REVIEWS.md and address concerns manually
+
+Enter number:
+```
+
+Otherwise use AskUserQuestion:
+```js
+AskUserQuestion([
+  {
+    question: "Plan convergence did not complete after {MAX_CYCLES} cycles. {HIGH_COUNT} HIGH concerns remain:\n\n{HIGH_LINES}\n\nHow would you like to proceed?",
+    header: "Convergence",
+    multiSelect: false,
+    options: [
+      { label: "Proceed anyway", description: "Accept plans with remaining HIGH concerns and move to execution" },
+      { label: "Manual review", description: "Stop here — review REVIEWS.md and address concerns manually" }
+    ]
+  }
+])
+```
+
+If "Proceed anyway": Display final status and exit.
+If "Manual review":
+```text
+Review the concerns in: {REVIEWS_FILE}
+
+To replan manually:  /sdd:plan-phase {PHASE} --reviews
+To restart loop:     /sdd:plan-review-convergence {PHASE} {REVIEWER_FLAGS}
+```
+Exit workflow.
+
+### 5d. Replan (Spawn Agent)
+
+**If under max cycles:**
+
+Update `prev_high_count = HIGH_COUNT`.
+
+Display: `◆ Spawning replan agent with review feedback...`
+
+```text
+Agent(
+  description="Replan Phase {PHASE} with review feedback cycle {cycle}",
+  prompt="Run /sdd:plan-phase with --reviews for Phase {PHASE}.
+
+Execute: Skill(skill='sdd-plan-phase', args='{PHASE} --reviews --skip-research {SDD_WS}')
+
+This will replan incorporating cross-AI review feedback from REVIEWS.md.
+Do NOT return until replanning is complete and updated PLAN.md files are committed.
+
+IMPORTANT: When sdd-plan-phase outputs '## PLANNING COMPLETE', that means replanning is done. Return at that point.",
+  mode="auto"
+)
+```
+
+After agent returns → go back to **step 5a** (review again).
+
+</process>
+
+<success_criteria>
+- [ ] Config gate checked before running — exits with enable instructions if workflow.plan_review_convergence is false
+- [ ] Initial planning via Agent → Skill("sdd-plan-phase") if no plans exist
+- [ ] Review via Agent → Skill("sdd-review") — isolated, not inline; {SDD_WS} forwarded
+- [ ] Replan via Agent → Skill("sdd-plan-phase --reviews") — isolated, not inline
+- [ ] Orchestrator only does: init, config gate, loop control, parse CYCLE_SUMMARY for HIGH count, stall detection, escalation
+- [ ] HIGH count extracted from review agent's CYCLE_SUMMARY return message (not by grepping REVIEWS.md)
+- [ ] Review agent prompt defines CYCLE_SUMMARY: current_high=<N> contract with PARTIALLY/FULLY RESOLVED definitions
+- [ ] Abort with clear error if CYCLE_SUMMARY is absent; distinguish malformed from absent
+- [ ] Warn if HIGH_COUNT > 0 but ## Current HIGH Concerns section is absent from return message
+- [ ] Each Agent fully completes its Skill before returning
+- [ ] Loop exits on: no HIGH concerns (converged) OR max cycles (escalation)
+- [ ] Stall detection reported when HIGH count not decreasing
+- [ ] STATE.md updated on convergence completion
+</success_criteria>

package/sdd/workflows/plant-seed.md

@@ -8,82 +8,49 @@ Seeds beat deferred items because they:
 - Define WHEN to surface (trigger conditions, not manual scanning)
 - Track breadcrumbs (code references, related decisions)
 - Auto-present at the right time via new-milestone scan
+
+**One-shot capture**: the seed file is written immediately from the idea text alone.
+Trigger / Why / Scope are optional enrichment — they can be provided now or added
+later. The file is never gated behind questions.
 </purpose>
 
 <process>
 
-<step name="parse_idea">
+<step name="parse-idea">
 Parse `$ARGUMENTS` for the idea summary.
 
-If empty, ask:
-```
-What's the idea? (one sentence)
-```
-
-Store as `$IDEA`.
-</step>
+First, check for an enrich flag:
 
-<step name="create_seed_dir">
 ```bash
-mkdir -p .planning/seeds
+if echo "$ARGUMENTS" | grep -qE '\-\-enrich[[:space:]]+SEED-[0-9]+'; then
+  ENRICH_TARGET=$(echo "$ARGUMENTS" | grep -oE 'SEED-[0-9]+')
+  SEED_FILE=$(ls .planning/seeds/${ENRICH_TARGET}-*.md 2>/dev/null | head -1)
+  # Skip to enrich-seed step — do not prompt for $IDEA
+else
+  if [ -n "$ARGUMENTS" ]; then
+    IDEA="$ARGUMENTS"
+  else
+    # Ask only when no arguments at all
+    # What's the idea? (one sentence)
+    IDEA="<user response>"
+  fi
+fi
 ```
-</step>
-
-<step name="gather_context">
-Ask focused questions to build a complete seed:
 
-```
-AskUserQuestion(
-  header: "Trigger",
-  question: "When should this idea surface? (e.g., 'when we add user accounts', 'next major version', 'when performance becomes a priority')",
-  options: []  // freeform
-)
-```
+If `$ENRICH_TARGET` is set, skip straight to the `enrich-seed` step. Do not set `$IDEA` and do not run `create-seed-dir`, `generate-seed-id`, `write-seed`, `collect-breadcrumbs`, `commit-seed`, or `confirm`.
 
-Store as `$TRIGGER`.
-
-```
-AskUserQuestion(
-  header: "Why",
-  question: "Why does this matter? What problem does it solve or what opportunity does it create?",
-  options: []
-)
-```
-
-Store as `$WHY`.
-
-```
-AskUserQuestion(
-  header: "Scope",
-  question: "How big is this? (rough estimate)",
-  options: [
-    { label: "Small", description: "A few hours — could be a quick task" },
-    { label: "Medium", description: "A phase or two — needs planning" },
-    { label: "Large", description: "A full milestone — significant effort" }
-  ]
-)
-```
+If `$ARGUMENTS` is non-empty and contains no `--enrich` flag, treat the full value as `$IDEA` (no prompt).
 
-Store as `$SCOPE`.
+Only prompt for the idea when `$ARGUMENTS` is empty and no enrich target is present. Store the response as `$IDEA`.
 </step>
 
-<step name="collect_breadcrumbs">
-Search the codebase for relevant references:
-
+<step name="create-seed-dir">
 ```bash
-# Find files related to the idea keywords
-grep -rl "$KEYWORD" --include="*.ts" --include="*.js" --include="*.md" . 2>/dev/null | head -10
+mkdir -p .planning/seeds
 ```
-
-Also check:
-- Current STATE.md for related decisions
-- ROADMAP.md for related phases
-- todos/ for related captured ideas
-
-Store relevant file paths as `$BREADCRUMBS`.
 </step>
 
-<step name="generate_seed_id">
+<step name="generate-seed-id">
 ```bash
 # Find next seed number
 EXISTING=$( (ls .planning/seeds/SEED-*.md 2>/dev/null || true) | wc -l )
@@ -94,76 +61,169 @@ PADDED=$(printf "%03d" $NEXT)
 Generate slug from idea summary.
 </step>
 
-<step name="write_seed">
-Write `.planning/seeds/SEED-{PADDED}-{slug}.md`:
+<step name="write-seed">
+Write `.planning/seeds/SEED-{PADDED}-{slug}.md` immediately with sensible defaults:
+
+- `trigger_when`: default is `"when relevant"` — the seed will surface during any
+  new-milestone scan; the user can narrow it later via `--enrich`
+- `scope`: default is `"unknown"` — the user can update it via `--enrich`
 
 ```markdown
 ---
 id: SEED-{PADDED}
 status: dormant
 planted: {ISO date}
-planted_during: {current milestone/phase from STATE.md}
-trigger_when: {$TRIGGER}
-scope: {$SCOPE}
+planted_during: {current milestone/phase from STATE.md, or "unknown" if not in a SDD project}
+trigger_when: when relevant
+scope: unknown
 ---
 
 # SEED-{PADDED}: {$IDEA}
 
 ## Why This Matters
 
-{$WHY}
+_To be filled in. Run `/sdd:capture --seed --enrich SEED-{PADDED}` to add context._
 
 ## When to Surface
 
-**Trigger:** {$TRIGGER}
+**Trigger:** when relevant
 
-This seed should be presented during `/sdd:new-milestone` when the milestone
-scope matches any of these conditions:
-- {trigger condition 1}
-- {trigger condition 2}
+This seed will surface during `/sdd:new-milestone` when the milestone scope matches.
 
 ## Scope Estimate
 
-**{$SCOPE}** — {elaboration based on scope choice}
+**Unknown** — run `/sdd:capture --seed --enrich SEED-{PADDED}` to estimate effort.
 
 ## Breadcrumbs
 
-Related code and decisions found in the current codebase:
-
-{list of $BREADCRUMBS with file paths}
+_No breadcrumbs collected yet._
 
 ## Notes
 
-{any additional context from the current session}
+_Captured via one-shot seed capture. Enrich with trigger, why, and scope at your convenience._
+```
+</step>
+
+<step name="collect-breadcrumbs">
+After writing the file, search the codebase for relevant references:
+
+Extract one or two key terms from `$IDEA` (the most distinctive noun or phrase) and store as `$KEYWORD`.
+
+```bash
+# Derive a single keyword for breadcrumb search.
+# Lower-case, strip punctuation, take the first token longer than 2 chars.
+KEYWORD=$(printf '%s' "$IDEA" \
+  | tr '[:upper:]' '[:lower:]' \
+  | tr -cs 'a-z0-9' '\n' \
+  | awk 'length > 2 {print; exit}')
+KEYWORD="${KEYWORD:-seed}"  # fallback to literal "seed" if extraction yields nothing
+```
+
+```bash
+# Find files related to the idea keywords ($KEYWORD derived from $IDEA)
+grep -rl "$KEYWORD" --include="*.ts" --include="*.js" --include="*.md" . 2>/dev/null | head -10
 ```
+
+Also check:
+- Current STATE.md for related decisions
+- ROADMAP.md for related phases
+- todos/ for related captured ideas
+
+If any breadcrumbs are found, update the Breadcrumbs section of the seed file.
+Store relevant file paths as `$BREADCRUMBS`.
 </step>
 
-<step name="commit_seed">
+<step name="commit-seed">
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs: plant seed — {$IDEA}" --files .planning/seeds/SEED-{PADDED}-{slug}.md
+sdd-sdk query commit "docs: plant seed — {$IDEA}" --files .planning/seeds/SEED-{PADDED}-{slug}.md
 ```
 </step>
 
 <step name="confirm">
-```
+```text
 ✅ Seed planted: SEED-{PADDED}
 
 "{$IDEA}"
-Trigger: {$TRIGGER}
-Scope: {$SCOPE}
 File: .planning/seeds/SEED-{PADDED}-{slug}.md
 
-This seed will surface automatically when you run /sdd:new-milestone
-and the milestone scope matches the trigger condition.
+Trigger and scope are set to defaults. Run `/sdd:capture --seed --enrich SEED-{PADDED}`
+to add trigger conditions, rationale, and scope estimate at your convenience.
+
+This seed will surface automatically when you run /sdd:new-milestone.
+```
+</step>
+
+<step name="enrich-seed">
+**Optional enrichment — only run this step when `--enrich` flag is present.**
+
+If `--enrich` flag is in `$ARGUMENTS`:
+- `$ENRICH_TARGET` and `$SEED_FILE` are already set by `parse-idea`. Derive `$SEED_ID` from `$ENRICH_TARGET` (e.g. `SEED_ID="$ENRICH_TARGET"`). If `$SEED_FILE` is empty, fall back to the most-recently modified file in `.planning/seeds/` and set `$SEED_ID` from its filename.
+- Ask focused questions to build a complete seed:
+
+
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
+
+```text
+AskUserQuestion(
+  header: "Trigger",
+  question: "When should this idea surface? (e.g., 'when we add user accounts', 'next major version', 'when performance becomes a priority')",
+  options: []  // freeform
+)
+```
+
+Store as `$TRIGGER`.
+
+```text
+AskUserQuestion(
+  header: "Why",
+  question: "Why does this matter? What problem does it solve or what opportunity does it create?",
+  options: []
+)
+```
+
+Store as `$WHY`.
+
+```text
+AskUserQuestion(
+  header: "Scope",
+  question: "How big is this? (rough estimate)",
+  options: [
+    { label: "Small", description: "A few hours — could be a quick task" },
+    { label: "Medium", description: "A phase or two — needs planning" },
+    { label: "Large", description: "A full milestone — significant effort" }
+  ]
+)
+```
+
+Store as `$SCOPE`.
+
+Update the seed file's frontmatter and sections with the gathered values:
+- Set `trigger_when: {$TRIGGER}`
+- Set `scope: {$SCOPE}`
+- Fill in `## Why This Matters` with `{$WHY}`
+- Fill in `## When to Surface` trigger detail
+- Fill in `## Scope Estimate` elaboration
+
+Commit the update:
+```bash
+sdd-sdk query commit "docs: enrich seed ${SEED_ID} — trigger + why + scope" --files "$SEED_FILE"
+```
+
+Confirm:
+```text
+✅ Seed enriched: ${SEED_ID}
+Trigger: {$TRIGGER}
+Scope: {$SCOPE}
 ```
 </step>
 
 </process>
 
 <success_criteria>
-- [ ] Seed file created in .planning/seeds/
-- [ ] Frontmatter includes status, trigger, scope
-- [ ] Breadcrumbs collected from codebase
+- [ ] Seed file created in .planning/seeds/ in one step, no questions required
+- [ ] Frontmatter includes status, trigger_when (default: "when relevant"), scope (default: "unknown")
+- [ ] File is written BEFORE any optional enrichment questions are asked
 - [ ] Committed to git
-- [ ] User shown confirmation with trigger info
+- [ ] User shown confirmation with file path
+- [ ] Optional --enrich path available for adding trigger, why, scope post-capture
 </success_criteria>