sdlc-framework 1.0.2 → 2.1.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)
@@ -157,13 +168,21 @@ Follows: reproduce → isolate → root-cause → fix → verify.
 - 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 triggers phase transition
+
+### TRANSITION — Advance to next phase
+
+- Verifies all plans in the current phase are complete
+- Cross-checks STATE.md, PROJECT.md, and ROADMAP.md for consistency
+- Updates PROJECT.md with implemented and newly discovered requirements
+- Creates a git commit at the phase boundary
+- Advances state to the first spec of the next phase
 
 ---
 
 ## Commands
 
-15 commands, grouped by purpose. Run `/sdlc:help` for the full reference.
+14 commands, grouped by purpose. Run `/sdlc:help` for the full reference.
 
 ### Core Loop
 
@@ -173,7 +192,8 @@ Follows: reproduce → isolate → root-cause → fix → verify.
 | `/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:close` | Reconcile and close the loop | → `/sdlc:spec` or → `/sdlc:transition` |
+| `/sdlc:transition` | Advance to next phase when all plans complete | → `/sdlc:spec` |
 
 ### Quick Entry
 
@@ -187,23 +207,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 +267,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 +279,7 @@ Severity is configurable per project in `.sdlc/LAWS.md`:
 
 | Aspect | PAUL | SDLC |
 |--------|------|------|
-| Commands | 26 (cognitive overload) | 15 (focused) |
+| Commands | 26 (cognitive overload) | 14 (focused) |
 | Testing | Manual UAT | Automated (Playwright MCP) |
 | Code review | None | Engineering Laws enforcement |
 | Implementation | In-session | Sub-agent parallel waves |
@@ -304,7 +329,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.1.0",
   "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

@@ -19,14 +19,15 @@ 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.
 </objective>
 
 <execution_context>
-@~/.claude/sdlc-framework/workflows/close-loop.md
+@~/.claude/sdlc-framework/workflows/close-phase.md
 @.sdlc/STATE.md
 @.sdlc/ROADMAP.md
 </execution_context>
@@ -44,7 +45,7 @@ Read these files:
 </context>
 
 <process>
-Follow workflow: @~/.claude/sdlc-framework/workflows/close-loop.md
+Follow workflow: @~/.claude/sdlc-framework/workflows/close-phase.md
 
 Step-by-step:
 
@@ -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/debug.md

@@ -21,7 +21,7 @@ Structured debugging that follows a disciplined flow: REPRODUCE, ISOLATE, ROOT-C
 </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:
 

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

@@ -1,6 +1,7 @@
 ---
 name: sdlc:help
 description: "Show SDLC framework command reference"
+argument-hint: "[command]"
 allowed-tools: [Read]
 ---
 
@@ -49,35 +50,39 @@ COMMANDS — Core Loop
   /sdlc:close     Archive the plan. Update STATE.md. Advance to next cycle.
 
 
+COMMANDS — Phase Management
+───────────────────────────
+
+  /sdlc:transition  Advance to the next phase after all plans complete.
+
 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 +139,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/impl.md

@@ -24,7 +24,7 @@ Execute an approved specification by spawning parallel sub-agents for independen
 </objective>
 
 <execution_context>
-@~/.claude/sdlc-framework/workflows/execute-impl.md
+@~/.claude/sdlc-framework/workflows/impl-phase.md
 @.sdlc/STATE.md
 @.sdlc/LAWS.md
 The SPEC.md path is read from STATE.md or provided via $ARGUMENTS.
@@ -40,7 +40,7 @@ Read these files:
 </context>
 
 <process>
-Follow workflow: @~/.claude/sdlc-framework/workflows/execute-impl.md
+Follow workflow: @~/.claude/sdlc-framework/workflows/impl-phase.md
 
 Step-by-step:
 

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/review.md

@@ -25,7 +25,7 @@ Review all code modified during implementation against the Engineering Laws defi
 </objective>
 
 <execution_context>
-@~/.claude/sdlc-framework/workflows/run-review.md
+@~/.claude/sdlc-framework/workflows/review-phase.md
 @.sdlc/STATE.md
 @.sdlc/LAWS.md
 The SPEC.md and IMPL.md paths are read from STATE.md.
@@ -45,7 +45,7 @@ Use `git diff` to identify changed files if IMPL.md is unavailable.
 </context>
 
 <process>
-Follow workflow: @~/.claude/sdlc-framework/workflows/run-review.md
+Follow workflow: @~/.claude/sdlc-framework/workflows/review-phase.md
 
 Step-by-step:
 

package/src/commands/spec.md

@@ -26,7 +26,7 @@ Define a complete specification for one unit of work (a "plan"). Produce a SPEC.
 </objective>
 
 <execution_context>
-@~/.claude/sdlc-framework/workflows/create-spec.md
+@~/.claude/sdlc-framework/workflows/spec-phase.md
 @.sdlc/STATE.md
 @.sdlc/PROJECT.md
 @.sdlc/ROADMAP.md
@@ -46,7 +46,7 @@ Scan the codebase to understand existing structure, patterns, and conventions.
 </context>
 
 <process>
-Follow workflow: @~/.claude/sdlc-framework/workflows/create-spec.md
+Follow workflow: @~/.claude/sdlc-framework/workflows/spec-phase.md
 
 Step-by-step: