sdlc-framework 1.0.2 → 2.1.0

package/src/workflows/fast-forward.md

@@ -1,10 +1,10 @@
-<purpose>The universal entry point workflow. Accept a plain language description, classify the work, estimate complexity, and either execute inline (simple work) or route to the appropriate specialized command (complex work, bugs, research, hotfixes). This is the "just tell me what to do" workflow.</purpose>
+<purpose>The universal entry point workflow. Accept a plain language description, classify the work, estimate complexity, and either execute inline (simple work), handle critical issues as inline hotfixes, or route to the appropriate specialized command. This is the "just tell me what to do" workflow.</purpose>
 <when_to_use>Use anytime. This is the default way to start work. The user describes what they need, and this workflow figures out the rest. No prior knowledge of SDLC commands required.</when_to_use>
 <required_reading>.sdlc/STATE.md, .sdlc/PROJECT.md, .sdlc/LAWS.md</required_reading>
 <loop_context>
-  expected_phase: FAST (compressed loop or routing)
+  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, HOTFIX, RESEARCH, or self-contained
+  next_phase: depends on routing — SPEC, DEBUG, RESEARCH, DISCUSS, or self-contained
 </loop_context>
 <references>
 @~/.claude/sdlc-framework/references/prompt-detection.md
@@ -49,10 +49,9 @@
 
   1. CRITICAL — urgent production issues
      Indicators: "urgent", "production", "down", "outage", "critical", "P0", "hotfix", "emergency", "ASAP"
-     Route: /sdlc:hotfix
-     Display: "Critical issue detected. Routing to /sdlc:hotfix for emergency handling."
-     Write to STATE.md: fast_context = {original description}
-     STOP this workflow.
+     Route: inline hotfix (skip to inline_hotfix step)
+     Display: "Critical issue detected. Running inline hotfix — minimal spec, full verification."
+     Do NOT stop — proceed to inline_hotfix step.
 
   2. BUG — something broken that needs debugging
      Indicators: "fix bug", "broken", "crash", "error when", "fails to", "wrong output", "regression", "not working", "throws", "exception"
@@ -337,4 +336,56 @@
   WHY: Fast is a side-quest. It records what happened (audit trail) but does not disrupt the main loop state.
 </step>
 
+<step name="inline_hotfix" priority="tenth">
+  ONLY IF classification = CRITICAL. 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, critical path unavailable
+  - P1: data corruption, security breach, data loss
+  - P2: major feature broken but system is up
+
+  If not P0/P1: Display "This may not be critical. Consider /sdlc:debug instead." Let user override.
+
+  Save current STATE.md position — hotfix restores it when done.
+
+  B. 3-LINE INLINE SPEC:
+  - Line 1: WHAT is broken (from triage)
+  - Line 2: WHERE is the likely location (quick Grep search)
+  - Line 3: WHAT the fix should achieve (expected behavior)
+  Display but do NOT wait for approval — speed matters.
+  Boundary: fix ONLY the critical issue. No refactoring. No cleanup.
+
+  C. FIX DIRECTLY:
+  - Single-threaded, no sub-agents
+  - Read relevant files, apply MINIMAL fix
+  - Engineering laws still apply (no empty catch, no hardcoded secrets)
+  - Add regression test for the specific failure
+  - Mark debt with TODO(hotfix-{date})
+
+  D. FULL VERIFICATION:
+  - Run FULL test suite (all tests, not just affected)
+  - For UI: Playwright verification
+  - If any fail: fix before proceeding
+
+  E. FULL REVIEW:
+  - Check all modified files against engineering laws
+  - Security blockers still block even in emergencies
+  - Warnings acceptable for hotfixes
+
+  F. RECORD:
+  - Hotfix number = {phase}.{count+1} (e.g., 02.1, 02.2)
+  - 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 completion summary with verification results
+
+  WHY: Hotfixes trade planning ceremony for speed, but never trade verification or review. The inline approach avoids command-switching overhead during emergencies while maintaining quality gates.
+</step>
+
 </process>

