sdlc-framework 2.1.1 → 3.0.0

package/src/workflows/close-phase.md

@@ -1,10 +1,10 @@
-<purpose>Close the current SPEC-IMPL-VERIFY-REVIEW loop by reconciling planned work against actual outcomes, creating a SUMMARY.md, and advancing the state machine to the next spec or phase transition.</purpose>
+<purpose>Close the current SPEC-IMPL-VERIFY-REVIEW loop by reconciling planned work against actual outcomes, creating a SUMMARY.md, and advancing the state machine to the next spec. 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.</purpose>
 <when_to_use>Run after /sdlc:review passes with zero blockers. STATE.md must show loop_position = REVIEW ✓ and next_required_action = /sdlc:close.</when_to_use>
-<required_reading>.sdlc/STATE.md, the current SPEC.md, REVIEW.md, VERIFY.md</required_reading>
+<required_reading>.sdlc/STATE.md, .sdlc/ROADMAP.md, .sdlc/PROJECT.md, the current SPEC.md, REVIEW.md, VERIFY.md</required_reading>
 <loop_context>
   expected_phase: CLOSE (active)
   prior_phase: REVIEW ✓
-  next_phase: SPEC (next loop) or transition-phase (if last plan)
+  next_phase: SPEC (next loop) — phase transition handled inline when last plan completes
 </loop_context>
 <display_rule>
   MANDATORY: Display the loop closure summary in the chat window. Show:
@@ -135,22 +135,66 @@
   OPTION A — More plans in this phase:
   - Check ROADMAP.md: is this the last planned plan for the current phase?
   - If there are more plans (or the phase is open-ended): set next to /sdlc:spec
+  - Update .sdlc/STATE.md:
+    - loop_position: CLOSE ✓
+    - current_plan: cleared (no active plan)
+    - next_required_action: /sdlc:spec
+    - Add history entry: "{timestamp} | close | Plan {N} closed. {N} ACs passed. {N} deviations."
+  - Update .sdlc/ROADMAP.md:
+    - Increment completed plan count for current phase
+
+  OPTION B — Last plan in phase (execute phase transition inline):
+
+  B1. Verify phase completeness:
+  - List all SPEC and SUMMARY files in .sdlc/phases/{current_phase}/.
+  - Every SPEC must have a corresponding SUMMARY. If a SPEC exists without a SUMMARY: STOP. Display: "Phase transition blocked. Plan {N} has a spec but no summary. Complete it first."
+  - Every SUMMARY must show all ACs passed. If any AC is FAIL: STOP. Display: "Phase transition blocked. Plan {N} has failing ACs."
+  - Display completeness check: plans created, plans completed, hotfixes, all ACs passed.
+
+  B2. Cross-check STATE.md, PROJECT.md, ROADMAP.md consistency:
+  - STATE.md current_milestone must match ROADMAP.md in-progress milestone.
+  - STATE.md current_phase must match the phase being completed.
+  - Prior phases in this milestone must all be COMPLETE.
+  - If inconsistency found: display details, offer to auto-fix, ask for user confirmation before applying.
+
+  B3. Update PROJECT.md:
+  - Read all SUMMARY.md files from the completing phase.
+  - For each requirement in PROJECT.md:
+    - If addressed in this phase: mark as IMPLEMENTED with reference to plan number.
+    - If contradicted or superseded by implementation: mark as SUPERSEDED with explanation.
+    - Leave unaddressed requirements as-is (future phase responsibility).
+  - Add newly discovered requirements (from decisions and lessons learned) as NOT STARTED.
+  - Display proposed changes and ask user to confirm before writing.
+
+  B4. Update ROADMAP.md with phase completion details:
+  - Mark completed phase as COMPLETE with date.
+  - Add phase summary note:
+    ```
+    #### Phase {number} Summary
+    - Plans executed: {N}
+    - Hotfixes: {N}
+    - Key deliverables: {from summaries}
+    - Duration: {first spec date} to {completion date}
+    ```
 
