Skill spec-driven-implementation

Spec-Driven Implementation

Overview

After a Design Document is approved by the Design Bar Raiser, you do NOT jump directly to code. Instead, you decompose the macro design into N vertical specs—each representing an independently deliverable unit of customer value. Each spec follows the Kiro IDE trio format:

requirements.md → design.md → tasks.md

This intermediate layer exists because macro designs are too coarse for implementation and too abstract for task tracking. A spec bridges the gap: it is precise enough to code against, small enough to deliver in 1–2 weeks, and traceable back to the approved design.

The flow:

Design Document (approved) → Spec 1 → Spec 2 → ... → Spec N → Done
                                 ↓         ↓              ↓
                            Implement  Implement      Implement
                                 ↓         ↓              ↓
                             Deploy     Deploy         Deploy

Each spec is a complete vertical slice: from customer-facing behavior at the top to infrastructure at the bottom. No spec depends on "the rest being finished" to deliver observable value.

When to Use

Important: This skill is invoked as the final phase of the design command (/design), after the system Design Document is approved. It is NOT part of /build. By the time /build starts, all specs must already exist with approved requirements, design, and tasks.

• After the Design Document has been approved by the Design Bar Raiser
• Before incremental-implementation begins on any slice
• When the approved design covers more than a single deployable unit of work
• When multiple engineers will work in parallel on different parts of the system
• When requirements need to be formalized into testable acceptance criteria
• As the last step of /design — creating the specs that /build will execute

Do NOT use for:

• Trivial changes (< 2 hours of work)—go directly to implementation
• Bug fixes with clear root cause—use incremental-implementation directly
• Changes already covered by an existing spec
• Prototype/spike work (use wb-test-and-iterate instead)

Amazon Context

Flow Clarification: This skill is the LAST STEP of /design. The /design command sequence is: design-document → api-contract-first → threat-modeling → design-review → spec-driven-implementation. Once specs are created and approved here, /build picks them up and executes the tasks. /build does NOT create specs — it only reads and executes them.

This skill is the bridge in Amazon's engineering workflow:

Layer	Artifact	Scope	Audience	Approved By
Macro	Design Document	System-level blueprint	All engineers, stakeholders	Design Bar Raiser
Micro	Spec (trio)	Single vertical slice	Implementing engineer(s)	Tech Lead / Peer
Execution	PR / Commit	Individual code change	Reviewer	Code Review Bar Raiser

The Design Bar Raiser approved the macro—the overall architecture, trade-offs, cost model, and operational plan. Now you plan each slice at micro level before coding. This prevents:

1. Implementation drift: Code diverges from the approved design because engineers interpret ambiguity differently
2. Integration hell: Slices built in isolation don't compose correctly
3. Missing edge cases: Requirements not formalized means edge cases discovered in production
4. Parallelization failure: Without explicit dependency graphs, parallel work creates merge conflicts and rework

At Amazon, this maps to the practice of writing implementation plans after design approval but before sprint planning. The spec trio formalizes what many senior engineers do informally in their heads—making the reasoning explicit, reviewable, and traceable.

Template Enforcement (Non-Negotiable)

When generating spec artifacts, you MUST follow the templates EXACTLY:

1. requirements.md → Copy structure from skills/spec-driven-implementation/templates/requirements-template.md

   • MUST have: Introduction, Glossary, Requirements sections
   • Each requirement MUST have: User Story + Acceptance Criteria
   • Acceptance Criteria MUST use EARS notation: "THE [Subject] SHALL [behavior]", "WHEN [condition] THE [Subject] SHALL [action]"
   • MUST use modal verbs: SHALL, SHALL NOT, MUST, MAY
   • Each criterion must be individually testable and referenceable (e.g., "1.3.a")

2. design.md → Copy structure from skills/spec-driven-implementation/templates/design-template.md

   • MUST have: Overview, Architecture (with Mermaid diagrams), Components & Interfaces (with code signatures), Data Models, Error Handling, Properties (PBT), Testing Strategy, Security, Open Questions
   • MUST include at least one Mermaid sequence diagram
   • MUST reference requirements by number (traceability)

