sdlc-framework 1.0.0

package/src/workflows/milestone-management.md

@@ -0,0 +1,169 @@
+<purpose>Create new milestones or complete existing ones. Milestones are the highest-level organizational unit — they contain phases, which contain plans. This workflow manages the milestone lifecycle.</purpose>
+<when_to_use>Run to create a new milestone (/sdlc:milestone create) or complete an existing one (/sdlc:milestone complete). Also triggered automatically by transition-phase when the last phase in a milestone completes.</when_to_use>
+<required_reading>.sdlc/STATE.md, .sdlc/ROADMAP.md, .sdlc/PROJECT.md</required_reading>
+<loop_context>
+  expected_phase: MILESTONE (meta-workflow, operates above the loop)
+  prior_phase: varies
+  next_phase: SPEC (for new milestone) or none (project complete)
+</loop_context>
+<process>
+
+<step name="determine_operation" priority="first">
+  Determine whether the user wants to CREATE or COMPLETE a milestone.
+
+  IF explicitly specified (e.g., "/sdlc:milestone create" or "/sdlc:milestone complete"):
+    Use the specified operation.
+
+  IF not specified:
+    Read .sdlc/ROADMAP.md.
+    - If the current milestone has incomplete phases → likely COMPLETE is premature
+    - If the current milestone is done or no milestone is active → likely CREATE
+
+    Ask: "Do you want to:
+    A. Create a new milestone
+    B. Complete the current milestone ({name})
+    ?"
+
+  WHY: The two operations are very different. Creating sets up future work. Completing archives past work. Mixing them up would corrupt the state.
+</step>
+
+<step name="create_milestone" priority="second">
+  ONLY IF operation = CREATE.
+
+  A. GATHER MILESTONE INFO:
+
+  Question 1: "What is the milestone name? (e.g., 'MVP', 'Auth System', 'v2.0')"
+
+  Question 2: "What is the goal of this milestone? What will be true when it is done?"
+    - This becomes the milestone completion criteria
+    - Be specific: "Users can register, log in, and reset passwords" not "Auth works"
+
+  Question 3: "What phases make up this milestone? List 2-5 phases in order."
+    - Provide guidance: "Each phase should be a cohesive group of related work"
+    - Example: "Phase 01: Database Schema, Phase 02: API Endpoints, Phase 03: Frontend Forms"
+
+  Question 4: "Any dependencies on prior milestones? (e.g., requires 'MVP' milestone to be complete)"
+    - If yes: verify the dependency milestone is complete
+
+  Question 5: "Any rough timeline or priority? (optional)"
+
+  B. CALCULATE MILESTONE NUMBER:
+  Read ROADMAP.md. Count existing milestones. New milestone = max + 1, zero-padded to 2 digits.
+
+  C. CREATE PHASE DIRECTORIES:
+  For each phase in the new milestone:
+    mkdir -p .sdlc/phases/{phase-number}-{phase-name}
+
+  D. UPDATE ROADMAP.MD:
+  Add the new milestone section:
+  ```markdown
+  ## Milestone {number}: {name}
+  **Goal**: {goal}
+  **Status**: NOT STARTED
+  **Dependencies**: {list or "None"}
+
+  ### Phases
+  | Phase | Name | Status | Plans |
+  |-------|------|--------|-------|
+  | {NN} | {name} | NOT STARTED | 0 |
+  | {NN} | {name} | NOT STARTED | 0 |
+  ```
+
+  E. UPDATE STATE.MD:
+  - If no active milestone: set this as the current milestone
+  - Add history entry: "{timestamp} | milestone | Created milestone {number}: {name} with {N} phases"
+
+  Display:
+  ```
+  Milestone created: {number} — {name}
+
+  Phases:
+  1. {phase-name}
+  2. {phase-name}
+  ...
+
+  Directories created: .sdlc/phases/{phase-dirs}
+
+  NEXT ACTION REQUIRED: /sdlc:spec
+  Start the first phase with /sdlc:spec.
+  ```
+
+  WHY: Milestones provide the big-picture structure. Without them, phases are disconnected chunks of work with no clear endpoint.
+</step>
+
+<step name="complete_milestone" priority="third">
+  ONLY IF operation = COMPLETE.
+
+  A. VERIFY ALL PHASES ARE DONE:
+  Read ROADMAP.md. For the current milestone:
+  - List all phases
+  - Check each phase status: must be COMPLETE
+  - Check each phase directory: must have at least one SUMMARY.md
+
+  IF ANY PHASE IS INCOMPLETE:
+    STOP. Display: "Cannot complete milestone. Phase {N} ({name}) is not complete. Status: {status}."
+    List incomplete phases with their current status.
+
+  B. VERIFY STATE CONSISTENCY:
+  Cross-check:
+  - STATE.md milestone number matches ROADMAP.md current milestone
+  - STATE.md loop_position is CLOSE ✓ or ready for new spec
+  - No active plan is in progress
+
+  IF INCONSISTENCY FOUND:
+    Display: "State inconsistency detected: {details}. Run /sdlc:resume to reconcile."
+
+  C. GENERATE MILESTONE SUMMARY:
+  Read all SUMMARY.md files across all phases in this milestone.
+  Compile a milestone-level summary:
+
+  ```
+  Milestone {number}: {name}
+
+  Completed: {date}
+  Duration: {first spec date} to {last close date}
+  Phases: {count}
+  Plans executed: {total across all phases}
+  Hotfixes: {count, if any}
+
+  Deliverables:
+  - {consolidated list from all summaries}
+
+  Key decisions:
+  - {consolidated from all summaries}
+
+  Technical debt introduced:
+  - {from hotfixes and review warnings}
+  ```
+
+  D. ARCHIVE:
+  The milestone's phase directories remain in place (they are the historical record).
+  No files are moved or deleted.
+
+  E. GIT TAG (if git repository):
+  Ask user: "Create a git tag for this milestone? (recommended)"
+  If yes:
+    git tag -a "milestone-{number}-{name}" -m "Milestone {number}: {name} complete"
+  Display the tag name.
+
+  F. UPDATE ROADMAP.MD:
+  Set milestone status to COMPLETE with completion date.
+
+  G. UPDATE STATE.MD:
+  - Clear current milestone
+  - Add history entry: "{timestamp} | milestone | Completed milestone {number}: {name}. {N} phases, {N} plans."
+
+  H. DETERMINE NEXT MILESTONE:
+  Check ROADMAP.md for the next NOT STARTED milestone.
+
+  IF NEXT MILESTONE EXISTS:
+    Set it as current in STATE.md.
+    Display: "Milestone {number} complete. Next milestone: {next-number} — {next-name}. Run /sdlc:spec to begin."
+
+  IF NO NEXT MILESTONE:
+    Display: "Milestone {number} complete. No further milestones planned. Run /sdlc:milestone create to plan the next one, or the project may be complete."
+
+  WHY: Milestone completion is a significant checkpoint. The git tag marks a stable point. The summary captures institutional knowledge. Without completion, milestones just fade out with no clear ending.
+</step>
+
+</process>

