From vibe-spec
Spec-driven development workflow and full-stack reference for Next.js apps. Use when planning specs, choosing stack tools, breaking work into phases, or implementing phases.
How this skill is triggered — by the user, by Claude, or both
Slash command
/vibe-spec:vibe-specThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A reusable blueprint for building full-stack web apps with Next.js, Prisma, and
reference/00-workflow.mdreference/01-scaffolding.mdreference/02-nestjs.mdreference/03-docker.mdreference/04-database.mdreference/05-prisma.mdreference/06-dbt.mdreference/07-auth.mdreference/08-rbac.mdreference/09-validation.mdreference/10-testing.mdreference/11-ui.mdreference/12-s3.mdreference/13-push-notifications.mdreference/14-ci-cd.mdreference/15-pre-commit.mdreference/16-deployment.mdreference/17-scripts.mdreference/18-prerequisites.mdreference/19-secrets.mdA reusable blueprint for building full-stack web apps with Next.js, Prisma, and PostgreSQL using spec-driven development. Refined through real production projects — every tool, pattern, and convention is documented so you can pick what fits the project in front of you.
This catalogs a comprehensive stack, but most projects won't need all of it. A static site doesn't need Prisma, Docker, or dbt; a simple CRUD app doesn't need S3 or push notifications. Adding tools you don't need is complexity for no benefit. Load only the reference file(s) relevant to the task at hand.
| Project type | Recommended references |
|---|---|
| Static / marketing site | 00-workflow, 01-scaffolding, 11-ui, 15-pre-commit |
| Simple CRUD app | 00–01, 03–05, 07-auth, 08-rbac, 10-testing, 11-ui, 14–16, 19-secrets, 20-surface |
| API-only backend | 00–01, 03–05, 02-nestjs (optional), 07–10, 14–16, 19-secrets, 20-surface |
| Data-heavy app (pipelines, transforms) | All references |
/spec-* commands)The methodology: write a spec before touching code, refine it with AI, break it into phases, and implement phase by phase with clean context boundaries. Each step has a slash command:
/spec-draft — Write a rough V0 spec: what the product does and the exact
user workflows. No tooling decisions yet./spec-refine — Promote V0 → V1: fill gaps, then map each piece of
functionality to concrete tools using the references below./spec-phases — Promote V1 → V2: break the spec into sequential,
self-contained phases with a phase index./spec-plan — Generate a high-level plan file for every phase
(docs/plans/phase-*.md), each with a scope + status header, so you have a
complete set to work from./spec-implement — Implement one phase in a fresh session, then update the
docs so the spec always reflects reality. A stale spec is worse than no spec.Full detail (AGENTS.md hierarchy, tool permissions, phase conventions) lives in
reference/00-workflow.md.
Getting set up: before the workflow needs tools, /spec-setup installs only what
the project requires (guided, confirm each step), /spec-doctor reports what's
installed, and /spec-troubleshoot diagnoses common failures — all backed by
reference/18-prerequisites.md.
Load the file(s) that match the current task — not all of them.
| Reference | Skip if… / Use if… |
|---|---|
00-workflow | The spec-driven workflow, AGENTS.md hierarchy, tool permissions. Use when setting up methodology or AI context. |
01-scaffolding | Next.js 16 + TypeScript + pnpm + Tailwind v4 + ESLint. The base layer for any web app. |
02-nestjs | Decoupled high-performance API (Fastify). Escape hatch — only when you've measured a need. |
03-docker | Local Postgres 16 via docker-compose. Use when the app has a DB and you want an isolated local env. |
04-database | Dual-client (Prisma + raw pg Pool) and multi-schema layout. Use when you need ORM and raw SQL / JSONB. |
05-prisma | Prisma ORM schema conventions and migrations. Use for structured, relational data. |
06-dbt | raw → staging → marts transforms with uv. Use when you ingest raw data that needs transforming. |
07-auth | OAuth (Auth.js) or OTP + JWT (jose). Use when the app needs sign-in / sessions / protected routes. |
08-rbac | Roles + permissions, server- and client-side enforcement. Use when access differs by role. |
09-validation | Zod v4 runtime validation. Use when consuming external APIs, webhooks, or complex input. |
10-testing | Vitest with mocked Prisma. Testing is not optional — use always. |
11-ui | shadcn/ui components + theming via CSS variables. Use when building a web UI. |
12-s3 | Presigned uploads, lifecycle tags, CSP. Use for file / media uploads. |
13-push-notifications | Web Push + VAPID + service worker. Use for push notifications / PWA. |
14-ci-cd | GitHub Actions lint/test gates and scheduled pipelines. Use for any team repo. |
15-pre-commit | Native git hooks (no Husky). Use to enforce checks before commit. |
16-deployment | Vercel + Neon, security headers, env-var checklist. Use when shipping to production. |
17-scripts | TypeScript CLI tools (tsx) for pipelines, seeding, prod sync. Use for operational tooling. |
18-prerequisites | Required tools (Git, Node, pnpm, Docker, uv), how to detect them, and per-OS install methods. Used by /spec-setup, /spec-doctor, /spec-troubleshoot. |
19-secrets | Keep secrets out of the browser bundle and out of git. The trust boundary, the known-sensitive catalog, and the /spec-secrets audit. Use when the app has a .env. |
20-surface | Documentation governed like code — anchor doc claims to symbols; logic drift blocks the commit. Use on agent-heavy or fast-moving repos to stop AGENTS.md / hub prose silently going stale. |
For a new project: start with the spec (/spec-draft → /spec-refine →
/spec-phases), scaffold with 01-scaffolding using
official CLI init commands, then add only the references the quick-reference table
points to. Set up AGENTS.md and CI early, and anchor your first hubs with
20-surface so the docs agents read can't silently rot. Break
work into phases completable in 1–3
sessions, and update phase docs whenever implementation drifts from the plan.
The key principle: every tool here exists because a real project needed it. Your project has different needs — start minimal, add complexity only when a specific feature demands it.
npx claudepluginhub connorrmcd6/vibe-spec --plugin vibe-specGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.