3. tasks.md → Copy structure from skills/spec-driven-implementation/templates/tasks-template.md

   • MUST have: Legend, Phases with green-build gates, Tasks with sub-tasks
   • Each task MUST have: size estimate (S/M/L/XL), traceability annotations (Requirements: X.Y, Design: §N.N, Depends on: Task X.Y), Wave assignment
   • MUST end with Dependency Graph JSON showing waves
   • MUST use status markers: - [ ] pending, - [-] in progress, - [x] done, - [!] blocked

⛔ RED FLAG: If your spec output does NOT have these sections, STOP and redo it following the template. ⛔ RED FLAG: If your requirements don't use EARS notation (SHALL/WHEN/IF), STOP and rewrite them. ⛔ RED FLAG: If your tasks.md doesn't have a dependency graph with waves, STOP and add it.

The Process

1. Identify Vertical Slices from the Design Document

Read the approved Design Document and identify slices that:

Criteria	Good Slice	Bad Slice
Delivers observable value	User can see/use something new	Only adds internal plumbing
Vertical completeness	API → Logic → Storage → Observability	Only a database migration
Independent deployability	Works without other slices being done	Requires slice 3 to function
Bounded scope	1–2 weeks of implementation	Multi-month effort
Testable in isolation	Has clear acceptance criteria	"Works when everything else works"

Outputs: A numbered list of slices with one-line descriptions and estimated effort.

2. Order Slices by Risk, API First, and Dependency

Apply the hardest-first principle (fail fast), with API First as the dominant ordering rule:

• Tier 1 — Foundation: Infrastructure, schemas, control plane, shared interfaces that others depend on. Only present when an adopted pattern (e.g., cell-based) demands it, or when a one-way door decision (e.g., partition key) must be locked first.
• Tier 2 — API: The API spec(s) implementing the customer-value contract end-to-end (handler → logic → storage → observability for that API surface). The API is the only customer-facing contract. No client spec is created before the API it consumes is specified and frozen.
• Tier 3 — Clients: UI, CLI, SDK, MCP server, AI agent, partner integration, batch job — each is its own spec, built on the now-stable API. A "client" is anything that consumes an API; the word "frontend" is too narrow.
• Tier 4 — Hardening: Edge case handling, degraded modes, performance optimization, operational polish, documentation.

Within each tier, order by dependency: if Slice B imports from Slice A, A comes first.

API First — the non-negotiable ordering rule

API specs precede client specs. When a feature involves both an API and one or more clients (UI, CLI, SDK, MCP, AI agent, batch job, partner integration), the API spec is created and approved first. Client specs are created only after the API contract is stable. This is not negotiable — it prevents the client from leaking implementation assumptions into a not-yet-frozen API surface, and it keeps every client equivalent from the contract's point of view.

The API may be REST, gRPC, an event schema, a data contract, an MCP tool surface, or an agent tool definition. The protocol does not change the rule.

If you find yourself ordering a UI spec before its API spec, stop — you have inverted the dependency. The UI cannot exist without a stable API, and any work done before the API is stable will need to be redone when the API is finalized.

Rationale: If the hardest part is impossible or needs redesign, you discover that in week 1, not week 8. Two-way door decisions (reversible) can be reordered; one-way door decisions (schema migrations, public APIs, partition keys) are sequenced carefully — and almost always live in Tier 1 or Tier 2.

3. Create a Spec for Each Slice (The Trio)

⛔ MANDATORY HUMAN REVIEW GATES: Each artifact (requirements → design → tasks) has a mandatory pause for user review. Do NOT generate the next artifact until the previous one is explicitly approved by the user.

For each slice, create three files in .bla/specs/<slice-name>/:

3.1 requirements.md

Extract and formalize requirements for this slice only from the Design Document.

• Use the EARS (Easy Approach to Requirements Syntax) format
• Each requirement has a User Story and Acceptance Criteria
• Acceptance Criteria use SHALL/MUST/MAY with WHEN/IF/WHERE conditions
• Cross-reference the Design Document section that drives each requirement

Agent: Load agents/requirements-analyzer.md and apply the requirements-analyzer persona to review the requirements for:

• Logical inconsistencies across requirements
• Ambiguous terms ("fast", "large scale", "reasonable")
• Conflicting constraints
• Unstated assumptions
• Missing edge cases and boundary conditions

