sdlc-framework 1.0.0 → 1.0.1

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 → 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.
 
@@ -76,14 +76,17 @@ Choose global (all projects) or local (current project only). Verify with `/sdlc
 # 1. Initialize the framework
 /sdlc:init
 
-# 2. Define what to build (asks clarification questions)
+# 2. (Optional) Brainstorm — AI asks questions, produces a PRD
+/sdlc:discuss add user notifications
+
+# 3. Define what to build (asks clarification questions)
 /sdlc:spec
 
-# 3. Build it (spawns parallel sub-agents)
+# 4. Build it (spawns parallel sub-agents)
 /sdlc:impl
 
-# 4. 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 → close automatically
 ```
 
 ### Just Tell It What To Do
@@ -109,71 +112,85 @@ Follows: reproduce → isolate → root-cause → fix → verify.
 ## The Loop
 
 ```
-┌──────────────────────────────────────────────────────────┐
-│  SPEC ──→ IMPLEMENT ──→ VERIFY ──→ REVIEW ──→ CLOSE     │
-│   │                                              │       │
-│   └──────────────── next cycle ←─────────────────┘       │
-│                                                          │
-│  Define    Build (parallel   Auto-test    Engineering    │
-│  work +    sub-agents per    (Playwright  laws check     │
-│  ask Qs    dependency wave)  MCP + tests) (SOLID/DRY/..) │
-└──────────────────────────────────────────────────────────┘
+┌────────────────────────────────────────────────────────────┐
+│  SPEC ──→ IMPLEMENT ──→ VERIFY ──→ CLOSE                   │
+│   │                                   │                     │
+│   └──────────── next cycle ←──────────┘                     │
+│                                                             │
+│  Define    Build (parallel   Two-phase:        Close loop,  │
+│  work +    sub-agents per    1. AC testing     reconcile,   │
+│  ask Qs    dependency wave)  2. Laws review    advance      │
+└────────────────────────────────────────────────────────────┘
 ```
 
