sdlc-framework 1.0.0

package/src/workflows/hotfix-flow.md

@@ -0,0 +1,190 @@
+<purpose>Emergency fix workflow for critical production issues. Skips spec ceremony but enforces full verification and review. Tracked as a decimal sub-phase (e.g., 02.1) to maintain audit trail without disrupting the main phase sequence.</purpose>
+<when_to_use>Use ONLY for critical issues: production down, data corruption, security vulnerability, blocking bug affecting users NOW. For non-critical bugs, use /sdlc:debug instead.</when_to_use>
+<required_reading>.sdlc/STATE.md, .sdlc/PROJECT.md, .sdlc/LAWS.md</required_reading>
+<loop_context>
+  expected_phase: HOTFIX (emergency, interrupts main loop)
+  prior_phase: any (hotfix can interrupt at any point)
+  next_phase: VERIFY (hotfix still goes through verify and review)
+</loop_context>
+<process>
+
+<step name="accept_critical_issue" priority="first">
+  Receive the critical issue description.
+
+  Ask the user:
+  Question 1: "What is broken? (specific symptom)"
+  Question 2: "What is the impact? (who is affected, how badly)"
+  Question 3: "When did it start? (recent deploy, config change, external event)"
+
+  CLASSIFY SEVERITY:
+  - P0 (system down): entire service or critical path is unavailable
+  - P1 (data risk): data corruption, security breach, or data loss occurring
+  - P2 (major feature broken): core feature broken but system is up
+
+  IF severity is not P0 or P1: Display: "This does not appear critical. Consider using /sdlc:debug for structured debugging or /sdlc:fast for a quick fix."
+  Let the user override if they insist.
+
+  Save the current STATE.md position — hotfix must restore it when done.
+
+  WHY: Hotfix workflow trades ceremony for speed. That trade-off is only justified for critical issues. Overusing hotfix leads to unreviewed, untested changes accumulating.
+</step>
+
+<step name="create_inline_spec" priority="second">
+  Create a lightweight inline spec (no file — kept in memory for speed).
+
+  Inline spec:
+  ```
+  Hotfix: {title}
+  Severity: {P0|P1|P2}
+  Symptom: {what is broken}
+  Expected: {what should happen}
+  Files likely affected: {from initial analysis}
+  Acceptance criteria:
+    AC-1: GIVEN the fix is deployed WHEN {trigger action} THEN {correct behavior}
+    AC-2: GIVEN the fix is deployed WHEN regression tests run THEN all pass
+  Boundary: fix ONLY the critical issue. No refactoring. No cleanup. No "while I am here" changes.
+  ```
+
+  Display the inline spec to the user. Do NOT wait for approval — in an emergency, speed matters. But DO display it so the user can object if the scope is wrong.
+
+  WHY: Even emergencies get a spec — just a minimal one. Without it, the fix scope creeps and the hotfix becomes a feature.
+</step>
+
+<step name="fix_directly" priority="third">
+  Fix the issue directly. No sub-agents — hotfix is single-threaded for speed and control.
+
+  PROCESS:
+  1. Read the relevant files identified in the inline spec
+  2. If root cause is not immediately obvious, use binary search isolation (same as debug-flow)
+  3. Apply the MINIMAL fix — change as few lines as possible
+  4. Do NOT refactor. Do NOT clean up. Do NOT improve. Fix the bug ONLY.
+  5. Add a regression test for the specific failure scenario
+  6. Run the regression test — it must pass
+
+  RULES FOR HOTFIX CODE:
+  - Engineering laws still apply (no empty catch blocks, no hardcoded secrets)
+  - But scope is strictly limited to the fix
+  - Mark any technical debt created by the minimal fix with a TODO comment:
+    "TODO(hotfix-{date}): Clean up in next regular loop"
+  - These TODOs become tasks in the next spec
+
+  Record:
+  ```
+  Files modified: {list}
+  Lines changed: {count}
+  Root cause: {brief explanation}
+  Technical debt introduced: {yes/no — if yes, describe}
+  ```
+
+  WHY: Hotfixes are surgical. Minimal changes minimize risk of introducing new bugs. The TODO ensures debt is tracked and addressed, not forgotten.
+</step>
+
+<step name="full_verification" priority="fourth">
+  Run the SAME verification as verify-phase. No shortcuts.
+
+  FOR EACH AC in the inline spec:
+  1. Execute the verification (Playwright for UI, curl for API, test suite for logic)
+  2. Record PASS or FAIL with evidence
+
+  Additionally:
+  - Run the FULL test suite (not just related tests)
+  - A hotfix that breaks something else is worse than the original bug
+
+  IF ANY VERIFICATION FAILS:
+    Display: "Hotfix verification failed: {details}. The fix is incomplete or introduced a regression."
+    Return to fix step.
+
+  IF ALL PASS:
+    Proceed to review.
+
+  WHY: Hotfixes are the riskiest changes — rushed, minimal context, high pressure. Full verification is non-negotiable precisely because the process is compressed.
+</step>
+
+<step name="full_review" priority="fifth">
+  Run the SAME review as review-phase. No shortcuts.
+
+  Check all modified files against engineering laws.
+
+  The review is likely to find:
+  - WARN: minimal fix may not follow ideal patterns (acceptable for hotfix)
+  - INFO: TODO comments for technical debt (expected)
+
+  BUT BLOCKERS STILL BLOCK:
+  - Hardcoded secrets: BLOCKER (no exceptions, not even in emergencies)
+  - Empty catch blocks: BLOCKER
+  - SQL injection: BLOCKER
+
+  IF BLOCKERS: Fix them. Even in an emergency, security and error handling are non-negotiable.
+  IF CLEAN or WARNINGS ONLY: Proceed.
+
+  WHY: Security violations in hotfixes are especially dangerous because hotfixes often get deployed without the usual deployment review.
+</step>
+
+<step name="record_and_update_state" priority="sixth">
+  Create the hotfix record.
+
+  Determine the hotfix number:
+  - Read current phase number (e.g., "02")
+  - Count existing hotfixes: look for HOTFIX-*.md in the phase directory
+  - Hotfix number = {phase}.{hotfix-count + 1} (e.g., "02.1", "02.2")
+
+  Create .sdlc/phases/{current_phase}/HOTFIX-{number}-SUMMARY.md:
+  ```markdown
+  # Hotfix {number}: {title}
+
+  ## Issue
+  - **Severity**: {P0|P1|P2}
+  - **Symptom**: {what was broken}
+  - **Impact**: {who was affected}
+  - **Duration**: {how long the issue lasted, if known}
+
+  ## Root Cause
+  {Brief explanation}
+
+  ## Fix
+  - **Files modified**: {list}
+  - **Approach**: {what was changed}
+  - **Lines changed**: {count}
+
+  ## Verification
+  | AC | Status | Evidence |
+  |----|--------|----------|
+  | AC-1 | PASS | {evidence} |
+  | AC-2 | PASS | {evidence} |
+
+  ## Technical Debt
+  - {TODO items introduced by the minimal fix}
+  - These should be addressed in the next regular /sdlc:spec loop
+
+  ## Review
+  - Blockers: 0
+  - Warnings: {count}
+  ```
+
+  Update .sdlc/STATE.md:
+  - RESTORE the prior state (hotfix does not advance the main loop)
+  - Add history entry: "{timestamp} | hotfix | {severity}: {title}. {N} files modified. Debt: {yes/no}."
+
+  Update .sdlc/ROADMAP.md:
+  - Add a note under the current phase: "Hotfix {number}: {title} ({date})"
+
+  Display:
+  ```
+  Hotfix applied and verified.
+
+  Hotfix: {number}
+  Severity: {severity}
+  Files modified: {N}
+  Verification: PASSED
+  Review: PASSED ({N} warnings)
+  Technical debt: {description or "none"}
+
+  Record: .sdlc/phases/{phase}/HOTFIX-{number}-SUMMARY.md
+
+  State restored. Continue with: {prior next_required_action}
+  ```
+
+  WHY: Hotfixes are recorded separately from regular plans so they do not disrupt the plan numbering. The decimal notation (02.1) makes it clear this was an emergency intervention, not planned work.
+</step>
+
+</process>

