Skip to main content
plugin CX Codex

spec-driven — Claude Code plugin: what it does, how to install

spec-driven turns a feature idea into requirements, design and tasks, then lets the agent build them.

MIT ★ 1,596 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install spec-driven@awesome-codex-plugins
Open on GitHub

What spec-driven does

/spec <name> creates .claude/specs/<name>/ and fills it with three files before any code appears. requirements.md holds user stories with acceptance criteria written in EARS form: a trigger line, then what the system must do. design.md covers architecture and the implementation plan. tasks.md lists discrete items with status, verification and dependencies, and those items mirror into Claude's todo list. Requirements come out of two or three rounds of questions.

Execution lives in the plugin's scripts/ folder. One pass is bash scripts/spec-exec.sh --spec-name <name>; the loop variant keeps going until --max-iterations runs out. Each pass starts with a checkpoint commit, so a crash with a non-zero exit rolls the branch back. A spec can name other specs under ## Depends On in requirements.md, and nothing runs until every task in those dependencies is verified.

Codex takes the same commands with $ in front. SPEC_ROOT moves the spec root; .codex/specs/ is read as a fallback for older layouts. Once tasks are done there is an optional tail: acceptance, docs, release notes, smoke tests against --url, a retrospective, or the whole chain via spec-complete.sh. spec-verify.sh returns 0 on pass and 1 on fail, which is exactly what a CI stage wants.

What it helps with

  • Break a feature idea into requirements, design and tasks before touching code
  • Write acceptance criteria in EARS so each one can be tested
  • Run an autonomous loop that rolls back to a checkpoint when the agent dies
  • Declare dependencies between specs and block execution until they clear
  • Wire post-deploy smoke tests into a CI pipeline through exit codes

Example prompts for the agent

  • Run /spec user-authentication and take me through the three phases
  • Keep /spec-loop running until every task in tasks.md is closed
  • Show /spec-status so I can see what is done and which dependency blocks me

How to install spec-driven

Plugin marketplace

/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install spec-driven@awesome-codex-plugins

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about spec-driven

How do I install spec-driven in Claude Code?

Add the marketplace first: /plugin marketplace add hashgraph-online/awesome-codex-plugins. Then install the plugin: /plugin install spec-driven@awesome-codex-plugins.

What does spec-driven do?

It walks a feature through requirements, design and tasks, then runs implementation from those tasks with scripts, including a loop that checkpoints each pass.

Where are the spec files stored?

Under .claude/specs/<feature-name>/ as requirements.md, design.md and tasks.md. Set SPEC_ROOT to use a different root.

Source text

spec-driven-plugin · MIT
# Spec-Driven Development Plugin

A structured workflow plugin for Claude Code & Codex that transforms feature ideas into formal specifications before implementation.

## Overview

This plugin guides you through three phases:

1. **Requirements** - User stories with EARS notation and acceptance criteria
2. **Design** - Technical architecture, sequence diagrams, implementation considerations
3. **Tasks** - Discrete, trackable implementation items that mirror to Claude Code's todo system

## Commands

Commands use `/` prefix in Claude Code and `$` prefix in Codex.

### Core Workflow
| Claude Code | Codex | Description |
|-------------|-------|-------------|
| `/spec-brainstorm` | `$spec-brainstorm` | Brainstorm a feature idea before spec creation |
| `/spec <name>` | `$spec <name>` | Start a new feature spec with interactive 3-phase workflow |
| `/spec-bugfix <name>` | `$spec-bugfix <name>` | Start a new bugfix spec with defect analysis and regression prevention |
| `/spec-refine` | `$spec-refine` | Refine requirements/design for current spec |
| `/spec-tasks` | `$spec-tasks` | Regenerate tasks from updated spec |
| `/spec-status` | `$spec-status` | Show spec progress, task completion, and dependency status |
| `/spec-validate` | `$spec-validate` | Validate spec completeness and consistency |

### Research & Navigation
| Claude Code | Codex | Description |
|-------------|-------|-------------|
| `/research` | `$research` | Deep parallel research before planning — searches docs, web, and codebase |
| `/zoom-out` | `$zoom-out` | Map modules, interfaces, and callers for unfamiliar code |
| `/ubiquitous-language` | `$ubiquitous-language` | Extract domain terms into a canonical glossary with flagged ambiguities |

### Implementation
| Claude Code | Codex | Description |
|-------------|-------|-------------|
| `/spec-exec` | `$spec-exec` | Run one autonomous implementation iteration |
| `/spec-loop` | `$spec-loop` | Loop implementation until all tasks complete |

