@bhargavvc/sdd-cc 1.30.1 → 1.42.3

package/sdd/workflows/autonomous.md

@@ -1,6 +1,6 @@
 <purpose>
 
-Drive all remaining milestone phases autonomously. For each incomplete phase: discuss → plan → execute using Skill() flat invocations. Pauses only for explicit user decisions (grey area acceptance, blockers, validation requests). Re-reads ROADMAP.md after each phase to catch dynamically inserted phases.
+Drive milestone phases autonomously — all remaining phases, a range via `--from N`/`--to N`, or a single phase via `--only N`. For each incomplete phase: discuss → plan → execute using Skill() flat invocations. Pauses only for explicit user decisions (grey area acceptance, blockers, validation requests). Re-reads ROADMAP.md after each phase to catch dynamically inserted phases.
 
 </purpose>
 
@@ -16,19 +16,39 @@ Read all files referenced by the invoking prompt's execution_context before star
 
 ## 1. Initialize
 
-Parse `$ARGUMENTS` for `--from N` flag:
+Parse `$ARGUMENTS` for `--from N`, `--to N`, `--only N`, and `--interactive` flags:
 
 ```bash
 FROM_PHASE=""
 if echo "$ARGUMENTS" | grep -qE '\-\-from\s+[0-9]'; then
   FROM_PHASE=$(echo "$ARGUMENTS" | grep -oE '\-\-from\s+[0-9]+\.?[0-9]*' | awk '{print $2}')
 fi
+
+TO_PHASE=""
+if echo "$ARGUMENTS" | grep -qE '\-\-to\s+[0-9]'; then
+  TO_PHASE=$(echo "$ARGUMENTS" | grep -oE '\-\-to\s+[0-9]+\.?[0-9]*' | awk '{print $2}')
+fi
+
+ONLY_PHASE=""
+if echo "$ARGUMENTS" | grep -qE '\-\-only\s+[0-9]'; then
+  ONLY_PHASE=$(echo "$ARGUMENTS" | grep -oE '\-\-only\s+[0-9]+\.?[0-9]*' | awk '{print $2}')
+  FROM_PHASE="$ONLY_PHASE"
+fi
+
+INTERACTIVE=""
+if echo "$ARGUMENTS" | grep -q '\-\-interactive'; then
+  INTERACTIVE="true"
+fi
 ```
 
+When `--only` is set, also set `FROM_PHASE` to the same value so existing filter logic applies.
+
+When `--interactive` is set, discuss runs inline with questions (not auto-answered), while plan and execute are dispatched as background agents. This keeps the main context lean — only discuss conversations accumulate — while preserving user input on all design decisions.
+
 Bootstrap via milestone-level init:
 
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init milestone-op)
+INIT=$(sdd-sdk query init.milestone-op)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
@@ -48,7 +68,10 @@ Display startup banner:
  Phases: {phase_count} total, {completed_phases} complete
 ```
 
-If `FROM_PHASE` is set, display: `Starting from phase ${FROM_PHASE}`
+If `ONLY_PHASE` is set, display: `Single phase mode: Phase ${ONLY_PHASE}`
+Else if `FROM_PHASE` is set, display: `Starting from phase ${FROM_PHASE}`
+If `TO_PHASE` is set, display: `Stopping after phase ${TO_PHASE}`
+If `INTERACTIVE` is set, display: `Mode: Interactive (discuss inline, plan+execute in background)`
 
 </step>
 
@@ -59,7 +82,7 @@ If `FROM_PHASE` is set, display: `Starting from phase ${FROM_PHASE}`
 Run phase discovery:
 
 ```bash
-ROADMAP=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" roadmap analyze)
+ROADMAP=$(sdd-sdk query roadmap.analyze)
 ```
 
 Parse the JSON `phases` array.
@@ -68,6 +91,26 @@ Parse the JSON `phases` array.
 
 **Apply `--from N` filter:** If `FROM_PHASE` was provided, additionally filter out phases where `number < FROM_PHASE` (use numeric comparison — handles decimal phases like "5.1").
 
+**Apply `--to N` filter:** If `TO_PHASE` was provided, additionally filter out phases where `number > TO_PHASE` (use numeric comparison). This limits execution to phases up through the target phase.
+
+**Apply `--only N` filter:** If `ONLY_PHASE` was provided, additionally filter OUT phases where `number != ONLY_PHASE`. This means the phase list will contain exactly one phase (or zero if already complete).
+
+**If `TO_PHASE` is set and no phases remain** (all phases up to N are already completed):
+
+```
+All phases through ${TO_PHASE} are already completed. Nothing to do.
+```
+
+Exit cleanly.
+
+**If `ONLY_PHASE` is set and no phases remain** (phase already complete):
+
+```
+Phase ${ONLY_PHASE} is already complete. Nothing to do.
+```
+
+Exit cleanly.
+
 **Sort by `number`** in numeric ascending order.
 
 **If no incomplete phases remain:**
@@ -98,7 +141,7 @@ Exit cleanly.
 **Fetch details for each phase:**
 
 ```bash
