sdlc-framework 2.1.1 → 3.0.0

package/README.md

@@ -40,7 +40,7 @@ AI-assisted development has a quality problem. Research shows:
 
 SDLC fixes all of this with five principles:
 
-1. **Closed loop** — SPEC → IMPLEMENT → VERIFY → REVIEW → CLOSE. Every step forces the next. No orphan plans. No skipped reviews.
+1. **Closed loop** — SPEC → IMPLEMENT → VERIFY → REVIEW → CLOSE. Steps auto-advance with a 10-second delay — reply to intervene. No orphan plans. No skipped reviews.
 
 2. **Engineering Laws** — SOLID, DRY, YAGNI, Clean Code, Security, and Testing are enforced as blocking gates at review. Not suggestions. Laws.
 
@@ -85,8 +85,8 @@ Choose global (all projects) or local (current project only). Verify with `/sdlc
 # 4. Build it (spawns parallel sub-agents)
 /sdlc:impl
 
-# 5. The framework forces verify → review → close automatically
-# Just follow the NEXT ACTION REQUIRED prompts
+# 5. Steps auto-advance with 10s delay — reply to intervene
+# The framework chains verify → review → close automatically
 ```
 
 ### Just Tell It What To Do
@@ -126,9 +126,10 @@ Follows: reproduce → isolate → root-cause → fix → verify.
 ### DISCUSS — Explore the idea (optional, pre-loop)
 
 - AI-driven brainstorming — you describe an idea, AI asks structured questions
-- 4 rounds max: problem space → scope → approach validation → requirements detail
+- 4 rounds max: problem space → scope → research unknowns → approach validation → requirements detail
+- Spawns research subagents when unknowns are detected (codebase patterns, external APIs, library choices)
 - Every question includes a recommendation with concrete trade-offs
-- Produces a PRD document at `.sdlc/discuss/{topic}-PRD.md`
+- Produces a PRD document at `.sdlc/discuss/{topic}-PRD.md` with research findings included
 - **User approval gate** — PRD must be approved before routing to `/sdlc:spec`
 
 ### SPEC — Define the work
@@ -168,21 +169,14 @@ Follows: reproduce → isolate → root-cause → fix → verify.
 - Reconciles spec vs actual implementation
 - Records deviations, decisions, lessons
 - Creates SUMMARY.md for audit trail
-- Advances state to next plan or triggers phase transition
-
-### TRANSITION — Advance to next phase
-
-- Verifies all plans in the current phase are complete
-- Cross-checks STATE.md, PROJECT.md, and ROADMAP.md for consistency
-- Updates PROJECT.md with implemented and newly discovered requirements
-- Creates a git commit at the phase boundary
-- Advances state to the first spec of the next phase
+- Advances state to next plan or handles phase transition inline
+- Phase transitions: verifies completeness, updates PROJECT.md, creates git commit, advances to next phase
 
 ---
 
 ## Commands
 
-14 commands, grouped by purpose. Run `/sdlc:help` for the full reference.
+12 commands, grouped by purpose. Run `/sdlc:help` for the full reference.
 
 ### Core Loop
 
@@ -192,8 +186,7 @@ Follows: reproduce → isolate → root-cause → fix → verify.
 | `/sdlc:impl` | Build via parallel sub-agents | → `/sdlc:verify` |
 | `/sdlc:verify` | Automated testing (Playwright MCP) | → `/sdlc:review` |
 | `/sdlc:review` | Engineering laws compliance check | → `/sdlc:close` |
-| `/sdlc:close` | Reconcile and close the loop | → `/sdlc:spec` or → `/sdlc:transition` |
-| `/sdlc:transition` | Advance to next phase when all plans complete | → `/sdlc:spec` |
+| `/sdlc:close` | Close the loop. Handles phase transitions and milestone completion inline | → `/sdlc:spec` |
 
 ### Quick Entry
 
@@ -216,12 +209,11 @@ Follows: reproduce → isolate → root-cause → fix → verify.
 | `/sdlc:status pause` | Save context for break, create HANDOFF.md |
 | `/sdlc:status resume` | Restore context, ONE next action |
 
-### Planning & Research
+### Planning & Discovery
 
 | Command | What it does |
 |---------|-------------|
-| `/sdlc:discuss [idea]` | Brainstorm an idea — AI asks questions, produces a PRD |
-| `/sdlc:research <topic>` | Deploy research sub-agents |
+| `/sdlc:discuss [idea]` | Brainstorm and research — AI asks questions, spawns research subagents for unknowns, produces a PRD |
 
 ### Setup
 
@@ -268,7 +260,7 @@ Severity is configurable per project in `.sdlc/LAWS.md`:
 │       ├── 01-01-REVIEW.md
 │       └── 01-01-SUMMARY.md
 ├── discuss/            # PRD documents from /sdlc:discuss
-└── research/           # Sub-agent research output
+└── research/           # Research findings (generated by /sdlc:discuss when unknowns detected)
 ```
 
 ---
@@ -279,7 +271,7 @@ Severity is configurable per project in `.sdlc/LAWS.md`:
 
 | Aspect | PAUL | SDLC |
 |--------|------|------|
-| Commands | 26 (cognitive overload) | 14 (focused) |
+| Commands | 26 (cognitive overload) | 12 (focused) |
 | Testing | Manual UAT | Automated (Playwright MCP) |
 | Code review | None | Engineering Laws enforcement |
 | Implementation | In-session | Sub-agent parallel waves |
@@ -333,6 +325,17 @@ npx sdlc-framework@latest
 
 ---
 
+## What's New in v3.0.0
+
+**Fewer commands, faster flow, zero idle time.**
+
+- **Research merged into Discuss** — `/sdlc:discuss` now spawns research subagents inline when unknowns are detected. No separate `/sdlc:research` command needed. One entry point for all pre-spec discovery.
+- **Transition absorbed into Close** — `/sdlc:close` handles phase transitions inline when the last plan completes. Phase completeness verification, PROJECT.md updates, git commits — all automatic. No separate `/sdlc:transition` command.
+- **Auto-advance (10s timeout)** — Steps chain automatically. After each step completes, the next command runs after a 10-second delay. Reply during the delay to intervene. Disable with `auto_advance: false` in `.sdlc/STATE.md`.
+- **12 commands** (down from 14) — Less to learn, same power.
+
+---
+
 ## License
 
 MIT License. See [LICENSE](LICENSE) for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdlc-framework",
-  "version": "2.1.1",
+  "version": "3.0.0",
   "description": "Structured Development Lifecycle - A closed-loop AI-assisted development framework for Claude Code",
   "bin": {
     "sdlc-framework": "bin/install.js"

package/src/commands/close.md

@@ -1,12 +1,12 @@
 ---
 name: sdlc:close
-description: Reconcile spec vs actual and close the loop
+description: Reconcile spec vs actual, close the loop, handle phase transitions and milestone completion inline
 argument-hint: "[spec-path]"
-allowed-tools: [Read, Write, Bash, Glob, Grep, Edit]
+allowed-tools: [Read, Write, Bash, Glob, Grep, Edit, AskUserQuestion]
 ---
 
 <objective>
-Close the current SDLC loop by reconciling what was planned (SPEC.md) against what was built (IMPL.md, VERIFY.md, REVIEW.md). Record deviations, decisions, and lessons learned. Advance the state to the next plan or phase.
+Close the current SDLC loop by reconciling what was planned (SPEC.md) against what was built (IMPL.md, VERIFY.md, REVIEW.md). Record deviations, decisions, and lessons learned. Advance the state to the next plan or phase. When the last plan in a phase completes, execute the phase transition inline — verify completeness, update PROJECT.md, advance the roadmap, and commit the phase boundary.
 
 **When to use:** After /sdlc:review completes with no blockers. This is the CLOSE phase of the SDLC loop.
 
@@ -16,10 +16,11 @@ Close the current SDLC loop by reconciling what was planned (SPEC.md) against wh
 3. Record deviations with reasons (scope changes, discovered complexity, design pivots).
 4. Create SUMMARY.md with deliverables, results, deviations, decisions, and lessons.
 5. Update STATE.md to advance to the next plan or phase.
+6. If this was the last plan in a phase: execute the full phase transition inline (completeness check, PROJECT.md update, ROADMAP.md update, git commit).
 
 **What happens next:**
 - More plans in the current phase: Framework directs you to /sdlc:spec for the next plan.
-- Phase complete (all plans done): Framework advances to the next phase and directs to /sdlc:spec.
+- Phase complete (all plans done): Framework executes the phase transition inline, then directs to /sdlc:spec for the first plan of the new phase.
 - Milestone complete (all phases done): Framework generates milestone summary, creates git tag, and advances to next milestone or marks project complete.
 - All milestones complete: Project is done.
 
@@ -30,6 +31,7 @@ Close the current SDLC loop by reconciling what was planned (SPEC.md) against wh
 @~/.claude/sdlc-framework/workflows/close-phase.md
 @.sdlc/STATE.md
 @.sdlc/ROADMAP.md
+@.sdlc/PROJECT.md
 </execution_context>
 
 <context>
@@ -38,6 +40,7 @@ $ARGUMENTS — optional path to SPEC.md. If not provided, read from .sdlc/STATE.
 Read these files:
 - .sdlc/STATE.md — current plan, all artifact paths.
 - .sdlc/ROADMAP.md — milestones, phases, plans to determine next steps.
+- .sdlc/PROJECT.md — requirements to update during phase transitions.
 - .sdlc/specs/SPEC-<plan-id>.md — what was planned.
 - .sdlc/impl/IMPL-<plan-id>.md — what was built.
 - .sdlc/verify/VERIFY-<plan-id>.md — what was verified.
@@ -172,10 +175,19 @@ Step-by-step:
 9. **Determine and output next action**
    - If more plans in the current phase:
      - Output: "Plan <plan-id> complete. Next plan: <next-plan-id>."
-     - End with: NEXT ACTION REQUIRED: /sdlc:spec
-   - If phase is complete but more phases exist:
-     - Output: "Phase <phase-name> complete. Next phase: <next-phase-name>."
-     - End with: NEXT ACTION REQUIRED: /sdlc:spec
+     - End with auto-advance directive to /sdlc:spec
+
+   - If phase is complete (last plan done) — execute phase transition inline:
+     a. **Verify phase completeness:** List all SPEC and SUMMARY files in .sdlc/phases/{current_phase}/. Every SPEC must have a corresponding SUMMARY. Every SUMMARY must show all ACs passed. If not, block: "Phase transition blocked. Plan {N} has no summary or failing ACs."
+     b. **Cross-check consistency:** Verify STATE.md current_milestone matches ROADMAP.md in-progress milestone. Verify prior phases in this milestone are all COMPLETE. If inconsistency found: display details, offer auto-fix, ask for confirmation.
+     c. **Update PROJECT.md:** Read all SUMMARY.md files from the completing phase. Mark addressed requirements as IMPLEMENTED. Mark contradicted requirements as SUPERSEDED. Add newly discovered requirements as NOT STARTED. Display proposed changes and ask user to confirm before writing.
+     d. **Update ROADMAP.md:** Mark completed phase as COMPLETE with date. Add phase summary note (plans executed, hotfixes, key deliverables, duration from first spec to completion).
+     e. **Advance state:** Update STATE.md — set current_phase to next phase, clear current_plan, set loop_position to SPEC, set next_required_action to /sdlc:spec. Update ROADMAP.md — set next phase to IN PROGRESS.
+     f. **If no next phase (last phase in milestone):** Do not advance to a new phase. Set next_required_action to milestone completion (step 10 handles this).
+     g. **Create git commit** (if in a git repo): Stage .sdlc/ files and source files from the phase. Commit: `feat({phase-name}): complete phase {number}`
+     h. Output: "Phase <phase-name> complete. Next phase: <next-phase-name>."
+     i. End with auto-advance directive to /sdlc:spec
+
    - If milestone is complete: run milestone completion (step 10).
    - If all milestones are complete:
      - Output: "All milestones complete. Project roadmap fulfilled."
@@ -191,7 +203,7 @@ Step-by-step:
     d. Mark milestone as COMPLETE in ROADMAP.md with completion date.
     e. Check for next milestone in ROADMAP.md:
        - If exists: set as current in STATE.md.
-         Output: "Milestone complete. Next: {name}. NEXT ACTION REQUIRED: /sdlc:spec"
+         End with auto-advance directive to /sdlc:spec with message: "Milestone complete. Next: {name}."
        - If none: clear current_milestone.
          Output: "Milestone complete. No further milestones. Run /sdlc:init milestone <name> to plan the next."
 </process>
@@ -209,6 +221,7 @@ Step-by-step:
 - [ ] STATE.md updated: loop_position reset to SPEC, current plan advanced
 - [ ] ROADMAP.md updated: completed plan/phase/milestone marked as done
 - [ ] Correct next action determined based on roadmap position
+- [ ] Phase transition (when last plan completes): completeness verified, PROJECT.md updated, ROADMAP.md updated with phase summary, git commit created
 - [ ] Milestone completion: summary generated, git tag created, ROADMAP.md updated (when applicable)
-- [ ] Output ends with NEXT ACTION REQUIRED: /sdlc:spec (or project complete message)
+- [ ] Output ends with auto-advance directive to /sdlc:spec (or project complete message)
 </success_criteria>

package/src/commands/debug.md

@@ -107,7 +107,7 @@ Step-by-step:
 
 8. **Update STATE.md and force next action**
    - Update .sdlc/STATE.md: record the debug session, files changed.
-   - Output: "NEXT ACTION REQUIRED: /sdlc:review — validate the fix meets engineering standards."
+   - End with auto-advance directive to /sdlc:review.
 </process>
 
 <success_criteria>
@@ -120,5 +120,5 @@ Step-by-step:
 - [ ] Similar bugs in other locations identified and fixed
 - [ ] DEBUG-LOG.md created in .sdlc/debug-logs/
 - [ ] STATE.md updated
-- [ ] Output ends with NEXT ACTION REQUIRED: /sdlc:review
+- [ ] Output ends with auto-advance directive to /sdlc:review
 </success_criteria>

package/src/commands/discuss.md

@@ -1,25 +1,27 @@
 ---
 name: sdlc:discuss
-description: Brainstorm and shape an idea into a complete PRD through AI-driven questioning
+description: Brainstorm an idea into a PRD. Spawns research subagents when unknowns are detected.
 argument-hint: "[idea or topic]"
-allowed-tools: [Read, Write, Glob, Grep, AskUserQuestion]
+allowed-tools: [Read, Write, Glob, Grep, Agent, WebSearch, WebFetch, AskUserQuestion]
 ---
 
 <objective>
-Drive a structured brainstorming session to help the user explore, clarify, and validate an idea. Produce a complete PRD document through targeted AI-driven questions across problem, scope, approach, and requirements.
+Drive a structured brainstorming session to help the user explore, clarify, and validate an idea. Spawn research subagents inline when unknowns surface. Produce a complete PRD document through targeted AI-driven questions across problem, scope, research, approach, and requirements.
 
-**When to use:** Before /sdlc:spec when the idea is raw, vague, or needs exploration. This is the DISCOVERY phase — upstream of the SDLC loop.
+**When to use:** Before /sdlc:spec when the idea is raw, vague, or needs exploration. Also use when research is needed — external APIs, library choices, codebase patterns. This is the DISCOVERY phase — upstream of the SDLC loop.
 
 **What it does:**
 1. Accept a raw idea or topic from the user.
 2. Ask structured questions in rounds: problem, scope, approach, requirements.
-3. Validate ideas and offer recommendations with concrete trade-offs.
-4. Compile all decisions into a PRD document.
-5. Boot up the SDLC loop by routing to /sdlc:spec with the PRD as input.
+3. Between scope and approach, detect unknowns and spawn research subagents inline (codebase exploration, web research, or both).
+4. Feed research findings directly into approach validation.
+5. Validate ideas and offer recommendations with concrete trade-offs.
+6. Compile all decisions and research findings into a PRD document.
+7. Boot up the SDLC loop by routing to /sdlc:spec with the PRD as input.
 
 **What happens next:** After user approves the PRD, framework directs to /sdlc:spec to formalize it into a specification.
 
-**Critical rule:** AI drives the conversation. Ask questions — do not assume answers. Every question includes a recommendation. Maximum 4 rounds of 2-4 questions each.
+**Critical rule:** AI drives the conversation. Ask questions — do not assume answers. Every question includes a recommendation. Maximum 4 rounds of 2-4 questions each. Research spawns inline when unknowns exist — skip research when the idea is clear enough.
 </objective>
 
 <execution_context>
@@ -37,6 +39,7 @@ Read these files if they exist:
 - .sdlc/STATE.md — current loop position (discuss can run at any point).
 - .sdlc/PROJECT.md — project context, tech stack, existing architecture.
 - .sdlc/ROADMAP.md — milestones and phases for context.
+- .sdlc/research/*.md — prior research findings for reuse.
 
 Scan the codebase to understand existing patterns and constraints.
 </context>
@@ -53,13 +56,15 @@ Step-by-step:
 2. **Run question rounds** (max 4 rounds, 2-4 questions per round)
    - Round 1: Problem space — who, what, why, current workarounds.
    - Round 2: Scope and constraints — in/out, MVP, timeline, tech.
-   - Round 3: Approach validation — present options with trade-offs, ask user to choose.
+   - Round 2.5: Research unknowns — if unknowns exist (external APIs, library choices, codebase patterns, best practices), spawn research subagents inline. Classify research type (codebase, web, hybrid). Save findings to .sdlc/research/{topic-slug}.md. Skip if no unknowns identified.
+   - Round 3: Approach validation — present options with trade-offs informed by research findings, ask user to choose.
    - Round 4: Requirements detail — user flows, edge cases, integrations.
    - Each question includes a recommendation. Stop early if clarity is sufficient.
 
 3. **Compile PRD**
    - Assemble all answers into .sdlc/discuss/{topic}-PRD.md using @templates/PRD.md.
    - Include decisions log with every question asked and answer received.
+   - Include "Research Findings" section if research was conducted.
 
 4. **Present and approve**
    - Display PRD summary. User options: APPROVE, REVISE, REJECT.
@@ -67,15 +72,19 @@ Step-by-step:
 
 5. **Update STATE.md and output**
    - Record discussion reference. Set next_required_action: /sdlc:spec.
-   - End with NEXT ACTION REQUIRED: /sdlc:spec
+   - End with auto-advance directive to /sdlc:spec
 </process>
 
 <success_criteria>
 - [ ] Idea explored through at least 2 rounds of structured questions
 - [ ] Every question included a recommendation with trade-offs
+- [ ] Research subagents spawned when unknowns detected (external APIs, library choices, codebase patterns)
+- [ ] Research skipped cleanly when idea is clear and no unknowns exist
+- [ ] Research findings saved to .sdlc/research/{topic-slug}.md when applicable
 - [ ] PRD created at .sdlc/discuss/{topic}-PRD.md with all required sections
+- [ ] PRD includes Research Findings section when research was conducted
 - [ ] PRD includes decisions log mapping questions to answers
 - [ ] User explicitly approved the PRD (APPROVE response received)
 - [ ] STATE.md updated with discussion reference
-- [ ] Output ends with NEXT ACTION REQUIRED: /sdlc:spec
+- [ ] Output ends with auto-advance directive to /sdlc:spec
 </success_criteria>

package/src/commands/fast.md

@@ -11,14 +11,13 @@ The primary entry point for getting work done. Describe what you need in plain l
 **When to use:** Anytime. This is the default command for starting work. Use it instead of figuring out which specific command to run.
 
 **What it does:**
-1. Classify the work type (feature, bug, refactor, test, docs, research, critical).
+1. Classify the work type (feature, bug, refactor, test, docs, critical).
 2. Estimate complexity (files, lines, dependencies).
 3. Route based on classification and complexity:
    - Simple work (≤3 files, ≤100 lines): execute full loop inline (spec→impl→verify→review→close).
    - Complex feature: route to /sdlc:spec with pre-filled context.
    - Bug: route to /sdlc:debug with reproduction context.
-   - Research question: route to /sdlc:research with topic.
-   - Brainstorming: route to /sdlc:discuss with topic.
+   - Brainstorming or research: route to /sdlc:discuss with topic.
    - Critical production issue: execute hotfix inline (minimal spec→fix→full verify→full review).
 4. For inline execution: run compressed loop with full engineering law enforcement.
 
@@ -61,8 +60,7 @@ Step-by-step:
    |------|-----------|-------|
    | CRITICAL | "urgent", "production", "down", "outage", "critical", "P0", "hotfix" | inline hotfix |
    | BUG | "fix", "bug", "error", "broken", "crash", "fails", "wrong", "regression" | /sdlc:debug |
-   | RESEARCH | "explore", "investigate", "research", "compare", "evaluate", "options" | /sdlc:research |
-   | DISCUSS | "brainstorm", "discuss", "idea", "what if", "think about", "concept", "should we", "could we" | /sdlc:discuss |
+   | DISCUSS | "brainstorm", "discuss", "idea", "what if", "think about", "concept", "should we", "could we", "explore", "investigate", "research", "compare", "evaluate", "options" | /sdlc:discuss |
    | FEATURE | "add", "create", "build", "implement", "new", "introduce" | complexity-dependent |
    | REFACTOR | "refactor", "clean", "rename", "extract", "move", "simplify" | complexity-dependent |
    | TEST | "test", "coverage", "spec", "assertion" | complexity-dependent |
@@ -71,9 +69,8 @@ Step-by-step:
    Display: "Classified as: {type}"
 
 3. **Immediate routing** (for specialized types)
-   - BUG → Display: "Bug detected. NEXT ACTION REQUIRED: /sdlc:debug {original description}" — STOP.
-   - RESEARCH → Display: "Research task. NEXT ACTION REQUIRED: /sdlc:research {original description}" — STOP.
-   - DISCUSS → Display: "Brainstorming topic. NEXT ACTION REQUIRED: /sdlc:discuss {original description}" — STOP.
+   - BUG → Display: "Bug detected." End with auto-advance directive to /sdlc:debug — STOP.
+   - DISCUSS → Display: "Brainstorming or research topic." End with auto-advance directive to /sdlc:discuss — STOP.
    - CRITICAL → proceed to inline hotfix (step 10).
 
 4. **Complexity estimation** (for feature/refactor/test/docs)
@@ -93,10 +90,10 @@ Step-by-step:
    Task exceeds inline threshold ({N} files, ~{N} lines).
    Routing to full spec for proper task decomposition and parallel sub-agent execution.
 
-   NEXT ACTION REQUIRED: /sdlc:spec
    Context pre-loaded: {task description, identified files, estimated scope}
    ```
    Write pre-filled context to .sdlc/STATE.md fast_context field so /sdlc:spec picks it up.
+   End with auto-advance directive to /sdlc:spec.
    STOP.
 
 5. **Inline execution — Mini-SPEC**
@@ -181,8 +178,7 @@ Step-by-step:
 - [ ] Work classified correctly from natural language description
 - [ ] Bugs routed to /sdlc:debug — never processed inline
 - [ ] Critical issues handled as inline hotfix with full verify + review
-- [ ] Research tasks routed to /sdlc:research
-- [ ] Brainstorming routed to /sdlc:discuss
+- [ ] Brainstorming and research topics routed to /sdlc:discuss
 - [ ] Complex work (>3 files or >100 lines) routed to /sdlc:spec with pre-filled context
 - [ ] Simple work executed inline through full compressed loop
 - [ ] Hotfix: minimal fix, full test suite, engineering laws enforced

package/src/commands/fix.md

@@ -99,6 +99,6 @@ Step-by-step:
 - [ ] User approved the fix plan before execution
 - [ ] Sub-agents spawned for independent file fixes
 - [ ] /sdlc:review automatically re-runs after fixes
-- [ ] If review passes: output ends with NEXT ACTION REQUIRED: /sdlc:close
-- [ ] If review fails again: output ends with "New findings found. Re-run /sdlc:fix"
+- [ ] If review passes: output ends with auto-advance directive to /sdlc:close
+- [ ] If review fails again: output ends with auto-advance directive to /sdlc:fix
 </success_criteria>

package/src/commands/help.md

@@ -47,14 +47,9 @@ COMMANDS — Core Loop
   /sdlc:impl      Implement the plan. Spawns subagents to write code.
   /sdlc:verify    Run tests and Playwright checks. Confirm acceptance criteria met.
   /sdlc:review    Review code against engineering laws. Flag violations.
-  /sdlc:close     Archive the plan. Update STATE.md. Advance to next cycle.
+  /sdlc:close     Close the loop. Handles phase transitions and milestone completion inline.
 
 
-COMMANDS — Phase Management
-───────────────────────────
-
-  /sdlc:transition  Advance to the next phase after all plans complete.
-
 COMMANDS — Quick Entry
 ──────────────────────
 
@@ -77,11 +72,10 @@ COMMANDS — Session & Status
   /sdlc:status resume       Restore context. Determines ONE next action.
 
 
-COMMANDS — Planning & Research
-──────────────────────────────
+COMMANDS — Planning & Discovery
+───────────────────────────────
 
-  /sdlc:discuss   Brainstorm an idea. AI asks questions, produces a PRD.
-  /sdlc:research  Deploy subagents for codebase or web research.
+  /sdlc:discuss   Brainstorm an idea into a PRD. Spawns research subagents when unknowns are detected.
   /sdlc:init      Initialize framework or add milestones. Run once.
   /sdlc:help      Show this reference.
 
