sdlc-framework 1.0.0

package/src/rules/commands.md

@@ -0,0 +1,180 @@
+---
+paths:
+  - "src/commands/**/*.md"
+---
+
+# Command Rules
+
+Rules for editing files in `src/commands/`.
+
+## File Structure
+
+YAML frontmatter is required at the top of every command file.
+
+```yaml
+---
+name: sdlc:command-name
+description: One-line description of what the command does
+argument-hint: "<required>" or "[optional]"
+allowed-tools: [Read, Write, Bash, Glob, Grep, Edit, AskUserQuestion]
+---
+```
+
+### Frontmatter Field Rules
+
+| Field | Required | Format | Notes |
+|-------|----------|--------|-------|
+| `name` | Yes | `sdlc:kebab-case` | Must match filename without extension |
+| `description` | Yes | Single sentence, imperative voice | No period at end |
+| `argument-hint` | Yes | `<angle>` = required, `[square]` = optional | Describe the argument semantically |
+| `allowed-tools` | Yes | Array of tool names | Minimum set needed — no extras |
+
+## Section Order
+
+Every command file contains these sections in this exact order. Do not reorder. Do not skip required sections.
+
+### 1. `<objective>` — REQUIRED
+
+Explain what the command does, when to use it, and what happens after it completes. Write for a developer encountering this framework for the first time. Three components:
+
+- **What**: One sentence stating the action performed.
+- **Why**: One sentence explaining the purpose within the SDLC loop.
+- **When**: One sentence describing the trigger condition (prior command output, user decision, or entry point).
+
+```xml
+<objective>
+What: Create a specification document from a task description.
+Why: Specifications anchor all downstream implementation, verification, and review work.
+When: Run after `/sdlc:plan` completes or when starting a new task.
+</objective>
+```
+
+### 2. `<execution_context>` — REQUIRED
+
+List static resources from the sdlc-framework that the command needs. Use `@`-references to workflows, templates, and references. Do not reference project-specific files here.
+
+```xml
+<execution_context>
+@workflows/spec-creation.md
+@templates/spec.md
+@references/engineering-laws.md
+</execution_context>
+```
+
+### 3. `<context>` — REQUIRED
+
+Declare dynamic content: user arguments, bash output blocks, and `@`-references to `.sdlc/` project state files.
+
+```xml
+<context>
+$ARGUMENTS — Task description provided by the user
+@.sdlc/STATE.md — Current loop state and phase
+@.sdlc/PLAN.md — Active plan with phase breakdown
+
+<bash>
+# Gather project structure for context
+find src/ -type f -name "*.ts" | head -50
+</bash>
+</context>
+```
+
+Rules for `<context>`:
+- `$ARGUMENTS` is the raw user input passed to the command.
+- Bash blocks gather ephemeral project state. Keep them minimal and fast.
+- `@.sdlc/` references pull in persisted loop state.
+
+### 4. `<process>` — REQUIRED
+
+Implementation steps. Commands are thin — delegate detailed logic to workflows. Each step is a short imperative instruction, not a paragraph.
+
+```xml
+<process>
+1. Read STATE.md to confirm current phase permits this command.
+2. Execute @workflows/spec-creation.md with $ARGUMENTS as input.
+3. Write output to .sdlc/specs/{phase}/{spec-id}-SPEC.md using @templates/spec.md.
+4. Update STATE.md with new spec reference and next_required_action.
+</process>
+```
+
+Rules for `<process>`:
+- Maximum 8 steps. If more are needed, the workflow is doing too little.
+- Each step starts with an imperative verb: Read, Write, Execute, Validate, Update.
+- Reference workflows by `@`-path, not by inlining their logic.
+- Never put conditional branching in commands. Move it to the workflow.
+
+### 5. `<success_criteria>` — REQUIRED
+
+Measurable checklist. Every item is a verifiable statement, not a vague aspiration.
+
+```xml
+<success_criteria>
+- [ ] Spec file exists at .sdlc/specs/{phase}/{spec-id}-SPEC.md
+- [ ] Spec contains all required sections from @templates/spec.md
+- [ ] STATE.md updated with spec reference
+- [ ] Output ends with NEXT ACTION REQUIRED: /sdlc:implement
+</success_criteria>
+```
+
+**Mandatory final item**: `Output ends with NEXT ACTION REQUIRED: /sdlc:{next-command}`. Every command must force the next action. No command is terminal except `/sdlc:close`.
+
+## Core Principles
+
+### Commands Are Thin Wrappers
+
+A command file orchestrates — it does not contain business logic. If a command's `<process>` section exceeds 8 steps or contains conditional branches, extract the complexity into a workflow.
+
+### Commands Force Next Action
+
+The SDLC loop is deterministic. Every command output ends with `NEXT ACTION REQUIRED: /sdlc:{next-command}`. The user or agent must execute the specified command next. No ambiguity. No optional follow-ups.
+
+### Commands Are Self-Explanatory
+
+The `<objective>` section is the command's documentation. A developer reading it for the first time understands what the command does, why it exists, and what triggers it. No external documentation needed.
+
+### Commands Are Idempotent Where Possible
+
+Running the same command twice with the same input produces the same output. If idempotency is impossible (e.g., the command modifies external state), document the non-idempotent behavior in `<objective>`.
+
+## @-Reference Patterns
+
+### Static Resources (execution_context)
+
+Reference framework-internal files that do not change per project:
+
+```
+@workflows/{workflow-name}.md
+@templates/{template-name}.md
+@references/{reference-name}.md
+```
+
+### Dynamic Project State (context)
+
+Reference project-specific files that change during the SDLC loop:
+
+```
+@.sdlc/STATE.md
+@.sdlc/PLAN.md
+@.sdlc/specs/{phase}/{spec-id}-SPEC.md
+@.sdlc/reviews/{review-id}.md
+```
+
+## Naming
+
+- Command files: `kebab-case.md` (e.g., `create-spec.md`)
+- Command names: `sdlc:kebab-case` (e.g., `sdlc:create-spec`)
+- The filename (minus extension) must match the name after `sdlc:` in frontmatter.
+
+## Validation Checklist
+
+Before merging a command file, verify:
+
+- [ ] YAML frontmatter has all required fields
+- [ ] All 5 sections present in correct order
+- [ ] `<objective>` answers what/why/when
+- [ ] `<process>` has 8 or fewer steps
+- [ ] `<process>` delegates to at least one workflow
+- [ ] `<success_criteria>` ends with NEXT ACTION REQUIRED
+- [ ] All `@`-references point to files that exist
+- [ ] No inline business logic — all logic lives in workflows
+- [ ] Imperative voice throughout — no passive constructions
+- [ ] No filler words (see style.md)