package/src/workflows/impl-phase.md

@@ -0,0 +1,229 @@
+<purpose>Execute the specification through sub-agent driven parallel implementation. Each task from the spec becomes an independent agent with full context, engineering laws, and boundaries. Tasks run in dependency-ordered waves.</purpose>
+<when_to_use>Run after /sdlc:spec completes. STATE.md must show loop_position = SPEC ✓ and next_required_action = /sdlc:impl.</when_to_use>
+<required_reading>.sdlc/STATE.md, the current SPEC.md, .sdlc/LAWS.md, .sdlc/PROJECT.md</required_reading>
+<loop_context>
+  expected_phase: IMPL (active)
+  prior_phase: SPEC ✓
+  next_phase: VERIFY
+</loop_context>
+<process>
+
+<step name="validate_state" priority="first">
+  Read .sdlc/STATE.md.
+
+  CHECK: loop_position must be "SPEC ✓"
+  CHECK: next_required_action must be "/sdlc:impl"
+
+  IF EITHER CHECK FAILS: STOP. Display: "Cannot start implementation. State requires: {next_required_action}. Run that first."
+
+  Extract from STATE.md:
+  - current_phase (e.g., "01-setup")
+  - current_plan (e.g., "01")
+
+  WHY: Running impl without a spec means building without a blueprint. The code will not match requirements, verification will fail, and the loop breaks.
+</step>
+
+<step name="load_spec" priority="second">
+  Construct the spec path: .sdlc/phases/{current_phase}/{current_plan}-SPEC.md
+
+  Read the SPEC.md file. Parse:
+
+  FROM YAML FRONTMATTER:
+  - task_graph.parallel_groups → array of arrays (wave structure)
+  - task_graph.dependencies → map of task → [dependency tasks]
+  - files_modified → list (may be empty, will be populated during impl)
+  - files_created → list (may be empty, will be populated during impl)
+
+  FROM MARKDOWN BODY:
+  - Each task: name, action, files, verification, done criteria, complexity
+  - Acceptance criteria (for context — verify phase handles these)
+  - Boundaries (CRITICAL — pass to every agent)
+  - Required patterns (CRITICAL — pass to every agent)
+
+  IF THE SPEC IS MISSING OR MALFORMED: STOP. Display: "Spec file not found or invalid: {path}. Run /sdlc:spec to create it."
+
+  WHY: The spec is the contract. Every agent works from this contract. If the contract is wrong, all work is wrong.
+</step>
+
+<step name="load_engineering_laws" priority="third">
+  Read .sdlc/LAWS.md. Extract all laws with severity ERROR or WARN.
+
+  Build a compact law summary string to pass to each agent. Format:
+
+  ```
+  ENGINEERING LAWS (violations will be caught in review):
+  [ERROR] DRY: Search for existing patterns before creating new ones. No duplicate logic.
+  [ERROR] Clean Code: Max 40 lines/function, max 3 params, max 3 nesting levels.
+  [ERROR] Security: No hardcoded secrets. Validate all input. Parameterized queries only.
+  [ERROR] Testing: New behavior requires new tests.
+  [ERROR] Error Handling: No empty catch blocks. No swallowed exceptions.
+  [WARN] Null Safety: No non-null assertions. Handle null/undefined explicitly.
+  [WARN] Type Safety: Named types for complex shapes.
+  ```
+
+  Only include laws at ERROR and WARN severity. Skip INFO — those are review-only.
+
+  WHY: Agents that do not know the laws will violate them. Passing laws upfront prevents rework during review.
+</step>
+
+<step name="build_execution_plan" priority="fourth">
+  From the parsed task_graph, build the wave execution plan:
+
+  Wave 1: tasks from parallel_groups[0] — these have NO dependencies
+  Wave 2: tasks from parallel_groups[1] — these depend on Wave 1 completion
+  Wave N: tasks from parallel_groups[N-1]
+
+  VALIDATE the dependency graph:
+  - Every task referenced in dependencies must exist in the task list
+  - No circular dependencies (A depends on B, B depends on A)
+  - Every task must appear in exactly one parallel_group
+
+  IF VALIDATION FAILS: STOP. Display: "Spec has invalid task graph: {error}. Fix the spec and re-run /sdlc:spec."
+
+  Display the execution plan:
+  ```
+  Execution Plan:
+  Wave 1 (parallel): {task-1}, {task-2}
+  Wave 2 (after wave 1): {task-3}
+  Total waves: {N}
+  Total tasks: {N}
+  ```
+
+  WHY: Validating before execution prevents wasted agent time. An invalid graph causes agents to block forever or produce conflicting outputs.
+</step>
+
+<step name="execute_wave" priority="fifth">
+  FOR EACH WAVE (starting with Wave 1):
+
+  A. SPAWN AGENTS FOR ALL TASKS IN THIS WAVE:
+     For each task in the wave, spawn an agent with run_in_background: true.
+
+     Each agent instruction MUST include ALL of the following (no shortcuts):
+
+     ```
+     You are implementing a single task as part of a larger plan.
+
+     PROJECT CONTEXT:
+     {from PROJECT.md: tech stack, conventions, architecture}
+
+     YOUR TASK:
+     Name: {task-name}
+     Action: {detailed action description from spec}
+     Files to modify: {file list}
+     Files to create: {file list, if any}
+     Done criteria: {observable outcome}
+
+     ENGINEERING LAWS (MUST FOLLOW):
+     {compact law summary from step 3}
+
+     BOUNDARIES (DO NOT VIOLATE):
+     - DO NOT modify any file not listed in "Files to modify"
+     - DO NOT change behavior outside your task scope
+     {boundaries from spec}
+
+     REQUIRED PATTERNS:
+     {patterns from spec}
+
+     BEFORE WRITING ANY CODE:
+     1. Read every file you plan to modify — understand existing patterns
+     2. Search the codebase for similar implementations — reuse, do not reinvent
+     3. Check for existing utilities, helpers, or base classes that do what you need
+
+     AFTER WRITING CODE:
+     1. Verify your changes compile/parse (no syntax errors)
+     2. Verify your done criteria is met
+     3. List all files you modified or created
+     ```
+
+  B. WAIT FOR ALL AGENTS IN THIS WAVE TO COMPLETE.
+     Do NOT proceed to the next wave until every agent in the current wave has returned.
+
+  C. REVIEW WAVE RESULTS:
+     For each agent result:
+     - Did it complete successfully?
+     - Did it list modified files?
+     - Did it report any issues or blockers?
+
+     IF ANY AGENT FAILED:
+       - Display: "Agent for task '{task-name}' failed: {error}"
+       - Display the failure details
+       - STOP. Do NOT proceed to next wave.
+       - Ask user: "How do you want to proceed? Options:
+         A. Fix the issue and re-run /sdlc:impl (recommended — restarts from this wave)
+         B. Skip this task and continue (risky — dependent tasks may fail)
+         C. Abort implementation and return to spec"
+
+     IF ALL AGENTS SUCCEEDED:
+       - Collect all modified/created file lists
+       - Proceed to next wave
+
+  D. REPEAT for each subsequent wave.
+
+  WHY: Wave-based execution respects dependencies while maximizing parallelism. Stopping on failure prevents cascading errors where later agents build on broken foundations.
+</step>
+
+<step name="collect_modified_files" priority="sixth">
+  After all waves complete successfully, collect the union of all files modified or created by all agents.
+
+  Deduplicate the list. Sort alphabetically.
+
+  Update the SPEC.md frontmatter:
+  - files_modified: {updated list}
+  - files_created: {updated list}
+
+  WHY: The review phase needs to know exactly which files to inspect. Missing a file means the review skips it, and law violations slip through.
+</step>
+
+<step name="smoke_test" priority="seventh">
+  Run a quick smoke test to verify nothing is fundamentally broken.
+
+  Based on the tech stack from PROJECT.md:
+
+  IF package.json exists with "build" script:
+    Run: npm run build (or bun run build, etc.)
+    CHECK: exit code 0. If non-zero, display build errors.
+
+  IF package.json exists with "lint" script:
+    Run: npm run lint (or bun run lint, etc.)
+    CHECK: exit code 0. If non-zero, display lint errors.
+
+  IF tsconfig.json exists:
+    Run: npx tsc --noEmit
+    CHECK: exit code 0. If non-zero, display type errors.
+
+  IF ANY SMOKE TEST FAILS:
+    - Display the errors
+    - Do NOT update state to IMPL ✓
+    - Display: "Smoke test failed. Fix the errors and re-run /sdlc:impl."
+    - The user must fix and re-run. Do not auto-fix — the user needs to see what broke.
+
+  IF ALL SMOKE TESTS PASS:
+    - Display: "Smoke tests passed (build, lint, types)."
+
+  WHY: Catching build/lint/type errors now is cheap. Catching them during verify or review wastes an entire loop iteration.
+</step>
+
+<step name="update_state" priority="eighth">
+  Update .sdlc/STATE.md:
+  - loop_position: IMPL ✓
+  - next_required_action: /sdlc:verify
+  - Add history entry: "{timestamp} | impl | Plan {N} implemented. {N} tasks across {N} waves. {N} files modified."
+
+  Display to user:
+  ```
+  Implementation complete.
+
+  Tasks completed: {N}/{N}
+  Waves executed: {N}
+  Files modified: {list}
+  Files created: {list}
+  Smoke tests: PASSED
+
+  NEXT ACTION REQUIRED: /sdlc:verify
+  Run /sdlc:verify to test acceptance criteria.
+  ```
+
+  WHY: Clear reporting lets the user assess what happened before deciding to proceed. The forcing function moves them to verification.
+</step>
+
+</process>

