claude-devkit-cli 1.0.0

package/templates/.claude/commands/challenge.md

@@ -0,0 +1,210 @@
+Think hard. This is adversarial plan review — you are the coordinator who sends hostile reviewers to DESTROY a plan, then adjudicates their findings.
+
+## Input
+
+Target: $ARGUMENTS
+
+If argument is a file path → use that.
+If argument is a feature name → search `docs/test-plans/` and `docs/specs/` for matches.
+If no argument → list recent files in both dirs, ask user which to challenge.
+
+## Phase 1: Read and Map
+
+Read the ENTIRE target file. Also read related files:
+- If target is a test plan → also read the corresponding spec in `docs/specs/`
+- If target is a spec → also read the corresponding test plan in `docs/test-plans/`
+
+Map the plan's attack surface:
+- Decisions made (and what was rejected)
+- Assumptions (stated AND implied)
+- Dependencies (external services, APIs, libraries, infra)
+- Scope boundaries (in/out/suspiciously unmentioned)
+- Risk acknowledgments (mentioned vs. conspicuously absent)
+- Spec↔plan consistency (use cases without test cases? contradictions?)
+
+Collect all file paths the reviewers will need to read.
+
+## Phase 2: Scale Reviewers
+
+Assess plan complexity and select which lenses to deploy:
+
+| Complexity Signal | Reviewers | Lenses |
+|-------------------|-----------|--------|
+| Simple (1 spec section, <20 test cases, no auth/data) | 2 | Assumptions + Scope |
+| Standard (multiple sections, auth or data involved) | 3 | + Security |
+| Complex (multiple integrations, concurrency, migrations, 6+ phases) | 4 | + Failure Modes |
+
+When in doubt, use 3 reviewers. 4 is for genuinely complex plans.
+
+## Phase 3: Spawn Parallel Reviewers
+
+Launch reviewers simultaneously using the Agent tool. Each reviewer is an independent subagent that reads the plan files directly and returns findings.
+
+**CRITICAL:** Each reviewer prompt MUST include:
+1. The file paths to read (so they can access the plan directly)
+2. Their specific adversarial persona and lens
+3. The exact output format (so you can parse findings consistently)
+4. The rules of engagement
+
+### Reviewer Prompts
+
+For each selected lens, spawn an agent with this structure:
+
+```
+You are a hostile reviewer. Your job is to DESTROY this plan by finding every flaw through the {LENS_NAME} lens.
+
+Read these files first:
+{LIST OF FILE PATHS}
+
+--- YOUR LENS ---
+
+{LENS-SPECIFIC INSTRUCTIONS — see below}
+
+--- OUTPUT FORMAT ---
+
+For EACH flaw found, output exactly:
+
+### Finding: <title>
+- **Severity:** Critical | High | Medium
+- **Location:** <exact section or heading in the plan>
+- **Flaw:** <what's wrong — be specific>
+- **Evidence:** "<direct quote from the plan>"
+- **Failure scenario:** <step-by-step: how this causes a real problem in production>
+- **Root cause:** <why does this flaw exist? Missing requirement? Wrong assumption?>
+- **Suggested fix:** <specific, actionable — not just "fix it">
+
+--- RULES ---
+
+- 3-7 findings per lens. Quality over quantity.
+- Be HOSTILE. No praise. No "overall looks good."
+- Be SPECIFIC. Cite exact sections. Quote the plan.
+- Be CONCRETE. Failure scenarios must be step-by-step, not "could be a problem."
+- Skip trivial issues (naming, formatting, style).
+- If the plan is solid for your lens, 1-2 findings is honest. Don't manufacture problems.
+```
+
+### Lens-Specific Instructions
+
+**Security Adversary:**
+```
+You are an attacker with knowledge of the tech stack and access to the public API.
+
+Examine the plan for:
+- Authentication/authorization bypass: Can auth be skipped? Can user A access user B's data? Are role checks at every layer?
+- Injection vectors: Where does user input enter? SQL, shell, HTML, template, log injection? Parameterized queries?
+- Data exposure: What leaks in error messages, logs, API responses? Stack traces? Internal paths? DB schemas?
+- Cryptography: Password hashing (bcrypt/argon2, not MD5/SHA)? Secrets in env vars not code? TLS?
+- Supply chain: New dependencies? Maintained? Known CVEs?
+- OWASP Top 10 (2021): Broken Access Control, Crypto Failures, Injection, Insecure Design, Security Misconfiguration, Vulnerable Components, Identity Failures, Integrity Failures, Logging Failures, SSRF
+```
+
+**Failure Mode Analyst:**
+```
+You believe Murphy's Law: everything that can go wrong, will — simultaneously, at 3 AM, during peak traffic.
+
+Examine the plan for:
+- Partial failures: What if step 3 of 5 fails? Rollback? Atomic writes? Inconsistent state?
+- Concurrency: Race conditions? Two users editing same resource? Shared mutable state? Deadlocks?
+- Cascading failures: Service A down → B also fails? Circuit-breaking? Graceful degradation?
+- Data integrity: Data loss? Corruption? Duplication? DB-level constraints or app-only validation?
+- Recovery: How to recover from each failure? Reversible migrations? Backup restoration time?
+- Deployment: What breaks during deploy? Rollback plan? Migration failures?
+- Idempotency: Retried requests duplicate data? Double-charge? Double-email?
+- Observability: How do you KNOW something failed? Logging? Monitoring? Alerts? Or angry users?
+```
+
+**Assumption Destroyer:**
+```
+You are a radical skeptic. "It should work" is not evidence. "We assume X" means X is unverified.
+
+Examine the plan for:
+- Unverified claims: "The API returns X" — tested? "The library supports Y" — checked docs?
+- Scale assumptions: Expected load? Works at 10x? 100x? O(n²) hiding in "iterate all items"?
+- Environment gaps: Same behavior in dev/staging/prod? Different OS? Docker vs bare metal?
+- Integration risk: Third-party SLA? Rate limits? Their service down → your plan?
+- Data assumptions: Always clean? Unicode? Emoji? Null bytes? 10MB payloads? Empty strings?
+- User behavior: Will users actually do this? What if they click 50 times? Upload 2GB? Use mobile?
+- Timing: "A before B" — always? What if B first? Implicit ordering dependencies?
+- Hidden dependencies: Services, configs, env vars, or manual steps that must exist but aren't documented?
+```
+
+**Scope & Complexity Critic (YAGNI Enforcer):**
+```
+You believe the best code is no code. The best feature is the one you didn't build.
+
+Examine the plan for:
+- Over-engineering: Solving problems that don't exist yet? "In case we need it later" = YAGNI.
+- Premature abstraction: Generic framework for 1 use case? Plugin system nobody asked for?
+- Missing MVP: What's the absolute minimum viable delivery? Can 40% be deferred?
+- Complexity vs value: Distributed system for 5 users? Proportional?
+- Gold plating: Nice-to-have mixed with must-have? Can you ship without the nice-to-haves?
+- Simpler alternative: Boring 10-line solution vs clever 500-line solution?
+- Test burden: Test cases harder to maintain than the feature itself?
+```
+
+## Phase 4: Collect and Consolidate
+
+After all reviewers complete:
+
+1. **Collect** all findings from all reviewers
+2. **Deduplicate** — if two lenses found the same root issue, merge into one finding noting both lenses
+3. **Rate severity** using Likelihood × Impact:
+
+| | Low Impact | Medium Impact | High Impact |
+|---|-----------|---------------|-------------|
+| **Likely** | Medium | High | Critical |
+| **Possible** | Low | Medium | High |
+| **Unlikely** | Low | Low | Medium |
+
+4. **Sort** by severity: Critical → High → Medium → Low
+5. **Cap** at 15 findings: keep all Critical, top High by specificity, note how many Medium were dropped
+6. **Cross-reference check** (you, not reviewers): If both spec and test plan exist, flag any use cases in spec without test cases, and any test cases that contradict the spec
+
+## Phase 5: Adjudicate
+
+For each finding, YOU (the coordinator) evaluate and propose a disposition:
+
+| Disposition | When to use |
+|-------------|-------------|
+| **Accept** | Valid flaw. Plan should be updated. |
+| **Reject** | False positive, acceptable risk, or already handled elsewhere. |
+
+Include 1-sentence rationale for each disposition. Be honest — don't reject valid findings to be nice, and don't accept trivial findings to pad the list.
+
+## Phase 6: Present to User
+
+Show adjudicated findings using the reviewer output format plus Disposition and Rationale fields.
+
+Then ask: "How would you like to proceed?"
+1. **"Apply all accepted"** — update the plan with all accepted fixes
+2. **"Review each"** — walk through one by one, accept/reject/modify each
+
+If user picks "Review each": for each finding, ask "Accept / Reject / Modify fix?"
+
+## Phase 7: Apply
+
+For each accepted finding:
+1. Edit the target file at the exact location cited
+2. Apply the fix (or user's modified version)
+3. Surgical edits only — do NOT rewrite surrounding sections
+
+After all edits, show summary:
+```
+Challenge complete.
+Reviewers: N lenses
+Findings: X total → Y accepted, Z rejected
+Severity: N Critical, N High, N Medium
+Files modified: [list]
+Next: /test to implement, or /plan to regenerate if major changes.
+```
+
+If a reviewer returns > 7 findings, take only top 7 by severity. If a reviewer fails, proceed with remaining reviewers.
+
+## Rules — Non-Negotiable
+
+1. **Spawn reviewers in parallel.** Don't run lenses in your own context.
+2. **Reviewers read files directly.** Pass paths, not content.
+3. **Be hostile.** No praise. Not in reviewers, not in adjudication.
+4. **Quote the plan.** Every finding needs a direct quote in Evidence.
+5. **Don't manufacture findings.** 3 honest findings > 15 padded ones.
+6. **Skip style/formatting.** Substance only: logic, security, assumptions, scope.

package/templates/.claude/commands/commit.md

@@ -0,0 +1,97 @@
+EXECUTE, not EXPLORE. Follow these steps exactly. Minimize tool calls.
+
+## Step 1 — Analyze (single compound command)
+
+```bash
+echo "=== STATUS ===" && \
+git status --short 2>/dev/null && \
+echo "=== DIFF STAT ===" && \
+git diff --stat 2>/dev/null && \
+git diff --cached --stat 2>/dev/null && \
+echo "=== METRICS ===" && \
+{ git diff --shortstat 2>/dev/null; git diff --cached --shortstat 2>/dev/null; } && \
+echo "=== SECRETS ===" && \
+(git diff 2>/dev/null; git diff --cached 2>/dev/null) | grep -ciE "(api[_-]?key|token|password|secret|private[_-]?key|credential|auth[_-]?token)" || echo "0" && \
+echo "=== DEBUG ===" && \
+(git diff 2>/dev/null; git diff --cached 2>/dev/null) | grep -ciE "(console\.log|debugger|print\(|TODO:.*remove|HACK:|FIXME:.*temp|binding\.pry|var_dump)" || echo "0"
+```
+
+---
+
+## Step 2 — Safety checks
+
+**Secrets (hard block):** If count > 0, show matched lines and STOP. Do not commit.
+
+**Debug code (soft warn):** If count > 0, show matched lines. Proceed only after user confirms they're intentional.
+
+**Large diff:** If > 10 files or > 300 lines, note: "Large commit — consider splitting for easier review." Continue unless user says to split.
+
+---
+
+## Step 3 — Stage files
+
+Prefer staging specific files by name. Do NOT use `git add -A`.
+
+Never stage: `.env`, credentials, build artifacts, generated files, binaries > 1MB.
+
+---
+
+## Step 4 — Generate commit message
+
+**Format:** `type(scope): description`
+
+| Type | When |
+|------|------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `test` | Tests only |
+| `refactor` | Code change, no behavior change |
+| `chore` | Maintenance, deps, config |
+| `perf` | Performance improvement |
+| `build` | Build system |
+| `ci` | CI/CD changes |
+
+**Breaking changes:** If diff removes/renames a public function, export, or API endpoint → use `feat!` or `fix!` type, or add `BREAKING CHANGE:` footer.
+
+**Rules:** Under 72 chars. Imperative tense ("add" not "added"). No period. WHAT+WHY, not HOW.
+
+**Bad examples — avoid:**
+- ❌ `Updated some files` — not descriptive
+- ❌ `feat(auth): added login validation using bcrypt with salt rounds of 12` — too long, describes HOW
+- ❌ `Fix bug` — not specific
+- ❌ `WIP` — never commit unfinished work
+
+---
+
+## Step 5 — Commit
+
+```bash
+git commit -m "$(cat <<'EOF'
+type(scope): description
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+```
+
+**Do NOT push** unless user explicitly asks.
+
+---
+
+## Output
+
+```
+staged: N files (+X/-Y lines)
+checks: secrets ✓ | debug ✓
+commit: abc1234 type(scope): description
+pushed: no
+```
+
+Keep under 5 lines. No explanations.
+
+## Rules
+1. **Specific files, not `git add -A`.** Stage intentionally.
+2. **Secrets = hard block.** No exceptions.
+3. **Never push without explicit request.**
+4. **One concern per commit.** Mixed features → suggest separate commits.

package/templates/.claude/commands/fix.md

@@ -0,0 +1,95 @@
+Test-first bug fix. Investigate → Reproduce → Fix → Verify → Learn.
+
+Bug: $ARGUMENTS
+
+---
+
+## Phase 0: Investigate
+
+Don't jump to code. Understand the bug first:
+
+1. **Parse the report.** Symptom? Expected vs actual? Repro steps?
+2. **Locate the code.** Grep for keywords from the bug (error messages, function names).
+3. **Check history.** `git log --oneline -5 -- <file>` and `git blame -L <range> <file>` — who changed this last and why?
+4. **Form a hypothesis:** "I believe the bug is caused by [X] in [file:function] because [evidence]."
+
+If the bug is in a dependency/config/data (not our code), say so before proceeding.
+
+---
+
+## Phase 1: Write a Failing Test
+
+Write a test that reproduces the bug. It **MUST fail** with current code.
+
+Add a comment: `// Regression: <bug description> — <expected> vs <actual>`
+
+Run it:
+```
+bash scripts/build-test.sh --filter "<test name>"
+```
+
+- **FAILS** → reproduced. Continue.
+- **PASSES** → hypothesis may be wrong. Ask: "Test passes — need different repro steps or environment details."
+
+---
+
+## Phase 2: Fix
+
+Make the **minimal change** needed.
+
+| Do | Don't |
+|----|-------|
+| Fix the specific bug | Refactor surrounding code |
+| Add a guard for the edge case | Rewrite the function |
+| Explain what and why before editing | Silently change code |
+
+---
+
+## Phase 3: Verify
+
+1. Run the bug test: `bash scripts/build-test.sh --filter "<test name>"` → must PASS.
+2. Run full suite: `bash scripts/build-test.sh` → no regressions.
+
+If other tests break → the fix caused a regression. Investigate. Do NOT weaken existing tests.
+
+---
+
+## Phase 4: Root Cause Analysis
+
+After fixing, document:
+
+```
+Symptom: <what the user saw>
+Root cause: <why it happened>
+Gap: <why not caught earlier — missing test? wrong assumption? missing spec?>
+Prevention: <suggest one: type constraint, validation, lint rule, spec update, or test plan update>
+```
+
+This is non-optional for serious bugs. For trivial bugs, the fix summary is enough.
+
+---
+
+## Phase 5: Summary
+
+```
+Bug: <description>
+Hypothesis: <what you predicted> → <confirmed or actual cause>
+Test added: <file>:<test name>
+Fix: <file>:<lines> — <what changed>
+Root cause: <1 sentence>
+Prevention: <suggestion>
+Full suite: All passing ✓
+```
+
+If the bug reveals an undocumented edge case: "Consider updating the spec at docs/specs/<feature>.md."
+
+## Multiple Bugs
+
+If `$ARGUMENTS` describes multiple bugs: triage by severity, fix one at a time, commit each separately.
+
+## Rules
+1. **Investigate before coding.** Hypothesis before test. Evidence before fix.
+2. **Minimal fix.** One bug, one change. Don't improve the neighborhood.
+3. **Never weaken tests.** If existing tests break, the fix is wrong.
+4. **Ask before touching production code** if unsure.
+5. **One bug, one commit.** Each fix independently revertable.

package/templates/.claude/commands/plan.md

@@ -0,0 +1,141 @@
+Think hard about this task. A bad plan wastes days, a good plan saves weeks.
+
+## Determine mode
+
+Examine `$ARGUMENTS`:
+
+- **Mode A — Spec exists:** Argument is a file path → read spec, generate test plan.
+- **Mode B — No spec:** Argument is a description → create spec + test plan.
+- **Mode C — Update:** Argument mentions "update" or existing path → read existing, update surgically.
+
+---
+
+## Phase 0: Codebase Awareness
+
+Before writing anything:
+1. Scan existing code in the feature area — what files, functions, types already exist?
+2. Check `docs/specs/` — is there already a spec for this or a related feature?
+3. Check `docs/test-plans/` — any overlap with existing plans?
+4. Identify project patterns — test framework, naming conventions, directory structure.
+
+Don't plan in a vacuum. A spec that ignores existing code creates conflicts.
+
+---
+
+## Phase 1: Draft the Spec (Mode B only)
+
+Create at `docs/specs/<feature-name>.md`. Include these sections (skip any that don't apply):
+
+- **Overview** — what, why, who. 2-3 sentences.
+- **Data Model** — entities, attributes, relationships (table format)
+- **Use Cases** — UC-NNN with actor, preconditions, flow, postconditions, error cases. Each use case contains:
+  - **FR-NNN** (Functional Requirements) — specific behaviors the system must exhibit
+  - **SC-NNN** (Success Criteria) — measurable non-functional targets (performance, limits)
+- **State Machine** — states and valid transitions (if applicable)
+- **Settings/Configuration** — configurable behavior and defaults
+- **Constraints & Invariants** — rules that must ALWAYS hold
+- **Error Handling** — how errors surface to users and are logged
+- **Security Considerations** — auth, authorization, data sensitivity
+
+Match depth to complexity. Simple CRUD = 1 paragraph overview + 3 use cases. Complex auth system = full template. Don't generate filler for sections that don't apply.
+
+Show the draft to the user. Wait for confirmation before generating the test plan.
+
+---
+
+## Phase 2: Clarify Ambiguities
+
+Before generating the test plan, scan the spec for gaps. A test plan built on a vague spec produces vague tests.
+
+| Lens | What to look for |
+|------|-----------------|
+| **Behavioral gaps** | Missing user actions, undefined system responses, incomplete flows |
+| **Data & persistence** | Undefined entities, missing relationships, unclear storage/lifecycle |
+| **Auth & access** | Who can do what is unclear, missing role definitions |
+| **Non-functional** | Vague adjectives without metrics ("fast", "secure", "scalable") — add SC-NNN with numbers |
+| **Integration** | Third-party API assumptions, unstated dependencies, SLA gaps |
+| **Concurrency & edge cases** | Multi-user scenarios, boundary conditions, error paths not addressed |
+
+Identify the top 3-5 ambiguities (most impactful first). For each, ask the user a targeted question with 2-4 concrete options and a recommendation.
+
+If the spec is clear and complete, 0 questions is valid. Don't manufacture ambiguity.
+
+Write clarifications back into the spec under `## Clarifications — <date>`.
+Then proceed to test plan generation.
+
+---
+
+## Phase 3: Generate the Test Plan
+
+Read the spec. For each section, extract:
+1. Use cases → at least 1 test (happy path) + 1 test (error path) each
+2. State transitions → test valid AND invalid transitions
+3. Constraints → test they hold under edge conditions
+4. Settings → test default AND non-default values
+5. Cross-cutting concerns (auth, validation) → integration-level tests
+
+Prioritize by risk: data loss/security = P0, error handling = P1, cosmetic/rare = P2.
+
+### Output
+
+Write to `docs/test-plans/<feature-name>.md`:
+
+```markdown
+# Test Plan: <Feature Name>
+
+**Spec:** docs/specs/<feature-name>.md
+**Generated:** <$(date +%Y-%m-%d)>
+
+## Test Cases
+
+| ID | Priority | Type | UC | FR/SC | Description | Expected |
+|----|----------|------|----|-------|-------------|----------|
+| TC-001 | P0 | unit | UC-001 | FR-001 | Valid login returns token | 200 + JWT |
+| TC-002 | P0 | unit | UC-001 | FR-002 | Wrong password returns 401 | 401 + error msg |
+
+## Implementation Order
+1. TC-001, TC-002 (no dependencies — start here)
+2. TC-003+ (depend on setup from earlier tests)
+
+## Coverage Notes
+- Highest risk areas: ...
+- Existing code needing modification: [file paths]
+```
+
+**Priority:** P0 = must have (blocks release), P1 = should have, P2 = nice to have.
+**Type:** `unit`, `integration`, `e2e`, `snapshot`, `performance`
+
+### What NOT to produce
+- "Test that the feature works" — too vague
+- 50+ test cases for simple CRUD — over-testing
+- Testing implementation details — brittle
+- Duplicate tests verifying same behavior
+
+---
+
+## Phase 4: Summary
+
+Show: test case counts (P0/P1/P2), implementation order, estimated scope.
+Next steps: "Use `/test` after each chunk. For complex plans, run `/challenge` first."
+
+## Naming Convention
+
+Spec and test plan MUST share the same filename:
+```
+docs/specs/<feature-name>.md       ← kebab-case, 2-3 words
+docs/test-plans/<feature-name>.md  ← same name
+```
+- Use feature name, not module name: `user-auth.md` not `AuthService.md`
+- No prefix/suffix: `user-auth.md` not `spec-user-auth.md`
+
+**Requirement IDs** — sequential per spec:
+- `UC-001` Use Case, `FR-001` Functional Requirement, `SC-001` Success Criteria, `TC-001` Test Case
+- Every TC must reference at least one FR or SC for traceability.
+
+## Rules
+1. **Spec-first.** Test plan derives from spec, never from code.
+2. **Codebase-aware.** Don't plan features that already exist.
+3. **Actionable.** Every test case must be unambiguous enough to implement directly.
+4. **Proportional.** Simple feature = simple plan. Don't over-engineer CRUD.
+5. **Traceable.** Every test links to a use case. No orphan tests.
+6. **Consistent names.** Spec and test plan always share the same filename.

package/templates/.claude/commands/review.md

@@ -0,0 +1,109 @@
+Think hard about this review. You are the last gate before code reaches the main branch.
+
+## Phase 0: Understand Intent
+
+1. Read commit messages:
+   ```
+   BASE=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||') || BASE="main"
+   git log --oneline "$BASE"...HEAD
+   ```
+2. Check for spec in `docs/specs/` and test plan in `docs/test-plans/` — review against INTENT.
+3. Read the diff: `git diff "$BASE"...HEAD`
+
+If `$ARGUMENTS` provided → scope to those files only.
+If diff > 500 lines → review file-by-file, prioritize by smart focus below.
+
+---
+
+## Phase 1: Smart Focus
+
+Auto-detect primary focus from diff content:
+
+| Diff contains | Focus heavily on |
+|--------------|-----------------|
+| auth, login, token, session, password, JWT | Security — full depth |
+| SQL, query, database, migration | Injection + data integrity |
+| API, endpoint, route, controller, handler | Input validation + error handling |
+| .env, config, secret, key, credential | Secret exposure |
+| Test files only | Test quality (skip security deep-dive) |
+| Docs/comments only | Accuracy only (minimal review) |
+| Payment, billing, transaction | Correctness + idempotency |
+
+Spend 60% of analysis on the primary focus. Cover all categories, but proportionally.
+
+---
+
+## Phase 2: Checklist
+
+### Security (Critical)
+- **Injection:** Search diff for string concatenation in SQL/shell/HTML. Look for `${var}` in queries, `.innerHTML`, template literals in SQL. Flag any user input reaching a query without parameterization.
+- **Auth/Authz:** New endpoint → has auth middleware? Can user A access user B's data? ID in URL without ownership check?
+- **Secrets:** Hardcoded strings matching `sk-`, `ghp_`, `Bearer `, long base64. New env vars committed?
+- **Error exposure:** Catch blocks sending raw errors to users? Stack traces, file paths, DB schemas in responses?
+- **Dependencies:** New packages — maintained? >1000 weekly downloads? Known CVEs?
+
+### Correctness (High)
+- **Logic vs intent:** Does the code do what commits/spec claim? "Add validation" but code just logs?
+- **Edge cases:** null, empty, 0, negative, MAX_INT, unicode, very long strings — handled?
+- **Error handling:** For each try/catch — error logged with context? User shown safe message? Resources cleaned in finally?
+- **Concurrency:** Shared state without locks? Read-then-write without atomicity? Non-atomic DB updates?
+- **Null safety:** Optionals used without guards? `object!.property` without nil check?
+
+### Spec-Test Alignment (Medium)
+- Source changed but no spec update in `docs/specs/`? → flag
+- Source changed but no test update? → flag
+- Spec changed but tests not updated? → flag
+- Code removed but dead tests remain? → flag
+- Spec contains vague requirements without metrics ("fast", "secure", "easy", "scalable")? → flag with suggestion to add SC-NNN with concrete numbers
+
+### Code Quality (Medium)
+- Dead code: removed functions still imported elsewhere?
+- Obvious duplication: copy-pasted blocks that should be shared?
+- Naming: consistent with codebase? Descriptive?
+- Complexity: functions > 40 lines or > 3 nesting levels?
+
+### Performance (Low)
+- Flag N+1 queries, unbounded collections, redundant computation in loops.
+
+---
+
+## Phase 3: Output
+
+```markdown
+## Code Review: <branch or description>
+
+**Scope:** X files, +Y/-Z lines
+**Focus:** <auto-detected>
+**Verdict:** APPROVE / REQUEST CHANGES / NEEDS DISCUSSION
+
+### Critical Issues
+**[C-1] file.ts:42 — SQL injection via unsanitized input**
+`req.query.search` concatenated into SQL. Use parameterized query.
+
+### High Priority
+**[H-1] file.ts:87 — Empty catch swallows DB errors**
+Users see blank screen. Log with context, return safe error.
+
+### Medium Priority
+**[M-1] Spec-test gap — rate limiting not in spec**
+New logic at auth-service.ts:45-62 undocumented.
+
+### Low Priority
+**[L-1] Consider caching config lookup (called 3x per request)**
+
+### Positive Notes
+(At least 1 — reinforce good patterns)
+- Clean middleware separation in auth-middleware.ts
+- Thorough edge case tests
+
+### Summary
+<1-2 sentences: quality + clear next action>
+```
+
+## Rules
+1. **Never auto-fix.** Report only.
+2. **Specific.** Every finding has `file:line` and concrete description.
+3. **Severity matches impact.** Style nits = Low. Injection = Critical.
+4. **Positive notes mandatory.** Reviews aren't just about problems.
+5. **Review against intent.** Not just "clean code?" but "does this match spec/commits?"
+6. **Proportional.** 5-line doc change ≠ 500-line auth rewrite.