package/src/workflows/init-project.md

@@ -152,7 +152,7 @@
   | ... | ... | ... | ... |
 
   ## Future Milestones
-  {Leave blank — added via /sdlc:milestone}
+  {Leave blank — added via /sdlc:init milestone <name>}
   ```
 
   WHY: The roadmap gives structure to the work. Without it, specs are disconnected tasks with no arc. The phase structure ensures work builds on itself in a logical order.

package/src/workflows/status-session.md

@@ -0,0 +1,206 @@
+<purpose>Show loop position, save session context (pause), or restore session context (resume). Consolidates status, pause, and resume into a single workflow. The state machine always knows the next action — this workflow surfaces it.</purpose>
+<when_to_use>Run anytime. No-arg for status. "pause" before a break. "resume" when returning. Can run at any loop position.</when_to_use>
+<required_reading>.sdlc/STATE.md, .sdlc/ROADMAP.md</required_reading>
+<loop_context>
+  expected_phase: any (status/pause/resume work at any loop position)
+  prior_phase: current position is preserved
+  next_phase: determined by STATE.md
+</loop_context>
+<process>
+
+<step name="determine_mode" priority="first">
+  Parse $ARGUMENTS to determine the mode.
+
+  IF $ARGUMENTS is empty or not "pause"/"resume": MODE = STATUS
+  IF $ARGUMENTS starts with "pause": MODE = PAUSE. Extract optional reason.
+  IF $ARGUMENTS starts with "resume": MODE = RESUME. Extract optional handoff path.
+
+  Read .sdlc/STATE.md.
+
+  IF .sdlc/ does not exist:
+    Display: "Framework not initialized. Run /sdlc:init first."
+    STOP.
+
+  Extract: loop_position, current_milestone, current_phase, current_plan, next_required_action, blockers, deferred_issues.
+
+  WHY: One entry point with three modes eliminates the need for three separate commands. The state file is the single source of truth regardless of mode.
+</step>
+
+<step name="show_status" priority="second">
+  ONLY IF MODE = STATUS.
+
+  Read .sdlc/ROADMAP.md for milestone progress data.
+
+  Display the core loop with 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, show as a side branch off IMPLEMENT.
+
+  Display project context:
+  ```
+  Milestone: {name} ({completed_phases}/{total_phases} phases)
+  Phase:     {name}
+  Plan:      {name or "none — run /sdlc:spec"}
+  ```
+
+  Calculate and display progress bar from ROADMAP.md:
+  ```
+  Progress: [████████░░░░░░░░░░░░] 40% (4/10 plans completed)
+  ```
+
+  Show blockers and deferred issues (or "No blockers. No deferred issues.").
+
+  Force ONE next action from loop_position with explanation:
+  ```
+  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.
+  ```
+
+  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>
+
+<step name="pause_gather_context" priority="third">
+  ONLY IF MODE = PAUSE.
+
+  Gather session context:
+
+  A. GIT STATE:
+     Run: git status --short (if git repo)
+     Run: git log --oneline -5
+
+  B. WORK COMPLETED THIS SESSION:
+     Read STATE.md history entries. Summarize recent work.
+
+  C. IN-PROGRESS WORK:
+     Read any active spec, review, or summary files referenced in STATE.md.
+     Determine: which tasks done, which pending, which ACs verified.
+
+  D. DECISIONS AND BLOCKERS:
+     Scan recent .sdlc/ files for recorded decisions.
+     Note any blockers from STATE.md.
+
+  E. USER CONTEXT:
+     Ask: "Anything to remember for next session not already in files? (or press enter to skip)"
+     Record response if provided.
+
+  WHY: Session context is ephemeral — conversation history may not survive. The handoff captures it before it is lost.
+</step>
+
+<step name="pause_save" priority="fourth">
+  ONLY IF MODE = PAUSE.
+
+  Create .sdlc/HANDOFF.md (overwrite if exists):
+  ```markdown
+  # Session Handoff
+
+  ## Session Info
+  - **Paused at**: {ISO timestamp}
+  - **Reason**: {from arguments or "manual pause"}
+  - **Loop position**: {from STATE.md}
+  - **Next required action**: {from STATE.md}
+
+  ## What Was Done This Session
+  {Bulleted list of work completed}
+
+  ## Current State
+  - **Phase**: {phase name and number}
+  - **Plan**: {plan number and title, or "no active plan"}
+  - **Loop step**: {position} — {status}
+
+  ## In-Progress Work
+  {What is partially done — specific tasks, files, ACs}
+
+  ## Decisions Made
+  {List of decisions with rationale}
+
+  ## Blockers / Open Questions
+  {List or "None"}
+
+  ## User Context
+  {Verbatim notes from the user, if any}
+
+  ## Git State
+  - **Branch**: {current branch}
+  - **Commit**: {latest commit hash and message}
+  - **Uncommitted changes**: {yes/no — details}
+  ```
+
+  IF UNCOMMITTED CHANGES EXIST:
+    Ask: "You have uncommitted changes. Create a WIP commit? (yes/no)"
+    If yes: stage relevant files (not .env), commit "wip({phase}): {brief description}"
+    If no: note in handoff that uncommitted changes exist.
+
+  Update STATE.md: add paused_at timestamp, history entry. Do NOT change loop_position.
+
+  Display:
+  ```
+  Session saved.
+
+  Handoff: .sdlc/HANDOFF.md
+  State: {loop_position}
+  Next action (on resume): {next_required_action}
+
+  When you return, run /sdlc:status resume
+  ```
+
+  WHY: HANDOFF.md bridges sessions. The explicit resume instruction ensures the next session starts correctly.
+</step>
+
+<step name="resume_restore" priority="fifth">
+  ONLY IF MODE = RESUME.
+
+  A. LOCATE HANDOFF:
+     If path in $ARGUMENTS: use that file.
+     Else if .sdlc/HANDOFF.md exists: use it.
+     Else: display "No handoff found. Resuming from STATE.md." Skip to next-action determination.
+
+  B. READ AND DISPLAY CONTEXT:
+     Read handoff. Calculate time since pause.
+     ```
+     === SESSION RESUMED ===
+
+     Last session: {time} ago
+     Loop position: {position}
+
+     Work in progress:
+     - {from handoff}
+
+     Decisions:
+     - {from handoff}
+
+     Blockers:
+     - {from handoff, or "None"}
+     ```
+
+     If blockers: ask "These blockers were noted. Are they resolved?"
+
+  C. VERIFY GIT STATE:
+     Run: git status
+     Compare branch and uncommitted changes to handoff.
+     If branch changed: warn.
+     If new commits since pause: display them.
+
+  D. ARCHIVE HANDOFF:
+     Rename .sdlc/HANDOFF.md to .sdlc/HANDOFF-{timestamp}.md.archived
+     Remove paused_at from STATE.md.
+     Add history entry: "{timestamp} | resume | Resumed from {loop_position}."
+
+  E. FORCE NEXT ACTION:
+     Determine from STATE.md next_required_action.
+     Display: "NEXT ACTION REQUIRED: {action}"
+
+  WHY: Exactly ONE next action. The state machine has already decided. The user just executes it.
+</step>
+
+</process>

package/src/workflows/transition-phase.md

@@ -113,7 +113,7 @@
   IF NO NEXT PHASE (this was the last phase in the milestone):
     Update .sdlc/STATE.md:
     - loop_position: TRANSITION ✓
-    - next_required_action: /sdlc:milestone complete
+    - next_required_action: /sdlc:close (milestone completion handled inline)
     - Add history entry: "{timestamp} | transition | Phase {current} complete. Last phase in milestone. Trigger milestone completion."
 
     Update .sdlc/ROADMAP.md:
@@ -193,8 +193,8 @@
     Completed: Phase {number} — {name} (LAST PHASE)
     Milestone {milestone-number} — {milestone-name}: ALL PHASES COMPLETE
 
-    NEXT ACTION REQUIRED: /sdlc:milestone complete
-    Run /sdlc:milestone complete to finalize the milestone.
+    NEXT ACTION REQUIRED: /sdlc:close
+    Run /sdlc:close to finalize the milestone.
     ```
 
   WHY: The display makes the transition visible. Moving to a new phase is a significant moment — the user should know where they are in the broader plan.

