The to-spec Skill: What It Writes and When to Skip It
How Matt Pocock's /to-spec skill turns a planning conversation into a spec issue, what its template leaves out, and when a spec is not worth the step.
Spec-First Library
Spec Coding Blog
Practical articles for teams using spec-first delivery. The focus is on writing clearer requirements, tightening review loops, and shipping with fewer surprises.
From the editors
New here? Start with the spec-first guide — API contracts, acceptance criteria, and the case studies all build on it. We publish when a piece survives our own review gate, not on a schedule.
All Articles
Filter by topic. Start with the article closest to your current delivery risk — each one links onward to the related routes.
Harness Engineering vs Spec-Driven Development
What harness engineering means for AI coding agents, how it differs from spec-driven development, and how to run both.
AGENTS.md for Spec-First Teams: What Belongs In It
AGENTS.md is a README for coding agents. The hard part is the boundary: which rules are true for every change, and which belong in a spec for one change.
Cursor Rules: The Four Types and When Each Fires
A Cursor rule that never fires is worse than no rule. Three frontmatter fields decide which of the four types you wrote, and most teams write the dead one.
Spec-First Workflow for AI Agent Teams
A five-stage spec-first workflow for teams running AI coding agents: spec packets, bounded tasks, write scopes, evidence gates, and PR review that scales.
MCP Server API Contracts for AI Agents
Write API spec contracts for MCP servers: input schemas, output shapes, error taxonomies, idempotency flags, and versioning that AI agent clients can rely on.
OpenSpec vs Superpowers vs Spec Kit: Compare and Combine
OpenSpec vs Superpowers vs Spec Kit, checked Nov 2026: what each one owns, how to combine them, and which to start with.
AI Coding Spec Packet Before Code Generation
A copy-ready packet for giving AI coding tools a bounded task, acceptance criteria, file ownership, tests, and review evidence before code generation starts.
Spec Skills and Spec-First Delivery
See how Spec Skills fits spec-first delivery through constrained prompts, spec injection, boundary enforcement, and reviewable AI output.
Refund Example: Vibe vs Spec Coding
Same refund feature built two ways: vibe coding ships fast but misses edge cases, while spec coding defines scope, acceptance criteria, tests, and rollout proof.
Acceptance Criteria Examples You Can Copy
20 real-world acceptance criteria examples in Given/When/Then format covering authentication, e-commerce, APIs, data processing, payments, and notifications.
Technical Specification Document: Template and Examples
How to write a technical specification document for software: the sections to include, five worked examples (config, API, migration, UI), and a copy-ready template.
Database Schema Specs Before Migrations
Define database schemas before writing migrations, including columns, constraints, indexes, API alignment, and rollout order.
AI Coding Prompts That Follow Specs
AI coding tools drift without constraints, adding fields, renaming functions, expanding scope, and inventing tests. Spec-first prompts keep changes reviewable.
AI Coding Governance with Spec-Driven Prompts
Govern AI-assisted coding with spec-driven prompts: define scope, boundaries, evidence, and audit trails before generated code reaches review.
AI Coding PR Review with Acceptance Criteria
Review AI-generated pull requests against acceptance criteria: inspect the diff, run evidence checks, and catch failures a quick skim misses.
AI Coding Risk Register Before Merge
Use a pre-merge risk register for AI-generated code: flag auth, data, contract, migration, rollback, and observability risks.
AI Coding with Test-Evidence Gates
Use test-evidence gates for AI-generated code: require meaningful tests before merge and catch hallucinated implementations before release.
Designing API Specs for Agentic Clients
Design API specs for LLM-powered agentic clients with discoverable fields, idempotency, dry-runs, semantic descriptions, and safe destructive actions.
Contract Testing Plan: From OpenAPI to CI
Add contract testing from OpenAPI to CI with generated tests, provider checks, consumer expectations, and reliable fixtures.
Event-Driven Systems: Specification Patterns
Specification patterns for event-driven systems: schema versioning, command vs fact events, orchestration choices, idempotent handlers, and replay safety.
Payment Workflow Spec: Failure and Retry Matrix
Write payment workflow specs with retryable errors, declined-card handling, timeout behavior, 3DS branches, and dunning states.
10 Common Mistakes in Software Specifications
Avoid ten specification mistakes that hide decisions, blur acceptance criteria, skip failure paths, and push scope arguments into implementation.
Quality Gates for AI-Assisted Development Specs
Quality gates for AI-assisted code: pre-prompt spec checks, diff review, test evidence, and human sign-off before generated code ships.
Spec Review Checklist Before Coding
Use this pre-coding review checklist to separate blockers from preferences, record accepted risks, and attach test evidence before implementation begins.
What Is Spec-First Development? (Complete Guide)
What is spec-first development? A complete guide to surfacing hidden decisions about scope, contracts, edge cases, and acceptance criteria before coding starts.
Static pagination · Page 1/3 · 26 articles
What Is Spec-First Development? (Complete Guide)
Use this as the orientation piece if you want the overall model, tradeoffs, and where spec-first work pays off.
Read the full guideHow to Write a Technical Spec
A complete template, worked example, and free generator covering acceptance criteria, edge cases, and the sections every spec needs.
Open the template guideOpenSpec vs Superpowers vs Spec Kit
Which spec tool decides what gets built, which one controls how the agent builds it, and how to run two of them together.
Read the comparisonChoose a Learning Path
Pick the path that matches the problem in front of you. Each path starts with a practical article, then points toward a template, checklist, or tool you can use in the same session.
Learn the method before you change your process
Start with the complete guide, then compare spec-first with agile and use the adoption plan only after the team agrees on the behavior you want to protect.
Start the foundations pathTurn vague requirements into testable criteria
Use the technical spec guide, acceptance criteria examples, and edge-case articles when a ticket is too broad for implementation.
Follow the writing pathProtect contracts, migrations, and rollback paths
Start here when a change touches external consumers, database shape, idempotency, compatibility, or release safety.
Follow the contract pathGive AI tools boundaries they can be reviewed against
Start with a spec packet, then move into prompts, risk registers, PR review gates, and test evidence before generated code reaches production.
Follow the AI pathTopic Hubs
Use these hubs when you want a structured route through the library instead of one article at a time. Each hub includes a decision table, copy-ready block, and related guides.
Spec-First Development Hub
Start here for the method, core decisions, review gates, and evidence habits.
Open hubAPI Contracts Hub
Use this route for schema diffs, compatibility, versioning, webhooks, and deprecation.
Open hubAcceptance Criteria Hub
Turn success statements into testable criteria with failure paths and proof.
Open hubAI Coding Governance Hub
Connect prompts, risk registers, acceptance mapping, and test evidence.
Open hub