Skip to content
/

vibe-stack (vibestackdev)

vibe-stack · vibestackdev/vibe-stack · ★ 6 · last commit 2026-05-25

Prevent AI coding assistants from generating insecure or broken Next.js 15 + Supabase code by injecting stack-specific constraint rules into every AI interaction.

Best whenAI training data is stale and wrong for fast-evolving frameworks; architecture rules that override AI priors are the only reliable fix.
Skip ifUsing getSession() on the server, Importing from deprecated @supabase/auth-helpers-nextjs
vs seeds
Primitive shape
No installable primitives
00

Summary

vibe-stack (vibestackdev) — Summary

vibe-stack is a Next.js 15 + Supabase boilerplate that ships 22 free .mdc architecture rule files (with 29 total available via paid tiers) designed to prevent AI coding assistants from generating insecure, deprecated, or broken code patterns. Each .mdc rule targets a specific failure mode: banning getSession() in favor of getUser() for JWT verification, enforcing async params handling in Next.js 15, requiring RLS on every Supabase table, and blocking deprecated @supabase/auth-helpers-nextjs imports. The boilerplate is a real working Next.js app (App Router, React 19, TypeScript strict, Supabase SSR, Stripe, Resend) with the rules as a complementary safety layer. A VIBE-CODING.md document describes a 3-stage agentic development loop, and AGENTS.md provides cross-tool instructions for Cursor/Claude/Copilot/Windsurf/Cline. The paid tiers ($29–$149) include more rules, MCP configs, architecture ADRs, and n8n automation workflows. vibe-stack differs from the openspec seed (structured spec workflow) in having no spec workflow at all — it is a rule-injection pack preventing AI hallucinations in a specific technology stack, closest to agent-os (Archetype 4) but scoped to Next.js+Supabase rather than general coding methodology.

01

Overview

vibe-stack (vibestackdev) — Overview

Origin

Created by vibestackdev, published on GitHub with MIT license. Actively maintained as of May 2026. The repository is a hybrid: a working Next.js 15 boilerplate (installable via git clone) + a rules pack sold via Gumroad at tiered pricing ($29/$69/$149).

Core Problem Statement

From the README:

"The problem: AI models generate code that compiles perfectly but ships critical vulnerabilities — getSession() instead of getUser(), synchronous params that crash in Next.js 15, missing RLS policies that expose your database. These bugs are invisible until production."

"The fix: Architecture rules that override the AI's training data. When a rule says 'NEVER use getSession()', the model is constrained to generate the secure pattern. Every time."

Philosophy

The framework operates on a single premise: AI training data is stale and wrong for rapidly-evolving frameworks. Rules files are the correction layer that overrides the AI's (incorrect) priors with current best practices.

Key opinions:

  1. Security rules are non-negotiable — phrased as "NEVER VIOLATE" constraints
  2. Specificity beats generality — each rule targets one concrete anti-pattern
  3. The AI is the execution engine, the rules are the guardrails — no spec planning, no phases
  4. Cross-tool compatibilityAGENTS.md explicitly targets Cursor, Claude, Copilot, Windsurf, and Cline

Agentic Loop Philosophy

VIBE-CODING.md describes a "3-stage agentic loop":

  • Stage 1: Foundation (context setup, rules loading)
  • Stage 2: Advanced Debugging (paywalled in free tier)
  • Stage 3: Agentic Power Tools (paywalled)

Stage 1 is available free; Stages 2-3 require paid tier.

Business Model

Freemium:

  • Free: 5/22 rules + working boilerplate
  • Tier 1 ($29): All 29 rules
  • Tier 2 ($69): Rules + MCP configs + Architecture ADRs + SQL templates
  • Tier 3 ($149): Everything + Stripe boilerplate + n8n workflows + priority support
02

Architecture

vibe-stack (vibestackdev) — Architecture

Distribution Type

