sdlc-framework 2.1.1 → 3.1.0

package/src/workflows/spec-phase.md

@@ -141,39 +141,91 @@
 </step>
 
 <step name="write_acceptance_criteria" priority="fifth">
-  For each piece of observable behavior, write a BDD acceptance criterion:
+  For each piece of observable behavior, write a BDD acceptance criterion.
 
+  ╔══════════════════════════════════════════════════════════════════════╗
+  ║  EVERY AC MUST INCLUDE A verification_type FIELD.                   ║
+  ║  This field is NOT optional. It is NOT inferred. It is DECLARED.    ║
+  ║  The verify phase reads this field to select the correct tool.      ║
+  ║  Without it, the AC will NOT be verified — it will be SKIPPED.      ║
+  ╚══════════════════════════════════════════════════════════════════════╝
+
+  FORMAT — every AC must follow this exact structure:
   ```
   AC-{N}: {short description}
+  Type: {verification_type}
   GIVEN {initial state or precondition}
   WHEN {action or trigger}
   THEN {expected outcome}
   ```
 
+  VERIFICATION TYPE — choose exactly ONE per AC:
+
+  | Type | When to Use | Verify Phase Tool |
+  |------|-------------|-------------------|
+  | UI_INTERACTION | The AC involves a browser, page, form, button, visual element, navigation, rendering, modal, dropdown, or any user-facing screen | Playwright MCP (browser_navigate, browser_snapshot, browser_click, browser_fill_form, browser_take_screenshot) |
+  | API_ENDPOINT | The AC involves an HTTP endpoint, request/response, status code, JSON body, REST or GraphQL call | Bash curl commands |
+  | CLI_BEHAVIOR | The AC involves a terminal command, stdout/stderr, exit code, file system output | Bash command execution |
+  | BUSINESS_LOGIC | The AC involves a function return value, calculation, transformation, validation rule, or internal behavior with no UI/API surface | Project test runner (bun test, npm test, vitest, jest, pytest) |
+  | DATA_INTEGRITY | The AC involves a database record, migration, schema constraint, or data consistency | Database CLI queries via Bash |
+
+  DECISION RULES for choosing the type:
+  1. If the user interacts with a browser to trigger the behavior → UI_INTERACTION
+  2. If the behavior is triggered by an HTTP request (even if there is also a UI) → choose based on WHAT the AC is testing:
+     - Testing the visual result in the browser → UI_INTERACTION
+     - Testing the API contract (status code, response body) → API_ENDPOINT
+  3. If the AC tests internal logic that has no user-facing surface → BUSINESS_LOGIC
+  4. If the AC tests a CLI tool or script → CLI_BEHAVIOR
+  5. If the AC tests data persistence or schema → DATA_INTEGRITY
+  6. When in doubt, prefer UI_INTERACTION — Playwright is the primary UAT tool
+
   Rules for writing good ACs:
   - Each AC tests ONE behavior (not multiple things)
   - The GIVEN sets up a specific, reproducible state
   - The WHEN is a single action (not a sequence)
   - The THEN is observable and verifiable (not "works correctly" — specify WHAT is correct)
   - Include at least one AC for the "happy path" and one for an error/edge case
+  - The verification_type MUST match the nature of the test — do NOT default everything to BUSINESS_LOGIC
 
-  Example (good):
+  Example (good — UI):
   ```
   AC-1: User login with valid credentials
+  Type: UI_INTERACTION
   GIVEN a registered user with email "test@example.com" and password "ValidPass123"
   WHEN the user submits the login form with those credentials
-  THEN a JWT token is returned with status 200 and the response body contains { "token": "<jwt>" }
+  THEN the browser redirects to /dashboard and displays "Welcome back" in the header
+  ```
+
+  Example (good — API):
+  ```
+  AC-2: Login API returns JWT token
+  Type: API_ENDPOINT
+  GIVEN a registered user with email "test@example.com" and password "ValidPass123"
+  WHEN a POST request is sent to /api/auth/login with { "email": "test@example.com", "password": "ValidPass123" }
+  THEN the response has status 200 and body contains { "token": "<jwt>" }
+  ```
+
+  Example (good — CLI):
+  ```
+  AC-3: Install command copies files to target
+  Type: CLI_BEHAVIOR
+  GIVEN an empty target directory at /tmp/test-install
+  WHEN the user runs "node bin/install.js --local --target /tmp/test-install"
+  THEN the directory /tmp/test-install/commands/sdlc/ contains 12 command files and exit code is 0
   ```
 
-  Example (bad — too vague):
+  Example (bad — missing Type):
   ```
   AC-1: Login works
   GIVEN a user
   WHEN they log in
   THEN it works
   ```
+  This AC is INVALID: no Type field, vague GIVEN/WHEN/THEN, untestable.
+
+  Present ACs to user with their types and ask: "Do these cover all cases? Are the verification types correct?"
 
-  WHY: The verify phase translates ACs directly into test actions. Vague ACs produce vague tests that pass even when the code is broken. Specific ACs catch real bugs.
+  WHY: The verify phase reads the Type field to select Playwright MCP, curl, Bash, or the test runner. Without an explicit type, the verify phase guesses based on keywords — and guesses wrong. This field is the contract between spec and verify. It MUST be present on every AC.
 </step>
 
 <step name="define_boundaries" priority="sixth">
@@ -196,7 +248,114 @@
   WHY: Without boundaries, sub-agents during implementation will "helpfully" refactor nearby code, breaking things outside the spec scope. Boundaries are guardrails.
 </step>
 
-<step name="write_spec_file" priority="seventh">
+<step name="codebase_gap_analysis" priority="seventh">
+  ╔══════════════════════════════════════════════════════════════════════╗
+  ║  THIS STEP IS MANDATORY. DO NOT SKIP. DO NOT ABBREVIATE.           ║
+  ║  Review the EXISTING code that this spec touches BEFORE writing     ║
+  ║  the spec file. Gaps found here become new ACs or task updates.     ║
+  ╚══════════════════════════════════════════════════════════════════════╝
+
+  PURPOSE: Catch missing logic, incomplete requirements, and hidden dependencies
+  by reading the actual code BEFORE implementation begins. A spec written without
+  reading the code it modifies will miss error handling, edge cases, validation,
+  and integration points that only the code reveals.
+
+  PROCEDURE:
+
+  1. IDENTIFY FILES TO REVIEW:
+     Collect every file path listed in the tasks from step "task_decomposition":
+     - Files to modify (existing code that will change)
+     - Files adjacent to modified files (same directory — they may share types, imports, or patterns)
+     - Test files for modified files (if they exist)
+     Do NOT review files listed in Boundaries/DO NOT CHANGE.
+
+  2. READ EACH FILE and check for these gap categories:
+
+     A. MISSING ERROR HANDLING:
+        - Does the code handle null/undefined returns from functions the spec will call?
+        - Are there try/catch blocks around operations that can fail (network, file I/O, DB)?
+        - Does the code validate input at system boundaries (controllers, API handlers)?
+        - Are there error paths that the spec's ACs do not cover?
+        → If gaps found: create new ACs with Type: BUSINESS_LOGIC or Type: API_ENDPOINT for each uncovered error path.
+
+     B. INCOMPLETE EDGE CASES:
+        - Empty arrays, empty strings, zero values — does the code handle them?
+        - Concurrent access — can two users hit this code path simultaneously?
+        - Partial failures — what happens if step 2 of 3 fails?
+        - Boundary values — maximum lengths, integer overflow, special characters?
+        → If gaps found: add edge case ACs or expand THEN clauses in existing ACs.
+
+     C. MISSING VALIDATION:
+        - Are there function parameters that accept any value but should be constrained?
+        - Are there user inputs that reach business logic without sanitization?
+        - Are there type assertions or casts that assume a shape without checking?
+        → If gaps found: add validation tasks or expand existing tasks to include validation.
+
+     D. INTEGRATION RISKS:
+        - Does the modified code export types/functions used by OTHER files not in the spec?
+        - Will changing a function signature break its callers?
+        - Are there shared state or singleton patterns that could cause side effects?
+        - Does the code depend on environment variables, config, or feature flags not mentioned in the spec?
+        → If gaps found: add integration ACs or expand Boundaries to protect callers.
+
+     E. UNTESTED PATHS:
+        - Read existing test files for the modified code.
+        - Are there public methods with zero test coverage?
+        - Are there conditional branches (if/else, switch) where only one branch is tested?
+        - Does the spec add new behavior that existing tests do not cover?
+        → If gaps found: add BUSINESS_LOGIC ACs for untested paths, or add test tasks.
+
+     F. PATTERN VIOLATIONS:
+        - Does the existing code follow patterns (error handling, naming, structure) that the spec's tasks should also follow?
+        - Are there established abstractions (base classes, utilities, factories) that the spec should reuse instead of reinventing?
+        → If gaps found: update tasks to reference existing patterns. Add to Required Patterns section.
+
+  3. COMPILE GAP REPORT:
+     Present findings to the user in this format:
+     ```
+     ══════════════════════════════════════════════
+     CODEBASE GAP ANALYSIS
+     ══════════════════════════════════════════════
+     Files reviewed: {N}
+
+     Gaps found: {N}
+
+     GAP-1: {category} — {file}:{line range}
+       Problem: {what is missing or incomplete}
+       Impact: {what could go wrong during implementation or in production}
+       Recommendation: {add AC / expand task / add to boundaries}
+
+     GAP-2: ...
+
+     New ACs to add: {N}
+     Tasks to update: {N}
+     Boundaries to add: {N}
+
+     No gaps found in: {list categories with no issues}
+     ══════════════════════════════════════════════
+     ```
+
+  4. APPLY FIXES:
+     For each gap:
+     - If it requires a new AC → add the AC with the correct verification_type to the AC list
+     - If it requires expanding an existing task → update the task's action and done criteria
+     - If it reveals an out-of-scope dependency → add to Boundaries
+     - If it reveals a required pattern → add to Required Patterns
+
+     Do NOT silently absorb gaps. Every gap MUST appear in the report and result in a spec change.
+
+  5. RE-PRESENT UPDATED ACs AND TASKS:
+     After applying fixes, show the user the updated AC list and any changed tasks.
+     Ask: "I found {N} gaps in the existing code. Here are the additions. Do these look right?"
+
+  WHY: Specs written in a vacuum miss what the code actually does. A login spec might
+  forget rate limiting because the spec author did not read the auth middleware. A form
+  spec might miss accessibility because the spec author did not see the existing aria
+  patterns. This step forces the spec to account for reality — not just intent. It is
+  the difference between a spec that sounds right and a spec that IS right.
+</step>
+
+<step name="write_spec_file" priority="eighth">
   Write the spec to: .sdlc/phases/{phase-dir}/{plan-number}-SPEC.md
 
   Format:
@@ -245,12 +404,16 @@
   ## Acceptance Criteria
 
   AC-1: {description}
+  Type: {UI_INTERACTION | API_ENDPOINT | CLI_BEHAVIOR | BUSINESS_LOGIC | DATA_INTEGRITY}
   GIVEN {precondition}
   WHEN {action}
   THEN {outcome}
 
   AC-2: ...
 
+  ## Codebase Gap Analysis
+  {Summary of gaps found in existing code, with GAP-N references to ACs/tasks they generated}
+
   ## Boundaries
   - DO NOT modify: {files/modules}
   - DO NOT implement: {out-of-scope features}
@@ -267,7 +430,7 @@
   WHY: The YAML frontmatter is machine-readable — the impl phase parses it to build the execution plan. The markdown body is human-readable — developers can review it. Both are needed.
 </step>
 
-<step name="spec_integrity_review" priority="eighth">
+<step name="spec_integrity_review" priority="ninth">
   ╔══════════════════════════════════════════════════════════════════════╗
   ║  THIS STEP IS MANDATORY. DO NOT SKIP. DO NOT ABBREVIATE.           ║
   ║  You MUST print the full integrity review table before proceeding.  ║
@@ -286,6 +449,7 @@
   - [ ] complexity (LOW/MEDIUM/HIGH)
   For each AC, verify it has ALL of these (print each):
   - [ ] AC number (AC-1, AC-2, etc.)
+  - [ ] Type field with valid verification_type (UI_INTERACTION, API_ENDPOINT, CLI_BEHAVIOR, BUSINESS_LOGIC, or DATA_INTEGRITY)
   - [ ] GIVEN with specific precondition (not "given the system is running")
   - [ ] WHEN with specific action (not "when the user does something")
   - [ ] THEN with specific observable outcome (not "then it works correctly")
@@ -321,11 +485,26 @@
   - [ ] Independent tasks (no shared files, no shared types) are correctly parallelized
   - [ ] Dependent tasks (shared files, shared types/interfaces) are correctly sequenced
 
+  CHECK 6 — VERIFICATION TYPE VALIDITY:
+  - [ ] Every AC has a Type field (no AC without a Type)
+  - [ ] Every Type is one of: UI_INTERACTION, API_ENDPOINT, CLI_BEHAVIOR, BUSINESS_LOGIC, DATA_INTEGRITY
+  - [ ] Type matches the AC content (UI ACs reference browser/page/form elements, API ACs reference endpoints/status codes, etc.)
+  - [ ] ACs with Type: UI_INTERACTION have THEN clauses that reference observable browser state (page content, URL, visible elements) — not internal state
+  - [ ] ACs with Type: API_ENDPOINT have WHEN clauses that specify HTTP method and endpoint path
+  - [ ] ACs with Type: CLI_BEHAVIOR have WHEN clauses that specify the exact command to run
+
+  CHECK 7 — CODEBASE GAP ANALYSIS COMPLETED:
+  - [ ] The codebase_gap_analysis step was executed (not skipped)
+  - [ ] Files listed in tasks were read and reviewed for gaps
+  - [ ] Gap report was presented to user
+  - [ ] Any gaps found resulted in new ACs or updated tasks (no silent absorption)
+  - [ ] Codebase Gap Analysis section exists in the spec file
+
   IF ANY CHECK ITEM FAILS:
   1. List all failures with specific descriptions
   2. Propose a fix for each failure
   3. Apply all fixes to the SPEC.md
-  4. Re-run ALL five checks on the updated spec
+  4. Re-run ALL seven checks on the updated spec
   5. Repeat until all checks pass
 
   PRINT the full integrity review report:
@@ -333,17 +512,29 @@
   ══════════════════════════════════════════════
   SPEC INTEGRITY REVIEW
   ══════════════════════════════════════════════
-  Completeness:      {✓ or ✗} — {details}
-  Consistency:       {✓ or ✗} — {details}
-  Contradictions:    {✓ or ✗} — {details or "none found"}
-  Feasibility:       {✓ or ✗} — {details}
-  Dependency Graph:  {✓ or ✗} — {details}
+  Completeness:        {✓ or ✗} — {details}
+  Consistency:         {✓ or ✗} — {details}
+  Contradictions:      {✓ or ✗} — {details or "none found"}
+  Feasibility:         {✓ or ✗} — {details}
+  Dependency Graph:    {✓ or ✗} — {details}
+  Verification Types:  {✓ or ✗} — {details}
+  Gap Analysis:        {✓ or ✗} — {details}
 
   Tasks: {N} fully defined
-  ACs: {N} with specific Given/When/Then
+  ACs: {N} with specific Given/When/Then and verification_type
   Waves: {N} parallel execution groups
   Estimated scope: ~{N} lines across {N} files
 
+  Verification type breakdown:
+  - UI_INTERACTION: {N} ACs (Playwright MCP)
+  - API_ENDPOINT: {N} ACs (curl)
+  - CLI_BEHAVIOR: {N} ACs (Bash)
+  - BUSINESS_LOGIC: {N} ACs (test runner)
+  - DATA_INTEGRITY: {N} ACs (DB queries)
+
+  Codebase gaps found: {N}
+  {if any: list each gap and the AC/task it generated}
+
   Contradictions found: {N}
   {if any: list each contradiction and how it was resolved}
 
@@ -352,10 +543,10 @@
   ══════════════════════════════════════════════
   ```
 
-  WHY: A spec with contradictions produces agents that build conflicting code. A spec with orphan ACs means untested features. A spec with invalid dependencies means agents wait forever or overwrite each other. This review catches all of these. It costs 30 seconds now and saves hours of debugging later.
+  WHY: A spec with contradictions produces agents that build conflicting code. A spec with orphan ACs means untested features. A spec with invalid dependencies means agents wait forever or overwrite each other. A spec without verification types means the verify phase guesses and skips Playwright. A spec without gap analysis means missing logic ships undetected. This review catches all of these.
 </step>
 
-<step name="user_approval_gate" priority="ninth">
+<step name="user_approval_gate" priority="tenth">
   THIS IS A BLOCKING GATE. The spec does NOT proceed without explicit user approval.
 
   Present the complete spec summary to the user:
@@ -409,7 +600,7 @@
   WHY: Implementation is expensive. Building the wrong thing wastes hours. A 30-second review of the spec catches misunderstandings before they become code. The user MUST see and approve the plan before sub-agents start writing code.
 </step>
 
-<step name="update_state" priority="tenth">
+<step name="update_state" priority="eleventh">
   ONLY REACHED AFTER USER APPROVES THE SPEC.
 
   Update .sdlc/STATE.md:
@@ -431,10 +622,21 @@
   Acceptance Criteria: {N}
   Boundaries: {N} files protected
 
-  NEXT ACTION REQUIRED: /sdlc:impl
-  Run /sdlc:impl to begin sub-agent implementation.
+  NEXT: /sdlc:impl
   ```
 