### Post-Completion (Optional)
| Claude Code | Codex | Description |
|-------------|-------|-------------|
| `/spec-accept` | `$spec-accept` | Run user acceptance testing for formal sign-off |
| `/spec-docs` | `$spec-docs` | Generate documentation from spec and implementation |
| `/spec-release` | `$spec-release` | Generate release notes and deployment checklist |
| `/spec-verify` | `$spec-verify` | Run post-deployment smoke tests |
| `/spec-retro` | `$spec-retro` | Run a retrospective on a completed spec |
| `/spec-complete` | `$spec-complete` | Run full post-completion pipeline (accept → docs → release → retro) |

## Usage

### Starting a New Spec

**Claude Code:**
```
/spec user-authentication
```

**Codex:**
```
$spec user-authentication
```

This will:
1. Create `.claude/specs/user-authentication/` directory
2. Gather requirements interactively (2-3 rounds of questions)
3. Guide you through Design phase (architecture docs)
4. Generate Tasks with explicit status, wiring, verification, and dependencies

### Spec Files Location

Specs are stored in `.claude/specs/<feature-name>/` by default. Existing `.codex/specs/<feature-name>/` directories are supported as a migration fallback, or set `SPEC_ROOT` explicitly:

```
.claude/specs/user-authentication/
├── requirements.md   # User stories with acceptance criteria
├── design.md         # Architecture and implementation plan
└── tasks.md          # Trackable implementation tasks
```

### Cross-Spec Dependencies

Specs can declare dependencies on other specs via a `## Depends On` section in requirements.md:

```markdown
## Depends On

- auth-system
- database-migrations
```

Execution scripts check dependencies before running. A dependency is considered complete when all its tasks are verified. `/spec-status` shows dependency status.

## Implementation

After creating a spec, run autonomous implementation:

```bash
# single task
bash scripts/spec-exec.sh --spec-name user-authentication

# loop until all tasks complete
bash scripts/spec-loop.sh --spec-name user-authentication --max-iterations 20
```

Scripts live in the plugin's `scripts/` directory. If only one spec exists, `--spec-name` is auto-detected.

### Post-Completion (Optional)

After implementation completes, optionally run:

```bash
# user acceptance testing
bash scripts/spec-accept.sh --spec-name user-authentication

# generate documentation
bash scripts/spec-docs.sh --spec-name user-authentication

# release notes and deployment checklist
bash scripts/spec-release.sh --spec-name user-authentication

# post-deployment smoke tests
bash scripts/spec-verify.sh --spec-name user-authentication --url https://staging.example.com

# retrospective analysis
bash scripts/spec-retro.sh --spec-name user-authentication

# or run all at once
bash scripts/spec-complete.sh --spec-name user-authentication
```

### Checkpoint Recovery

`spec-loop.sh` creates checkpoint commits before each iteration. If the agent crashes or exits non-zero, the branch is rolled back to the last checkpoint automatically.

### CI/CD Integration

The verification script returns exit codes for CI pipelines:
- `spec-verify.sh` exits `0` on PASS, `1` on FAIL (promise markers: `VERIFIED` / `VERIFICATION_FAILED`)
- `spec-accept.sh` outputs `<promise>ACCEPTED</promise>` or `<promise>REJECTED</promise>`
- `spec-loop.sh` outputs `<promise>COMPLETE</promise>` when all tasks are done

Example CI stage:
```bash
bash scripts/spec-verify.sh --spec-name user-authentication --url "$STAGING_URL" --scope quick || exit 1
```

## Spec-Loop Performance

The loop script includes optimizations for long-running specs:
- **Progress tail**: Only the last 20 progress entries are included in the prompt (configurable via `--progress-tail`)
- **Lightweight Step 1**: Iterations 2+ skip full environment checks
- **Spec reference**: Requirements and design are referenced by path (not inlined) after iteration 1
- **Timing**: Each iteration prints elapsed time

## EARS Notation

Requirements use EARS (Easy Approach to Requirements Syntax):

```
WHEN [condition/trigger]
THE SYSTEM SHALL [expected behavior]
```

Example:
```
WHEN a user submits invalid form data
THE SYSTEM SHALL display validation errors inline
```

## Installation

### Claude Code

Add to your `~/.claude/settings.json`:

```json
{
  "enabledPlugins": {
    "spec-driven@spec-driven": true
  },
  "extraKnownMarketplaces": {
    "spec-driven": {
      "source": {
        "source": "url",
        "url": "https://github.com/Habib0x0/spec-driven-plugin.git"
      }
    }
  }
}
```

Then restart Claude Code.

### Codex

This repository includes a Codex plugin manifest at `.codex-plugin/plugin.json`.

Install from GitHub:

```bash
codex plugin marketplace add Habib0x0/spec-driven-plugin
```

