sdlc-framework 1.0.0

package/src/templates/REVIEW.md

@@ -0,0 +1,145 @@
+# Code Review Findings Template
+
+This template defines the review document produced during `/sdlc:review`. It is stored at `.sdlc/milestones/M{{N}}/phases/P{{N}}/reviews/REVIEW-{{NNN}}.md`. The review evaluates all code changes against the engineering laws defined in `.sdlc/LAWS.md`.
+
+---
+
+```markdown
+# Code Review: {{SPEC_TITLE}}
+
+**Spec:** {{SPEC_FILE_PATH}}
+**Reviewer:** SDLC Framework (automated)
+**Date:** {{DATE}}
+
+## Files Reviewed
+
+| File | Lines Changed | Type |
+|------|---------------|------|
+| {{FILE_PATH}} | {{LINES_ADDED}}/{{LINES_REMOVED}} | {{created/modified}} |
+
+**Total files reviewed:** {{COUNT}}
+**Total lines changed:** {{TOTAL_ADDED}} added, {{TOTAL_REMOVED}} removed
+
+## Summary
+
+| Severity | Count |
+|----------|-------|
+| error (blocks closure) | {{COUNT}} |
+| warning (reported) | {{COUNT}} |
+| info (noted) | {{COUNT}} |
+
+**Overall status:** {{PASS — no errors / BLOCKED — errors found}}
+
+---
+
+## Findings
+
+### {{FILE_PATH}}
+
+#### Finding F-{{NNN}}
+
+- **Lines:** {{START_LINE}}–{{END_LINE}}
+- **Law:** {{LAW_NAME}} ({{SOLID/DRY/YAGNI/CLEAN_CODE/SECURITY/TESTING/NAMING/ERROR_HANDLING}})
+- **Severity:** {{error/warning/info}}
+- **Description:** {{WHAT_IS_WRONG — specific, concrete, no hand-waving}}
+- **Code:**
+  ```{{language}}
+  {{THE_PROBLEMATIC_CODE}}
+  ```
+- **Suggested Fix:**
+  ```{{language}}
+  {{HOW_TO_FIX_IT}}
+  ```
+- **Why:** {{WHY_THIS_MATTERS — real consequence, not theoretical}}
+
+---
+
+#### Finding F-{{NNN}}
+
+- **Lines:** {{START_LINE}}–{{END_LINE}}
+- **Law:** {{LAW_NAME}}
+- **Severity:** {{error/warning/info}}
+- **Description:** {{WHAT_IS_WRONG}}
+- **Code:**
+  ```{{language}}
+  {{THE_PROBLEMATIC_CODE}}
+  ```
+- **Suggested Fix:**
+  ```{{language}}
+  {{HOW_TO_FIX_IT}}
+  ```
+- **Why:** {{WHY_THIS_MATTERS}}
+
+---
+
+### {{NEXT_FILE_PATH}}
+
+#### Finding F-{{NNN}}
+
+(Same structure as above, repeated for each finding in each file)
+
+---
+
+## Law Summary
+
+| Law | Findings | Errors | Warnings | Info |
+|-----|----------|--------|----------|------|
+| SOLID | {{COUNT}} | {{COUNT}} | {{COUNT}} | {{COUNT}} |
+| DRY | {{COUNT}} | {{COUNT}} | {{COUNT}} | {{COUNT}} |
+| YAGNI | {{COUNT}} | {{COUNT}} | {{COUNT}} | {{COUNT}} |
+| CLEAN_CODE | {{COUNT}} | {{COUNT}} | {{COUNT}} | {{COUNT}} |
+| SECURITY | {{COUNT}} | {{COUNT}} | {{COUNT}} | {{COUNT}} |
+| TESTING | {{COUNT}} | {{COUNT}} | {{COUNT}} | {{COUNT}} |
+| NAMING | {{COUNT}} | {{COUNT}} | {{COUNT}} | {{COUNT}} |
+| ERROR_HANDLING | {{COUNT}} | {{COUNT}} | {{COUNT}} | {{COUNT}} |
+| **Total** | **{{COUNT}}** | **{{COUNT}}** | **{{COUNT}}** | **{{COUNT}}** |
+
+## Overall Assessment
+
+{{FREE_TEXT_ASSESSMENT — 2-3 sentences summarizing code quality, notable positives, and primary concerns}}
+
+### Blocking Issues
+
+{{LIST_OF_ERROR_SEVERITY_FINDINGS_THAT_MUST_BE_FIXED or "No blocking issues found."}}
+
+### Recommendations
+
+{{NON_BLOCKING_SUGGESTIONS_FOR_IMPROVEMENT or "No additional recommendations."}}
+
+### Resolution Required
+
+{{IF_BLOCKED: what specifically must be fixed and in which files}}
+{{IF_PASS: "No resolution required. Code review passed."}}
+```
+
+---
+
+## Field Documentation
+
+### Files Reviewed
+Every file that was created or modified by the implementation. Lines changed gives a sense of scope — large changes get more scrutiny.
+
+### Summary
+Quick overview. The three severity counts tell you instantly whether the review blocks closure. If `error` count is 0, the review passes.
+
+### Findings
+The core of the review. Each finding is specific and actionable:
+- **Lines** — Exact location so the developer can jump to the code
+- **Law** — Which engineering law is violated
+- **Severity** — Whether this blocks closure
+- **Description** — What is wrong in plain English
+- **Code** — The actual problematic code (not a paraphrase)
+- **Suggested Fix** — How to fix it (working code, not hand-waving)
+- **Why** — Real-world consequence to motivate the fix
+
+### Finding IDs
+Findings are numbered sequentially (F-001, F-002, etc.) across the entire review, not per file. This makes them easy to reference in discussions and in the summary.
+
+### Law Summary
+Table showing which laws had findings and at what severity. Useful for spotting patterns — if DRY has 5 findings, there may be a systemic issue with code reuse.
+
+### Overall Assessment
+Human-readable summary. Not a repeat of the findings table — a narrative assessment of code quality. Mention positives as well as negatives.
+
+### Resolution Required
+If the review is blocked, this section lists exactly what must be fixed. When the developer fixes the issues, they re-run `/sdlc:review` and a new review is generated.

