sdlc-framework 2.1.0 → 3.0.0

package/src/workflows/review-phase.md

@@ -313,10 +313,23 @@
     Warnings: {count} (non-blocking, but should fix)
     Info: {count}
 
-    Run /sdlc:fix to systematically fix all blockers, then re-review automatically.
     Report: .sdlc/phases/{phase}/{plan}-REVIEW.md
+
+    NEXT: /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 — Run /sdlc:fix to systematically fix all blockers, then re-review automatically."
+      Wait for user to manually run the command.
+    </auto_advance>
+
   IF NO BLOCKERS (only warnings and info, or clean):
     Update .sdlc/STATE.md:
     - loop_position: REVIEW ✓
@@ -333,10 +346,21 @@
 
     Report: .sdlc/phases/{phase}/{plan}-REVIEW.md
 
-    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: Blockers are the gate. They enforce engineering standards. Warnings are advisory — the team can choose to address them. The gate prevents shipping code that violates critical laws.
 </step>
 

package/src/workflows/spec-phase.md

@@ -431,10 +431,21 @@
   Acceptance Criteria: {N}
   Boundaries: {N} files protected
 
-  NEXT ACTION REQUIRED: /sdlc:impl
-  Run /sdlc:impl to begin sub-agent implementation.
+  NEXT: /sdlc:impl
   ```
 
+  <auto_advance>
+  Read .sdlc/STATE.md auto_advance setting.
+  IF auto_advance is true:
+    Display: "Auto-advancing to /sdlc:impl 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:impl.
+    If user sends a message: cancel auto-advance, process user input, then resume.
+  IF auto_advance is false:
+    Display: "NEXT ACTION REQUIRED: /sdlc:impl"
+    Wait for user to manually run the command.
+  </auto_advance>
+
   WHY: The forcing function ensures the user moves to implementation. Without it, specs pile up without being built.
 </step>
 

package/src/workflows/status-session.md

@@ -61,12 +61,24 @@
 
   Force ONE next action from loop_position with explanation:
   ```