package/src/workflows/pause-work.md

@@ -0,0 +1,153 @@
+<purpose>Save the current session state so work can be resumed later without context loss. Creates a HANDOFF.md that captures everything the next session needs to continue seamlessly.</purpose>
+<when_to_use>Run when ending a work session, switching context, or before a break. Can be run at any point in the loop — the state is preserved exactly as-is.</when_to_use>
+<required_reading>.sdlc/STATE.md</required_reading>
+<loop_context>
+  expected_phase: any (pause works at any loop position)
+  prior_phase: current position is preserved
+  next_phase: RESUME (the next session must run /sdlc:resume)
+</loop_context>
+<process>
+
+<step name="read_current_state" priority="first">
+  Read .sdlc/STATE.md. Capture:
+  - Current milestone, phase, plan
+  - Loop position (e.g., "IMPL ✓", "VERIFY in progress")
+  - Next required action
+  - Last history entry
+
+  WHY: The state machine is the primary context. Without it, the resume workflow does not know where to continue.
+</step>
+
+<step name="gather_session_context" priority="second">
+  Collect all relevant context from the current session:
+
+  A. WORK COMPLETED THIS SESSION:
+     - Read STATE.md history entries from today/this session
+     - Summarize what was done (e.g., "Completed spec for auth module, started implementation")
+
+  B. DECISIONS MADE:
+     - Scan recent SPEC.md, REVIEW.md, or SUMMARY.md files for decisions
+     - List any verbal decisions or trade-offs discussed but not yet written down
+
+  C. IN-PROGRESS WORK:
+     - If mid-implementation: which tasks are done, which are pending?
+     - If mid-verification: which ACs passed, which remain?
+     - If mid-review: which files reviewed, which remain?
+
+  D. BLOCKERS AND OPEN QUESTIONS:
+     - Any unresolved issues?
+     - Any questions that need user input?
+     - Any external dependencies (waiting on API, waiting on design)?
+
+  E. IMPORTANT CONTEXT NOT IN FILES:
+     Ask the user: "Is there anything I should remember for next session that is not already written down? (decisions, context, concerns)"
+     If yes: record their response verbatim.
+
+  WHY: Session context is ephemeral — it lives in conversation history, not in files. The handoff captures it before it is lost.
+</step>
+
+<step name="check_uncommitted_changes" priority="third">
+  Run: git status (if the project is a git repository)
+
+  IF UNCOMMITTED CHANGES EXIST:
+    Display the list of modified/untracked files.
+
+    Ask the user:
+    "You have uncommitted changes:
+    {file list}
+
+    Options:
+    A. Create a WIP commit now (recommended — prevents accidental loss)
+    B. Leave changes uncommitted (they will persist in the working directory)
+    C. Stash changes (saves them without committing)"
+
+    IF user chooses A:
+      Stage relevant files (not .env or secret files)
+      Create commit with message: "wip({phase}): {brief description of current work}"
+      Note the commit hash in the handoff
+
+    IF user chooses B:
+      Note in handoff: "WARNING: uncommitted changes exist. Do not run git clean or git checkout."
+
+    IF user chooses C:
+      Run: git stash push -m "sdlc-pause-{timestamp}"
+      Note the stash reference in the handoff
+
+  IF NO UNCOMMITTED CHANGES:
+    Note: "Working directory clean. No uncommitted changes."
+
+  WHY: Uncommitted changes can be lost (accidental git clean, system crash, someone else working on the branch). A WIP commit is the safest option.
+</step>
+
+<step name="create_handoff" priority="fourth">
+  Create .sdlc/HANDOFF.md (overwrite if exists — only one active handoff at a time):
+
+  ```markdown
+  # Session Handoff
+
+  ## Session Info
+  - **Paused at**: {ISO timestamp}
+  - **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**: {SPEC|IMPL|VERIFY|REVIEW|CLOSE} — {status}
+
+  ## In-Progress Work
+  {What is partially done — specific tasks, files, ACs}
+  - Task X: COMPLETE
+  - Task Y: IN PROGRESS — {what remains}
+  - Task Z: NOT STARTED
+
+  ## Decisions Made
+  {List of decisions with rationale}
+
+  ## Blockers / Open Questions
+  {List of blockers or questions that need resolution}
+
+  ## 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}
+  - **Stash**: {stash reference, if applicable}
+
+  ## Resume Instructions
+  Run /sdlc:resume to continue. The resume workflow will:
+  1. Read this handoff
+  2. Restore context
+  3. Tell you exactly what to do next
+  ```
+
+  WHY: HANDOFF.md is the bridge between sessions. Without it, resuming requires re-reading all files and reconstructing context manually — slow and error-prone.
+</step>
+
+<step name="update_state" priority="fifth">
+  Update .sdlc/STATE.md:
+  - Add session field: paused_at = {timestamp}
+  - Add history entry: "{timestamp} | pause | Session paused at {loop_position}. Handoff created."
+  - Do NOT change loop_position or next_required_action — those are preserved for resume
+
+  Display:
+  ```
+  Session saved.
+
+  Handoff: .sdlc/HANDOFF.md
+  State: {loop_position}
+  Next action (on resume): {next_required_action}
+  Git: {clean | WIP committed | stashed | uncommitted changes}
+
+  When you return, run /sdlc:resume to continue exactly where you left off.
+  ```
+
+  WHY: The explicit "run /sdlc:resume" instruction ensures the next session starts correctly. Without it, the user might try to pick up manually and skip steps.
+</step>
+
+</process>

