Vibe-Spec
A spec-driven development workflow and a production-tested full-stack reference —
packaged as a Claude Code plugin. Instead of copy-pasting a markdown file, install it
once and get nine /spec-* commands — a five-step workflow, three setup helpers, and
a redacted secret-leak audit — and an on-demand stack reference for Next.js, Prisma,
PostgreSQL, and the rest of the stack.
Refined through real production projects. You only adopt what you need — every
reference has skip/need conditions.
Install
In Claude Code, run:
/plugin marketplace add Connorrmcd6/vibe-spec
/plugin install vibe-spec
That's it — the /spec-* commands and the vibe-spec skill are now available.
Get your machine ready
The stack assumes a few tools (Git, Node + pnpm, and — depending on the project —
Docker and Python/uv). Three helper commands handle setup and recovery so you only
install what your project actually needs:
| Command | What it does |
|---|
/spec-setup | Run me first. Figures out which tools your project needs (from your spec, or by project type) and helps install only the gaps — proposing exact per-OS commands and running each only after you confirm. |
/spec-doctor | Read-only health check: reports which tools are installed, their versions, and the Docker daemon state. Installs nothing. |
/spec-troubleshoot | Diagnoses common failures (Docker daemon down, port conflicts, missing DATABASE_URL, Prisma client not generated, pnpm-vs-npm, broken git hooks) and walks you through the fix. |
Prefer the old way? The full reference still lives in the repo under
skills/vibe-spec/reference/ — read or copy any
section directly.
The workflow: 5 commands
Write a spec before touching code, refine it with AI, break it into phases, and
implement phase by phase with clean context boundaries.
| Command | Step | What it does |
|---|
/spec-draft | 1 — V0 | Interview you and write a rough, tool-agnostic spec: what the product does and how users interact with it. |
/spec-refine | 2 — V1 | Critique the draft, fill gaps, and map each feature to concrete stack tools using the references. |
/spec-phases | 3 — V2 | Break the spec into sequential, self-contained phases with a phase index. |
/spec-plan | 4 | Generate high-level plan files for all phases (scope + status header each), so you have a complete set to work from. |
/spec-implement | 5 | Promote a phase to detailed, implement it, then update the docs so the spec stays the source of truth. |
Step 5 is iterative — run it once per phase in a fresh session. A stale spec is
worse than no spec; it actively misleads future sessions, so updating docs after
implementation is part of the step, not an afterthought.
Audit secrets: /spec-secrets
Secrets leak to the browser in three common ways — a secret mis-prefixed as
NEXT_PUBLIC_, a server-only var read inside a "use client" component, or a value
hardcoded in source. /spec-secrets catches all three.
It's built on one rule: a local script is the only thing that ever touches secret
values; Claude only ever sees variable names and pass/fail verdicts. The command
is locked to a single deterministic script — no Read, no cat — so secret values
never enter the model's context. The script reads .env and the built bundle, and
prints a redacted report (names, verdicts, and file:line on a leak). Claude's job is
to explain each finding and the fix. Run /spec-secrets build to include the
definitive .next/static bundle scan. Same checks wire into the pre-commit hook and CI.
The reference (the vibe-spec skill)
The skill carries 21 stack references that Claude loads on demand — only the file
relevant to the task, keeping context lean. The commands consult them automatically;
you can also just ask a stack question and the skill pulls the right reference.
