@bhargavvc/sdd-cc 1.35.0 → 1.42.3

package/sdd/workflows/manager.md

@@ -19,18 +19,18 @@ Read all files referenced by the invoking prompt's execution_context before star
 Bootstrap via manager init:
 
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init manager)
+INIT=$(sdd-sdk query init.manager)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
-Parse JSON for: `milestone_version`, `milestone_name`, `phase_count`, `completed_count`, `in_progress_count`, `phases`, `recommended_actions`, `all_complete`, `waiting_signal`, `manager_flags`.
+Parse JSON for: `milestone_version`, `milestone_name`, `phase_count`, `completed_count`, `in_progress_count`, `phases`, `recommended_actions`, `all_complete`, `waiting_signal`, `manager_flags`, and the optional trio `queued_milestone_version`, `queued_milestone_name`, `queued_phases` (added in SDK fix `2495-2496-2497` — may be absent on older SDK versions, treat missing as empty).
 
 `manager_flags` contains per-step passthrough flags from config:
-- `manager_flags.discuss` — appended to `/sdd-discuss-phase` args (e.g. `"--auto --analyze"`)
+- `manager_flags.discuss` — appended to `/sdd:discuss-phase` args (e.g. `"--auto --analyze"`)
 - `manager_flags.plan` — appended to plan agent init command
 - `manager_flags.execute` — appended to execute agent init command
 
-These are empty strings by default. Set via: `sdd-tools config-set manager.flags.discuss "--auto --analyze"`
+These are empty strings by default. Set via: `sdd-sdk query config-set manager.flags.discuss "--auto --analyze"`
 
 **If error:** Display the error message and exit.
 
@@ -60,7 +60,7 @@ Proceed to dashboard step.
 **Every time this step is reached**, re-read state from disk to pick up changes from background agents:
 
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init manager)
+INIT=$(sdd-sdk query init.manager)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
@@ -103,6 +103,28 @@ Example output:
  | 6 | Polish & Final Mail… | 1-5  | · | · | · | · Up next           |
 ```
 
+**Queued section (next milestone preview):**
+
+If `queued_phases` is present and non-empty, render a compact preview of the next milestone's phases directly below the main table. This surfaces upcoming work without cluttering the active-milestone grid. Skip this section entirely when `queued_phases` is empty or missing (e.g. the active milestone is the last one in the roadmap).
+
+Use `queued_milestone_version` and `queued_milestone_name` for the header. Phases render without D/P/E columns since they aren't discussed yet — just number, name (pre-truncated `display_name`), dependencies (`deps_display`), and a fixed `· Queued` status. Phase-name padding should match the active-table column width for visual alignment.
+
+Example:
+
+```
+ ───────────────────────────────────────────────────────────────
+ ◆ Queued — {queued_milestone_version} {queued_milestone_name}  ({queued_phases.length} phases)
+ ───────────────────────────────────────────────────────────────
+ | # | Phase                | Deps | Status       |
+ |---|----------------------|------|--------------|
+ | 31| Email Logs           | —    | · Queued     |
+ | 32| Today's Sheets       | 31   | · Queued     |
+ | 33| Resend Backfill      | 31   | · Queued     |
+ | 34| Business Day Audit   | 31   | · Queued     |
+```
+
+Queued phases are NOT eligible for the Continue action menu — they live in a future milestone and must wait for the current milestone to ship. The preview exists purely for situational awareness.
+
 **Recommendations section:**
 
 If `all_complete` is true:
@@ -113,8 +135,8 @@ If `all_complete` is true:
 ╚══════════════════════════════════════════════════════════════╝
 
 All {phase_count} phases done. Ready for final steps:
-  → /sdd-verify-work — run acceptance testing
-  → /sdd-complete-milestone — archive and wrap up
+  → /sdd:verify-work — run acceptance testing
+  → /sdd:complete-milestone — archive and wrap up
 ```
 
 
