sdlc-framework 1.0.0

package/src/workflows/spec-phase.md

@@ -0,0 +1,379 @@
+<purpose>Create a detailed specification through structured clarification and task decomposition. This is the MOST IMPORTANT workflow — a bad spec cascades failures through implementation, verification, and review. Never guess. Always ask. Always recommend.</purpose>
+<when_to_use>Run after /sdlc:init (first spec) or after /sdlc:close (next loop iteration). STATE.md must show next_required_action = /sdlc:spec.</when_to_use>
+<required_reading>.sdlc/STATE.md, .sdlc/ROADMAP.md, .sdlc/LAWS.md, .sdlc/PROJECT.md, any prior SUMMARY.md files in the current phase</required_reading>
+<loop_context>
+  expected_phase: SPEC (active)
+  prior_phase: CLOSE (or INIT for first spec)
+  next_phase: IMPL
+</loop_context>
+<process>
+
+<step name="validate_state" priority="first">
+  Read .sdlc/STATE.md.
+
+  CHECK: Is next_required_action set to /sdlc:spec?
+
+  IF YES: Proceed.
+  IF NO: STOP. Display: "Cannot start spec. Current state requires: {next_required_action}. Complete that step first."
+
+  CHECK: Is the prior loop closed? Look at loop_position:
+  - If "INIT ✓" → this is the first spec, proceed
+  - If "CLOSE ✓" → prior loop is done, proceed
+  - If anything else (e.g., "IMPL ✓" or "VERIFY ✓") → STOP. The prior loop is not closed.
+
+  WHY: The state machine prevents skipping steps. If you skip review, bugs ship. If you skip verify, untested code ships. The loop is non-negotiable.
+</step>
+
+<step name="load_context" priority="second">
+  Read .sdlc/ROADMAP.md to identify:
+  - Current milestone number and name
+  - Current phase number and name
+  - How many plans have been completed in this phase
+
+  Calculate the next plan number:
+  - List files in .sdlc/phases/{current-phase}/ matching *-SPEC.md
+  - Next plan = count + 1, zero-padded to 2 digits (01, 02, 03...)
+
+  Read .sdlc/PROJECT.md to load:
+  - Tech stack (needed for implementation guidance)
+  - Architecture patterns (needed for task decomposition)
+  - Conventions (needed for consistency)
+
+  Read any SUMMARY.md files from prior plans in this phase:
+  - These contain decisions, lessons learned, and context
+  - Summarize key points that might affect this spec
+  - Present relevant context to user: "From prior work in this phase: {summary}"
+
+  WHY: Context continuity prevents re-litigating decisions and ensures consistency. Without reading prior summaries, each spec starts from zero and may contradict earlier work.
+</step>
+
+<step name="clarification_phase" priority="third">
+  THIS STEP IS CRITICAL. DO NOT SKIP OR SHORTCUT.
+
+  Start with an open-ended prompt:
+  "What do you want to build in this plan? Describe the feature, fix, or change."
+
+  LISTEN to the response. Do NOT immediately start writing code or specs.
+
+  Then ask 3-5 TARGETED clarification questions. Each question MUST:
+  - Be specific to what the user described (not generic)
+  - Include a RECOMMENDATION with reasoning
+  - Present trade-offs when multiple approaches exist
+
+  Categories to cover (pick the most relevant 3-5):
+
+  A. SCOPE BOUNDARIES:
+     "You mentioned {X}. Does this include {Y}? I recommend excluding {Y} for now because {reason}. We can add it in a follow-up plan."
+
+  B. TECHNICAL APPROACH:
+     "For implementing {feature}, I see these options:
+       Option A: {approach} — Pros: {pros}. Cons: {cons}. Effort: {estimate}.
+       Option B: {approach} — Pros: {pros}. Cons: {cons}. Effort: {estimate}.
+       I recommend Option {X} because {reason}."
+
+  C. EDGE CASES AND ERRORS:
+     "What should happen when {edge case}? For example: empty input, network failure, concurrent access, missing data. I recommend {approach} because {reason}."
+
+  D. INTEGRATION POINTS:
+     "This will touch {existing module/file}. I found {pattern} already in use there. Should we follow the same pattern or is there a reason to diverge?"
+
+  E. TESTING STRATEGY:
+     "How should we verify this works? I recommend {unit tests for logic, Playwright for UI, curl for API} because {reason}."
+
+  WAIT for the user to answer ALL questions before proceeding.
+
+  IF the user's answers reveal more ambiguity, ask follow-up questions. Do NOT proceed with ambiguity.
+
+  WHY: Guessing is the #1 cause of rework. A 5-minute clarification saves hours of implementation in the wrong direction. The recommendations save the user from having to research options themselves.
+</step>
+
+<step name="task_decomposition" priority="fourth">
+  Break the work into discrete, independently verifiable tasks.
+
+  TARGET: 2-5 tasks per spec. If you have more than 5, the spec is too large — suggest splitting into multiple plans.
+
+  For EACH task, define:
+  ```
+  Task: {task-name} (kebab-case, descriptive)
+  Action: {what to do — imperative voice, specific}
+  Files to modify: {list of file paths}
+  Files to create: {list of new file paths, if any}
+  Verification: {how to confirm this task is done correctly}
+  Done criteria: {observable outcome — "the test passes", "the endpoint returns 200", etc.}
+  Estimated complexity: LOW (<20 lines) | MEDIUM (20-60 lines) | HIGH (60+ lines)
+  ```
+
+  DEPENDENCY ANALYSIS — build a directed acyclic graph (DAG):
+
+  For each task, ask: "Does this task depend on another task's output?"
+  - If task-3 needs a function created by task-1 → task-3 depends on task-1
+  - If task-2 needs a type defined by task-1 → task-2 depends on task-1
+  - If task-1 and task-2 touch different files with no shared types → they are INDEPENDENT
+
+  Group tasks into PARALLEL WAVES:
+  - Wave 1: all tasks with no dependencies (can run simultaneously)
+  - Wave 2: tasks that depend only on Wave 1 tasks
+  - Wave 3: tasks that depend on Wave 2 tasks
+  - And so on
+
+  Present the dependency graph to the user:
+  ```
+  Wave 1 (parallel): task-1, task-2
+  Wave 2 (after wave 1): task-3 (depends on task-1, task-2)
+  Wave 3 (after wave 2): task-4 (depends on task-3)
+  ```
+
+  Ask: "Does this task breakdown and ordering look right? Any tasks missing or misplaced?"
+
+  WHY: Parallel execution dramatically speeds up implementation. But wrong dependency ordering causes race conditions where an agent tries to use code that does not exist yet. The DAG prevents this.
+</step>
+
+<step name="write_acceptance_criteria" priority="fifth">
+  For each piece of observable behavior, write a BDD acceptance criterion:
+
+  ```
+  AC-{N}: {short description}
+  GIVEN {initial state or precondition}
+  WHEN {action or trigger}
+  THEN {expected outcome}
+  ```
+
+  Rules for writing good ACs:
+  - Each AC tests ONE behavior (not multiple things)
+  - The GIVEN sets up a specific, reproducible state
+  - The WHEN is a single action (not a sequence)
+  - The THEN is observable and verifiable (not "works correctly" — specify WHAT is correct)
+  - Include at least one AC for the "happy path" and one for an error/edge case
+
+  Example (good):
+  ```
+  AC-1: User login with valid credentials
+  GIVEN a registered user with email "test@example.com" and password "ValidPass123"
+  WHEN the user submits the login form with those credentials
+  THEN a JWT token is returned with status 200 and the response body contains { "token": "<jwt>" }
+  ```
+
+  Example (bad — too vague):
+  ```
+  AC-1: Login works
+  GIVEN a user
+  WHEN they log in
+  THEN it works
+  ```
+
+  WHY: The verify phase translates ACs directly into test actions. Vague ACs produce vague tests that pass even when the code is broken. Specific ACs catch real bugs.
+</step>
+
+<step name="define_boundaries" priority="sixth">
+  List what this spec does NOT cover. Be explicit.
+
+  ```
+  ## Boundaries — Do NOT Change
+  - {file or module}: {reason it is out of scope}
+  - {feature}: {reason it is deferred}
+  ```
+
+  Also list any existing patterns that MUST be followed:
+  ```
+  ## Required Patterns
+  - Error handling: use {existing pattern} from {file}
+  - Naming: follow {convention} as seen in {file}
+  - Testing: use {test helper/factory} from {file}
+  ```
+
+  WHY: Without boundaries, sub-agents during implementation will "helpfully" refactor nearby code, breaking things outside the spec scope. Boundaries are guardrails.
+</step>
+
+<step name="write_spec_file" priority="seventh">
+  Write the spec to: .sdlc/phases/{phase-dir}/{plan-number}-SPEC.md
+
+  Format:
+  ```markdown
+  ---
+  phase: {phase-number}-{phase-name}
+  plan: {plan-number}
+  type: execute
+  autonomous: true
+  task_graph:
+    parallel_groups:
+      - [{wave-1-tasks}]
+      - [{wave-2-tasks}]
+    dependencies:
+      {task}: [{dependency-tasks}]
+  files_modified: []
+  files_created: []
+  ---
+
+  # Plan {plan-number}: {title}
+
+  ## Context
+  {What this plan accomplishes and why it matters in the broader phase}
+
+  ## Prior Decisions
+  {Relevant decisions from prior plans, or "First plan in phase" if none}
+
+  ## Tasks
+
+  ### Task 1: {task-name}
+  - **Action**: {what to do}
+  - **Files**: {files to modify/create}
+  - **Verification**: {how to verify}
+  - **Done criteria**: {observable outcome}
+  - **Complexity**: {LOW|MEDIUM|HIGH}
+
+  ### Task 2: {task-name}
+  ...
+
+  ## Dependency Graph
+  ```
+  Wave 1 (parallel): {tasks}
+  Wave 2 (sequential after wave 1): {tasks}
+  ```
+
+  ## Acceptance Criteria
+
+  AC-1: {description}
+  GIVEN {precondition}
+  WHEN {action}
+  THEN {outcome}
+
+  AC-2: ...
+
+  ## Boundaries
+  - DO NOT modify: {files/modules}
+  - DO NOT implement: {out-of-scope features}
+
+  ## Required Patterns
+  - {pattern}: {source file}
+
+  ## Engineering Laws
+  Enforced per .sdlc/LAWS.md. Key reminders for this plan:
+  - {most relevant law for this specific work}
+  - {second most relevant law}
+  ```
+
+  WHY: The YAML frontmatter is machine-readable — the impl phase parses it to build the execution plan. The markdown body is human-readable — developers can review it. Both are needed.
+</step>
+
+<step name="spec_integrity_review" priority="eighth">
+  BEFORE updating state, perform a self-review of the spec for completeness and correctness.
+
+  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 ✗
+
+  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:
+  ```
+  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}
+  ```
+
+  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.
+</step>
+
+<step name="user_approval_gate" priority="ninth">
+  THIS IS A BLOCKING GATE. The spec does NOT proceed without explicit user approval.
+
+  Present the complete spec summary to the user:
+  ```
+  ══════════════════════════════════════
+  SPEC REVIEW — Approval Required
+  ══════════════════════════════════════
+
+  Plan: {plan-number} — {title}
+  Phase: {phase-name}
+
+  Tasks ({N}):
+  {numbered list of task names with complexity}
+
+  Execution Order:
+  Wave 1 (parallel): {tasks}
+  Wave 2 (after wave 1): {tasks}
+
+  Acceptance Criteria ({N}):
+  {numbered list of AC descriptions}
+
+  Boundaries:
+  {list of protected files/modules}
+
+  Spec file: .sdlc/phases/{phase}/{plan}-SPEC.md
+  ══════════════════════════════════════
+
+  Review the spec above. Your options:
+  1. APPROVE — Proceed to implementation
+  2. REVISE — Tell me what to change (I will update the spec and re-present)
+  3. REJECT — Discard this spec and start over
+  ```
+
+  Wait for user response using AskUserQuestion.
+
+  IF "APPROVE" (or "1", "yes", "looks good", "go", "lgtm"):
+    Proceed to update_state step.
+
+  IF "REVISE" (or "2", or user provides specific feedback):
+    Apply the requested changes to the SPEC.md file.
+    Re-run spec_integrity_review on the updated spec.
+    Re-present for approval (loop back to this step).
+    Do NOT proceed until approved.
+
+  IF "REJECT" (or "3", "start over", "scrap it"):
+    Delete the spec file.
+    Display: "Spec discarded. Run /sdlc:spec to start a new spec."
+    Do NOT update STATE.md.
+    STOP.
+
+  WHY: Implementation is expensive. Building the wrong thing wastes hours. A 30-second review of the spec catches misunderstandings before they become code. The user MUST see and approve the plan before sub-agents start writing code.
+</step>
+
+<step name="update_state" priority="tenth">
+  ONLY REACHED AFTER USER APPROVES THE SPEC.
+
+  Update .sdlc/STATE.md:
+  - loop_position: SPEC ✓
+  - current_plan: {plan-number}
+  - current_phase: {phase-number}
+  - next_required_action: /sdlc:impl
+  - Add history entry: "{timestamp} | spec | Plan {N} spec approved: {title}"
+
+  Update .sdlc/ROADMAP.md:
+  - Increment plan count for current phase
+  - Set phase status to IN PROGRESS if not already
+
+  Display to user:
+  ```
+  Spec approved: .sdlc/phases/{phase}/{plan}-SPEC.md
+
+  Tasks: {N} ({N} parallel waves)
+  Acceptance Criteria: {N}
+  Boundaries: {N} files protected
+
+  NEXT ACTION REQUIRED: /sdlc:impl
+  Run /sdlc:impl to begin sub-agent implementation.
+  ```
+
+  WHY: The forcing function ensures the user moves to implementation. Without it, specs pile up without being built.
+</step>
+
+</process>

