sdlc-framework 1.0.0 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdlc-framework",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Structured Development Lifecycle - A closed-loop AI-assisted development framework for Claude Code",
   "bin": {
     "sdlc-framework": "bin/install.js"

package/src/commands/impl.md

@@ -20,7 +20,7 @@ Execute an approved specification by spawning parallel sub-agents for independen
 
 **What happens next:** Framework directs you to /sdlc:verify to validate the implementation against acceptance criteria.
 
-**Critical rule:** Sub-agents do the work. This command orchestrates. Each sub-agent operates within strict boundaries defined by the spec.
+**CRITICAL MANDATORY RULE:** You MUST use the Agent tool to spawn sub-agents for EVERY task. DO NOT implement tasks yourself in the main session. DO NOT skip agent spawning. DO NOT write code directly. This command ORCHESTRATES — the Agent tool EXECUTES. Each sub-agent gets its task, files, laws, and boundaries. All agents in the same wave are spawned in ONE message with run_in_background: true. Use TaskCreate to track every task. This is NON-NEGOTIABLE.
 </objective>
 
 <execution_context>
@@ -80,12 +80,13 @@ Step-by-step:
    - Report what you created, modified, and tested.
    ```
 
-4. **Execute wave 1 (independent tasks)**
+4. **Execute wave 1 (independent tasks) — MUST USE Agent TOOL**
    - Identify all tasks with no dependencies (wave 1).
-   - Spawn one Agent per task with `run_in_background: true`.
-   - Spawn ALL wave 1 agents in a single message.
-   - Update each task status to "in_progress" via TaskUpdate.
-   - Wait for all wave 1 agents to complete.
+   - Call TaskCreate for each task (ALL in one message).
+   - Call the Agent tool for EACH task with run_in_background: true.
+   - ALL Agent calls for this wave MUST be in a SINGLE message (parallel spawn).
+   - DO NOT write any implementation code yourself — agents do ALL the work.
+   - Wait for all wave 1 agents to complete (you will be notified).
 
 5. **Process wave results**
    - When a wave completes, review each agent's output:

package/src/commands/spec.md

@@ -123,16 +123,19 @@ Step-by-step:
    ## Engineering Constraints (from LAWS.md)
    ```
 
-9. **Spec integrity review**
-   - CHECK completeness: all tasks have required fields, all ACs have Given/When/Then
-   - CHECK consistency: every task links to an AC, no boundary violations, no cycles in DAG
-   - CHECK feasibility: task count 2-5, estimated change under ~300 lines
-   - Fix any issues found before presenting for approval
+9. **Spec integrity review — MANDATORY, DO NOT SKIP**
+   You MUST print a full integrity review table with ✓/✗ for EACH check:
+   - CHECK 1 — COMPLETENESS: every task has name, action, files, verification, done criteria, complexity. Every AC has numbered GIVEN/WHEN/THEN with specific values.
+   - CHECK 2 — CONSISTENCY: no orphan tasks (every task → AC), no orphan ACs (every AC → task), no boundary violations, no DAG cycles, no shared-file parallel writes.
+   - CHECK 3 — CONTRADICTIONS: no conflicting ACs for same input, no conflicting task actions on same function, no task contradicting boundary, no AC contradicting PROJECT.md constraints.
+   - CHECK 4 — FEASIBILITY: task count 2-5, estimated change under ~300 lines, all referenced files exist.
+   - CHECK 5 — DEPENDENCY GRAPH: every task in exactly one wave, ordering matches dependencies, independent tasks parallelized, dependent tasks sequenced.
+   - Print the full review table with all results. Fix any failures before proceeding.
 
 10. **User approval gate** (BLOCKING — cannot proceed without approval)
-    - Present full spec summary to user
+    - Present full spec summary AND integrity review results to user
     - User options: APPROVE (proceed), REVISE (change and re-review), REJECT (discard)
-    - If REVISE: apply changes, re-run integrity review, re-present
+    - If REVISE: apply changes, re-run ALL integrity checks, re-present
     - If REJECT: delete spec, stop
     - If APPROVE: proceed to update state
 

package/src/workflows/close-phase.md

@@ -6,6 +6,14 @@
   prior_phase: REVIEW ✓
   next_phase: SPEC (next loop) or transition-phase (if last plan)
 </loop_context>
+<display_rule>
+  MANDATORY: Display the loop closure summary in the chat window. Show:
+  - What was built (deliverables, 2-3 lines)
+  - AC results table (AC | Status)
+  - Deviations (if any, 1 line each)
+  - Next action
+  Keep it compact (~15-25 lines). Full SUMMARY.md is in the file for audit.
+</display_rule>
 <process>
 
 <step name="validate_state" priority="first">

package/src/workflows/impl-phase.md

@@ -1,4 +1,21 @@
-<purpose>Execute the specification through sub-agent driven parallel implementation. Each task from the spec becomes an independent agent with full context, engineering laws, and boundaries. Tasks run in dependency-ordered waves.</purpose>
+<purpose>Execute the specification through sub-agent driven parallel implementation. Each task from the spec becomes an independent agent with full context, engineering laws, and boundaries. Tasks run in dependency-ordered waves.
+
+╔══════════════════════════════════════════════════════════════════════╗
+║  MANDATORY: You MUST use the Agent tool to spawn sub-agents.        ║
+║  You MUST NOT implement tasks yourself in the main session.         ║
+║  Every task in the spec MUST be executed by a spawned Agent.        ║
+║  Use run_in_background: true for parallel wave execution.           ║
+║  Use TaskCreate/TaskUpdate to track each task's progress.           ║
+║  This is NON-NEGOTIABLE. Implementing inline violates the SDLC.    ║
+╚══════════════════════════════════════════════════════════════════════╝
+</purpose>
+<display_rule>
+  MANDATORY: Display ALL progress in the chat window. The developer monitors via chat, not files.
+  - Before spawning agents: display the full todo list with all tasks and their wave assignments.
+  - After each wave: display updated progress with ✅/🔄/⬚ status per task.
+  - After all waves: display final summary with files modified per task.
+  Keep displays compact (~15-30 lines). The developer sees progress without opening any files.
+</display_rule>
 <when_to_use>Run after /sdlc:spec completes. STATE.md must show loop_position = SPEC ✓ and next_required_action = /sdlc:impl.</when_to_use>
 <required_reading>.sdlc/STATE.md, the current SPEC.md, .sdlc/LAWS.md, .sdlc/PROJECT.md</required_reading>
 <loop_context>
@@ -93,10 +110,35 @@
 </step>
 
 <step name="execute_wave" priority="fifth">
+  ╔══════════════════════════════════════════════════════════════════════╗
+  ║  YOU MUST CALL THE Agent TOOL HERE. THIS IS NOT OPTIONAL.           ║
+  ║  DO NOT write code yourself. DO NOT skip agent spawning.            ║
+  ║  Every task = one Agent tool call with run_in_background: true.     ║
+  ║  All agents in the same wave MUST be spawned in ONE message.        ║
+  ╚══════════════════════════════════════════════════════════════════════╝
+
   FOR EACH WAVE (starting with Wave 1):
 
-  A. SPAWN AGENTS FOR ALL TASKS IN THIS WAVE:
-     For each task in the wave, spawn an agent with run_in_background: true.
+  A. CREATE TRACKABLE TODO LIST:
+     ╔══════════════════════════════════════════════════════════════════╗
+     ║  YOU MUST call TaskCreate for EVERY task. This creates a        ║
+     ║  visible, trackable todo list in the chat. The developer        ║
+     ║  monitors progress through this list. DO NOT SKIP.              ║
+     ╚══════════════════════════════════════════════════════════════════╝
+     For EACH task in the spec (ALL tasks, not just this wave):
+     - Call TaskCreate with: description = "Task {N}: {task-name} — {short action}"
+     This creates the full todo list upfront. The developer sees ALL tasks at once.
+
+     Then for each task in THIS WAVE, call TaskUpdate to set status = "in_progress".
+
+  B. SPAWN AGENTS FOR ALL TASKS IN THIS WAVE:
+     For each task in the wave, call the Agent tool with:
+     - description: "Implement: {task-name}" (short)
+     - run_in_background: true
+     - prompt: the full agent instruction below
+
+     CRITICAL: Spawn ALL agents for a wave in ONE single message.
+     Example for a 3-task wave — your message contains 3 Agent tool calls.
 
      Each agent instruction MUST include ALL of the following (no shortcuts):
 
@@ -138,14 +180,29 @@
   B. WAIT FOR ALL AGENTS IN THIS WAVE TO COMPLETE.
      Do NOT proceed to the next wave until every agent in the current wave has returned.
 
-  C. REVIEW WAVE RESULTS:
+  C. REVIEW WAVE RESULTS AND UPDATE TODO LIST:
      For each agent result:
      - Did it complete successfully?
      - Did it list modified files?
      - Did it report any issues or blockers?
 
+     For EACH completed task, call TaskUpdate to set status = "completed".
+     For EACH failed task, call TaskUpdate to set status = "failed".
+
+     DISPLAY the todo list progress in chat after EVERY wave:
+     ```
+     ── Implementation Progress ──────────────
+     ✅ Task 1: {name} — DONE ({N} files)
+     ✅ Task 2: {name} — DONE ({N} files)
+     🔄 Task 3: {name} — IN PROGRESS (wave 2)
+     ⬚ Task 4: {name} — PENDING (wave 3)
+     ──────────────────────────────────────────
+     Wave {N}/{total} complete. {N}/{total} tasks done.
+     ```
+
      IF ANY AGENT FAILED:
-       - Display: "Agent for task '{task-name}' failed: {error}"
+       - Call TaskUpdate to set failed task status = "failed"
+       - Display: "❌ Agent for task '{task-name}' failed: {error}"
        - Display the failure details
        - STOP. Do NOT proceed to next wave.
        - Ask user: "How do you want to proceed? Options:

package/src/workflows/review-phase.md

@@ -6,6 +6,12 @@
   prior_phase: VERIFY ✓
   next_phase: CLOSE
 </loop_context>
+<display_rule>
+  MANDATORY: Display the review findings in the chat window. The developer reads findings
+  in chat, not by opening REVIEW.md. Show: per-file findings table (file, line, law, severity,
+  description), blocker count, warning count, and the verdict (PASS/FAIL).
+  Keep it compact (~20-40 lines). Full details are in REVIEW.md for reference.
+</display_rule>
 <process>
 
 <step name="validate_state" priority="first">

package/src/workflows/spec-phase.md

@@ -6,6 +6,18 @@
   prior_phase: CLOSE (or INIT for first spec)
   next_phase: IMPL
 </loop_context>
+<display_rule>
+  MANDATORY: After writing ANY artifact (SPEC.md, REVIEW.md, SUMMARY.md), you MUST
+  display a COMPACT summary of the artifact in the chat window. The developer does NOT
+  have time to open files and read them. They monitor progress in the chat.
+
+  COMPACT means: key sections with content, NOT just section headers.
+  Show: objective (2 lines), tasks (numbered list with files), ACs (numbered Given/When/Then),
+  dependency graph (wave diagram), boundaries (list).
+
+  DO NOT dump the entire file verbatim — that bloats context. Show the substance in ~30-50 lines.
+  The full artifact is in the file for reference; the chat shows the actionable summary.
+</display_rule>
 <process>
 
 <step name="validate_state" priority="first">
@@ -256,41 +268,91 @@
 </step>
 
 <step name="spec_integrity_review" priority="eighth">
-  BEFORE updating state, perform a self-review of the spec for completeness and correctness.
+  ╔══════════════════════════════════════════════════════════════════════╗
+  ║  THIS STEP IS MANDATORY. DO NOT SKIP. DO NOT ABBREVIATE.           ║
+  ║  You MUST print the full integrity review table before proceeding.  ║
+  ╚══════════════════════════════════════════════════════════════════════╝
+
+  Re-read the SPEC.md file you just wrote. Perform ALL FIVE checks below.
+  For EACH check item, print ✓ (pass) or ✗ (fail) with explanation.
 
   CHECK 1 — COMPLETENESS:
-  - Every task has: name, action, files, verification, done criteria, complexity ✓ or ✗
-  - Every AC has: GIVEN, WHEN, THEN with specific values (not vague) ✓ or ✗
-  - Dependency graph accounts for all tasks ✓ or ✗
-  - Boundaries section is non-empty ✓ or ✗
-  - Required patterns section references actual existing files ✓ or ✗
+  For each task, verify it has ALL of these fields (print each):
+  - [ ] name (descriptive, kebab-case)
+  - [ ] action (imperative, specific — not vague like "implement the feature")
+  - [ ] files to modify (specific file paths, not "relevant files")
+  - [ ] verification (how to confirm — a command, a test, an observable outcome)
+  - [ ] done criteria (links to AC-N)
+  - [ ] complexity (LOW/MEDIUM/HIGH)
+  For each AC, verify it has ALL of these (print each):
+  - [ ] AC number (AC-1, AC-2, etc.)
+  - [ ] GIVEN with specific precondition (not "given the system is running")
+  - [ ] WHEN with specific action (not "when the user does something")
+  - [ ] THEN with specific observable outcome (not "then it works correctly")
 
   CHECK 2 — CONSISTENCY:
-  - Every task links to at least one AC (no orphan tasks)
-  - Every AC is covered by at least one task (no orphan ACs)
-  - File lists in tasks do not overlap with boundaries (no protected file modification)
-  - Task dependency graph has no cycles
-  - Parallel groups contain only truly independent tasks (no shared file writes)
-
-  CHECK 3 — FEASIBILITY:
-  - No single task exceeds HIGH complexity (60+ lines) — if so, suggest splitting
-  - Total task count is 2-5 per spec — if more, suggest splitting into multiple plans
-  - Estimated total change stays under ~300 lines — if more, warn user
-
-  IF ANY CHECK FAILS: Fix the spec before presenting for approval. Do not present a broken spec.
-
-  Present the integrity review results:
+  - [ ] Every task references at least one AC in its done criteria (no orphan tasks)
+  - [ ] Every AC is satisfied by at least one task (no orphan ACs)
+  - [ ] No task modifies a file listed in Boundaries/DO NOT CHANGE
+  - [ ] Dependency graph has no cycles (A→B→A)
+  - [ ] Tasks in the same parallel group do NOT write to the same file
+
+  CHECK 3 — CONTRADICTION DETECTION:
+  Compare every AC pair and every task pair for contradictions:
+  - [ ] No two ACs define conflicting behavior for the same input/state
+      Example contradiction: AC-1 says "return 404" but AC-3 says "return empty array" for missing resource
+  - [ ] No two tasks modify the same function/method with conflicting changes
+      Example contradiction: Task-1 adds validation to createUser, Task-2 removes validation from createUser
+  - [ ] No task action contradicts a boundary
+      Example contradiction: Boundary says "do not change auth logic" but Task-3 says "update auth middleware"
+  - [ ] No AC contradicts project constraints from PROJECT.md
+      Example contradiction: PROJECT.md says "REST API only" but AC-2 tests a GraphQL endpoint
+  - [ ] The acceptance criteria as a whole describe a coherent feature (not fragments that don't connect)
+
+  CHECK 4 — FEASIBILITY:
+  - [ ] No single task exceeds HIGH complexity (60+ lines) — if so, split it
+  - [ ] Total task count is 2-5 — if more, split into multiple plans
+  - [ ] Estimated total change under ~300 lines — if more, warn user
+  - [ ] All referenced files in tasks actually exist (or are marked as "create")
+
+  CHECK 5 — DEPENDENCY GRAPH VALIDITY:
+  - [ ] Every task appears in exactly one parallel group
+  - [ ] Wave ordering matches dependencies (no task in Wave 1 that depends on another task)
+  - [ ] Independent tasks (no shared files, no shared types) are correctly parallelized
+  - [ ] Dependent tasks (shared files, shared types/interfaces) are correctly sequenced
+
+  IF ANY CHECK ITEM FAILS:
+  1. List all failures with specific descriptions
+  2. Propose a fix for each failure
+  3. Apply all fixes to the SPEC.md
+  4. Re-run ALL five checks on the updated spec
+  5. Repeat until all checks pass
+
+  PRINT the full integrity review report:
   ```
-  Spec Integrity Review:
-  ✓ Completeness: All {N} tasks fully defined, {N} ACs with Given/When/Then
-  ✓ Consistency: All tasks linked to ACs, no boundary violations, no cycles
-  ✓ Feasibility: {N} tasks across {N} waves, estimated ~{N} lines of change
-
-  Issues found: {count}
-  {list any issues with suggested fixes}
+  ══════════════════════════════════════════════
+  SPEC INTEGRITY REVIEW
+  ══════════════════════════════════════════════
+  Completeness:      {✓ or ✗} — {details}
+  Consistency:       {✓ or ✗} — {details}
+  Contradictions:    {✓ or ✗} — {details or "none found"}
+  Feasibility:       {✓ or ✗} — {details}
+  Dependency Graph:  {✓ or ✗} — {details}
+
+  Tasks: {N} fully defined
+  ACs: {N} with specific Given/When/Then
+  Waves: {N} parallel execution groups
+  Estimated scope: ~{N} lines across {N} files
+
+  Contradictions found: {N}
+  {if any: list each contradiction and how it was resolved}
+
+  Issues found and fixed: {N}
+  {if any: list each issue and the fix applied}
+  ══════════════════════════════════════════════
   ```
 
-  WHY: A broken spec cascades failures through every downstream step. Catching spec issues here is 10x cheaper than catching them in review. This is the cheapest point to fix problems.
+  WHY: A spec with contradictions produces agents that build conflicting code. A spec with orphan ACs means untested features. A spec with invalid dependencies means agents wait forever or overwrite each other. This review catches all of these. It costs 30 seconds now and saves hours of debugging later.
 </step>
 
 <step name="user_approval_gate" priority="ninth">

package/src/workflows/verify-phase.md

@@ -6,6 +6,13 @@
   prior_phase: IMPL ✓
   next_phase: REVIEW
 </loop_context>
+<display_rule>
+  MANDATORY: Display verification results in the chat window as a table. The developer
+  monitors pass/fail per AC in chat, not by opening files. Show:
+  | AC | Description | Type | Status | Evidence (1 line) |
+  Keep it compact. If Playwright screenshots were taken, mention the screenshot but
+  do not embed images — just note "screenshot captured."
+</display_rule>
 <process>
 
 <step name="validate_state" priority="first">
@@ -116,7 +123,18 @@
      - Include console errors in the evidence
      - Continue to next AC (do not stop on first failure)
 
-  WHY: Playwright MCP replaces manual UAT. Every UI acceptance criterion gets tested programmatically with screenshot evidence, making verification reproducible and auditable.
+  ╔══════════════════════════════════════════════════════════════════════╗
+  ║  YOU MUST USE THE PLAYWRIGHT MCP TOOLS FOR UI VERIFICATION.         ║
+  ║  DO NOT ask the user to manually test UI. DO NOT skip UI ACs.       ║
+  ║  Call: mcp__plugin_playwright_playwright__browser_navigate           ║
+  ║  Call: mcp__plugin_playwright_playwright__browser_snapshot           ║
+  ║  Call: mcp__plugin_playwright_playwright__browser_click              ║
+  ║  Call: mcp__plugin_playwright_playwright__browser_fill_form          ║
+  ║  Call: mcp__plugin_playwright_playwright__browser_take_screenshot    ║
+  ║  These are the ACTUAL tool names you must invoke.                   ║
+  ╚══════════════════════════════════════════════════════════════════════╝
+
+  WHY: Playwright MCP replaces manual UAT. Every UI acceptance criterion gets tested programmatically with screenshot evidence, making verification reproducible and auditable. NEVER fall back to "please test this manually."
 </step>
 
 <step name="verify_api_endpoints" priority="fifth">