@@ -115,6 +109,13 @@ FOR BUGS
   Example: /sdlc:debug login form submits twice on slow connections
 
 
+AUTO-ADVANCE
+─────────────
+  Steps chain automatically with a 10-second delay.
+  Reply during the delay to intervene.
+  Disable: set auto_advance: false in .sdlc/STATE.md
+
+
 ENGINEERING LAWS (summary)
 ──────────────────────────
 
@@ -139,7 +140,7 @@ If .sdlc/LAWS.md exists, read it and append any project-specific law customizati
 
 <success_criteria>
 - [ ] Core loop diagram displayed
-- [ ] All 14 commands listed with one-line descriptions
+- [ ] All 12 commands listed with one-line descriptions
 - [ ] Commands grouped by purpose (core loop, shortcuts, session, planning)
 - [ ] Quick start guide shown (3 steps)
 - [ ] Small tasks shortcut mentioned (/sdlc:fast)

package/src/commands/impl.md

@@ -125,7 +125,7 @@ Step-by-step:
 
 10. **Output confirmation**
     - Print implementation summary: tasks completed, files modified, build status.
-    - End with NEXT ACTION REQUIRED.
+    - End with auto-advance directive to /sdlc:verify.
 </process>
 
 <success_criteria>
@@ -139,5 +139,5 @@ Step-by-step:
 - [ ] IMPL-<plan-id>.md created with completion summary
 - [ ] STATE.md updated with loop_position: IMPL_COMPLETE
 - [ ] No files modified outside spec boundaries
