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)