package/src/templates/ROADMAP.md

@@ -0,0 +1,101 @@
+# Roadmap Template
+
+This template defines the phase breakdown and milestone tracker stored at `.sdlc/ROADMAP.md`. It is created during `/sdlc:init` and updated as milestones and phases complete. The roadmap is the high-level plan; individual specs contain the low-level details.
+
+---
+
+```markdown
+# Roadmap: {{PROJECT_NAME}}
+
+## Version Overview
+
+| Version | Milestone | Status | Phases | Target |
+|---------|-----------|--------|--------|--------|
+| {{VERSION}} | {{MILESTONE_NAME}} | {{planned/active/complete}} | {{PHASE_COUNT}} | {{TARGET_DATE or "TBD"}} |
+
+---
+
+## Milestone {{MILESTONE_NUMBER}}: {{MILESTONE_NAME}}
+
+**Goal:** {{ONE_SENTENCE_GOAL}}
+**Status:** {{planned/active/complete}}
+**Started:** {{DATE or "Not started"}}
+**Completed:** {{DATE or "In progress"}}
+
+### Phase {{PHASE_NUMBER}}: {{PHASE_NAME}}
+
+**Description:** {{WHAT_THIS_PHASE_DELIVERS}}
+**Status:** {{planned/active/complete}}
+
+| Plan | Description | Status | Spec | Summary |
+|------|-------------|--------|------|---------|
+| {{PLAN_NUMBER}} | {{PLAN_DESCRIPTION}} | {{planned/spec/implement/verify/review/close/complete}} | {{SPEC_PATH or "—"}} | {{SUMMARY_PATH or "—"}} |
+
+#### Phase Dependencies
+
+- **Requires:** {{PREVIOUS_PHASE or "None"}}
+- **Enables:** {{NEXT_PHASE or "None"}}
+- **External:** {{EXTERNAL_DEPENDENCIES or "None"}}
+
+---
+
+## Progress Tracking
+
+### Completed
+
+| Milestone | Phase | Plan | Completed | Summary |
+|-----------|-------|------|-----------|---------|
+| {{MILESTONE}} | {{PHASE}} | {{PLAN}} | {{DATE}} | {{SUMMARY_PATH}} |
+
+### In Progress
+
+| Milestone | Phase | Plan | Started | Current Step |
+|-----------|-------|------|---------|--------------|
+| {{MILESTONE}} | {{PHASE}} | {{PLAN}} | {{DATE}} | {{LOOP_STEP}} |
+
+### Upcoming
+
+| Milestone | Phase | Plan | Blocked By |
+|-----------|-------|------|------------|
+| {{MILESTONE}} | {{PHASE}} | {{PLAN}} | {{DEPENDENCY or "Ready"}} |
+
+---
+
+## Change Log
+
+| Date | Change | Reason |
+|------|--------|--------|
+| {{DATE}} | {{WHAT_CHANGED}} | {{WHY}} |
+```
+
+---
+
+## Field Documentation
+
+### Version Overview
+High-level view of all milestones. Each milestone represents a significant deliverable — something you could demo or release.
+
+### Milestone Sections
+Each milestone gets its own section with phases listed in execution order. Phases within a milestone are sequential — Phase 2 starts after Phase 1 completes. Plans within a phase may have their own dependency graph defined in the spec.
+
+### Plan Status Values
+Plans move through these statuses in order:
+- **planned** — Not yet started
+- **spec** — Specification is being written or reviewed
+- **implement** — Code is being written
+- **verify** — Acceptance criteria are being tested
+- **review** — Engineering laws are being checked
+- **close** — Loop is being closed, summary being written
+- **complete** — Loop closed, summary written, done
+
+### Phase Dependencies
+Explicit dependency tracking prevents starting work that depends on incomplete prerequisites. "External" captures things outside the project's control (API access, design assets, stakeholder decisions).
+
+### Progress Tracking
+Three tables provide instant status:
+- **Completed** — Done work with links to summaries for reference
+- **In Progress** — Current work with loop position
+- **Upcoming** — Future work with dependency information
+
+### Change Log
+Roadmaps change. When they do, record what changed and why. This prevents "I thought we were building X" confusion.