+### DISCUSS — Explore the idea (optional, pre-loop)
+
+- AI-driven brainstorming — you describe an idea, AI asks structured questions
+- 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` with research findings included
+- **User approval gate** — PRD must be approved before routing to `/sdlc:spec`
+
 ### SPEC — Define the work
 
 - Asks clarification questions (no guessing)
 - Presents options with trade-offs and recommendations
-- Defines BDD acceptance criteria (Given/When/Then)
+- Defines BDD acceptance criteria (Given/When/Then) with **explicit verification types** — each AC declares whether it's tested via Playwright MCP, curl, Bash, test runner, or DB queries
 - Decomposes tasks with dependency graph for parallel execution
-- **Spec integrity review** — checks completeness, consistency, feasibility
+- **Codebase gap analysis** — reads existing code the spec touches, flags missing error handling, edge cases, validation gaps, and integration risks before implementation starts
+- **Spec integrity review** — checks completeness, consistency, feasibility, verification types, and gap analysis (7 checks)
 - **User approval gate** — spec must be explicitly approved before implementation starts
 
 ### IMPLEMENT — Build it
 
+- **Pre-flight plan verification** — validates AC↔task coverage, file existence, boundary compliance, and dependency integrity before spawning agents
 - Analyzes task dependencies (DAG)
 - Spawns parallel sub-agents per wave
 - Each agent gets: task spec, engineering laws, boundaries
 - Tracks progress via todo list
 
-### VERIFY — Test it
+### VERIFY — Test it + review it (two phases in one command)
 
-- Translates acceptance criteria to automated tests
-- UI: Playwright MCP (navigate, click, assert)
-- API: curl requests with assertions
-- Logic: test suite execution
-- Reports pass/fail per AC with evidence
+**Phase 1 — Acceptance Criteria:**
+- Reads the **declared verification type** from each AC — no keyword guessing
+- **UI_INTERACTION**: Playwright MCP (navigate, click, snapshot, screenshot, fill_form) with pre-check for browser availability
+- **API_ENDPOINT**: curl requests with status code and body assertions
+- **CLI_BEHAVIOR**: Bash command execution with stdout/stderr/exit code capture
+- **BUSINESS_LOGIC**: project test runner (bun test, npm test, vitest, jest, pytest)
+- **DATA_INTEGRITY**: database queries via CLI
+- ACs missing a Type field are marked FAIL — never skipped, never guessed
+- If any AC fails, stops immediately — no engineering review on broken code
 
-### REVIEW — Check it
-
-- Reviews all modified files against Engineering Laws
+**Phase 2 — Engineering Laws Review (only runs after all ACs pass):**
+- Reviews all modified files against LAWS.md
 - Checks: SOLID, DRY, YAGNI, Clean Code, Security, Testing, Naming, Error Handling
 - Severity levels: BLOCKER (must fix), WARNING (should fix), INFO (consider)
 - Blockers prevent loop closure — routes to `/sdlc:fix` for systematic fixing
-- `/sdlc:fix` analyzes fix dependencies, applies fixes (parallel where possible), auto re-reviews
+- `/sdlc:fix` analyzes fix dependencies, applies fixes (parallel where possible), auto re-verifies
 
 ### CLOSE — Ship it
 
 - Reconciles spec vs actual implementation
 - Records deviations, decisions, lessons
 - Creates SUMMARY.md for audit trail
-- Advances state to next cycle
+- 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
 
-15 commands, grouped by purpose. Run `/sdlc:help` for the full reference.
+11 commands, grouped by purpose. Run `/sdlc:help` for the full reference.
 
 ### Core Loop
 
 | Command | What it does | Forces next |
 |---------|-------------|-------------|
 | `/sdlc:spec` | Define work with acceptance criteria | → `/sdlc:impl` |
-| `/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` |
+| `/sdlc:impl` | Build via parallel sub-agents (with pre-flight plan verification) | → `/sdlc:verify` |
+| `/sdlc:verify` | Two-phase: AC testing (Playwright MCP, curl, tests) + engineering laws review | → `/sdlc:close` |
+| `/sdlc:close` | Close the loop. Handles phase transitions and milestone completion inline | → `/sdlc:spec` |
 
 ### Quick Entry
 
@@ -185,32 +202,35 @@ Follows: reproduce → isolate → root-cause → fix → verify.
 
 | Command | What it does |
 |---------|-------------|
-| `/sdlc:fix` | Fix review blockers systematically, auto re-review |
+| `/sdlc:fix` | Fix code quality blockers systematically, auto re-verify |
 | `/sdlc:debug <issue>` | Structured debugging: reproduce → isolate → fix → verify |
-| `/sdlc:hotfix <issue>` | Emergency fix with minimal ceremony |
 
-### Session
+### Session & Status
 
 | Command | What it does |
 |---------|-------------|
-| `/sdlc:pause` | Save context for break |
-| `/sdlc:resume` | Restore context, ONE next action |
-| `/sdlc:status` | Show position + forced next action |
+| `/sdlc:status` | Show loop position, progress, forced next action |
+| `/sdlc:status pause` | Save context for break, create HANDOFF.md |
+| `/sdlc:status resume` | Restore context, ONE next action |
+
+### Planning & Discovery
+
+| Command | What it does |
+|---------|-------------|
+| `/sdlc:discuss [idea]` | Brainstorm and research — AI asks questions, spawns research subagents for unknowns, produces a PRD |
 
 ### Setup
 
 | Command | What it does |
 |---------|-------------|
-| `/sdlc:init` | Initialize framework in project |
-| `/sdlc:milestone` | Create or complete milestones |
-| `/sdlc:research` | Deploy research sub-agents |
+| `/sdlc:init` | Initialize framework or add milestones |
 | `/sdlc:help` | Show command reference |
 
 ---
 
 ## Engineering Laws
 
-Laws are enforced at `/sdlc:review`. Violations at `error` severity block `/sdlc:close`.
+Laws are enforced at `/sdlc:verify` (Phase 2). Violations at `error` severity block `/sdlc:close`.
 
 | Law | Default | What it enforces |
 |-----|---------|-----------------|
@@ -241,9 +261,10 @@ Severity is configurable per project in `.sdlc/LAWS.md`:
 ├── phases/
 │   └── 01-phase-name/
 │       ├── 01-01-SPEC.md
-│       ├── 01-01-REVIEW.md
+│       ├── 01-01-VERIFY.md
 │       └── 01-01-SUMMARY.md
-└── research/           # Sub-agent research output
+├── discuss/            # PRD documents from /sdlc:discuss
+└── research/           # Research findings (generated by /sdlc:discuss when unknowns detected)
 ```
 
 ---