-  OPTION B — Last plan in phase:
-  - If this was the last plan: trigger transition-phase workflow
-  - Set next to /sdlc:transition (which handles phase advancement)
-
-  Update .sdlc/STATE.md:
-  - loop_position: CLOSE ✓
-  - current_plan: cleared (no active plan)
-  - next_required_action: /sdlc:spec OR /sdlc:transition
-  - Add history entry: "{timestamp} | close | Plan {N} closed. {N} ACs passed. {N} deviations."
-
-  Update .sdlc/ROADMAP.md:
-  - Increment completed plan count for current phase
-  - If phase is complete: mark phase status as COMPLETE
-
-  WHY: The state machine must always have a clear next action. Ambiguity in state leads to confusion about what to do next.
+  B5. Advance state to next phase:
+  - IF next phase exists in ROADMAP.md:
+    - Update STATE.md: 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 status to IN PROGRESS.
+    - Add history entry: "{timestamp} | close | Plan {N} closed. Phase {phase} complete. Transitioning to phase {next-phase}."
+  - IF no next phase (last phase in milestone):
+    - Do not advance to a new phase. The milestone completion logic in the display_result step handles this.
+    - Add history entry: "{timestamp} | close | Plan {N} closed. Phase {phase} complete. Last phase in milestone."
+
+  B6. Create git commit (if in a git repo):
+  - Check git status for uncommitted changes.
+  - If uncommitted changes exist:
+    - Stage .sdlc/ files and source files from the phase.
+    - Commit: `feat({phase-name}): complete phase {number}`
+    - Display: "Git commit created: {hash}"
+  - If no uncommitted changes: Display: "No uncommitted changes to commit."
+
+  WHY: The state machine must always have a clear next action. Phase transitions are executed inline to keep the close command as the single point of state advancement. No separate transition command needed.
 </step>
 
 <step name="display_result" priority="sixth">
@@ -165,22 +209,52 @@
     ACs passed: {count}/{count}
     Deviations: {count}
 
-    NEXT ACTION REQUIRED: /sdlc:spec
-    Run /sdlc:spec to create the next specification.
+    NEXT: /sdlc:spec
     ```
 
-  IF phase complete:
+    <auto_advance>
+    Read .sdlc/STATE.md auto_advance setting.
+    IF auto_advance is true:
+      Display: "Auto-advancing to /sdlc:spec in {advance_delay_seconds}s — reply to intervene."
+      Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+      If no user message received during sleep: automatically execute /sdlc:spec.
+      If user sends a message: cancel auto-advance, process user input, then resume.
+    IF auto_advance is false:
+      Display: "NEXT ACTION REQUIRED: /sdlc:spec"
+      Wait for user to manually run the command.
+    </auto_advance>
+
+  IF phase complete (transition executed inline) AND next phase exists:
     Display:
     ```
     Loop closed: Plan {N} complete.
-    Phase {phase} COMPLETE — all plans finished.
+
+    Phase transition complete.
+    ─────────────────────────
+    Completed: Phase {old-number} — {old-name}
+    Plans executed: {N}
+    Hotfixes: {N}
+    Duration: {first spec date} to {completion date}
+
+    Starting: Phase {new-number} — {new-name}
 
     Summary: .sdlc/phases/{phase}/{plan}-SUMMARY.md
 
-    Transitioning to next phase...
-    NEXT ACTION REQUIRED: /sdlc:transition
+    NEXT: /sdlc:spec
     ```
 
+    <auto_advance>
+    Read .sdlc/STATE.md auto_advance setting.
+    IF auto_advance is true:
+      Display: "Auto-advancing to /sdlc:spec in {advance_delay_seconds}s — reply to intervene."
+      Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+      If no user message received during sleep: automatically execute /sdlc:spec.
+      If user sends a message: cancel auto-advance, process user input, then resume.
+    IF auto_advance is false:
+      Display: "NEXT ACTION REQUIRED: /sdlc:spec"
+      Wait for user to manually run the command.
+    </auto_advance>
+
   IF milestone complete (last phase, last plan):
     Display:
     ```

