feat: add /speckit.review command — staff-level code review

[arunt14]

Description

Problem

Spec-Kit guides teams through spec → plan → tasks → implement, but has no built-in code review step after implementation. Once /speckit.implement completes, there is no structured way to validate that the code is correct, secure, performant, and faithful to the specification. Teams either skip review entirely or rely on ad-hoc processes, creating a quality gap between implementation and shipping.

The community review extension exists but is not part of core, meaning most users don't benefit from it. A core review command ensures every spec-driven project has a quality gate built into the workflow.

Industry context: GStack's /review command demonstrates that embedding a staff-engineer-level review directly in the AI workflow catches issues that informal review misses — particularly security vulnerabilities, spec deviations, and performance regressions.

Solution

Adds /speckit.review — a new core command that performs a thorough, staff-engineer-level code review through 5 structured passes:

1. Correctness & Logic — spec compliance, boundary conditions, null handling, race conditions, state management
2. Security — injection vulnerabilities, auth checks, hardcoded secrets, input sanitization, CORS/CSP headers
3. Performance & Scalability — N+1 queries, unbounded loops, resource leaks, caching correctness
4. Spec Compliance & Architecture — requirement coverage matrix, API contract validation, scope creep detection
5. Test Quality — coverage gaps, assertion quality, test isolation, untested error paths

Output: Structured review report with severity levels (🔴 Blocker / 🟡 Warning / 🟢 Suggestion), spec coverage matrix, and verdict (APPROVED / APPROVED WITH CONDITIONS / CHANGES REQUIRED).

Business Value

• Creates a mandatory quality gate between implementation and shipping — the most critical checkpoint in any development workflow
• Catches security vulnerabilities early with a dedicated security review pass before code reaches production
• Ensures spec fidelity by cross-referencing every requirement against the actual implementation
• Reduces review burden on human reviewers by having the AI agent surface high-signal issues first
• Completes the post-implementation workflow: implement → review → qa → ship

Workflow Position

/speckit.implement → /speckit.review ⭐ → /speckit.qa → /speckit.ship → /speckit.retro

Files Added

File	Purpose
templates/commands/review.md	Command template with 5 review passes, severity classification, extension hooks (before_review, after_review)
templates/review-template.md	Structured review report template with findings table, spec coverage matrix, and metrics

Testing

• Tested locally with uv run specify --help
• Ran existing tests with uv sync && uv run pytest — 878/972 pass (44 failures are pre-existing, unrelated to this change)
• Verified YAML frontmatter is valid and parseable
• Verified command file is auto-discovered by specify init
• Confirmed no changes to Python source code — template-only addition

AI Disclosure

• AI assistance was used in this PR
• How: GitHub Copilot CLI (Claude) was used to draft the command template and output template content, following the existing patterns established by implement.md and analyze.md. All content was reviewed and validated against the project's template conventions.

---

Note: Happy to discuss the scope and approach with maintainers. This is one of five related-but-independent PRs adding lifecycle commands inspired by GStack's role-based workflow.

[Copilot]

Pull request overview

Adds a new /speckit.review command template and an accompanying review report template to introduce a structured, staff-level implementation review step in the spec-driven workflow.

Changes:

• Added templates/commands/review.md defining a 5-pass review procedure plus extension hook support (before_review / after_review).
• Added templates/review-template.md to standardize the Markdown output report structure (findings table, coverage matrix, metrics, actions).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
templates/commands/review.md	Introduces the /speckit.review command workflow and hook integration points.
templates/review-template.md	Provides the Markdown report skeleton used by /speckit.review.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The tables use a leading double pipe (|| ... |), which renders as an extra empty column in Markdown (and may fail markdownlint). Use a single leading pipe and ensure the header separator row has the same number of columns as the header.

[Copilot]

This spec coverage matrix table has the same || leading-pipe issue as the findings table, which breaks table rendering. Replace || with | for the header, separator, and data rows.

[Copilot]

The test coverage assessment table header starts with ||, which adds an unintended blank column in Markdown table rendering. Use a single leading | consistently.

[Copilot]

The metrics summary table has an extra leading pipe (|| Metric | Value |), which will misalign the table (extra empty column). Use the standard single leading pipe format to keep columns consistent.

[Copilot]

Step 10 references "the review report template" but doesn’t name the concrete template file (unlike other commands that reference templates/*-template.md). Point explicitly to templates/review-template.md and ensure FEATURE_DIR/reviews/ is created if missing. Also specify a filesystem-safe timestamp format (e.g., YYYYMMDD-HHMMSS) to avoid characters like : that break on Windows.

Suggested change

	Create the review report at `FEATURE_DIR/reviews/review-{timestamp}.md` using the review report template. The report must include:
	Create the review report in a new file at `FEATURE_DIR/reviews/review-{YYYYMMDD-HHMMSS}.md` using the `templates/review-template.md` review report template. Ensure the `FEATURE_DIR/reviews/` directory exists (create it if necessary). The report must include:

[mnriem]

Please deliver this as an extension. See https://github.com/github/spec-kit/tree/main/extensions

[arunt14]

Thanks for the review! Addressed in the latest push:

1-4. Double-pipe table issue: Investigated and confirmed the tables in review-template.md already use correct single-pipe format — no || leading pipes exist in the actual file content. This may have been a rendering artifact in the diff view.
5. Step 10 template reference: Now explicitly references templates/review-template.md, ensures FEATURE_DIR/reviews/ directory is created if missing, and uses a filesystem-safe timestamp format (YYYYMMDD-HHMMSS) to avoid issues with : on Windows.

[mnriem]

Please review https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-PUBLISHING-GUIDE.md for publishing a community hosted extension

[arunt14]

Thanks @mnriem! I've reviewed the Extension Publishing Guide. Will restructure this as a community extension following the extension.yml manifest pattern and resubmit as an extension contribution to catalog.community.json.

[arunt14]

Re: the double-pipe (||) table comments - I've re-inspected the raw file content of review-template.md line by line and confirmed there are no double leading pipes anywhere. All tables consistently use single | format. This appears to have been a rendering artifact in the diff view. Happy to take another look if you can point to a specific line that still shows the issue.

[arunt14]

Closing in favor of PR #2049 — restructured as a community extension per maintainer feedback. Extension repo and v1.0.0 release are available.