Spec-First: No Code Before an Approved Spec

When the user asks for a feature, change, or fix, do NOT start writing code. Write a spec first, present it, and wait for explicit approval. A prompt is a wish; a spec is a contract.

Workflow

1. Investigate before writing. Read the files the change will touch and note how the existing code works. If a decision materially shapes the spec (data model, API surface, new dependency), ask the user before drafting, not after.
2. Write the spec to specs/<slug>.md, where <slug> is a short kebab-case name for the task (e.g. specs/rate-limit-login.md). Create the specs/ directory if it does not exist. Use the template below. Keep the spec under one page: if it will not fit, the feature is too big, propose splitting it into smaller specs instead.
3. Present it and stop. Show the spec (or a faithful summary plus the file path) and ask: "Approve this spec, or want changes?" Then WAIT. Do not write, edit, or scaffold any implementation code until the user replies with explicit approval ("approved", "go ahead", "yes, build it"). Silence, follow-up questions, or partial answers are not approval.
4. After approval, the spec is the contract. Implement exactly what it says. If reality contradicts the spec mid-implementation (an API that does not exist, a wrong assumption), stop, update the spec file, and re-request approval for the delta before continuing. Never expand scope silently, "while I was in there" improvements belong in a future spec, not this diff.
5. Before declaring done, re-read the spec. Walk the acceptance criteria one by one, run the verification command, and report each criterion as met or not met.

Spec template

# <Title>

## Context
Why this change is needed, in 2-4 sentences. Link related code or issues.

## Scope
What will be built, and which files/modules it touches.

## Out of scope
Explicit non-goals, so nobody "helpfully" builds them.

## Acceptance criteria
- [ ] Machine-checkable statements ("GET /api/login returns 429 after
      5 requests/minute"), never vibes ("works well", "feels fast").

## Verification
One command that proves the criteria, e.g.
npm test -- rate-limit && npx tsc --noEmit

Edge cases

• Tiny change (typo, comment, one-line config): a one-paragraph spec in chat is enough, but still get a "yes" before editing.
• User says "skip the spec, just do it": comply, and note in one line that spec-first was skipped at their request.
• Vague request: draft the spec anyway with your best-guess scope and mark every guess with ASSUMPTION: so approval doubles as clarification.
• A spec for this task already exists: re-read it and confirm it still stands instead of writing a duplicate.

Boundaries

• Never write implementation code before explicit approval. The only file you may create pre-approval is the spec itself.
• Never mark an acceptance criterion as met without having run the verification command in this session.
• Never widen scope beyond the approved spec without a new approval.
• Approval comes from the human, never from you deciding the spec "looks fine".