-DETAIL=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" roadmap get-phase ${PHASE_NUM})
+DETAIL=$(sdd-sdk query roadmap.get-phase ${PHASE_NUM})
 ```
 
 Extract `phase_name`, `goal`, `success_criteria` from each. Store for use in execute_phase and transition messages.
@@ -117,14 +160,16 @@ For the current phase, display the progress banner:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-Where N = current phase number (from the ROADMAP, e.g., 6), T = total milestone phases (from `phase_count` parsed in initialize step, e.g., 8), P = percentage of all milestone phases completed so far. Calculate P as: (number of phases with `disk_status` "complete" from the latest `roadmap analyze` / T × 100). Use █ for filled and ░ for empty segments in the progress bar (8 characters wide).
+Where N = current phase number (from the ROADMAP, e.g., 63), T = total milestone phases (from `phase_count` parsed in initialize step, e.g., 67). **Important:** T must be `phase_count` (the total number of phases in this milestone), NOT the count of remaining/incomplete phases. When phases are numbered 61-67, T=7 and the banner should read `Phase 63/7` (phase 63, 7 total in milestone), not `Phase 63/3` (which would confuse 3 remaining with 3 total). P = percentage of all milestone phases completed so far. Calculate P as: (number of phases with `disk_status` "complete" from the latest `roadmap analyze` / T × 100). Use █ for filled and ░ for empty segments in the progress bar (8 characters wide).
+
+**Alternative display when phase numbers exceed total** (e.g., multi-milestone projects where phases are numbered globally): If N > T (phase number exceeds milestone phase count), use the format `Phase {N} ({position}/{T})` where `position` is the 1-based index of this phase among incomplete phases being processed. This prevents confusing displays like "Phase 63/5".
 
 **3a. Smart Discuss**
 
 Check if CONTEXT.md already exists for this phase:
 
 ```bash
-PHASE_STATE=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init phase-op ${PHASE_NUM})
+PHASE_STATE=$(sdd-sdk query init.phase-op ${PHASE_NUM})
 ```
 
 Parse `has_context` from JSON.
@@ -140,7 +185,7 @@ Proceed to 3b.
 **If has_context is false:** Check if discuss is disabled via settings:
 
 ```bash
-SKIP_DISCUSS=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" config-get workflow.skip_discuss 2>/dev/null || echo "false")
+SKIP_DISCUSS=$(sdd-sdk query config-get workflow.skip_discuss 2>/dev/null || echo "false")
 ```
 
 **If SKIP_DISCUSS is `true`:** Skip discuss entirely — the ROADMAP phase description is the spec. Display:
@@ -152,7 +197,7 @@ Phase ${PHASE_NUM}: Discuss skipped (workflow.skip_discuss=true) — using ROADM
 Write a minimal CONTEXT.md so downstream plan-phase has valid input. Get phase details:
 
 ```bash
-DETAIL=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" roadmap get-phase ${PHASE_NUM})
+DETAIL=$(sdd-sdk query roadmap.get-phase ${PHASE_NUM})
 ```
 
 Extract `goal` and `requirements` from JSON. Write `${phase_dir}/${padded_phase}-CONTEXT.md` with:
@@ -204,27 +249,38 @@ None — discuss phase skipped.
 Commit the minimal context:
 
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs(${PADDED_PHASE}): auto-generated context (discuss skipped)" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
+sdd-sdk query commit "docs(${PADDED_PHASE}): auto-generated context (discuss skipped)" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
 ```
 
 Proceed to 3b.
 
-**If SKIP_DISCUSS is `false` (or unset):** Execute the smart_discuss step for this phase.
+**If SKIP_DISCUSS is `false` (or unset):**
+
+**IMPORTANT — Discuss must be single-pass in autonomous mode.**
+The discuss step in `--auto` mode MUST NOT loop. If CONTEXT.md already exists after discuss completes, do NOT re-invoke discuss for the same phase. The `has_context` check below is authoritative — once true, discuss is done for this phase regardless of perceived "gaps" in the context file.
+
+**If `INTERACTIVE` is set:** Run the standard discuss-phase skill inline (asks interactive questions, waits for user answers). This preserves user input on all design decisions while keeping plan+execute out of the main context:
 
