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
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install spec-driven@awesome-codex-pluginsWhat 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-authenticationand take me through the three phases - Keep
/spec-looprunning until every task intasks.mdis closed - Show
/spec-statusso 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-pluginsStep 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