package/src/workflows/transition-phase.md

@@ -0,0 +1,203 @@
+<purpose>Transition from one phase to the next within a milestone. Called automatically by close-phase when the last plan in a phase completes. Verifies completeness, updates project state, and commits the phase.</purpose>
+<when_to_use>Triggered automatically when /sdlc:close detects the last plan in a phase is done. Can also be run manually via /sdlc:transition to force a phase transition.</when_to_use>
+<required_reading>.sdlc/STATE.md, .sdlc/ROADMAP.md, .sdlc/PROJECT.md, all SUMMARY.md files in the completing phase</required_reading>
+<loop_context>
+  expected_phase: TRANSITION (between phases)
+  prior_phase: CLOSE ✓ (last plan in phase)
+  next_phase: first SPEC of the next phase, or milestone completion
+</loop_context>
+<process>
+
+<step name="verify_phase_completeness" priority="first">
+  Read .sdlc/STATE.md. Extract the current phase.
+  Read .sdlc/ROADMAP.md. Get the current phase's plan count.
+
+  List all files in .sdlc/phases/{current_phase}/:
+  - Count *-SPEC.md files (plans created)
+  - Count *-SUMMARY.md files (plans completed)
+  - Count HOTFIX-*-SUMMARY.md files (hotfixes applied)
+
+  VERIFY: Every SPEC.md has a corresponding SUMMARY.md.
+  - If a SPEC exists without a SUMMARY: that plan was not completed.
+  - STOP. Display: "Phase transition blocked. Plan {N} has a spec but no summary. Complete it first."
+
+  VERIFY: Every SUMMARY.md shows all ACs passed.
+  - Read each SUMMARY.md. Check the AC results table.
+  - If any AC is FAIL: STOP. Display: "Phase transition blocked. Plan {N} has failing ACs."
+
+  Display:
+  ```
+  Phase {phase} completeness check:
+  Plans: {N} created, {N} completed
+  Hotfixes: {N}
+  All ACs: PASSED
+  Phase is ready for transition.
+  ```
+
+  WHY: Transitioning with incomplete work means skipping it forever. The completeness check prevents accidental abandonment.
+</step>
+
+<step name="verify_state_consistency" priority="second">
+  Cross-check three state files for consistency:
+
+  STATE.MD:
+  - current_milestone should match ROADMAP.md's in-progress milestone
+  - current_phase should match the phase being completed
+  - loop_position should be CLOSE ✓
+
+  PROJECT.MD:
+  - Tech stack should still be accurate (ask user if uncertain)
+  - Requirements section should reflect what was built
+
+  ROADMAP.MD:
+  - Current phase should show correct plan count
+  - Prior phases in this milestone should all be COMPLETE
+
+  IF INCONSISTENCY FOUND:
+  Display: "State inconsistency: {detail}. Recommend fixing before transitioning."
+  Offer to auto-fix obvious inconsistencies (e.g., plan count mismatch).
+  Ask for user confirmation before applying fixes.
+
+  WHY: State drift accumulates silently. Catching it at phase boundaries prevents compounding errors.
+</step>
+
+<step name="update_project_md" priority="third">
+  Read .sdlc/PROJECT.md.
+
+  Based on the completed phase's summaries:
+
+  A. VALIDATE EXISTING REQUIREMENTS:
+  For each requirement listed in PROJECT.md:
+  - Was it addressed in this phase? (search summaries for related work)
+  - If addressed: mark as IMPLEMENTED with reference to plan number
+  - If not addressed: leave as-is (future phase responsibility)
+
+  B. INVALIDATE OUTDATED REQUIREMENTS:
+  For each requirement:
+  - Does the implementation contradict or supersede it?
+  - If yes: mark as SUPERSEDED with explanation
+
+  C. ADD NEW REQUIREMENTS:
+  From decisions and lessons learned in summaries:
+  - Were new requirements discovered during implementation?
+  - If yes: add them to PROJECT.md with status NOT STARTED
+
+  Display changes to user before writing:
+  ```
+  PROJECT.md updates:
+  - IMPLEMENTED: {requirement} (Plan {N})
+  - SUPERSEDED: {requirement} (replaced by {new approach})
+  - NEW: {requirement} (discovered in Plan {N})
+
+  Apply these changes? (yes/no)
+  ```
+
+  WHY: PROJECT.md must stay current. Stale requirements mislead future specs. New requirements discovered during implementation must be captured or they are forgotten.
+</step>
+
+<step name="update_state_for_next_phase" priority="fourth">
+  Read .sdlc/ROADMAP.md. Identify the next phase in the current milestone.
+
+  IF NEXT PHASE EXISTS:
+    Update .sdlc/STATE.md:
+    - current_phase: {next phase number and name}
+    - current_plan: cleared
+    - loop_position: TRANSITION ✓
+    - next_required_action: /sdlc:spec
+    - Add history entry: "{timestamp} | transition | Phase {old} complete. Transitioning to phase {new}."
+
+    Update .sdlc/ROADMAP.md:
+    - Set completed phase status to COMPLETE with date
+    - Set next phase status to IN PROGRESS
+
+  IF NO NEXT PHASE (this was the last phase in the milestone):
+    Update .sdlc/STATE.md:
+    - loop_position: TRANSITION ✓
+    - next_required_action: /sdlc:milestone complete
+    - Add history entry: "{timestamp} | transition | Phase {current} complete. Last phase in milestone. Trigger milestone completion."
+
+    Update .sdlc/ROADMAP.md:
+    - Set completed phase status to COMPLETE with date
+
+  WHY: The state machine must always point to exactly one next action. Whether that is the next phase or milestone completion depends on the roadmap.
+</step>
+
+<step name="update_roadmap" priority="fifth">
+  Update .sdlc/ROADMAP.md with phase completion details:
+
+  For the completed phase, update the row:
+  ```
+  | {phase-num} | {name} | COMPLETE ({date}) | {plan-count} |
+  ```
+
+  Add a phase summary note under the milestone:
+  ```
+  #### Phase {number} Summary
+  - Plans executed: {N}
+  - Hotfixes: {N}
+  - Key deliverables: {from summaries}
+  - Duration: {first spec date} to {completion date}
+  ```
+
+  WHY: The roadmap is the high-level progress tracker. Completion details help stakeholders understand velocity and scope.
+</step>
+
+<step name="create_git_commit" priority="sixth">
+  IF the project is a git repository:
+
+  Check: git status for uncommitted changes.
+
+  IF UNCOMMITTED CHANGES EXIST:
+    Stage all .sdlc/ files: git add .sdlc/
+    Stage any source files that were part of the phase
+
+    Create commit:
+    ```
+    feat({phase-name}): complete phase {number}
+
+    Phase {number} ({phase-name}) of milestone {milestone-number} is complete.
+
+    Plans executed: {N}
+    Key deliverables:
+    - {deliverable 1}
+    - {deliverable 2}
+    ```
+
+    Display: "Git commit created: {hash}"
+
+  IF NO UNCOMMITTED CHANGES:
+    Display: "No uncommitted changes to commit."
+
+  WHY: Phase completion is a natural commit point. The commit message documents what was accomplished, making git log useful as a project history.
+</step>
+
+<step name="display_result" priority="seventh">
+  IF NEXT PHASE EXISTS:
+    Display:
+    ```
+    Phase transition complete.
+
+    Completed: Phase {old-number} — {old-name}
+    Plans: {N} executed
+    Starting: Phase {new-number} — {new-name}
+
+    NEXT ACTION REQUIRED: /sdlc:spec
+    Run /sdlc:spec to create the first specification for Phase {new-number}.
+    ```
+
+  IF MILESTONE COMPLETE (no next phase):
+    Display:
+    ```
+    Phase transition complete.
+
+    Completed: Phase {number} — {name} (LAST PHASE)
+    Milestone {milestone-number} — {milestone-name}: ALL PHASES COMPLETE
+
+    NEXT ACTION REQUIRED: /sdlc:milestone complete
+    Run /sdlc:milestone complete to finalize the milestone.
+    ```
+
+  WHY: The display makes the transition visible. Moving to a new phase is a significant moment — the user should know where they are in the broader plan.
+</step>
+
+</process>