skills.rest
s3nex-com
s3nex-comCOMMUNITY
Explore all skills by this author →
GitHub

specification-driven-development

Define and freeze API contracts before implementation begins.

Updated Apr 8, 2026
Search Tags:#openapi#graphql#asyncapi#protobuf#contract-first#api-design#contract-review
One-click install
npx skills add https://github.com/s3nex-com/sdlc-skills-library --skill specification-driven-development-s3nex-com
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: specification-driven-development
Source: https://github.com/s3nex-com/sdlc-skills-library/tree/main/skills/phase1/specification-driven-development
Command: npx skills add https://github.com/s3nex-com/sdlc-skills-library --skill specification-driven-development-s3nex-com

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires pyyaml, openapi-spec-validator, and includes scripts (resource) and references (resource) components.

What problem does it solve?

Governs contract-first and specification-driven development — defining interfaces, schemas, and workflows before implementation begins. The contract is the truth; code is secondary, and deviations trigger contract reviews and ADRs.

Core Features & Use Cases

  • Creates and freezes API contracts for OpenAPI, Protobuf, AsyncAPI, GraphQL, and related schemas.
  • Provides a structured process for contract reviews, versioning, and change management with an auditable trail.
  • Integrates with scripts and references to validate, compare, and publish frozen contracts across REST, gRPC, events, and data schemas.
  • Enables deterministic collaboration between teams by documenting publication and migration steps for breaking changes.
  • Example-driven guidance for rendering consumer-friendly documentation and governance artifacts.

Quick Start

Create your API contract first (OpenAPI/Proto/AsyncAPI/GraphQL), freeze it, then implement to that spec.

Frequently Asked Questions about specification-driven-development

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
What is contract-first API development and when should I use it?▼

Contract-first API development defines interfaces, schemas, and workflows before implementation begins. You should use it to orchestrate cross-team contracts, versioning, freezing, and change management across REST, gRPC, events, and GraphQL, ensuring code adheres to the specified truth.

How do I freeze and validate an OpenAPI or AsyncAPI contract?▼

You can freeze and validate OpenAPI, AsyncAPI, Protobuf, or GraphQL contracts using provided scripts and reference materials. The process applies deterministic contract creation and validation workflows, establishing an auditable trail for formal contract reviews and change classification.

Does this skill support change management and versioning for gRPC and GraphQL?▼

Yes, this skill supports change management and versioning for gRPC, GraphQL, REST, and event-driven schemas. It provides a structured process for contract reviews and documents publication and migration steps for breaking changes, enabling deterministic collaboration between teams.

What is the best way to manage breaking changes across cross-team API contracts?▼

The best way to manage breaking changes is through a formal review checklist and change classification using provided scripts. This skill enables deterministic collaboration by documenting publication and migration steps, ensuring deviations trigger contract reviews and architecture decision records.

Do I need openapi-spec-validator to review and publish API contracts?▼

Yes, openapi-spec-validator and pyyaml are required dependencies to validate, compare, and publish frozen contracts. These dependencies enable the skill to perform deterministic contract creation, validation, and rendering of consumer-friendly documentation and governance artifacts.

Why should I define API schemas before writing any implementation code?▼

Defining API schemas before implementation ensures the contract remains the truth and code is secondary. This specification-driven approach prevents integration issues by validating interfaces first, triggering formal contract reviews and ADRs whenever implementation deviates from the frozen contract.

Related Skills

Explore More Software Engineering Skills→
SensLiaoSensLiao

qa-contract-api

Test API contracts with OpenAPI, Pact, AsyncAPI, and GraphQL specifications.

Community
Advanced
robit-manrobit-man

regression-api-contract

Detect breaking changes in REST, GraphQL, and gRPC API contracts.

Community
Advanced
proffesor-for-testingproffesor-for-testing
436

contract-testing

Verify microservice API providers against consumer-driven Pact contracts in CI/CD pipelines.

Community
Advanced
dieu-donneedieu-donnee

spec-miner

Reverse-engineer codebases into formal EARS specification artifacts.

Community
Advanced