-After smart_discuss completes, verify context was written:
+```
+Skill(skill="sdd-discuss-phase", args="${PHASE_NUM}")
+```
+
+**If `INTERACTIVE` is NOT set:** Execute the smart_discuss step for this phase (batch table proposals, auto-optimized).
+
+After discuss completes (either mode), verify context was written:
 
 ```bash
-PHASE_STATE=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init phase-op ${PHASE_NUM})
+PHASE_STATE=$(sdd-sdk query init.phase-op ${PHASE_NUM})
 ```
 
-Check `has_context`. If false → go to handle_blocker: "Smart discuss for phase ${PHASE_NUM} did not produce CONTEXT.md."
+Check `has_context`. If false → go to handle_blocker: "Discuss for phase ${PHASE_NUM} did not produce CONTEXT.md."
 
 **3a.5. UI Design Contract (Frontend Phases)**
 
 Check if this phase has frontend indicators and whether a UI-SPEC already exists:
 
 ```bash
-PHASE_SECTION=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" roadmap get-phase ${PHASE_NUM} 2>/dev/null)
+PHASE_SECTION=$(sdd-sdk query roadmap.get-phase ${PHASE_NUM} 2>/dev/null)
 echo "$PHASE_SECTION" | grep -iE "UI|interface|frontend|component|layout|page|screen|view|form|dashboard|widget" > /dev/null 2>&1
 HAS_UI=$?
 UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
@@ -233,7 +289,7 @@ UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
 Check if UI phase workflow is enabled:
 
 ```bash
-UI_PHASE_CFG=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" config-get workflow.ui_phase 2>/dev/null || echo "true")
+UI_PHASE_CFG=$(sdd-sdk query config-get workflow.ui_phase 2>/dev/null || echo "true")
 ```
 
 **If `HAS_UI` is 0 (frontend indicators found) AND `UI_SPEC_FILE` is empty (no UI-SPEC exists) AND `UI_PHASE_CFG` is not `false`:**
@@ -245,7 +301,7 @@ Phase ${PHASE_NUM}: Frontend phase detected — generating UI design contract...
 ```
 
 ```
-Skill(skill="sdd:ui-phase", args="${PHASE_NUM}")
+Skill(skill="sdd-ui-phase", args="${PHASE_NUM}")
 ```
 
 Verify UI-SPEC was created:
@@ -260,21 +316,72 @@ UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
 
 **3b. Plan**
 
+**If `INTERACTIVE` is set:** Dispatch plan as a background agent to keep the main context lean. While plan runs, the workflow can immediately start discussing the next phase (see step 4).
+
 ```
-Skill(skill="sdd:plan-phase", args="${PHASE_NUM}")
+Agent(
+  description="Plan phase ${PHASE_NUM}: ${PHASE_NAME}",
+  run_in_background=true,
+  prompt="Run plan-phase for phase ${PHASE_NUM}: Skill(skill=\"sdd-plan-phase\", args=\"${PHASE_NUM}\")"
+)
+```
+
+Store the agent task_id. After discuss for the next phase completes (or if no next phase), wait for the plan agent to finish before proceeding to execute.
+
+**If `INTERACTIVE` is NOT set (default):** Run plan inline as before.
+
+```
+Skill(skill="sdd-plan-phase", args="${PHASE_NUM}")
 ```
 
 Verify plan produced output — re-run `init phase-op` and check `has_plans`. If false → go to handle_blocker: "Plan phase ${PHASE_NUM} did not produce any plans."
 
 **3c. Execute**
 
+**If `INTERACTIVE` is set:** Wait for the plan agent to complete (if not already), verify plans exist, then dispatch execute as a background agent:
+
+```
+Agent(
+  description="Execute phase ${PHASE_NUM}: ${PHASE_NAME}",
+  run_in_background=true,
+  prompt="Run execute-phase for phase ${PHASE_NUM}: Skill(skill=\"sdd-execute-phase\", args=\"${PHASE_NUM} --no-transition\")"
+)
+```
+
+Store the agent task_id. The workflow can now start discussing the next phase while this phase executes in the background. Before starting post-execution routing for this phase, wait for the execute agent to complete.
+
+**If `INTERACTIVE` is NOT set (default):** Run execute inline as before.
+
+```
+Skill(skill="sdd-execute-phase", args="${PHASE_NUM} --no-transition")
+```
+
+**3c.5. Code Review and Fix**
+
+Auto-invoke code review and fix chain. Autonomous mode chains both review and fix (unlike execute-phase/quick which only suggest fix).
+
+**Config gate:**
+```bash
+CODE_REVIEW_ENABLED=$(sdd-sdk query config-get workflow.code_review 2>/dev/null || echo "true")
+```
+If `"false"`: display "Code review skipped (workflow.code_review=false)" and proceed to 3d.
+
+```
+Skill(skill="sdd-code-review", args="${PHASE_NUM}")
+```
+
+Parse status from REVIEW.md frontmatter. If "clean" or "skipped": proceed to 3d. If findings found: auto-invoke:
 ```
-Skill(skill="sdd:execute-phase", args="${PHASE_NUM} --no-transition")
+Skill(skill="sdd-code-review", args="${PHASE_NUM} --fix --auto")
 ```
 