-- [ ] Output ends with NEXT ACTION REQUIRED: /sdlc:verify
+- [ ] Output ends with auto-advance directive to /sdlc:verify
 </success_criteria>

package/src/commands/init.md

@@ -82,7 +82,7 @@ Step-by-step:
 8. **Output confirmation**
    - Print summary of created files.
    - Print the first milestone and phase.
-   - End with NEXT ACTION REQUIRED.
+   - End with auto-advance directive to /sdlc:spec.
 
 ### If "milestone <name>" in $ARGUMENTS: ADD MILESTONE
 
@@ -95,7 +95,7 @@ Step-by-step:
 4. Create phase directories: mkdir -p .sdlc/phases/{phase-number}-{phase-name}
 5. Update ROADMAP.md with new milestone section, phases, and status.
 6. Update STATE.md: set current_milestone if none active. Add history entry.
-7. Output: "Milestone created. NEXT ACTION REQUIRED: /sdlc:spec"
+7. Output: "Milestone created." End with auto-advance directive to /sdlc:spec.
 </process>
 
 <success_criteria>
@@ -105,5 +105,5 @@ Step-by-step:
 - [ ] ROADMAP.md has at least one milestone with at least one phase
 - [ ] LAWS.md contains engineering laws with severity levels configured for the project type
 - [ ] No guessing — all project context gathered via clarification questions