package/src/commands/hotfix.md

@@ -1,99 +0,0 @@
----
-name: sdlc:hotfix
-description: "Emergency fix with minimal ceremony, maximum verification"
-argument-hint: "<critical-issue>"
-allowed-tools: [Read, Write, Bash, Glob, Grep, Edit, mcp__plugin_playwright_playwright__browser_navigate, mcp__plugin_playwright_playwright__browser_snapshot, mcp__plugin_playwright_playwright__browser_click, mcp__plugin_playwright_playwright__browser_fill_form, mcp__plugin_playwright_playwright__browser_take_screenshot, mcp__plugin_playwright_playwright__browser_evaluate, mcp__plugin_playwright_playwright__browser_console_messages, mcp__plugin_playwright_playwright__browser_close, AskUserQuestion]
----
-
-<objective>
-Emergency fix for critical issues. Minimal ceremony getting to the fix. Maximum verification after the fix. No corners cut on quality — only on planning overhead.
-
-**When to use:** Production is broken. A critical path is failing. Security vulnerability discovered. Something that cannot wait for a full SPEC cycle.
-
-**What it does:**
-1. Skip full spec — create a lightweight inline spec (3 lines).
-2. Fix the issue directly.
-3. Run FULL verification (tests + Playwright).
-4. Run FULL review (engineering laws compliance).
-5. Record as a hotfix with decimal phase numbering (2.1, 2.2, etc.).
-
-**What happens next:** /sdlc:verify to run the full verification suite.
-</objective>
-
-<execution_context>
-@~/.claude/sdlc-framework/workflows/hotfix.md
-@.sdlc/STATE.md
-@.sdlc/LAWS.md
-</execution_context>
-
-<context>
-$ARGUMENTS
-
-Read .sdlc/STATE.md to get current milestone and phase.
-Read .sdlc/LAWS.md — hotfixes are NOT exempt from engineering laws.
-</context>
-
-<process>
-Follow workflow: @~/.claude/sdlc-framework/workflows/hotfix.md
-
-Step-by-step:
-
-1. **Pre-flight check**
-   - Verify .sdlc/ exists. If not, tell the user to run /sdlc:init first.
-   - Read .sdlc/STATE.md to get current phase number (e.g., phase 2).
-   - Assign hotfix number: current phase + decimal increment (2.1, 2.2, etc.).
-   - Update STATE.md: set loop_position to HOTFIX, record hotfix number.
-
-2. **Lightweight inline spec (3 lines)**
-   - Line 1: WHAT is broken. (From $ARGUMENTS.)
-   - Line 2: WHERE is the likely location. (Quick search with Grep.)
-   - Line 3: WHAT the fix should achieve. (Expected behavior.)
-   - Record this inline spec in STATE.md under the hotfix entry.
-
-3. **Fix the issue**
-   - Search for the affected code using Grep and Read.
-   - Apply the fix. Follow engineering laws:
-     - DRY: use existing patterns.
-     - Handle edge cases.
-     - Named types for complex objects.
-     - No lint suppression. No non-null assertions.
-     - Max 40 lines per function.
-   - Keep the change surface as small as possible. Fix the issue, nothing more.
-
-4. **Full verification**
-   - Run the entire test suite. Not just affected tests — ALL tests.
-   - For UI-related hotfixes:
-     - Use Playwright to navigate to affected pages.
-     - Verify the fix visually with screenshots.
-     - Check console for errors.
-     - Test the happy path AND edge cases.
-   - If tests fail: fix the test failures before proceeding. Do not skip.
-
-5. **Full review against engineering laws**
-   - Read .sdlc/LAWS.md.
-   - Check every changed line against every applicable law.
-   - Verify: no dead code introduced, no unused imports, no inline complex types.
-   - If any law is violated: fix it. Hotfixes are not exempt.
-
-6. **Record in STATE.md**
-   - Update .sdlc/STATE.md:
-     - Record hotfix number (decimal: 2.1, 2.2, etc.).
-     - Record: issue description, files changed, tests run, verification status.
-     - Set loop_position back to current phase position.
-   - Create .sdlc/hotfixes/HOTFIX-{number}-{timestamp}.md with full details.
-
-7. **Force next action**
-   - Output: "NEXT ACTION REQUIRED: /sdlc:verify — run full verification suite to confirm no regressions."
-</process>
-
-<success_criteria>
-- [ ] Inline spec created (3 lines: what, where, expected behavior)
-- [ ] Fix applied following engineering laws — no exceptions for hotfixes
-- [ ] Full test suite runs and passes
-- [ ] Playwright verification completed for UI-related hotfixes
-- [ ] Engineering laws review passed on all changed code
-- [ ] Hotfix recorded in STATE.md with decimal phase numbering
-- [ ] Hotfix detail file created in .sdlc/hotfixes/
-- [ ] Change surface is minimal — only the fix, nothing extra
-- [ ] Output ends with NEXT ACTION REQUIRED: /sdlc:verify
-</success_criteria>