@@ -254,7 +275,7 @@ Severity is configurable per project in `.sdlc/LAWS.md`:
 
 | Aspect | PAUL | SDLC |
 |--------|------|------|
-| Commands | 26 (cognitive overload) | 15 (focused) |
+| Commands | 26 (cognitive overload) | 11 (focused) |
 | Testing | Manual UAT | Automated (Playwright MCP) |
 | Code review | None | Engineering Laws enforcement |
 | Implementation | In-session | Sub-agent parallel waves |
@@ -304,7 +325,29 @@ npx sdlc-framework@latest
 - Check `.sdlc/STATE.md` directly
 
 **Resuming after a break?**
-- Run `/sdlc:resume` — it reads state and handoffs automatically
+- Run `/sdlc:status resume` — it reads state and handoffs automatically
+
+---
+
+## What's New in v1.0.1
+
+**Verify and review merged. Plan verification before implementation. Playwright pre-checks.**
+
+- **Verify + Review merged into one command** — `/sdlc:verify` now runs two phases: Phase 1 tests acceptance criteria (Playwright MCP, curl, test runners), Phase 2 reviews code against engineering laws (SOLID, DRY, YAGNI, etc.). One command, one artifact (`VERIFY.md`), one fewer step in the loop. `/sdlc:review` is removed.
+- **Pre-flight plan verification** — `/sdlc:impl` now validates the spec plan before spawning agents: AC↔task coverage, file existence, boundary compliance, dependency integrity. Catches gaps before expensive agent execution.
+- **Playwright MCP pre-check** — Before running UI verifications, the framework calls `browser_install` and tests navigation to confirm Playwright MCP is available and the app is running. Fails fast with clear error instead of silently skipping.
+- **Auto-advance fixed** — Phase transitions now correctly set `loop_position: CLOSE ✓` so auto-advance to the next spec works reliably across all loop states.
+- **11 commands** (down from 12) — Verify absorbs review. Less to learn, same enforcement.
+
+### Previous: v3.1.0
+
+- Explicit verification types on every AC (Type field).
+- Codebase gap analysis in spec phase.
+- 7 integrity checks in spec integrity review.
+
+### Previous: v3.0.0
+
+- Research merged into Discuss. Transition absorbed into Close. Auto-advance. 12 commands.
 
 ---
 

package/bin/install.js

