Spec

Spec-Driven Development

Language Adaptation

Detect the user's language from their first message. If the user writes in a non-English language, ALL skill output — specs, assumptions, questions, success criteria — MUST be in that language. Do not mix languages.

Vietnamese example:

GIẢ ĐỊNH TÔI ĐANG ĐẶT:
1. Đây là web app (không phải mobile native)
2. Auth dùng session-based cookies (không phải JWT)
3. Database là PostgreSQL (dựa trên Prisma schema hiện tại)
→ Sửa tôi ngay nếu sai.

Label mapping for Vietnamese:

English	Vietnamese
ASSUMPTIONS I'M MAKING	GIẢ ĐỊNH TÔI ĐANG ĐẶT
Objective	MỤC TIÊU
Tech Stack	CÔNG NGHỆ
Commands	LỆNH
Project Structure	CẤU TRÚC
Code Style	PHONG CÁCH CODE
Testing Strategy	CHIẾN LƯỢC TEST
Boundaries	RANH GIỚI
Success Criteria	TIÊU CHÍ THÀNH CÔNG
Open Questions	CÂU HỎI MỞ
Always	LUÔN LÀM
Ask first	HỎI TRƯỚC
Never	KHÔNG BAO GIỜ

AskUserQuestion UI labels for Vietnamese:

English	Vietnamese
All correct	Đúng hết
Some wrong	Có chỗ sai
Approved	Duyệt
Needs changes	Cần chỉnh
Assumptions	Giả định
Spec	Spec
Proceed with these assumptions	Tiếp tục với các giả định này
I'll specify which ones to correct	Tôi sẽ chỉ chỗ cần sửa
Proceed to next phase	Tiếp tục phase tiếp
I'll specify what to adjust	Tôi sẽ chỉ chỗ cần chỉnh

This applies to AskUserQuestion calls too — question text, option labels, and option descriptions MUST be in the user's language. Only header stays in English (12-char limit makes translation impractical).

For other languages, translate labels equivalently. The structure stays the same — only the language changes.

Overview

Write a structured specification before writing any code. The spec is the shared source of truth between you and the human engineer — it defines what we're building, why, and how we'll know it's done. Code without a spec is guessing.

HARD GATE: Do NOT write implementation code during this skill. This skill produces a validated spec document — nothing else. Implementation is downstream.

When to Use

• Starting a new project or feature
• Requirements are ambiguous or incomplete
• The change touches multiple files or modules
• You're about to make an architectural decision
• The task would take more than 30 minutes to implement

When NOT to use: Single-line fixes, typo corrections, or changes where requirements are unambiguous and self-contained.

The Gated Workflow

Spec-driven development has four phases. Do not advance to the next phase until the current one is validated.

SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
   │          │        │          │
   ▼          ▼        ▼          ▼
 Human      Human    Human      Human
 reviews    reviews  reviews    reviews

Phase 1: Specify

Start with a high-level vision. Ask the human clarifying questions until requirements are concrete.

MANDATORY: Use AskUserQuestion tool for ALL questions and confirmations in this skill. Structure each turn as:

1. Text output first — print your assumptions, analysis, or context as normal text.
2. Then call AskUserQuestion — with ONLY the question inside the prompt. Keep the prompt clean.

Surface assumptions immediately. Before writing any spec content, list assumptions as text output, then use AskUserQuestion to confirm:

Text output:

ASSUMPTIONS I'M MAKING:
1. This is a web application (not native mobile)
2. Authentication uses session-based cookies (not JWT)
3. The database is PostgreSQL (based on existing Prisma schema)
4. We're targeting modern browsers only (no IE11)

Then call:

{
  "questions": [{
    "header": "Assumptions",
    "question": "Are these assumptions correct?",
    "options": [
      {"label": "All correct", "description": "Proceed with these assumptions"},
      {"label": "Some wrong", "description": "I'll specify which ones to correct"}
    ],
    "multiSelect": false
  }]
}

For clarifying questions, same pattern — context in text, question in prompt:

{
  "questions": [{
    "header": "Auth",
    "question": "What authentication method are you using?",
    "options": [
      {"label": "Session cookies", "description": "Server-side sessions with HTTP-only cookies"},
      {"label": "JWT tokens", "description": "Stateless tokens stored client-side"},
      {"label": "OAuth only", "description": "Delegated auth via external provider"}
    ],
    "multiSelect": false
  }]
}

For spec validation, present the full spec in text output, then confirm via prompt:

{
  "questions": [{
    "header": "Spec",
    "question": "Spec looks good?",
    "options": [
      {"label": "Approved", "description": "Proceed to next phase"},
      {"label": "Needs changes", "description": "I'll specify what to adjust"}
    ],
    "multiSelect": false
  }]
}

Don't silently fill in ambiguous requirements. The spec's entire purpose is to surface misunderstandings before code gets written — assumptions are the most dangerous form of misunderstanding.

Write a spec document covering these six core areas:

1. Objective — What are we building and why? Who is the user? What does success look like?

