CommunityProductivity & Collaborationgithub.com

spec-gatekeeper

Conducts a focused 4-question developer interview and drafts a deterministic 4-section SPEC.md (Scope & Security, Data Contracts, Edge Cases, Acceptance Criteria) before writing source code.

What is spec-gatekeeper?

spec-gatekeeper is a Claude Code agent skill that conducts a focused 4-question developer interview and drafts a deterministic 4-section SPEC.md (Scope & Security, Data Contracts, Edge Cases, Acceptance Criteria) before writing source code.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/dansierrasam79/spec-gatekeeper/tree/main/skills/spec-gatekeeper

Installed? Explore more Productivity & Collaboration skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

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):

  1. 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?
  2. Data Contracts:

    • What are the exact schemas, API interfaces, types, and protocol shapes?
    • What are the precise input parameters and expected output payloads?
  3. 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?
  4. 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:

  1. Size Requirement: At least 300 UTF-8 bytes of substantive content.
  2. 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, or Permissions.
    • Data Contracts: Headings containing Data Contract, Data Contracts, Schema, Schemas, Interface, Interfaces, API, Types, Payload, or Protocol.
    • Edge Cases: Headings containing Edge Case, Edge Cases, Error Handling, Failure Mode, Failure Modes, Resilience, Constraints, or Fallbacks.
    • Acceptance Criteria: Headings containing Acceptance Criteria, Acceptance Test, Test Matrix, Verification, Testing, Definition of Done, or Validation.

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

  1. Present the draft SPEC.md to the developer for review and explicit sign-off.
  2. Once SPEC.md is committed and valid (>= 300 bytes with all 4 sections), the spec-gatekeeper hook will automatically permit implementation source files to be written.

Related Skills