Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when drafting a PRD or requirements document with objectives and scope, or when requirements are unclear, ambiguous, or only exist as a vague idea. Use when a single requ

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, preceded by a scope check (Phase 0) that activates only when one request bundles several independently testable capabilities. Do not advance to the next phase until the current one is validated. Phase 0: Scope Check Most requests describe one capability. If this one does, skip this phase and go straight to Specify — Phase 0 exists for the exception, not the rule, and it puts no hierarchy on single capability features. Detection. Decompose before specifying when a single requirement bundles several independently testable capabilities: The requirement names distinct capabilities with their own consumers or data (e.g. identity, billing, notifications, reporting) Acceptance criteria cluster into groups that could ship and be verified separately One capability could be cut or replaced without rewriting the others' requirements Propose a capability map before writing any spec. Small and reviewable — a module table plus a build order, not a project plan: Stable module ids. Kebab case, chosen once, never renamed mid initiative. Specs, plans, and downstream commands select work by these ids instead of guessing which spec is active. Dependency direction, no cycles. Arrows point one way. If two modules each need the other, they are one module. Interfaces live at the boundary. The map records that billing depends on identity ; the contract between them belongs in the provider module's spec (see api and interface design for designing it). The map is gated like every phase. The human reviews module boundaries, dependency direction, and build order before any module spec is written. Getting the map wrong is expensive; reviewing ten lines is not. Then recurse per module. Run Specify → Plan → Tasks → Implement for each module in dependency order. Each module gets its own spec, scoped to that module's objective, boundaries, and success criteria. Save the approved map at the project root and each module's spec alongside it, named by module id ( SPEC identity.md , SPEC billing.md ) — the map, not filename guessing, is the index of what exists. 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: 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. 3. Project Structure — Where source code lives, where tests go, where docs belong. 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: External spec tools: This workflow is format agnostic. If the project already uses OpenSpec or another specification system, keep that system's artifact format and storage conventions instead of creating a duplicate SPEC.md . This skill owns the clarification, content, and approval gates; the external tool owns how the approved spec is represented. Reframe instructions as success criteria. When receiving vague requirements, translate them into concrete conditions: 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 Follow planning and task breakdown for the dependency graph mapping and vertical slicing mechanics behind these steps; it is the canonical source. The bullets above are a lightweight summary; if they ever diverge, planning and task breakdown takes precedence. Output convention: Save the plan to tasks/plan.md and record the task list in the task list target defined by planning and task breakdown (default tasks/todo.md ; projects may designate an external tracker instead). Create tasks/ if it does not exist. Downstream commands ( /build , etc.) expect these defaults. 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 Follow planning and task breakdown for the full task sizing and dependency ordering mechanics; it is the canonical source. The template below is a lightweight inline form; if they ever diverge, planning and task breakdown takes precedence. Task template: Phase 4: Implement Execute tasks one at a time following skills/incremental implementation/SKILL.md ( incremental implementation ) and skills/test driven development/SKILL.md ( test driven development ). Use skills/context engineering/SKILL.md ( context engineering ) to load the right spec sections and source files at each step rather than flooding the agent with the entire spec. 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. "It's one big feature; splitting it is overhead" If acceptance criteria cluster into independently testable groups, a monolithic spec forces every downstream task to reason over the whole contract. A ten line capability map is the cheap alternative. "I'll decompose during planning" Planning slices tasks within a spec. By then the oversized artifact already exists — module boundaries and dependency direction must be decided before the spec is written, not after. 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" One spec whose requirements span several independently testable capabilities Module boundaries or build order decided implicitly during implementation because no capability map was approved up front 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 [ ] If the request bundles several independently testable capabilities, a capability map (module ids, dependency direction, build order) was approved before any module spec was written [ ] Every module spec traces to a module id in the approved map

spec-driven-development