-- [ ] Output ends with NEXT ACTION REQUIRED: /sdlc:spec
+- [ ] Output ends with auto-advance directive to /sdlc:spec
 </success_criteria>

package/src/commands/review.md

@@ -171,11 +171,11 @@ Step-by-step:
     - If ZERO blockers:
       - Update STATE.md: set `loop_position: REVIEW_COMPLETE`
       - Set `review_path: .sdlc/review/REVIEW-<plan-id>.md`
-      - Output ends with: NEXT ACTION REQUIRED: /sdlc:close
+      - End with auto-advance directive to /sdlc:close
     - If ANY blockers:
       - Update STATE.md: set `loop_position: REVIEW_FAILED`
       - List each blocker with its remediation.
-      - Output ends with: "NEXT ACTION REQUIRED: /sdlc:fix — Run /sdlc:fix to systematically fix all blockers, then re-review automatically."
+      - End with auto-advance directive to /sdlc:fix
 </process>
 
 <success_criteria>
@@ -190,6 +190,6 @@ Step-by-step:
 - [ ] REVIEW-<plan-id>.md created with all findings, severity, and remediation steps
 - [ ] Laws compliance matrix included in review report
 - [ ] Severity assigned honestly — blockers not downgraded to pass faster
-- [ ] If no blockers: output ends with NEXT ACTION REQUIRED: /sdlc:close
-- [ ] If blockers exist: output ends with NEXT ACTION REQUIRED: /sdlc:fix
+- [ ] If no blockers: output ends with auto-advance directive to /sdlc:close
+- [ ] If blockers exist: output ends with auto-advance directive to /sdlc:fix
 </success_criteria>

package/src/commands/spec.md

@@ -147,7 +147,7 @@ Step-by-step:
 
 12. **Output confirmation**
     - Print spec summary: objective, number of ACs, number of tasks, execution waves.
-    - End with NEXT ACTION REQUIRED: /sdlc:impl
+    - End with auto-advance directive to /sdlc:impl
 </process>
 
 <success_criteria>
@@ -163,5 +163,5 @@ Step-by-step:
 - [ ] SPEC.md created at .sdlc/phases/{phase}/{plan}-SPEC.md
 - [ ] STATE.md updated with current_plan, spec_path, loop_position: SPEC ✓
 - [ ] No assumptions made — every ambiguity resolved via clarification
-- [ ] Output ends with NEXT ACTION REQUIRED: /sdlc:impl
+- [ ] Output ends with auto-advance directive to /sdlc:impl
 </success_criteria>

package/src/commands/status.md

@@ -65,7 +65,7 @@ Step-by-step:
 4. Verify git state matches handoff (warn on mismatch). Pop stash if applicable.
 5. Archive consumed handoff to .sdlc/HANDOFF-{timestamp}.md.archived.
 6. Clean up STATE.md session fields (remove paused_at).
-7. Force ONE next action. Output ends with NEXT ACTION REQUIRED.
+7. Force ONE next action. End with auto-advance directive to the forced next action.
 </process>
 
 <success_criteria>