-  NEXT ACTION REQUIRED: /sdlc:impl
+  NEXT: /sdlc:impl
 
   What it does: Implements the current plan by writing code with subagent workers.
   Why it is next: The spec phase is complete. The plan has been approved.
   ```
 
+  <auto_advance>
+  Read .sdlc/STATE.md auto_advance setting.
+  IF auto_advance is true:
+    Display: "Auto-advancing to /sdlc:{next} 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:{next}.
+    If user sends a message: cancel auto-advance, process user input, then resume.
+  IF auto_advance is false:
+    Display: "NEXT ACTION REQUIRED: /sdlc:{next}"
+    Wait for user to manually run the command.
+  </auto_advance>
+
   WHY: Status is the "where am I" command. Junior developers need the visual. Senior developers need the forced next action. Both get what they need.
 </step>
 
@@ -198,7 +210,18 @@
 
   E. FORCE NEXT ACTION:
      Determine from STATE.md next_required_action.
-     Display: "NEXT ACTION REQUIRED: {action}"
+
+     <auto_advance>
+     Read .sdlc/STATE.md auto_advance setting.
+     IF auto_advance is true:
+       Display: "Auto-advancing to {action} 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 {action}.
+       If user sends a message: cancel auto-advance, process user input, then resume.
+     IF auto_advance is false:
+       Display: "NEXT ACTION REQUIRED: {action}"
+       Wait for user to manually run the command.
+     </auto_advance>
 
   WHY: Exactly ONE next action. The state machine has already decided. The user just executes it.
 </step>

package/src/workflows/verify-phase.md

@@ -263,10 +263,21 @@
 
     Report: .sdlc/phases/{phase}/{plan}-VERIFY.md
 
-    NEXT ACTION REQUIRED: /sdlc:review
-    Run /sdlc:review for engineering laws compliance check.
+    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>
+
   IF ANY AC FAILS:
     Do NOT update loop_position. Keep it at "IMPL ✓".
     Update next_required_action to "/sdlc:verify" (stay in verify).

package/src/commands/research.md

@@ -1,136 +0,0 @@
----
-name: sdlc:research
-description: "Deploy research subagents for discovery"
-argument-hint: "<topic>"
-allowed-tools: [Read, Write, Glob, Grep, Agent, WebSearch, WebFetch]
----
-
-<objective>
-Deploy research subagents to investigate a topic before writing code. This is the ONLY valid use of subagents outside of /sdlc:impl. Research never auto-integrates into code — findings are saved for human review.
-
-**When to use:** Before writing a spec, you need to understand something: an API, a library, a codebase pattern, a competing approach, or a technical constraint.
-
-**What it does:**
-1. Classify the research type (codebase, web, or both).
-2. Spawn focused subagent(s) with the Agent tool.
-3. Save structured findings to .sdlc/research/{topic}.md.
-4. Present findings for your review. Never auto-apply.
-
-**What happens next:** /sdlc:spec to use the research findings in planning.
-</objective>
-
-<execution_context>
-@~/.claude/sdlc-framework/workflows/research.md
-@.sdlc/STATE.md
-</execution_context>
-
-<context>
-$ARGUMENTS — the research topic. Required.
-
-If $ARGUMENTS is empty, output: "Provide a research topic. Example: /sdlc:research authentication patterns" Then stop.
-</context>
-
-<process>
-Follow workflow: @~/.claude/sdlc-framework/workflows/research.md
-
-Step-by-step:
-
-1. **Pre-flight check**
-   - Verify $ARGUMENTS is not empty.
-   - Read .sdlc/STATE.md to confirm framework is initialized.
-   - Create .sdlc/research/ directory if it does not exist.
-
-2. **Classify research type**
-   - Analyze the topic to determine what kind of research is needed:
-     - **Codebase exploration:** Understanding existing patterns, finding usage examples, mapping dependencies. Keywords: "how does", "where is", "existing pattern", "current implementation".
-     - **Web research:** External APIs, libraries, best practices, security advisories. Keywords: "library", "API", "best practice", "alternative", "comparison".
-     - **Both:** Topics that require understanding current code AND external context. Keywords: "migrate to", "upgrade", "integrate with".
-
-3. **Spawn research subagent(s)**
-   - For **codebase exploration**: spawn ONE Agent with instructions:
-     ```
-     Research topic: {topic}
-     Search the codebase for:
-     - Existing implementations of {topic}
-     - Patterns used for similar functionality
-     - Dependencies and imports related to {topic}
-     - Test coverage of related code
-     Use Glob, Grep, and Read. Report findings in structured format:
-     - Files found
-     - Patterns identified
-     - Key code snippets (with file paths and line numbers)
-     - Gaps or inconsistencies
-     ```
-   - For **web research**: spawn ONE Agent with instructions:
-     ```
-     Research topic: {topic}
-     Use WebSearch and WebFetch to find:
-     - Official documentation
-     - Best practices and recommendations
-     - Common pitfalls and gotchas
-     - Security considerations
-     - Performance implications
-     Report findings in structured format with source URLs.
-     ```
-   - For **both**: spawn TWO Agents (one codebase, one web) in parallel.
-
-4. **Collect and structure findings**
-   - Wait for all agents to complete.
-   - Merge findings into a structured document.
-
-5. **Save findings**
-   - Write to .sdlc/research/{sanitized-topic}.md:
-     ```
-     # Research: {topic}
-     Date: {timestamp}
-     Type: {codebase | web | both}
-
-     ## Summary
-     {2-3 sentence summary of key findings}
-
-     ## Codebase Findings
-     {if applicable}
-     ### Existing Patterns
-     - {pattern 1 with file references}
-     ### Dependencies
-     - {dependency 1}
-     ### Gaps
-     - {gap 1}
-
-     ## Web Findings
-     {if applicable}
-     ### Best Practices
-     - {practice 1} (source: {url})
-     ### Pitfalls
-     - {pitfall 1}
-     ### Security Considerations
-     - {consideration 1}
-
-     ## Recommendations
-     - {recommendation 1}
-     - {recommendation 2}
-
-     ## Open Questions
-     - {question that needs human input}
-     ```
-
-6. **Present findings — do NOT auto-integrate**
-   - Display the summary and recommendations to the user.
-   - Explicitly state: "These findings are saved for reference. They have NOT been applied to code."
-   - Output: "NEXT ACTION REQUIRED: /sdlc:spec — use these findings to plan your implementation."
-
-7. **Update STATE.md**
-   - Record that research was conducted on {topic}.
-   - Add reference to the findings file.
-</process>
-
-<success_criteria>
-- [ ] Research topic provided (not empty)
-- [ ] Research type classified correctly (codebase, web, or both)
-- [ ] Appropriate subagent(s) spawned with clear instructions
-- [ ] Findings saved to .sdlc/research/{topic}.md in structured format
-- [ ] Findings presented to user but NOT auto-applied to code
-- [ ] STATE.md updated with research reference
-- [ ] Output ends with NEXT ACTION REQUIRED: /sdlc:spec
-- [ ] No code changes made — research is read-only
-</success_criteria>

package/src/commands/transition.md

@@ -1,99 +0,0 @@
----
-name: sdlc:transition
-description: Transition to the next phase after all plans in a phase complete
-argument-hint: "[phase-name]"
-allowed-tools: [Read, Write, Bash, Glob, Grep, Edit, AskUserQuestion]
----
-
-<objective>
-Transition from the current phase to the next phase within a milestone. Verify phase completeness, update project state, commit the phase, and advance to the next phase.
-
-**When to use:** After /sdlc:close detects the last plan in a phase is done. Can also be run manually to force a phase transition.
-
-**What it does:**
-1. Verify all plans in the current phase are complete (every SPEC has a SUMMARY, all ACs passed).
-2. Cross-check STATE.md, PROJECT.md, and ROADMAP.md for consistency.
-3. Update PROJECT.md with implemented, superseded, and newly discovered requirements.
-4. Advance state to the next phase (or trigger milestone completion if this was the last phase).
-5. Update ROADMAP.md with phase completion details.
-6. Create a git commit marking the phase boundary.
-
-**What happens next:**
-- Next phase exists: Framework directs you to /sdlc:spec for the first plan of the new phase.
-- Last phase in milestone: Framework directs you to /sdlc:close for milestone finalization.
-
-**Critical rule:** No phase transitions without completeness verification. Every plan must have a summary. Every AC must pass. State inconsistencies are surfaced and resolved before advancing.
-</objective>
-
-<execution_context>
-@~/.claude/sdlc-framework/workflows/transition-phase.md
-@.sdlc/STATE.md
-@.sdlc/ROADMAP.md
-@.sdlc/PROJECT.md
-</execution_context>
-
-<context>
-$ARGUMENTS — optional phase name to transition from. If not provided, read from .sdlc/STATE.md current_phase field.
-
-Read these files:
-- .sdlc/STATE.md — current phase, milestone, loop position.
-- .sdlc/ROADMAP.md — phase list, plan counts, next phase identification.
-- .sdlc/PROJECT.md — requirements to update based on completed work.
-- All SUMMARY.md files in the completing phase's directory.
-</context>
-
-<process>
-Follow workflow: @~/.claude/sdlc-framework/workflows/transition-phase.md
-
-Step-by-step:
-
-1. **Verify phase completeness**
-   - Read .sdlc/STATE.md. Confirm loop_position is CLOSE ✓. If not, warn: "Loop not closed. Run /sdlc:close first."
-   - List all SPEC and SUMMARY files in .sdlc/phases/{current_phase}/.
-   - Every SPEC must have a corresponding SUMMARY. If not, block: "Phase transition blocked. Plan {N} has a spec but no summary."
-   - Every SUMMARY must show all ACs passed. If not, block: "Phase transition blocked. Plan {N} has failing ACs."
-
-2. **Verify state consistency**
-   - Cross-check STATE.md, PROJECT.md, and ROADMAP.md:
-     - STATE.md current_milestone matches ROADMAP.md in-progress milestone.
-     - STATE.md current_phase matches the phase being completed.
-     - Prior phases in this milestone are all COMPLETE.
-   - If inconsistency found: display details, offer to auto-fix, ask for confirmation.
-
-3. **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.
-
-4. **Advance state to next phase**
-   - Read ROADMAP.md to identify the next phase.
-   - If next phase exists:
-     - Update STATE.md: current_phase, clear current_plan, set loop_position: TRANSITION ✓, set next_required_action: /sdlc:spec.
-     - Update ROADMAP.md: mark completed phase as COMPLETE, set next phase to IN PROGRESS.
-   - If no next phase (last phase in milestone):
-     - Update STATE.md: set next_required_action: /sdlc:close (milestone completion).
-
-5. **Update ROADMAP.md with phase summary**
-   - Add completion date, plan count, hotfix count, key deliverables, and duration.
-
-6. **Create git commit** (if in a git repository)
-   - Stage .sdlc/ files and source files from the phase.
-   - Commit with message: "feat({phase-name}): complete phase {number}"
-
-7. **Output next action**
-   - If next phase exists: end with NEXT ACTION REQUIRED: /sdlc:spec
-   - If milestone complete: end with NEXT ACTION REQUIRED: /sdlc:close
-</process>
-
-<success_criteria>
-- [ ] Phase completeness verified: every SPEC has a SUMMARY, all ACs passed
-- [ ] State consistency checked across STATE.md, PROJECT.md, ROADMAP.md
-- [ ] PROJECT.md updated with implemented, superseded, and new requirements
-- [ ] STATE.md advanced to next phase (or milestone completion)
-- [ ] ROADMAP.md updated with phase completion details and summary
-- [ ] Git commit created at phase boundary (if in a git repo)
-- [ ] If next phase exists: output ends with NEXT ACTION REQUIRED: /sdlc:spec
-- [ ] If milestone complete: output ends with NEXT ACTION REQUIRED: /sdlc:close
-</success_criteria>

package/src/workflows/research.md

@@ -1,219 +0,0 @@
-<purpose>Conduct structured research before writing a specification. Spawns sub-agents to explore the codebase or search the web, saves findings, and routes back to the spec phase with informed context.</purpose>
-<when_to_use>Run when you need to understand existing code patterns, evaluate technical options, or gather external information before committing to a spec. Typically run before /sdlc:spec or when the spec phase reveals unknowns.</when_to_use>
-<required_reading>.sdlc/STATE.md, .sdlc/PROJECT.md</required_reading>
-<loop_context>
-  expected_phase: RESEARCH (pre-spec activity)
-  prior_phase: any (usually between loops or during spec clarification)
-  next_phase: SPEC (research always leads to a spec)
-</loop_context>
-<process>
-
-<step name="define_research_question" priority="first">
-  Ask the user: "What do you need to research? Describe the question or topic."
-
-  Then classify the research type:
-
-  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 agents (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: "Research type: {type}. Proceeding with {method}."
-
-  WHY: Different research types need different tools. Searching the web for "how is auth implemented in our code" is useless. Searching the codebase for "best JWT library" is equally useless.
-</step>
-
-<step name="spawn_codebase_agents" priority="second">
-  ONLY IF type is CODEBASE_EXPLORATION or HYBRID.
-
-  Spawn an exploration 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}
-  ```
-
-  WHY: Codebase exploration prevents reinventing the wheel. Finding existing patterns before writing a spec ensures the spec follows conventions.
-</step>
-
-<step name="spawn_web_agents" priority="third">
-  ONLY IF type is WEB_RESEARCH or HYBRID.
-
-  Spawn a web research 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}
-  ```
-
-  WHY: Web research prevents choosing outdated or inappropriate tools. It also surfaces gotchas that would otherwise be discovered mid-implementation.
-</step>
-
-<step name="review_findings" priority="fourth">
-  Wait for all agents to complete.
-
-  Read and synthesize the results:
-
-  FOR CODEBASE FINDINGS:
-  - Are the patterns consistent? Or are there competing approaches in the codebase?
-  - Is there reusable code? How much can be leveraged?
-  - What gaps need to be filled?
-
-  FOR WEB FINDINGS:
-  - Are the recommended options compatible with our stack?
-  - Do any options conflict with existing patterns?
-  - Are there security concerns?
-
-  FOR HYBRID:
-  - Do the codebase patterns align with external best practices?
-  - Where do they diverge? Is the divergence justified?
-
-  Present the 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}
-
-  Recommendation for spec:
-  {How to approach this in the specification, given both codebase and external findings}
-  ```
-
-  Ask: "Does this answer your question? Any follow-up research needed?"
-
-  IF FOLLOW-UP NEEDED: Return to step 1 with the refined question.
-
-  WHY: Raw agent output needs synthesis. The user should see a coherent recommendation, not a dump of search results.
-</step>
-
-<step name="save_findings" priority="fifth">
-  Create .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}
-  ```
-
-  WHY: Research findings are reusable. A future spec in the same area should read prior research instead of re-doing it. The research/ directory is a knowledge base.
-</step>
-
-<step name="route_to_spec" priority="sixth">
-  Update .sdlc/STATE.md:
-  - Add history entry: "{timestamp} | research | Topic: {topic}. Type: {type}. Findings saved."
-  - next_required_action: /sdlc:spec (if not already set)
-
-  Display:
-  ```
-  Research complete.
-
-  Findings: .sdlc/research/{topic-slug}.md
-
-  The spec phase will use these findings for informed task decomposition.
-
-  NEXT ACTION REQUIRED: /sdlc:spec
-  Run /sdlc:spec to create a specification informed by this research.
-  ```
-
-  WHY: Research without a spec is just reading. The forcing function ensures findings are applied to actual work.
-</step>
-
-</process>