package/src/workflows/debug-flow.md

@@ -292,10 +292,21 @@
 
   Debug record: .sdlc/phases/{phase}/DEBUG-{slug}.md
 
-  NEXT ACTION REQUIRED: /sdlc:review
-  Run /sdlc:review to check the fix against engineering laws.
+  NEXT: /sdlc:review
   ```
 
+  <auto_advance>
+  Read .sdlc/STATE.md auto_advance setting.
+  IF auto_advance is true:
+    Display: "Auto-advancing to /sdlc:review in {advance_delay_seconds}s — reply to intervene."
+    Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+    If no user message received during sleep: automatically execute /sdlc:review.
+    If user sends a message: cancel auto-advance, process user input, then resume.
+  IF auto_advance is false:
+    Display: "NEXT ACTION REQUIRED: /sdlc:review"
+    Wait for user to manually run the command.
+  </auto_advance>
+
   WHY: Debug fixes still go through review. A hurried fix might violate engineering laws — empty catch blocks, missing types, function too long. The review catches that.
 </step>
 

package/src/workflows/discuss-phase.md

@@ -1,6 +1,6 @@
-<purpose>Drive AI-led brainstorming to transform a raw idea into a structured PRD. The discuss phase sits upstream of spec — it explores the problem space, validates approaches, and builds requirements through targeted questioning. Without this phase, specs are built on assumptions instead of explored decisions.</purpose>
-<when_to_use>Run when the user has an idea but has not yet defined what to build. This is pre-loop discovery — it feeds into /sdlc:spec. Can run at any point: before init, between loops, or when pivoting direction.</when_to_use>
-<required_reading>.sdlc/PROJECT.md (if exists), .sdlc/ROADMAP.md (if exists), codebase structure for technical context</required_reading>
+<purpose>Drive AI-led brainstorming to transform a raw idea into a structured PRD. The discuss phase sits upstream of spec — it explores the problem space, researches unknowns inline, validates approaches, and builds requirements through targeted questioning. Without this phase, specs are built on assumptions instead of explored decisions.</purpose>
+<when_to_use>Run when the user has an idea but has not yet defined what to build. Also use when research is needed — external APIs, library choices, codebase patterns, best practices. This is pre-loop discovery — it feeds into /sdlc:spec. Can run at any point: before init, between loops, or when pivoting direction.</when_to_use>
+<required_reading>.sdlc/PROJECT.md (if exists), .sdlc/ROADMAP.md (if exists), .sdlc/research/*.md (prior research), codebase structure for technical context</required_reading>
 <loop_context>
   expected_phase: DISCUSS (pre-loop activity)
   prior_phase: any (entry point or between loops)
@@ -68,10 +68,188 @@
   Record all answers in the decisions log.
 </step>
 
-<step name="validate_approach" priority="fourth">
+<step name="research_unknowns" priority="fourth">
+  Unknowns discovered during problem and scope rounds must be resolved before choosing an approach. Picking an approach without understanding external APIs, library options, or codebase patterns leads to rework.
+
+  SKIP CONDITION: If no unknowns were identified in prior rounds — the idea is clear, the tech is familiar, and existing codebase patterns are sufficient — skip research and proceed to validate_approach.
+
+  A. IDENTIFY UNKNOWNS:
+  Review answers from explore_problem and define_scope. Extract unknowns:
+  - External APIs or services that need integration
+  - Library or tool choices not yet decided
+  - Codebase patterns not yet understood (how does X work in our code?)
+  - Best practices or security considerations for unfamiliar territory
+  - Migration paths or upgrade strategies
+
+  IF no unknowns identified:
+    Display: "No research needed — proceeding to approach validation."
+    Skip to validate_approach.
+
+  B. CLASSIFY RESEARCH TYPE:
+  For each unknown, classify:
+
+  TYPE: CODEBASE_EXPLORATION
+  Indicators: "how does X work in our code", "where is Y implemented", "what pattern does Z use", "find all instances of W"
+  Method: Codebase search agent (Grep, Glob, Read)
+
+  TYPE: WEB_RESEARCH
+  Indicators: "what is the best library for X", "how does Y technology work", "compare options for Z", "what are best practices for W"
+  Method: WebSearch agent
+
+  TYPE: HYBRID
+  Indicators: "how should we implement X" (needs both codebase understanding AND external knowledge)
+  Method: Both codebase and web agents
+
+  Display: "Unknowns identified: {list}. Research type: {type}. Spawning research subagents."
+
+  C. SPAWN RESEARCH SUBAGENTS:
+
+  For CODEBASE_EXPLORATION: spawn ONE Agent with run_in_background: true.
+  Agent instruction:
+  ```
+  You are researching the codebase to answer: "{research question}"
+
+  PROJECT CONTEXT:
+  {from PROJECT.md: tech stack, architecture, conventions}
+
+  YOUR TASK:
+  1. Search for files and code related to: {topic}
+     - Use Glob to find files by name pattern
+     - Use Grep to search file contents for relevant patterns
+     - Read key files to understand implementation details
+
+  2. For each relevant finding, record:
+     - File path and line numbers
+     - What the code does
+     - What pattern it follows
+     - How it relates to the research question
+
+  3. Look for:
+     - Existing implementations of similar features
+     - Patterns and conventions used in the codebase
+     - Utilities, helpers, and shared code that could be reused
+     - Test patterns used for similar features
+     - Configuration and setup patterns
+
+  4. Compile findings into a structured summary:
+     - Existing patterns found: {list with file references}
+     - Reusable code: {list of utilities/helpers that apply}
+     - Conventions: {naming, structure, testing patterns}
+     - Gaps: {what does NOT exist yet that would be needed}
+     - Recommendation: {how to approach the implementation based on existing patterns}
+  ```
+
+  For WEB_RESEARCH: spawn ONE Agent with run_in_background: true.
+  Agent instruction:
+  ```
+  You are researching an external topic to inform a specification.
+
+  RESEARCH QUESTION: "{research question}"
+
+  PROJECT CONTEXT:
+  {from PROJECT.md: tech stack — so research is relevant to the stack}
+
+  YOUR TASK:
+  1. Use WebSearch to find information about: {topic}
+  2. Search for:
+     - Official documentation for relevant libraries/tools
+     - Best practices and common patterns
+     - Comparison articles if evaluating options
+     - Known issues, gotchas, and caveats
+     - Security considerations
+
+  3. For each option/approach found:
+     - Name and description
+     - Pros: {advantages}
+     - Cons: {disadvantages}
+     - Maturity: {stable, beta, experimental}
+     - Community: {active, declining, abandoned}
+     - Compatibility with our stack: {yes/no, details}
+
+  4. Compile findings into a structured summary:
+     - Options evaluated: {list}
+     - Recommended option: {which and why}
+     - Key considerations: {trade-offs, risks}
+     - Implementation notes: {relevant details for the spec}
+  ```
+
+  For HYBRID: spawn TWO Agents (one codebase, one web) in parallel with run_in_background: true.
+
+  D. COLLECT AND SYNTHESIZE:
+  Wait for all agents to complete.
+
+  Synthesize findings:
+  - Are codebase patterns consistent with external best practices?
+  - Do any options conflict with existing conventions?
+  - Are there security or performance concerns?
+
+  E. SAVE FINDINGS:
+  Create .sdlc/research/ directory if it does not exist.
+  Generate a topic slug: lowercase, hyphens, no special characters, max 40 chars.
+
+  Write to .sdlc/research/{topic-slug}.md:
+  ```markdown
+  # Research: {topic}
+
+  ## Question
+  {Original research question}
+
+  ## Date
+  {ISO timestamp}
+
+  ## Type
+  {CODEBASE|WEB|HYBRID}
+
+  ## Codebase Findings
+  {Structured findings from codebase exploration}
+  - Pattern: {description} — {file}:{line}
+  - Reusable: {utility/helper} — {file}
+
+  ## External Findings
+  {Structured findings from web research}
+  - Option: {name} — Pros: {pros}, Cons: {cons}
+
+  ## Synthesis
+  {Combined analysis}
+
+  ## Recommendation
+  {What to do in the spec, and why}
+
+  ## References
+  - {file paths for codebase references}
+  - {URLs for web references}
+  ```
+
+  F. PRESENT FINDINGS:
+  Display synthesized findings to the user:
+  ```
+  Research Findings: {topic}
+
+  Codebase:
+  - Found {N} relevant patterns
+  - Key pattern: {description} (used in {files})
+  - Reusable: {list of utilities/helpers}
+  - Gap: {what is missing}
+
+  External:
+  - Recommended approach: {option}
+  - Key trade-off: {trade-off}
+  - Risk: {risk}
+
+  Saved: .sdlc/research/{topic-slug}.md
+  ```
+
+  These findings feed directly into the next step — approach validation.
+</step>
+
+<step name="validate_approach" priority="fifth">
   Choosing the wrong approach is the most expensive mistake — it compounds through every downstream phase. Presenting options with trade-offs prevents blind commitment to the first idea.
 
-  Based on the problem and scope, identify 2-3 viable technical approaches.
+  Based on the problem, scope, and research findings (if any), identify 2-3 viable technical approaches.
+
+  IF research was conducted in research_unknowns:
+    Use research findings to inform approach options. Reference specific findings — do not ignore the research.
+    Approaches that conflict with codebase patterns or external best practices must note the conflict.
 
   Present each approach:
   ```