Or test the local checkout:

```bash
codex plugin marketplace add /path/to/spec-driven-plugin
```

Override the agent backend:

```bash
export SPEC_ROOT=.codex/specs
export SPEC_AGENT_CMD='codex exec --full-auto -'
bash scripts/spec-exec.sh --spec-name user-authentication
```

#### Usage in Codex

Codex commands use `$` prefix instead of `/`:

```
$spec user-authentication
$spec-status
$spec-exec
```

You can also invoke the skill by typing one of its default prompt phrases:

| Prompt | Action |
| --- | --- |
| `Create a spec for this feature` | Start a new spec workflow |
| `Validate the current spec` | Run validation on the active spec |
| `Break this design into tasks` | Regenerate tasks from the design doc |

Or reference it by display name: `Use Spec Driven to plan user authentication`.

**Plan mode vs build mode:** Works in both. Plan mode generates the spec for review before writing; build mode writes files directly. Implementation scripts (`spec-exec.sh`, `spec-loop.sh`) run from your terminal.

All generated spec files live in `.codex/specs/<feature-name>/` when running under Codex.

## Inspiration

This plugin was inspired by [Kiro](https://kiro.dev)'s spec-driven development functionality. Kiro introduced the concept of structured specification workflows that guide developers through requirements gathering, design, and task breakdown before implementation.

Key concepts borrowed from Kiro:
- **Three-phase workflow**: Requirements → Design → Tasks
- **EARS notation**: Structured acceptance criteria format
- **Spec file organization**: Dedicated spec directories with separate documents for each phase
- **Task traceability**: Linking implementation tasks back to requirements

## License

MIT

© habib0x · MIT · hashgraph-online/awesome-codex-plugins

Similar plugins

All plugins for Agent setup: memory, context, orchestration →
tlc-spec-driven Felipe Rodrigues - github.com/felipfr tlc-spec-driven guides feature development through four adaptive phases with EARS specs, automated gates, and atomic commits. Useful when you need test-backed code execution. CX Codex +1 1,300installs ns-spec-driven nextstage-brasil ns-spec-driven is a Claude Code skill that drives feature delivery through formal specifications. It triggers on medium or large tasks, multi-day work, or when resuming a version from docs/versions/. CX Codex +1 208installs spec-driven-workflow-v1 official github The spec-driven-workflow-v1 rule structures work from requirements analysis through design, implementation, and validation. Use it when you want decisions and progress recorded in project files. CX Codex +1 ★ 41,430repo stars spec-driven-workflow Alireza Rezvani spec-driven-workflow makes the agent write a specification before any code: requirements, acceptance criteria, scope limits. Useful when a feature needs thinking through first. CX Codex +1 600installs mcp-server-spec-driven-development reason-machines The mcp-server-spec-driven-development skill guides a project from EARS requirements to a design document and generated code. Use it when you want those steps to build on one another. CX Codex +1 175installs spec-driven-development formulahendry The spec-driven-development MCP server guides an agent from requirements to a design document and implementation code. Use it to give a project a written specification before code generation. CX Codex +1 ★ 441repo stars

From the same set391

The whole set →
stark stark guides an AI coding agent through interface decisions before implementation, then checks the rendered result. Use it to shape a new flow or review an existing screen. CX Codex ★ 1,596repo stars stacked-prs stacked-prs turns one oversized branch into small reviewable PRs, sends review fixes up the chain and merges the stack in dependency order. CX Codex ★ 1,596repo stars spellbook-skills spellbook-skills — a bundle of 10 engineering skills and a project context hook for Claude Code and Codex that covers git worktrees, TDD, code reviews, and PR creation. CX Codex ★ 1,596repo stars spec-superflow spec-superflow — a plugin for direct or planned coding workflows with saved state, final review, and verification. Use it when a change needs a clear scope and a checkable finish. CX Codex ★ 1,596repo stars sno-station-standalone The sno-station-standalone plugin for Claude Code and Codex reviews code, audits intent, and generates tests locally without accounts or external hooks. CX Codex ★ 1,596repo stars skill-sync-publisher skill-sync-publisher is a plugin for Claude Code and Codex that checks a local SKILL.md package and syncs it with GitHub and skill directories. It publishes one version to several registries. CX Codex ★ 1,596repo stars skill-skill skill-skill writes agent skills that change what gets generated, then lints SKILL.md against the Agent Skills spec and scores its health from 0 to 100. CX Codex ★ 1,596repo stars since-cutoff since-cutoff finds Python dependency changes after your model's knowledge cutoff and records short rules in AGENTS.md to stop the assistant from generating outdated API calls. CX Codex ★ 1,596repo stars

Project sponsors

Companies that keep this analytics open