sdlc-framework 1.0.0

package/src/rules/templates.md

@@ -0,0 +1,238 @@
+---
+paths:
+  - "src/templates/**/*.md"
+---
+
+# Template Rules
+
+Rules for editing files in `src/templates/`.
+
+## File Structure
+
+Template files have four sections in this order:
+
+1. **Header** — Markdown H1 with the template name
+2. **Introduction** — What the template produces and when to use it
+3. **Template Block** — The actual template content inside a fenced code block or XML tag
+4. **Field Documentation** — Description of every field in the template
+
+```markdown
+# Spec Template
+
+Produces a specification document for a single task or feature.
+Use during the SPEC phase after plan approval.
+
+<template>
+---
+id: {plan-id}-{sequence}-SPEC
+title: [Spec title — one line describing what is being specified]
+phase: {phase-id}
+status: draft
+created: {date}
+---
+
+## Requirements
+
+[List each functional requirement as a numbered item. Each requirement
+must be independently testable.]
+
+## Acceptance Criteria
+
+[Write acceptance criteria in Given/When/Then format. One criterion
+per requirement minimum.]
+
+## Technical Constraints
+
+[List architectural, performance, security, or compatibility constraints
+that bound the implementation.]
+
+## Out of Scope
+
+[Explicitly list what this spec does NOT cover. Prevents scope creep
+during implementation.]
+</template>
+
+## Field Documentation
+
+| Field | Format | Description |
+|-------|--------|-------------|
+| `id` | `{plan-id}-{sequence}-SPEC` | Auto-generated from plan ID and sequence number |
+| `title` | Free text | Human-readable summary of the spec's scope |
+| `phase` | `NN-kebab-name` | Phase ID from PLAN.md |
+| `status` | `draft`, `approved`, `implemented` | Lifecycle state of the spec |
+| `created` | `YYYY-MM-DD` | Date the spec was created |
+```
+
+## Placeholder Conventions
+
+### Square Brackets: `[Human-Fillable]`
+
+Use square brackets for fields that require human judgment or creative input. The text inside the brackets is an instruction, not a default value.
+
+```markdown
+[Spec title — one line describing what is being specified]
+[List each functional requirement as a numbered item]
+[Describe the expected behavior when the input is valid]
+```
+
+Rules:
+- The instruction inside brackets tells the author what to write, not how to format it.
+- Start with an imperative verb when the field requires generating content.
+- Include constraints in the instruction when the field has specific requirements.
+
+### Curly Braces: `{Variable}`
+
+Use curly braces for fields that are auto-populated from system state, arguments, or computed values. The text inside the braces names the data source.
+
+```markdown
+{plan-id}
+{date}
+{phase-id}
+{spec-id}
+{command-output}
+```
+
+Rules:
+- Variable names use `kebab-case`.
+- Each variable must be documented in the Field Documentation table.
+- Variables resolve at generation time — the template consumer fills them programmatically.
+
+### Mixing Placeholders
+
+A single field may combine both types:
+
+```markdown
+## {phase-id}: [Phase title describing the work]
+```
+
+The variable part is auto-populated; the bracketed part requires human input.
+
+## YAML Frontmatter in Templates
+
+When a template contains YAML frontmatter, that frontmatter is example content to be generated — it is NOT metadata about the template file itself. The template file's own metadata (if any) lives in a separate frontmatter block at the very top of the file before the H1 header.
+
+```markdown
+---
+paths:
+  - "src/templates/spec.md"
+---
+
+# Spec Template
+
+<template>
+---
+id: {plan-id}-{sequence}-SPEC
+title: [Spec title]
+---
+...
+</template>
+```
+
+The outer `---` block is file metadata (paths, tags). The inner `---` block inside `<template>` is the generated document's frontmatter.
+
+## Self-Documenting Fields
+
+Every field in the template must have a corresponding entry in the Field Documentation table. No undocumented fields.
+
+### Field Documentation Table Format
+
+| Column | Required | Description |
+|--------|----------|-------------|
+| Field | Yes | The field name as it appears in the template |
+| Format | Yes | Expected format, enum values, or data type |
+| Description | Yes | What the field represents and how to fill it |
+
+### Field Description Rules
+
+- State what the field represents, not just its type.
+- Include valid values or ranges for constrained fields.
+- Specify the data source for `{variable}` fields.
+- Include an example for complex or ambiguous fields.
+
+```markdown
+| Field | Format | Description |
+|-------|--------|-------------|
+| `id` | `{plan-id}-{sequence}-SPEC` | Computed from plan ID and spec sequence. Example: `01-03-SPEC` |
+| `title` | Free text, max 80 chars | One-line summary of the spec scope. Displayed in plan overviews |
+| `status` | `draft` / `approved` / `implemented` | Lifecycle state. Transitions: draft -> approved -> implemented |
+| `priority` | `critical` / `high` / `medium` / `low` | Implementation priority within the phase. Drives task ordering |
+```
+
+## Template Block Conventions
+
+### Use `<template>` Tags
+
+Wrap the actual template content in `<template>` tags. This separates the template from its documentation.
+
+```xml
+<template>
+(template content here)
+</template>
+```
+
+### Alternative: Fenced Code Blocks
+
+When the template content is short (under 20 lines) and contains no markdown that would conflict with the outer document, use a fenced code block with the `template` language hint:
+
+````markdown
+```template
+(template content here)
+```
+````
+
+Prefer `<template>` tags for longer or markdown-heavy templates.
+
+### Template Content Rules
+
+- Include all required sections with their placeholders.
+- Use markdown formatting inside the template as it will appear in the generated file.
+- Do not include instructions or commentary inside the template block — put those in Field Documentation.
+- Maintain consistent indentation within the template.
+
+## Section-Level Templates
+
+Some templates define section structures rather than full documents. These follow the same rules but wrap individual sections:
+
+```xml
+<template name="acceptance-criterion">
+### AC-{sequence}: [Criterion title]
+
+**Given** [precondition or initial state]
+**When** [action or trigger]
+**Then** [expected outcome or behavior]
+
+**Verification**: [How to test this criterion — command, assertion, or manual check]
+</template>
+```
+
+Name section templates with a `name` attribute on the `<template>` tag. The name uses `kebab-case`.
+
+## Composability
+
+Templates may reference other templates by name. Use `@templates/{name}.md` to indicate composition.
+
+```xml
+<template>
+## Acceptance Criteria
+
+For each requirement, generate one criterion using @templates/acceptance-criterion.md.
+</template>
+```
+
+The consuming workflow resolves the reference and inlines the sub-template at generation time.
+
+## Validation Checklist
+
+Before merging a template file, verify:
+
+- [ ] H1 header matches the template's purpose
+- [ ] Introduction explains what the template produces and when to use it
+- [ ] Template block wrapped in `<template>` tags or fenced code block
+- [ ] All `[square bracket]` placeholders contain actionable instructions
+- [ ] All `{curly brace}` variables use kebab-case and are documented
+- [ ] Field Documentation table covers every field in the template
+- [ ] YAML inside `<template>` is example frontmatter, not file metadata
+- [ ] No undocumented fields or placeholders
+- [ ] No instructions or commentary inside the template block
+- [ ] Imperative voice in all placeholder instructions
+- [ ] No filler words (see style.md)

