Methodology · Spec-Drivenemergingpartial

Requirements-First Spec Workflow

also known as Kiro spec workflow, EARS-based spec workflow, requirements-design-tasks

Applies to: coding-agentagentsoftware-teamregulated-software

Tags: spec-drivenrequirementsearscoding-agent

Drive the build from a structured requirements document, then a design, then tasks. Write requirements as user stories with EARS acceptance criteria of the form 'when X, the system shall Y'. Generate a design with architecture and data models from those requirements. Break the design into tasks the agent runs, independent ones first. A design-first variant flips the order when the architecture is the hard part.

Methodology process overview

flowchart TD feat[Feature to formalise] --> req[Requirements in EARS] req --> design[Design: architecture + data models] design --> tasks[Dependency-ordered task list] tasks --> wave[Run tasks in dependency waves] wave --> check[Check against acceptance criteria] feat -.design-first variant.-> design

Intent. Formalise a feature as testable requirements, then a validated design, then dependency-ordered tasks an agent can execute.

When to apply. Use this when a feature is complex enough that jumping to code loses requirements, and when you want acceptance criteria you can check implementation against. It suits regulated or interface-heavy work where 'the system shall' statements matter. Don't apply the requirements-first order when the architecture is the genuinely hard part; use the design-first variant then.

Example scenario

A fintech team builds a transaction-export feature that must satisfy auditors, so vague requirements are a real risk. Using a spec-driven IDE in the Kiro shape, they started in the requirements phase. Each rule became a user story with EARS acceptance criteria, for example 'when an export includes transactions older than seven years, the system shall require a compliance approval'. Writing them this way surfaced two rules nobody had agreed on, which they resolved before any design. The tool then generated a design document with a sequence diagram, the export service interface, and the data model, which they checked against the requirements. It broke the design into fourteen tasks and built a dependency graph: schema and validation tasks had no dependencies and ran first, while the UI tasks waited on the service. They ran the independent tasks concurrently, then the dependent ones, and checked each finished task back against its acceptance criteria. The EARS phrasing made that check mechanical: every 'shall' was either demonstrably met or not.

Inputs

Feature or bug to formalise — The change to make, ready to be turned into user stories and acceptance criteria.
Existing codebase context — The current architecture and code the design must fit into.
Spec-driven IDE or agent — Tooling such as Kiro that generates requirements, design, and a runnable task list.

Outputs

Requirements document — User stories with EARS acceptance criteria that state, testably, what the system shall do.
Design document — Architecture, component interfaces, and data models, with diagrams, that satisfy the requirements.
Dependency-ordered task list — The design broken into tasks with their dependencies, ready to run independent ones in parallel.

Steps (5)

Gather requirements in EARS
Write user stories with acceptance criteria in the form 'when X, the system shall Y'. The constraint forces each criterion to be checkable.
usesPre-Flight Spec Authoring
Generate the design
Turn approved requirements into a design document: architecture, interfaces, and data models, with diagrams, fitted to the existing code.
Break into a dependency-ordered task list
Decompose the design into tasks and record which depend on which, so independent work can run in parallel.
usesPlan-and-Execute
Run tasks in waves
Execute tasks by dependency wave: all tasks with no unmet dependencies run together, then the next wave once theirs are satisfied.
usesSpec-Driven Loop
Check against acceptance criteria
Verify each finished task against its EARS criteria. Every 'shall' is either demonstrably met or it is not done.
usesHuman-in-the-Loop