package/src/commands/milestone.md

@@ -1,136 +0,0 @@
----
-name: sdlc:milestone
-description: "Create or complete project milestones"
-argument-hint: "[create <name> | complete]"
-allowed-tools: [Read, Write, Bash, Glob, Grep, AskUserQuestion]
----
-
-<objective>
-Manage project milestones. Create new milestones with scope definition. Complete milestones with verification, archival, and tagging.
-
-**When to use:**
-- Starting a new body of work: `/sdlc:milestone create <name>`
-- Finishing a milestone: `/sdlc:milestone complete`
-- Checking milestone status: `/sdlc:milestone` (no argument)
-
-**What it does:**
-- **No argument:** Show current milestone status, phases, and progress.
-- **create:** Ask clarification questions about scope, then create milestone with phases.
-- **complete:** Verify all phases done, archive, update ROADMAP.md, create git tag.
-
-**What happens next:**
-- After create: /sdlc:spec to define the first unit of work.
-- After complete: Completion summary displayed.
-</objective>
-
-<execution_context>
-@~/.claude/sdlc-framework/workflows/milestone.md
-@.sdlc/STATE.md
-@.sdlc/ROADMAP.md
-</execution_context>
-
-<context>
-$ARGUMENTS — one of: empty, "create <name>", or "complete".
-
-Read .sdlc/STATE.md for current milestone.
-Read .sdlc/ROADMAP.md for milestone definitions and progress.
-</context>
-
-<process>
-Follow workflow: @~/.claude/sdlc-framework/workflows/milestone.md
-
-Step-by-step:
-
-### If no argument: SHOW STATUS
-
-1. Read .sdlc/ROADMAP.md.
-2. Read .sdlc/STATE.md for current milestone.
-3. Display:
-   ```
-   Current Milestone: {name}
-   Status: {in-progress | blocked}
-
-   Phases:
-   [x] Phase 1: {name} — completed
-   [x] Phase 2: {name} — completed
-   [ ] Phase 3: {name} — in progress (3/5 plans done)
-   [ ] Phase 4: {name} — not started
-
-   Progress: [████████████░░░░░░░░] 60%
-   ```
-4. Show the next required action based on current loop position.
-
-### If "create <name>": CREATE MILESTONE
-
-1. Parse the milestone name from $ARGUMENTS.
-2. Ask clarification questions via AskUserQuestion:
-   - "What is the objective of this milestone? (1-2 sentences)"
-   - "What are the key deliverables? (list 3-5)"
-   - "What does 'done' look like? (acceptance criteria)"
-   - "Estimated number of phases? (suggest based on deliverables)"
-3. Create the milestone in .sdlc/ROADMAP.md:
-   ```
-   ## Milestone: {name}
-   Objective: {from answer}
-   Status: in-progress
-
-   ### Phases
-   - Phase 1: {derived from deliverables}
-   - Phase 2: {derived from deliverables}
-   ...
-
-   ### Acceptance Criteria
-   - {from answer}
-   ```
-4. Update .sdlc/STATE.md:
-   - Set current_milestone to the new milestone name.
-   - Set current_phase to Phase 1.
-   - Set loop_position to SPEC.
-5. Output: "NEXT ACTION REQUIRED: /sdlc:spec — define the first unit of work for Phase 1."
-
-### If "complete": COMPLETE MILESTONE
-
-1. Read .sdlc/STATE.md and .sdlc/ROADMAP.md.
-2. Verify ALL phases in the current milestone are marked complete.
-   - If any phase is incomplete, output: "Cannot complete milestone. Phase {N}: {name} is not done. Complete it first." Then stop.
-3. Archive the milestone:
-   - Create .sdlc/archive/MILESTONE-{name}-{timestamp}.md with full milestone data.
-   - Mark the milestone as `completed` in ROADMAP.md with completion timestamp.
-4. Update ROADMAP.md:
-   - Set milestone status to `completed`.
-   - If there is a next milestone, note it.
-5. Create a git tag:
-   - Run `git tag -a milestone/{name} -m "Milestone completed: {name}"`.
-   - If git is not initialized or tag fails, warn but continue.
-6. Update STATE.md:
-   - Clear current_milestone if no next milestone.
-   - Or set current_milestone to the next milestone and loop_position to SPEC.
-7. Output completion summary:
-   ```
-   Milestone Complete: {name}
-
-   Phases completed: {N}
-   Plans executed: {N}
-   Hotfixes applied: {N}
-   Git tag: milestone/{name}
-
-   {If next milestone exists}
-   Next milestone: {name}
-   Run /sdlc:spec to begin.
-
-   {If no next milestone}
-   All milestones complete. Define new milestones with /sdlc:milestone create <name>.
-   ```
-</process>
-
-<success_criteria>
-- [ ] No argument: milestone status displayed with phase progress
-- [ ] Create: clarification questions asked, milestone added to ROADMAP.md, STATE.md updated
-- [ ] Create: output ends with NEXT ACTION REQUIRED: /sdlc:spec
-- [ ] Complete: all phases verified as done before completing
-- [ ] Complete: milestone archived to .sdlc/archive/
-- [ ] Complete: ROADMAP.md updated with completion status
-- [ ] Complete: git tag created
-- [ ] Complete: STATE.md updated for next milestone (or cleared)
-- [ ] No guessing — all scope gathered via clarification questions
-</success_criteria>