template-bundle — both a working Next.js 15 boilerplate AND a Cursor .mdc rules pack. Paid tiers add more rules.

Install

git clone https://github.com/vibestackdev/vibe-stack.git
cd vibe-stack
npm install
cp .env.example .env.local
# Add Supabase URL + anon key to .env.local
npm run dev

Open in Cursor — rules activate automatically.

Directory Tree

vibe-stack/
├── .cursor/
│   └── rules/              # NOT in repo (would be in paid tier)
│                           # Free rules are in: rules/ directory
├── rules/                  # 22 free .mdc rule files
│   ├── supabase-auth-security.mdc
│   ├── nextjs15-params.mdc
│   ├── supabase-ssr-only.mdc
│   ├── server-vs-client-components.mdc
│   ├── supabase-rls.mdc
│   ├── ai-collaboration.mdc
│   ├── api-design.mdc
│   ├── caching-revalidation.mdc
│   ├── database-design.mdc
│   ├── env-management.mdc
│   ├── error-handling.mdc
│   ├── file-naming.mdc
│   ├── git-conventions.mdc
│   ├── hydration-safety.mdc
│   ├── performance.mdc
│   ├── project-context.mdc
│   ├── security.mdc
│   ├── server-actions.mdc
│   ├── shadcn-patterns.mdc
│   ├── stripe-payments.mdc
│   ├── testing.mdc
│   └── typescript-strict.mdc
├── src/
│   ├── app/               # Next.js App Router
│   ├── lib/               # Supabase, Stripe, email helpers
│   ├── types/             # Shared TypeScript types
│   └── middleware.ts
├── supabase/              # DB migrations, seed
├── n8n-workflows/         # 3 n8n automation templates (Tier 3 only)
├── docs/
│   ├── VIBE-CODING.md     # 3-stage agentic loop
│   ├── ARCHITECTURE.md    # 8 ADRs (Tier 2+)
│   └── MCP-SETUP.md       # MCP config guide (Tier 2+)
├── CLAUDE.md              # Claude Code instructions
├── AGENTS.md              # Cross-tool agent instructions
├── COMPATIBILITY_LOG.md   # Track AI tool compatibility notes
└── package.json

Required Runtime

  • Node.js (for Next.js development)
  • Supabase account/project
  • Cursor or another AI IDE (rules files are .mdc — Cursor native)

Target AI Tools

  • Cursor (primary — .mdc rules format)
  • Claude Code (CLAUDE.md)
  • GitHub Copilot (AGENTS.md)
  • Windsurf (AGENTS.md)
  • Cline (AGENTS.md)