package/src/templates/SPEC.md

@@ -0,0 +1,231 @@
+# Specification Template
+
+This template defines the structure for individual specs stored at `.sdlc/milestones/M{{N}}/phases/P{{N}}/specs/SPEC-{{NNN}}.md`. Each spec represents one iteration of the SDLC loop. It is produced during `/sdlc:spec` and consumed by `/sdlc:implement`.
+
+---
+
+```markdown
+---
+phase: {{PHASE_NAME}}
+plan: {{PLAN_NUMBER}}
+type: {{feature/bugfix/refactor/test/docs}}
+autonomous: {{true/false}}
+task_graph:
+  parallel_groups:
+    - group: 1
+      tasks: [T-001, T-002]
+    - group: 2
+      tasks: [T-003]
+      depends_on: [1]
+    - group: 3
+      tasks: [T-004, T-005]
+      depends_on: [2]
+  dependencies:
+    T-003: [T-001, T-002]
+    T-004: [T-003]
+    T-005: [T-003]
+files_modified:
+  - {{src/path/to/file.ts}}
+  - {{src/path/to/another-file.ts}}
+---
+
+# Spec: {{SPEC_TITLE}}
+
+<objective>
+
+## Goal
+
+{{ONE_SENTENCE_GOAL}}
+
+## Purpose
+
+{{WHY_THIS_WORK_MATTERS — what problem does it solve, what value does it deliver}}
+
+## Output
+
+{{CONCRETE_DELIVERABLE — what exists after this spec is implemented that did not exist before}}
+
+</objective>
+
+<context>
+
+## Relevant Files
+
+- @{{src/path/to/existing-file.ts}} — {{WHY_THIS_FILE_IS_RELEVANT}}
+- @{{src/path/to/related-file.ts}} — {{HOW_IT_CONNECTS_TO_THIS_SPEC}}
+- @{{.sdlc/PROJECT.md}} — Project context and constraints
+- @{{.sdlc/LAWS.md}} — Engineering laws to follow
+
+## Background
+
+{{ADDITIONAL_CONTEXT — prior decisions, related specs, domain knowledge needed to understand this work}}
+
+</context>
+
+<clarifications>
+
+## Questions and Answers
+
+These clarifications were gathered during the spec phase. They form the audit trail of decisions made before implementation began.
+
+| # | Question | Answer | Date |
+|---|----------|--------|------|
+| Q-001 | {{QUESTION_ASKED}} | {{ANSWER_RECEIVED}} | {{DATE}} |
+| Q-002 | {{QUESTION_ASKED}} | {{ANSWER_RECEIVED}} | {{DATE}} |
+
+## Recommendations Given
+
+| # | Topic | Options Presented | Recommendation | Decision |
+|---|-------|-------------------|----------------|----------|
+| R-001 | {{TOPIC}} | {{A, B, C}} | {{RECOMMENDED_OPTION_AND_WHY}} | {{CHOSEN_OPTION}} |
+
+</clarifications>
+
+<acceptance_criteria>
+
+## Acceptance Criteria
+
+Each criterion uses BDD format. These are the contract between the spec and the verification phase. If all criteria pass, the implementation is correct.
+
+### AC-1: {{CRITERION_NAME}}
+
+**Given** {{PRECONDITION — system state before the action}}
+**When** {{ACTION — what the user or system does}}
+**Then** {{OUTCOME — observable result that proves it works}}
+
+### AC-2: {{CRITERION_NAME}}
+
+**Given** {{PRECONDITION}}
+**When** {{ACTION}}
+**Then** {{OUTCOME}}
+
+### AC-3: {{CRITERION_NAME}}
+
+**Given** {{PRECONDITION}}
+**When** {{ACTION}}
+**Then** {{OUTCOME}}
+
+</acceptance_criteria>
+
+<tasks>
+
+## Task List
+
+Each task is a discrete unit of work. Tasks are assigned to sub-agents during implementation. A task should be completable independently (given its dependencies are met).
+
+### T-001: {{TASK_NAME}}
+
+- **Files:** {{src/path/to/file.ts}}
+- **Action:** {{WHAT_TO_DO — specific, concrete, unambiguous}}
+- **Verify:** {{HOW_TO_CONFIRM_THIS_TASK_IS_DONE}}
+- **Done:** [ ]
+- **Dependencies:** none
+
+### T-002: {{TASK_NAME}}
+
+- **Files:** {{src/path/to/file.ts}}, {{src/path/to/other-file.ts}}
+- **Action:** {{WHAT_TO_DO}}
+- **Verify:** {{HOW_TO_CONFIRM}}
+- **Done:** [ ]
+- **Dependencies:** none
+
+### T-003: {{TASK_NAME}}
+
+- **Files:** {{src/path/to/file.ts}}
+- **Action:** {{WHAT_TO_DO}}
+- **Verify:** {{HOW_TO_CONFIRM}}
+- **Done:** [ ]
+- **Dependencies:** T-001, T-002
+
+### T-004: {{TASK_NAME}}
+
+- **Files:** {{src/path/to/file.ts}}
+- **Action:** {{WHAT_TO_DO}}
+- **Verify:** {{HOW_TO_CONFIRM}}
+- **Done:** [ ]
+- **Dependencies:** T-003
+
+### T-005: {{TASK_NAME}}
+
+- **Files:** {{tests/path/to/test-file.test.ts}}
+- **Action:** {{WHAT_TO_DO}}
+- **Verify:** {{HOW_TO_CONFIRM}}
+- **Done:** [ ]
+- **Dependencies:** T-003
+
+</tasks>
+
+<task_dependency_graph>
+
+## Task Dependency Graph
+
+```
+Group 1 (parallel):  T-001 ─┐
+                     T-002 ─┤
+                             │
+Group 2 (sequential): T-003 ◀┘
+                             │
+Group 3 (parallel):  T-004 ◀┤
+                     T-005 ◀┘
+```
+
+**Execution order:**
+1. T-001 and T-002 run in parallel (no dependencies)
+2. T-003 runs after both T-001 and T-002 complete
+3. T-004 and T-005 run in parallel after T-003 completes
+
+</task_dependency_graph>
+
+<boundaries>
+
+## DO NOT CHANGE
+
+These files and behaviors are explicitly out of scope. Do not modify them, do not refactor them, do not "improve" them. They are boundaries.
+
+- **{{src/path/to/untouchable-file.ts}}** — {{REASON_IT_IS_OFF_LIMITS}}
+- **{{DATABASE_SCHEMA}}** — {{REASON}}
+- **{{BEHAVIOR}}** — {{REASON}}
+
+If a task seems to require changing something listed here, STOP and escalate. Do not proceed.
+
+</boundaries>
+```
+
+---
+
+## Field Documentation
+
+### YAML Frontmatter
+
+**phase** — Which phase this spec belongs to. Must match a phase in ROADMAP.md.
+
+**plan** — Sequential plan number within the phase. Used for ordering and state tracking.
+
+**type** — Classification of the work:
+- `feature` — New functionality that did not exist before
+- `bugfix` — Fixing incorrect behavior in existing code
+- `refactor` — Restructuring code without changing behavior
+- `test` — Adding or improving tests without changing production code
+- `docs` — Documentation changes only
+
+**autonomous** — Whether `/sdlc:implement` can complete this spec without human intervention. Set to `false` if the spec requires human decisions during implementation.
+
+**task_graph** — Defines which tasks can run in parallel and which must wait for others. This drives sub-agent spawning in the implementation phase. Each `parallel_group` runs its tasks simultaneously. Groups with `depends_on` wait for the specified groups to complete first.
+
+**files_modified** — Complete list of files this spec will create or modify. Used for conflict detection when multiple specs might touch the same files.
+
+### Sections
+
+**objective** — The "elevator pitch" for this spec. Should be understandable by a non-developer. Goal is one sentence. Purpose explains why. Output describes the concrete deliverable.
+
+**context** — Everything a developer needs to understand before implementing. File references use `@` prefix to enable IDE/tool integration. Background fills in domain knowledge that is not obvious from the code.
+
+**clarifications** — Audit trail of the clarification-first approach. Every question asked and every recommendation given during spec creation is recorded here. This prevents the same questions from being re-asked if the spec is revisited.
+
+**acceptance_criteria** — The contract. BDD format (Given/When/Then) makes criteria testable and unambiguous. Each criterion gets a unique ID (AC-1, AC-2, etc.) for reference in verification results.
+
+**tasks** — Atomic units of work. Each task specifies exactly which files to touch, what to do, and how to verify the task is complete. Tasks are the unit of sub-agent assignment.
+
+**task_dependency_graph** — Visual representation of the task execution order. Makes it immediately clear which tasks can run in parallel and which must wait.
+
+**boundaries** — Explicit "do not touch" list. Prevents well-intentioned but out-of-scope changes. Anything not listed here is implicitly in scope if a task requires it.