@@ -222,7 +244,7 @@ After discuss completes, loop back to dashboard step.
 Planning runs autonomously. Spawn a background agent that delegates to the Skill pipeline with any configured flags:
 
 ```
-Task(
+Agent(
   description="Plan phase {N}: {phase_name}",
   run_in_background=true,
   prompt="You are running the SDD plan-phase workflow for phase {N} of the project.
@@ -241,6 +263,8 @@ Important: You are running in the background. Do NOT use AskUserQuestion — mak
 )
 ```
 
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above with `run_in_background=true`, do NOT do any planning work for this phase independently. Return to the dashboard immediately and wait for the background agent to report back. Only resume planning-related work when the subagent result is available.
+
 Display:
 
 ```
@@ -254,7 +278,7 @@ Loop back to dashboard step.
 Execution runs autonomously. Spawn a background agent that delegates to the Skill pipeline with any configured flags:
 
 ```
-Task(
+Agent(
   description="Execute phase {N}: {phase_name}",
   run_in_background=true,
   prompt="You are running the SDD execute-phase workflow for phase {N} of the project.
@@ -273,6 +297,8 @@ Important: You are running in the background. Do NOT use AskUserQuestion — mak
 )
 ```
 
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above with `run_in_background=true`, do NOT do any execution work for this phase independently. Return to the dashboard immediately and wait for the background agent to report back. Only resume execution-related work when the subagent result is available.
+
 Display:
 
 ```
@@ -337,11 +363,11 @@ Display final status with progress bar:
  {milestone_version} — {milestone_name}
  {PROGRESS_BAR} {progress_pct}%  ({completed_count}/{phase_count} phases)
 
- Resume anytime: /sdd-manager
+ Resume anytime: /sdd:manager
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-**Note:** Any background agents still running will continue to completion. Their results will be visible on next `/sdd-manager` or `/sdd-progress` invocation.
+**Note:** Any background agents still running will continue to completion. Their results will be visible on next `/sdd:manager` or `/sdd:progress` invocation.
 
 </step>
 
@@ -362,4 +388,5 @@ Display final status with progress bar:
 - [ ] Exit shows final status with resume instructions
 - [ ] "Other" free-text input parsed for phase number and action
 - [ ] Manager loop continues until user exits or milestone completes
+- [ ] Queued section renders when `queued_phases` is non-empty; skipped when absent or empty
 </success_criteria>

package/sdd/workflows/map-codebase.md

@@ -27,16 +27,54 @@ Documents are reference material for Claude when planning/executing. Always incl
 
 <process>
 
+<step name="parse_paths_flag" priority="first">
+Parse an optional `--paths <p1,p2,...>` argument. When supplied (by the
+post-execute codebase-drift gate in `/sdd:execute-phase` or by a user running
+`/sdd:map-codebase --paths apps/accounting,packages/ui`), the workflow
+operates in **incremental-remap mode**:
+
+- Pass `--paths <p1>,<p2>,...` through to each spawned `sdd-codebase-mapper`
+  agent's prompt. Agents scope their Glob/Grep/Bash exploration to the listed
+  repo-relative prefixes only — no whole-repo scan.
+- Reject path values that contain `..`, start with `/`, or include shell
+  metacharacters (`;`, `` ` ``, `$`, `&`, `|`, `<`, `>`). If all provided
+  paths are invalid, fall back to a normal whole-repo run.
+- On write, each mapper stamps `last_mapped_commit: <HEAD sha>` into the YAML
+  frontmatter of every document it produces (see `bin/lib/drift.cjs:writeMappedCommit`).
+
+**Explicit contract — propagate `--paths` through a single normalized
+variable.** Downstream steps (`spawn_agents`, `sequential_mapping`, and any
+Agent-mode prompt construction) MUST use `${PATH_SCOPE_HINT}` to ensure every
+mapper receives the same deterministic scope. Without this contract
+incremental-remap can silently regress to a whole-repo scan.
+
+```bash
+# Validated, comma-separated paths (empty if --paths absent or all rejected):
+SCOPED_PATHS="<validated paths or empty>"
+if [ -n "$SCOPED_PATHS" ]; then
+  PATH_SCOPE_HINT="--paths $SCOPED_PATHS"
+else
+  PATH_SCOPE_HINT=""
+fi
+```
+
+All mapper prompts built later in this workflow MUST include
+`${PATH_SCOPE_HINT}` (expanded to empty when full-repo mode is in effect).
+
+When `--paths` is absent, behave exactly as before: full-repo scan, all 7
+documents refreshed.
+</step>
+
 <step name="init_context" priority="first">
 Load codebase mapping context:
 
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init map-codebase)
+INIT=$(sdd-sdk query init.map-codebase)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-AGENT_SKILLS_MAPPER=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" agent-skills sdd-codebase-mapper 2>/dev/null)
+AGENT_SKILLS_MAPPER=$(sdd-sdk query agent-skills sdd-codebase-mapper)
 ```
 
-Extract from init JSON: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`, `subagent_timeout`.
+Extract from init JSON: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`, `subagent_timeout`, `date`.
 </step>
 
 <step name="check_existing">
@@ -89,31 +127,32 @@ Continue to spawn_agents.
 </step>
 
 <step name="detect_runtime_capabilities">
-Before spawning agents, detect whether the current runtime supports the `Task` tool for subagent delegation.
+Before spawning agents, detect whether the current runtime supports the `Agent` tool for subagent delegation.
 
-**How to detect:** Check if you have access to a `Task` tool (may be capitalized as `Task` or lowercase as `task` depending on runtime). If you do NOT have a `Task`/`task` tool (or only have tools like `browser_subagent` which is for web browsing, NOT code analysis):
+**How to detect:** Check if you have access to an `Agent` tool (may be capitalized as `Agent` or lowercase as `agent` depending on runtime). If you do NOT have an `Agent`/`agent` tool (or only have tools like `browser_subagent` which is for web browsing, NOT code analysis):
 
 → **Skip `spawn_agents` and `collect_confirmations`** — go directly to `sequential_mapping` instead.
 
-**CRITICAL:** Never use `browser_subagent` or `Explore` as a substitute for `Task`. The `browser_subagent` tool is exclusively for web page interaction and will fail for codebase analysis. If `Task` is unavailable, perform the mapping sequentially in-context.
+**CRITICAL:** Never use `browser_subagent` or `Explore` as a substitute for `Agent`. The `browser_subagent` tool is exclusively for web page interaction and will fail for codebase analysis. If `Agent` is unavailable, perform the mapping sequentially in-context.
 </step>
 
-<step name="spawn_agents" condition="Task tool is available">
+<step name="spawn_agents" condition="Agent tool is available">
 Spawn 4 parallel sdd-codebase-mapper agents.
 
-Use Task tool with `subagent_type="sdd-codebase-mapper"`, `model="{mapper_model}"`, and `run_in_background=true` for parallel execution.
+Use Agent tool with `subagent_type="sdd-codebase-mapper"`, `model="{mapper_model}"`, and `run_in_background=true` for parallel execution.
 
 **CRITICAL:** Use the dedicated `sdd-codebase-mapper` agent, NOT `Explore` or `browser_subagent`. The mapper agent writes documents directly.
 
 **Agent 1: Tech Focus**
 
-```
-Task(
+```text
+Agent(
   subagent_type="sdd-codebase-mapper",
   model="{mapper_model}",
   run_in_background=true,
   description="Map codebase tech stack",
   prompt="Focus: tech
+Today's date: {date}
 
 Analyze this codebase for technology stack and external integrations.
 
@@ -121,6 +160,10 @@ Write these documents to .planning/codebase/:
 - STACK.md - Languages, runtime, frameworks, dependencies, configuration
 - INTEGRATIONS.md - External APIs, databases, auth providers, webhooks
 
+IMPORTANT: Use {date} for all [YYYY-MM-DD] date placeholders in documents.
+
+Scope: ${PATH_SCOPE_HINT:-(full repo)} — when --paths is supplied, restrict exploration to those prefixes only.
+
 Explore thoroughly. Write documents directly using templates. Return confirmation only.
 ${AGENT_SKILLS_MAPPER}"
 )
@@ -128,13 +171,14 @@ ${AGENT_SKILLS_MAPPER}"
 
 **Agent 2: Architecture Focus**
 
-```
-Task(
+```text
+Agent(
   subagent_type="sdd-codebase-mapper",
   model="{mapper_model}",
   run_in_background=true,
   description="Map codebase architecture",
   prompt="Focus: arch
+Today's date: {date}
 
 Analyze this codebase architecture and directory structure.
 
@@ -142,6 +186,10 @@ Write these documents to .planning/codebase/:
 - ARCHITECTURE.md - Pattern, layers, data flow, abstractions, entry points
 - STRUCTURE.md - Directory layout, key locations, naming conventions
 
+IMPORTANT: Use {date} for all [YYYY-MM-DD] date placeholders in documents.
+
+Scope: ${PATH_SCOPE_HINT:-(full repo)} — when --paths is supplied, restrict exploration to those prefixes only.
+
 Explore thoroughly. Write documents directly using templates. Return confirmation only.
 ${AGENT_SKILLS_MAPPER}"
 )
@@ -149,13 +197,14 @@ ${AGENT_SKILLS_MAPPER}"
 
 **Agent 3: Quality Focus**
 
-```
-Task(
+```text
+Agent(
   subagent_type="sdd-codebase-mapper",
   model="{mapper_model}",
   run_in_background=true,
   description="Map codebase conventions",
   prompt="Focus: quality
+Today's date: {date}
 
 Analyze this codebase for coding conventions and testing patterns.
 
@@ -163,6 +212,10 @@ Write these documents to .planning/codebase/:
 - CONVENTIONS.md - Code style, naming, patterns, error handling
 - TESTING.md - Framework, structure, mocking, coverage
 
+IMPORTANT: Use {date} for all [YYYY-MM-DD] date placeholders in documents.
+
+Scope: ${PATH_SCOPE_HINT:-(full repo)} — when --paths is supplied, restrict exploration to those prefixes only.
+
 Explore thoroughly. Write documents directly using templates. Return confirmation only.
 ${AGENT_SKILLS_MAPPER}"
 )
@@ -171,23 +224,30 @@ ${AGENT_SKILLS_MAPPER}"
 **Agent 4: Concerns Focus**
 
 ```
-Task(
+Agent(
   subagent_type="sdd-codebase-mapper",
   model="{mapper_model}",
   run_in_background=true,
   description="Map codebase concerns",
   prompt="Focus: concerns
+Today's date: {date}
 
 Analyze this codebase for technical debt, known issues, and areas of concern.
 
 Write this document to .planning/codebase/:
 - CONCERNS.md - Tech debt, bugs, security, performance, fragile areas
 
+IMPORTANT: Use {date} for all [YYYY-MM-DD] date placeholders in documents.
+
+Scope: ${PATH_SCOPE_HINT:-(full repo)} — when --paths is supplied, restrict exploration to those prefixes only.
+
 Explore thoroughly. Write document directly using template. Return confirmation only.
 ${AGENT_SKILLS_MAPPER}"
 )
 ```
 
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling all 4 Agent() calls above with `run_in_background=true`, do NOT read any source files, analyze the codebase, or write any mapping documents independently while the subagents are active. Wait for all 4 agents to complete before proceeding to collect_confirmations. This prevents duplicate work and wasted context.
+
 Continue to collect_confirmations.
 </step>
 
@@ -227,11 +287,15 @@ If any agent failed, note the failure and continue with successful documents.
 Continue to verify_output.
 </step>
 
-<step name="sequential_mapping" condition="Task tool is NOT available (e.g. Antigravity, Gemini CLI, Codex)">
-When the `Task` tool is unavailable, perform codebase mapping sequentially in the current context. This replaces `spawn_agents` and `collect_confirmations`.
+<step name="sequential_mapping" condition="Agent tool is NOT available (e.g. Antigravity, Gemini CLI, Codex)">
+When the `Agent` tool is unavailable, perform codebase mapping sequentially in the current context. This replaces `spawn_agents` and `collect_confirmations`.
 
 **IMPORTANT:** Do NOT use `browser_subagent`, `Explore`, or any browser-based tool. Use only file system tools (Read, Bash, Write, Grep, Glob, list_dir, view_file, grep_search, or equivalent tools available in your runtime).
 
+**IMPORTANT:** Use `{date}` from init context for all `[YYYY-MM-DD]` date placeholders in documents. NEVER guess the date.
+
+**SCOPE:** When `${PATH_SCOPE_HINT}` is non-empty (i.e. `--paths` was supplied), restrict every pass below to the validated path prefixes in `${SCOPED_PATHS}`. Do NOT scan files outside those prefixes. When `${PATH_SCOPE_HINT}` is empty, perform a full-repo scan.
+
 Perform all 4 mapping passes sequentially:
 
 **Pass 1: Tech Focus**
@@ -314,7 +378,7 @@ Continue to commit_codebase_map.
 Commit the codebase map:
 
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs: map existing codebase" --files .planning/codebase/*.md
+sdd-sdk query commit "docs: map existing codebase" --files .planning/codebase/*.md
 ```
 
 Continue to offer_next.
@@ -345,18 +409,18 @@ Created .planning/codebase/:
 
 ---
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Initialize project** — use codebase context for planning
 
 `/clear` then:
 
-`/sdd-new-project`
+`/sdd:new-project`
 
 ---
 
 **Also available:**
-- Re-run mapping: `/sdd-map-codebase`
+- Re-run mapping: `/sdd:map-codebase`
 - Review specific file: `cat .planning/codebase/STACK.md`
 - Edit any document before proceeding
 
@@ -370,8 +434,8 @@ End workflow.
 
 <success_criteria>
 - .planning/codebase/ directory created
-- If Task tool available: 4 parallel sdd-codebase-mapper agents spawned with run_in_background=true
-- If Task tool NOT available: 4 sequential mapping passes performed inline (never using browser_subagent)
+- If Agent tool available: 4 parallel sdd-codebase-mapper agents spawned with run_in_background=true
+- If Agent tool NOT available: 4 sequential mapping passes performed inline (never using browser_subagent)
 - All 7 codebase documents exist
 - No empty documents (each should have >20 lines)
 - Clear completion summary with line counts

package/sdd/workflows/milestone-summary.md

@@ -15,7 +15,7 @@ If `$ARGUMENTS` is empty:
 1. Check `.planning/STATE.md` for current milestone version
 2. Check `.planning/milestones/` for the latest archived version
 3. If neither found, check if `.planning/ROADMAP.md` exists (project may be mid-milestone)
-4. If nothing found: error "No milestone found. Run /sdd-new-project or /sdd-new-milestone first."
+4. If nothing found: error "No milestone found. Run /sdd:new-project or /sdd:new-milestone first."
 
 Set `VERSION` to the resolved version (e.g., "1.0").
 
@@ -53,7 +53,7 @@ Read all files that exist. Missing files are fine — the summary adapts to what
 Find all phase directories:
 
 ```bash
-sdd-tools.cjs init progress
+sdd-sdk query init.progress
 ```
 
 This returns phase metadata. For each phase in the milestone scope:
@@ -189,8 +189,8 @@ mkdir -p .planning/reports
 
 Write the summary, then commit:
 ```bash
-sdd-tools.cjs commit "docs(v${VERSION}): generate milestone summary for onboarding" \
-  --files ".planning/reports/MILESTONE_SUMMARY-v${VERSION}.md"
+sdd-sdk query commit "docs(v${VERSION}): generate milestone summary for onboarding" --files \
+  ".planning/reports/MILESTONE_SUMMARY-v${VERSION}.md"
 ```
 
 ## Step 7: Present Summary
@@ -212,12 +212,12 @@ If the user asks questions:
 - Stay grounded in what was actually built (not speculation)
 
 If the user is done:
-- Suggest next steps: `/sdd-new-milestone`, `/sdd-progress`, or sharing the summary with the team
+- Suggest next steps: `/sdd:new-milestone`, `/sdd:progress`, or sharing the summary with the team
 
 ## Step 9: Update STATE.md
 
 ```bash
-sdd-tools.cjs state record-session \
-  --stopped-at "Milestone v${VERSION} summary generated" \
-  --resume-file ".planning/reports/MILESTONE_SUMMARY-v${VERSION}.md"
+sdd-sdk query state.record-session "" \
+  "Milestone v${VERSION} summary generated" \
+  ".planning/reports/MILESTONE_SUMMARY-v${VERSION}.md"
 ```

package/sdd/workflows/mvp-phase.md

@@ -0,0 +1,221 @@
+<purpose>
+Guide the user through MVP-mode planning for a phase. Prompts for an "As a / I want to / So that" user story, runs SPIDR splitting check on the story, writes the result to ROADMAP.md, and delegates to `/sdd plan-phase` (which auto-detects MVP via the roadmap mode field shipped in PRD Phase 1).
+</purpose>
+
+<required_reading>
+@~/.claude/sdd/references/user-story-template.md
+@~/.claude/sdd/references/spidr-splitting.md
+@~/.claude/sdd/references/planner-mvp-mode.md
+</required_reading>
+
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. They are equivalent.
+
+**TEXT_MODE fallback:** 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.
+</runtime_note>
+
+<process>
+
+## 1. Parse and validate phase argument
+
+Extract the phase number from `$ARGUMENTS` (integer or decimal like `2.1`). Optional flag: `--force` (allow operating on `in_progress` / `completed` phases).
+
+If no argument:
+```
+ERROR: Phase number required
+Usage: /sdd mvp-phase <phase-number>
+Example: /sdd mvp-phase 1
+Example: /sdd mvp-phase 2.1
+```
+Exit.
+
+Normalize per `@~/.claude/sdd/references/phase-argument-parsing.md` (zero-pad integer phases to two digits).
+
+## 2. Validate phase exists and check status
+
+```bash
+PHASE_INFO=$(sdd-sdk query roadmap.get-phase "${PHASE}")
+PHASE_FOUND=$(echo "$PHASE_INFO" | jq -r '.found')
+PHASE_NAME=$(echo "$PHASE_INFO" | jq -r '.phase_name')
+PHASE_GOAL=$(echo "$PHASE_INFO" | jq -r '.goal')
+PHASE_MODE=$(echo "$PHASE_INFO" | jq -r '.mode // ""')
+PHASE_COMPLETE=$(echo "$PHASE_INFO" | jq -r '.roadmap_complete // false')
+
+ANALYZE=$(sdd-sdk query roadmap.analyze)
+if [[ "$ANALYZE" == @file:* ]]; then ANALYZE=$(cat "${ANALYZE#@file:}"); fi
+DISK_STATUS=$(echo "$ANALYZE" | jq -r --arg p "$PHASE" '.phases[] | select((.phase_number|tostring)==$p) | .disk_status' | head -1)
+if [[ "$DISK_STATUS" == "complete" || "$PHASE_COMPLETE" == "true" ]]; then
+  STATUS="completed"
+elif [[ "$DISK_STATUS" == "planned" || "$DISK_STATUS" == "partial" ]]; then
+  STATUS="in_progress"
+else
+  STATUS="not_started"
+fi
+```
+
+If `PHASE_FOUND` is `false`: error and exit. Suggest `/sdd add-phase` or `/sdd insert-phase` to create the phase first.
+
+**Status guard.** If the phase is `in_progress` (has plans but not complete) or `completed`, refuse unless `--force` is in `$ARGUMENTS`:
+
+```text
+ERROR: Phase ${PHASE} is currently ${STATUS}.
+Converting an active or completed phase to MVP mode mid-flight will
+invalidate any existing plans and summaries.
+
+To proceed anyway: /sdd mvp-phase ${PHASE} --force
+```
+
+**Already-MVP guard.** If `PHASE_MODE` is already `mvp`, surface this and ask whether to re-prompt the user story or abort:
+
+> "Phase ${PHASE} is already in MVP mode with goal: «${PHASE_GOAL}». Re-run user-story prompts and SPIDR check?"
+
+Use `AskUserQuestion` with options [Re-prompt / Abort]. On Abort, exit cleanly. On Re-prompt, proceed.
+
+## 3. User story prompts
+
+Run three sequential `AskUserQuestion` calls. Each is free-text. After all three, assemble into the canonical sentence per `@~/.claude/sdd/references/user-story-template.md`:
+
+**Prompt 1 — As a:**
+> "As a [user role]?"
+> (Examples: "new user", "admin", "signed-in customer", "API consumer")
+
+**Prompt 2 — I want to:**
+> "I want to [capability]?"
+> (Examples: "register and log in", "upload a CSV", "see my dashboard")
+
+**Prompt 3 — So that:**
+> "So that [outcome]?"
+> (Examples: "I can access my account", "I can bulk-import contacts", "I can see at a glance what needs attention")
+
+Assemble:
+
+```
+USER_STORY="As a ${ROLE}, I want to ${CAPABILITY}, so that ${OUTCOME}."
+```
+
+If any of the three answers is empty or whitespace-only, error and re-prompt that single field. Do NOT proceed with a partial story.
+
+**Validate via the centralized User Story validator.** The verb owns the canonical regex `/^As a .+, I want to .+, so that .+\.$/` and surfaces per-error guidance:
+
+```bash
+USER_STORY_RESULT=$(sdd-sdk query user-story.validate --story "$USER_STORY")
+if [ "$(echo "$USER_STORY_RESULT" | jq -r '.valid')" != "true" ]; then
+  echo "$USER_STORY_RESULT" | jq -r '.errors[]' >&2
+  # Re-prompt the offending field(s) per surfaced errors, then re-run validation.
+  # Do not abort the workflow on first invalid draft.
+  RE_PROMPT_USER_STORY=true
+fi
+```
+
+This guarantees the goal stored in ROADMAP.md will satisfy the same guard the verifier applies later.
+If `RE_PROMPT_USER_STORY=true`, re-run only the offending prompt field(s), rebuild `USER_STORY`, and validate again before continuing.
+
+## 4. SPIDR splitting check
+
+Run the SPIDR rules from `@~/.claude/sdd/references/spidr-splitting.md`. Briefly:
+
+**Trigger evaluation.** Check the assembled `USER_STORY` against the four size signals from the reference (compound capabilities, multi-actor, length > 120 chars, vague capability). If none fire, **skip SPIDR** entirely — go to step 5.
+
+**If SPIDR triggers.**
+
+a) Restate the story to the user:
+
+> "Your story: «${USER_STORY}»
+>
+> This story has [signal description, e.g., 'two compound capabilities joined by and']. Splitting it into multiple phases will produce a cleaner Walking Skeleton and reduce the risk of mid-phase scope creep.
+>
+> Want to walk through SPIDR splitting?"
+
+Use `AskUserQuestion` with options [Yes, walk through SPIDR / No, proceed with the story as-is].
+
+If "No": skip SPIDR, go to step 5.
+
+If "Yes": continue to (b).
+
+b) Ask which SPIDR axis fits best:
+
+> "Which axis best fits how to split this story?"
+
+Use `AskUserQuestion` with the five options from `spidr-splitting.md` (Spike / Paths / Interfaces / Data / Rules). Each option includes its targeted question as the description so the user can pick by understanding what each axis means.
+
+c) Walk through the chosen axis with **one** targeted question (not all five). For example, if the user picked "Paths":
+
+> "Does this feature have a happy path and one or more error/edge paths?"
+
+Free-text response. Workflow parses to identify the split.
+
+d) Produce a split proposal. Example:
+
+> "Proposed split (Paths axis):
+> - **Phase ${PHASE} (this one):** Happy path — ${HAPPY_STORY}
+> - **Phase ${PHASE+1} (new):** Edge case — ${EDGE_STORY}
+>
+> Accept this split?"
+
+Use `AskUserQuestion` [Accept / Modify / Reject].
+
+- **Accept**: `USER_STORY` becomes the first split's story (`${HAPPY_STORY}` in the example). Surface the remaining splits as a list of `/sdd add-phase` invocations the user can run after this command completes — do NOT auto-create the new phases (preserve user control over numbering).
+- **Modify**: re-prompt the splits one more time, then accept or reject.
+- **Reject**: revert `USER_STORY` to the original, proceed without splitting.
+
+## 5. Update ROADMAP.md
+
+Read `ROADMAP.md`. Find the section for `Phase ${PHASE}`. Apply two edits:
+
+**Edit 1 — Update Goal line.**
+
+Find: `**Goal:** ${OLD_GOAL_TEXT}`
+Replace with: `**Goal:** ${USER_STORY}`
+
+**Edit 2 — Insert Mode line.**
+
+If `**Mode:**` already exists in the section (replacing or re-running), update it to `**Mode:** mvp`.
+If `**Mode:**` does not exist, insert `**Mode:** mvp` on the line immediately after `**Goal:**`.
+
+Show the user a unified diff (lines being changed) and ask:
+
+> "Apply these changes to ROADMAP.md?"
+
+Use `AskUserQuestion` [Apply / Cancel]. On Cancel, exit without writing.
+
+On Apply, write the updated `ROADMAP.md` atomically (read-edit-write).
+
+## 6. Verify the write
+
+```bash
+NEW_MODE=$(sdd-sdk query roadmap.get-phase "${PHASE}" --pick mode)
+NEW_GOAL=$(sdd-sdk query roadmap.get-phase "${PHASE}" --pick goal)
+```
+
+Assert:
+- `NEW_MODE` equals `mvp`
+- `NEW_GOAL` equals the assembled user story
+
+If either assertion fails, surface the discrepancy to the user and exit. Do not proceed to plan-phase delegation with a half-applied write.
+
+## 7. Delegate to /sdd plan-phase
+
+Invoke `/sdd plan-phase ${PHASE}` (no flags). Phase 1's MVP_MODE resolution chain (CLI flag → roadmap mode → config → false) will detect the new `**Mode:** mvp` line and run plan-phase in vertical-slice mode automatically.
+
+The Walking Skeleton gate (also from Phase 1) will fire automatically if `${PHASE} == "01"` and there are zero prior phase summaries.
+
+## 8. Surface deferred phase splits (if any)
+
+If SPIDR produced a split in step 4, append a final user-facing message:
+
+> "**SPIDR split deferred phases.**
+>
+> Your original story was split. The first slice is now planned via plan-phase.
+> To create the remaining slice(s) as new phases, run:
+>
+> - `/sdd add-phase` — for the next slice: «${SPLIT_2_STORY}»
+> - `/sdd add-phase` — for the next slice: «${SPLIT_3_STORY}»
+>
+> Each will be added to the end of the current milestone. You can then run
+> `/sdd mvp-phase <new-phase-number>` on each to plan them as MVP slices."
+
+## 9. Exit
+
+Workflow ends. The phase is now in MVP mode with a planned PLAN.md, optionally with deferred follow-up phases surfaced for the user.
+
+</process>