package/src/commands/pause.md

@@ -1,115 +0,0 @@
----
-name: sdlc:pause
-description: "Save context for session break"
-argument-hint: "[reason]"
-allowed-tools: [Read, Write, Bash, Glob, Grep, AskUserQuestion]
----
-
-<objective>
-Save complete session context so you can walk away and pick up exactly where you left off. Creates a HANDOFF.md that captures everything the next session needs.
-
-**When to use:** You need to take a break, switch tasks, or end your session. Run this before closing your terminal.
-
-**What it does:**
-1. Detect current loop position from STATE.md.
-2. Gather all context: work done, decisions made, blockers, in-progress tasks.
-3. Create HANDOFF.md with everything needed to resume.
-4. Optionally create a WIP git commit.
-5. Tell you exactly how to resume.
-
-**What happens next:** When you return, run /sdlc:resume.
-</objective>
-
-<execution_context>
-@~/.claude/sdlc-framework/workflows/pause-resume.md
-@.sdlc/STATE.md
-</execution_context>
-
-<context>
-$ARGUMENTS — optional reason for pausing (e.g., "end of day", "switching to urgent task").
-
-Read .sdlc/STATE.md to detect current loop position and active work.
-</context>
-
-<process>
-Follow workflow: @~/.claude/sdlc-framework/workflows/pause-resume.md
-
-Step-by-step:
-
-1. **Read current state**
-   - Read .sdlc/STATE.md to get:
-     - Current loop_position (SPEC, IMPLEMENT, VERIFY, REVIEW, CLOSE, DEBUG, HOTFIX).
-     - Current milestone and phase.
-     - Current plan (if any).
-     - Any recorded blockers.
-
-2. **Gather session context**
-   - Check git status for uncommitted changes (`git status --short`).
-   - Check git log for recent commits in this session (`git log --oneline -5`).
-   - Read any in-progress spec, plan, or task files referenced in STATE.md.
-   - Scan .sdlc/ for recently modified files (`find .sdlc -mmin -120 -type f`).
-
-3. **Create HANDOFF.md**
-   - Save to .sdlc/handoffs/HANDOFF-{timestamp}.md with:
-
-   ```
-   # Session Handoff — {timestamp}
-
-   ## Loop Position
-   {current loop_position} in {milestone} / {phase}
-
-   ## Work Completed This Session
-   - {list of completed tasks, commits, files changed}
-
-   ## Work In Progress
-   - {what was being worked on when paused}
-   - {current state of that work}
-
-   ## Decisions Made
-   - {any architectural or design decisions}
-
-   ## Blockers
-   - {anything preventing progress}
-
-   ## Uncommitted Changes
-   - {list of modified/untracked files from git status}
-
-   ## Resume Instructions
-   Run /sdlc:resume to continue.
-   The framework will pick up at: {loop_position}
-   Next action will be: {determined next action}
-   ```
-
-4. **Update STATE.md**
-   - Add session continuity section:
-     - `paused_at: {timestamp}`
-     - `pause_reason: {from $ARGUMENTS or "manual pause"}`
-     - `handoff_file: .sdlc/handoffs/HANDOFF-{timestamp}.md`
-   - Do NOT change loop_position — it stays where it was.
-
-5. **Offer WIP commit**
-   - Check if there are uncommitted changes.
-   - If yes, ask the user via AskUserQuestion:
-     "You have uncommitted changes. Create a WIP commit? (yes/no)"
-   - If yes: stage all changes and commit with message "WIP: {current task} [sdlc:pause]".
-   - If no: note in HANDOFF.md that uncommitted changes exist.
-
-6. **Output resume instructions**
-   - Print:
-     ```
-     Session paused. Context saved to .sdlc/handoffs/HANDOFF-{timestamp}.md
-
-     When you return, run: /sdlc:resume
-     ```
-   - Do not suggest any other actions. The only valid next step is /sdlc:resume.
-</process>
-
-<success_criteria>
-- [ ] Current loop position detected from STATE.md
-- [ ] All session context gathered (commits, changes, decisions, blockers)
-- [ ] HANDOFF.md created in .sdlc/handoffs/ with complete context
-- [ ] STATE.md updated with session continuity section
-- [ ] WIP commit offered if uncommitted changes exist
-- [ ] Output clearly states: "When you return, run /sdlc:resume"
-- [ ] No ambiguity — exactly one path forward
-</success_criteria>