package/src/rules/workflows.md

@@ -0,0 +1,314 @@
+---
+paths:
+  - "src/workflows/**/*.md"
+---
+
+# Workflow Rules
+
+Rules for editing files in `src/workflows/`.
+
+## File Structure
+
+Workflow files have NO YAML frontmatter. Start directly with the root XML element.
+
+```xml
+<workflow name="workflow-name">
+  <purpose>...</purpose>
+  <when_to_use>...</when_to_use>
+  <process>...</process>
+</workflow>
+```
+
+The root `<workflow>` element's `name` attribute must match the filename (minus extension) in kebab-case.
+
+## Section Order
+
+Sections appear inside `<workflow>` in this exact order. Do not reorder.
+
+### 1. `<purpose>` — REQUIRED
+
+One to three sentences. State what the workflow accomplishes and why it exists in the SDLC loop. Write for a developer who has never seen this framework.
+
+```xml
+<purpose>
+Create a specification document that anchors implementation, verification, and review.
+Specifications translate task descriptions into structured, testable requirements.
+Without a spec, downstream phases have no acceptance criteria to verify against.
+</purpose>
+```
+
+### 2. `<when_to_use>` — REQUIRED
+
+Declare the expected loop phase, the prior command that triggers this workflow, and the next command that follows. This grounds the workflow in the SDLC loop.
+
+```xml
+<when_to_use>
+Phase: SPEC
+Prior command: /sdlc:plan
+Next command: /sdlc:implement
+Trigger: Called by /sdlc:create-spec command after plan is approved.
+</when_to_use>
+```
+
+### 3. `<required_reading>` — OPTIONAL
+
+List files the workflow must read before executing. Use `@`-references. Include the reason each file is needed.
+
+```xml
+<required_reading>
+@references/engineering-laws.md — Enforce SOLID, DRY, YAGNI constraints on spec content
+@templates/spec.md — Structure for the output spec document
+@.sdlc/PLAN.md — Phase breakdown and task decomposition
+</required_reading>
+```
+
+### 4. `<loop_context>` — OPTIONAL
+
+Describe how this workflow interacts with the broader SDLC loop. Use when the workflow reads or writes shared state, or when its behavior changes based on loop phase.
+
+```xml
+<loop_context>
+Reads STATE.md to determine the active phase and plan ID.
+Writes the spec file path into STATE.md.current_artifacts.
+Sets STATE.md.next_required_action to /sdlc:implement on success.
+On failure, sets next_required_action to /sdlc:create-spec with error context.
+</loop_context>
+```
+
+### 5. `<process>` — REQUIRED
+
+The core logic. Contains ordered `<step>` elements. This is where all detailed implementation logic lives (commands delegate here).
+
+```xml
+<process>
+  <step name="validate_preconditions">
+    ...
+  </step>
+  <step name="gather_context">
+    ...
+  </step>
+  <step name="generate_output">
+    ...
+  </step>
+  <step name="update_state">
+    ...
+  </step>
+</process>
+```
+
+### 6. `<references>` — OPTIONAL
+
+List related workflows, commands, or external resources. Use when the workflow has dependencies or alternatives that contributors should know about.
+
+```xml
+<references>
+@workflows/spec-review.md — Called if spec requires peer review
+@workflows/plan-creation.md — Upstream workflow that produces the plan
+@commands/create-spec.md — Command that invokes this workflow
+</references>
+```
+
+## Step Element Rules
+
+### Naming
+
+Use `snake_case` for the `name` attribute. The name describes the action, not the outcome.
+
+```xml
+<!-- Correct -->
+<step name="validate_preconditions">
+<step name="read_existing_specs">
+<step name="write_spec_file">
+
+<!-- Wrong -->
+<step name="ValidatePreconditions">
+<step name="step-1">
+<step name="the_spec_is_written">
+```
+
+### Step Content
+
+Each step contains:
+
+1. **Why**: One sentence explaining why this step matters. Place it first. A junior developer reading the workflow must understand the purpose of each step without external context.
+2. **What**: Imperative instructions for what to do.
+3. **How** (optional): Implementation details, tool calls, or code patterns when the "what" is not self-evident.
+
+```xml
+<step name="validate_preconditions">
+STATE.md must confirm the loop is in SPEC phase — executing spec work in
+the wrong phase corrupts the loop state.
+
+Read @.sdlc/STATE.md.
+Verify current_phase equals "SPEC".
+Verify active_plan is not empty.
+
+If validation fails:
+  Report the mismatch to the user.
+  Do not proceed. Set next_required_action to the correct command for the current phase.
+</step>
+```
+
+### Step Constraints
+
+- Maximum 20 lines per step. If a step exceeds 20 lines, split it.
+- Maximum 12 steps per workflow. If more are needed, extract a sub-workflow.
+- Each step starts with a "why" sentence.
+- Use imperative voice for all instructions.
+
+## Loop Phase Awareness
+
+Every workflow operates within a specific SDLC loop phase. Declare the expected phase in `<when_to_use>` and validate it in the first process step.
+
+### SDLC Loop Phases
+
+| Phase | Purpose | Entry Command | Exit Command |
+|-------|---------|---------------|--------------|
+| SPEC | Define requirements | `/sdlc:create-spec` | `/sdlc:implement` |
+| IMPL | Build the solution | `/sdlc:implement` | `/sdlc:verify` |
+| VERIFY | Test and validate | `/sdlc:verify` | `/sdlc:review` |
+| REVIEW | Assess quality | `/sdlc:review` | `/sdlc:close` |
+| CLOSE | Finalize and commit | `/sdlc:close` | Loop complete |
+
+### Phase Validation Pattern
+
+Every workflow's first step must validate the current phase:
+
+```xml
+<step name="validate_phase">
+Running a workflow in the wrong phase produces artifacts that conflict with
+the loop's expected state progression.
+
+Read @.sdlc/STATE.md.
+Verify current_phase matches this workflow's expected phase.
+
+If phase mismatch:
+  Report: "Expected phase {expected}, found {actual}."
+  Set next_required_action to the correct command for the actual phase.
+  Halt execution.
+</step>
+```
+
+## STATE.md Updates
+
+Every workflow must update STATE.md before completing. The update includes:
+
+1. **Artifacts produced**: File paths added to `current_artifacts`.
+2. **Next required action**: The `/sdlc:` command the user or agent must run next.
+3. **Phase transition** (if applicable): Update `current_phase` when the workflow completes a phase.
+
+```xml
+<step name="update_state">
+STATE.md is the single source of truth for loop progress. Failing to update
+it breaks the deterministic command chain.
+
+Update @.sdlc/STATE.md:
+  Add output file path to current_artifacts.
+  Set next_required_action to /sdlc:implement.
+  Set last_completed_action to /sdlc:create-spec.
+</step>
+```
+
+## Conditional Logic Patterns
+
+Use plain-language conditionals inside steps. Do not use code syntax. Do not use nested conditionals — flatten with guard clauses.
+
+### Correct Pattern
+
+```xml
+<step name="check_existing_spec">
+Overwriting an existing spec without acknowledgment loses prior requirements work.
+
+Check if .sdlc/specs/{phase}/{spec-id}-SPEC.md exists.
+
+If the file exists and $ARGUMENTS does not include --force:
+  Report: "Spec already exists. Run with --force to overwrite."
+  Halt execution.
+
+If the file exists and $ARGUMENTS includes --force:
+  Back up existing file to .sdlc/specs/{phase}/{spec-id}-SPEC.md.bak.
+  Proceed to next step.
+
+If the file does not exist:
+  Proceed to next step.
+</step>
+```
+
+### Banned Patterns
+
+- Nested if/else blocks deeper than 2 levels.
+- Conditional logic that spans multiple steps (keep each condition self-contained).
+- Implicit fallthrough — every branch must have an explicit instruction.
+
+## Error Handling
+
+Every workflow must handle failure at each step. Define what happens when a step fails.
+
+### Error Handling Rules
+
+1. **Fail fast**: If a precondition fails, halt immediately. Do not attempt partial execution.
+2. **Report clearly**: State what failed, what was expected, and what the user should do.
+3. **Update state on failure**: Set `next_required_action` in STATE.md to the recovery command.
+4. **Never swallow errors**: Every failure path must produce visible output.
+
+### Error Handling Pattern
+
+```xml
+<step name="write_spec_file">
+The spec file is the primary deliverable. Write failures must be caught and
+reported — silent failures leave the loop in an inconsistent state.
+
+Write spec content to .sdlc/specs/{phase}/{spec-id}-SPEC.md.
+
+If write fails:
+  Report: "Failed to write spec file: {error}."
+  Do not update STATE.md artifacts.
+  Set next_required_action to /sdlc:create-spec (retry).
+  Halt execution.
+</step>
+```
+
+## Sub-Agent Delegation
+
+Workflows may delegate steps to sub-agents for parallel execution. When delegating:
+
+1. Define the sub-agent's task in a single imperative sentence.
+2. Specify the input the sub-agent receives.
+3. Specify the output the sub-agent must produce.
+4. Define the success criteria for the sub-agent's work.
+
+```xml
+<step name="delegate_implementation">
+Parallel implementation of independent modules reduces wall-clock time
+without sacrificing quality — each sub-agent works within its bounded context.
+
+For each independent module in the spec:
+  Spawn a sub-agent with:
+    Task: "Implement {module-name} per spec section {section-ref}."
+    Input: Spec section content, relevant source files.
+    Output: Implementation files, unit tests.
+    Success: All tests pass, no lint errors.
+
+Wait for all sub-agents to complete.
+Collect and validate outputs.
+</step>
+```
+
+## Validation Checklist
+
+Before merging a workflow file, verify:
+
+- [ ] No YAML frontmatter — file starts with `<workflow>`
+- [ ] `name` attribute on `<workflow>` matches filename
+- [ ] `<purpose>` and `<when_to_use>` present
+- [ ] `<process>` contains `<step>` elements with `snake_case` names
+- [ ] First step validates the expected loop phase
+- [ ] Last step updates STATE.md with next_required_action
+- [ ] Every step starts with a "why" sentence
+- [ ] No step exceeds 20 lines
+- [ ] No more than 12 steps total
+- [ ] All conditional branches have explicit instructions
+- [ ] All failure paths report errors and update state
+- [ ] All `@`-references point to files that exist
+- [ ] Imperative voice throughout
+- [ ] No filler words (see style.md)

