First Principles · 11 min mission

Spec-Driven Development with Coding Agents

Write the spec first, let the agent plan, slice, and implement from it — and stop fixing confidently-wrong code.

spec-driven-developmentspec-kitkiroplan-modeworkflowfoundationsFact-checked 2026-06-15

On this page

The wave: specify → plan → tasks → implement
GitHub Spec Kit: the wave as slash commands
The /speckit. commands
AWS Kiro: the same loop, as files
EARS: acceptance criteria a test can check
Claude Code plan mode: the in-session version

Spec-driven development (SDD) reorders agent work: write a precise spec, have the agent turn it into a technical plan, slice that into ordered tasks, then implement — with the spec as the source of truth, not the diff. This guide shows the four-stage wave and the exact commands, flags, files, and config keys for running it in GitHub Spec Kit, AWS Kiro, and Claude Code plan mode.

The wave: specify → plan → tasks → implement

Every SDD tool runs the same four stages. The gate between each stage is the mechanism: reviewing a one-page spec is cheaper than reviewing a thousand lines of generated code, so the review is front-loaded.

The four stages

Specify
Capture what and why — user stories, requirements, acceptance criteria. Do not name the tech stack here.
Plan
Turn the approved spec into a technical plan: architecture, data model, API contracts, and the stack. First stage that names a framework.
Tasks
Break the plan into a dependency-ordered list of small, individually checkable units. A task that depends on another comes after it.
Implement
Execute the tasks and write code against the now-fixed outline.

GitHub Spec Kit: the wave as slash commands

Spec Kit is an open-source, MIT-licensed toolkit + specify CLI that scaffolds the SDD wave into 30+ coding agents as slash commands. As of 2026-06-15 the CLI is v0.10.2 (published 2026-06-11). Install once with uv, then initialize a project and select the agent with the --integration flag.

Install Spec Kit and scaffold a project

# Install the CLI once (pin the latest tag, e.g. v0.10.2)
uv tool install specify-cli \
  --from git+https://github.com/github/spec-kit.git@v0.10.2
 
# One-off run without installing:
# uvx --from git+https://github.com/github/spec-kit.git specify init my-feature --integration claude
 
# Scaffold the SDD commands into a new project, targeting Claude Code
specify init my-feature --integration claude
 
# ...or scaffold into the current directory
specify init .            # prompts if the dir is non-empty
specify init . --force    # skip the confirmation
specify init --here       # equivalent to "."
 
# List every agent it can target (Claude Code, Gemini CLI, Codex CLI,
# Cursor, Kiro CLI, Copilot — 30+; full set is runtime-only)
specify integration list

The /speckit.* commands

After specify init, the agent gains a namespaced command set under /speckit.*. Early write-ups show bare /specify, /plan, /tasks, /implement; those forms do not exist on the current CLI. Each command writes durable files into the repo, so the spec, plan, and tasks can be committed and diffed like any other source.

Command	Role	Produces
`/speckit.constitution`	Establish governing project principles	`.specify/memory/constitution.md`
`/speckit.specify`	Define requirements + user stories (what/why)	`specs/[feature]/spec.md`
`/speckit.clarify`	Resolve underspecified areas — run before plan	Updates the spec
`/speckit.plan`	Create the technical plan and stack choices	`plan.md`, `data-model.md`, `contracts/api-spec.json`, `research.md`, `quickstart.md`
`/speckit.tasks`	Break the plan into a dependency-ordered list	`tasks.md`
`/speckit.analyze`	Optional cross-artifact consistency check	Report (no new file)
`/speckit.checklist`	Generate quality-validation checklists	Checklist artifact
`/speckit.taskstoissues`	Convert tasks into GitHub issues	GitHub issues
`/speckit.implement`	Execute the tasks and write the code	Working code

Spec Kit command set as of v0.10.2. Run /speckit.clarify before /speckit.plan; /speckit.analyze and /speckit.checklist are optional quality gates.

One feature, the full wave

… scroll to run this session

Spec Kit running inside Claude Code. Each command leaves a durable file behind; /speckit.clarify closes gaps before the plan is drafted.

AWS Kiro: the same loop, as files

AWS Kiro is an agentic IDE + CLI built on SDD; it replaced Amazon Q Developer and reached general availability on 2025-11-17 (November 2025). The four headline GA capabilities: property-based testing, execution checkpointing, the Kiro CLI, and centrally-managed team plans. Kiro's wave lives in three sequential files under .kiro/specs/{feature}/.

Kiro file	Contents	Spec Kit equivalent
`requirements.md`	User stories + acceptance criteria in EARS format	`spec.md`
`design.md`	Architecture, sequence diagrams, tech-stack decisions	`plan.md`
`tasks.md`	Discrete, dependency-ordered implementation tasks	`tasks.md`

Kiro spec files and their Spec Kit equivalents. Bug-type specs use bugfix.md in place of requirements.md.

Kiro surrounds the spec with two more pillars:

Steering — persistent markdown context in .kiro/steering/ (workspace) or ~/.kiro/steering/ (global; workspace wins on conflict). Three default files are generated and included in every interaction: product.md, tech.md, structure.md. Inclusion modes set via YAML front-matter: Always, fileMatch (glob like "components/**/*.tsx"), Manual (referenced with #steering-file-name), and Auto.
Hooks — event-triggered automation that runs an agent prompt or shell command. Triggers include onFileSave, onFileCreate, onFileDelete, prompt/agent-turn events, pre/post tool-use, before/after spec-task execution, and manual. Managed in the IDE's Agent Hooks panel.

EARS: acceptance criteria a test can check

Kiro's requirements.md uses EARS (Easy Approach to Requirements Syntax) so the property-based tests can verify each criterion. The core template is WHEN <trigger> THE SYSTEM SHALL <response>; the IF <precondition> THEN THE SYSTEM SHALL <response> conditional is part of standard EARS. A vague line passes human review but fails the generated tests, because it names neither a concrete trigger nor an observable response.

requirements.md — vague vs. testable EARS

# Too vague to test — no concrete trigger, no observable response
The system shall handle invalid logins gracefully.
 
# Testable EARS — a property-based test can drive this directly
WHEN a person submits valid registration data
  THE SYSTEM SHALL create a new user account.
 
WHEN a person submits an email already in use
  THE SYSTEM SHALL reject the request and return a 409 conflict.
 
# The conditional (IF/THEN) variant, also standard EARS:
IF a sign-in link is older than 15 minutes
  THEN THE SYSTEM SHALL reject it as expired.

Install the Kiro CLI

Run the installer
macOS / Linux / Windows: curl -fsSL https://cli.kiro.dev/install | bash
Pick a model
The CLI offers Claude Sonnet 4.5, Claude Haiku 4.5, and an Auto mode.
Reuse Q entry points if migrating
Kiro CLI is the rebranded Amazon Q Developer CLI (auto-rollout 2025-11-24). The q and q chat commands still work and retain agent mode, MCP, steering, and custom agents.

Tier	Price	Credits
Free	`$0`	50 (trial allowance)
Pro	`$20/mo`	1,000
Pro+	`$40/mo`	2,000
Pro Max	`$100/mo`	5,000
Power	`$200/mo`	10,000

Kiro individual pricing as of 2026-06. Paid tiers add premium models and $0.04/credit pay-as-you-go overage; team plans mirror these rates and add centralized billing, usage analytics, and SAML/SCIM SSO.

Claude Code plan mode: the in-session version

Claude Code ships a first-party analogue of the spec/plan gate: plan mode, one of six permission modes (default, acceptEdits, plan, auto, dontAsk, bypassPermissions). In plan mode Claude reads files and runs shell commands to explore and writes a plan, but does not edit your source. Where Spec Kit and Kiro externalize the spec/plan/tasks as committed files, plan mode keeps the equivalent reasoning in the conversation and asks for approval before any edit.

Enter and drive plan mode

Enter it (three ways)
Press Shift+Tab to cycle default -> acceptEdits -> plan; prefix one prompt with /plan; or start with claude --permission-mode plan. The status bar shows the active mode.
Review the plan
Press Ctrl+G to open the plan in your editor and hand-edit it before proceeding.
Approve a plan
Choose: approve and start in auto mode / approve and accept edits / approve and review each edit / keep planning with feedback / refine with Ultraplan (browser-based review).
Make it the project default
Set "permissions": { "defaultMode": "plan" } in .claude/settings.json.

.claude/settings.json — make plan mode the project default

{
  "permissions": {
    "defaultMode": "plan"
  }
}

Stage	Spec Kit	AWS Kiro	Claude Code plan mode
Specify	`/speckit.specify` -> `spec.md`	`requirements.md` (EARS)	Stated outcome + constraints in the prompt
Clarify	`/speckit.clarify`	Iterate on `requirements.md`	Claude asks before drafting; you refine
Plan	`/speckit.plan` -> `plan.md`	`design.md`	The plan Claude writes (read-only)
Tasks	`/speckit.tasks` -> `tasks.md`	`tasks.md`	Plan steps, reviewed before approval
Implement	`/speckit.implement`	Run tasks in the agent	Approve the plan -> Claude edits
Artifacts	Durable files, committed	Durable files, committed	Ephemeral, in-session

The four-stage wave across three tools. Columns are equivalents, not identical commands: /speckit.plan ≈ Kiro design.md ≈ the plan Claude drafts in plan mode.

Durable artifacts vs. an in-session gate

Spec Kit / Kiro

The spec, plan, and tasks are files in the repo — reviewable in a PR, diffable over time, shareable with a team. Use for features that outlive one session or need sign-off.

Plan mode

The plan lives in the conversation — zero setup, instant, for a contained change you finish now. Nothing to commit or clean up; nothing durable to point a reviewer at later.

Knowledge check

Your spec says "the system shall handle expired sign-in links appropriately." Within a spec-driven workflow, what is the most important thing to do before letting the agent plan or implement?

Reach the end and this star joins your charted sky.