package/src/rules/style.md

@@ -0,0 +1,354 @@
+---
+paths:
+  - "src/**/*.md"
+---
+
+# Style Rules
+
+Universal style rules for ALL files in the SDLC framework. Every contributor must follow these rules in every file under `src/`.
+
+## Voice and Tone
+
+### Imperative Voice — REQUIRED
+
+Write all instructions as direct commands. The subject is always the reader or the system.
+
+```markdown
+<!-- Correct -->
+Execute the test suite before marking verification complete.
+Read STATE.md to determine the current phase.
+Validate all acceptance criteria against the spec.
+
+<!-- Wrong -->
+The test suite should be executed before verification is complete.
+STATE.md is read to determine the current phase.
+Acceptance criteria are validated against the spec.
+```
+
+### Banned Filler Words
+
+These words add no information. Remove them on sight.
+
+| Banned | Replacement |
+|--------|-------------|
+| "Let me" | Remove — start with the verb |
+| "Just" | Remove — the action stands alone |
+| "Simply" | Remove — nothing is simple to everyone |
+| "Please" | Remove — these are instructions, not requests |
+| "Note that" | Remove — state the fact directly |
+| "It should be noted" | Remove — state the fact directly |
+| "Basically" | Remove — explain fully or not at all |
+| "In order to" | "To" |
+| "Make sure to" | Remove — start with the verb |
+| "Go ahead and" | Remove — start with the verb |
+
+### Banned Sycophancy
+
+These words signal empty enthusiasm. Remove them on sight.
+
+| Banned | Context |
+|--------|---------|
+| "Great!" | Never use as a response opener or transition |
+| "Awesome!" | Never use as a response opener or transition |
+| "Excellent!" | Never use as a response opener or transition |
+| "Perfect!" | Never use as a response opener or transition |
+| "Wonderful!" | Never use as a response opener or transition |
+| "Amazing!" | Never use as a response opener or transition |
+| "Good job!" | Never use as feedback in framework content |
+| "Well done!" | Never use as feedback in framework content |
+
+### Banned Temporal Language
+
+Describe the current state. Do not reference past actions or future intentions.
+
+```markdown
+<!-- Correct -->
+STATE.md contains the current phase and next required action.
+
+<!-- Wrong -->
+STATE.md will contain the current phase after you run the command.
+STATE.md now contains the current phase since we updated it.
+After running the command, STATE.md has been updated with the phase.
+```
+
+Exception: Workflow steps that describe sequential operations use "after" and "before" to indicate ordering, not past/future tense.
+
+```markdown
+<!-- Acceptable in workflow steps -->
+After validation completes, write the spec file.
+Before updating STATE.md, verify the file was written.
+```
+
+## Naming Conventions
+
+| Entity | Convention | Example |
+|--------|-----------|---------|
+| Files | `kebab-case.md` | `spec-creation.md` |
+| Commands | `sdlc:kebab-case` | `sdlc:create-spec` |
+| Workflow names | `kebab-case` | `spec-creation` |
+| Step names | `snake_case` | `validate_preconditions` |
+| Phase IDs | `NN-kebab-name` | `01-authentication` |
+| Spec IDs | `NN-NN-SPEC.md` | `01-03-SPEC.md` |
+| Plan IDs | `NN-PLAN.md` | `01-PLAN.md` |
+| Template names | `kebab-case` | `acceptance-criterion` |
+| Variable placeholders | `{kebab-case}` | `{plan-id}` |
+| Human placeholders | `[Sentence case instruction]` | `[Describe the expected behavior]` |
+
+### File Naming Rules
+
+- All framework source files use `.md` extension.
+- Filenames match the primary entity name (command name, workflow name, template name).
+- No spaces. No underscores. No camelCase. Kebab-case only.
+- State files in `.sdlc/` use UPPER_CASE: `STATE.md`, `PLAN.md`.
+
+## XML Conventions
+
+### Semantic Tags
+
+Use XML tags that describe content semantics, not presentation.
+
+```xml
+<!-- Correct -->
+<objective>
+<process>
+<step name="validate_input">
+<success_criteria>
+<template>
+
+<!-- Wrong -->
+<section>
+<div>
+<block>
+<content>
+```
+
+### Tag Naming
+
+- Tags use `snake_case` (matching step naming convention).
+- Tags describe what the content IS, not where it goes.
+- Avoid generic tags. Each tag name should be unique in purpose.
+
+### Hierarchy
+
+Use XML tags for top-level structure. Use markdown headers for hierarchy within XML sections.
+
+```xml
+<process>
+  <step name="implement_module">
+    ## Module Structure
+
+    Create the following files:
+
+    ### Service Layer
+    Write the service file at src/services/{module}.service.ts.
+
+    ### Controller Layer
+    Write the controller at src/controllers/{module}.controller.ts.
+  </step>
+</process>
+```
+
+### Attributes
+
+- Use attributes for metadata: `name`, `type`, `phase`.
+- Use element content for instructions and descriptions.
+- Attribute values use `kebab-case` or `snake_case` depending on the entity convention.
+
+## @-Reference Patterns
+
+### Framework References
+
+Reference framework-internal files with paths relative to `src/`:
+
+```
+@workflows/spec-creation.md
+@templates/spec.md
+@references/engineering-laws.md
+@commands/create-spec.md
+```
+
+### Project State References
+
+Reference project-specific files with paths relative to the project root:
+
+```
+@.sdlc/STATE.md
+@.sdlc/PLAN.md
+@.sdlc/specs/01-auth/01-03-SPEC.md
+```
+
+### Reference Rules
+
+- Every `@`-reference must point to a file that exists or will exist at execution time.
+- Use `@`-references instead of prose descriptions. "Read @.sdlc/STATE.md" is better than "Read the state file."
+- Do not use `@`-references for conceptual references. Use plain text: "See the engineering laws for constraint details."
+
+## Loop Terminology
+
+Use these terms consistently. Do not invent synonyms.
+
+| Term | Meaning | Usage |
+|------|---------|-------|
+| SPEC | Specification phase | "Run during SPEC phase" |
+| IMPL | Implementation phase | "Transition to IMPL after spec approval" |
+| VERIFY | Verification phase | "VERIFY phase runs all tests" |
+| REVIEW | Review phase | "REVIEW phase assesses code quality" |
+| CLOSE | Closing phase | "CLOSE phase commits and finalizes" |
+| Loop | One full SPEC-IMPL-VERIFY-REVIEW-CLOSE cycle | "Complete the loop for each plan" |
+| Phase | One stage within the loop | "Current phase: IMPL" |
+| Plan | A decomposed task with phases | "Plan 01 has 4 phases" |
+| Spec | A specification document | "Spec 01-03 covers authentication" |
+| Artifact | Any file produced during the loop | "Add artifact path to STATE.md" |
+
+### Banned Synonyms
+
+| Banned | Use Instead |
+|--------|-------------|
+| "Stage" | "Phase" |
+| "Step" (for loop phases) | "Phase" (steps are within workflows) |
+| "Task" (for loop phases) | "Phase" |
+| "Cycle" | "Loop" |
+| "Document" (for specs) | "Spec" |
+| "Deliverable" | "Artifact" |
+
+## Acceptance Criteria Format
+
+All acceptance criteria use BDD Given/When/Then format.
+
+```markdown
+### AC-{sequence}: [Criterion title]
+
+**Given** [precondition — describe the initial state]
+**When** [action — describe the trigger or user action]
+**Then** [outcome — describe the expected observable result]
+```
+
+### Rules
+
+- One acceptance criterion per testable behavior.
+- "Given" describes state, not actions. No verbs in "Given".
+- "When" describes exactly one action.
+- "Then" describes an observable, verifiable outcome.
+- Do not combine multiple behaviors into one criterion.
+
+```markdown
+<!-- Correct -->
+### AC-01: Authenticated user accesses dashboard
+
+**Given** a user with valid session credentials
+**When** the user requests the dashboard endpoint
+**Then** the system returns the dashboard view with user-specific data
+
+<!-- Wrong — multiple behaviors in one criterion -->
+### AC-01: User login and dashboard
+
+**Given** a user exists in the database
+**When** the user logs in and navigates to the dashboard
+**Then** the session is created and the dashboard shows their data
+```
+
+## Commit Message Format
+
+```
+{type}({phase}-{plan}): {description}
+```
+
+### Components
+
+| Component | Values | Example |
+|-----------|--------|---------|
+| `type` | `spec`, `impl`, `verify`, `review`, `fix`, `refactor`, `docs` | `spec` |
+| `phase` | Phase ID from plan | `01-auth` |
+| `plan` | Plan number | `01` |
+| `description` | Imperative, max 72 chars | `add JWT validation to auth guard` |
+
+### Examples
+
+```
+spec(01-auth-01): define authentication requirements
+impl(01-auth-01): add JWT validation to auth guard
+verify(01-auth-01): add integration tests for auth flow
+review(01-auth-01): address review feedback on token expiry
+fix(01-auth-01): handle expired refresh token edge case
+```
+
+### Commit Message Rules
+
+- Description uses imperative voice: "add", "fix", "update" — not "added", "fixes", "updates".
+- Max 72 characters for the entire first line.
+- No period at the end of the description.
+- Body (optional, separated by blank line) explains WHY, not WHAT.
+
+## Next Action Enforcement
+
+Every command output, workflow completion, and agent response must end with:
+
+```
+NEXT ACTION REQUIRED: /sdlc:{command-name}
+```
+
+### Rules
+
+- The next action is always a specific `/sdlc:` command — never a vague instruction.
+- The next action is deterministic. Given the same state, the same next action is always required.
+- Only `/sdlc:close` has no next action (it terminates the loop).
+- Do not suggest multiple possible next actions. One command. No ambiguity.
+
+```markdown
+<!-- Correct -->
+NEXT ACTION REQUIRED: /sdlc:implement
+
+<!-- Wrong -->
+Next steps: You could run /sdlc:implement or /sdlc:verify depending on your needs.
+Consider running /sdlc:implement next.
+```
+
+## Formatting Rules
+
+### Headers
+
+- Use markdown headers (`#`, `##`, `###`) for document structure outside XML.
+- Use headers inside XML steps for sub-structure within a step.
+- Do not skip header levels (no `#` followed by `###`).
+
+### Lists
+
+- Use numbered lists for ordered sequences (steps, priorities).
+- Use bullet lists for unordered collections (requirements, constraints).
+- Do not nest lists deeper than 2 levels.
+
+### Tables
+
+- Use tables for structured data with 3+ columns.
+- Always include a header row.
+- Align columns for readability in source.
+
+### Code Blocks
+
+- Use fenced code blocks with language hints for all code.
+- Use `yaml`, `xml`, `markdown`, `bash`, `typescript` as language hints.
+- Do not use indented code blocks (4 spaces) — always use fences.
+
+### Line Length
+
+- Prose lines: wrap at 100 characters for readability in source.
+- Code blocks: no hard wrap — let the content determine length.
+- Tables: no hard wrap — readability in rendered form takes priority.
+
+## Validation Checklist
+
+Before merging any framework file, verify:
+
+- [ ] Imperative voice throughout — no passive constructions
+- [ ] No banned filler words
+- [ ] No banned sycophancy
+- [ ] No temporal language (except sequential ordering in workflow steps)
+- [ ] All names follow the naming convention table
+- [ ] All `@`-references use correct path format
+- [ ] Loop terminology uses standard terms, not synonyms
+- [ ] Acceptance criteria use Given/When/Then format
+- [ ] File ends with NEXT ACTION REQUIRED (for commands and workflows)
+- [ ] Commit messages follow `{type}({phase}-{plan}): {description}` format
+- [ ] No headers skipped
+- [ ] No lists nested deeper than 2 levels
+- [ ] Code blocks use fenced format with language hints