| name | specgates |
| description | Spec-driven quality gates (SpecKit) for Claude Code. Enforces specification verification before implementation, test coverage requirements, and acceptance criteria checks. Use when building features that require formal specifications or quality assurance workflows. |
CLAUDE-specgates.md
Spec-driven quality gates and conventions
Inspired by GitHub Spec Kit. These are native GIR conventions, not SpecKit dependencies.
Clarification Gate
When: Between Plan and Code phases. Before any non-trivial feature implementation begins.
Skip for: Single-file bug fixes, styling changes, copy updates, config changes.
Scan planned work against these 10 categories. Rate each Clear / Partial / Missing. Implementation MUST NOT start if any category is Missing.
| # | Category | What to Verify |
|---|
| 1 | Functional scope | All user actions defined? |
| 2 | Data model | Entities, fields, relationships specified? |
| 3 | UX flow | User paths from entry to completion documented? |
| 4 | Non-functional | Performance, security, accessibility targets set? |
| 5 | Integrations | External API contracts and error handling defined? |
| 6 | Edge cases | Failure modes and boundary conditions enumerated? |
| 7 | Constraints | Budget, timeline, tech constraints stated? |
| 8 | Terminology | Ambiguous terms defined consistently? |
| 9 | Completion signals | How do we know this feature is done? |
| 10 | State transitions | For stateful features: lifecycle documented? |
[NEEDS CLARIFICATION] Markers
When a requirement is ambiguous during planning, mark it inline with [NEEDS CLARIFICATION].
Rules:
- Max 3 per feature
- Priority: scope > security > UX > technical
- ALL must be resolved before coding begins
- Use
AskUserQuestion to resolve — never guess
Acceptance Criteria Convention
Every non-trivial feature MUST include Given/When/Then acceptance scenarios. These are the definition of done.
Format (use inline in TodoWrite items or task descriptions):
## Feature: [Name]
### Acceptance
- Given [precondition]
When [action]
Then [expected outcome]
- Given [edge case]
When [action]
Then [expected outcome]
Rules:
- Minimum 2 scenarios per feature (happy path + one edge case)
- Each scenario must be independently testable
- At least one negative/error scenario for user-facing features
- Reference specific business rules from .gir/CLAUDE-activeContext.md where applicable
Task Format Conventions
Parallel Safety Markers
Mark parallelizable tasks with [P]. Always include target file paths.
- [ ] [P] Implement feature A — src/components/FeatureA.tsx
- [ ] [P] Add analytics metrics — src/pages/analytics.tsx
- [ ] Shared middleware update — src/middleware.ts (NOT parallel — shares file)
Tasks without [P] are sequential by default. Tasks marked [P] MUST NOT share files with other [P] tasks.
Phased Task Structure
For multi-task features, organize into 4 phases:
| Phase | Name | Execution | Contents |
|---|
| 1 | Setup | Sequential | Dependencies, config, scaffolding |
| 2 | Foundational | Sequential, blocking | DB migrations, shared types, API contracts |
| 3 | User Stories | Parallelizable [P] | Feature work grouped P1→P2→P3 |
| 4 | Polish | Sequential | Cross-cutting improvements, cleanup |
Rule: No Phase 3 work begins until Phase 2 is complete.
Example:
## Phase 1: Setup
- [ ] Install dependencies — package.json
## Phase 2: Foundational (blocking)
- [ ] Create DB migration — migrations/
- [ ] Add shared types — types/
## Phase 3: User Stories
- [ ] [P] [US1] Feature page — src/pages/feature.tsx
- [ ] [P] [US2] Settings panel — src/pages/settings.tsx
- [ ] [US3] API handler — src/api/handler.ts
## Phase 4: Polish
- [ ] Verify security policies
- [ ] Update .gir/CLAUDE-activeContext.md
State Machine Convention
For any feature with >3 states, document the state machine BEFORE implementation.
Format:
[state_a] --trigger--> [state_b]
[state_b] --trigger--> [state_c]
Then add a table showing user-facing impact per state:
| State | What user sees | What's allowed | Notes |
|---|---|---|---|
| state_a | ... | ... | ... |
Projects should maintain a CLAUDE-statemachines.md file for their state machine reference.
spec-analyst Agent
Cross-artifact consistency auditor. Detects drift, gaps, and contradictions across GIR docs.
When: Before phase transitions, after major scope changes, when docs feel stale.
Process:
- Read: ROADMAP.md, active TASKS.md files, .gir/CLAUDE-decisions.md, .gir/CLAUDE-activeContext.md
- Run 6 analysis passes (cap at 30 findings):
- Coverage: Every ROADMAP item has corresponding task entries
- Consistency: No terminology drift between docs
- Decision compliance: Patterns match .gir/CLAUDE-decisions.md
- Orphans: No task items that don't trace to a roadmap item
- Staleness: No completed items still listed as pending
- Business rule alignment: .gir/CLAUDE-activeContext.md rules reflected in task acceptance criteria
- Output findings table with severity (CRITICAL / HIGH / MEDIUM / LOW)
- Suggest specific fixes with file:line references
Output format:
| # | Severity | File | Finding | Suggested Fix |
|---|---|---|---|---|
| 1 | CRITICAL | ROADMAP.md:42 | Feature X has no task entries | Create tasks |
| 2 | HIGH | .gir/CLAUDE-activeContext.md:125 | Terminology drift | Standardize |
Principles: Strict read-only. Never edit files during analysis. Cite file:line for every finding.
Invocation: "Run spec-analyst" or "Audit GIR docs for consistency"
Updated: 2026-02-22
