sdlc-framework 1.0.0

package/src/workflows/fast-forward.md

@@ -0,0 +1,340 @@
+<purpose>The universal entry point workflow. Accept a plain language description, classify the work, estimate complexity, and either execute inline (simple work) or route to the appropriate specialized command (complex work, bugs, research, hotfixes). This is the "just tell me what to do" workflow.</purpose>
+<when_to_use>Use anytime. This is the default way to start work. The user describes what they need, and this workflow figures out the rest. No prior knowledge of SDLC commands required.</when_to_use>
+<required_reading>.sdlc/STATE.md, .sdlc/PROJECT.md, .sdlc/LAWS.md</required_reading>
+<loop_context>
+  expected_phase: FAST (compressed loop or routing)
+  prior_phase: any (fast can be used between loops or as the first action)
+  next_phase: depends on routing — SPEC, DEBUG, HOTFIX, RESEARCH, or self-contained
+</loop_context>
+<references>
+@~/.claude/sdlc-framework/references/prompt-detection.md
+@~/.claude/sdlc-framework/references/engineering-laws.md
+</references>
+<process>
+
+<step name="preflight" priority="first">
+  Read .sdlc/STATE.md.
+
+  IF .sdlc/ does not exist:
+    Display: "Framework not initialized. Run /sdlc:init first."
+    STOP.
+
+  Note the current state:
+  - current_phase
+  - current_plan
+  - loop_position
+  - next_required_action
+
+  Save this state — if we execute inline, we restore it after.
+
+  Check: Is there an active mid-loop?
+  - If loop_position is mid-loop (e.g., "IMPL ✓" waiting for verify):
+    Display: "Active loop in progress. Current state: {loop_position}. Required: {next_required_action}."
+    Ask: "Override and start fast work? The active loop will pause. (yes/no)"
+    If no: STOP.
+    If yes: save state for restoration, proceed.
+
+  Read .sdlc/PROJECT.md for tech stack context.
+  Read .sdlc/LAWS.md for engineering laws.
+
+  WHY: Fast should work from any state — it's the universal entry point. But if there's an active loop, the user should know they're interrupting it.
+</step>
+
+<step name="classify_work" priority="second">
+  Receive the user's description from $ARGUMENTS.
+
+  Apply PROMPT DETECTION to classify. Scan for keywords and intent:
+
+  CLASSIFICATION RULES (checked in priority order — first match wins):
+
+  1. CRITICAL — urgent production issues
+     Indicators: "urgent", "production", "down", "outage", "critical", "P0", "hotfix", "emergency", "ASAP"
+     Route: /sdlc:hotfix
+     Display: "Critical issue detected. Routing to /sdlc:hotfix for emergency handling."
+     Write to STATE.md: fast_context = {original description}
+     STOP this workflow.
+
+  2. BUG — something broken that needs debugging
+     Indicators: "fix bug", "broken", "crash", "error when", "fails to", "wrong output", "regression", "not working", "throws", "exception"
+     IMPORTANT: "fix" alone is ambiguous — "fix the button alignment" is a feature, "fix the crash on login" is a bug.
+     Disambiguation: Does the description mention an ERROR, FAILURE, or INCORRECT BEHAVIOR?
+     - Yes → BUG → Route: /sdlc:debug
+     - No → FEATURE (a "fix" that is really a refinement)
+     Display: "Bug detected. Routing to /sdlc:debug for structured debugging."
+     Write to STATE.md: fast_context = {original description}
+     STOP this workflow.
+
+  3. RESEARCH — exploration and investigation
+     Indicators: "explore", "investigate", "research", "compare options", "evaluate", "what are the options", "how does X work", "should we use"
+     Route: /sdlc:research
+     Display: "Research task detected. Routing to /sdlc:research."
+     Write to STATE.md: fast_context = {original description}
+     STOP this workflow.
+
+  4. FEATURE — new functionality
+     Indicators: "add", "create", "build", "implement", "new", "introduce", "enable", "support", "integrate"
+     Route: complexity-dependent (next step)
+
+  5. REFACTOR — restructuring without behavior change
+     Indicators: "refactor", "clean up", "rename", "extract", "move", "reorganize", "simplify", "split", "merge"
+     Route: complexity-dependent (next step)
+
+  6. TEST — adding or improving tests
+     Indicators: "test", "coverage", "spec", "assertion", "mock", "e2e", "unit test", "integration test"
+     Route: complexity-dependent (next step)
+
+  7. DOCS — documentation only
+     Indicators: "document", "readme", "comment", "describe", "jsdoc", "annotate"
+     Route: complexity-dependent (next step)
+
+  8. DEFAULT — if no clear match
+     Treat as FEATURE and proceed to complexity check.
+
+  Display: "Classified as: {TYPE}. {Brief explanation of why.}"
+
+  WHY: Classification determines the entire routing strategy. Bugs need root cause analysis (debug), not fast implementation. Critical issues need minimal ceremony (hotfix). Research needs subagents, not code changes. Getting the classification wrong wastes the user's time on the wrong workflow.
+</step>
+
+<step name="estimate_complexity" priority="third">
+  FOR TYPES: FEATURE, REFACTOR, TEST, DOCS — estimate scope.
+
+  A. CODEBASE SCAN:
+  Extract key terms from the description.
+  Search the codebase for related files:
+  - Grep for keywords in file content
+  - Glob for file names matching the description
+  - Check import graphs for connected modules
+
+  B. SCOPE ESTIMATION:
+  Count the files that would need modification.
+  Estimate lines of change based on task type:
+  - New function/method: ~20-40 lines
+  - New file: ~50-100 lines
+  - Modification to existing logic: ~10-30 lines per function
+  - Test file: ~30-60 lines per test suite
+  - Docs: ~10-50 lines
+
+  C. DEPENDENCY CHECK:
+  Does the task cross module boundaries?
+  Does it require changes to shared types/interfaces?
+  Does it affect database schema, API contracts, or config?
+  These add complexity even if file/line counts are low.
+
+  D. COMPLEXITY CLASSIFICATION:
+
+  SIMPLE (execute inline):
+  - ≤3 files modified
+  - ≤100 estimated lines
+  - No cross-module dependencies
+  - No schema/API/config changes
+
+  MEDIUM (route to /sdlc:spec):
+  - 4-6 files modified, OR
+  - 101-300 estimated lines, OR
+  - Cross-module dependencies
+
+  COMPLEX (route to /sdlc:spec):
+  - 7+ files modified, OR
+  - 300+ estimated lines, OR
+  - Schema/API/config changes, OR
+  - Requires parallel sub-agent execution
+
+  Display complexity assessment:
+  ```
+  Complexity: {SIMPLE|MEDIUM|COMPLEX}
+  Estimated: {N} files, ~{N} lines
+  Cross-module: {yes/no}
+  Schema/API changes: {yes/no}
+  ```
+
+  WHY: The complexity check protects quality. Simple work done inline is fast and safe. Complex work needs proper task decomposition, dependency analysis, and parallel sub-agent execution — which /sdlc:spec provides. Skipping decomposition for complex work produces spaghetti.
+</step>
+
+<step name="route_complex_work" priority="fourth">
+  IF COMPLEXITY IS MEDIUM OR COMPLEX:
+
+  Pre-fill context for /sdlc:spec so the user doesn't repeat themselves:
+  Write to .sdlc/STATE.md fast_context field:
+  ```yaml
+  fast_context:
+    description: "{original user description}"
+    classified_as: "{type}"
+    estimated_files: [{list of identified files}]
+    estimated_lines: {N}
+    cross_module: {yes/no}
+    suggested_approach: "{brief recommendation based on codebase scan}"
+  ```
+
+  Display:
+  ```
+  Task complexity exceeds inline threshold.
+
+  Classification: {TYPE}
+  Estimated scope: {N} files, ~{N} lines
+  Reason: {why this needs full spec — e.g., "cross-module changes require task dependency analysis"}
+
+  Your description and the identified files have been saved to STATE.md.
+  /sdlc:spec will pick up this context automatically — no need to repeat yourself.
+
+  NEXT ACTION REQUIRED: /sdlc:spec
+  Run /sdlc:spec to decompose this into parallel tasks with proper dependency ordering.
+  ```
+
+  STOP this workflow.
+
+  WHY: The user should not have to re-describe their work when routing. Pre-filling context makes the handoff seamless. The explanation tells the user WHY the routing happened — building trust in the framework's decisions.
+</step>
+
+<step name="inline_mini_spec" priority="fifth">
+  IF COMPLEXITY IS SIMPLE: execute inline.
+
+  Create a lightweight inline specification:
+
+  Task name: derive from description (kebab-case, max 5 words)
+  Task type: {classified type}
+  Files to modify: {from codebase scan}
+  Action: {imperative description of what to do}
+
+  Write 1-3 acceptance criteria in BDD format:
+  - At minimum: one AC for the expected behavior
+  - If type involves user interaction: one AC for the interaction flow
+  - If type involves error handling: one AC for the error case
+
+  Define boundaries: do not modify files outside the identified set.
+
+  Display:
+  ```
+  ── Quick Spec ──────────────────────
+  Task: {name}
+  Type: {type}
+  Files: {list}
+
+  AC-1: {description}
+  GIVEN {precondition}
+  WHEN {action}
+  THEN {outcome}
+
+  Boundaries: only {listed files}
+  ────────────────────────────────────
+  Proceed? (yes / no / adjust)
+  ```
+
+  Wait for user response.
+  - "yes" / "y" / "go" → proceed
+  - "no" / "n" → STOP
+  - Anything else → treat as adjustment instructions, update spec, re-present
+
+  WHY: Even quick work gets a spec. But it's 10 lines, not a full SPEC.md. The user confirms before code changes begin.
+</step>
+
+<step name="inline_implement" priority="sixth">
+  Execute the task directly (no sub-agents for inline work).
+
+  BEFORE writing code:
+  1. Read every file to modify — understand current state
+  2. Search for existing patterns that match what you need (DRY)
+  3. Check for utilities, helpers, base classes to reuse
+
+  IMPLEMENT following engineering laws:
+  - Max 40 lines per function
+  - Max 3 parameters
+  - Max 3 nesting levels
+  - Named types for complex shapes (2+ properties)
+  - Search before creating
+  - Guard clauses over nested conditionals
+  - Domain-specific exceptions over generic Error
+
+  AFTER writing code:
+  - List all files actually modified
+  - Verify no syntax errors (quick build check if available)
+
+  WHY: Even inline execution follows the laws. "Fast" means less ceremony, not less quality.
+</step>
+
+<step name="inline_verify" priority="seventh">
+  Verify based on task type:
+
+  ALL TYPES:
+  - Run build if available (npm run build / bun run build)
+  - Run lint if available
+
+  FEATURE / TEST:
+  - Run relevant tests (test files for modified modules)
+  - Check new tests pass
+
+  REFACTOR:
+  - Run FULL test suite — refactors must not change behavior
+  - Verify no regressions
+
+  DOCS:
+  - Verify markdown/JSDoc parses correctly
+
+  UI-RELATED (detected from file types — .tsx, .vue, .svelte, etc.):
+  - Playwright MCP: browser_navigate → browser_snapshot → verify AC against snapshot
+
+  Check each AC:
+  - PASS: expected outcome observed
+  - FAIL: expected outcome not observed, describe what happened instead
+
+  IF ALL PASS: proceed to mini-review
+  IF ANY FAIL:
+    Display: "Verification failed:\n  AC-{N}: FAIL — {what happened}\nFix the issue and describe what you changed, or say 'retry' to re-verify."
+    Wait for user response, then re-verify.
+
+  WHY: Fast work still gets verified. Small changes are where bugs hide — developers assume "it's trivial" and skip checking.
+</step>
+
+<step name="inline_review" priority="eighth">
+  Quick engineering laws check on changed files ONLY.
+
+  Check (abbreviated — only blockers):
+  - Function length > 40 lines?
+  - Parameter count > 3?
+  - Nesting depth > 3 levels?
+  - DRY: search codebase for duplicates of new code
+  - Security: hardcoded secrets, injection patterns
+  - Error handling: empty catch blocks, swallowed exceptions
+  - Tests: new behavior without new tests?
+
+  IF BLOCKERS FOUND:
+    Fix them inline immediately (do not route to /sdlc:fix for fast work).
+    Display: "Review found {N} issues. Fixing inline..."
+    Apply fixes. Re-check.
+
+  IF CLEAN: proceed.
+
+  WHY: Review is abbreviated but never skipped. Fast trades ceremony, not quality.
+</step>
+
+<step name="inline_close" priority="ninth">
+  Write fast-forward summary to .sdlc/phases/{current_phase}/FF-{timestamp}-SUMMARY.md:
+  ```markdown
+  # Fast: {task name}
+
+  - **Type**: {type}
+  - **Files modified**: {list}
+  - **ACs**: {N}/{N} passed
+  - **Review**: clean (or {N} warnings fixed inline)
+  - **Routed from**: /sdlc:fast
+  ```
+
+  Update .sdlc/STATE.md:
+  - Restore prior loop state (fast does not advance the phase)
+  - Add history entry: "{timestamp} | fast | {type}: {task name}. {N} files changed."
+
+  Display:
+  ```
+  ── Fast Complete ──────────────────
+  Task: {name}
+  Type: {type}
+  Files: {N} changed
+  ACs: {N}/{N} passed
+  Review: clean
+  ────────────────────────────────────
+  State restored. Continue with: {prior next_required_action or "/sdlc:fast for more work"}
+  ```
+
+  WHY: Fast is a side-quest. It records what happened (audit trail) but does not disrupt the main loop state.
+</step>
+
+</process>

