# Spec-Driven Development Workflow: A 4-Phase Gated Process for Agent-Skills

> Explore the spec-driven development workflow for agent-skills. Learn the four gated phases Specify Plan Tasks and Implement that require human approval for agent advancement.

- Repository: [Addy Osmani/agent-skills](https://github.com/addyosmani/agent-skills)
- Tags: architecture
- Published: 2026-04-16

---

**The spec-driven development workflow in the addyosmani/agent-skills repository defines a strict four-phase gated process—Specify, Plan, Tasks, and Implement—where each phase requires explicit human approval before the agent advances to the next.**

This workflow ensures every piece of code originates from a clear, human-validated specification. Defined in [`skills/spec-driven-development/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/skills/spec-driven-development/SKILL.md), it prevents implementation drift by forcing the agent to surface assumptions, define architectural boundaries, and obtain sign-off at every stage before writing any production code.

## The Four Phases of the Workflow

According to the source code in [`skills/spec-driven-development/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/skills/spec-driven-development/SKILL.md) (lines 22-31), the workflow is deliberately "gated": the agent cannot proceed to the next phase until the human reviews and approves the current deliverable.

### Phase 1: Specify

**Goal:** Produce a comprehensive written specification that captures the problem, assumptions, commands, architecture, style, testing strategy, and boundaries.

Key actions in this phase include:

- **Surface assumptions:** List every assumption (e.g., web app architecture, session-cookie usage, PostgreSQL as the database) and ask the human to confirm (lines 38-48).
- **Fill the six core sections:** Objective, Commands, Project Structure, Code Style, Testing Strategy, and Boundaries (lines 51-80).
- **Use the spec template:** A ready-made Markdown skeleton that the agent populates with project-specific details (lines 82-115).

Only after the human reviews and approves this specification does the workflow unlock Phase 2.

### Phase 2: Plan

**Goal:** Convert the approved specification into a concrete implementation plan.

This plan must outline major components, dependencies, task ordering, potential risks, and verification checkpoints (lines 31-41). The deliverable remains human-readable, and the human must sign off that the approach is sound before any tasks are created. This gate ensures the architectural strategy aligns with the validated spec before execution begins.

### Phase 3: Tasks

**Goal:** Break the implementation plan into discrete, independently implementable tasks.

Each task definition must include:

- A concise description
- Explicit acceptance criteria
- A verification step (test, build, or manual check)
- A list of files it will touch

A standardized task template is provided in the skill file to ensure consistency (lines 53-60). Like previous phases, this task list requires human approval before implementation commences.

### Phase 4: Implement

**Goal:** Execute the approved tasks one-by-one.

During implementation, the agent leverages the companion **incremental-implementation** and **test-driven-development** skills. To keep context windows manageable, the agent loads only the relevant specification sections via **context-engineering** (lines 61-65). This targeted loading ensures the agent references the correct architectural constraints and acceptance criteria without being overwhelmed by the full project scope.

## Keeping the Specification Alive

The specification is not a static document. According to the source code (lines 65-73), the spec is version-controlled and updated whenever decisions change during development. Pull requests reference the spec to maintain traceability between requirements and implementation, ensuring the specification remains the single source of truth throughout the project lifecycle.

## Key Files and Dependencies

The workflow orchestrates multiple skills across the repository:

| File | Role |
|------|------|
| [`skills/spec-driven-development/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/skills/spec-driven-development/SKILL.md) | Full definition of the spec-driven development workflow, templates, and gating rules. |
| [`skills/incremental-implementation/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/skills/incremental-implementation/SKILL.md) | Executes the **Implement** phase, applying tasks incrementally while loading relevant spec context. |
| [`skills/planning-and-task-breakdown/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/skills/planning-and-task-breakdown/SKILL.md) | Guides the **Plan** and **Tasks** phases, turning specs into actionable implementation plans. |

## Practical Examples

### Minimal Specification Template

```markdown

# Spec: User Authentication Flow

## Objective

Implement a login page where users can sign in with email/password. Success criteria: 95% of login attempts succeed, and the UI shows a friendly error on failure.

## Tech Stack

React 18, Node 18 (Express), PostgreSQL 13, JWT v9

## Commands

Build: npm run build
Test: npm test -- --coverage
Lint: npm run lint
Dev: npm run dev

## Project Structure

src/
  components/auth/   → LoginForm.tsx, SignupForm.tsx
  lib/auth/         → JWT utils, session helpers
tests/
  auth/             → unit and integration tests for login flow

## Code Style

```tsx
// Prefer arrow functions, use async/await, and TypeScript strict mode
export const login = async (email:string, password:string): Promise<User> => { … }

```

## Testing Strategy

Jest for unit tests, Cypress for end-to-end login flow, coverage ≥ 80%.

## Boundaries

- **Always:** Run `npm test` before committing.
- **Ask first:** Introducing a new OAuth provider.
- **Never:** Storing plain-text passwords.

```

### Task Definition Example

```markdown
- [ ] Task: Create login UI component
  - Acceptance: LoginForm renders, validates input, calls `login()` API.
  - Verify: Run `npm test` (Jest) and `cypress run` (login flow) with all passing.
  - Files: src/components/auth/LoginForm.tsx, src/lib/auth/api.ts

```

## Summary

- The **spec-driven development workflow** comprises four gated phases: Specify, Plan, Tasks, and Implement.
- **Human approval** is required at every phase gate to prevent premature implementation.
- The **Specify** phase produces a six-section document (Objective, Commands, Project Structure, Code Style, Testing Strategy, Boundaries) using a standardized template.
- The **Implement** phase uses companion skills (incremental-implementation, test-driven-development) and context-engineering to manage prompt size.
- Specifications are **version-controlled living documents** referenced in pull requests to maintain traceability.

## Frequently Asked Questions

### What are the six core sections required in the Specify phase?

The specification template requires **Objective**, **Commands**, **Project Structure**, **Code Style**, **Testing Strategy**, and **Boundaries**. These sections force the agent to define not just what to build, but how to build it, how to test it, and what constraints govern the implementation.

### Why does the workflow require human approval between each phase?

The gating mechanism ensures **specification validity** before resources are spent on implementation. By requiring human sign-off after Specify, Plan, and Tasks, the workflow prevents the agent from proceeding with incorrect assumptions or architectural flaws that would be costly to fix during coding.

### Which companion skills does the Implement phase use?

According to [`skills/spec-driven-development/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/skills/spec-driven-development/SKILL.md) (lines 61-65), the **Implement** phase invokes the **incremental-implementation** skill for phased execution and the **test-driven-development** skill for verification. It also utilizes **context-engineering** to load only relevant specification sections, keeping context windows manageable.

### How does the agent handle specification changes during development?

The specification is treated as a **living document**. When decisions change during implementation, the agent updates the spec file and maintains version control. The workflow explicitly requires referencing the spec in pull requests, ensuring the documentation evolves alongside the code rather than becoming stale.