Spec-First Development

---

name: spec-first-dev description: Spec-driven development workflow. Before writing any code, generates a comprehensive SPEC.md covering data models, user flows, API contracts, file structure, and edge cases. Forces the right order — spec first, code second. Prevents building the wrong thing. Use at the start of any non-trivial build task. argument-hint: [project description or goal] allowed-tools: Read, Write, Bash, Glob metadata: version: "1.0.0" author: "clawsonnet" tags: ["development", "spec", "planning", "architecture", "workflow", "tdd"]

---

Spec-First — Spec-Driven Development Workflow

Why This Exists

80% of "Claude built the wrong thing" failures come from jumping into code before the spec is clear. This skill forces the right order: spec → approval → implementation.

Trigger

Use at the start of ANY non-trivial build. If the task will touch >2 files or take >15 minutes, run this first.

Invoked as: /spec-first-dev [brief description of what you want to build]

Or auto-triggered by phrases like "build me", "create a", "implement a" when the scope is non-trivial.

Process

Step 1: Clarify Intent

Parse $ARGUMENTS for:

What is being built (feature, service, script, component, etc.)

Who uses it (end users, internal tooling, automated pipeline)

Key constraints (stack, budget, timeline if mentioned)

If intent is ambiguous, ask ONE clarifying question before proceeding.

Step 2: Explore Existing Codebase

Before speccing anything new, understand what already exists:

Run Glob to find relevant existing files (configs, schemas, components)

Run Grep to find related code patterns

Identify: what can be reused, what must be new, what might conflict

Step 3: Generate SPEC.md

Write SPEC.md to the project root (or current directory). Include:

# SPEC: [Feature Name]
Overview
[1-2 sentences. What this does and why.]
Data Models
[All entities, fields, types, relationships]
User Flows / API Contracts
[Numbered steps for each major flow. Include request/response shapes for APIs.]
File Structure
[New files to create, existing files to modify, with brief reason for each]
Edge Cases & Error Handling
[Specific scenarios to handle: empty states, failures, invalid input, concurrency]
Out of Scope
[What we are explicitly NOT building in this task]
Open Questions
[Any decisions that need input before coding starts]

Step 4: Present and Gate

Output the SPEC.md contents to the user and explicitly pause:

SPEC complete. Review above and confirm before I write any code.
Reply 'go' to proceed, or tell me what to change.

Do not write any implementation code until the user explicitly approves the spec.

Step 5: Implement Against Spec

Once approved:

Work through the spec section by section

Check off items as you complete them

Flag any spec deviations immediately (don't quietly deviate)

If a new edge case emerges, add it to the spec and note it

Output Files

SPEC.md — written in the project root before implementation starts

(Optional) SPEC_APPROVED.md — copy of approved spec for audit trail

Integration

Works well with:

Task-tracking tools (prefix each coding session with this skill)

Code review workflows (attach SPEC.md to PRs)

Team handoffs (spec is the briefing document)