sdlc-framework 1.0.0

package/src/commands/pause.md

@@ -0,0 +1,115 @@
+---
+name: sdlc:pause
+description: "Save context for session break"
+argument-hint: "[reason]"
+allowed-tools: [Read, Write, Bash, Glob, Grep, AskUserQuestion]
+---
+
+<objective>
+Save complete session context so you can walk away and pick up exactly where you left off. Creates a HANDOFF.md that captures everything the next session needs.
+
+**When to use:** You need to take a break, switch tasks, or end your session. Run this before closing your terminal.
+
+**What it does:**
+1. Detect current loop position from STATE.md.
+2. Gather all context: work done, decisions made, blockers, in-progress tasks.
+3. Create HANDOFF.md with everything needed to resume.
+4. Optionally create a WIP git commit.
+5. Tell you exactly how to resume.
+
+**What happens next:** When you return, run /sdlc:resume.
+</objective>
+
+<execution_context>
+@~/.claude/sdlc-framework/workflows/pause-resume.md
+@.sdlc/STATE.md
+</execution_context>
+
+<context>
+$ARGUMENTS — optional reason for pausing (e.g., "end of day", "switching to urgent task").
+
+Read .sdlc/STATE.md to detect current loop position and active work.
+</context>
+
+<process>
+Follow workflow: @~/.claude/sdlc-framework/workflows/pause-resume.md
+
+Step-by-step:
+
+1. **Read current state**
+   - Read .sdlc/STATE.md to get:
+     - Current loop_position (SPEC, IMPLEMENT, VERIFY, REVIEW, CLOSE, DEBUG, HOTFIX).
+     - Current milestone and phase.
+     - Current plan (if any).
+     - Any recorded blockers.
+
+2. **Gather session context**
+   - Check git status for uncommitted changes (`git status --short`).
+   - Check git log for recent commits in this session (`git log --oneline -5`).
+   - Read any in-progress spec, plan, or task files referenced in STATE.md.
+   - Scan .sdlc/ for recently modified files (`find .sdlc -mmin -120 -type f`).
+
+3. **Create HANDOFF.md**
+   - Save to .sdlc/handoffs/HANDOFF-{timestamp}.md with:
+
+   ```
+   # Session Handoff — {timestamp}
+
+   ## Loop Position
+   {current loop_position} in {milestone} / {phase}
+
+   ## Work Completed This Session
+   - {list of completed tasks, commits, files changed}
+
+   ## Work In Progress
+   - {what was being worked on when paused}
+   - {current state of that work}
+
+   ## Decisions Made
+   - {any architectural or design decisions}
+
+   ## Blockers
+   - {anything preventing progress}
+
+   ## Uncommitted Changes
+   - {list of modified/untracked files from git status}
+
+   ## Resume Instructions
+   Run /sdlc:resume to continue.
+   The framework will pick up at: {loop_position}
+   Next action will be: {determined next action}
+   ```
+
+4. **Update STATE.md**
+   - Add session continuity section:
+     - `paused_at: {timestamp}`
+     - `pause_reason: {from $ARGUMENTS or "manual pause"}`
+     - `handoff_file: .sdlc/handoffs/HANDOFF-{timestamp}.md`
+   - Do NOT change loop_position — it stays where it was.
+
+5. **Offer WIP commit**
+   - Check if there are uncommitted changes.
+   - If yes, ask the user via AskUserQuestion:
+     "You have uncommitted changes. Create a WIP commit? (yes/no)"
+   - If yes: stage all changes and commit with message "WIP: {current task} [sdlc:pause]".
+   - If no: note in HANDOFF.md that uncommitted changes exist.
+
+6. **Output resume instructions**
+   - Print:
+     ```
+     Session paused. Context saved to .sdlc/handoffs/HANDOFF-{timestamp}.md
+
+     When you return, run: /sdlc:resume
+     ```
+   - Do not suggest any other actions. The only valid next step is /sdlc:resume.
+</process>
+
+<success_criteria>
+- [ ] Current loop position detected from STATE.md
+- [ ] All session context gathered (commits, changes, decisions, blockers)
+- [ ] HANDOFF.md created in .sdlc/handoffs/ with complete context
+- [ ] STATE.md updated with session continuity section
+- [ ] WIP commit offered if uncommitted changes exist
+- [ ] Output clearly states: "When you return, run /sdlc:resume"
+- [ ] No ambiguity — exactly one path forward
+</success_criteria>