+**Error handling:** If either Skill fails, catch the error, display as non-blocking, and proceed to 3d.
+
 **3d. Post-Execution Routing**
 
-After execute-phase returns, read the verification result:
+**If `INTERACTIVE` is set:** Wait for the execute agent to complete before reading verification results.
+
+After execute-phase returns (or the execute agent completes), read the verification result:
 
 ```bash
 VERIFY_STATUS=$(grep "^status:" "${PHASE_DIR}"/*-VERIFICATION.md 2>/dev/null | head -1 | cut -d: -f2 | tr -d ' ')
@@ -283,7 +390,7 @@ VERIFY_STATUS=$(grep "^status:" "${PHASE_DIR}"/*-VERIFICATION.md 2>/dev/null | h
 Where `PHASE_DIR` comes from the `init phase-op` call already made in step 3a. If the variable is not in scope, re-fetch:
 
 ```bash
-PHASE_STATE=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init phase-op ${PHASE_NUM})
+PHASE_STATE=$(sdd-sdk query init.phase-op ${PHASE_NUM})
 ```
 
 Parse `phase_dir` from the JSON.
@@ -305,6 +412,8 @@ Proceed to iterate step.
 
 Read the human_verification section from VERIFICATION.md to get the count and items requiring manual testing.
 
+
+**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.
 Display the items, then ask user via AskUserQuestion:
 - **question:** "Phase ${PHASE_NUM} has items needing manual verification. Validate now or continue to next phase?"
 - **options:** "Validate now" / "Continue without validation"
@@ -334,14 +443,14 @@ Ask user via AskUserQuestion:
 On **"Run gap closure"**: Execute gap closure cycle (limit: 1 attempt):
 
 ```
-Skill(skill="sdd:plan-phase", args="${PHASE_NUM} --gaps")
+Skill(skill="sdd-plan-phase", args="${PHASE_NUM} --gaps")
 ```
 
 Verify gap plans were created — re-run `init phase-op ${PHASE_NUM}` and check `has_plans`. If no new gap plans → go to handle_blocker: "Gap closure planning for phase ${PHASE_NUM} did not produce plans."
 
 Re-execute:
 ```
-Skill(skill="sdd:execute-phase", args="${PHASE_NUM} --no-transition")
+Skill(skill="sdd-execute-phase", args="${PHASE_NUM} --no-transition")
 ```
 
 Re-read verification status:
@@ -377,7 +486,7 @@ UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
 Check if UI review is enabled:
 
 ```bash
-UI_REVIEW_CFG=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" config-get workflow.ui_review 2>/dev/null || echo "true")
+UI_REVIEW_CFG=$(sdd-sdk query config-get workflow.ui_review 2>/dev/null || echo "true")
 ```
 
 **If `UI_SPEC_FILE` is not empty AND `UI_REVIEW_CFG` is not `false`:**
@@ -389,7 +498,7 @@ Phase ${PHASE_NUM}: Frontend phase with UI-SPEC — running UI review audit...
 ```
 
 ```
-Skill(skill="sdd:ui-review", args="${PHASE_NUM}")
+Skill(skill="sdd-ui-review", args="${PHASE_NUM}")
 ```
 
 Display the review result summary (score from UI-REVIEW.md if produced). Continue to iterate step regardless of score — UI review is advisory, not blocking.
@@ -402,299 +511,47 @@ Display the review result summary (score from UI-REVIEW.md if produced). Continu
 
 ## Smart Discuss
 
