/spec-driven-development

name: spec-driven-development
type: workflow
description: "Enforces the creation of a clear, actionable specification before any implementation code is written. Prevents hallucinations and architectural drift."
argument-hint: "[feature-description-or-issue]"
user-invocable: true
allowed-tools: Read, Glob, Grep, WebSearch
context: fork
effort: 3
agent: lead-programmer
when_to_use: "When starting a new feature, doing major architectural refactoring, receiving a complex prompt, or when the user invokes /spec."

Spec-Driven Development

Purpose

This skill forces the agent to pause, analyze, and agree upon a specification before jumping into implementation code. Drafting a spec first prevents hallucinations, scopes down overly ambitious changes, and protects the codebase's existing architecture.

---

Task Classification — Run First

Before any other step, classify the task. The classification determines which gate path applies.

| Class | Criteria | Gate path | |---|---|---| | **Simple** | ≤ 1 file, ≤ 30 min, intent unambiguous, no data model change | Assumption Log (≤ 3 items) → Fast Gate → code | | **Medium** | Multi-file, ≤ 2 days, some data or logic change | Ground Truth Gate → Spec Gate → plan → tdd | | **Complex** | Cross-domain, > 2 days, new entities, auth, billing, or architecture change | Interview Gate → Ground Truth Gate → Spec Gate → plan → tdd |

State the classification in one line before proceeding:

Classification: [Simple|Medium|Complex] — reason: <one sentence>

Simple Task — Assumption Log

For Simple tasks, skip the full spec. Instead, surface assumptions in a scannable 3-item max format and pause for user confirmation before any edit:

Trước khi bắt đầu, confirm 3 điều:

1. [Assumption về stack / file / scope] → đúng không? [y/n]
2. [Assumption về behavior / constraint] → đúng không? [y/n]
3. Scope: chỉ làm X, KHÔNG làm Y → đúng không? [y/n]

(Nếu có gì sai, nói ngay — tôi chờ trước khi tiếp tục.)

If any answer is "n" or ambiguous → reclassify as Medium and run Ground Truth Gate.

---

Ground Truth Gate — Required for Medium and Complex tasks

**This gate must pass before a spec can be drafted or approved.**

The agent must produce — and the user must explicitly confirm — all three documents:

Document 1: Data Model

List every entity involved in the feature. For each entity, specify field names, types, and constraints. No prose allowed — use a table or code block.

Entity: User
  - id: UUID, primary key
  - email: string, unique, not null
  - role: enum(admin, member), default=member
  - created_at: timestamp

Entity: Session
  - token: string, primary key
  - user_id: FK → User.id
  - expires_at: timestamp, not null

Gate check: If any field name, type, or relationship is written as "TBD", "flexible", or left blank → gate FAILS. Stop and fill in before continuing.

Document 2: Business Rules

List every logic condition that governs the feature. Use explicit if/then/else format. No prose paragraphs.

Rule 1: Login attempt
  IF email not found → return "Invalid credentials" (do not reveal which field failed)
  IF password wrong → return "Invalid credentials"
  IF account locked → return "Account locked, contact support"
  IF success → create Session, set HttpOnly cookie, redirect to dashboard

Rule 2: Session expiry
  IF Session.expires_at < now() → destroy session, redirect to login
  IF user is active within 30 min → extend expires_at by 30 min

Gate check: If any rule uses vague language ("handle appropriately", "validate properly", "standard logic") → gate FAILS. Rewrite as explicit condition before continuing.

Document 3: Acceptance Criteria

Every criterion must be in Given/When/Then format and be independently testable. Minimum 3 criteria per Medium task, 5 per Complex task.

AC-1:
  Given a registered user with correct credentials
  When they submit the login form
  Then a session cookie is set and they are redirected to /dashboard

AC-2:
  Given a wrong password is entered
  When they submit the login form
  Then "Invalid credentials" is shown and no session is created

AC-3:
  Given a session expired
  When the user navigates to any protected route
  Then they are redirected to /login and the expired session is destroyed

Gate check: If any criterion contains "works correctly", "as expected", "handles the case" → gate FAILS. Rewrite as specific observable outcome.

Out-of-Scope Declaration (required)

State explicitly what this feature does NOT do. Minimum 2 items.

Out of scope:
- Registration / sign-up flow
- Password reset
- OAuth / social login
- Rate limiting (tracked separately in SPEC-20260515-002)

**Ground Truth Gate summary checklist — all must be ✅ before spec draft:**

□ Data Model: all entities with field names, types, constraints — no TBDs
□ Business Rules: all conditions as if/then/else — no vague language
□ Acceptance Criteria: Given/When/Then, independently testable — no "works correctly"
□ Out-of-Scope: ≥ 2 explicit exclusions stated

If any checkbox is unchecked → STOP. Do not draft the spec. Return to the user with the specific gap.

---

Workflow (Strict Process)

**ABSOLUTE DIRECTIVE**: You are an Agent. You MUST NOT start writing implementation files (.ts, .js, .py, etc.) until you have completed this workflow and the user has explicitly approved the spec or the documented Fast Gate/Override Gate from `using-sdd`.

1. Context Analysis

• Review relevant files using `Read`, `Glob`, or `Grep` to understand the system boundaries.
• Identify how the proposed feature fits into the current architecture.
• Detect existing commands, test locations, project structure, and local conventions from repository files instead of inventing them.

2. Assumption Surfacing

• Before drafting spec content, explicitly list assumptions that affect scope, architecture, data, security, or verification.
• If an assumption materially c