package/src/commands/research.md

@@ -0,0 +1,136 @@
+---
+name: sdlc:research
+description: "Deploy research subagents for discovery"
+argument-hint: "<topic>"
+allowed-tools: [Read, Write, Glob, Grep, Agent, WebSearch, WebFetch]
+---
+
+<objective>
+Deploy research subagents to investigate a topic before writing code. This is the ONLY valid use of subagents outside of /sdlc:impl. Research never auto-integrates into code — findings are saved for human review.
+
+**When to use:** Before writing a spec, you need to understand something: an API, a library, a codebase pattern, a competing approach, or a technical constraint.
+
+**What it does:**
+1. Classify the research type (codebase, web, or both).
+2. Spawn focused subagent(s) with the Agent tool.
+3. Save structured findings to .sdlc/research/{topic}.md.
+4. Present findings for your review. Never auto-apply.
+
+**What happens next:** /sdlc:spec to use the research findings in planning.
+</objective>
+
+<execution_context>
+@~/.claude/sdlc-framework/workflows/research.md
+@.sdlc/STATE.md
+</execution_context>
+
+<context>
+$ARGUMENTS — the research topic. Required.
+
+If $ARGUMENTS is empty, output: "Provide a research topic. Example: /sdlc:research authentication patterns" Then stop.
+</context>
+
+<process>
+Follow workflow: @~/.claude/sdlc-framework/workflows/research.md
+
+Step-by-step:
+
+1. **Pre-flight check**
+   - Verify $ARGUMENTS is not empty.
+   - Read .sdlc/STATE.md to confirm framework is initialized.
+   - Create .sdlc/research/ directory if it does not exist.
+
+2. **Classify research type**
+   - Analyze the topic to determine what kind of research is needed:
+     - **Codebase exploration:** Understanding existing patterns, finding usage examples, mapping dependencies. Keywords: "how does", "where is", "existing pattern", "current implementation".
+     - **Web research:** External APIs, libraries, best practices, security advisories. Keywords: "library", "API", "best practice", "alternative", "comparison".
+     - **Both:** Topics that require understanding current code AND external context. Keywords: "migrate to", "upgrade", "integrate with".
+
+3. **Spawn research subagent(s)**
+   - For **codebase exploration**: spawn ONE Agent with instructions:
+     ```
+     Research topic: {topic}
+     Search the codebase for:
+     - Existing implementations of {topic}
+     - Patterns used for similar functionality
+     - Dependencies and imports related to {topic}
+     - Test coverage of related code
+     Use Glob, Grep, and Read. Report findings in structured format:
+     - Files found
+     - Patterns identified
+     - Key code snippets (with file paths and line numbers)
+     - Gaps or inconsistencies
+     ```
+   - For **web research**: spawn ONE Agent with instructions:
+     ```
+     Research topic: {topic}
+     Use WebSearch and WebFetch to find:
+     - Official documentation
+     - Best practices and recommendations
+     - Common pitfalls and gotchas
+     - Security considerations
+     - Performance implications
+     Report findings in structured format with source URLs.
+     ```
+   - For **both**: spawn TWO Agents (one codebase, one web) in parallel.
+
+4. **Collect and structure findings**
+   - Wait for all agents to complete.
+   - Merge findings into a structured document.
+
+5. **Save findings**
+   - Write to .sdlc/research/{sanitized-topic}.md:
+     ```
+     # Research: {topic}
+     Date: {timestamp}
+     Type: {codebase | web | both}
+
+     ## Summary
+     {2-3 sentence summary of key findings}
+
+     ## Codebase Findings
+     {if applicable}
+     ### Existing Patterns
+     - {pattern 1 with file references}
+     ### Dependencies
+     - {dependency 1}
+     ### Gaps
+     - {gap 1}
+
+     ## Web Findings
+     {if applicable}
+     ### Best Practices
+     - {practice 1} (source: {url})
+     ### Pitfalls
+     - {pitfall 1}
+     ### Security Considerations
+     - {consideration 1}
+
+     ## Recommendations
+     - {recommendation 1}
+     - {recommendation 2}
+
+     ## Open Questions
+     - {question that needs human input}
+     ```
+
+6. **Present findings — do NOT auto-integrate**
+   - Display the summary and recommendations to the user.
+   - Explicitly state: "These findings are saved for reference. They have NOT been applied to code."
+   - Output: "NEXT ACTION REQUIRED: /sdlc:spec — use these findings to plan your implementation."
+
+7. **Update STATE.md**
+   - Record that research was conducted on {topic}.
+   - Add reference to the findings file.
+</process>
+
+<success_criteria>
+- [ ] Research topic provided (not empty)
+- [ ] Research type classified correctly (codebase, web, or both)
+- [ ] Appropriate subagent(s) spawned with clear instructions
+- [ ] Findings saved to .sdlc/research/{topic}.md in structured format
+- [ ] Findings presented to user but NOT auto-applied to code
+- [ ] STATE.md updated with research reference
+- [ ] Output ends with NEXT ACTION REQUIRED: /sdlc:spec
+- [ ] No code changes made — research is read-only
+</success_criteria>