package/src/workflows/init-project.md

@@ -0,0 +1,249 @@
+<purpose>Initialize the .sdlc/ directory structure and project configuration files. This is the entry point for any new SDLC-managed project — nothing else works until this runs.</purpose>
+<when_to_use>Run this ONCE at the start of a new project, or when adopting SDLC on an existing codebase. If .sdlc/ already exists, this workflow warns before overwriting.</when_to_use>
+<required_reading>None — this is the bootstrap workflow. No prior state exists.</required_reading>
+<loop_context>
+  expected_phase: none (pre-loop)
+  prior_phase: none
+  next_phase: SPEC (the user must run /sdlc:spec after init)
+</loop_context>
+<process>
+
+<step name="check_existing_sdlc" priority="first">
+  Check if a .sdlc/ directory already exists in the project root.
+
+  Run: ls -la .sdlc/ 2>/dev/null
+
+  IF .sdlc/ EXISTS:
+    - Display warning: "WARNING: .sdlc/ directory already exists. Re-initializing will overwrite STATE.md and may lose progress."
+    - Ask the user: "Do you want to continue? This will reset your SDLC state. (yes/no)"
+    - If user says no, STOP. Display: "Init cancelled. Existing .sdlc/ preserved."
+    - If user says yes, proceed but PRESERVE existing phases/ directory content (do not delete completed work).
+
+  IF .sdlc/ DOES NOT EXIST:
+    - Proceed without warning.
+
+  WHY: Preventing accidental data loss is critical. A re-init should never silently destroy completed specs, reviews, or summaries.
+</step>
+
+<step name="gather_project_info" priority="second">
+  Ask the user these questions. Do NOT guess or assume defaults.
+
+  Question 1: "What is the project name?"
+    - This becomes the title in PROJECT.md
+    - Use kebab-case for directory references (e.g., "My App" → "my-app")
+
+  Question 2: "Describe the project in 1-2 sentences. What does it do?"
+    - This becomes the description in PROJECT.md
+
+  Question 3: "What is the tech stack?"
+    - Ask specifically: language, framework, database, testing framework, package manager
+    - Example prompt: "Tech stack? (e.g., TypeScript, NestJS, PostgreSQL, Jest, bun)"
+
+  Question 4: "Is this an existing codebase or greenfield (starting from scratch)?"
+    - If EXISTING: proceed to auto-detection step
+    - If GREENFIELD: skip auto-detection, use user-provided stack info only
+
+  WHY: The spec phase needs to know the tech stack to generate appropriate task decompositions. Getting this wrong cascades errors through every subsequent phase.
+</step>
+
+<step name="auto_detect_stack" priority="third">
+  ONLY run this step if the user said "existing codebase."
+
+  Scan the project root for these files and extract information:
+
+  1. package.json → read "dependencies", "devDependencies", "scripts" keys
+     - Detect framework: look for "next", "react", "vue", "angular", "nestjs", "express", "fastify"
+     - Detect test runner: look for "jest", "vitest", "mocha", "playwright"
+     - Detect package manager: check for bun.lockb (bun), yarn.lock (yarn), pnpm-lock.yaml (pnpm), package-lock.json (npm)
+  2. tsconfig.json → TypeScript project, read "compilerOptions.target" and "compilerOptions.module"
+  3. biome.json or .eslintrc* → linter config
+  4. docker-compose.yml or Dockerfile → containerized
+  5. .env.example → environment variables needed
+  6. prisma/schema.prisma or src/**/*.entity.ts → database/ORM
+
+  Present findings to user: "I detected: {stack}. Is this accurate? Anything to add or correct?"
+
+  WHY: Auto-detection prevents the user from having to manually list everything, but we ALWAYS confirm because detection can miss things or misidentify.
+</step>
+
+<step name="create_project_md" priority="fourth">
+  Create .sdlc/PROJECT.md with this structure:
+
+  ```markdown
+  # {Project Name}
+
+  ## Description
+  {User-provided description}
+
+  ## Tech Stack
+  - **Language**: {language}
+  - **Framework**: {framework}
+  - **Database**: {database or "None"}
+  - **Testing**: {test framework}
+  - **Package Manager**: {package manager}
+  - **Linter**: {linter}
+
+  ## Architecture
+  {Leave blank for user to fill, or note "To be defined in first spec"}
+
+  ## Conventions
+  - File naming: {detected or ask}
+  - Import style: {detected or ask}
+  - Test location: {co-located or separate test/ directory}
+
+  ## Requirements
+  {Leave blank — populated during spec phases}
+  ```
+
+  WHY: PROJECT.md is the single source of truth for project context. Every workflow reads it. Incomplete or wrong info here breaks everything downstream.
+</step>
+
+<step name="create_state_md" priority="fifth">
+  Create .sdlc/STATE.md with this structure:
+
+  ```markdown
+  # SDLC State
+
+  ## Current Position
+  - **milestone**: 01
+  - **phase**: none
+  - **plan**: none
+  - **loop_position**: INIT ✓
+  - **status**: ready
+
+  ## Next Required Action
+  /sdlc:spec
+
+  ## Session
+  - **started**: {ISO timestamp}
+  - **last_updated**: {ISO timestamp}
+
+  ## History
+  | Timestamp | Action | Result |
+  |-----------|--------|--------|
+  | {now} | init | Project initialized |
+  ```
+
+  WHY: STATE.md is the state machine. Every workflow reads it first to know where we are. The next_required_action field enforces the SPEC → IMPL → VERIFY → REVIEW → CLOSE loop. Without it, users can skip steps.
+</step>
+
+<step name="create_roadmap_md" priority="sixth">
+  Ask the user:
+
+  Question 1: "What is your first milestone? (e.g., 'MVP', 'Auth System', 'v1.0')"
+  Question 2: "What phases make up this milestone? List 2-5 phases in order."
+    - Provide example: "e.g., Phase 01: Project Setup, Phase 02: Core Models, Phase 03: API Endpoints, Phase 04: UI"
+  Question 3: "Any rough timeline? (optional — leave blank if unknown)"
+
+  Create .sdlc/ROADMAP.md:
+
+  ```markdown
+  # Roadmap
+
+  ## Milestone 01: {name}
+  **Goal**: {user description}
+  **Status**: IN PROGRESS
+
+  ### Phases
+  | Phase | Name | Status | Plans |
+  |-------|------|--------|-------|
+  | 01 | {name} | NOT STARTED | 0 |
+  | 02 | {name} | NOT STARTED | 0 |
+  | ... | ... | ... | ... |
+
+  ## Future Milestones
+  {Leave blank — added via /sdlc:milestone}
+  ```
+
+  WHY: The roadmap gives structure to the work. Without it, specs are disconnected tasks with no arc. The phase structure ensures work builds on itself in a logical order.
+</step>
+
+<step name="create_laws_md" priority="seventh">
+  Present the engineering laws to the user with default severities:
+
+  Display:
+  "These engineering laws will be enforced during /sdlc:review. Default severity is ERROR (blocks progress). You can downgrade any to WARN (flagged but non-blocking) or INFO (noted only)."
+
+  | # | Law | Default | Description |
+  |---|-----|---------|-------------|
+  | 1 | SOLID | ERROR | Single Responsibility, Open/Closed, Liskov, Interface Segregation, Dependency Inversion |
+  | 2 | DRY | ERROR | No duplicate logic. Search before creating |
+  | 3 | YAGNI | ERROR | No speculative code. Only what the spec requires |
+  | 4 | Clean Code | ERROR | Max 40 lines/function, max 3 params, max 3 nesting levels |
+  | 5 | Security | ERROR | No hardcoded secrets, input validation, parameterized queries |
+  | 6 | Testing | ERROR | New behavior requires new tests. Edge cases covered |
+  | 7 | Error Handling | ERROR | No empty catch blocks, no swallowed exceptions |
+  | 8 | Null Safety | WARN | No non-null assertions in production. Explicit null handling |
+  | 9 | Type Safety | WARN | Named types for complex shapes. No inline object types with 2+ properties |
+  | 10 | File Size | WARN | Max 500 lines per file |
+
+  Ask: "Keep all defaults, or change any? (e.g., 'set 8 to INFO, set 10 to ERROR')"
+
+  Create .sdlc/LAWS.md with the configured severities:
+
+  ```markdown
+  # Engineering Laws
+
+  ## Enforcement Levels
+  - **ERROR**: Blocks /sdlc:close. Must fix before proceeding.
+  - **WARN**: Flagged in review. Should fix but non-blocking.
+  - **INFO**: Noted for awareness. No action required.
+
+  ## Laws
+  | # | Law | Severity | Enforcement |
+  |---|-----|----------|-------------|
+  | 1 | SOLID | {severity} | {description} |
+  ...
+  ```
+
+  WHY: Configurable severity lets teams adopt incrementally. A legacy codebase might start with Clean Code as WARN and tighten later. But the laws EXIST from day one — you cannot skip the review phase.
+</step>
+
+<step name="create_directory_structure" priority="eighth">
+  Create the phase directories based on the roadmap:
+
+  ```
+  .sdlc/
+    PROJECT.md
+    STATE.md
+    ROADMAP.md
+    LAWS.md
+    phases/
+      01-{phase-name}/
+      02-{phase-name}/
+      ...
+    research/
+  ```
+
+  Run: mkdir -p .sdlc/phases/{phase-dir} for each phase
+  Run: mkdir -p .sdlc/research
+
+  WHY: Pre-creating directories prevents "directory not found" errors during spec/impl phases. The research/ directory is used by /sdlc:research to store findings.
+</step>
+
+<step name="update_state_and_display" priority="ninth">
+  Update STATE.md:
+  - loop_position: INIT ✓
+  - next_required_action: /sdlc:spec
+  - Add history entry: "{timestamp} | init | Project initialized with {N} phases"
+
+  Display to user:
+  ```
+  ✅ Project initialized.
+
+  Created:
+    .sdlc/PROJECT.md  — project configuration
+    .sdlc/STATE.md     — state machine
+    .sdlc/ROADMAP.md   — milestone and phase tracking
+    .sdlc/LAWS.md      — engineering law configuration
+    .sdlc/phases/      — phase directories
+    .sdlc/research/    — research storage
+
+  NEXT ACTION REQUIRED: /sdlc:spec
+  Run /sdlc:spec to create your first specification.
+  ```
+
+  WHY: The explicit "NEXT ACTION REQUIRED" message is the forcing function. The user always knows exactly what to do next. No ambiguity, no guessing.
+</step>
+
+</process>