Config Files

  • rules/*.mdc — Cursor architecture rules (22 free, 29 paid)
  • CLAUDE.md — Claude Code behavioral instructions
  • AGENTS.md — Cross-tool agent instructions
  • .env.example — Environment variable template
  • COMPATIBILITY_LOG.md — AI tool compatibility tracking log
03

Components

vibe-stack (vibestackdev) — Components

Free MDC Rules (22, in rules/)

Rule File What It Prevents / Enforces
supabase-auth-security.mdc Bans getSession(), enforces getUser() for JWT verification
nextjs15-params.mdc Prevents synchronous params access (breaking change in Next.js 15)
supabase-ssr-only.mdc Blocks deprecated @supabase/auth-helpers-nextjs imports
server-vs-client-components.mdc Prevents unnecessary 'use client' overuse
supabase-rls.mdc Enforces Row Level Security on every table
ai-collaboration.mdc AI collaboration patterns for this codebase
api-design.mdc API design patterns and validation rules
caching-revalidation.mdc Correct caching + revalidatePath() usage
database-design.mdc Schema patterns, UUID keys, RLS templates
env-management.mdc Secret classification + NEXT_PUBLIC_ safety
error-handling.mdc Error boundary and error response patterns
file-naming.mdc File naming conventions
git-conventions.mdc Git commit and branch conventions
hydration-safety.mdc Prevents hydration mismatches
performance.mdc Parallel fetching, N+1 prevention, dynamic imports
project-context.mdc Project-wide context (tech stack, patterns)
security.mdc OWASP Top 10 with rate limiting examples
server-actions.mdc Server Action patterns with Zod validation
shadcn-patterns.mdc shadcn/ui component usage patterns
stripe-payments.mdc Server-only Stripe, webhook signature verification
testing.mdc Testing patterns
typescript-strict.mdc Bans any, enforces Zod at every boundary

Paid-Only MDC Rules (7 additional in Tier 1)

Not available in public repo. Names partially listed in README:

  • middleware-auth.mdc
  • file-uploads.mdc
  • and 5 more covering components, API design, testing, shadcn/ui

Configuration Files

File Purpose
CLAUDE.md Claude Code instructions (security rules, patterns, commands)
AGENTS.md Cross-tool agent instructions for Cursor/Claude/Copilot/Windsurf/Cline
COMPATIBILITY_LOG.md AI tool compatibility tracking (what works, what breaks)

Paid-Only Components (Tier 2+)

  • .cursor/mcp.json — 4 pre-configured MCP servers (GitHub, Supabase, Filesystem, Browser)
  • docs/ARCHITECTURE.md — 8 Architecture Decision Records
  • SQL migration templates
  • docs/MCP-SETUP.md — MCP setup guide

Paid-Only Components (Tier 3)

  • src/app/api/webhooks/stripe/ — Stripe webhook handler
  • Resend email templates
  • n8n-workflows/ — 3 n8n automation workflows

Total Public Component Count

  • MDC rules: 22
  • Config/instruction files: 3 (CLAUDE.md, AGENTS.md, COMPATIBILITY_LOG.md)
  • Next.js app source files: multiple (full working boilerplate)
  • Scripts: 0 standalone
05

Prompts

vibe-stack (vibestackdev) — Prompts

Excerpt 1: supabase-auth-security.mdc (security constraint rule)

---
description: Supabase auth security — enforces getUser() over getSession() on the server
globs: ["**/app/**", "**/actions/**", "**/api/**", "**/lib/supabase/**", "**/middleware.*"]
alwaysApply: false
---

# Supabase Auth Security

## RULE 1: NEVER Use getSession() on the Server

SECURITY CRITICAL: `getSession()` reads the JWT from cookies without revalidating it.
A malicious user can craft a fake session token that `getSession()` will silently accept.
`getUser()` sends a request to Supabase Auth to revalidate the JWT — it is cryptographically secure.

✅ SECURE (always use on the server):
```typescript
const { data: { user }, error } = await supabase.auth.getUser()
if (error || !user) redirect('/login')

❌ INSECURE (never use in server code):

// VULNERABILITY: This does NOT verify the JWT with the auth server
const { data: { session } } = await supabase.auth.getSession()

RULE 2: Always Use @supabase/ssr, Never @supabase/auth-helpers

The @supabase/auth-helpers-nextjs package is DEPRECATED. Always import from @supabase/ssr for cookie-based sessions.


**Prompting technique**: YAML frontmatter declares glob-based activation scope. Rule body uses ALL-CAPS LABELS (`SECURITY CRITICAL`, `RULE 1`, `RULE 2`) as emphasis markers. ✅/❌ code examples provide concrete correct/incorrect patterns. The security rationale is explained ("reads the JWT without revalidating it") to help the AI understand *why*, not just *what*.

---

## Excerpt 2: nextjs15-params.mdc (breaking-change constraint rule)

```markdown
---
description: Critical Next.js 15 breaking changes regarding async params and searchParams
globs: ["**/app/**/page.tsx", "**/app/**/layout.tsx", "**/app/**/route.ts"]
alwaysApply: false
---

# Next.js 15 Async Params (BREAKING CHANGE)

CRITICAL: In Next.js 15+, `params` and `searchParams` are ASYNC Promises.
This is a breaking change from Next.js 14. The AI MUST await them.

✅ CORRECT (Next.js 15):
```tsx
type PageProps = { 
  params: Promise<{ slug: string }> 
  searchParams: Promise<{ [key: string]: string | string[] | undefined }> 
}

export default async function Page({ params, searchParams }: PageProps) {
  const { slug } = await params;
  const search = await searchParams;
}

❌ WRONG (outdated Next.js 14 pattern — will crash silently):

// DO NOT GENERATE THIS PATTERN
export default function Page({ params }: { params: { slug: string } }) {
  const { slug } = params; // BREAKS: params is a Promise in Next.js 15
}

**Prompting technique**: "BREAKING CHANGE" in the heading and "CRITICAL" in the body signal urgency to the AI. The `// DO NOT GENERATE THIS PATTERN` comment inside the wrong code example is a direct negative instruction embedded in the example itself — a double-layer prohibiton (rule text + inline comment).

---

## Excerpt 3: CLAUDE.md Security Rules Section

```markdown
## SECURITY RULES — NEVER VIOLATE

<security_critical>
1. NEVER use `supabase.auth.getSession()` in server-side code (Server Components, Server Actions, Route Handlers, middleware). It reads the JWT from cookies WITHOUT verifying it — a forged token passes silently. ALWAYS use `supabase.auth.getUser()` which makes a verification call to the Supabase auth server.

2. NEVER import from `@supabase/auth-helpers-nextjs` — it is DEPRECATED. Always use `@supabase/ssr` for both `createBrowserClient` (client) and `createServerClient` (server).

3. NEVER put auth enforcement logic in `middleware.ts`. Middleware runs on Edge Runtime and cannot securely verify Supabase JWTs. Middleware should ONLY call `updateSession()` to refresh tokens.
</security_critical>

Prompting technique: XML-tagged security block (<security_critical>) provides additional context signal for the AI. Numbered NEVER/ALWAYS dichotomies. Parenthetical explanation of why each rule exists. Caps NEVER/ALWAYS are stronger than "do not" — they signal non-negotiable constraints.

09

Uniqueness

vibe-stack (vibestackdev) — Uniqueness

Differs From Seeds

vibe-stack is closest to agent-os (Archetype 4 — markdown scaffold) in that it provides configuration files (rules, CLAUDE.md, AGENTS.md) that guide AI agent behavior rather than orchestrating agents. However, agent-os ships generic coding methodology instructions; vibe-stack ships stack-specific security and compatibility constraints targeting known failure modes in Next.js 15 + Supabase.

The fundamental architectural delta vs. all seeds: rules are stack-specific anti-hallucination guards, not methodology instructions. Where superpowers tells the AI "always write tests before code," vibe-stack tells the AI "never use getSession() because here is why it is a security vulnerability." The goal is output correctness (code that doesn't have CVEs) rather than process correctness (follow these development steps).

Compared to spec-kit (mirror commands+skills pattern), vibe-stack has no commands, no skills, no hooks — just static rule files injected by Cursor's glob-matching system.

Cross-Tool Portability Note

Unusually for this corpus, vibe-stack explicitly ships instructions for 5 different AI tools (Cursor, Claude Code, Copilot, Windsurf, Cline) via separate entry point files. Most frameworks in the corpus target one tool.

Business Model Differentiation

vibe-stack is the only framework in this batch with an explicit freemium commerce model (Gumroad). The free tier intentionally withholds 7/29 rules to drive paid conversion. This creates a documented "evaluation trap": users who clone the free repo can't replicate the full paid experience.

Positioning

  • Niche: Next.js 15 + Supabase developers who want AI to generate secure, correct code without manual review
  • Key differentiator: Rules embed security rationale (the AI understands why the constraint exists), not just constraints
  • Limitation: Stack-specific — entirely useless for non-Next.js/non-Supabase projects

Observable Failure Modes

  1. Rules don't load in non-Cursor tools.mdc is Cursor-native; CLAUDE.md/AGENTS.md provide weaker instruction coverage for other tools
  2. Rule staleness — if Supabase or Next.js releases break the rule assumptions, rules need manual update
  3. Incomplete free tier — the 7 withheld paid rules cover stripe-payments, file-uploads, middleware-auth — areas where AI hallucinations are equally dangerous
  4. No enforcement mechanism — rules are advisory (context injection), not enforced; AI can still ignore them
  5. Single-stack utility — no value for Django, Rails, or other stacks

Cross-References

  • COMPATIBILITY_LOG.md explicitly mentions multiple AI tools — this is the only framework in the batch that maintains a cross-tool compatibility log as a first-class artifact
04

Workflow

vibe-stack (vibestackdev) — Workflow

Developer Workflow (with vibe-stack)

Unlike spec-driven frameworks, vibe-stack has no explicit phases. Rules activate automatically when Cursor loads the project.

Step Action Artifact
1 Clone repo, set up Supabase + env Working local dev environment
2 Open in Cursor Rules auto-load from rules/*.mdc
3 Prompt the AI to build features AI-generated code constrained by rules
4 AI generates code Code with correct patterns (getUser(), async params, etc.)
5 Build and deploy Production-grade Next.js app

Vibe Coding 3-Stage Agentic Loop

Described in docs/VIBE-CODING.md:

Stage Name Available
1 Foundation (context setup, rules loading) Free
2 Advanced Debugging Paid (Tier 2+)
3 Agentic Power Tools Paid (Tier 2+)

Approval Gates

None defined in the framework. The rules fire automatically; no human approval gates.

How Rules Activate

Cursor loads .mdc files based on their globs frontmatter:

---
description: Critical Next.js 15 breaking changes
globs: ["**/app/**/page.tsx", "**/app/**/layout.tsx"]
alwaysApply: false
---

Rules with alwaysApply: false activate when the user opens a file matching the glob. Rules with alwaysApply: true are always in context.

Phase-to-Artifact Map

Phase Artifact
Initial setup Working Next.js 15 app + configured rules
Feature development Rule-constrained AI-generated code
Auth implementation Supabase SSR auth with getUser()
Payment implementation Stripe Checkout + webhook with signature verification
Deployment Production-ready Next.js app

Security Workflow

The framework treats security as workflow-embedded:

  1. Auth check before input validation before business logic (enforced by supabase-auth-security.mdc)
  2. RLS on every table (enforced by supabase-rls.mdc)
  3. No raw error messages to client (enforced by error-handling.mdc)
06

Memory Context

vibe-stack (vibestackdev) — Memory & Context

Memory Mechanism

No dedicated memory system. Context is provided through:

  1. .mdc rules files — automatically injected by Cursor based on file globs; these are the primary "memory" mechanism
  2. CLAUDE.md — read by Claude Code at session start; contains project context, patterns, and constraints
  3. AGENTS.md — read by any agent; provides project overview and architectural principles
  4. COMPATIBILITY_LOG.md — a human-maintained log of AI tool compatibility notes; serves as institutional memory about what works

Rule File Loading (Cursor)

Rules activate per-file based on glob patterns in frontmatter:

globs: ["**/app/**", "**/actions/**", "**/api/**"]
alwaysApply: false

Cursor injects matching rules into the AI's context window when editing files in those paths.

Project Context Rule

rules/project-context.mdc provides project-wide context injected into every relevant AI interaction. This acts as the persistent "memory" of the tech stack and key decisions.

Cross-Session Continuity

Via CLAUDE.md and AGENTS.md which are always present in the project root. The rules themselves don't change between sessions — they are static constraints.

State Files

None created by the framework dynamically. The COMPATIBILITY_LOG.md is manually updated.

Memory Persistence

File-based, project-scoped. Nothing stored outside the repository.

Compaction

Not applicable. Rules are static; no growing context to compact.

07

Orchestration

vibe-stack (vibestackdev) — Orchestration

Multi-Agent Pattern

None. vibe-stack is a single-agent rule-injection framework. No multi-agent orchestration is defined.

Execution Mode

interactive-loop — developer uses AI assistant in their IDE; rules fire automatically based on file context.

Isolation

None. All work happens in the working tree.

Multi-Model Routing

None defined. Cursor, Claude Code, Copilot etc. each use their own default model.

Prompt Chaining

None within the framework. Rules are stateless constraints — they don't chain to each other.

Orchestration Pattern

none — no coordination between components. Rules are independent.

Consensus

None.

How the "Orchestration" Works

Cursor's rule system handles activation:

  1. User opens a .tsx page file
  2. Cursor scans all rules/*.mdc for matching globs
  3. Matching rules are injected into the conversation context
  4. AI generates code with those constraints active

This is context injection, not agent orchestration.

Cross-Tool Strategy

The framework addresses cross-tool use through dedicated instruction files:

  • rules/*.mdc → Cursor
  • CLAUDE.md → Claude Code
  • AGENTS.md → All tools (Cursor, Claude, Copilot, Windsurf, Cline)

Each tool has its own entry point, same constraints.

08

Ui Cli Surface

vibe-stack (vibestackdev) — UI / CLI Surface

Dedicated CLI Binary

None for the framework itself. The boilerplate includes standard Next.js CLI:

npm run dev      # Start dev server (Next.js)
npm run build    # Production build
npm run lint     # ESLint
npx tsc --noEmit # Type check

Local Web Dashboard

The boilerplate ships a working Next.js web application:

  • Landing page
  • Login/Signup pages (Supabase SSR auth)
  • Protected dashboard
  • Error boundaries, loading states, custom 404

This is the product application, not a framework management UI.

IDE Integration

Cursor is the primary target:

  • rules/*.mdc files are Cursor's native rule format
  • Rules load automatically when opening matching files
  • No manual activation required

Claude Code:

  • CLAUDE.md provides project context

GitHub Copilot / Windsurf / Cline:

  • AGENTS.md provides cross-tool instructions

MCP Configuration (Paid Tier 2+)

The paid tier includes .cursor/mcp.json with 4 pre-configured MCP servers:

  • GitHub MCP
  • Supabase MCP
  • Filesystem MCP
  • Browser MCP

Observability

  • No dedicated agent log files
  • COMPATIBILITY_LOG.md — manually updated log of AI tool behavior notes
  • Standard Next.js build output for app issues

Commerce Surface

The paid content is distributed via Gumroad:

  • $29: All 29 rules
  • $69: Rules + MCP + ADRs
  • $149: Everything + Stripe boilerplate + n8n + support

The free tier (this repo) has 22/29 rules + the working app.

Related frameworks

same archetype · same primary tool · same memory type

claude-mem (thedotmack) ★ 78k

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…

pi (badlogic/earendil) ★ 55k

A minimal, hackable, multi-provider terminal coding agent that adapts to your workflows via npm-installable TypeScript Extensions…

Agent Skills (Addy Osmani) ★ 46k

Encodes senior-engineer software development lifecycle as 23 auto-routed skills and 7 slash commands for any AI coding agent.

wshobson/agents Plugin Marketplace ★ 36k

Single Markdown source for 83 domain-specialized plugins that auto-generates idiomatic artifacts for five AI coding harnesses.

TabbyML/Tabby ★ 34k

Self-hosted AI coding assistant server (alternative to GitHub Copilot) with admin dashboard, RAG-based completions, and multi-IDE…

Compound Engineering ★ 17k

Make each unit of engineering work compound into easier future work via brainstorm→plan→execute→review→learn cycles.