vibe-spec

A Claude Code plugin for spec-driven development. Write the spec, then let the agent break it into tasks and build them. Tests first, one commit per task, reviewed as it goes.

Two commands, two phases:

All commands are user-invoked only. Claude will not enter a phase on its own.

/vibe-spec:spec writes each spec as a requirements.md and design.md pair, so behaviour is tracked apart from architecture. That split is what lets /vibe-spec:build tell a requirements change (tasks may have built the wrong thing) from a design-only change (completed tasks still stand). How the directories under spec/ are laid out is up to your repo; single-file specs written before this still work.

Repo-wide conventions — tech stack, commands, project structure, code style, test framework, boundaries — belong in CLAUDE.md, not in a spec. /vibe-spec:spec writes them there when they are missing.

flowchart LR
    spec["/vibe-spec:spec"] --> specs[("spec/*.md")]
    specs --> review["You review"]
    review --> build["/vibe-spec:build"]
    build --> tasks[(".tasks/plan.md<br>.tasks/todo.md")]

Philosophy

• One gate, at the spec. Everything downstream is derived from it.
• Speed is the point. A gate that catches nothing is pure latency.
• Build the whole thing at once. Rollback is git revert, not your attention.

Install

Claude Code

/plugin marketplace add yuntan/vibe-spec
/plugin install vibe-spec@yuntan-vibe-spec

Cursor

Local: Cursor rejects symlinks pointing outside ~/.cursor/plugins/local, so copy instead:

mkdir -p ~/.cursor/plugins/local
rsync -a --delete \
  --exclude .git \
  "$(pwd)/" ~/.cursor/plugins/local/vibe-spec/

Then reload the window (Developer: Reload Window). Run rsync again after editing skills.

Team Marketplace: Dashboard → Plugins → Import from Repo → https://github.com/yuntan/vibe-spec

Codex

codex plugin marketplace add yuntan/vibe-spec

What's inside

The plugin is self-contained. Along with the two orchestration skills, it vendors the knowledge skills they delegate to from addyosmani/agent-skills, so installing vibe-spec pulls in everything it needs:

planning-and-task-breakdown · incremental-implementation · test-driven-development · code-review-and-quality · debugging-and-error-recovery · doubt-driven-development

These stay active as ordinary skills too — Claude reaches for them during normal work, not only inside the workflow.

Vendored content is refreshed from upstream with:

scripts/sync-agent-skills.sh          # sync to the newest upstream tag
scripts/sync-agent-skills.sh --check  # report drift without changing anything

agent-skills.lock records the pinned version. See CLAUDE.md before editing anything under skills/ or references/. Most of it is copied in, and the sync script overwrites hand edits.

Credits

The vendored skills are addyosmani/agent-skills, pinned at 0.6.6. MIT licensed. See LICENSE.