-Run smart discuss for the current phase. Proposes grey area answers in batch tables — the user accepts or overrides per area. Produces identical CONTEXT.md output to regular discuss-phase.
-
-> **Note:** Smart discuss is an autonomous-optimized variant of the `sdd:discuss-phase` skill. It produces identical CONTEXT.md output but uses batch table proposals instead of sequential questioning. The original `discuss-phase` skill remains unchanged (per CTRL-03). Future milestones may extract this to a separate skill file.
-
-**Inputs:** `PHASE_NUM` from execute_phase. Run init to get phase paths:
-
-```bash
-PHASE_STATE=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init phase-op ${PHASE_NUM})
-```
-
-Parse from JSON: `phase_dir`, `phase_slug`, `padded_phase`, `phase_name`.
-
----
-
-### Sub-step 1: Load prior context
-
-Read project-level and prior phase context to avoid re-asking decided questions.
-
-**Read project files:**
-
-```bash
-cat .planning/PROJECT.md 2>/dev/null || true
-cat .planning/REQUIREMENTS.md 2>/dev/null || true
-cat .planning/STATE.md 2>/dev/null || true
-```
-
-Extract from these:
-- **PROJECT.md** — Vision, principles, non-negotiables, user preferences
-- **REQUIREMENTS.md** — Acceptance criteria, constraints, must-haves vs nice-to-haves
-- **STATE.md** — Current progress, decisions logged so far
-
-**Read all prior CONTEXT.md files:**
-
-```bash
-(find .planning/phases -name "*-CONTEXT.md" 2>/dev/null || true) | sort
-```
-
-For each CONTEXT.md where phase number < current phase:
-- Read the `<decisions>` section — these are locked preferences
-- Read `<specifics>` — particular references or "I want it like X" moments
-- Note patterns (e.g., "user consistently prefers minimal UI", "user rejected verbose output")
-
-**Build internal prior_decisions context** (do not write to file):
+> Full instructions are in `sdd/references/autonomous-smart-discuss.md`. Read that file now and follow it exactly.
 
-```
-<prior_decisions>
-## Project-Level
-- [Key principle or constraint from PROJECT.md]
-- [Requirement affecting this phase from REQUIREMENTS.md]
-
-## From Prior Phases
-### Phase N: [Name]
-- [Decision relevant to current phase]
-- [Preference that establishes a pattern]
-</prior_decisions>
-```
-
-If no prior context exists, continue without — expected for early phases.
-
----
-
-### Sub-step 2: Scout Codebase
-
-Lightweight codebase scan to inform grey area identification and proposals. Keep under ~5% context.
-
-**Check for existing codebase maps:**
-
-```bash
-ls .planning/codebase/*.md 2>/dev/null || true
-```
-
-**If codebase maps exist:** Read the most relevant ones (CONVENTIONS.md, STRUCTURE.md, STACK.md based on phase type). Extract reusable components, established patterns, integration points. Skip to building context below.
-
-**If no codebase maps, do targeted grep:**
-
-Extract key terms from the phase goal. Search for related files:
-
-```bash
-grep -rl "{term1}\|{term2}" src/ app/ --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" 2>/dev/null | head -10 || true
-ls src/components/ src/hooks/ src/lib/ src/utils/ 2>/dev/null || true
-```
-
-Read the 3-5 most relevant files to understand existing patterns.
-
-**Build internal codebase_context** (do not write to file):
-- **Reusable assets** — existing components, hooks, utilities usable in this phase
-- **Established patterns** — how the codebase does state management, styling, data fetching
-- **Integration points** — where new code connects (routes, nav, providers)
-
----
-
-### Sub-step 3: Analyze Phase and Generate Proposals
-
-**Get phase details:**
-
-```bash
-DETAIL=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" roadmap get-phase ${PHASE_NUM})
-```
+Smart discuss is an autonomous-optimized variant of `sdd-discuss-phase`. It proposes grey area answers in batch tables — the user accepts or overrides per area — and writes an identical CONTEXT.md to what discuss-phase produces.
 
-Extract `goal`, `requirements`, `success_criteria` from the JSON response.
+**Inputs:** `PHASE_NUM` from execute_phase.
 
-**Infrastructure detection — check FIRST before generating grey areas:**
+Read and execute: `$HOME/.claude/sdd/references/autonomous-smart-discuss.md`
 