@@ -80,6 +258,7 @@
   - Risk: {what could go wrong}
   - Maintenance: {ongoing burden}
   - Fits existing patterns: {yes/no — reference specific codebase patterns}
+  - Research support: {what research findings support this approach}
 
   Approach B: {description}
   - Effort: {low/medium/high}
@@ -102,7 +281,7 @@
   Record the chosen approach and rationale in the decisions log.
 </step>
 
-<step name="detail_requirements" priority="fifth">
+<step name="detail_requirements" priority="sixth">
   Requirements bridge the gap between "what to build" and "how to spec it." Missing requirements surface as bugs during implementation.
 
   Ask 2-4 questions from this category. Include a recommendation with each.
@@ -130,8 +309,8 @@
   Record all answers in the decisions log.
 </step>
 
-<step name="compile_prd" priority="sixth">
-  The PRD is the deliverable — it captures every decision made during discussion. Without it, the discussion is just a conversation that evaporates.
+<step name="compile_prd" priority="seventh">
+  The PRD is the deliverable — it captures every decision made during discussion and every research finding discovered. Without it, the discussion is just a conversation that evaporates.
 
   Create .sdlc/discuss/ directory if it does not exist.
 
@@ -141,22 +320,31 @@
   - Problem Statement: from explore_problem answers
   - Proposed Solution: from validate_approach chosen approach
   - Alternatives Considered: from validate_approach rejected approaches
