vibe-spec

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.