Spec First

---
description: Create or update a feature spec with Gherkin scenarios and ASCII mockups (TDD step 1)
---

# Spec-First Mode (TDD + Design Flow)

Create or update the feature specification for: $ARGUMENTS

Per feature: ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ SPEC │ ──▶ │ RED (test) │ ──▶ │ GREEN (impl) │ ──▶ │ REFACTOR │ │ (Gherkin + │ │ (failing) │ │ (until tests │ │ (clean up, │ │ mockup + │ │ │ │ pass) │ │ tests must │ │ persona │ │ │ │ │ │ still pass) │ │ revision) │ │ │ │ │ │ │ └──────┬───────┘ └──────────────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ [PAUSE] ▼ ▼ user approves ┌──────────────┐ ┌──────────────┐ then /tdd │ DRIFT CHECK │ │ DRIFT CHECK │ │ (layer 1) │ │ (layer 1b) │ └──────────────┘ └──────┬───────┘ │ ▼ ┌──────────────┐ │ COMPOUND │ │ (learnings) │ └──────────────┘

Reads from: .specs/strategy.md, .specs/constitution.md, .specs/personas/, .specs/design-system/, .specs/migrations.md, .specs/learnings/index.md Writes to: .specs/features/, .specs/design-system/components/ (stubs)

## Mode Detection

Check if the user included `--full` or `--auto` flag:

| Command | Mode | Behavior |
|---------|------|----------|
| `/spec-first user auth` | Normal | Stop for approval at each step |
| `/spec-first user auth --full` | Full | Complete TDD cycle without pauses |
| `/spec-first --full user auth` | Full | Same (flag position flexible) |
| `/spec-first user auth --auto` | Full | Alias for --full |

### Full Mode Behavior

If `--full` or `--auto` flag is present, execute the ENTIRE Red-Green-Refactor TDD cycle without stopping:

1. Create OR update spec (see Step 0)
2. **Do NOT pause** - immediately write failing tests (RED)
3. **Do NOT pause** - immediately implement until tests pass (GREEN)
4. Self-check drift (Layer 1) — compare spec to code, fix mismatches
5. **REFACTOR** — clean up code, tests MUST still pass
6. Post-refactor drift check (Layer 1b) — re-verify spec↔code after refactor
7. Run `/compound` to extract learnings
8. Update all frontmatter (status: implemented)
9. Commit with descriptive message

**Skip all "Ready to...?" prompts in full mode. Both create and update paths continue through the full loop.**

### Normal Mode Behavior (default)

Stop for user approval at each step (existing behavior).

---

## Behavior

### 0. Resolve Spec File (Create vs Update)

**Before creating anything**, determine whether to create or update:

1. Parse the feature description from arguments (strip `--full`, `--auto`).
2. Search for an existing spec:
   - List `.specs/features/**/*.feature.md`
   - Derive candidate path from input: e.g. "user profile" → `users/user-profile.feature.md`, "Auth: Signup" → `auth/signup.feature.md`
   - For each spec, check if frontmatter `feature:` matches (case-insensitive, normalize spaces/hyphens)
   - If a file exists at the derived path, it's a match
3. **If match found** → **UPDATE mode**:
   - Read the existing spec
   - Preserve: `status`, `tests`, `components`, `created`, `design_refs`
   - Update: scenarios, mockup, description per user's request
   - Set `updated: YYYY-MM-DD`
   - **Full mode**: continue through tests → implement → compound → commit (same as create)
4. **If no match** → **CREATE mode** (proceed to Step 1)

### 1. Load Context

Before writing anything, read what exists. This shapes the entire spec.

#### Strategy

Read `.specs/strategy.md` if it exists and has real content (not just the template). The strategy provides:
- **Target customer** — who the feature should serve (validates feature is for the right segment)
- **Buying motion** — PLG features need fast time-to-value; enterprise features can have setup flows
- **Value proposition** — every feature should connect to the core value
- **Anti-goals** — features that serve anti-goals should be flagged or deferred

If strategy exists, the spec will include a **Strategy Alignment** section.
If no strategy exists, note it:

ℹ️ No strategy.md found. Spec will not include strategy alignment. Run /strategy to define product positioning.

#### Constitution

Read `.specs/constitution.md` if it exists and has real rules (not just the template). Constitutional constraints are non-negotiable rules (security, data handling, error handling) that every feature must satisfy.

If constitution exists, the spec will include a **Constitutional Compliance** section.
If no constitution exists, note it:

ℹ️ No constitution.md found. Spec will not include compliance section. Run /constitution to define project-wide constraints.

#### Migrations

Read `.specs/migrations.md` if it exists. It records how this project changes its database schema (tool, naming, reversibility, backfill habits, expand-contract rules). The always-applied `.cursor/rules/migrations.mdc` summary is also in context.

This matters only when the feature changes the Data Model. If it does, the spec will include a **Migration Plan** subsection (see Technical Design) that follows these conventions.

If no migrations playbook exists but the feature touches the schema, note