+  - Research Findings: from research_unknowns findings (if research was conducted)
+    - Codebase patterns discovered
+    - External options evaluated
+    - Recommendation and rationale
+    - Link to full research: .sdlc/research/{topic-slug}.md
   - Requirements: from detail_requirements answers
   - Constraints: from define_scope answers
   - Edge Cases: from detail_requirements answers
   - Success Metrics: from detail_requirements answers
   - Decisions Log: every question asked and answer received, numbered
 
+  IF research was NOT conducted:
+    Omit the Research Findings section entirely.
+
   Display a compact summary of the PRD (30-50 lines):
   - Problem (2 lines)
   - Solution (2 lines)
+  - Research findings (2-3 lines, if applicable)
   - Requirements (numbered list)
   - Constraints (list)
   - Edge cases (list)
   - Open questions (list)
 </step>
 
-<step name="approve_and_route" priority="seventh">
+<step name="approve_and_route" priority="eighth">
   The user must approve the PRD before it feeds into spec. An unapproved PRD is just notes.
 
   Ask: "PRD complete. Review the summary above."
@@ -168,7 +356,7 @@
   IF APPROVE:
     Set PRD status to APPROVED.
     Update .sdlc/STATE.md:
-    - Add history entry: "{timestamp} | discuss | Topic: {topic}. PRD saved."
+    - Add history entry: "{timestamp} | discuss | Topic: {topic}. PRD saved. Research: {yes/no}."
     - Set next_required_action: /sdlc:spec
     - Add prd_path: .sdlc/discuss/{topic-slug}-PRD.md
 
