sdlc-framework 1.0.0

package/src/commands/spec.md

@@ -0,0 +1,164 @@
+---
+name: sdlc:spec
+description: Define specification with acceptance criteria and task dependencies
+argument-hint: "[phase-plan]"
+allowed-tools: [Read, Write, Glob, Grep, AskUserQuestion]
+---
+
+<objective>
+Define a complete specification for one unit of work (a "plan"). Produce a SPEC.md file containing objective, acceptance criteria, task breakdown, dependency graph, and boundaries.
+
+**When to use:** After /sdlc:init or after /sdlc:close completes a previous plan. This is the PLANNING phase of the SDLC loop.
+
+**What it does:**
+1. Read current state from .sdlc/STATE.md, PROJECT.md, and ROADMAP.md.
+2. Ask clarification questions about what to build — never guess, never assume.
+3. Present architectural recommendations with concrete trade-offs.
+4. Define acceptance criteria in BDD format (Given/When/Then).
+5. Break work into tasks with dependency analysis for parallel execution.
+6. Write SPEC.md with everything an implementer needs.
+7. Run spec integrity review (completeness, consistency, feasibility checks).
+8. Present spec for user APPROVAL — implementation does not start until approved.
+
+**What happens next:** After user approves the spec, framework directs you to /sdlc:impl.
+
+**Critical rule:** This command asks questions. It does NOT write code. It does NOT make assumptions. Every ambiguity triggers a clarification question.
+</objective>
+
+<execution_context>
+@~/.claude/sdlc-framework/workflows/create-spec.md
+@.sdlc/STATE.md
+@.sdlc/PROJECT.md
+@.sdlc/ROADMAP.md
+@.sdlc/LAWS.md
+</execution_context>
+
+<context>
+$ARGUMENTS — optional phase-plan identifier (e.g., "phase-1/plan-2" or a description of work).
+
+Read these files to understand current state:
+- .sdlc/STATE.md — current loop position, active phase, previous plans.
+- .sdlc/PROJECT.md — project context, tech stack, quality priorities.
+- .sdlc/ROADMAP.md — milestones, phases, and planned work.
+- .sdlc/LAWS.md — engineering laws that constrain implementation.
+
+Scan the codebase to understand existing structure, patterns, and conventions.
+</context>
+
+<process>
+Follow workflow: @~/.claude/sdlc-framework/workflows/create-spec.md
+
+Step-by-step:
+
+1. **Load state**
+   - Read .sdlc/STATE.md. Confirm loop_position is SPEC. If not, warn the user: "Loop position is <position>, not SPEC. Run /sdlc:close first or confirm you want to override."
+   - Read .sdlc/PROJECT.md for project context.
+   - Read .sdlc/ROADMAP.md to identify the current phase and next planned work.
+
+2. **Understand the request**
+   - If $ARGUMENTS provided, use it as the starting point.
+   - If no arguments, ask: "What do you want to build or change? Describe the feature, fix, or refactor."
+
+3. **Ask clarification questions** (use AskUserQuestion for each)
+   Do NOT proceed until ambiguities are resolved. Common questions:
+   - "Who is the user/actor for this feature?"
+   - "What is the expected input and output?"
+   - "Are there edge cases you already know about?"
+   - "Does this interact with existing features? Which ones?"
+   - "What should happen when <error condition>?"
+   - "Is there a performance requirement?"
+   - "Is there a UI/UX design, or should I propose one?"
+
+   Ask at minimum 2 clarification questions. Ask more if the scope is ambiguous.
+
+4. **Present recommendations with trade-offs**
+   For each significant design decision, present 2-3 options:
+   - Option A (recommended): description, effort, risk, maintenance burden.
+   - Option B: description, effort, risk, maintenance burden.
+   - Option C (do nothing / defer): description, risk of deferring.
+   Ask the user to choose before proceeding.
+
+5. **Define acceptance criteria in BDD format**
+   Write Given/When/Then scenarios for each user-facing behavior:
+   ```
+   AC-1: [Short title]
+   Given [precondition]
+   When [action]
+   Then [expected outcome]
+   ```
+   Include happy path, error cases, and edge cases.
+   Present acceptance criteria to the user and ask: "Do these cover all cases? Anything to add or change?"
+
+6. **Break into tasks with dependency analysis**
+   - List every discrete task needed to implement the spec.
+   - For each task, identify:
+     - Files to create or modify.
+     - Dependencies on other tasks (which tasks must complete first).
+     - Estimated complexity (low/medium/high).
+   - Build a dependency graph:
+     - Independent tasks (no dependencies) can run in parallel.
+     - Dependent tasks are ordered sequentially.
+     - Group tasks into execution waves (wave 1 = all independent, wave 2 = depends on wave 1, etc.).
+
+7. **Define boundaries**
+   Explicitly state:
+   - What is IN scope.
+   - What is OUT of scope.
+   - What is DEFERRED to a future plan.
+
+8. **Write SPEC.md**
+   Create .sdlc/specs/SPEC-<plan-id>.md with:
+   ```
+   # Spec: <title>
+   ## Objective
+   ## Acceptance Criteria
+   ## Tasks
+   ### Task Dependency Graph
+   ### Execution Waves
+   ## Boundaries
+   ### In Scope
+   ### Out of Scope
+   ### Deferred
+   ## Files to Modify
+   ## 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
+
+10. **User approval gate** (BLOCKING — cannot proceed without approval)
+    - Present full spec summary to user
+    - User options: APPROVE (proceed), REVISE (change and re-review), REJECT (discard)
+    - If REVISE: apply changes, re-run integrity review, re-present
+    - If REJECT: delete spec, stop
+    - If APPROVE: proceed to update state
+
+11. **Update STATE.md**
+    - Set `current_plan: <plan-id>`
+    - Set `spec_path: .sdlc/phases/{phase}/{plan}-SPEC.md`
+    - Set `loop_position: SPEC ✓`
+    - Set `next_required_action: /sdlc:impl`
+
+12. **Output confirmation**
+    - Print spec summary: objective, number of ACs, number of tasks, execution waves.
+    - End with NEXT ACTION REQUIRED: /sdlc:impl
+</process>
+
+<success_criteria>
+- [ ] At least 2 clarification questions asked before writing the spec
+- [ ] Every design decision presented with trade-offs and user confirmation
+- [ ] Acceptance criteria written in BDD format (Given/When/Then)
+- [ ] Acceptance criteria cover happy path, error cases, and edge cases
+- [ ] Tasks broken into dependency graph with execution waves
+- [ ] Each task identifies files to create/modify and complexity
+- [ ] Boundaries section explicitly states in-scope, out-of-scope, and deferred items
+- [ ] Spec integrity review passed (completeness, consistency, feasibility)
+- [ ] User explicitly approved the spec (APPROVE response received)
+- [ ] SPEC.md created at .sdlc/phases/{phase}/{plan}-SPEC.md
+- [ ] STATE.md updated with current_plan, spec_path, loop_position: SPEC ✓
+- [ ] No assumptions made — every ambiguity resolved via clarification
+- [ ] Output ends with NEXT ACTION REQUIRED: /sdlc:impl
+</success_criteria>

package/src/commands/status.md

@@ -0,0 +1,118 @@
+---
+name: sdlc:status
+description: "Show loop position and forced next action"
+allowed-tools: [Read, Glob, Grep]
+---
+
+<objective>
+Show exactly where you are in the SDLC loop and what you must do next. Visual progress, current state, and forced next action. Designed for junior developers who need clear guidance.
+
+**When to use:** You are lost. You do not know what to do next. You want to see progress. Run this anytime.
+
+**What it does:**
+1. Read STATE.md for current position.
+2. Display milestone, phase, plan, and loop position with a visual diagram.
+3. Show progress bar and any blockers.
+4. Force exactly ONE next action with an explanation of what it does and why.
+
+**What happens next:** The forced next action. No choices.
+</objective>
+
+<execution_context>
+@.sdlc/STATE.md
+@.sdlc/ROADMAP.md
+</execution_context>
+
+<context>
+No arguments required.
+
+Read .sdlc/STATE.md for current loop position, milestone, phase, plan.
+Read .sdlc/ROADMAP.md for milestone completion data.
+</context>
+
+<process>
+Step-by-step:
+
+1. **Read state**
+   - Read .sdlc/STATE.md. If it does not exist, output: "Framework not initialized. Run /sdlc:init first." Then stop.
+   - Extract: loop_position, current_milestone, current_phase, current_plan, blockers, deferred_issues.
+   - Read .sdlc/ROADMAP.md for milestone progress data.
+
+2. **Display loop position (visual)**
+   - Show the core loop with the 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 or HOTFIX, show those as side branches:
+
+   ```
+     SPEC ──→ IMPLEMENT ──→ VERIFY ──→ REVIEW ──→ CLOSE
+                  │
+                  ├──→ [DEBUG] ◄── YOU ARE HERE
+                  └──→ HOTFIX
+   ```
+
+3. **Display project context**
+   - Show:
+   ```
+   Milestone: {name} ({completed_phases}/{total_phases} phases)
+   Phase:     {name}
+   Plan:      {name or "none — run /sdlc:spec"}
+   ```
+
+4. **Show progress bar**
+   - Calculate completion percentage from ROADMAP.md.
+   - Display:
+   ```
+   Progress: [████████░░░░░░░░░░░░] 40% (4/10 plans completed)
+   ```
+
+5. **Show blockers and deferred issues**
+   - If blockers exist in STATE.md:
+   ```
+   BLOCKERS:
+   - {blocker 1}
+   - {blocker 2}
+   ```
+   - If deferred issues exist:
+   ```
+   DEFERRED:
+   - {issue 1}
+   - {issue 2}
+   ```
+   - If none: "No blockers. No deferred issues."
+
+6. **Force ONE next action with explanation**
+   - Determine the next action from loop_position (same logic as /sdlc:resume).
+   - Explain what that action DOES and WHY it is next:
+
+   ```
+   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.
+   Your implementation will be verified in the next step.
+   ```
+
+   - Junior-friendly: use plain language. Assume the reader has never used the framework.
+</process>
+
+<success_criteria>
+- [ ] STATE.md read successfully
+- [ ] Visual loop diagram displayed with current position highlighted
+- [ ] Milestone, phase, and plan shown
+- [ ] Progress bar calculated and displayed
+- [ ] Blockers and deferred issues shown (or "none")
+- [ ] Exactly ONE next action forced
+- [ ] Next action includes plain-language explanation of what it does and why
+- [ ] No choices, no menus — one clear path forward
+</success_criteria>

package/src/commands/verify.md

@@ -0,0 +1,153 @@
+---
+name: sdlc:verify
+description: Automated verification via Playwright MCP and test runners
+argument-hint: "[spec-path]"
+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_select_option, mcp__plugin_playwright_playwright__browser_hover, mcp__plugin_playwright_playwright__browser_press_key, mcp__plugin_playwright_playwright__browser_type, mcp__plugin_playwright_playwright__browser_navigate_back, mcp__plugin_playwright_playwright__browser_take_screenshot, mcp__plugin_playwright_playwright__browser_console_messages, mcp__plugin_playwright_playwright__browser_network_requests, mcp__plugin_playwright_playwright__browser_tabs, mcp__plugin_playwright_playwright__browser_wait_for, mcp__plugin_playwright_playwright__browser_evaluate, mcp__plugin_playwright_playwright__browser_handle_dialog, mcp__plugin_playwright_playwright__browser_file_upload, mcp__plugin_playwright_playwright__browser_close, mcp__plugin_playwright_playwright__browser_install, mcp__plugin_playwright_playwright__browser_resize, mcp__plugin_playwright_playwright__browser_drag, mcp__plugin_playwright_playwright__browser_run_code]
+---
+
+<objective>
+Verify the implementation against every acceptance criterion in the SPEC.md. Use automated testing appropriate to the work type: Playwright MCP for UI, HTTP requests for APIs, shell commands for CLIs, and test runners for logic.
+
+**When to use:** After /sdlc:impl completes all tasks. This is the VERIFY phase of the SDLC loop.
+
+**What it does:**
+1. Read acceptance criteria from SPEC.md.
+2. Determine the verification strategy per criterion (UI test, API test, CLI test, unit test).
+3. Execute each verification automatically.
+4. Report pass/fail per acceptance criterion with evidence.
+5. On failure: provide specific diagnosis and suggest fixes.
+
+**What happens next:**
+- All criteria pass: Framework directs you to /sdlc:review.
+- Any criteria fail: Fix the failures, then re-run /sdlc:verify.
+
+**Critical rule:** Every acceptance criterion gets tested. No criterion is skipped. No manual "it looks right" — automated verification only.
+</objective>
+
+<execution_context>
+@~/.claude/sdlc-framework/workflows/run-verify.md
+@.sdlc/STATE.md
+The SPEC.md path is read from STATE.md or provided via $ARGUMENTS.
+</execution_context>
+
+<context>
+$ARGUMENTS — optional path to SPEC.md. If not provided, read from .sdlc/STATE.md spec_path field.
+
+Read these files:
+- .sdlc/STATE.md — current plan, spec path, impl path.
+- The SPEC.md file — acceptance criteria to verify.
+- .sdlc/impl/IMPL-<plan-id>.md — files modified, build status.
+</context>
+
+<process>
+Follow workflow: @~/.claude/sdlc-framework/workflows/run-verify.md
+
+Step-by-step:
+
+1. **Load state and acceptance criteria**
+   - Read .sdlc/STATE.md. Confirm loop_position is IMPL_COMPLETE. If not, warn: "Implementation not complete. Run /sdlc:impl first."
+   - Read SPEC.md. Extract all acceptance criteria (AC-1, AC-2, ...).
+   - Read IMPL.md for the list of modified files and build status.
+
+2. **Classify each acceptance criterion by verification type**
+   For each AC, determine the appropriate test strategy:
+
+   | Work Type | Verification Method | Tools Used |
+   |-----------|-------------------|------------|
+   | UI/Frontend | Playwright MCP browser automation | browser_navigate, browser_click, browser_snapshot, browser_fill_form |
+   | REST API | HTTP requests via curl or fetch | Bash (curl commands) |
+   | GraphQL API | GraphQL queries via HTTP | Bash (curl commands) |
+   | CLI tool | Shell command execution | Bash |
+   | Business logic | Test runner (jest, vitest, pytest, etc.) | Bash (npm test, etc.) |
+   | Database | Query verification | Bash (database CLI tools) |
+   | File output | File content inspection | Read, Grep |
+
+3. **Execute UI verifications (Playwright MCP)**
+   For each UI acceptance criterion:
+   - Install browser if needed: call browser_install.
+   - Navigate to the target URL: call browser_navigate.
+   - Take a snapshot to understand the page state: call browser_snapshot.
+   - Execute the Given/When/Then steps:
+     - **Given** (precondition): Navigate to the correct page, fill forms, click setup elements.
+     - **When** (action): Click buttons, submit forms, type input, select options.
+     - **Then** (assertion): Take a snapshot, inspect the DOM for expected elements, check console for errors, verify network requests.
+   - Take a screenshot as evidence: call browser_take_screenshot.
+   - Record pass/fail with evidence (screenshot path, DOM state, console output).
+
+4. **Execute API verifications**
+   For each API acceptance criterion:
+   - Construct the HTTP request (method, URL, headers, body) from the AC.
+   - Execute via curl in Bash.
+   - Parse the response (status code, body, headers).
+   - Compare against expected values from the AC.
+   - Record pass/fail with evidence (request/response pairs).
+
+5. **Execute CLI verifications**
+   For each CLI acceptance criterion:
+   - Construct the shell command from the AC.
+   - Execute via Bash.
+   - Capture stdout, stderr, and exit code.
+   - Compare against expected values from the AC.
+   - Record pass/fail with evidence (command, output, exit code).
+
+6. **Execute logic verifications**
+   For each logic acceptance criterion:
+   - Identify the relevant test files.
+   - Run the test suite (or specific test files) via Bash.
+   - Parse test output for pass/fail counts.
+   - Record pass/fail with evidence (test runner output).
+
+7. **Compile verification report**
+   Create .sdlc/verify/VERIFY-<plan-id>.md with:
+   ```
+   # Verification Report: <plan title>
+
+   ## Summary
+   - Total ACs: <count>
+   - Passed: <count>
+   - Failed: <count>
+   - Skipped: <count> (with reasons)
+
+   ## Results
+
+   ### AC-1: <title>
+   - Status: PASS / FAIL
+   - Verification type: UI / API / CLI / Logic
+   - Evidence: <screenshot path / response body / test output>
+   - Details: <what was checked and what was found>
+
+   ### AC-2: <title>
+   ...
+
+   ## Failures (if any)
+   ### AC-X: <title>
+   - Expected: <what should have happened>
+   - Actual: <what actually happened>
+   - Root cause: <analysis of why it failed>
+   - Suggested fix: <specific code change to fix it>
+   - Files to modify: <file paths>
+   ```
+
+8. **Determine next action**
+   - If ALL acceptance criteria pass:
+     - Update STATE.md: set `loop_position: VERIFY_COMPLETE`
+     - Set `verify_path: .sdlc/verify/VERIFY-<plan-id>.md`
+     - Output ends with: NEXT ACTION REQUIRED: /sdlc:review
+   - If ANY acceptance criteria fail:
+     - Update STATE.md: set `loop_position: VERIFY_FAILED`
+     - Output the failure details with suggested fixes.
+     - Output ends with: "Fix the failures above, then re-run /sdlc:verify"
+</process>
+
+<success_criteria>
+- [ ] Every acceptance criterion from SPEC.md has a corresponding verification
+- [ ] Correct verification type selected per AC (UI uses Playwright, API uses curl, etc.)
+- [ ] UI tests use Playwright MCP tools (navigate, snapshot, click, fill_form, screenshot)
+- [ ] Each verification produces concrete evidence (screenshots, response bodies, test output)
+- [ ] VERIFY-<plan-id>.md created with per-AC pass/fail results
+- [ ] Failed ACs include: expected vs actual, root cause analysis, suggested fix, files to modify
+- [ ] STATE.md updated with loop_position (VERIFY_COMPLETE or VERIFY_FAILED)
+- [ ] If all pass: output ends with NEXT ACTION REQUIRED: /sdlc:review
+- [ ] If any fail: output ends with "Fix the failures above, then re-run /sdlc:verify"
+- [ ] No criteria skipped without documented reason
+</success_criteria>