spec-tests-first

Show SDD progress across all specs in the current project, or drill into one feature's per-AC status. Reads docs/specs/*/spec-status.md and renders a pass/fail/blocked/stale summary table. Read-only — never modifies files.

Reviews code for quality issues similar to SonarQube — maintainability, cyclomatic complexity, code smells, duplication, naming clarity, dead code, magic numbers, deep nesting, missing error handling, inconsistent patterns, and test coverage gaps. Use PROACTIVELY whenever significant code changes are made (new features, refactors, large diffs) and whenever the user asks to "review code quality", "check maintainability", "find code smells", "audit complexity", or "check for tech debt". Read-only — never modifies files. Does NOT handle security vulnerabilities; those are out of scope and routed to security-reviewer.

Aggregates the outputs of code-quality-reviewer and security-reviewer into a single timestamped Markdown report saved to ./reports/code-review_<timestamp>.md. Use AFTER both reviewers have produced their findings — invoke this agent and pass the two reviewer outputs in the prompt. Trigger phrases include "generate code review report", "save review findings", "create review report", "combine review outputs", "write review report to disk". Performs NO code analysis itself; only faithful aggregation, formatting, and persistence.

Reviews code for security vulnerabilities and exposure risks — injection (SQL/NoSQL/command/template), XSS, CSRF, SSRF, XXE, path traversal, broken access control, insecure deserialization, weak crypto, hardcoded secrets, vulnerable dependencies, insecure configs, missing security headers, CORS misconfig, unsafe input handling, JWT misuse, and OWASP Top 10 issues in general. Use PROACTIVELY before any deploy, merge to main, or release; whenever authentication, authorization, session handling, input parsing, file upload, deserialization, or sensitive-data code is added or modified; and whenever the user asks to "security review", "check for vulnerabilities", "audit for OWASP issues", "scan for secrets", "find security bugs", "do a sec review", or similar. Read-only — never patches code. Does NOT cover code-quality / maintainability concerns; those are routed to code-quality-reviewer.

Runs the project's test command, parses the output, and returns a strict JSON summary keyed by AC-ID. Invoked by /spec-tests-first:build's per-AC red-green-refactor loop (RED, GREEN, REFACTOR, REGRESSION CHECK steps), /spec-tests-first:review's pre-flight green check, and /spec-tests-first:fix's per-fix regression check. Read-only — never writes files; the parent skill owns spec-status.md and any other writes.

Phase 2 of the SDD cycle. Use when the user invokes /spec-tests-first:build <feature> to implement the spec at docs/specs/<feature>/spec.md using per-AC red-green-refactor. Detects test framework + layout profile (12 built-in stack profiles plus a `custom` fallback; multi-service-aware for monorepos via per-service blocks in CLAUDE.md), scaffolds the test root (or no-op for co-located profiles), iterates ACs one-by-one writing a single failing test, watching RED via test-runner, writing minimal implementation, watching GREEN, then a regression check across the feature suite. Cap=3 attempts per AC; commits the whole feature once at the end. /spec-tests-first:tests is now a deprecation shim — this skill owns test scaffolding + writing under per-AC RGR.

Phase 4 of the SDD cycle. Use when the user invokes /spec-tests-first:fix <feature> to walk through findings in the latest /spec-tests-first:review report. Reads ./reports/code-review_<feature>_*.md (resolved via spec-status.md's `Latest review:` pointer), iterates findings severity-then-file, asks the user (fix / custom / skip / defer / quit) per finding, applies the edit, dispatches test-runner to re-check the feature's tests, reverts that single edit if any AC regresses, mutates the report's `Status:` field in place, atomic-commits each successful fix, gates on Critical findings before allowing /spec-tests-first:validate, and (recommended) re-runs /spec-tests-first:review at the end. Resumable — re-invoking picks up at the first finding still marked `pending`.

Pre-cycle skill for spec-tests-first. Use when the user invokes /spec-tests-first:init to set up STF on a repository — auto-detects whether to run Case A (fresh repo, fresh project), Case B (existing codebase, no specs), or Case C (existing repo with flat specs requiring migration). Seeds CLAUDE.md (## Test commands +

Phase 3 of the SDD cycle. Use when the user invokes /spec-tests-first:review <feature> to run a code-quality + security review on the feature's changed files. Dispatches code-quality-reviewer and security-reviewer in parallel against the file list, aggregates via code-reporter, and writes ./reports/code-review_<feature>_<ts>.md with stable finding-IDs (SEC-NNN / QUA-NNN) and a per-finding `Status: pending` line. Read-only — never edits source files. Updates docs/specs/<feature>/spec-status.md only to set the `Latest review:` pointer to the new report path. Does NOT gate progress (no BLOCK/CAUTION/GO); the Critical gate lives in /spec-tests-first:fix.

Orchestrator for the full SDD cycle. Use when the user invokes /spec-tests-first:run <feature> to chain spec → build → review → fix → validate → ship end-to-end. Pauses for explicit user confirmation between every phase (y / edit / skip / stop where applicable). Resumable — detects existing artifacts (spec.md, spec-status.md showing all ACs pass, review report, fix-log progress, validation block) and offers to skip already-completed phases.