@@ -177,14 +365,26 @@
     PRD approved.
 
     Saved: .sdlc/discuss/{topic-slug}-PRD.md
+    Research: {.sdlc/research/{topic-slug}.md if applicable, otherwise "none"}
 
     The spec phase will use this PRD to create a detailed specification with
     acceptance criteria and task dependencies.
 
-    NEXT ACTION REQUIRED: /sdlc:spec
-    Run /sdlc:spec to formalize this PRD into an implementation-ready specification.
+    NEXT: /sdlc:spec
     ```
 
+    <auto_advance>
+    Read .sdlc/STATE.md auto_advance setting.
+    IF auto_advance is true:
+      Display: "Auto-advancing to /sdlc:spec in {advance_delay_seconds}s — reply to intervene."
+      Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+      If no user message received during sleep: automatically execute /sdlc:spec.
+      If user sends a message: cancel auto-advance, process user input, then resume.
+    IF auto_advance is false:
+      Display: "NEXT ACTION REQUIRED: /sdlc:spec"
+      Wait for user to manually run the command.
+    </auto_advance>
+
   IF REVISE:
     Apply changes. Re-display summary. Re-ask for approval.
 

package/src/workflows/fast-forward.md

@@ -4,7 +4,7 @@
 <loop_context>
   expected_phase: FAST (compressed loop, inline hotfix, or routing)
   prior_phase: any (fast can be used between loops or as the first action)
-  next_phase: depends on routing — SPEC, DEBUG, RESEARCH, DISCUSS, or self-contained
+  next_phase: depends on routing — SPEC, DEBUG, DISCUSS, or self-contained
 </loop_context>
 <references>
 @~/.claude/sdlc-framework/references/prompt-detection.md
@@ -61,13 +61,39 @@
      - No → FEATURE (a "fix" that is really a refinement)
      Display: "Bug detected. Routing to /sdlc:debug for structured debugging."
      Write to STATE.md: fast_context = {original description}
+
+     <auto_advance>
+     Read .sdlc/STATE.md auto_advance setting.
+     IF auto_advance is true:
+       Display: "Auto-advancing to /sdlc:debug in {advance_delay_seconds}s — reply to intervene."
+       Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+       If no user message received during sleep: automatically execute /sdlc:debug.
+       If user sends a message: cancel auto-advance, process user input, then resume.
+     IF auto_advance is false:
+       Display: "NEXT ACTION REQUIRED: /sdlc:debug"
+       Wait for user to manually run the command.
+     </auto_advance>
+
      STOP this workflow.
 
-  3. RESEARCH — exploration and investigation
-     Indicators: "explore", "investigate", "research", "compare options", "evaluate", "what are the options", "how does X work", "should we use"
-     Route: /sdlc:research
-     Display: "Research task detected. Routing to /sdlc:research."
+  3. DISCUSS — brainstorming, research, and exploration
+     Indicators: "brainstorm", "discuss", "idea", "what if", "think about", "concept", "should we", "could we", "explore", "investigate", "research", "compare options", "evaluate", "what are the options", "how does X work", "should we use"
+     Route: /sdlc:discuss
+     Display: "Brainstorming or research topic detected. Routing to /sdlc:discuss for structured discovery."
      Write to STATE.md: fast_context = {original description}
+
+     <auto_advance>
+     Read .sdlc/STATE.md auto_advance setting.
+     IF auto_advance is true:
+       Display: "Auto-advancing to /sdlc:discuss in {advance_delay_seconds}s — reply to intervene."
+       Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+       If no user message received during sleep: automatically execute /sdlc:discuss.
+       If user sends a message: cancel auto-advance, process user input, then resume.
+     IF auto_advance is false:
+       Display: "NEXT ACTION REQUIRED: /sdlc:discuss"
+       Wait for user to manually run the command.
+     </auto_advance>
+
      STOP this workflow.
 
   4. FEATURE — new functionality
@@ -91,7 +117,7 @@
 
   Display: "Classified as: {TYPE}. {Brief explanation of why.}"
 
-  WHY: Classification determines the entire routing strategy. Bugs need root cause analysis (debug), not fast implementation. Critical issues need minimal ceremony (hotfix). Research needs subagents, not code changes. Getting the classification wrong wastes the user's time on the wrong workflow.
+  WHY: Classification determines the entire routing strategy. Bugs need root cause analysis (debug), not fast implementation. Critical issues need minimal ceremony (hotfix). Research and brainstorming need structured discovery (discuss). Getting the classification wrong wastes the user's time on the wrong workflow.
 </step>
 
 <step name="estimate_complexity" priority="third">
@@ -175,10 +201,21 @@
   Your description and the identified files have been saved to STATE.md.
   /sdlc:spec will pick up this context automatically — no need to repeat yourself.
 
-  NEXT ACTION REQUIRED: /sdlc:spec
-  Run /sdlc:spec to decompose this into parallel tasks with proper dependency ordering.
+  NEXT: /sdlc:spec
   ```
 