The agent asks clarifying questions with suggested fixes and updates the requirements.

🚦 GATE: Present requirements.md to the user. Ask: "Review these requirements. Anything missing, ambiguous, or wrong?" Wait for explicit approval. Do NOT generate design.md until requirements are approved.

3.2 design.md

Detailed technical design for this slice only:

• Architecture specific to this slice (Mermaid diagrams)
• Component interfaces with code signatures
• Data models (schema, types, validations)
• Error handling strategy (retry, circuit breaker, fallback)
• Dependency behavior inherited from the approved Design Document (classification, timeout/retry policy, circuit breakers, bulkheads, fallback behavior, observability)
• Feature flag behavior inherited from the approved Design Document (flag type, safe default, OFF behavior, kill switch behavior, rollout metrics, cleanup)
• Operational behavior inherited from the approved Design Document (customer experience metrics, service health metrics, dashboards, alarms, runbooks, severity expectations, operational burden)
• Properties for property-based testing (PBT)
• Testing strategy (unit, integration, contract)
• Security considerations specific to this slice

This is NOT a repeat of the macro design. It adds implementation detail: exact function signatures, error codes, retry policies, concurrency handling, dependency failure behavior, feature flag behavior, operational behavior, and test properties that the macro design intentionally omits. Specs must preserve dependency-management, feature-flag lifecycle, and operational-excellence decisions from the approved Design Document rather than rediscovering them during /build.

🚦 GATE: Present design.md to the user. Ask: "Review this design. Trade-offs make sense? Anything to adjust?" Wait for explicit approval. Do NOT generate tasks.md until design is approved.

3.3 tasks.md

Decompose the design into executable tasks:

• Organized in phases with green-build gates between them
• Tasks grouped into parallelizable waves
• Each task has sub-tasks, size estimates, and traceability
• Dependency annotations link tasks to each other
• Requirement traceability links tasks to requirements
• Design references link tasks to design sections
• A dependency graph JSON at the end enables tooling

Agent: Load agents/task-planner.md and apply the task-planner persona to generate the dependency graph, identify the critical path, group tasks into waves, and flag one-way door decisions that need extra review.

🚦 GATE: Present tasks.md to the user. Ask: "Review this task plan. Dependencies correct? Sizing makes sense?" Wait for explicit approval. The spec is only ready for /build after tasks are approved.

4. Approval Gates

Each spec goes through review before execution:

Gate	Reviewer	Focus
Requirements Review	Product/Tech Lead	Completeness, correctness, priority
Design Review	Peer Engineer	Feasibility, interface contracts, testability
Task Review	Tech Lead	Ordering, parallelization, risk

A spec can be rejected back to any previous stage. Rejection is cheap at this stage—it's just markdown. Rejection after coding is expensive (throwaway code, morale damage).

5. Execute Tasks Wave-by-Wave

Once a spec is approved:

1. Execute Wave 1 tasks (these have no dependencies)
2. Verify green-build gate passes (all tests green, no regressions)
3. Execute Wave 2 tasks (depend on Wave 1 outputs)
4. Continue until all waves are complete
5. Load agents/implementation-verifier.md and apply the implementation-verifier persona to validate PBT properties

Parallel execution within a wave is safe only when both of these invariants hold:

1. No intra-wave logical dependency. No task in the wave consumes an output produced by another task in the same wave. This one the task-planner does guarantee — it is exactly what the dependency graph models — and python3 tools/bla-check tasks .bla/specs/<slice-name> re-reads the emitted graph and reports FALHA [wave-dep-intra] where the guarantee slipped, because /build dispatches only tasks whose dependencies are all [x] and a task depending on a wave-mate is therefore never dispatched in that wave.
2. No intersection of files written within the wave. No two tasks in the wave write the same file. This one the graph models too: skills/spec-driven-implementation/templates/tasks-template.md carries depends_on, wave, size, type, door and writes per task, and writes is the declared set of paths that task changes. The invariant is therefore checkable by comparing the declared sets: for every pair of tasks in one wave, the intersection of their writes must be empty, where a path ending in / is a directory and collides with everything beneath it. python3 tools/bla-check tasks .bla/specs/<slice-name> performs that comparison and reports FALHA [wave-writes-intersection]. A task that changes no file in the repository declares no writes, and there is then nothing to intersect on its behalf.