2. Commands — Full executable commands with flags, not just tool names.

   Build: npm run build
   Test: npm test -- --coverage
   Lint: npm run lint --fix
   Dev: npm run dev
   

3. Project Structure — Where source code lives, where tests go, where docs belong.

   src/           → Application source code
   src/components → React components
   src/lib        → Shared utilities
   tests/         → Unit and integration tests
   e2e/           → End-to-end tests
   docs/          → Documentation
   

4. Code Style — One real code snippet showing your style beats three paragraphs describing it. Include naming conventions, formatting rules, and examples of good output.

5. Testing Strategy — What framework, where tests live, coverage expectations, which test levels for which concerns.

6. Boundaries — Three-tier system:

   • Always do: Run tests before commits, follow naming conventions, validate inputs
   • Ask first: Database schema changes, adding dependencies, changing CI config
   • Never do: Commit secrets, edit vendor directories, remove failing tests without approval

Spec template:

# Spec: [Project/Feature Name]

## Objective
[What we're building and why. User stories or acceptance criteria.]

## Tech Stack
[Framework, language, key dependencies with versions]

## Commands
[Build, test, lint, dev — full commands]

## Project Structure
[Directory layout with descriptions]

## Code Style
[Example snippet + key conventions]

## Testing Strategy
[Framework, test locations, coverage requirements, test levels]

## Boundaries
- Always: [...]
- Ask first: [...]
- Never: [...]

## Success Criteria
[How we'll know this is done — specific, testable conditions]

## Open Questions
[Anything unresolved that needs human input]

Reframe instructions as success criteria. When receiving vague requirements, translate them into concrete conditions:

REQUIREMENT: "Make the dashboard faster"

REFRAMED SUCCESS CRITERIA:
- Dashboard LCP < 2.5s on 4G connection
- Initial data load completes in < 500ms
- No layout shift during load (CLS < 0.1)
→ Are these the right targets?

This lets you loop, retry, and problem-solve toward a clear goal rather than guessing what "faster" means.

Phase 2: Plan

STOP. Do not proceed to Phase 2 automatically. After the spec is validated, suggest the next step:

Spec confirmed. Next steps:
→ /plan [topic] — generate implementation plan from this spec
→ Continue here — if you want me to plan within this session, say "continue"

Do NOT invoke any skill automatically. Wait for the user to choose.

If the user says "continue", proceed with Phase 2 below.

---

With the validated spec, generate a technical implementation plan:

1. Identify the major components and their dependencies
2. Determine the implementation order (what must be built first)
3. Note risks and mitigation strategies
4. Identify what can be built in parallel vs. what must be sequential
5. Define verification checkpoints between phases

The plan should be reviewable: the human should be able to read it and say "yes, that's the right approach" or "no, change X."

Phase 3: Tasks

Break the plan into discrete, implementable tasks:

• Each task should be completable in a single focused session
• Each task has explicit acceptance criteria
• Each task includes a verification step (test, build, manual check)
• Tasks are ordered by dependency, not by perceived importance
• No task should require changing more than ~5 files

Task template:

- [ ] Task: [Description]
  - Acceptance: [What must be true when done]
  - Verify: [How to confirm — test command, build, manual check]
  - Files: [Which files will be touched]

Phase 4: Implement

STOP. Do not proceed to Phase 4 automatically. After tasks are defined, suggest the next step:

Tasks defined. Next steps:
→ /cook [topic] — implement tasks with test-first discipline
→ Continue here — if you want me to implement within this session, say "continue"

Do NOT invoke any skill automatically. Wait for the user to choose.

If the user says "continue", proceed: execute tasks one at a time. Each task follows: write test → implement → verify → next.

Keeping the Spec Alive

The spec is a living document, not a one-time artifact:

• Update when decisions change — If you discover the data model needs to change, update the spec first, then implement.
• Update when scope changes — Features added or cut should be reflected in the spec.
• Commit the spec — The spec belongs in version control alongside the code.
• Reference the spec in PRs — Link back to the spec section that each PR implements.

Common Rationalizations

Rationalization	Reality
"This is simple, I don't need a spec"	Simple tasks don't need long specs, but they still need acceptance criteria. A two-line spec is fine.
"I'll write the spec after I code it"	That's documentation, not specification. The spec's value is in forcing clarity before code.
"The spec will slow us down"	A 15-minute spec prevents hours of rework. Waterfall in 15 minutes beats debugging in 15 hours.
"Requirements will change anyway"	That's why the spec is a living document. An outdated spec is still better than no spec.
"The user knows what they want"	Even clear requests have implicit assumptions. The spec surfaces those assumptions.

Red Flags

• Starting to write code without any written requirements
• Asking "should I just start building?" before clarifying what "done" means
• Implementing features not mentioned in any spec or task list
• Making architectural decisions without documenting them
• Skipping the spec because "it's obvious what to build"

Verification

Before proceeding to implementation, confirm:

• The spec covers all six core areas
• The human has reviewed and approved the spec
• Success criteria are specific and testable
• Boundaries (Always/Ask First/Never) are defined
• The spec is saved to a file in the repository