Add review-plan and review-spec skills
Two new read-only skills that review plans and specs against best practices: - /review-plan: Checks plans against 6 areas (security, API design, LLM code security, spec-driven dev, TDD, operational readiness). Outputs scorecard with critical gaps and recommendations. - /review-spec: Checks specs for structure quality, requirement testability, security coverage, and API design patterns. Scores 5 dimensions and identifies missing requirements and scenarios. Both load api-design.md, llm-code-security.md, spec-driven-development.md, test-driven-development.md, and security-architecture.md from best-practices. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Paul O'Reilly
149
skills/review-spec/SKILL.md
Normal file
149
skills/review-spec/SKILL.md
Normal file
@@ -0,0 +1,149 @@
|
||||
---
|
||||
name: review-spec
|
||||
description: >
|
||||
Review a spec file against best practices: API design, LLM code security, spec-driven
|
||||
development, test-driven development, and security architecture. Checks spec structure,
|
||||
requirement quality, security coverage, and testability. Invoke with the spec filename,
|
||||
e.g. /review-spec spec/authentication.md
|
||||
allowed-tools: Read, Glob, Grep, Bash(cat *), Bash(ls *), Bash(find *)
|
||||
---
|
||||
|
||||
# Spec Review Skill
|
||||
|
||||
You are reviewing the spec file **$ARGUMENTS** against established best practices.
|
||||
|
||||
## Pre-gathered context
|
||||
|
||||
### Best practices index
|
||||
!`cat ~/dev/claude/BESTPRACTICES.md 2>/dev/null || echo "BESTPRACTICES.md not found"`
|
||||
|
||||
### Spec index (if exists)
|
||||
!`cat SPEC.md 2>/dev/null || echo "No SPEC.md found"`
|
||||
|
||||
### Spec file to review
|
||||
(Use the Read tool to read the spec file specified in $ARGUMENTS. If no filename is given, read SPEC.md and ask which spec to review.)
|
||||
|
||||
## Best practice files to load
|
||||
|
||||
Read ALL of the following best practice files before starting the review:
|
||||
|
||||
1. `~/dev/claude/projects/best-practices/spec-driven-development.md` -- Spec structure, requirements, scenarios, writing guidelines
|
||||
2. `~/dev/claude/projects/best-practices/test-driven-development.md` -- Test derivation, edge cases, property testing
|
||||
3. `~/dev/claude/projects/best-practices/api-design.md` -- Transport security, auth, API patterns, input validation, zero-trust
|
||||
4. `~/dev/claude/projects/best-practices/llm-code-security.md` -- LLM-generated code vulnerabilities, review checklists
|
||||
5. `~/dev/claude/projects/best-practices/security-architecture.md` -- Server boundary rule, credential proxying
|
||||
|
||||
Also read any additional best practice files relevant to the spec's technology stack (check the index for Kubernetes, Helm, Docker, secrets management, etc.).
|
||||
|
||||
## Review: spec structure quality
|
||||
|
||||
Evaluate the spec against the required structure from spec-driven-development.md:
|
||||
|
||||
### Required sections
|
||||
|
||||
- [ ] **Overview** -- 2-3 sentences, clear purpose. An agent knows if this spec is relevant after reading this.
|
||||
- [ ] **Responsibilities** -- What this subsystem owns AND what it delegates. Prevents scope creep.
|
||||
- [ ] **Dependencies** -- Which other specs to read. Links present and correct.
|
||||
- [ ] **Data Model** -- Types, schemas, state machines, interfaces with concrete examples (not just abstract schemas).
|
||||
- [ ] **Requirements** -- Numbered with a consistent prefix (e.g., AU-1, CP-1). Each independently testable.
|
||||
- [ ] **Scenarios** -- Given/when/then format. Cover happy path AND failure modes.
|
||||
|
||||
### Optional sections (flag if missing but relevant)
|
||||
|
||||
- [ ] **Interface** -- API surface, endpoints, signatures (required if the subsystem has an external API)
|
||||
- [ ] **Extension Points** -- How to add capabilities without modifying existing code
|
||||
- [ ] **Error Handling** -- Failure modes and expected behaviour (prevents agents inventing strategies)
|
||||
|
||||
## Review: requirement quality
|
||||
|
||||
For each numbered requirement, check:
|
||||
|
||||
- [ ] **Testable** -- Can an agent write a test that unambiguously passes or fails?
|
||||
- [ ] **Unambiguous** -- No "should", "appropriate", "handle errors gracefully". Specific exit codes, status codes, timeouts.
|
||||
- [ ] **Includes rationale** -- Why this requirement exists (the "Why:" line). Without it, agents follow mechanically and can't judge edge cases.
|
||||
- [ ] **No duplicates** -- Same requirement doesn't appear under different numbers.
|
||||
- [ ] **Complete coverage** -- Are there obvious behaviours that lack requirements?
|
||||
|
||||
Count the requirements and verify any summary counts in the spec are accurate.
|
||||
|
||||
## Review: security coverage
|
||||
|
||||
Check the spec against API design and security best practices:
|
||||
|
||||
### Authentication and authorization
|
||||
- [ ] Auth model specified for every endpoint (who can call it, what credential, how validated)
|
||||
- [ ] Service-to-service auth uses mTLS or short-lived tokens (not shared static keys)
|
||||
- [ ] Human auth uses OIDC/OAuth2 with PKCE (not implicit flow, not password grant)
|
||||
- [ ] Token validation is complete (signature, expiry, issuer, audience, algorithm pinned)
|
||||
|
||||
### Transport and data protection
|
||||
- [ ] TLS required (or explicit justification for plaintext)
|
||||
- [ ] Secrets never in payloads, URLs, query params, or logs
|
||||
- [ ] Secrets passed via env vars or mounted files
|
||||
- [ ] Error responses don't expose internals
|
||||
|
||||
### Input validation
|
||||
- [ ] All external inputs validated (types, lengths, ranges, formats)
|
||||
- [ ] Parameterized queries for database access (no string concatenation)
|
||||
- [ ] Request size limits specified
|
||||
|
||||
### API patterns (if the spec defines an API)
|
||||
- [ ] Pagination on list endpoints with enforced max page size
|
||||
- [ ] Idempotency for POST endpoints
|
||||
- [ ] Rate limiting mentioned or deferred with a reference
|
||||
- [ ] Structured error responses with stable codes
|
||||
- [ ] API versioning strategy
|
||||
|
||||
### Infrastructure security (if the spec involves K8s/containers)
|
||||
- [ ] securityContext specified (runAsNonRoot, readOnlyRootFilesystem, drop ALL capabilities)
|
||||
- [ ] Resource limits defined
|
||||
- [ ] NetworkPolicy specified or referenced
|
||||
- [ ] No privileged containers
|
||||
- [ ] Images pinned to digest or specific version
|
||||
|
||||
## Review: testability
|
||||
|
||||
Evaluate how well this spec supports test-driven development:
|
||||
|
||||
- [ ] Every requirement maps to at least one testable assertion
|
||||
- [ ] Scenarios cover both happy path and failure modes
|
||||
- [ ] Edge cases identified (boundary values, empty inputs, concurrent access, timeout)
|
||||
- [ ] Data model examples are concrete enough to use as test fixtures
|
||||
- [ ] Extension points describe how to test new extensions
|
||||
|
||||
## Output format
|
||||
|
||||
Structure your review as:
|
||||
|
||||
### Summary
|
||||
One paragraph: overall quality of the spec and its readiness for implementation.
|
||||
|
||||
### Scorecard
|
||||
|
||||
| Area | Score | Notes |
|
||||
|------|-------|-------|
|
||||
| Structure completeness | 1-5 | ... |
|
||||
| Requirement quality | 1-5 | ... |
|
||||
| Security coverage | 1-5 | ... |
|
||||
| Testability | 1-5 | ... |
|
||||
| Clarity for AI agents | 1-5 | ... |
|
||||
|
||||
(1 = major gaps, 3 = adequate, 5 = exemplary)
|
||||
|
||||
### Critical issues
|
||||
Numbered list of problems that would cause implementation failures or security vulnerabilities. Each includes:
|
||||
- The specific section/requirement with the issue
|
||||
- What best practice it violates
|
||||
- A concrete fix
|
||||
|
||||
### Missing requirements
|
||||
Requirements that should exist but don't. Suggest a requirement ID and text for each.
|
||||
|
||||
### Missing scenarios
|
||||
Scenarios that should exist but don't. Provide given/when/then for each.
|
||||
|
||||
### Recommendations
|
||||
Non-blocking improvements that would strengthen the spec.
|
||||
|
||||
### What's done well
|
||||
Specific sections or requirements that are exemplary -- reinforces good patterns for future specs.
|
||||
Reference in New Issue
Block a user