@@ -79,6 +79,6 @@ Step-by-step:
 - [ ] Resume: handoff located and context restored
 - [ ] Resume: git state verified against handoff
 - [ ] Resume: handoff archived after consumption
-- [ ] Resume: output ends with NEXT ACTION REQUIRED: /sdlc:{action}
+- [ ] Resume: output ends with auto-advance directive to /sdlc:{action}
 - [ ] No menus, no options — one clear path forward
 </success_criteria>

package/src/commands/verify.md

@@ -132,11 +132,12 @@ Step-by-step:
    - If ALL acceptance criteria pass:
      - Update STATE.md: set `loop_position: VERIFY_COMPLETE`
      - Set `verify_path: .sdlc/verify/VERIFY-<plan-id>.md`
-     - Output ends with: NEXT ACTION REQUIRED: /sdlc:review
+     - End with auto-advance directive to /sdlc:review
    - If ANY acceptance criteria fail:
      - Update STATE.md: set `loop_position: VERIFY_FAILED`
      - Output the failure details with suggested fixes.
      - Output ends with: "Fix the failures above, then re-run /sdlc:verify"
+     - Do NOT auto-advance on failure — the user must fix issues first.
 </process>
 
 <success_criteria>
@@ -147,7 +148,7 @@ Step-by-step:
 - [ ] VERIFY-<plan-id>.md created with per-AC pass/fail results
 - [ ] Failed ACs include: expected vs actual, root cause analysis, suggested fix, files to modify
 - [ ] STATE.md updated with loop_position (VERIFY_COMPLETE or VERIFY_FAILED)
-- [ ] If all pass: output ends with NEXT ACTION REQUIRED: /sdlc:review
+- [ ] If all pass: output ends with auto-advance directive to /sdlc:review
 - [ ] If any fail: output ends with "Fix the failures above, then re-run /sdlc:verify"
 - [ ] No criteria skipped without documented reason
 </success_criteria>

package/src/references/prompt-detection.md

@@ -8,11 +8,11 @@ This document explains how the `/sdlc:fast` command classifies task types from n
 
 When a developer types `/sdlc:fast "add a login page"`, the framework must determine:
 
-1. **What type of work is this?** (feature, bug, critical, research, test, refactor, docs)
+1. **What type of work is this?** (feature, bug, critical, test, refactor, docs)
 2. **How complex is it?** (simple, medium, complex)
-3. **Where should it route?** (inline execution, /sdlc:spec, /sdlc:debug, /sdlc:research, /sdlc:discuss, or inline hotfix)
+3. **Where should it route?** (inline execution, /sdlc:spec, /sdlc:debug, /sdlc:discuss, or inline hotfix)
 
-`/sdlc:fast` is the **default entry point** for all work — not just small tasks. It is a universal router that classifies intent and complexity, then either handles work inline (simple) or routes to the appropriate specialized command (complex, bugs, research, emergencies).
+`/sdlc:fast` is the **default entry point** for all work — not just small tasks. It is a universal router that classifies intent and complexity, then either handles work inline (simple) or routes to the appropriate specialized command (complex, bugs, brainstorming/research, emergencies).
 
 This classification happens automatically. The developer can override it with flags if the automatic classification is wrong.
 

package/src/templates/STATE.md

@@ -14,6 +14,11 @@ This template defines the loop position tracker stored at `.sdlc/STATE.md`. It i
 - **Laws file:** .sdlc/LAWS.md
 - **Roadmap file:** .sdlc/ROADMAP.md
 
+## Settings
+
+- **auto_advance:** true
+- **advance_delay_seconds:** 10
+
 ## Current Position
 
 - **Milestone:** {{MILESTONE_NAME}} ({{MILESTONE_NUMBER}}/{{TOTAL_MILESTONES}})
@@ -102,5 +107,10 @@ This is the most important field in the entire SDLC. It tells the developer (or
 ### Accumulated Context
 Decisions, deferred issues, and blockers survive across loop iterations. They are the project's institutional memory. Without them, the same questions get asked repeatedly and the same mistakes get made.
 
+### Settings
+Configuration for framework behavior:
+- **auto_advance** — When true, the framework automatically runs the next required action after a brief delay. Set to false for manual step-by-step control where the user must explicitly run each command.
+- **advance_delay_seconds** — Seconds to wait before auto-advancing to the next command. Gives the user time to review output and intervene by sending a message. Default: 10.
+
 ### Session Continuity
 When a developer stops working (end of day, context switch), this section captures exactly where to resume. The handoff file (HANDOFF.md) contains detailed notes; this section contains the summary.