package/src/workflows/research.md

@@ -0,0 +1,219 @@
+<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>

package/src/workflows/resume-project.md

@@ -0,0 +1,159 @@
+<purpose>Restore a paused session by reading the handoff document, loading context, and directing the user to exactly one next action. Eliminates the cold-start problem when returning to work.</purpose>
+<when_to_use>Run at the start of a new session after /sdlc:pause was used. Also useful when returning to a project after any break, even if /sdlc:pause was not explicitly run.</when_to_use>
+<required_reading>.sdlc/STATE.md, .sdlc/HANDOFF.md (if exists)</required_reading>
+<loop_context>
+  expected_phase: RESUME (transitional — immediately routes to the correct phase)
+  prior_phase: whatever was active when paused
+  next_phase: determined by STATE.md
+</loop_context>
+<process>
+
+<step name="read_state" priority="first">
+  Read .sdlc/STATE.md.
+
+  IF .sdlc/ DOES NOT EXIST:
+    STOP. Display: "No SDLC project found. Run /sdlc:init to initialize."
+
+  IF STATE.md DOES NOT EXIST:
+    STOP. Display: "STATE.md not found. The .sdlc/ directory may be corrupted. Run /sdlc:init to re-initialize."
+
+  Extract:
+  - Current milestone, phase, plan
+  - Loop position
+  - Next required action
+  - Last history entry
+  - paused_at timestamp (if present)
+
+  WHY: STATE.md is the single source of truth. If it is missing, nothing else works.
+</step>
+
+<step name="find_handoff" priority="second">
+  Check for .sdlc/HANDOFF.md.
+
+  IF HANDOFF.md EXISTS:
+    Read it. Extract:
+    - When the session was paused
+    - What was done last session
+    - In-progress work details
+    - Decisions made
+    - Blockers / open questions
+    - User context notes
+    - Git state at pause time
+
+    Calculate time since pause: {now} - {paused_at}
+    Display: "Last session was {N hours/days} ago."
+
+  IF HANDOFF.md DOES NOT EXIST:
+    This is a cold resume without a formal pause.
+    Fall back to STATE.md only.
+    Display: "No handoff found. Resuming from STATE.md."
+
+    Read the most recent files in .sdlc/phases/ to reconstruct context:
+    - Most recent SPEC.md, SUMMARY.md, REVIEW.md, or VERIFY.md
+    - Build a brief context summary from these files
+
+  WHY: HANDOFF.md has rich context. Without it, we can still resume but with less context — the state machine still knows the next action.
+</step>
+
+<step name="restore_context" priority="third">
+  Present the restored context to the user:
+
+  ```
+  === SESSION RESUMED ===
+
+  Project: {from PROJECT.md}
+  Milestone: {number} — {name}
+  Phase: {number} — {name}
+  Plan: {number} — {title, if active}
+
+  Loop position: {position}
+  Last action: {from history}
+
+  {IF HANDOFF EXISTS:}
+  Last session summary:
+  - {what was done}
+  - {what was done}
+
+  In-progress:
+  - {task/AC status}
+
+  Decisions from last session:
+  - {decision}
+
+  Blockers:
+  - {blocker, if any}
+
+  User notes:
+  - {user context, if any}
+  ```
+
+  IF BLOCKERS WERE RECORDED:
+    Ask: "These blockers were noted last session: {blockers}. Are they resolved?"
+    If resolved: note resolution and proceed.
+    If not resolved: "These blockers may affect the next action. Proceed anyway or address them first?"
+
+  WHY: Presenting context upfront saves the user from having to re-read files. The blocker check prevents wasting time on work that is still blocked.
+</step>
+
+<step name="check_git_state" priority="fourth">
+  IF a git repository exists:
+
+  Run: git status
+
+  Compare current git state to the handoff's recorded git state:
+  - Is the branch the same?
+  - Are there new commits since the pause? (someone else may have pushed)
+  - Are there uncommitted changes or stashed changes?
+
+  IF BRANCH CHANGED:
+    Display: "WARNING: You are on branch {current} but the handoff was on branch {paused}. Switch back?"
+
+  IF NEW COMMITS EXIST:
+    Display: "New commits since last session: {count}. These may affect in-progress work."
+    Run: git log --oneline {paused_commit}..HEAD
+    Display the new commits.
+
+  IF STASHED CHANGES:
+    Ask: "Stashed changes from last session exist. Pop the stash to restore them? (yes/no)"
+    If yes: run git stash pop
+
+  WHY: Git state can drift between sessions. Catching mismatches early prevents confusion when code does not behave as expected.
+</step>
+
+<step name="determine_next_action" priority="fifth">
+  Read next_required_action from STATE.md. This is the SINGLE next action.
+
+  MAP the action to a clear instruction:
+
+  /sdlc:spec → "Create the next specification"
+  /sdlc:impl → "Implement the current specification"
+  /sdlc:verify → "Verify acceptance criteria"
+  /sdlc:review → "Review for engineering law compliance"
+  /sdlc:close → "Close the current loop"
+  /sdlc:transition → "Transition to the next phase"
+  /sdlc:milestone → "Complete or create a milestone"
+
+  WHY: Exactly ONE next action. Not two options. Not "you could do X or Y." The state machine has already decided. The user just needs to execute it.
+</step>
+
+<step name="archive_handoff" priority="sixth">
+  IF HANDOFF.md was consumed:
+    Move it to .sdlc/HANDOFF-{timestamp}.md.archived (rename, do not delete)
+    This prevents the next resume from re-reading stale context.
+
+  Update .sdlc/STATE.md:
+  - Remove paused_at field (session is now active)
+  - Add history entry: "{timestamp} | resume | Resumed from {loop_position}. Time since pause: {duration}."
+
+  Display:
+  ```
+  Resumed at: {loop_position}
+
+  NEXT ACTION REQUIRED: {next_required_action}
+  Run {next_required_action} to continue.
+  ```
+
+  WHY: Archiving (not deleting) the handoff preserves the audit trail while preventing stale context from confusing future resumes.
+</step>
+
+</process>