+  <auto_advance>
+  Read .sdlc/STATE.md auto_advance setting.
+  IF auto_advance is true:
+    Display: "Auto-advancing to /sdlc:spec in {advance_delay_seconds}s — reply to intervene."
+    Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+    If no user message received during sleep: automatically execute /sdlc:spec.
+    If user sends a message: cancel auto-advance, process user input, then resume.
+  IF auto_advance is false:
+    Display: "NEXT ACTION REQUIRED: /sdlc:spec — Run /sdlc:spec to decompose this into parallel tasks with proper dependency ordering."
+    Wait for user to manually run the command.
+  </auto_advance>
+
   STOP this workflow.
 
   WHY: The user should not have to re-describe their work when routing. Pre-filling context makes the handoff seamless. The explanation tells the user WHY the routing happened — building trust in the framework's decisions.

package/src/workflows/fix-findings.md

@@ -215,9 +215,21 @@
   Trigger the review-phase workflow (re-run the full review).
 
   IF re-review finds NEW blockers (fixes introduced new violations):
-    Display: "Fix introduced {N} new blockers. Review the new findings and run /sdlc:fix again."
+    Display: "Fix introduced {N} new blockers."
     Set next_required_action to "/sdlc:fix"
 
+    <auto_advance>
+    Read .sdlc/STATE.md auto_advance setting.
+    IF auto_advance is true:
+      Display: "Auto-advancing to /sdlc:fix in {advance_delay_seconds}s — reply to intervene."
+      Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+      If no user message received during sleep: automatically execute /sdlc:fix.
+      If user sends a message: cancel auto-advance, process user input, then resume.
+    IF auto_advance is false:
+      Display: "NEXT ACTION REQUIRED: /sdlc:fix — Review the new findings and run /sdlc:fix again."
+      Wait for user to manually run the command.
+    </auto_advance>
+
   IF re-review passes (zero blockers):
     Display:
     ```
@@ -225,10 +237,21 @@
     Warnings: {count}
     Info: {count}
 
-    NEXT ACTION REQUIRED: /sdlc:close
-    Run /sdlc:close to close this loop.
+    NEXT: /sdlc:close
     ```
 