package/src/workflows/fix-findings.md

@@ -0,0 +1,235 @@
+<purpose>Systematically fix all blocker findings from code review. Read REVIEW.md, analyze fix dependencies, apply fixes in optimal order (parallel where possible), then re-run review to confirm compliance. Fixes must not introduce new violations.</purpose>
+<when_to_use>Run after /sdlc:review reports blockers. STATE.md should show next_required_action = /sdlc:review (still in review loop) with blockers outstanding.</when_to_use>
+<required_reading>.sdlc/STATE.md, the current REVIEW.md, .sdlc/LAWS.md, all files referenced in findings</required_reading>
+<loop_context>
+  expected_phase: REVIEW (fix sub-loop)
+  prior_phase: REVIEW found blockers
+  next_phase: REVIEW (re-run) → CLOSE (if pass)
+</loop_context>
+<process>
+
+<step name="load_findings" priority="first">
+  Read the REVIEW.md at .sdlc/phases/{current_phase}/{current_plan}-REVIEW.md.
+
+  Parse every finding into a structured list:
+  ```
+  Finding {N}:
+    file: {path}
+    line: {number}
+    law: {SOLID|DRY|YAGNI|CLEAN_CODE|SECURITY|TESTING|ERROR_HANDLING|NAMING}
+    severity: {BLOCKER|WARNING|INFO}
+    description: {what is wrong}
+    suggested_fix: {how to fix it}
+  ```
+
+  Count totals: {blocker_count} blockers, {warning_count} warnings, {info_count} info.
+
+  IF blocker_count == 0:
+    Display: "No blockers to fix. Run /sdlc:review to confirm, then /sdlc:close."
+    STOP.
+
+  WHY: Parsing findings into structured data enables dependency analysis and parallel execution. Without structure, fixes would be ad-hoc and error-prone.
+</step>
+
+<step name="analyze_fix_dependencies" priority="second">
+  Analyze relationships between findings to determine fix order.
+
+  DEPENDENCY PATTERNS:
+
+  1. DRY RESOLUTION CASCADES:
+     If a DRY finding says "duplicates logic from {file-B}",
+     the fix (extract to shared utility) affects BOTH the flagged file AND file-B.
+     Other findings on the duplicated code may be auto-resolved.
+     → Fix DRY violations FIRST — they often reduce other finding counts.
+
+  2. YAGNI REMOVALS:
+     If a YAGNI finding says "remove {function/class}",
+     all other findings on that code (Clean Code, Naming, Testing) are auto-resolved.
+     → Fix YAGNI violations SECOND — they eliminate dead code findings.
+
+  3. SOLID REFACTORS:
+     If a SOLID finding says "split {class} into {class-A} and {class-B}",
+     other findings on that class need to know which split file they belong to.
+     → Fix SOLID violations BEFORE Clean Code findings on the same class.
+
+  4. INDEPENDENT FINDINGS:
+     Findings on different files with no shared code → fully independent.
+     → Fix in parallel.
+
+  Build a fix execution plan:
+  ```
+  Phase 1 (sequential): DRY extractions that affect multiple files
+  Phase 2 (sequential): YAGNI removals
+  Phase 3 (parallel by file): SOLID refactors + Clean Code + Security + Testing + Error Handling + Naming
+  ```
+
+  WHY: Wrong fix order causes wasted work. Fixing a Naming violation on code that YAGNI will remove is pointless. Fix order matters: DRY → YAGNI → SOLID → everything else.
+</step>
+
+<step name="present_fix_plan" priority="third">
+  Display the fix plan to the user:
+
+  ```
+  ══════════════════════════════════════
+  FIX PLAN — {blocker_count} Blockers
+  ══════════════════════════════════════
+
+  Phase 1 — DRY Extractions ({count} findings):
+    • {file}: Extract {function} to shared utility (resolves {N} findings)
+
+  Phase 2 — YAGNI Removals ({count} findings):
+    • {file}: Remove {function/class} (auto-resolves {N} other findings)
+
+  Phase 3 — File-Level Fixes ({count} findings, parallel):
+    • {file-A}: {N} findings (Clean Code, Security)
+    • {file-B}: {N} findings (SOLID, Error Handling)
+    • {file-C}: {N} findings (Testing)
+
+  Warnings ({warning_count} total):
+    {list of warning descriptions}
+
+  ══════════════════════════════════════
+  ```
+
+  Ask user:
+  "Proceed with fixing all {blocker_count} blockers? For warnings, which would you like fixed? (all / none / list numbers)"
+
+  Wait for response.
+
+  IF user says "none" for warnings: fix only blockers.
+  IF user says "all" for warnings: fix blockers + all warnings.
+  IF user lists specific numbers: fix blockers + listed warnings.
+
+  WHY: The user should understand what will change before code is modified. Showing the plan builds trust and catches misunderstandings ("wait, don't remove that function — it's used in the other repo").
+</step>
+
+<step name="execute_phase_1_dry" priority="fourth">
+  For each DRY extraction:
+
+  1. Identify the duplicated logic across files
+  2. Determine the best location for the shared utility:
+     - Is there an existing utils/ directory? Use it.
+     - Is there a shared module? Use it.
+     - Create new utility file only if no appropriate location exists.
+  3. Extract the shared logic into a named function with proper types
+  4. Replace all duplicate instances with imports of the shared function
+  5. Verify: run build/lint to confirm no import errors
+
+  IMPORTANT: Apply DRY fixes SEQUENTIALLY — each extraction may affect multiple files, and parallel edits to the same file cause conflicts.
+
+  After all DRY fixes:
+  - Re-count remaining findings (some may be auto-resolved)
+  - Update TaskUpdate with progress
+
+  WHY: DRY fixes have the highest cascading impact. A single extraction can resolve 2-5 findings across multiple files. Running these first maximizes the value of each fix.
+</step>
+
+<step name="execute_phase_2_yagni" priority="fifth">
+  For each YAGNI removal:
+
+  1. Verify the code has zero callers (search for imports/references)
+  2. If callers found: this is NOT a valid YAGNI removal — skip and flag as "disputed finding"
+  3. If truly unused: remove the code
+  4. Remove associated tests for removed code (tests for dead code are also dead)
+  5. Remove associated imports
+  6. Verify: run build/lint to confirm no broken references
+
+  After all YAGNI removals:
+  - Re-count remaining findings
+  - Update TaskUpdate with progress
+
+  WHY: Removing dead code eliminates entire categories of findings. Any Clean Code, Naming, or Testing findings on removed code disappear automatically.
+</step>
+
+<step name="execute_phase_3_parallel" priority="sixth">
+  Group remaining findings by file. For each file group:
+
+  IF the file group is independent (no shared dependencies with other file groups):
+    Spawn a sub-agent with Agent tool (run_in_background: true):
+    ```
+    Agent instruction:
+    Fix these review findings in {file-path}:
+    {list of findings with line numbers and suggested fixes}
+
+    Engineering laws to follow: {compact laws from LAWS.md}
+    Boundaries: Do NOT modify any file other than {file-path}.
+
+    For each finding:
+    1. Read the current code at the specified line
+    2. Apply the suggested fix
+    3. Verify the fix does not introduce new violations
+    4. If the suggested fix is unclear, apply your best judgment following engineering laws
+
+    CRITICAL: Do NOT introduce new violations. A fix that creates a new problem is worse than the original finding.
+    ```
+
+  IF the file group shares dependencies with another group:
+    Apply fixes SEQUENTIALLY to avoid conflicts.
+
+  Wait for all agents to complete.
+
+  Review agent results:
+  - Verify each fix was applied correctly
+  - Check for any agent errors or partial fixes
+  - If an agent failed: apply the fix manually
+
+  WHY: Parallel file-level fixes maximize speed. Each agent works on one file, no conflicts. Sequential fallback for dependent files prevents corruption.
+</step>
+
+<step name="verify_fixes" priority="seventh">
+  After all fixes applied:
+
+  1. Run build: verify the project still compiles
+  2. Run lint: verify no new lint errors
+  3. Run tests: verify no regressions
+
+  IF build fails:
+    Display: "Build broken after fixes. Error: {error}. Manual intervention needed."
+    Show which fix likely caused the failure (based on file and error location).
+    STOP.
+
+  IF tests fail:
+    Display: "Test regression after fixes. Failed: {test}. Manual intervention needed."
+    Show which fix likely caused the regression.
+    STOP.
+
+  IF all pass: proceed to re-review.
+
+  WHY: Fixes must not break the project. The build/test check is a safety net before re-running review.
+</step>
+
+<step name="trigger_re_review" priority="eighth">
+  Display:
+  ```
+  Fixes applied:
+  - Blockers fixed: {count}
+  - Warnings fixed: {count}
+  - YAGNI removals: {count} (auto-resolved {count} other findings)
+  - DRY extractions: {count} (auto-resolved {count} other findings)
+  - Build: ✓
+  - Tests: ✓
+
+  Re-running /sdlc:review to confirm compliance...
+  ```
+
+  Trigger the review-phase workflow (re-run the full review).
+
+  IF re-review finds NEW blockers (fixes introduced new violations):
+    Display: "Fix introduced {N} new blockers. Review the new findings and run /sdlc:fix again."
+    Set next_required_action to "/sdlc:fix"
+
+  IF re-review passes (zero blockers):
+    Display:
+    ```
+    Review PASSED after fixes: 0 blockers.
+    Warnings: {count}
+    Info: {count}
+
+    NEXT ACTION REQUIRED: /sdlc:close
+    Run /sdlc:close to close this loop.
+    ```
+
+  WHY: Re-review confirms the fixes are correct and complete. Without re-review, a fix that introduced a new violation would slip through to close.
+</step>
+
+</process>