+  <auto_advance>
+  Read .sdlc/STATE.md auto_advance setting.
+  IF auto_advance is true:
+    Display: "Auto-advancing to /sdlc:impl in {advance_delay_seconds}s — reply to intervene."
+    Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+    If no user message received during sleep: automatically execute /sdlc:impl.
+    If user sends a message: cancel auto-advance, process user input, then resume.
+  IF auto_advance is false:
+    Display: "NEXT ACTION REQUIRED: /sdlc:impl"
+    Wait for user to manually run the command.
+  </auto_advance>
+
   WHY: The forcing function ensures the user moves to implementation. Without it, specs pile up without being built.
 </step>
 

package/src/workflows/status-session.md

@@ -61,12 +61,24 @@
 
   Force ONE next action from loop_position with explanation:
   ```
-  NEXT ACTION REQUIRED: /sdlc:impl
+  NEXT: /sdlc:impl
 
   What it does: Implements the current plan by writing code with subagent workers.
   Why it is next: The spec phase is complete. The plan has been approved.
   ```
 
+  <auto_advance>
+  Read .sdlc/STATE.md auto_advance setting.
+  IF auto_advance is true:
+    Display: "Auto-advancing to /sdlc:{next} in {advance_delay_seconds}s — reply to intervene."
+    Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+    If no user message received during sleep: automatically execute /sdlc:{next}.
+    If user sends a message: cancel auto-advance, process user input, then resume.
+  IF auto_advance is false:
+    Display: "NEXT ACTION REQUIRED: /sdlc:{next}"
+    Wait for user to manually run the command.
+  </auto_advance>
+
   WHY: Status is the "where am I" command. Junior developers need the visual. Senior developers need the forced next action. Both get what they need.
 </step>
 
@@ -198,7 +210,18 @@
 
   E. FORCE NEXT ACTION:
      Determine from STATE.md next_required_action.
-     Display: "NEXT ACTION REQUIRED: {action}"
+
+     <auto_advance>
+     Read .sdlc/STATE.md auto_advance setting.
+     IF auto_advance is true:
+       Display: "Auto-advancing to {action} in {advance_delay_seconds}s — reply to intervene."
+       Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+       If no user message received during sleep: automatically execute {action}.
+       If user sends a message: cancel auto-advance, process user input, then resume.
+     IF auto_advance is false:
+       Display: "NEXT ACTION REQUIRED: {action}"
+       Wait for user to manually run the command.
+     </auto_advance>
 
   WHY: Exactly ONE next action. The state machine has already decided. The user just executes it.
 </step>

package/src/workflows/verify-phase.md

@@ -45,38 +45,43 @@
   WHY: Without acceptance criteria, there is nothing to verify. The spec must define what "done" looks like.
 </step>
 
-<step name="classify_acceptance_criteria" priority="third">
-  For each AC, classify its verification type based on the GIVEN/WHEN/THEN content:
-
-  TYPE: UI_INTERACTION
-  Indicators: mentions page, form, button, click, navigate, display, render, modal, input field, dropdown
-  Method: Playwright MCP (browser_navigate, browser_snapshot, browser_click, browser_fill_form, etc.)
+<step name="read_verification_types" priority="third">
+  ╔══════════════════════════════════════════════════════════════════════╗
+  ║  DO NOT GUESS OR INFER THE VERIFICATION TYPE.                       ║
+  ║  READ the Type field from each AC in the SPEC.md.                   ║
+  ║  The spec phase declared the type. The verify phase USES it.        ║
+  ║  If an AC is missing its Type field, mark it FAIL: "No Type field." ║
+  ╚══════════════════════════════════════════════════════════════════════╝
 
