sdlc-framework 1.0.0

package/src/references/prompt-detection.md

@@ -0,0 +1,264 @@
+# Prompt Detection Reference
+
+This document explains how the `/sdlc:fast` command classifies task types from natural language prompts. It covers keyword patterns, complexity estimation, routing logic, and override mechanisms.
+
+---
+
+## Overview
+
+When a developer types `/sdlc:fast "add a login page"`, the framework must determine:
+
+1. **What type of work is this?** (feature, bug, critical, research, test, refactor, docs)
+2. **How complex is it?** (simple, medium, complex)
+3. **Where should it route?** (inline execution, /sdlc:spec, /sdlc:debug, /sdlc:hotfix, /sdlc:research)
+
+`/sdlc:fast` is the **default entry point** for all work — not just small tasks. It is a universal router that classifies intent and complexity, then either handles work inline (simple) or routes to the appropriate specialized command (complex, bugs, research, emergencies).
+
+This classification happens automatically. The developer can override it with flags if the automatic classification is wrong.
+
+---
+
+## Keyword Patterns by Type
+
+Each task type has a set of keyword patterns that signal its classification. Patterns are checked in order — the first match wins.
+
+### Feature (new functionality)
+
+**Strong signals:**
+- "add", "create", "build", "implement", "new"
+- "page", "endpoint", "API", "component", "service"
+- "support for", "ability to"
+
+**Phrase patterns:**
+- "add a {{thing}}"
+- "create {{thing}} that {{behavior}}"
+- "build a {{thing}} for {{purpose}}"
+- "implement {{feature_name}}"
+- "new {{thing}}"
+
+**Examples:**
+- "add a login page" → feature
+- "create a user registration API" → feature
+- "build a dashboard component" → feature
+- "implement password reset" → feature
+
+### Bug Fix (correcting behavior)
+
+**Strong signals:**
+- "fix", "bug", "broken", "error", "crash"
+- "doesn't work", "not working", "fails", "incorrect"
+- "wrong", "should be", "expected", "instead of"
+
+**Phrase patterns:**
+- "fix {{thing}} that {{bad_behavior}}"
+- "{{thing}} is broken"
+- "{{thing}} returns wrong {{result}}"
+- "{{thing}} crashes when {{condition}}"
+- "{{thing}} doesn't {{expected_behavior}}"
+
+**Examples:**
+- "fix the login form that crashes on empty email" → bugfix
+- "user search returns wrong results" → bugfix
+- "signup page doesn't validate email" → bugfix
+- "API returns 500 instead of 404" → bugfix
+
+### Test (adding or improving tests)
+
+**Strong signals:**
+- "test", "spec", "coverage", "assert", "mock"
+- "unit test", "integration test", "e2e test"
+- "add tests for", "test coverage"
+
+**Phrase patterns:**
+- "add tests for {{thing}}"
+- "write unit tests for {{thing}}"
+- "increase test coverage for {{thing}}"
+- "add e2e tests for {{flow}}"
+
+**Examples:**
+- "add tests for the UserService" → test
+- "write unit tests for password validation" → test
+- "add e2e tests for checkout flow" → test
+
+### Refactor (restructuring without behavior change)
+
+**Strong signals:**
+- "refactor", "restructure", "reorganize", "clean up"
+- "extract", "split", "move", "rename"
+- "simplify", "reduce complexity", "DRY up"
+
+**Phrase patterns:**
+- "refactor {{thing}}"
+- "extract {{thing}} from {{other_thing}}"
+- "split {{thing}} into {{parts}}"
+- "clean up {{thing}}"
+- "rename {{thing}} to {{new_name}}"
+
+**Examples:**
+- "refactor the OrderService" → refactor
+- "extract validation logic into a shared utility" → refactor
+- "split the UserController into separate controllers" → refactor
+- "clean up the database query builders" → refactor
+
+### Documentation (docs-only changes)
+
+**Strong signals:**
+- "document", "docs", "README", "JSDoc", "comment"
+- "API docs", "guide", "tutorial", "changelog"
+- "update docs", "add documentation"
+
+**Phrase patterns:**
+- "document {{thing}}"
+- "add docs for {{thing}}"
+- "update the README"
+- "write a guide for {{thing}}"
+
+**Examples:**
+- "document the authentication API" → docs
+- "add JSDoc comments to the UserService" → docs
+- "update the README with setup instructions" → docs
+
+---
+
+## Complexity Estimation Heuristics
+
+After determining the type, estimate the complexity to decide the SDLC path.
+
+### Complexity Signals
+
+| Signal | Simple | Moderate | Complex |
+|--------|--------|----------|---------|
+| Files affected | 1-2 | 3-5 | 6+ |
+| Concepts involved | 1 | 2-3 | 4+ |
+| Dependencies mentioned | 0 | 1-2 | 3+ |
+| Words in prompt | 5-15 | 15-30 | 30+ |
+| Contains "and" | 0-1 times | 2 times | 3+ times |
+| Mentions integration | no | partial | yes |
+| Mentions testing explicitly | no | yes | yes + e2e |
+| Mentions multiple components | no | no | yes |
+
+### Complexity Scoring
+
+Each signal contributes a score. Total score determines complexity:
+
+- **0-3 points:** Simple — Fast-track path
+- **4-7 points:** Moderate — Standard loop
+- **8+ points:** Complex — Full loop with sub-agents
+
+### Examples
+
+**"fix typo in login page"**
+- Files: 1 (simple, 0 points)
+- Concepts: 1 (simple, 0 points)
+- Words: 5 (simple, 0 points)
+- Total: 0 → **Simple**
+
+**"add user search with filtering by role and status"**
+- Files: 2-3 (moderate, 2 points)
+- Concepts: 3 — search, filtering, roles (moderate, 2 points)
+- "and": 1 time (simple, 0 points)
+- Contains filtering logic (moderate, 1 point)
+- Total: 5 → **Moderate**
+
+**"implement OAuth2 login with Google and GitHub providers, including token refresh, account linking, and role-based access control"**
+- Files: 6+ (complex, 3 points)
+- Concepts: 5+ — OAuth, providers, tokens, linking, RBAC (complex, 3 points)
+- "and": 3 times (complex, 2 points)
+- Mentions integration (complex, 2 points)
+- Total: 10 → **Complex**
+
+---
+
+## Routing Logic
+
+Based on type and complexity, the framework routes to the appropriate SDLC path.
+
+### Routing Table
+
+| Complexity | Action |
+|------------|--------|
+| Simple | Skip spec phase. Generate minimal spec inline. Go directly to implementation. Quick verification. No sub-agents. |
+| Moderate | Standard SDLC loop. Spec phase with 1-2 clarification questions. Single-agent implementation. Full verification. Full review. |
+| Complex | Full SDLC loop. Spec phase with multiple clarification rounds. Sub-agent implementation with task dependency graph. Full verification including Playwright where applicable. Full review. |
+
+### Type-Specific Routing Adjustments
+
+| Type | Adjustment |
+|------|------------|
+| bugfix | Always include verification of the fix AND regression testing. |
+| refactor | Always include before/after behavior comparison. Skip UI verification. |
+| test | Skip implementation phase (tests ARE the implementation). Go directly to verification (run the tests). |
+| docs | Skip verification and review phases. Docs do not need engineering law review. |
+
+### Routing Decision Tree
+
+```
+Type = docs?
+  Yes → Write docs, skip verify/review, close
+  No  → Complexity = simple?
+    Yes → Fast-track: minimal spec, implement, quick verify, close
+    No  → Complexity = moderate?
+      Yes → Standard: spec, implement, verify, review, close
+      No  → Full: spec (with clarifications), implement (with sub-agents),
+             verify (with Playwright), review, close
+```
+
+---
+
+## Override Mechanism
+
+The automatic classification is a best guess. Developers can override it.
+
+### Force Flags
+
+| Flag | Effect |
+|------|--------|
+| `--type feature` | Force task type to feature |
+| `--type bugfix` | Force task type to bugfix |
+| `--type refactor` | Force task type to refactor |
+| `--type test` | Force task type to test |
+| `--type docs` | Force task type to docs |
+| `--complexity simple` | Force simple complexity (fast-track) |
+| `--complexity moderate` | Force moderate complexity (standard loop) |
+| `--complexity complex` | Force complex complexity (full loop) |
+| `--full` | Force full SDLC loop regardless of detection |
+| `--fast` | Force fast-track regardless of detection |
+
+### Override Examples
+
+```bash
+# Detected as simple, but developer knows it is complex
+/sdlc:fast "update the user model" --complexity complex
+
+# Detected as feature, but it is actually a refactor
+/sdlc:fast "restructure the auth module" --type refactor
+
+# Skip all detection, use full loop
+/sdlc:fast "add email notifications" --full
+```
+
+### When to Override
+
+- **The prompt is ambiguous:** "update the user page" could be a feature, bugfix, or refactor.
+- **The complexity is underestimated:** "add a button" sounds simple, but the button triggers a complex workflow.
+- **The complexity is overestimated:** "implement OAuth with Google, GitHub, and GitLab" sounds complex, but the library handles everything and it is actually moderate.
+- **You want the full loop for learning:** Even simple tasks benefit from the full loop when training junior developers.
+
+---
+
+## Classification Examples
+
+A comprehensive set of examples showing how detection works in practice.
+
+| Prompt | Detected Type | Detected Complexity | Route |
+|--------|---------------|--------------------|----|
+| "fix typo in header" | bugfix | simple | fast-track |
+| "add dark mode toggle" | feature | simple | fast-track |
+| "refactor UserService to use repository pattern" | refactor | moderate | standard |
+| "add user search with pagination and sorting" | feature | moderate | standard |
+| "fix race condition in payment processing" | bugfix | complex | full |
+| "implement real-time notifications with WebSocket" | feature | complex | full |
+| "add unit tests for OrderService" | test | moderate | standard (skip impl) |
+| "document the REST API endpoints" | docs | simple | fast-track (skip verify) |
+| "build a multi-tenant auth system with RBAC, SSO, and audit logging" | feature | complex | full |
+| "rename getUserById to findUserById" | refactor | simple | fast-track |

package/src/references/sub-agent-strategy.md

@@ -0,0 +1,260 @@
+# Sub-Agent Strategy Reference
+
+This document explains how sub-agent driven development works within the SDLC framework. It is loaded via `@references/sub-agent-strategy.md` when planning implementation or when understanding how tasks are parallelized.
+
+---
+
+## When to Use Sub-Agents
+
+Sub-agents are separate AI execution contexts that work on tasks in parallel. They are powerful but not free — each agent consumes tokens, requires instructions, and produces output that must be integrated.
+
+### Use Sub-Agents For
+
+- **Independent implementation tasks:** Two services that do not share files can be built in parallel.
+- **Test writing:** Tests for existing code can be written in parallel with new feature code.
+- **Research tasks:** Investigating a library, reading documentation, or analyzing existing code while another agent implements.
+- **File creation:** When multiple new files need to be created and they do not depend on each other.
+
+### Do NOT Use Sub-Agents For
+
+- **Simple edits:** Changing a single line, adding an import, fixing a typo. The overhead of spawning an agent exceeds the work.
+- **Sequential debugging:** Debugging requires reading output, thinking, trying something, reading output again. This is inherently sequential.
+- **Tasks that modify the same file:** Two agents editing the same file creates merge conflicts.
+- **Tasks with tight coupling:** If Task B needs to know what Task A decided, they must be sequential.
+- **Tasks under 50 lines of code:** The agent instruction overhead is not worth it for small changes.
+
+### Decision Framework
+
+```
+Is the task independent of other tasks?
+  No  → Run sequentially, do not use a sub-agent
+  Yes → Is the task substantial (50+ lines or multiple files)?
+    No  → Do it inline, no sub-agent needed
+    Yes → Does it modify files another task touches?
+      Yes → Run sequentially after the other task
+      No  → Use a sub-agent
+```
+
+---
+
+## Task Dependency Analysis
+
+Before spawning agents, build a directed acyclic graph (DAG) of task dependencies. The DAG determines which tasks can run in parallel and which must wait.
+
+### How to Build the DAG
+
+1. **List all tasks** from the spec (T-001 through T-NNN).
+2. **For each task, identify inputs:** What files does it read? What interfaces does it implement? What data structures does it consume?
+3. **For each task, identify outputs:** What files does it create or modify? What interfaces does it define? What data structures does it produce?
+4. **Draw edges:** If Task B's inputs include Task A's outputs, draw an edge from A to B (B depends on A).
+5. **Check for cycles:** If you find a cycle (A depends on B depends on A), the tasks need to be restructured. Cycles usually mean the tasks are not properly decomposed.
+
+### Example DAG Construction
+
+Spec tasks:
+- T-001: Define `User` interface in `types/user.ts`
+- T-002: Define `Order` interface in `types/order.ts`
+- T-003: Implement `UserService` (imports `User` interface)
+- T-004: Implement `OrderService` (imports `Order` and `User` interfaces)
+- T-005: Write tests for `UserService`
+- T-006: Write tests for `OrderService`
+
+Dependency analysis:
+```
+T-001 (User interface)     → T-003 (UserService), T-004 (OrderService)
+T-002 (Order interface)    → T-004 (OrderService)
+T-003 (UserService)        → T-005 (UserService tests)
+T-004 (OrderService)       → T-006 (OrderService tests)
+```
+
+DAG:
+```
+T-001 ─┬─→ T-003 ──→ T-005
+       │
+       └─→ T-004 ──→ T-006
+            ↑
+T-002 ─────┘
+```
+
+---
+
+## Parallel Group Formation
+
+Once the DAG is built, group tasks into parallel execution waves. A wave is a set of tasks with no dependencies on each other (all dependencies are in prior waves).
+
+### Algorithm
+
+1. Tasks with no dependencies form Wave 1.
+2. Remove Wave 1 tasks from the DAG.
+3. Tasks whose dependencies are now all satisfied form Wave 2.
+4. Repeat until all tasks are assigned to a wave.
+
+### Example (from the DAG above)
+
+- **Wave 1:** T-001, T-002 (no dependencies)
+- **Wave 2:** T-003, T-004 (depend on Wave 1 tasks which are now done — but T-004 depends on T-001 AND T-002, so both must be in a prior wave, which they are)
+- **Wave 3:** T-005, T-006 (depend on Wave 2 tasks)
+
+This means:
+- First, spawn 2 agents for T-001 and T-002 in parallel.
+- When both complete, spawn 2 agents for T-003 and T-004 in parallel.
+- When both complete, spawn 2 agents for T-005 and T-006 in parallel.
+
+Total: 3 sequential waves instead of 6 sequential tasks. Time savings depend on task size.
+
+---
+
+## Agent Instruction Template
+
+Each sub-agent receives a focused instruction set. The instruction must be self-contained — the agent does not have access to the full conversation history.
+
+### Required Elements
+
+Every agent instruction must include:
+
+1. **Role:** What the agent is (e.g., "You are implementing the UserService")
+2. **Task:** Exactly what to do, copied from the spec task
+3. **Files to read:** Which existing files to read for context
+4. **Files to create/modify:** Which files the agent owns
+5. **Interfaces/types to use:** Exact signatures the agent must conform to
+6. **Constraints:** What NOT to do (do not modify files outside your scope)
+7. **Verification:** How the agent confirms its work is correct
+8. **Output format:** What the agent should report when done
+
+### Template
+
+```
+## Role
+You are a sub-agent implementing {{TASK_NAME}}.
+
+## Task
+{{TASK_DESCRIPTION from spec}}
+
+## Context Files (read-only)
+- {{FILE_PATH}} — {{WHY_IT_IS_RELEVANT}}
+
+## Your Files (create or modify)
+- {{FILE_PATH}} — {{WHAT_TO_DO_WITH_IT}}
+
+## Interfaces to Conform To
+```typescript
+{{INTERFACE_DEFINITIONS_THE_AGENT_MUST_IMPLEMENT}}
+```
+
+## Constraints
+- Do NOT modify any file not listed in "Your Files"
+- Do NOT add dependencies not listed in the spec
+- Do NOT create abstractions not required by the task
+- Follow engineering laws: {{RELEVANT_LAWS}}
+
+## Verification
+- {{HOW_TO_CONFIRM_TASK_IS_DONE}}
+
+## Report
+When done, report:
+1. Files created/modified
+2. Any decisions made
+3. Any issues encountered
+```
+
+---
+
+## Error Handling: When an Agent Fails
+
+Agents can fail for several reasons: ambiguous instructions, missing context, file conflicts, or runtime errors.
+
+### Failure Categories and Responses
+
+**Ambiguous instructions:**
+- Symptom: Agent asks for clarification or makes an incorrect assumption.
+- Response: Rewrite the instruction with more specificity. Add explicit examples.
+
+**Missing context:**
+- Symptom: Agent cannot find a required interface, type, or utility.
+- Response: Add the missing file to the agent's context files. If the file does not exist yet (it is another agent's output), the task dependency graph is wrong — fix the ordering.
+
+**File conflict:**
+- Symptom: Two agents modified the same file.
+- Response: This should never happen if the task dependency graph is correct. If it does, one agent's changes take priority (the one later in the dependency chain). The earlier agent's changes to that file must be manually merged.
+
+**Runtime error:**
+- Symptom: Agent's code does not compile or tests fail.
+- Response: Review the error, fix the issue, and re-verify. Do not re-run the entire wave — fix the specific failure.
+
+### Retry Strategy
+
+- **First failure:** Review agent output, fix the instruction, re-run the single task.
+- **Second failure:** Bring the task back to the main context and implement it directly.
+- **Never:** Retry more than twice. If an agent fails twice, the task is too ambiguous for sub-agent execution.
+
+---
+
+## Integration: Merging Agent Outputs
+
+After all agents in a wave complete, their outputs must be integrated before the next wave starts.
+
+### Integration Checklist
+
+1. **File conflicts:** Verify no two agents modified the same file. If they did, merge manually.
+2. **Interface compliance:** Verify each agent's output conforms to the interfaces specified in its instructions.
+3. **Import resolution:** Verify that cross-file imports between agent outputs resolve correctly.
+4. **Type checking:** Run the type checker (if applicable) to catch interface mismatches.
+5. **Test execution:** Run existing tests to confirm nothing broke.
+
+### When Integration Fails
+
+If integration reveals a mismatch between agents (e.g., Agent A defined an interface differently than Agent B expected), the problem is in the spec. The spec did not define the shared interface precisely enough. Fix the spec, then re-run the affected agents.
+
+---
+
+## Anti-Patterns
+
+### Agents Modifying the Same File
+Never assign two agents to modify the same file. Even with different sections, the merge is error-prone and the conflict detection overhead negates the parallelism benefit.
+
+**Fix:** Split the file into separate concerns, or make one task sequential.
+
+### Agents Without Clear Scope
+An agent instruction that says "implement the authentication system" is too broad. The agent will make architectural decisions that conflict with other agents or with the project's conventions.
+
+**Fix:** Break it into specific tasks: "implement password hashing in auth/password.service.ts using bcrypt," "implement JWT token generation in auth/token.service.ts using jsonwebtoken."
+
+### Too Many Agents
+Spawning 10 agents for 10 tiny tasks creates more overhead than doing them sequentially. Each agent has startup cost (reading context, understanding instructions) and integration cost (verifying output, resolving imports).
+
+**Fix:** Group small related tasks into a single agent. An agent that creates 3 related files is more efficient than 3 agents creating 1 file each.
+
+### Agents That Need Human Input
+A sub-agent cannot ask the user questions. If a task requires a decision that was not made during the spec phase, the agent will guess — and usually guess wrong.
+
+**Fix:** All decisions must be made during `/sdlc:spec`. If a task has an open question, it is not ready for sub-agent execution.
+
+---
+
+## Cost Awareness
+
+Sub-agents consume tokens. Before spawning, estimate the cost.
+
+### Estimation Heuristic
+
+- **Context files:** Count tokens in the files the agent needs to read. Typical code file is 200-500 tokens.
+- **Instructions:** The agent instruction template is roughly 300-500 tokens.
+- **Output:** The agent's generated code is roughly proportional to the task complexity. A 50-line function is about 300-400 tokens.
+- **Total per agent:** Context + Instructions + Output + Reasoning overhead (2-3x the output).
+
+### Example
+
+An agent that reads 3 files (1500 tokens), receives instructions (400 tokens), and produces 100 lines of code (600 tokens with reasoning overhead of 1800 tokens):
+- Input: ~1900 tokens
+- Output: ~2400 tokens
+- Cost: varies by model, but roughly $0.01-0.05 per agent
+
+For a wave of 4 agents, that is $0.04-0.20. For a full implementation with 3 waves and 4 agents each, that is $0.12-0.60. This is usually far cheaper than the developer time saved.
+
+### When Cost Exceeds Benefit
+
+- Tasks that require reading enormous files (>1000 lines each) for a small change.
+- Tasks that will likely fail and need retries (ambiguous specs).
+- Tasks that could be done in 2 minutes inline.
+
+In these cases, skip the sub-agent and do the work directly.