-A phase is pure infrastructure when ALL of these are true:
-1. Goal keywords match: "scaffolding", "plumbing", "setup", "configuration", "migration", "refactor", "rename", "restructure", "upgrade", "infrastructure"
-2. AND success criteria are all technical: "file exists", "test passes", "config valid", "command runs"
-3. AND no user-facing behavior is described (no "users can", "displays", "shows", "presents")
-
-**If infrastructure-only:** Skip Sub-step 4. Jump directly to Sub-step 5 with minimal CONTEXT.md. Display:
-
-```
-Phase ${PHASE_NUM}: Infrastructure phase — skipping discuss, writing minimal context.
-```
-
-Use these defaults for the CONTEXT.md:
-- `<domain>`: Phase boundary from ROADMAP goal
-- `<decisions>`: Single "### Claude's Discretion" subsection — "All implementation choices are at Claude's discretion — pure infrastructure phase"
-- `<code_context>`: Whatever the codebase scout found
-- `<specifics>`: "No specific requirements — infrastructure phase"
-- `<deferred>`: "None"
-
-**If NOT infrastructure — generate grey area proposals:**
-
-Determine domain type from the phase goal:
-- Something users **SEE** → visual: layout, interactions, states, density
-- Something users **CALL** → interface: contracts, responses, errors, auth
-- Something users **RUN** → execution: invocation, output, behavior modes, flags
-- Something users **READ** → content: structure, tone, depth, flow
-- Something being **ORGANIZED** → organization: criteria, grouping, exceptions, naming
-
-Check prior_decisions — skip grey areas already decided in prior phases.
-
-Generate **3-4 grey areas** with **~4 questions each**. For each question:
-- **Pre-select a recommended answer** based on: prior decisions (consistency), codebase patterns (reuse), domain conventions (standard approaches), ROADMAP success criteria
-- Generate **1-2 alternatives** per question
-- **Annotate** with prior decision context ("You decided X in Phase N") and code context ("Component Y exists with Z variants") where relevant
-
----
-
-### Sub-step 4: Present Proposals Per Area
-
-Present grey areas **one at a time**. For each area (M of N):
-
-Display a table:
-
-```
-### Grey Area {M}/{N}: {Area Name}
-
-| # | Question | ✅ Recommended | Alternative(s) |
-|---|----------|---------------|-----------------|
-| 1 | {question} | {answer} — {rationale} | {alt1}; {alt2} |
-| 2 | {question} | {answer} — {rationale} | {alt1} |
-| 3 | {question} | {answer} — {rationale} | {alt1}; {alt2} |
-| 4 | {question} | {answer} — {rationale} | {alt1} |
-```
-
-Then prompt the user via **AskUserQuestion**:
-- **header:** "Area {M}/{N}"
-- **question:** "Accept these answers for {Area Name}?"
-- **options:** Build dynamically — always "Accept all" first, then "Change Q1" through "Change QN" for each question (up to 4), then "Discuss deeper" last. Cap at 6 explicit options max (AskUserQuestion adds "Other" automatically).
-
-**On "Accept all":** Record all recommended answers for this area. Move to next area.
-
-**On "Change QN":** Use AskUserQuestion with the alternatives for that specific question:
-- **header:** "{Area Name}"
-- **question:** "Q{N}: {question text}"
-- **options:** List the 1-2 alternatives plus "You decide" (maps to Claude's Discretion)
-
-Record the user's choice. Re-display the updated table with the change reflected. Re-present the full acceptance prompt so the user can make additional changes or accept.
-
-**On "Discuss deeper":** Switch to interactive mode for this area only — ask questions one at a time using AskUserQuestion with 2-3 concrete options per question plus "You decide". After 4 questions, prompt:
-- **header:** "{Area Name}"
-- **question:** "More questions about {area name}, or move to next?"
-- **options:** "More questions" / "Next area"
-
-If "More questions", ask 4 more. If "Next area", display final summary table of captured answers for this area and move on.
-
-**On "Other" (free text):** Interpret as either a specific change request or general feedback. Incorporate into the area's decisions, re-display updated table, re-present acceptance prompt.
-
-**Scope creep handling:** If user mentions something outside the phase domain:
-
-```
-"{Feature} sounds like a new capability — that belongs in its own phase.
-I'll note it as a deferred idea.
-
-Back to {current area}: {return to current question}"
-```
-
-Track deferred ideas internally for inclusion in CONTEXT.md.
-
----
-
-### Sub-step 5: Write CONTEXT.md
-
-After all areas are resolved (or infrastructure skip), write the CONTEXT.md file.
-
-**File path:** `${phase_dir}/${padded_phase}-CONTEXT.md`
-
-Use **exactly** this structure (identical to discuss-phase output):
-
-```markdown
-# Phase {PHASE_NUM}: {Phase Name} - Context
-
-**Gathered:** {date}
-**Status:** Ready for planning
-
-<domain>
-## Phase Boundary
-
-{Domain boundary statement from analysis — what this phase delivers}
-
-</domain>
-
-<decisions>
-## Implementation Decisions
-
-### {Area 1 Name}
-- {Accepted/chosen answer for Q1}
-- {Accepted/chosen answer for Q2}
-- {Accepted/chosen answer for Q3}
-- {Accepted/chosen answer for Q4}
-
-### {Area 2 Name}
-- {Accepted/chosen answer for Q1}
-- {Accepted/chosen answer for Q2}
-...
-
-### Claude's Discretion
-{Any "You decide" answers collected — note Claude has flexibility here}
-
-</decisions>
-
-<code_context>
-## Existing Code Insights
-
-### Reusable Assets
-- {From codebase scout — components, hooks, utilities}
-
-### Established Patterns
-- {From codebase scout — state management, styling, data fetching}
-
-### Integration Points
-- {From codebase scout — where new code connects}
-
-</code_context>
-
-<specifics>
-## Specific Ideas
-
-{Any specific references or "I want it like X" from discussion}
-{If none: "No specific requirements — open to standard approaches"}
-
-</specifics>
-
-<deferred>
-## Deferred Ideas
+</step>
 
-{Ideas captured but out of scope for this phase}
-{If none: "None — discussion stayed within phase scope"}
+<step name="iterate">
 
-</deferred>
-```
+## 4. Iterate
 
-Write the file.
+**If `ONLY_PHASE` is set:** Do not iterate. Proceed directly to lifecycle step (which exits cleanly per single-phase mode).
 
-**Commit:**
+**If `TO_PHASE` is set and current phase number >= `TO_PHASE`:** The target phase has been reached. Do not iterate further. Display:
 
-```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs(${PADDED_PHASE}): smart discuss context" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
 ```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SDD ► AUTONOMOUS ▸ --to ${TO_PHASE} REACHED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Display confirmation:
+ Completed through phase ${TO_PHASE} as requested.
+ Remaining phases were not executed.
 
+ Resume with: /sdd:autonomous --from ${next_incomplete_phase}
 ```
-Created: {path}
-Decisions captured: {count} across {area_count} areas
-```
-
-</step>
 
-<step name="iterate">
-
-## 4. Iterate
+Proceed directly to lifecycle step (which handles partial completion — skips audit/complete/cleanup since not all phases are done). Exit cleanly.
 
-After each phase completes, re-read ROADMAP.md to catch phases inserted mid-execution (decimal phases like 5.1):
+**Otherwise:** After each phase completes, re-read ROADMAP.md to catch phases inserted mid-execution (decimal phases like 5.1):
 
 ```bash
-ROADMAP=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" roadmap analyze)
+ROADMAP=$(sdd-sdk query roadmap.analyze)
 ```
 
 Re-filter incomplete phases using the same logic as discover_phases:
 - Keep phases where `disk_status !== "complete"` OR `roadmap_complete === false`
 - Apply `--from N` filter if originally provided
+- Apply `--to N` filter if originally provided
 - Sort by number ascending
 
 Read STATE.md fresh:
@@ -707,6 +564,13 @@ Check for blockers in the Blockers/Concerns section. If blockers are found, go t
 
 If incomplete phases remain: proceed to next phase, loop back to execute_phase.
 
+**Interactive mode overlap:** When `INTERACTIVE` is set, the iterate step enables pipeline parallelism:
+1. After discuss completes for Phase N, dispatch plan+execute as background agents
+2. Immediately start discuss for Phase N+1 (the next incomplete phase) while Phase N builds
+3. Before starting plan for Phase N+1, wait for Phase N's execute agent to complete and handle its post-execution routing (verification, gap closure, etc.)
+
+This means the user is always answering discuss questions (lightweight, interactive) while the heavy work (planning, code generation) runs in the background. The main context only accumulates discuss conversations — plan and execute contexts are isolated in their agents.
+
 If all phases complete, proceed to lifecycle step.
 
 </step>
@@ -715,7 +579,23 @@ If all phases complete, proceed to lifecycle step.
 
 ## 5. Lifecycle
 
-After all phases complete, run the milestone lifecycle sequence: audit → complete → cleanup.
+**If `ONLY_PHASE` is set:** Skip lifecycle. A single phase does not trigger audit/complete/cleanup. Display:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SDD ► AUTONOMOUS ▸ PHASE ${ONLY_PHASE} COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Phase ${ONLY_PHASE}: ${PHASE_NAME} — Done
+ Mode: Single phase (--only)
+
+ Lifecycle skipped — run /sdd:autonomous without --only
+ after all phases complete to trigger audit/complete/cleanup.
+```
+
+Exit cleanly.
+
+**Otherwise:** After all phases complete, run the milestone lifecycle sequence: audit → complete → cleanup.
 
 Display lifecycle transition banner:
 
@@ -731,7 +611,7 @@ Display lifecycle transition banner:
 **5a. Audit**
 
 ```
-Skill(skill="sdd:audit-milestone")
+Skill(skill="sdd-audit-milestone")
 ```
 
 After audit completes, detect the result:
@@ -787,7 +667,7 @@ On **"Stop"**: Go to handle_blocker with "User stopped — tech debt to address.
 **5b. Complete Milestone**
 
 ```
-Skill(skill="sdd:complete-milestone", args="${milestone_version}")
+Skill(skill="sdd-complete-milestone", args="${milestone_version}")
 ```
 
 After complete-milestone returns, verify it produced output:
@@ -801,7 +681,7 @@ If the archive file does not exist, go to handle_blocker: "Complete milestone di
 **5c. Cleanup**
 
 ```
-Skill(skill="sdd:cleanup")
+Skill(skill="sdd-cleanup")
 ```
 
 Cleanup shows its own dry-run and asks user for approval internally — this is an acceptable pause per CTRL-01 since it's an explicit decision about file deletion.
@@ -852,7 +732,7 @@ When any phase operation fails or a blocker is detected, present 3 options via A
  Skipped: {list of skipped phases}
  Remaining: {list of remaining phases}
 
- Resume with: /sdd:autonomous --from {next_phase}
+ Resume with: /sdd:autonomous ${ONLY_PHASE ? "--only " + ONLY_PHASE : "--from " + next_phase}${TO_PHASE ? " --to " + TO_PHASE : ""}
 ```
 
 </step>
@@ -876,16 +756,34 @@ When any phase operation fails or a blocker is detected, present 3 options via A
 - [ ] Final completion or stop summary displayed
 - [ ] After all phases complete, lifecycle step is invoked (not manual suggestion)
 - [ ] Lifecycle transition banner displayed before audit
-- [ ] Audit invoked via Skill(skill="sdd:audit-milestone")
+- [ ] Audit invoked via Skill(skill="sdd-audit-milestone")
 - [ ] Audit result routing: passed → auto-continue, gaps_found → user decides, tech_debt → user decides
 - [ ] Audit technical failure (no file/no status) routes to handle_blocker
 - [ ] Complete-milestone invoked via Skill() with ${milestone_version} arg
 - [ ] Cleanup invoked via Skill() — internal confirmation is acceptable (CTRL-01)
 - [ ] Final completion banner displayed after lifecycle
-- [ ] Progress bar uses phase number / total milestone phases (not position among incomplete)
+- [ ] Progress bar uses phase number / total milestone phases (not position among incomplete), with fallback display when phase numbers exceed total
 - [ ] Smart discuss documents relationship to discuss-phase with CTRL-03 note
 - [ ] Frontend phases get UI-SPEC generated before planning (step 3a.5) if not already present
 - [ ] Frontend phases get UI review audit after successful execution (step 3d.5) if UI-SPEC exists
 - [ ] UI phase and UI review respect workflow.ui_phase and workflow.ui_review config toggles
 - [ ] UI review is advisory (non-blocking) — phase proceeds to iterate regardless of score
+- [ ] `--only N` restricts execution to exactly one phase
+- [ ] `--only N` skips lifecycle step (audit/complete/cleanup)
+- [ ] `--only N` exits cleanly after single phase completes
+- [ ] `--only N` on already-complete phase exits with message
+- [ ] `--only N` handle_blocker resume message uses --only flag
+- [ ] `--to N` stops execution after phase N completes (halts at iterate step)
+- [ ] `--to N` filters out phases with number > N during discovery
+- [ ] `--to N` displays "Stopping after phase N" in startup banner
+- [ ] `--to N` on already completed target exits with "already completed" message
+- [ ] `--to N` compatible with `--from N` (run phases from M to N)
+- [ ] `--to N` handle_blocker resume message preserves --to flag
+- [ ] `--to N` skips lifecycle when not all milestone phases complete
+- [ ] `--interactive` runs discuss inline via sdd-discuss-phase (asks questions, waits for user)
+- [ ] `--interactive` dispatches plan and execute as background agents (context isolation)
+- [ ] `--interactive` enables pipeline parallelism: discuss Phase N+1 while Phase N builds
+- [ ] `--interactive` main context only accumulates discuss conversations (lean)
+- [ ] `--interactive` waits for background agents before post-execution routing
+- [ ] `--interactive` compatible with `--only`, `--from`, and `--to` flags
 </success_criteria>