Because a declared set can be wrong where a read cannot — a task may write a file it never declared — the check is necessary and not sufficient, and the serialisation rule is unchanged. When two tasks in the same wave must write the same file — a barrel of exports, a router registration, a schema migration — the intersection is mandatory and parallel execution would produce a lost write or a conflict. Serialise them: keep one task in the wave and move the colliding task to the next wave. /build closes the gap at the other end, by comparing the union of the wave's declared writes against the paths git says actually changed.

6. Post-Spec Completion

After each spec is fully implemented:

1. Run code-review-bar-raising on the aggregate changes
2. Deploy using progressive-deployment (or batch multiple specs before deploying)
3. Verify acceptance criteria pass in production (canary)
4. Mark the spec as DONE and proceed to the next spec

7. Spec Coherence Review (Pre-Build Gate)

After all 3 spec artifacts are approved (requirements.md, design.md, tasks.md) and BEFORE the spec is handed to /build, run a coherence review to catch drift between the spec and the approved Design Document.

Reviewers: Load agents/design-bar-raiser.md and apply the design-bar-raiser persona. For one-way door decisions, also load agents/principal-engineer.md and apply the principal-engineer persona.

What they check:

1. Does the spec contradict any decision from the System Design Document?
2. Are all requirements traceable to sections in the Design Doc?
3. Are there new architectural decisions in the spec that weren't in the Design Doc? (scope creep)
4. Is the tasks.md dependency graph achievable within the architecture described?
5. Are one-way door decisions in the spec consistent with the ones identified at design level?
6. Are dependency-management decisions from the Design Document preserved in requirements, slice design, and tasks?
7. Are feature-flag lifecycle decisions from the Design Document preserved in requirements, slice design, and tasks?
8. Are operational-excellence decisions from the Design Document preserved in requirements, slice design, and tasks?

Output format (structured so the build agent can consume it directly):

## Spec Coherence Review — [Spec Name]

### Verdict: APPROVED | APPROVED WITH NOTES | NEEDS REVISION

### Coherence Matrix
| Requirement | Design Doc Section | Status | Note |
|---|---|---|---|
| Req 1.1 | §3.2 Architecture | ✅ Aligned | — |
| Req 1.2 | §3.2 Architecture | ✅ Aligned | — |
| Req 2.3 | §4.1 Data Model | ⚠️ Divergence | Spec uses DynamoDB but Design Doc specified PostgreSQL |
| Req 3.1 | §5.1 Integration | ❌ No traceability | Requirement not found in Design Doc |

### Findings
- [BLOCKING] Description of blocking issue (must fix before /build proceeds)
- [WARNING] Description of non-blocking concern (proceed with awareness)
- [NOTE] Observation or context for the implementing agent

### Action Items for Build Agent
- [ ] When implementing Req 2.3, use PostgreSQL as specified in Design Doc §4.1 (not DynamoDB as written in spec)
- [ ] Req 3.1 references a service that doesn't exist yet — implement stub first (see Task 1.2)
- [ ] One-way door in Task 2.3 (schema migration) — confirm index strategy matches Design Doc §4.3 before executing

The "Action Items for Build Agent" section is the KEY deliverable — it becomes an addendum that the build agent reads alongside tasks.md. Save the review output to .bla/specs/<slice-name>/coherence-review.md.

🚦 GATE:

• If verdict is APPROVED: Proceed to /build. The build agent reads coherence-review.md alongside tasks.md.
• If verdict is APPROVED WITH NOTES: Proceed to /build. The "Action Items for Build Agent" section is mandatory reading for the build agent.
• If verdict is NEEDS REVISION: Go back and fix the spec artifacts. Do NOT proceed to /build until re-reviewed.

How the build agent uses this: When /build starts on a spec, it checks for .bla/specs/<slice-name>/coherence-review.md. If present, the "Action Items for Build Agent" section is treated as binding constraints — equivalent to additional requirements that override or clarify what's in the spec. If an action item conflicts with tasks.md, the action item wins.

