Spec-Gatekeeper: Spec-Driven Development Workflow
Use this skill whenever a source code write is blocked by spec-gatekeeper, or whenever starting a new feature, service, or major refactor.
Spec-Driven Development (SDD) ensures clarity and eliminates drift by requiring an agreed-upon, structured architectural contract before implementation begins.
Workflow Steps
Step 1: Conduct the 4-Question Developer Interview
Before writing any code or stubbing files, ask the developer the following 4 focused questions (or extract answers from existing requirements and ask for confirmation):
-
Scope & Security:
- What are the core goals and explicit non-goals of this task?
- What architectural components or system boundaries are involved?
- What are the security, permissions, authentication, or sandbox constraints?
-
Data Contracts:
- What are the exact schemas, API interfaces, types, and protocol shapes?
- What are the precise input parameters and expected output payloads?
-
Edge Cases & Resilience:
- What are the key failure modes, network/IO interruptions, and malformed inputs?
- What error handling, validation, and fallback mechanisms must be in place?
-
Acceptance Criteria:
- What deterministic verification matrix and test cases define "Done"?
- How will each acceptance criterion be validated?
Step 2: Draft SPEC.md
Create or update SPEC.md at the resolved project root (<repo_root>/SPEC.md).
Required Structure
The specification file must satisfy:
- Size Requirement: At least 300 UTF-8 bytes of substantive content.
- Canonical Section Headings: Level 1 through 3 Markdown headings outside code blocks matching each of the 4 required sections:
- Scope & Security: Headings containing
Scope,Security,Architecture,Overview,Boundaries,Threat Model, orPermissions. - Data Contracts: Headings containing
Data Contract,Data Contracts,Schema,Schemas,Interface,Interfaces,API,Types,Payload, orProtocol. - Edge Cases: Headings containing
Edge Case,Edge Cases,Error Handling,Failure Mode,Failure Modes,Resilience,Constraints, orFallbacks. - Acceptance Criteria: Headings containing
Acceptance Criteria,Acceptance Test,Test Matrix,Verification,Testing,Definition of Done, orValidation.
- Scope & Security: Headings containing
Template
# Specification: <Feature or Service Name>
## 1. Scope & Security
### Goals & Architectural Boundaries
- Detailed scope description...
### Security & Threat Model
- Permission checks and security boundaries...
## 2. Data Contracts
### Schemas & Interfaces
- Types, API signatures, request/response formats...
## 3. Edge Cases & Resilience
### Error Handling & Fallbacks
- Boundary conditions, input validation, failure modes...
## 4. Acceptance Criteria
### Verification & Test Matrix
- AT-01: ...
- AT-02: ...
Step 3: Developer Sign-Off & Implementation
- Present the draft
SPEC.mdto the developer for review and explicit sign-off. - Once
SPEC.mdis committed and valid (>= 300 bytes with all 4 sections), thespec-gatekeeperhook will automatically permit implementation source files to be written.