sdlc-framework 2.0.0 → 2.1.1

package/README.md

@@ -168,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
 
-13 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
 
@@ -184,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
 
@@ -270,7 +279,7 @@ Severity is configurable per project in `.sdlc/LAWS.md`:
 
 | Aspect | PAUL | SDLC |
 |--------|------|------|
-| Commands | 26 (cognitive overload) | 13 (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 |

package/package.json

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

package/src/commands/close.md

@@ -27,7 +27,7 @@ Close the current SDLC loop by reconciling what was planned (SPEC.md) against wh
 </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>
@@ -45,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:
 

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

@@ -1,6 +1,7 @@
 ---
 name: sdlc:help
 description: "Show SDLC framework command reference"
+argument-hint: "[command]"
 allowed-tools: [Read]
 ---
 
@@ -49,6 +50,11 @@ 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
 ──────────────────────
 
@@ -133,7 +139,7 @@ If .sdlc/LAWS.md exists, read it and append any project-specific law customizati
 
 <success_criteria>
 - [ ] Core loop diagram displayed
-- [ ] All 13 commands listed with one-line descriptions
+- [ ] All 14 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/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:
 

package/src/commands/transition.md

@@ -0,0 +1,99 @@
+---
+name: sdlc:transition
+description: Transition to the next phase after all plans in a phase complete
+argument-hint: "[phase-name]"
+allowed-tools: [Read, Write, Bash, Glob, Grep, Edit, AskUserQuestion]
+---
+
+<objective>
+Transition from the current phase to the next phase within a milestone. Verify phase completeness, update project state, commit the phase, and advance to the next phase.
+
+**When to use:** After /sdlc:close detects the last plan in a phase is done. Can also be run manually to force a phase transition.
+
+**What it does:**
+1. Verify all plans in the current phase are complete (every SPEC has a SUMMARY, all ACs passed).
+2. Cross-check STATE.md, PROJECT.md, and ROADMAP.md for consistency.
+3. Update PROJECT.md with implemented, superseded, and newly discovered requirements.
+4. Advance state to the next phase (or trigger milestone completion if this was the last phase).
+5. Update ROADMAP.md with phase completion details.
+6. Create a git commit marking the phase boundary.
+
+**What happens next:**
+- Next phase exists: Framework directs you to /sdlc:spec for the first plan of the new phase.
+- Last phase in milestone: Framework directs you to /sdlc:close for milestone finalization.
+
+**Critical rule:** No phase transitions without completeness verification. Every plan must have a summary. Every AC must pass. State inconsistencies are surfaced and resolved before advancing.
+</objective>
+
+<execution_context>
+@~/.claude/sdlc-framework/workflows/transition-phase.md
+@.sdlc/STATE.md
+@.sdlc/ROADMAP.md
+@.sdlc/PROJECT.md
+</execution_context>
+
+<context>
+$ARGUMENTS — optional phase name to transition from. If not provided, read from .sdlc/STATE.md current_phase field.
+
+Read these files:
+- .sdlc/STATE.md — current phase, milestone, loop position.
+- .sdlc/ROADMAP.md — phase list, plan counts, next phase identification.
+- .sdlc/PROJECT.md — requirements to update based on completed work.
+- All SUMMARY.md files in the completing phase's directory.
+</context>
+
+<process>
+Follow workflow: @~/.claude/sdlc-framework/workflows/transition-phase.md
+
+Step-by-step:
+
+1. **Verify phase completeness**
+   - Read .sdlc/STATE.md. Confirm loop_position is CLOSE ✓. If not, warn: "Loop not closed. Run /sdlc:close first."
+   - List all SPEC and SUMMARY files in .sdlc/phases/{current_phase}/.
+   - Every SPEC must have a corresponding SUMMARY. If not, block: "Phase transition blocked. Plan {N} has a spec but no summary."
+   - Every SUMMARY must show all ACs passed. If not, block: "Phase transition blocked. Plan {N} has failing ACs."
+
+2. **Verify state consistency**
+   - Cross-check STATE.md, PROJECT.md, and ROADMAP.md:
+     - STATE.md current_milestone matches ROADMAP.md in-progress milestone.
+     - STATE.md current_phase matches the phase being completed.
+     - Prior phases in this milestone are all COMPLETE.
+   - If inconsistency found: display details, offer to auto-fix, ask for confirmation.
+
+3. **Update PROJECT.md**
+   - Read all SUMMARY.md files from the completing phase.
+   - Mark addressed requirements as IMPLEMENTED.
+   - Mark contradicted requirements as SUPERSEDED.
+   - Add newly discovered requirements as NOT STARTED.
+   - Display proposed changes and ask user to confirm before writing.
+
+4. **Advance state to next phase**
+   - Read ROADMAP.md to identify the next phase.
+   - If next phase exists:
+     - Update STATE.md: current_phase, clear current_plan, set loop_position: TRANSITION ✓, set next_required_action: /sdlc:spec.
+     - Update ROADMAP.md: mark completed phase as COMPLETE, set next phase to IN PROGRESS.
+   - If no next phase (last phase in milestone):
+     - Update STATE.md: set next_required_action: /sdlc:close (milestone completion).
+
+5. **Update ROADMAP.md with phase summary**
+   - Add completion date, plan count, hotfix count, key deliverables, and duration.
+
+6. **Create git commit** (if in a git repository)
+   - Stage .sdlc/ files and source files from the phase.
+   - Commit with message: "feat({phase-name}): complete phase {number}"
+
+7. **Output next action**
+   - If next phase exists: end with NEXT ACTION REQUIRED: /sdlc:spec
+   - If milestone complete: end with NEXT ACTION REQUIRED: /sdlc:close
+</process>
+
+<success_criteria>
+- [ ] Phase completeness verified: every SPEC has a SUMMARY, all ACs passed
+- [ ] State consistency checked across STATE.md, PROJECT.md, ROADMAP.md
+- [ ] PROJECT.md updated with implemented, superseded, and new requirements
+- [ ] STATE.md advanced to next phase (or milestone completion)
+- [ ] ROADMAP.md updated with phase completion details and summary
+- [ ] Git commit created at phase boundary (if in a git repo)
+- [ ] If next phase exists: output ends with NEXT ACTION REQUIRED: /sdlc:spec
+- [ ] If milestone complete: output ends with NEXT ACTION REQUIRED: /sdlc:close
+</success_criteria>

package/src/commands/verify.md

@@ -25,7 +25,7 @@ Verify the implementation against every acceptance criterion in the SPEC.md. Use
 </objective>
 
 <execution_context>
-@~/.claude/sdlc-framework/workflows/run-verify.md
+@~/.claude/sdlc-framework/workflows/verify-phase.md
 @.sdlc/STATE.md
 The SPEC.md path is read from STATE.md or provided via $ARGUMENTS.
 </execution_context>
@@ -40,7 +40,7 @@ Read these files:
 </context>
 
 <process>
-Follow workflow: @~/.claude/sdlc-framework/workflows/run-verify.md
+Follow workflow: @~/.claude/sdlc-framework/workflows/verify-phase.md
 
 Step-by-step: