| name | vibe-spec |
| description | Spec-driven development workflow plus a production-tested full-stack reference (Next.js 16, Prisma, PostgreSQL, Auth.js/OTP, RBAC, dbt, Zod, Vitest, shadcn/ui, S3, Web Push, GitHub Actions, Vercel). Use when planning a web app spec, choosing stack tools for a feature, breaking work into phases, or implementing a phase — and as a lookup for any of these stack areas. Pulls in only the relevant reference file on demand. |
Vibe-Spec
A 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.
Only adopt what you need
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.
Quick reference: what do I need?
| 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 |
The workflow (use the /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.
Reference index
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. |
Putting it all together
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.