package/src/commands/resume.md

@@ -0,0 +1,103 @@
+---
+name: sdlc:resume
+description: "Restore context and continue with ONE next action"
+argument-hint: "[handoff-path]"
+allowed-tools: [Read, Write, Bash, Glob, Grep]
+---
+
+<objective>
+Restore session context after a break and determine exactly ONE next action. No menus. No options. The framework decides what happens next.
+
+**When to use:** After running /sdlc:pause and returning to work. The framework picks up exactly where you left off.
+
+**What it does:**
+1. Read STATE.md and the most recent HANDOFF.md.
+2. Display: where you stopped, what was in progress, any blockers.
+3. Determine and force exactly ONE next action.
+4. Archive the consumed handoff.
+
+**What happens next:** The determined action. You do not choose — the framework routes you.
+</objective>
+
+<execution_context>
+@~/.claude/sdlc-framework/workflows/pause-resume.md
+@.sdlc/STATE.md
+</execution_context>
+
+<context>
+$ARGUMENTS — optional path to a specific handoff file. If not provided, use the most recent one.
+
+Read .sdlc/STATE.md for loop position and session continuity data.
+</context>
+
+<process>
+Follow workflow: @~/.claude/sdlc-framework/workflows/pause-resume.md
+
+Step-by-step:
+
+1. **Locate the handoff file**
+   - If $ARGUMENTS contains a path, use that file.
+   - Otherwise, read .sdlc/STATE.md for the `handoff_file` field.
+   - If no handoff_file in STATE.md, scan .sdlc/handoffs/ for the most recently modified file.
+   - If no handoff exists at all, output: "No handoff found. Check .sdlc/STATE.md for current position and run /sdlc:status." Then stop.
+
+2. **Read and display context**
+   - Read the handoff file.
+   - Read .sdlc/STATE.md.
+   - Display to the user:
+
+   ```
+   ## Session Restored
+
+   **Where you stopped:** {loop_position} in {milestone} / {phase}
+   **Paused at:** {timestamp}
+   **Reason:** {pause_reason}
+
+   ### Work In Progress
+   {from handoff}
+
+   ### Blockers
+   {from handoff, or "None"}
+
+   ### Uncommitted Changes
+   {from handoff — verify against current git status}
+   ```
+
+3. **Verify current state**
+   - Run `git status --short` to check if uncommitted changes match the handoff.
+   - If they do not match, warn: "Git state has changed since pause. Review before proceeding."
+   - Check if any WIP commit exists from the pause (`git log --oneline -3`).
+
+4. **Determine the ONE next action**
+   - Use the loop_position from STATE.md to determine the next action:
+     - `SPEC` → "NEXT ACTION REQUIRED: /sdlc:spec"
+     - `IMPLEMENT` → "NEXT ACTION REQUIRED: /sdlc:impl"
+     - `VERIFY` → "NEXT ACTION REQUIRED: /sdlc:verify"
+     - `REVIEW` → "NEXT ACTION REQUIRED: /sdlc:review"
+     - `CLOSE` → "NEXT ACTION REQUIRED: /sdlc:close"
+     - `DEBUG` → "NEXT ACTION REQUIRED: /sdlc:debug"
+     - `HOTFIX` → "NEXT ACTION REQUIRED: /sdlc:hotfix"
+   - If blockers exist, prepend: "BLOCKER: {blocker}. Resolve before proceeding."
+   - Output exactly ONE action. No alternatives. No menus.
+
+5. **Archive the consumed handoff**
+   - Move the handoff file to .sdlc/handoffs/archive/:
+     `mkdir -p .sdlc/handoffs/archive && mv {handoff_file} .sdlc/handoffs/archive/`
+   - Remove the `handoff_file` field from STATE.md session continuity section.
+   - Remove the `paused_at` and `pause_reason` fields.
+
+6. **Force the next action**
+   - Output the determined next action as the final line.
+   - Do not offer choices. The loop position dictates the action.
+</process>
+
+<success_criteria>
+- [ ] Handoff file located (from argument, STATE.md, or most recent)
+- [ ] Context displayed: loop position, work in progress, blockers
+- [ ] Git state verified against handoff (warn if mismatch)
+- [ ] Exactly ONE next action determined from loop_position
+- [ ] Handoff file archived to .sdlc/handoffs/archive/
+- [ ] STATE.md session continuity fields cleaned up
+- [ ] Output ends with NEXT ACTION REQUIRED: /sdlc:{action}
+- [ ] No menus, no options, no choices — one path forward
+</success_criteria>

