sdlc-framework 1.0.2 → 2.0.0

package/README.md

@@ -76,13 +76,16 @@ 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
+# 5. The framework forces verify → review → close automatically
 # Just follow the NEXT ACTION REQUIRED prompts
 ```
 
@@ -120,6 +123,14 @@ 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
+- Every question includes a recommendation with concrete trade-offs
+- Produces a PRD document at `.sdlc/discuss/{topic}-PRD.md`
+- **User approval gate** — PRD must be approved before routing to `/sdlc:spec`
+
 ### SPEC — Define the work
 
 - Asks clarification questions (no guessing)
@@ -163,7 +174,7 @@ Follows: reproduce → isolate → root-cause → fix → verify.
 
 ## Commands
 
-15 commands, grouped by purpose. Run `/sdlc:help` for the full reference.
+13 commands, grouped by purpose. Run `/sdlc:help` for the full reference.
 
 ### Core Loop
 
@@ -187,23 +198,27 @@ Follows: reproduce → isolate → root-cause → fix → verify.
 |---------|-------------|
 | `/sdlc:fix` | Fix review blockers systematically, auto re-review |
 | `/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: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 & Research
 
 | 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:discuss [idea]` | Brainstorm an idea — AI asks questions, produces a PRD |
+| `/sdlc:research <topic>` | Deploy research sub-agents |
 
 ### 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 |
 
 ---
@@ -243,6 +258,7 @@ Severity is configurable per project in `.sdlc/LAWS.md`:
 │       ├── 01-01-SPEC.md
 │       ├── 01-01-REVIEW.md
 │       └── 01-01-SUMMARY.md
+├── discuss/            # PRD documents from /sdlc:discuss
 └── research/           # Sub-agent research output
 ```
 
@@ -254,7 +270,7 @@ Severity is configurable per project in `.sdlc/LAWS.md`:
 
 | Aspect | PAUL | SDLC |
 |--------|------|------|
-| Commands | 26 (cognitive overload) | 15 (focused) |
+| Commands | 26 (cognitive overload) | 13 (focused) |
 | Testing | Manual UAT | Automated (Playwright MCP) |
 | Code review | None | Engineering Laws enforcement |
 | Implementation | In-session | Sub-agent parallel waves |
@@ -304,7 +320,7 @@ 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
 
 ---
 

package/bin/install.js

