# Spec Driven Dev > Operating procedure for spec-driven development (SDD) with AI coding agents: treat code as disposable and the specification as the durable, versioned asset, then run the Constitution → Specify → Plan → Tasks → Implement loop (GitHub Spec Kit) with behavior-driven Gherkin-style specs. Trigger whenever building software meant to outlive a prototype — production features, multi-session or multi-agen… - **Type:** Skill - **Install:** `agentstack add skill-archive228-lab-skills-spec-driven-dev` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Archive228](https://agentstack.voostack.com/s/archive228) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Archive228](https://github.com/Archive228) - **Source:** https://github.com/Archive228/lab-skills/tree/main/skills/spec-driven-dev ## Install ```sh agentstack add skill-archive228-lab-skills-spec-driven-dev ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Spec-Driven Development with Agents This skill turns you from a code generator into an executor of specifications. The core inversion, from GitHub's Spec Kit methodology: "Specifications don't serve code—code serves specifications." The spec — not the code — is what gets versioned, reviewed, and reasoned about; code is one possible expression of it in a particular language and framework, and can be regenerated. Google's Day 5 whitepaper from the 5-Day AI Agents Intensive course makes the production case: a rock-solid behavioral specification in Gherkin BDD format makes code disposable — the implementation can be safely regenerated from the spec when requirements or the stack change. ## When to use Use this procedure when: - The output must survive past a demo: production features, enterprise code, anything with compliance or security requirements. - Multiple sessions, agents, or humans will touch the same codebase — the spec is the shared contract you onboard them with, instead of explaining decisions from memory. - Migrating or modernizing legacy code: write the spec once and regenerate on the new stack, instead of line-by-line translation. - Requirements will change: with SDD you update the spec first, then regenerate — not patch code and let intent drift. Do NOT use it when: - Building a throwaway prototype or exploring UX directions — vibe coding's fast accept/reject loop wins there. SDD is slower per feature because you write documents before code; the payoff compounds only when the codebase grows, features interact, or you revisit code weeks later and need the rationale. - The feature is small and the spec is already unambiguous — skip the optional `/speckit.clarify` and `/speckit.analyze` phases (see Rule 6) rather than skipping SDD entirely. ## Rules 1. **Treat the spec as the asset and code as disposable.** Version, review, and evolve `spec.md`; regenerate code from it. Maintaining software means evolving specifications. If the code and the spec disagree, that is a review finding, not an accepted fact. 2. **Keep the spec at WHAT/WHY altitude — never HOW.** The spec holds functional requirements and user-observable behavior; no tech stack, no SQL tables, no API internals. Implementation detail lives in `plan.md`. This separation prevents premature technical decisions from contaminating requirements. 3. **Write behavioral requirements in Gherkin BDD format.** The whitepaper recommends Gherkin because its structured natural language keeps LLMs focused on state, action, outcome — precise enough that the entire codebase can be regenerated or translated from it. 4. **Never guess on ambiguity — mark it.** Use explicit `[NEEDS CLARIFICATION]` markers in the spec for anything the request doesn't specify, then resolve them (with `/speckit.clarify` or the user) before planning. An unmarked assumption becomes silently generated wrong code. 5. **Run the Spec Kit loop in order.** With the `specify` CLI (`uv tool install specify-cli --from git+https://github.com/github/spec-kit.git`, then `specify init `; works with 30+ AI coding agents): - `/speckit.constitution` → `constitution.md` (governing principles) - `/speckit.specify` → `spec.md` (requirements, user stories) - `/speckit.plan` → `plan.md` plus `data-model.md`, `research.md` (stack, architecture, rationale) - `/speckit.tasks` → `tasks.md` (ordered, actionable steps) - `/speckit.implement` → code, executed task-by-task with checkoff Optional: `/speckit.clarify` (recommended before `/speckit.plan` for complex features), `/speckit.analyze` (cross-artifact consistency — most useful when the task list is long or the feature touches multiple subsystems), `/speckit.checklist` (final validation), `/speckit.converge` (assess an existing codebase against spec), `/speckit.taskstoissues` (tasks → GitHub issues). 6. **Establish a constitution and gate against it.** Non-negotiable project principles live at `.specify/memory/constitution.md`. Spec Kit's own reference articles: Library-First (Article I), CLI Interface Mandate (II), Test-First Imperative — non-negotiable (III), Simplicity with max 3 projects initially (VII), Anti-Abstraction — use frameworks directly (VIII), Integration-First Testing with real databases and contract tests (IX). Planning runs a Constitution Check with Simplicity, Anti-Abstraction, and Integration-First gates; `/speckit.analyze` flags violations as CRITICAL. 7. **Emit tasks in strict checklist format.** IDs, parallelizable markers, and file paths, e.g. `- [ ] [T001] [P] Create reservations table schema in scripts/seed_db.py`. Mark independent work `[P]`. Enforce ordering: contracts first, then tests (contract → integration → e2e → unit), then implementation. 8. **Version-control every artifact.** Artifacts live in `specs//` in git — not buried in chat history. If a conversation is interrupted, everything decided so far is already on disk; resume from the files. 9. **On requirement change, update the spec first, then regenerate.** Debugging means fixing the spec and plan that generated the wrong code. Production feedback flows back into the spec for the next regeneration cycle. 10. **Scale review by risk, not line-by-line reading.** The whitepaper's production pipeline pairs SDD with automated code-review agents. Focus human review on behavioral tests, system contracts, and high-risk changes rather than every generated line — humans forced to read everything an agent generates stop catching anything. 11. **Gate tool execution with policy, not trust.** In the whitepaper's zero-trust pipeline, a hybrid Policy Server evaluates agent tool-calling actions before execution and blocks unsafe or non-compliant ones. In enterprise settings, agent actions are checked, never assumed safe. 12. **Have the agent keep artifacts synchronized.** When code changes, update the specs, regenerate tests, and update changelogs in the same pass; require human review and approval of spec/plan/tasks artifacts before implementation proceeds. Generated artifacts vary between runs — review, then accept, modify, or regenerate. 13. **Optimize for business outcome, not generation volume.** The whitepaper's core warning: the same speed that vibe-codes a prototype in minutes produces fragile code at production scale. Measuring success by how much code the agent generates just moves the cost into review and maintenance; measure verified behavior instead. ## Checklist - [ ] Decide: will this outlive a prototype? If no — vibe iterate. If yes — proceed. - [ ] `specify init` (or confirm `.specify/` exists) before any feature work. - [ ] Constitution written at `.specify/memory/constitution.md` with the project's non-negotiables. - [ ] `/speckit.specify`: spec.md states WHAT and WHY only; zero implementation details. - [ ] Behavioral requirements expressed as Gherkin state/action/outcome scenarios. - [ ] Every unknown marked `[NEEDS CLARIFICATION]`; all markers resolved before `/speckit.plan`. - [ ] `/speckit.plan`: plan.md + data-model.md + research.md record stack choices with rationale. - [ ] Constitution Check passed (Simplicity, Anti-Abstraction, Integration-First gates). - [ ] `/speckit.tasks`: tasks.md uses `[T00N]` IDs, `[P]` parallel markers, explicit file paths. - [ ] Test order enforced: contracts → contract tests → integration → e2e → unit → implementation. - [ ] Long/multi-subsystem task list? Run `/speckit.analyze` before implementing. - [ ] Human approved spec, plan, and tasks before `/speckit.implement`. - [ ] All artifacts committed under `specs//`. - [ ] Any requirement change went spec-first, then regeneration — never code-only patches. ## Anti-patterns - **Vibe coding into production.** Accepting generated code "because it looks right" is fine for demos; the same speed that builds a prototype in minutes makes it fragile in production, because there is no source of truth to regenerate from. - **Spec drift.** Editing generated code without updating the spec. The spec silently stops being the source of truth and the next regeneration destroys your fixes. - **HOW in the spec.** Naming databases, frameworks, or schemas inside spec.md — it locks in premature technical decisions and blocks regeneration on a different stack. - **Guessed defaults.** Filling unspecified behavior from assumption instead of `[NEEDS CLARIFICATION]` markers. - **One-shot generation.** Jumping from a one-sentence prompt to implementation without spec → plan → tasks; SDD is multi-step refinement, not single-shot codegen. - **Reviewing everything, line by line.** Unsustainable once agents scale output, and it degrades into rubber-stamping; tier the review by risk and audit tests/contracts instead. - **Measuring generation volume.** Counting generated lines or tokens as progress rather than verified, business-relevant behavior. - **Trusting agent tool calls.** Letting tool execution proceed unchecked in enterprise settings instead of gating it behind policy (the whitepaper's hybrid Policy Server pattern); unsafe actions must be blocked before execution, not caught after. ## Source - Spec-Driven Production Grade Development in the Age of Vibe Coding (whitepaper, Google × Kaggle 5-Day AI Agents Intensive, Day 5) — https://www.kaggle.com/whitepaper-spec-driven-production-grade-development-in-the-age-of-vibe-coding — 2026-06 - DAY 5 Livestream — 5-Days of AI Agents: Intensive Vibe Coding Course With Google (official Kaggle channel; hosts' walkthrough of the whitepaper) — https://www.youtube.com/watch?v=Y3HfV4IroCU — 2026-06 - Spec-Driven ADK Agent Development with Antigravity and Spec-kit (official Google Codelab companion) — https://codelabs.developers.google.com/sdd-adk-antigravity — 2026 - Spec Kit — Spec-Driven Development toolkit (README + spec-driven.md methodology) — https://github.com/github/spec-kit — 2026-08 Distilled from the official document(s) above on 2026-08-12. If this skill and the source disagree, trust the source. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Archive228](https://github.com/Archive228) - **Source:** [Archive228/lab-skills](https://github.com/Archive228/lab-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-archive228-lab-skills-spec-driven-dev - Seller: https://agentstack.voostack.com/s/archive228 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.