The Spec Format

requirements.md Format

# Requirements: [Slice Name]

## 1. Introduction

### 1.1 Context
[What part of the system this slice addresses]

### 1.2 Scope
[What is IN scope for this spec]

### 1.3 Non-Goals
[What is explicitly OUT of scope]

### 1.4 Design Document Reference
[Link to the approved Design Document section(s)]

## 2. Glossary

| Term | Definition |
|------|-----------|
| ... | ... |

## 3. Requirements

### 3.1 [Feature Area]

#### Requirement 3.1.1: [Short Name]

**User Story**: As a [role], I want [action] so that [benefit].

**Acceptance Criteria**:
1. WHEN [trigger] the system SHALL [behavior] — [rationale]
2. IF [condition] THEN the system MUST [behavior] — [rationale]
3. WHERE [context] the system MAY [behavior] — [rationale]

**Priority**: P0 | P1 | P2
**Design Ref**: §[section number] of Design Document

design.md Format

# Design: [Slice Name]

## 1. Overview
[What this slice implements and why this design approach]

## 2. Architecture

```mermaid
[Component/sequence diagram specific to this slice]

3. Components & Interfaces

3.1 [Component Name]

interface ComponentName {
  method(param: Type): ReturnType;
}

Responsibilities: ... Error Contract: ...

4. Data Models

[Schema definitions, type definitions, validations]

5. Error Handling

Error	Detection	Response	Recovery
...	...	...	...

6. Properties (PBT)

Property	Formal Statement	Generator Strategy
Idempotency	f(f(x)) = f(x) for all x	Random valid inputs
Monotonicity	if a ≤ b then f(a) ≤ f(b)	Ordered pairs

7. Testing Strategy

Level	What	How	Coverage Target
Unit	Pure logic	PBT + example-based	90%+
Integration	Component boundaries	Contract tests	All interfaces
E2E	User-facing flows	Acceptance criteria	All P0 requirements

8. Security

[Authentication, authorization, data protection for this slice]

9. Open Questions

[Unresolved decisions to discuss during review]

### tasks.md Format

```markdown
# Tasks: [Slice Name]

## Legend

- 🏗️ Infrastructure / Setup
- 🔧 Implementation
- 🧪 Testing
- 📖 Documentation
- 🚀 Deployment
- 🔒 One-way door (irreversible — needs explicit approval)
- 🔓 Two-way door (reversible — bias for action)
- ✅ Green-build gate

## Phase 1: Foundation

✅ **Green-build gate**: All existing tests pass. CI pipeline green.

### Task 1.1: [Task Name] 🏗️ 🔓

_Size: S | Requirements: 3.1.1 | Design: §3.1_
_Depends on: None (Wave 1)_

- [ ] Sub-task A
- [ ] Sub-task B
- [ ] Sub-task C

### Task 1.2: [Task Name] 🔧 🔓

_Size: M | Requirements: 3.1.2, 3.2.1 | Design: §3.2_
_Depends on: Task 1.1_

- [ ] Sub-task A
- [ ] Sub-task B

## Phase 2: Core Logic

✅ **Green-build gate**: Phase 1 tests pass. New interfaces compile. No regressions.

### Task 2.1: [Task Name] 🔧 🔓

_Size: L | Requirements: 3.2.1 | Design: §4.1_
_Depends on: Task 1.2 (Wave 2)_

- [ ] Sub-task A
- [ ] Sub-task B
- [ ] Sub-task C
- [ ] Sub-task D

## Dependency Graph

```json
{
  "tasks": {
    "1.1": { "depends_on": [], "wave": 1, "size": "S", "writes": ["src/domain/types.ts"] },
    "1.2": { "depends_on": ["1.1"], "wave": 1, "size": "M", "writes": ["src/db/schema.ts"] },
    "2.1": { "depends_on": ["1.2"], "wave": 2, "size": "L", "writes": ["src/service/resource-service.ts"] }
  },
  "critical_path": ["1.1", "1.2", "2.1"],
  "waves": {
    "1": ["1.1", "1.2"],
    "2": ["2.1"]
  }
}

## Three Specialized Sub-Agents