@@ -144,11 +144,12 @@ 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}6.${reset} /sdlc:close         ${dim}— Close the loop${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}— Playwright auto-test${reset}
+    ${dim}6.${reset} /sdlc:review        ${dim}— Engineering laws check${reset}
+    ${dim}7.${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.2",
+  "version": "2.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

@@ -19,7 +19,8 @@ Close the current SDLC loop by reconciling what was planned (SPEC.md) against wh
 
 **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 advances to the next phase and directs to /sdlc:spec.
+- 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.
@@ -175,12 +176,24 @@ Step-by-step:
    - 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
+   - 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.
+         Output: "Milestone complete. Next: {name}. NEXT ACTION REQUIRED: /sdlc:spec"
+       - If none: clear current_milestone.
+         Output: "Milestone complete. No further milestones. Run /sdlc:init milestone <name> to plan the next."
 </process>
 
 <success_criteria>
@@ -196,5 +209,6 @@ 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
+- [ ] Milestone completion: summary generated, git tag created, ROADMAP.md updated (when applicable)
 - [ ] Output ends with NEXT ACTION REQUIRED: /sdlc:spec (or project complete message)
 </success_criteria>

package/src/commands/discuss.md

@@ -0,0 +1,81 @@
+---
+name: sdlc:discuss
+description: Brainstorm and shape an idea into a complete PRD through AI-driven questioning
+argument-hint: "[idea or topic]"
+allowed-tools: [Read, Write, Glob, Grep, 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.
+
+**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.
+
+**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.
+
+**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.
+</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.
+
+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 3: Approach validation — present options with trade-offs, 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.
+
+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 NEXT ACTION REQUIRED: /sdlc:spec
+</process>
+
+<success_criteria>
+- [ ] Idea explored through at least 2 rounds of structured questions
+- [ ] Every question included a recommendation with trade-offs
+- [ ] PRD created at .sdlc/discuss/{topic}-PRD.md with all required sections
+- [ ] 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
+</success_criteria>

package/src/commands/fast.md

@@ -11,14 +11,15 @@ 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).
+1. Classify the work type (feature, bug, refactor, test, docs, research, 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.
-   - Critical production issue: route to /sdlc:hotfix with context.
+   - Brainstorming: 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.
 
 **What happens next:** Depends on routing — either the task is complete, or you are directed to the appropriate specialized command.
@@ -58,9 +59,10 @@ Step-by-step:
 
    | Type | Indicators | Route |
    |------|-----------|-------|
+   | CRITICAL | "urgent", "production", "down", "outage", "critical", "P0", "hotfix" | inline hotfix |
    | BUG | "fix", "bug", "error", "broken", "crash", "fails", "wrong", "regression" | /sdlc:debug |
-   | CRITICAL | "urgent", "production", "down", "outage", "critical", "P0", "hotfix" | /sdlc:hotfix |
    | RESEARCH | "explore", "investigate", "research", "compare", "evaluate", "options" | /sdlc:research |
+   | DISCUSS | "brainstorm", "discuss", "idea", "what if", "think about", "concept", "should we", "could we" | /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 |
@@ -70,8 +72,9 @@ Step-by-step:
 
 3. **Immediate routing** (for specialized types)
    - BUG → Display: "Bug detected. NEXT ACTION REQUIRED: /sdlc:debug {original description}" — STOP.
-   - CRITICAL → Display: "Critical issue. NEXT ACTION REQUIRED: /sdlc:hotfix {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.
+   - CRITICAL → proceed to inline hotfix (step 10).
 
 4. **Complexity estimation** (for feature/refactor/test/docs)
    - Scan codebase for files related to the description.
@@ -132,15 +135,57 @@ Step-by-step:
    - Update STATE.md history.
    - Restore prior state (fast does not advance the phase).
    - Display completion summary.
+
+10. **Inline hotfix** (CRITICAL type only)
+    Emergency fix with minimal ceremony, maximum verification.
+
+    a. **Triage:** Ask 3 questions:
+       - "What is broken? (specific symptom)"
+       - "What is the impact? (who is affected)"
+       - "When did it start? (recent deploy, config change)"
+       Classify severity: P0 (system down), P1 (data risk), P2 (major feature broken).
+       If not P0/P1: suggest /sdlc:debug instead. Let user override.
+
+    b. **3-line inline spec:**
+       - Line 1: WHAT is broken (from $ARGUMENTS + triage).
+       - Line 2: WHERE is the likely location (quick Grep search).
+       - Line 3: WHAT the fix should achieve (expected behavior).
+       Display inline spec. Do NOT wait for approval — speed matters in emergencies.
+
+    c. **Fix directly:**
+       - Single-threaded. No sub-agents.
+       - Apply MINIMAL fix — change as few lines as possible.
+       - Engineering laws still apply. No empty catch blocks. No hardcoded secrets.
+       - Add a regression test for the specific failure.
+       - Mark technical debt with TODO(hotfix-{date}).
+
+    d. **Full verification:**
+       - Run FULL test suite (not just affected tests).
+       - For UI: Playwright verification.
+       - If any fail: fix before proceeding.
+
+    e. **Full review:**
+       - Check all modified files against engineering laws.
+       - Blockers (security, error handling) still block even in emergencies.
+       - Warnings are acceptable for hotfixes.
+
+    f. **Record:**
+       - Determine hotfix number: {phase}.{count+1} (e.g., 02.1).
+       - Create .sdlc/phases/{phase}/HOTFIX-{number}-SUMMARY.md.
+       - Update STATE.md: restore prior state, add history entry.
+       - Update ROADMAP.md: note hotfix under current phase.
+       - Display: "Hotfix {number} applied and verified. State restored."
 </process>
 
 <success_criteria>
 - [ ] Work classified correctly from natural language description
 - [ ] Bugs routed to /sdlc:debug — never processed inline
-- [ ] Critical issues routed to /sdlc:hotfix
+- [ ] Critical issues handled as inline hotfix with full verify + review
 - [ ] Research tasks routed to /sdlc:research
+- [ ] Brainstorming 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
 - [ ] All code changes comply with engineering laws
 - [ ] Tests run and pass
 - [ ] STATE.md updated appropriately

package/src/commands/help.md

@@ -54,30 +54,29 @@ COMMANDS — Quick Entry
 
   /sdlc:fast      THE DEFAULT. Describe work, framework routes + executes.
                   Simple work runs inline. Complex work routes to /sdlc:spec.
-                  Bugs route to /sdlc:debug. Critical issues to /sdlc:hotfix.
+                  Bugs route to /sdlc:debug. Critical issues run as inline hotfix.
 
 COMMANDS — Fix & Debug
 ──────────────────────
 
   /sdlc:fix       Fix review blockers systematically, then auto re-review.
   /sdlc:debug     Structured debugging: reproduce → isolate → root-cause → fix → verify.
-  /sdlc:hotfix    Emergency fix. Minimal ceremony, maximum verification.
 
 
-COMMANDS — Session Management
-─────────────────────────────
+COMMANDS — Session & Status
+───────────────────────────
 
-  /sdlc:pause     Save context for a break. Creates HANDOFF.md.
-  /sdlc:resume    Restore context. Determines ONE next action.
-  /sdlc:status    Show current loop position, progress, and forced next action.
+  /sdlc:status              Show loop position, progress, forced next action.
+  /sdlc:status pause        Save context for a break. Creates HANDOFF.md.
+  /sdlc:status resume       Restore context. Determines ONE next action.
 
 
 COMMANDS — Planning & Research
 ──────────────────────────────
 
-  /sdlc:milestone Create or complete project milestones.
+  /sdlc:discuss   Brainstorm an idea. AI asks questions, produces a PRD.
   /sdlc:research  Deploy subagents for codebase or web research.
-  /sdlc:init      Initialize the framework in a project. Run once.
+  /sdlc:init      Initialize framework or add milestones. Run once.
   /sdlc:help      Show this reference.
 
 
@@ -134,7 +133,7 @@ If .sdlc/LAWS.md exists, read it and append any project-specific law customizati
 
 <success_criteria>
 - [ ] Core loop diagram displayed
-- [ ] All 15 commands listed with one-line descriptions
+- [ ] All 13 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/init.md

@@ -6,15 +6,16 @@ allowed-tools: [Read, Write, Bash, Glob, Grep, Edit, AskUserQuestion]
 ---
 
 <objective>
-Initialize the SDLC framework for a project. Create the .sdlc/ directory with four core files: PROJECT.md, STATE.md, ROADMAP.md, and LAWS.md.
+Initialize the SDLC framework for a project. Create the .sdlc/ directory with core files: PROJECT.md, STATE.md, ROADMAP.md, and LAWS.md. Define the first milestone with phases.
 
-**When to use:** First time setting up SDLC in a project. Run this once per repository.
+**When to use:** First time setting up SDLC in a project. Run this once per repository. Also use to create additional milestones: `/sdlc:init milestone <name>`.
 
 **What it does:**
 1. Scan the current directory to understand project structure (language, framework, existing config).
 2. Ask clarification questions about project goals, team conventions, and quality thresholds.
 3. Create .sdlc/ directory with populated templates.
-4. Set the loop position to SPEC (the first phase of the development cycle).
+4. Define the first milestone with phases (or add a new milestone if already initialized).
+5. Set the loop position to SPEC (the first phase of the development cycle).
 
 **What happens next:** Framework directs you to /sdlc:spec to define your first unit of work.
 </objective>
@@ -28,10 +29,12 @@ Initialize the SDLC framework for a project. Create the .sdlc/ directory with fo
 </execution_context>
 
 <context>
-$ARGUMENTS
+$ARGUMENTS — optional project name, or "milestone <name>" to create an additional milestone.
 
 Current directory contents (run ls to inspect).
-Check if .sdlc/ already exists — if it does, warn the user and ask whether to reinitialize or abort.
+Check if .sdlc/ already exists:
+- If "milestone <name>" in $ARGUMENTS: add a new milestone (skip project setup).
+- Otherwise: warn the user and ask whether to reinitialize or abort.
 Read any existing package.json, Cargo.toml, pyproject.toml, go.mod, or similar to detect project type.
 </context>
 
@@ -80,6 +83,19 @@ Step-by-step:
    - Print summary of created files.
    - Print the first milestone and phase.
    - End with NEXT ACTION REQUIRED.
+
+### If "milestone <name>" in $ARGUMENTS: ADD MILESTONE
+
+1. Verify .sdlc/ exists. If not: "Run /sdlc:init first (without 'milestone')."
+2. Read .sdlc/ROADMAP.md. Calculate next milestone number.
+3. Ask clarification questions:
+   - "What is the goal of this milestone? What will be true when it is done?"
+   - "What phases make up this milestone? (2-5 phases in order)"
+   - "Any dependencies on prior milestones?"
+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"
 </process>
 
 <success_criteria>

package/src/commands/status.md

@@ -1,118 +1,84 @@
 ---
 name: sdlc:status
-description: "Show loop position and forced next action"
-allowed-tools: [Read, Glob, Grep]
+description: "Show loop position, pause/resume sessions, and force next action"
+argument-hint: "[pause [reason] | resume [handoff-path]]"
+allowed-tools: [Read, Write, Bash, Glob, Grep, AskUserQuestion]
 ---
 
 <objective>
-Show exactly where you are in the SDLC loop and what you must do next. Visual progress, current state, and forced next action. Designed for junior developers who need clear guidance.
+Show exactly where you are in the SDLC loop. Optionally pause (save context) or resume (restore context). One command for all session awareness.
 
-**When to use:** You are lost. You do not know what to do next. You want to see progress. Run this anytime.
+**When to use:**
+- No argument: see loop position, progress, and forced next action.
+- `pause`: save session context before a break. Creates HANDOFF.md.
+- `resume`: restore session context after a break. Reads HANDOFF.md.
 
 **What it does:**
-1. Read STATE.md for current position.
-2. Display milestone, phase, plan, and loop position with a visual diagram.
-3. Show progress bar and any blockers.
-4. Force exactly ONE next action with an explanation of what it does and why.
+- **No argument:** Read STATE.md, display visual loop diagram, progress bar, blockers, and force ONE next action.
+- **pause:** Gather session context, create HANDOFF.md, optionally WIP commit. Tell user to run `/sdlc:status resume` when they return.
+- **resume:** Read HANDOFF.md, display restored context, verify git state, archive handoff, force ONE next action.
 
-**What happens next:** The forced next action. No choices.
+**What happens next:** The forced next action. No choices — the state machine decides.
 </objective>
 
 <execution_context>
+@~/.claude/sdlc-framework/workflows/status-session.md
 @.sdlc/STATE.md
 @.sdlc/ROADMAP.md
 </execution_context>
 
 <context>
-No arguments required.
+$ARGUMENTS — empty, "pause [reason]", or "resume [handoff-path]".
 
-Read .sdlc/STATE.md for current loop position, milestone, phase, plan.
-Read .sdlc/ROADMAP.md for milestone completion data.
+Read .sdlc/STATE.md for current loop position.
+Read .sdlc/ROADMAP.md for milestone progress.
 </context>
 
 <process>
+Follow workflow: @~/.claude/sdlc-framework/workflows/status-session.md
+
 Step-by-step:
 
-1. **Read state**
-   - Read .sdlc/STATE.md. If it does not exist, output: "Framework not initialized. Run /sdlc:init first." Then stop.
-   - Extract: loop_position, current_milestone, current_phase, current_plan, blockers, deferred_issues.
-   - Read .sdlc/ROADMAP.md for milestone progress data.
-
-2. **Display loop position (visual)**
-   - Show the core loop with the current position highlighted:
-
-   ```
-   SDLC Loop Position:
-
-     SPEC ──→ IMPLEMENT ──→ VERIFY ──→ REVIEW ──→ CLOSE
-      │                                              │
-      └──────────────── next cycle ←─────────────────┘
-
-     Current: [IMPLEMENT] ◄── YOU ARE HERE
-   ```
-
-   - Use `[PHASE]` brackets around the current position.
-   - If in DEBUG or HOTFIX, show those as side branches:
-
-   ```
-     SPEC ──→ IMPLEMENT ──→ VERIFY ──→ REVIEW ──→ CLOSE
-                  │
-                  ├──→ [DEBUG] ◄── YOU ARE HERE
-                  └──→ HOTFIX
-   ```
-
-3. **Display project context**
-   - Show:
-   ```
-   Milestone: {name} ({completed_phases}/{total_phases} phases)
-   Phase:     {name}
-   Plan:      {name or "none — run /sdlc:spec"}
-   ```
-
-4. **Show progress bar**
-   - Calculate completion percentage from ROADMAP.md.
-   - Display:
-   ```
-   Progress: [████████░░░░░░░░░░░░] 40% (4/10 plans completed)
-   ```
-
-5. **Show blockers and deferred issues**
-   - If blockers exist in STATE.md:
-   ```
-   BLOCKERS:
-   - {blocker 1}
-   - {blocker 2}
-   ```
-   - If deferred issues exist:
-   ```
-   DEFERRED:
-   - {issue 1}
-   - {issue 2}
-   ```
-   - If none: "No blockers. No deferred issues."
-
-6. **Force ONE next action with explanation**
-   - Determine the next action from loop_position (same logic as /sdlc:resume).
-   - Explain what that action DOES and WHY it is next:
-
-   ```
-   NEXT ACTION REQUIRED: /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.
-   Your implementation will be verified in the next step.
-   ```
-
-   - Junior-friendly: use plain language. Assume the reader has never used the framework.
+### If no argument: SHOW STATUS
+
+1. Read .sdlc/STATE.md. If missing: "Run /sdlc:init first." Stop.
+2. Display visual loop diagram with current position highlighted using `[PHASE]` brackets.
+3. Display project context: milestone, phase, plan, progress bar.
+4. Display blockers and deferred issues (or "None").
+5. Force ONE next action from loop_position with plain-language explanation.
+
+### If "pause": SAVE SESSION
+
+1. Read .sdlc/STATE.md to get current loop position and active work.
+2. Gather session context: git status, recent commits, in-progress tasks, decisions, blockers.
+3. Ask user: "Anything to remember for next session not already in files?"
+4. Create .sdlc/HANDOFF.md with full session context.
+5. Offer WIP commit if uncommitted changes exist.
+6. Update STATE.md: add paused_at timestamp, history entry. Do NOT change loop_position.
+7. Output: "Session saved. Run /sdlc:status resume when you return."
+
+### If "resume": RESTORE SESSION
+
+1. Locate handoff: from $ARGUMENTS path, STATE.md handoff_file field, or .sdlc/HANDOFF.md.
+2. If no handoff: fall back to STATE.md only. Display: "No handoff found. Resuming from state."
+3. Display restored context: loop position, work in progress, decisions, blockers.
+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.
 </process>
 
 <success_criteria>
-- [ ] STATE.md read successfully
-- [ ] Visual loop diagram displayed with current position highlighted
-- [ ] Milestone, phase, and plan shown
-- [ ] Progress bar calculated and displayed
-- [ ] Blockers and deferred issues shown (or "none")
-- [ ] Exactly ONE next action forced
-- [ ] Next action includes plain-language explanation of what it does and why
-- [ ] No choices, no menus — one clear path forward
+- [ ] No-arg: visual loop diagram displayed with current position
+- [ ] No-arg: progress bar and blockers shown
+- [ ] No-arg: exactly ONE next action forced with explanation
+- [ ] Pause: session context gathered (git, tasks, decisions, blockers)
+- [ ] Pause: HANDOFF.md created with complete context
+- [ ] Pause: WIP commit offered if uncommitted changes exist
+- [ ] Pause: output states "Run /sdlc:status resume when you return"
+- [ ] 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}
+- [ ] No menus, no options — one clear path forward
 </success_criteria>