-  TYPE: API_ENDPOINT
-  Indicators: mentions endpoint, request, response, status code, JSON body, header, GET/POST/PUT/DELETE
-  Method: Bash curl commands
+  For each AC extracted in the previous step, read its declared Type field.
 
-  TYPE: CLI_BEHAVIOR
-  Indicators: mentions command, terminal, output, exit code, stderr, stdout, flag, argument
-  Method: Bash command execution
+  VALID TYPES AND THEIR VERIFICATION TOOLS:
 
-  TYPE: BUSINESS_LOGIC
-  Indicators: mentions function, method, returns, throws, calculates, transforms, validates
-  Method: Run project test suite (npm test, bun test, etc.) or execute specific test files
+  | Type | Verification Tool | Action |
+  |------|------------------|--------|
+  | UI_INTERACTION | Playwright MCP | Use browser_navigate, browser_snapshot, browser_click, browser_fill_form, browser_take_screenshot |
+  | API_ENDPOINT | Bash curl | Construct and execute HTTP requests, parse response |
+  | CLI_BEHAVIOR | Bash | Run shell commands, capture stdout/stderr/exit code |
+  | BUSINESS_LOGIC | Test runner | Run bun test, npm test, vitest, jest, or pytest |
+  | DATA_INTEGRITY | DB CLI | Execute database queries via Bash |
 
-  TYPE: DATA_INTEGRITY
-  Indicators: mentions database, record, row, column, migration, schema, constraint
-  Method: Database queries via Bash or ORM commands
+  MISSING TYPE HANDLING:
+  If an AC does NOT have a Type field:
+  1. Record: "FAIL — AC-{N} is missing its Type field. The spec must declare a verification_type for every AC."
+  2. Do NOT attempt to guess the type from keywords.
+  3. Do NOT skip the AC silently.
+  4. Include this failure in the verification report.
+  5. The overall verification FAILS if any AC is missing its Type.
 
-  Present classification to proceed:
+  Present the type mapping before executing:
   ```
-  AC Classification:
-  AC-1: {description} → UI_INTERACTION (Playwright)
-  AC-2: {description} → API_ENDPOINT (curl)
-  AC-3: {description} → BUSINESS_LOGIC (test suite)
+  Verification Plan:
+  AC-1: {description} → {Type} (tool: {Playwright MCP | curl | Bash | test runner | DB CLI})
+  AC-2: {description} → {Type} (tool: {Playwright MCP | curl | Bash | test runner | DB CLI})
+  AC-3: {description} → {Type} (tool: {Playwright MCP | curl | Bash | test runner | DB CLI})
   ```
 
-  WHY: Different AC types need different verification tools. Using curl for a UI test or Playwright for a unit test wastes time and gives unreliable results.
+  WHY: The spec phase explicitly declared how each AC should be verified. Reading the declared type eliminates guessing, prevents misclassification, and ensures Playwright MCP is actually invoked for UI acceptance criteria. This is the contract between spec and verify — the spec says WHAT tool to use, the verify phase USES that tool.
 </step>
 
 <step name="verify_ui_interactions" priority="fourth">
@@ -263,10 +268,21 @@
 
     Report: .sdlc/phases/{phase}/{plan}-VERIFY.md
 
-    NEXT ACTION REQUIRED: /sdlc:review
-    Run /sdlc:review for engineering laws compliance check.
+    NEXT: /sdlc:review
     ```
 
+    <auto_advance>
+    Read .sdlc/STATE.md auto_advance setting.
+    IF auto_advance is true:
+      Display: "Auto-advancing to /sdlc:review in {advance_delay_seconds}s — reply to intervene."
+      Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+      If no user message received during sleep: automatically execute /sdlc:review.
+      If user sends a message: cancel auto-advance, process user input, then resume.
+    IF auto_advance is false:
+      Display: "NEXT ACTION REQUIRED: /sdlc:review"
+      Wait for user to manually run the command.
+    </auto_advance>
+
   IF ANY AC FAILS:
     Do NOT update loop_position. Keep it at "IMPL ✓".
     Update next_required_action to "/sdlc:verify" (stay in verify).

package/src/commands/research.md

@@ -1,136 +0,0 @@
----
-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>