package/src/templates/HANDOFF.md

@@ -0,0 +1,121 @@
+# Session Handoff Template
+
+This template defines the handoff document created when a developer stops working mid-loop. It is stored at `.sdlc/handoffs/HANDOFF-{{TIMESTAMP}}.md`. The handoff captures everything the next session (or the next developer) needs to continue without re-reading the entire codebase.
+
+---
+
+```markdown
+# Session Handoff
+
+## Metadata
+
+- **Timestamp:** {{YYYY-MM-DD HH:MM UTC}}
+- **Session duration:** {{APPROXIMATE_DURATION}}
+- **Handed off by:** {{DEVELOPER_OR_AI_AGENT}}
+
+## Current Position
+
+- **Milestone:** {{MILESTONE_NAME}} ({{N}}/{{TOTAL}})
+- **Phase:** {{PHASE_NAME}}
+- **Plan:** {{PLAN_NUMBER}}/{{TOTAL_PLANS}} — {{PLAN_DESCRIPTION}}
+- **Loop step:** {{spec/implement/verify/review/close}}
+- **Spec file:** {{SPEC_FILE_PATH or "Not yet created"}}
+- **State file:** .sdlc/STATE.md
+
+## Work Completed This Session
+
+### Completed Items
+
+1. {{WHAT_WAS_DONE — specific, verifiable}}
+2. {{WHAT_WAS_DONE}}
+3. {{WHAT_WAS_DONE}}
+
+### Files Created or Modified
+
+| File | Change | Status |
+|------|--------|--------|
+| {{FILE_PATH}} | {{WHAT_CHANGED}} | {{complete/partial}} |
+
+## In-Progress Items
+
+Items that were started but not finished. These are the immediate priorities for the next session.
+
+| # | Item | Current State | Remaining Work |
+|---|------|---------------|----------------|
+| IP-001 | {{WHAT_IS_IN_PROGRESS}} | {{WHERE_IT_STANDS}} | {{WHAT_IS_LEFT_TO_DO}} |
+
+## Decisions Made
+
+Decisions made during this session that affect future work:
+
+| # | Decision | Context | Impact |
+|---|----------|---------|--------|
+| D-001 | {{WHAT_WAS_DECIDED}} | {{WHY}} | {{HOW_IT_AFFECTS_NEXT_STEPS}} |
+
+## Blockers
+
+Issues that prevent progress:
+
+| # | Blocker | Impact | Suggested Resolution |
+|---|---------|--------|----------------------|
+| B-001 | {{WHAT_IS_BLOCKING}} | {{WHAT_CANNOT_PROCEED}} | {{HOW_TO_RESOLVE}} |
+
+If no blockers: "No blockers."
+
+## Next Action Required
+
+> **This is the single most important field. It tells the next session exactly what to do first.**
+
+**Action:** {{CONCRETE_NEXT_STEP}}
+**Command:** `{{SDLC_COMMAND_TO_RUN}}`
+**Context:** {{WHY_THIS_IS_THE_NEXT_STEP_AND_WHAT_TO_WATCH_FOR}}
+
+## Files to Review on Resume
+
+Files that the next session should read before doing anything else, in priority order:
+
+1. **{{FILE_PATH}}** — {{WHY_TO_READ_THIS_FIRST}}
+2. **{{FILE_PATH}}** — {{WHY}}
+3. **{{FILE_PATH}}** — {{WHY}}
+
+## Notes
+
+{{ANY_ADDITIONAL_CONTEXT — gotchas, things that almost went wrong, observations about the codebase that are not captured elsewhere}}
+```
+
+---
+
+## Field Documentation
+
+### Metadata
+When the handoff happened and how long the session lasted. Duration helps estimate velocity for future planning.
+
+### Current Position
+Copied from STATE.md for convenience. The next session should not have to open STATE.md to know where things stand — the handoff is self-contained.
+
+### Work Completed This Session
+Specific, verifiable items. Not "worked on authentication" but "implemented JWT token generation in src/auth/token.service.ts, including refresh token rotation." The next session needs to know what is done so they do not redo it.
+
+### In-Progress Items
+The critical section. These are tasks that were started but not finished. Each entry must include:
+- What the item is
+- Where it currently stands (e.g., "function skeleton written, business logic not yet implemented")
+- What remains (e.g., "add validation for edge cases, write unit tests")
+
+### Decisions Made
+Decisions that occurred outside of the spec's clarification phase. These must be recorded because they are not in any spec file. Without this record, the next session may make a conflicting decision.
+
+### Blockers
+Anything preventing progress. Each blocker must have a suggested resolution. If the blocker requires human input, say so explicitly.
+
+### Next Action Required
+This is the handoff's reason for existing. A clear, unambiguous next step. The developer opening this file should be able to start working within 2 minutes of reading it.
+
+### Files to Review on Resume
+Ordered by importance. The first file is the one that provides the most context for the next action. Usually this is the spec file or the file currently being implemented. Limit to 3-5 files — more than that and the developer loses focus.
+
+### Notes
+Free-form section for anything that does not fit elsewhere. Common entries:
+- "The database migration must run before the service starts"
+- "Test suite takes 45 seconds — use --grep to run specific tests"
+- "The API returns 500 instead of 422 for invalid input — known issue, not in scope"