Specification based development

--- name: spec-driven-development description: Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea. --- # Spec-Driven Development ## 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. ## 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. **Surface assumptions immediately.** Before writing any spec content, list what you're assuming: ` 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) → Correct me now or I'll proceed with these. ` 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:** `markdown # 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 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 sin