+    <auto_advance>
+    Read .sdlc/STATE.md auto_advance setting.
+    IF auto_advance is true:
+      Display: "Auto-advancing to /sdlc:close in {advance_delay_seconds}s — reply to intervene."
+      Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+      If no user message received during sleep: automatically execute /sdlc:close.
+      If user sends a message: cancel auto-advance, process user input, then resume.
+    IF auto_advance is false:
+      Display: "NEXT ACTION REQUIRED: /sdlc:close"
+      Wait for user to manually run the command.
+    </auto_advance>
+
   WHY: Re-review confirms the fixes are correct and complete. Without re-review, a fix that introduced a new violation would slip through to close.
 </step>
 

package/src/workflows/impl-phase.md

@@ -276,10 +276,21 @@
   Files created: {list}
   Smoke tests: PASSED
 
-  NEXT ACTION REQUIRED: /sdlc:verify
-  Run /sdlc:verify to test acceptance criteria.
+  NEXT: /sdlc:verify
   ```
 
+  <auto_advance>
+  Read .sdlc/STATE.md auto_advance setting.
+  IF auto_advance is true:
+    Display: "Auto-advancing to /sdlc:verify in {advance_delay_seconds}s — reply to intervene."
+    Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+    If no user message received during sleep: automatically execute /sdlc:verify.
+    If user sends a message: cancel auto-advance, process user input, then resume.
+  IF auto_advance is false:
+    Display: "NEXT ACTION REQUIRED: /sdlc:verify"
+    Wait for user to manually run the command.
+  </auto_advance>
+
   WHY: Clear reporting lets the user assess what happened before deciding to proceed. The forcing function moves them to verification.
 </step>
 

package/src/workflows/init-project.md

@@ -218,7 +218,7 @@
   Run: mkdir -p .sdlc/phases/{phase-dir} for each phase
   Run: mkdir -p .sdlc/research
 
-  WHY: Pre-creating directories prevents "directory not found" errors during spec/impl phases. The research/ directory is used by /sdlc:research to store findings.
+  WHY: Pre-creating directories prevents "directory not found" errors during spec/impl phases. The research/ directory is used by /sdlc:discuss to store research findings when unknowns are detected.
 </step>
 
 <step name="update_state_and_display" priority="ninth">
@@ -239,11 +239,22 @@
     .sdlc/phases/      — phase directories
     .sdlc/research/    — research storage
 
-  NEXT ACTION REQUIRED: /sdlc:spec
-  Run /sdlc:spec to create your first specification.
+  NEXT: /sdlc:spec
   ```
 
-  WHY: The explicit "NEXT ACTION REQUIRED" message is the forcing function. The user always knows exactly what to do next. No ambiguity, no guessing.
+  <auto_advance>
+  Read .sdlc/STATE.md auto_advance setting.
+  IF auto_advance is true:
+    Display: "Auto-advancing to /sdlc:spec in {advance_delay_seconds}s — reply to intervene."
+    Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+    If no user message received during sleep: automatically execute /sdlc:spec.
+    If user sends a message: cancel auto-advance, process user input, then resume.
+  IF auto_advance is false:
+    Display: "NEXT ACTION REQUIRED: /sdlc:spec"
+    Wait for user to manually run the command.
+  </auto_advance>
+
+  WHY: The auto-advance directive is the forcing function. The framework automatically chains to the next step unless the user intervenes. No ambiguity, no waiting.
 </step>
 
 </process>