package/src/templates/STATE.md

@@ -0,0 +1,106 @@
+# State Tracking Template
+
+This template defines the loop position tracker stored at `.sdlc/STATE.md`. It is the single source of truth for where the project is in the SDLC loop. Every command reads it. Every phase transition updates it. If this file is missing or corrupted, the loop cannot continue.
+
+---
+
+```markdown
+# SDLC State
+
+## Project Reference
+
+- **Project:** {{PROJECT_NAME}}
+- **Project file:** .sdlc/PROJECT.md
+- **Laws file:** .sdlc/LAWS.md
+- **Roadmap file:** .sdlc/ROADMAP.md
+
+## Current Position
+
+- **Milestone:** {{MILESTONE_NAME}} ({{MILESTONE_NUMBER}}/{{TOTAL_MILESTONES}})
+- **Phase:** {{PHASE_NAME}} (e.g., "Phase 1: Core Authentication")
+- **Plan:** {{PLAN_NUMBER}}/{{TOTAL_PLANS}} — {{PLAN_DESCRIPTION}}
+- **Status:** {{spec/implement/verify/review/close/blocked}}
+
+## Loop Position
+
+```
+  SPEC ──▶ IMPL ──▶ VERIFY ──▶ REVIEW ──▶ CLOSE
+  {{S}}      {{I}}     {{V}}      {{R}}      {{C}}
+```
+
+Legend: [x] = completed this loop | [ ] = not yet reached | [>] = currently here
+
+Example (currently implementing):
+```
+  SPEC ──▶ IMPL ──▶ VERIFY ──▶ REVIEW ──▶ CLOSE
+  [x]      [>]      [ ]       [ ]       [ ]
+```
+
+## Next Required Action
+
+> **CRITICAL: This field must ALWAYS be populated. An empty next action means the loop is broken.**
+
+**Action:** {{NEXT_ACTION}}
+**Command:** `{{SDLC_COMMAND}}`
+**Details:** {{WHAT_TO_DO_AND_WHY}}
+
+## Accumulated Context
+
+### Decisions Made
+
+| # | Decision | Rationale | Date | Phase |
+|---|----------|-----------|------|-------|
+| D-001 | {{DECISION}} | {{WHY}} | {{DATE}} | {{PHASE}} |
+
+### Deferred Issues
+
+| # | Issue | Reason Deferred | Revisit At |
+|---|-------|-----------------|------------|
+| DF-001 | {{ISSUE}} | {{WHY_NOT_NOW}} | {{MILESTONE_OR_PHASE}} |
+
+### Blockers
+
+| # | Blocker | Owner | Status | Since |
+|---|---------|-------|--------|-------|
+| B-001 | {{BLOCKER}} | {{WHO_CAN_RESOLVE}} | {{active/resolved}} | {{DATE}} |
+
+## Session Continuity
+
+- **Last session:** {{DATE_AND_TIME}}
+- **Stopped at:** {{WHAT_WAS_HAPPENING}}
+- **Next action:** {{SAME_AS_NEXT_REQUIRED_ACTION}}
+- **Resume file:** {{PATH_TO_HANDOFF_MD or "None"}}
+- **Handoff notes:** {{BRIEF_CONTEXT_FOR_NEXT_SESSION}}
+```
+
+---
+
+## Field Documentation
+
+### Current Position
+The exact coordinates of where the project is. Think of it as GPS for the development loop:
+- **Milestone** — The big goal (e.g., "MVP", "v1.0 Release")
+- **Phase** — A group of related work within a milestone
+- **Plan** — A single unit of work within a phase (one loop iteration)
+- **Status** — Which step of the loop this plan is in
+
+### Loop Position
+Visual indicator using checkmarks. There are exactly 5 states:
+- `[ ]` — Not reached yet
+- `[>]` — Currently here (only one at a time)
+- `[x]` — Completed for this loop iteration
+
+When a loop closes (CLOSE is `[x]`), all positions reset to `[ ]` for the next plan.
+
+### Next Required Action
+This is the most important field in the entire SDLC. It tells the developer (or the AI) exactly what to do next. Rules:
+- Must be a concrete, executable action ("Run /sdlc:implement", "Ask user about auth strategy")
+- Must include the command to run
+- Must never be empty, vague, or aspirational
+- If blocked, the action is "Resolve blocker B-XXX"
+
+### Accumulated Context
+Decisions, deferred issues, and blockers survive across loop iterations. They are the project's institutional memory. Without them, the same questions get asked repeatedly and the same mistakes get made.
+
+### Session Continuity
+When a developer stops working (end of day, context switch), this section captures exactly where to resume. The handoff file (HANDOFF.md) contains detailed notes; this section contains the summary.