@@ -144,10 +144,10 @@ function install(isGlobal) {
 
   ${yellow}Quick start:${reset}
     ${dim}1.${reset} /sdlc:init          ${dim}— Initialize project${reset}
-    ${dim}2.${reset} /sdlc:spec          ${dim}— Define what to build${reset}
-    ${dim}3.${reset} /sdlc:impl          ${dim}— Build it (sub-agent parallel)${reset}
-    ${dim}4.${reset} /sdlc:verify        ${dim}— Playwright auto-test${reset}
-    ${dim}5.${reset} /sdlc:review        ${dim}— Engineering laws check${reset}
+    ${dim}2.${reset} /sdlc:discuss       ${dim}— Brainstorm idea into PRD (optional)${reset}
+    ${dim}3.${reset} /sdlc:spec          ${dim}— Define what to build${reset}
+    ${dim}4.${reset} /sdlc:impl          ${dim}— Build it (sub-agent parallel)${reset}
+    ${dim}5.${reset} /sdlc:verify        ${dim}— Test ACs + engineering laws review${reset}
     ${dim}6.${reset} /sdlc:close         ${dim}— Close the loop${reset}
 
   ${dim}Or for small tasks:${reset} /sdlc:fast "add logout button"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdlc-framework",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Structured Development Lifecycle - A closed-loop AI-assisted development framework for Claude Code",
   "bin": {
     "sdlc-framework": "bin/install.js"
@@ -31,7 +31,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": ""
+    "url": "https://github.com/nadyshalaby/sdlc-framework.git"
   },
   "engines": {
     "node": ">=16.7.0"

package/src/commands/close.md

@@ -1,34 +1,37 @@
 ---
 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). 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.
+**When to use:** After /sdlc:verify completes with no blockers. This is the CLOSE phase of the SDLC loop.
 
 **What it does:**
-1. Read all artifacts from the current loop: SPEC, IMPL, VERIFY, REVIEW.
+1. Read all artifacts from the current loop: SPEC, IMPL, VERIFY (contains both AC results and review findings).
 2. Compare planned vs actual: tasks completed, ACs met, scope adhered to.
 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 directs you to the next milestone/phase.
+- 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.
 
 **Critical rule:** No loop closes without reconciliation. Every deviation from the spec is documented with a reason. Lessons learned feed into the next loop.
 </objective>
 
 <execution_context>
-@~/.claude/sdlc-framework/workflows/close-loop.md
+@~/.claude/sdlc-framework/workflows/close-phase.md
 @.sdlc/STATE.md
 @.sdlc/ROADMAP.md
+@.sdlc/PROJECT.md
 </execution_context>
 
 <context>
@@ -37,23 +40,22 @@ $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.
-- .sdlc/review/REVIEW-<plan-id>.md — what was reviewed.
 </context>
 
 <process>
-Follow workflow: @~/.claude/sdlc-framework/workflows/close-loop.md
+Follow workflow: @~/.claude/sdlc-framework/workflows/close-phase.md
 
 Step-by-step:
 
 1. **Load all loop artifacts**
-   - Read .sdlc/STATE.md. Confirm loop_position is REVIEW_COMPLETE. If not, warn: "Review not complete. Run /sdlc:review first."
+   - Read .sdlc/STATE.md. Confirm loop_position is VERIFY ✓. If not, warn: "Verification not complete. Run /sdlc:verify first."
    - Read SPEC-<plan-id>.md — extract: objective, acceptance criteria, tasks, boundaries.
    - Read IMPL-<plan-id>.md — extract: tasks completed, files modified, build status.
-   - Read VERIFY-<plan-id>.md — extract: AC results (pass/fail per criterion).
-   - Read REVIEW-<plan-id>.md — extract: findings summary, warnings count.
+   - Read VERIFY-<plan-id>.md — extract: AC results (Phase 1) and review findings (Phase 2).
 
 2. **Reconcile: Planned vs Actual**
 
@@ -91,7 +93,7 @@ Step-by-step:
    Compile all design decisions made during this loop:
    - Decisions from /sdlc:spec (architectural choices).
    - Decisions from /sdlc:impl (implementation choices).
-   - Decisions from /sdlc:review (remediation approaches).
+   - Decisions from /sdlc:verify (remediation approaches).
    Include the rationale for each decision.
 
 5. **Extract lessons learned**
@@ -155,7 +157,7 @@ Step-by-step:
    ```
 
 7. **Update STATE.md**
-   - Set `loop_position: SPEC` (ready for next loop).
+   - Set `loop_position: CLOSE ✓` (ready for next loop).
    - Archive the current plan: move plan-id to `completed_plans` list.
    - Determine next action:
      - Read ROADMAP.md to find the next plan in the current phase.
@@ -171,20 +173,41 @@ 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
-   - If milestone is complete but more milestones exist:
-     - Output: "Milestone <milestone-name> complete. Next milestone: <next-milestone-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."
-     - End with: "Project complete. Run /sdlc:init to start a new project or update ROADMAP.md with new milestones."
+     - End with: "Project complete. Run /sdlc:init milestone <name> to plan the next milestone."
+
+10. **Milestone completion** (when all phases in current milestone are done)
+    a. Verify all phases in current milestone are marked complete in ROADMAP.md.
+    b. Generate milestone summary by reading all SUMMARY.md files across phases:
+       - Total phases, plans executed, hotfixes applied.
+       - Consolidated deliverables, key decisions, technical debt.
+    c. Create git tag (ask user first):
+       - `git tag -a "milestone-{number}-{name}" -m "Milestone {number}: {name} complete"`
+    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.
+         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>
 
 <success_criteria>
-- [ ] All loop artifacts read: SPEC, IMPL, VERIFY, REVIEW
+- [ ] All loop artifacts read: SPEC, IMPL, VERIFY (contains AC results + review findings)
 - [ ] Task reconciliation complete: each task marked completed, skipped, or modified
 - [ ] Acceptance criteria reconciliation complete: every AC mapped to pass/fail
 - [ ] Scope reconciliation complete: files planned vs files modified compared
@@ -193,8 +216,10 @@ Step-by-step:
 - [ ] Key decisions recorded with rationale
 - [ ] Lessons learned extracted from the loop
 - [ ] SUMMARY-<plan-id>.md created with full reconciliation
-- [ ] STATE.md updated: loop_position reset to SPEC, current plan advanced
+- [ ] STATE.md updated: loop_position set to CLOSE ✓, current plan advanced
 - [ ] ROADMAP.md updated: completed plan/phase/milestone marked as done
 - [ ] Correct next action determined based on roadmap position
-- [ ] Output ends with NEXT ACTION REQUIRED: /sdlc:spec (or project complete message)
+- [ ] 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 auto-advance directive to /sdlc:spec (or project complete message)
 </success_criteria>

package/src/commands/debug.md

@@ -17,11 +17,11 @@ Structured debugging that follows a disciplined flow: REPRODUCE, ISOLATE, ROOT-C
 4. Apply a fix that follows engineering laws.
 5. Verify the fix by re-running the reproduction and regression tests.
 
-**What happens next:** /sdlc:review to validate the fix meets engineering standards.
+**What happens next:** /sdlc:verify to validate the fix meets engineering standards.
 </objective>
 
 <execution_context>
-@~/.claude/sdlc-framework/workflows/debug.md
+@~/.claude/sdlc-framework/workflows/debug-flow.md
 @.sdlc/STATE.md
 @.sdlc/LAWS.md
 </execution_context>
@@ -35,7 +35,7 @@ Gather any error messages, stack traces, or reproduction steps from the user's d
 </context>
 
 <process>
-Follow workflow: @~/.claude/sdlc-framework/workflows/debug.md
+Follow workflow: @~/.claude/sdlc-framework/workflows/debug-flow.md
 
 Step-by-step:
 
@@ -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:verify.
 </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:verify
 </success_criteria>

package/src/commands/discuss.md

@@ -0,0 +1,90 @@
+---
+name: sdlc:discuss
+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, Agent, WebSearch, WebFetch, AskUserQuestion]
+---
+
+<objective>
+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. 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. 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. Research spawns inline when unknowns exist — skip research when the idea is clear enough.
+</objective>
+
+<execution_context>
+@~/.claude/sdlc-framework/workflows/discuss-phase.md
+@~/.claude/sdlc-framework/templates/PRD.md
+@~/.claude/sdlc-framework/references/clarification-strategy.md
+@.sdlc/STATE.md
+@.sdlc/PROJECT.md
+</execution_context>
+
+<context>
+$ARGUMENTS — optional idea description or topic to explore.
+
+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>
+
+<process>
+Follow workflow: @~/.claude/sdlc-framework/workflows/discuss-phase.md
+
+Step-by-step:
+
+1. **Seed the idea**
+   - If $ARGUMENTS provided, acknowledge the idea and restate it.
+   - If no arguments, ask: "What idea or problem do you want to explore?"
+
+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 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.
+   - If APPROVE: route to /sdlc:spec.
+
+5. **Update STATE.md and output**
+   - Record discussion reference. Set next_required_action: /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 auto-advance directive to /sdlc:spec
+</success_criteria>