package/src/commands/review.md

@@ -0,0 +1,195 @@
+---
+name: sdlc:review
+description: Engineering laws compliance review
+argument-hint: "[spec-path]"
+allowed-tools: [Read, Write, Bash, Glob, Grep, Edit, AskUserQuestion]
+---
+
+<objective>
+Review all code modified during implementation against the Engineering Laws defined in .sdlc/LAWS.md. Produce a REVIEW.md with findings categorized by severity: blocker, warning, or info.
+
+**When to use:** After /sdlc:verify confirms all acceptance criteria pass. This is the REVIEW phase of the SDLC loop.
+
+**What it does:**
+1. Identify all files modified during implementation.
+2. Read each file and check against every engineering law.
+3. Detect violations: SOLID, DRY, YAGNI, Clean Code, Security, Test Coverage, Naming, Error Handling.
+4. Generate REVIEW.md with findings, severity, file references, and remediation steps.
+5. Blockers must be fixed before the loop can close.
+
+**What happens next:**
+- No blockers: Framework directs you to /sdlc:close.
+- Blockers found: Fix all blockers, then re-run /sdlc:review.
+
+**Critical rule:** This is an automated code review, not a rubber stamp. Every file gets read. Every law gets checked. Severity is assigned honestly — do not downgrade blockers to warnings to pass faster.
+</objective>
+
+<execution_context>
+@~/.claude/sdlc-framework/workflows/run-review.md
+@.sdlc/STATE.md
+@.sdlc/LAWS.md
+The SPEC.md and IMPL.md paths are read from STATE.md.
+</execution_context>
+
+<context>
+$ARGUMENTS — optional path to SPEC.md. If not provided, read from .sdlc/STATE.md spec_path field.
+
+Read these files:
+- .sdlc/STATE.md — current plan, spec path, impl path.
+- .sdlc/LAWS.md — engineering laws with severity configuration.
+- .sdlc/specs/SPEC-<plan-id>.md — what was planned (boundaries, tasks).
+- .sdlc/impl/IMPL-<plan-id>.md — files modified during implementation.
+- .sdlc/verify/VERIFY-<plan-id>.md — verification results.
+
+Use `git diff` to identify changed files if IMPL.md is unavailable.
+</context>
+
+<process>
+Follow workflow: @~/.claude/sdlc-framework/workflows/run-review.md
+
+Step-by-step:
+
+1. **Load state and identify modified files**
+   - Read .sdlc/STATE.md. Confirm loop_position is VERIFY_COMPLETE. If not, warn: "Verification not complete. Run /sdlc:verify first."
+   - Read IMPL-<plan-id>.md for the list of files created and modified.
+   - If IMPL.md is unavailable, run `git diff --name-only HEAD~<n>` to find changed files.
+   - Read .sdlc/LAWS.md for the full set of engineering laws and their configured severity.
+   - Read SPEC.md for boundaries (what was in scope vs out of scope).
+
+2. **Read all modified files**
+   - Read every file listed in the modified files list.
+   - For large files, read in chunks but cover the entire file.
+   - Note the file type, size, and purpose.
+
+3. **Check: SOLID Principles**
+   - **Single Responsibility:** Does each class/module/function have one reason to change? Flag files that mix concerns (e.g., a service that also formats responses).
+   - **Open/Closed:** Are new behaviors added via extension (new classes, new handlers) rather than modifying existing code? Flag modifications to stable abstractions.
+   - **Liskov Substitution:** Do subtypes honor the contract of their parent type? Flag overrides that change behavior semantics.
+   - **Interface Segregation:** Are interfaces focused? Flag interfaces with 5+ methods that clients only partially use.
+   - **Dependency Inversion:** Do high-level modules depend on abstractions? Flag direct imports of concrete implementations where an interface should exist.
+
+4. **Check: DRY (Don't Repeat Yourself)**
+   - Search for duplicate code blocks (3+ lines repeated across files).
+   - Use Grep to find similar patterns across the codebase.
+   - Flag: identical logic in multiple locations, copy-pasted error handling, repeated validation patterns.
+   - Recommend: extract to shared utility, base class, or helper function.
+
+5. **Check: YAGNI (You Ain't Gonna Need It)**
+   - Compare modified files against SPEC.md boundaries.
+   - Flag any code that is NOT required by the acceptance criteria:
+     - Unused functions or methods with no callers.
+     - Configuration for features not in scope.
+     - Abstractions that only have one implementation (premature abstraction).
+     - Comments saying "for future use" or "TODO: extend later."
+
+6. **Check: Clean Code**
+   - **Function length:** Flag functions exceeding 40 lines.
+   - **Parameter count:** Flag functions with more than 3 parameters.
+   - **Nesting depth:** Flag code with more than 3 levels of nesting.
+   - **Naming:** Flag single-letter variables (except loop counters), abbreviations, misleading names.
+   - **File size:** Flag files exceeding 500 lines.
+   - **Ternary chains:** Flag nested ternaries.
+   - **Magic numbers/strings:** Flag hardcoded values that should be constants.
+
+7. **Check: Security**
+   - **Hardcoded secrets:** Grep for API keys, passwords, tokens, connection strings in source files.
+   - **SQL injection:** Search for string concatenation in SQL queries.
+   - **XSS:** Search for unsanitized user input rendered in HTML/templates.
+   - **Path traversal:** Search for file path operations using unsanitized input.
+   - **Dependency vulnerabilities:** Run `npm audit` or equivalent.
+   - **Input validation:** Verify all user-facing endpoints validate input at the boundary.
+   - **Error exposure:** Flag stack traces or internal details exposed in error responses.
+
+8. **Check: Test Coverage**
+   - For each new function/method, verify a corresponding test exists.
+   - Check test quality: do tests cover happy path, error cases, and edge cases?
+   - Flag untested public methods.
+   - Run coverage tool if available (`npm run test -- --coverage`).
+
+9. **Check: Error Handling**
+   - Flag empty catch blocks.
+   - Flag generic `throw new Error()` instead of domain-specific exceptions.
+   - Flag swallowed exceptions (catch without rethrow or logging).
+   - Flag missing error handling on async operations (unhandled promise rejections).
+   - Flag non-null assertions (`!`) in production code.
+
+10. **Check: Naming Conventions**
+    - Verify consistency with existing codebase conventions.
+    - Flag naming that does not match the project's established patterns.
+    - Check: file names, class names, function names, variable names, constant names.
+
+11. **Compile review report**
+    Create .sdlc/review/REVIEW-<plan-id>.md with:
+    ```
+    # Code Review: <plan title>
+
+    ## Summary
+    - Files reviewed: <count>
+    - Blockers: <count>
+    - Warnings: <count>
+    - Info: <count>
+
+    ## Findings
+
+    ### Blockers (MUST fix before /sdlc:close)
+
+    #### B-1: <title>
+    - **Law:** <which engineering law is violated>
+    - **Severity:** BLOCKER
+    - **File:** <file path>:<line number>
+    - **Description:** <what is wrong and why it matters>
+    - **Remediation:** <specific steps to fix it>
+    - **Code:**
+      ```
+      <the offending code snippet>
+      ```
+
+    ### Warnings (SHOULD fix, recommend addressing)
+
+    #### W-1: <title>
+    ...
+
+    ### Info (CONSIDER fixing, low priority)
+
+    #### I-1: <title>
+    ...
+
+    ## Laws Compliance Matrix
+    | Law | Status | Findings |
+    |-----|--------|----------|
+    | Single Responsibility | PASS/FAIL | B-1, W-2 |
+    | DRY | PASS/FAIL | ... |
+    | YAGNI | PASS/FAIL | ... |
+    | Clean Code | PASS/FAIL | ... |
+    | Security | PASS/FAIL | ... |
+    | Test Coverage | PASS/FAIL | ... |
+    | Error Handling | PASS/FAIL | ... |
+    | Naming | PASS/FAIL | ... |
+    ```
+
+12. **Determine next action**
+    - If ZERO blockers:
+      - Update STATE.md: set `loop_position: REVIEW_COMPLETE`
+      - Set `review_path: .sdlc/review/REVIEW-<plan-id>.md`
+      - Output ends with: NEXT ACTION REQUIRED: /sdlc:close
+    - If ANY blockers:
+      - Update STATE.md: set `loop_position: REVIEW_FAILED`
+      - List each blocker with its remediation.
+      - Output ends with: "NEXT ACTION REQUIRED: /sdlc:fix — Run /sdlc:fix to systematically fix all blockers, then re-review automatically."
+</process>
+
+<success_criteria>
+- [ ] Every modified file read and reviewed
+- [ ] SOLID principles checked with specific file/line references for violations
+- [ ] DRY check performed — duplicate code detected via pattern search
+- [ ] YAGNI check performed — code compared against spec boundaries
+- [ ] Clean Code metrics checked: function length, params, nesting, file size, naming
+- [ ] Security scan performed: secrets, SQL injection, XSS, path traversal, input validation
+- [ ] Test coverage verified: every new public method has tests
+- [ ] Error handling checked: no empty catches, no swallowed exceptions, no generic errors
+- [ ] REVIEW-<plan-id>.md created with all findings, severity, and remediation steps
+- [ ] Laws compliance matrix included in review report
+- [ ] Severity assigned honestly — blockers not downgraded to pass faster
+- [ ] If no blockers: output ends with NEXT ACTION REQUIRED: /sdlc:close
+- [ ] If blockers exist: output ends with NEXT ACTION REQUIRED: /sdlc:fix
+</success_criteria>