spec-driven-plugin

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

Research & Navigation

Implementation

Post-Completion (Optional)

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:

## 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:

# 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:

# 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 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:

{
  "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:

codex plugin marketplace add Habib0x0/spec-driven-plugin

Or test the local checkout:

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

Override the agent backend:

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:

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'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