Skip to content

Preset

Content Site

Sanity content, Clerk accounts and Supabase Postgres. No payments until you need them.

What this preset installs

  • 6

    Agents

  • 22

    Skills

  • 22

    Rules

  • 6

    Hooks

  • 47

    Solution docs

  • 2

    MCP servers

Counted from the manifests for this exact selection. Every agent reads the same AGENTS.md. Guard hooks run in Claude Code, Codex, Cursor, GitHub Copilot, Antigravity, Gemini CLI and Windsurf.

Why this one

Who it is for

For a marketing site, docs site or publication that may grow into a product. Sanity holds the content, with the Studio at /studio, draft previews and webhook revalidation. The landing page, /terms, /privacy and /llms.txt all read one file, src/lib/site.ts. Clerk handles accounts, styled to your design in light and dark, and signed-in readers get a dashboard and settings. Supabase Postgres is ready for app data. Resend sends mail and PostHog tracks what readers do.

No payments battery, on purpose. When you are ready, regenerate with one selected and diff the result.

Path-scoped rules cover the Sanity layer, components (design tokens only) and analytics. Agents, skills and guard hooks come installed. SETUP.md walks through the Sanity, Clerk and Supabase keys in order.

Highlights

  • Sanity Studio at /studio, typed GROQ queries, draft previews and webhook revalidation
  • A landing page, /terms, /privacy and /llms.txt, all written from one src/lib/site.ts
  • Clerk sign-in and sign-up in your design's colours, plus a signed-in dashboard and settings
  • Supabase Postgres with a Clerk webhook that syncs users into your tables
  • PostHog events with naming and identify rules, plus /add-event and /ask-product skills
  • No payments and no admin panel: a smaller repo you can regenerate later

The exact selection

Stack
Next.js on Vercel
Package manager
bun
Design system
Paper
Mode
solo
AI tools
Claude Code, Codex, Cursor, GitHub Copilot, Antigravity, Gemini CLI, OpenCode, JetBrains AI, Windsurf, Kiro
Admin panel
not included
AI bundle
off

Resolver

What the resolver added for you

Nothing is added silently. The picker prints these same lines as you toggle options.

  • auto-addedDrizzle ORM added: Supabase needs orm.
  • recommendedSupabase recommends Supabase Auth.
  • recommendedSupabase recommends Supabase Storage.
  • recommendedPostHog recommends errors.

The output

Read every file before you download it

The real generated repo for Content Site: 521 files, content hash aad26fcf4b63. The same selection always produces the same bytes.

  • .agents/61 files
    • agents/6 files
      • designer.md
      • documentarian.md
      • pr-reviewer.md
      • product-analyst.md
      • security-auditor.md
      • system-manager.md
    • hooks/9 files
      • README.md
      • auto-lint.ts
      • block-destructive.ts
      • enforce-doc-meta.ts
      • enforce-typecheck.ts
      • env-leak-detector-write.ts
      • env-leak-detector.ts
      • guards.json
      • run.mjs
    • rules/22 files
      • app-shell.md
      • authorise-on-the-server.md
      • clerk-ui-follows-the-design.md
      • code-style.md
      • deployment.md
      • drizzle-migrations.md
      • drizzle-schema.md
      • email-sending-discipline.md
      • event-naming.md
      • git.md
      • identify-timing.md
      • landing-and-legal.md
      • sanity-runtime.md
      • sanity-schema.md
      • security.md
      • server-truth-and-pii.md
      • supabase-db-access.md
      • supabase-migrations.md
      • testing.md
      • tokens-only.md
      • ui-kit.md
      • verify-the-webhook-first.md
    • skills/22 files
      • add-app-page/1 file
        • SKILL.md
      • add-clerk-role/1 file
        • SKILL.md
      • add-email-template/1 file
        • SKILL.md
      • add-event/1 file
        • SKILL.md
      • add-rls-policy/1 file
        • SKILL.md
      • add-sanity-type/1 file
        • SKILL.md
      • add-table/1 file
        • SKILL.md
      • ask-product/1 file
        • SKILL.md
      • deploy-to-vercel/1 file
        • SKILL.md
      • help/1 file
        • SKILL.md
      • landing-copy/1 file
        • SKILL.md
      • local-supabase/1 file
        • SKILL.md
      • migrate/1 file
        • SKILL.md
      • new-component/1 file
        • SKILL.md
      • preview-and-test-email/1 file
        • SKILL.md
      • preview-draft/1 file
        • SKILL.md
      • qa-feature/1 file
        • SKILL.md
      • security-audit/1 file
        • SKILL.md
      • setup/1 file
        • SKILL.md
      • sync-clerk-user/1 file
        • SKILL.md
      • verify/1 file
        • SKILL.md
      • write-spec/1 file
        • SKILL.md
    • hooks.json
    • mcp_config.json
  • .aiassistant/1 file
    • rules/1 file
      • agents-md.md
  • .claude/49 files
    • agents/6 files
      • designer.md
      • documentarian.md
      • pr-reviewer.md
      • product-analyst.md
      • security-auditor.md
      • system-manager.md
    • rules/20 files
      • agents-md.md
      • app-shell.md
      • authorise-on-the-server.md
      • clerk-ui-follows-the-design.md
      • deployment.md
      • drizzle-migrations.md
      • drizzle-schema.md
      • email-sending-discipline.md
      • event-naming.md
      • identify-timing.md
      • landing-and-legal.md
      • sanity-runtime.md
      • sanity-schema.md
      • server-truth-and-pii.md
      • supabase-db-access.md
      • supabase-migrations.md
      • testing.md
      • tokens-only.md
      • ui-kit.md
      • verify-the-webhook-first.md
    • skills/22 files
      • add-app-page/1 file
        • SKILL.md
      • add-clerk-role/1 file
        • SKILL.md
      • add-email-template/1 file
        • SKILL.md
      • add-event/1 file
        • SKILL.md
      • add-rls-policy/1 file
        • SKILL.md
      • add-sanity-type/1 file
        • SKILL.md
      • add-table/1 file
        • SKILL.md
      • ask-product/1 file
        • SKILL.md
      • deploy-to-vercel/1 file
        • SKILL.md
      • help/1 file
        • SKILL.md
      • landing-copy/1 file
        • SKILL.md
      • local-supabase/1 file
        • SKILL.md
      • migrate/1 file
        • SKILL.md
      • new-component/1 file
        • SKILL.md
      • preview-and-test-email/1 file
        • SKILL.md
      • preview-draft/1 file
        • SKILL.md
      • qa-feature/1 file
        • SKILL.md
      • security-audit/1 file
        • SKILL.md
      • setup/1 file
        • SKILL.md
      • sync-clerk-user/1 file
        • SKILL.md
      • verify/1 file
        • SKILL.md
      • write-spec/1 file
        • SKILL.md
    • settings.json
  • .codex/8 files
    • agents/6 files
      • designer.toml
      • documentarian.toml
      • pr-reviewer.toml
      • product-analyst.toml
      • security-auditor.toml
      • system-manager.toml
    • config.toml
    • hooks.json
  • .cursor/21 files
    • agents/6 files
      • designer.md
      • documentarian.md
      • pr-reviewer.md
      • product-analyst.md
      • security-auditor.md
      • system-manager.md
    • rules/13 files
      • authorise-on-the-server.mdc
      • clerk-ui-follows-the-design.mdc
      • deployment.mdc
      • drizzle-migrations.mdc
      • email-sending-discipline.mdc
      • identify-timing.mdc
      • landing-and-legal.mdc
      • sanity-schema.mdc
      • server-truth-and-pii.mdc
      • testing.mdc
      • tokens-only.mdc
      • ui-kit.mdc
      • verify-the-webhook-first.mdc
    • hooks.json
    • mcp.json
  • .devin/1 file
    • hooks.v1.json
  • .gemini/7 files
    • agents/6 files
      • designer.md
      • documentarian.md
      • pr-reviewer.md
      • product-analyst.md
      • security-auditor.md
      • system-manager.md
    • settings.json
  • .github/8 files
    • agents/6 files
      • designer.agent.md
      • documentarian.agent.md
      • pr-reviewer.agent.md
      • product-analyst.agent.md
      • security-auditor.agent.md
      • system-manager.agent.md
    • copilot/1 file
      • settings.json
    • hooks/1 file
      • agentic-guards.json
  • .junie/1 file
    • mcp/1 file
      • mcp.json
  • .kiro/36 files
    • settings/1 file
      • mcp.json
    • skills/22 files
      • add-app-page/1 file
        • SKILL.md
      • add-clerk-role/1 file
        • SKILL.md
      • add-email-template/1 file
        • SKILL.md
      • add-event/1 file
        • SKILL.md
      • add-rls-policy/1 file
        • SKILL.md
      • add-sanity-type/1 file
        • SKILL.md
      • add-table/1 file
        • SKILL.md
      • ask-product/1 file
        • SKILL.md
      • deploy-to-vercel/1 file
        • SKILL.md
      • help/1 file
        • SKILL.md
      • landing-copy/1 file
        • SKILL.md
      • local-supabase/1 file
        • SKILL.md
      • migrate/1 file
        • SKILL.md
      • new-component/1 file
        • SKILL.md
      • preview-and-test-email/1 file
        • SKILL.md
      • preview-draft/1 file
        • SKILL.md
      • qa-feature/1 file
        • SKILL.md
      • security-audit/1 file
        • SKILL.md
      • setup/1 file
        • SKILL.md
      • sync-clerk-user/1 file
        • SKILL.md
      • verify/1 file
        • SKILL.md
      • write-spec/1 file
        • SKILL.md
    • steering/13 files
      • authorise-on-the-server.md
      • clerk-ui-follows-the-design.md
      • deployment.md
      • drizzle-migrations.md
      • email-sending-discipline.md
      • identify-timing.md
      • landing-and-legal.md
      • sanity-schema.md
      • server-truth-and-pii.md
      • testing.md
      • tokens-only.md
      • ui-kit.md
      • verify-the-webhook-first.md
  • .opencode/6 files
    • agents/6 files
      • designer.md
      • documentarian.md
      • pr-reviewer.md
      • product-analyst.md
      • security-auditor.md
      • system-manager.md
  • .vscode/2 files
    • extensions.json
    • settings.json
  • docs/50 files
    • plans/2 files
      • README.md
      • TEMPLATE.md
    • solutions/48 files
      • blog-sanity/5 files
        • draft-mode-and-the-app-router-cache.md
        • groq-projections-that-avoid-over-fetching.md
        • image-urls-and-lqip.md
        • modelling-references-without-n-plus-one.md
        • webhook-revalidation-vs-time-based.md
      • clerk/7 files
        • clerk-impersonation-and-the-act-claim.md
        • protecting-handlers-vs-pages.md
        • roles-publicmetadata-vs-local-table.md
        • styling-clerk-with-css-variables.md
        • testing-clerk-webhooks-locally.md
        • the-matcher-that-ate-your-static-assets.md
        • webhook-idempotency-and-ordering.md
      • drizzle/5 files
        • adding-a-column-with-a-backfill.md
        • generate-vs-push.md
        • relations-vs-joins.md
        • transactions-in-serverless.md
        • typing-partial-selects.md
      • nextjs-vercel/11 files
        • auth-checks-in-an-app-shell.md
        • compound-engineering-loop.md
        • env-vars-on-vercel-without-leaking-them.md
        • guard-hooks-and-how-to-extend-them.md
        • llms-txt-for-a-saas-site.md
        • privacy-policy-that-lists-your-real-vendors.md
        • regenerate-from-config-and-diff.md
        • rules-skills-agents-when-to-use-each.md
        • sample-testimonials-without-the-ftc-risk.md
        • sidebar-state-without-a-flash.md
        • writing-path-scoped-rules-agents-follow.md
      • paper/4 files
        • a-chart-palette-that-survives-dark-mode.md
        • class-and-system-dark-mode-that-both-work.md
        • pasting-shadcn-components-into-your-own-token-names.md
        • tailwind-v4-dark-mode-does-nothing.md
      • posthog/5 files
        • ad-blocker-reverse-proxy.md
        • event-naming-that-survives.md
        • feature-flags-without-flicker.md
        • identify-race-conditions.md
        • server-vs-client-events.md
      • resend/5 files
        • batching-and-rate-limits.md
        • bounces-complaints-and-webhooks.md
        • domain-verification-spf-dkim-dmarc.md
        • magic-link-deliverability.md
        • previewing-templates-locally.md
      • supabase/5 files
        • beyond-the-anon-key-on-the-server.md
        • direct-vs-pooler-connection-strings.md
        • generated-types-drift.md
        • local-dev-vs-supabase-branches.md
        • rls-with-an-orm-in-front.md
      • README.md
  • drizzle/1 file
    • AGENTS.md
  • sanity/12 files
    • lib/6 files
      • AGENTS.md
      • client.ts
      • fetch.ts
      • image.ts
      • queries.ts
      • types.ts
    • schemas/4 files
      • author.ts
      • block-content.ts
      • index.ts
      • post.ts
    • AGENTS.md
    • env.ts
  • scripts/8 files
    • email/2 files
      • render-samples.ts
      • send-test.ts
    • lib/1 file
      • env-file.ts
    • clerk-webhook.ts
    • setup-env.json
    • setup-env.ts
    • verify-hooks.ts
    • verify.ts
  • src/213 files
    • app/45 files
      • (app)/11 files
        • dashboard/1 file
          • page.tsx
        • settings/5 files
          • profile/1 file
            • page.tsx
          • security/1 file
            • page.tsx
          • layout.tsx
          • loading.tsx
          • page.tsx
        • AGENTS.md
        • error.tsx
        • layout.tsx
        • loading.tsx
        • not-found.tsx
      • (auth)/4 files
        • sign-in/1 file
          • [[...sign-in]]/1 file
            • page.tsx
        • sign-up/1 file
          • [[...sign-up]]/1 file
            • page.tsx
        • AGENTS.md
        • layout.tsx
      • (legal)/2 files
        • privacy/1 file
          • page.tsx
        • terms/1 file
          • page.tsx
      • (sanity)/3 files
        • blog/2 files
          • [slug]/1 file
            • page.tsx
          • page.tsx
        • AGENTS.md
      • api/10 files
        • draft-mode/3 files
          • disable/1 file
            • route.ts
          • enable/1 file
            • route.ts
          • AGENTS.md
        • health/1 file
          • route.ts
        • sanity/2 files
          • revalidate/1 file
            • route.ts
          • AGENTS.md
        • webhooks/4 files
          • clerk/2 files
            • AGENTS.md
            • route.ts
          • resend/2 files
            • AGENTS.md
            • route.ts
      • ingest/1 file
        • [...path]/1 file
          • route.ts
      • llms.txt/1 file
        • route.ts
      • studio/2 files
        • [[...tool]]/1 file
          • page.tsx
        • AGENTS.md
      • AGENTS.md
      • error.tsx
      • fonts.ts
      • global-error.tsx
      • globals.css
      • layout.tsx
      • loading.tsx
      • not-found.tsx
      • page.tsx
      • robots.ts
      • sitemap.ts
    • components/91 files
      • app/11 files
        • AGENTS.md
        • account-card.tsx
        • app-header.tsx
        • app-shell.tsx
        • app-sidebar.tsx
        • dashboard-card.tsx
        • empty-state.tsx
        • page-header.tsx
        • settings-nav.tsx
        • user-avatar.tsx
        • user-menu.tsx
      • auth/6 files
        • AGENTS.md
        • account-settings.tsx
        • clerk-root.tsx
        • clerk-user-profile.tsx
        • header-auth-actions.tsx
        • sign-out-button.tsx
      • dashboard/5 files
        • card-action.tsx
        • chart-area-interactive.tsx
        • data-table.tsx
        • data.json
        • section-cards.tsx
      • marketing/18 files
        • AGENTS.md
        • brand.tsx
        • cta-band.tsx
        • faq.tsx
        • feature-grid.tsx
        • hero.tsx
        • json-ld.tsx
        • legal-document.tsx
        • logo-cloud.tsx
        • product-preview.tsx
        • sample-badge.tsx
        • section-heading.tsx
        • showcase-visuals.tsx
        • showcase.tsx
        • smart-link.tsx
        • social-icons.tsx
        • steps.tsx
        • testimonials.tsx
      • sanity/4 files
        • AGENTS.md
        • draft-banner.tsx
        • portable-text.tsx
        • sanity-image.tsx
      • site/7 files
        • AGENTS.md
        • auth-frame.tsx
        • chrome.tsx
        • footer.tsx
        • header.tsx
        • mobile-nav.tsx
        • nav-link.tsx
      • theme/2 files
        • theme-provider.tsx
        • theme-toggle.tsx
      • ui/37 files
        • AGENTS.md
        • accordion.tsx
        • alert-dialog.tsx
        • alert.tsx
        • avatar.tsx
        • badge.tsx
        • breadcrumb.tsx
        • button.tsx
        • card.tsx
        • chart.tsx
        • checkbox.tsx
        • collapsible.tsx
        • dialog.tsx
        • drawer.tsx
        • dropdown-menu.tsx
        • field.tsx
        • input.tsx
        • kbd.tsx
        • label.tsx
        • pagination.tsx
        • popover.tsx
        • progress.tsx
        • radio-group.tsx
        • select.tsx
        • separator.tsx
        • sheet.tsx
        • sidebar.tsx
        • skeleton.tsx
        • spinner.tsx
        • switch.tsx
        • table.tsx
        • tabs.tsx
        • textarea.tsx
        • toaster.tsx
        • toggle-group.tsx
        • toggle.tsx
        • tooltip.tsx
      • AGENTS.md
    • db/18 files
      • AGENTS.md
      • README.md
      • audit.ts
      • clerk-schema.ts
      • client.ts
      • connection-url.ts
      • direct-url.ts
      • driver.ts
      • drizzle.ts
      • email-schema.ts
      • index.ts
      • load-env.ts
      • migrate.ts
      • schema.ts
      • supabase-browser.ts
      • tables.ts
      • url.ts
      • verify.ts
    • hooks/1 file
      • use-mobile.ts
    • lib/56 files
      • analytics/6 files
        • AGENTS.md
        • events.ts
        • identify.ts
        • posthog-client.ts
        • posthog-server.ts
        • provider.tsx
      • auth/14 files
        • AGENTS.md
        • appearance.ts
        • clerk-env.d.ts
        • origin.ts
        • proxy.ts
        • publishable-key.ts
        • redirect.test.ts
        • redirect.ts
        • roles.ts
        • session.ts
        • user-store.ts
        • user-sync.test.ts
        • user-sync.ts
        • webhook-idempotency.ts
      • billing/1 file
        • AGENTS.md
      • email/16 files
        • templates/6 files
          • magic-link.tsx
          • receipt.tsx
          • reset-password.tsx
          • theme.ts
          • verify-email.tsx
          • welcome.tsx
        • AGENTS.md
        • address.ts
        • index.ts
        • observability.ts
        • outbox.ts
        • resend.ts
        • retry.ts
        • store.ts
        • suppression.ts
        • tags.ts
      • AGENTS.md
      • app-shell.test.ts
      • app-shell.ts
      • client-ip.test.ts
      • client-ip.ts
      • cn.test.ts
      • cn.ts
      • cx.ts
      • design.ts
      • env.ts
      • llms.test.ts
      • llms.ts
      • nav.test.ts
      • nav.ts
      • routes.ts
      • site.test.ts
      • site.ts
      • validate.ts
      • verify.ts
    • AGENTS.md
    • proxy.ts
  • supabase/3 files
    • seed/1 file
      • 00_conventions.sql
    • AGENTS.md
    • config.toml
  • tests/13 files
    • e2e/7 files
      • app-shell.spec.ts
      • auth.spec.ts
      • auth.ts
      • fixtures.ts
      • landing.spec.ts
      • legal.spec.ts
      • users.ts
    • unit/4 files
      • email-outbox.test.ts
      • email.test.ts
      • env.test.ts
      • setup-env.test.ts
    • AGENTS.md
    • smoke.spec.ts
  • .env.example
  • .gitignore
  • .mcp.json
  • AGENTS.md
  • DESIGN.md
  • README.md
  • SETUP.md
  • agentic.config.json
  • biome.jsonc
  • components.json
  • drizzle.config.ts
  • next.config.ts
  • opencode.json
  • package.json
  • playwright.config.ts
  • postcss.config.mjs
  • sanity.cli.ts
  • sanity.config.ts
  • tsconfig.json
  • vitest.config.ts

The three files that do the work

AGENTS.mdmarkdown325 lines
# my-app

Generated by [Agentic Boilerplate](https://github.com/agentic-studio/agentic-boilerplate) from [Agentic Studio](https://theagentic.studio). Same `agentic.config.json`, same repo: regenerate and diff any time.

- **Stack:** Next.js on Vercel (`nextjs-vercel`)
- **Services:** Drizzle ORM (`drizzle`), Supabase (`supabase`), Clerk (`clerk`), Resend (`resend`), PostHog (`posthog`), Sanity blog (`blog-sanity`)
- **Design:** Paper (`paper`). Every UI change follows [DESIGN.md](DESIGN.md).
- **Package manager:** bun
- **Mode:** solo

## Start here

On a fresh clone, run the `setup` skill: `/setup` in most agents, `$setup` in Codex.
It reads [SETUP.md](SETUP.md), which lists every environment variable, where to get
it, and the order to set the services up.

```sh
bun install
bun run setup:env -- --check   # what .env.local still needs
bun run verify
bun run dev
```

## How this repo is set up for agents

This file is the instruction file every agent reads. It holds the rules for the whole repo.

- A folder with its own `AGENTS.md` adds the rules for the files under it. Before you edit a file, read every `AGENTS.md` from the repo root down to its folder. Most agents load them for you.
- `.agents/rules/`: all 22 rules in full, one file each.
- `.agents/skills/`: 22 skills, listed below.
- `.agents/agents/`: 6 subagents, listed below. Agents with their own folder get a copy: `.claude/agents/`, `.codex/agents/`, `.cursor/agents/`, `.github/agents/`, `.gemini/agents/`, `.opencode/agents/`.
- `.agents/hooks/`: 6 guard hooks. They block destructive commands and keep secrets out of the chat. Wired for Claude Code, Codex, Cursor, GitHub Copilot, Antigravity, Gemini CLI and Windsurf. `bun run verify:hooks` proves they still block.
- MCP servers: `posthog`, `supabase`. [SETUP.md](SETUP.md) says how to connect them in each agent.
- `docs/solutions/`: 47 solved problems. Read the relevant one before you re-solve anything.
- `docs/plans/`: one plan per unit of work.
- The `system-manager` subagent owns this agent setup: `AGENTS.md`, `.agents/` and each agent's own folder.

## Workflow

The Compound Engineering plugin adds the loop: `/ce-brainstorm`, `/ce-plan`, `/ce-work`, `/ce-code-review`, `/ce-compound`.
In Codex they start with `$`. [SETUP.md](SETUP.md) has the install line for each agent.

## Repo-wide rules

### Code style and file conventions

Source: `nextjs-vercel`

These are checkable statements. Before you finish a task, re-read the files you
touched and confirm each one.

#### Language and formatting

- TypeScript everywhere. `.js` files exist only in generated output and config
  that cannot be TS (`postcss.config.mjs`). Never add a new `.js` source file.
- Formatting is Biome's job, not yours. Two-space indent, double quotes,
  semicolons, trailing commas where Biome puts them. If you are unsure how
  something should be formatted, run `bun run lint` and accept the result.
- `strict` and `noUncheckedIndexedAccess` are on. An indexed read is
  `T | undefined`; narrow it, do not cast it away.
- `any` is never allowed in an exported signature. Inside a function body,
  prefer `unknown` plus a narrowing check. `as` casts need a comment saying why
  the compiler cannot see what you can.
- No `@ts-ignore`. `@ts-expect-error` is allowed only with a one-line reason on
  the same comment.

#### Toolchain majors

Examples online often target older majors. These are the ones installed here:

- **TypeScript 7** (the native `tsc`). It has no JavaScript API, so `next build`
  type-checks through the `tsc` CLI. Never add `baseUrl` to `tsconfig.json`:
  TS 7 rejects it, and `paths` entries are already relative to the file.
  `types` is `["node"]`, so a package that only adds globals must be listed
  there to be seen.
- **Zod 4**. Read failures from `error.issues` (`.errors` is gone). Custom
  messages use `{ error: "..." }`, not `message`, `required_error` or
  `errorMap`. Formats are top level: `z.email()`, `z.url()`, `z.uuid()`.
  `z.record()` takes a key and a value schema. For form errors use
  `z.flattenError(error)` or `z.treeifyError(error)`.
- **Vitest 5**. `vi.mock()` must sit at the top level of the file. Mock call
  history is cleared before every test.

#### Modules and exports

- Named exports only, except where a framework demands a default: Next.js
  `page.tsx`, `layout.tsx`, `route.ts` handlers, `error.tsx`, `global-error.tsx`,
  `not-found.tsx`, `loading.tsx`, `robots.ts`, `sitemap.ts`, and
  `next.config.ts`.
- Request interception lives in `src/proxy.ts` and exports a **named** `proxy`
  function, not a default. `middleware.ts` is the deprecated spelling of the same
  file and this repo does not generate one. A search result telling you to
  create it predates Next 16, and a `middleware.ts` next to `proxy.ts` fails the
  build ("Both middleware file and proxy file are detected").
- Import from the alias root: `@/lib/...`, `@/components/...`. Relative imports
  are for siblings inside the same feature folder only. Never `../../../`.
- One concern per file. If a file exports more than one unrelated public thing,
  split it.

#### Naming

- Files: `kebab-case.ts`. React components: `PascalCase` inside a
  `kebab-case.tsx` file.
- Functions and variables: `camelCase`. Types and interfaces: `PascalCase`, no
  `I` prefix. Constants that are true module-level constants: `SCREAMING_SNAKE`.
- Booleans read as predicates: `isLoading`, `hasSession`, `canPublish`.
- Async functions that fetch return the noun (`getUser`), functions that mutate
  use a verb that says so (`createUser`, `revokeSession`).

#### Server and client boundary

- Server Components are the default. Add `"use client"` only when the file
  needs state, effects, refs, or browser-only APIs, and put it as high in the
  tree as the interactivity actually requires, not on a whole page.
- Never import anything from `src/lib/**` that reads a non-`NEXT_PUBLIC_` env
  var into a `"use client"` file. That is how secrets reach the browser.
- Data fetching lives in Server Components or Route Handlers. A client
  component receives data as props or through a documented client SDK.

#### Errors

- Throw `Error` subclasses with a message a human can act on. No bare strings.
- Route Handlers return a typed JSON body and a correct status code. Never leak
  a stack trace, a SQL string, or a provider error object to the client.
- Do not swallow errors. An empty `catch {}` is a bug unless it has a comment
  explaining the exact condition being ignored.

#### Comments

- Comments explain *why*. If a comment restates the code, delete it.
- Match the comment density of the file you are editing.
- No commented-out code. Git remembers it.

### Git and change hygiene

Source: `nextjs-vercel`

#### Branches

- Never commit directly to `main`. Branch first:
  `feat/<short-slug>`, `fix/<short-slug>`, `chore/<short-slug>`,
  `docs/<short-slug>`.
- One branch per plan. If the work splits, the plan splits first.

#### Commits

- Conventional Commits: `type(scope): summary`. Types: `feat`, `fix`, `chore`,
  `docs`, `refactor`, `test`, `perf`, `build`.
- The summary says what changed and why it matters, in the imperative, under 72
  characters. `fix(billing): reject webhooks with a stale timestamp`, not
  `fix stuff`.
- A commit is one coherent change. Formatting churn goes in its own commit so
  review stays readable.
- Never commit generated artefacts, `node_modules`, build output, `.env` files
  of any kind other than `.env.example`, or editor settings.
- Never commit while untracked files are present: either `git add` them or add
  them to `.gitignore`, then commit. In team mode the `enforce-git-tracked`
  hook refuses the commit until you do. Solo mode does not install that hook, so
  the check is on you. Do not work around either.

#### What you must never run

These are blocked by the `block-destructive` hook and must not be attempted
another way:

- `git push --force` on a shared branch. Use `--force-with-lease` on your own
  branch, and only after confirming nobody else is on it.
- `git reset --hard`: it destroys uncommitted work that is not yours to
  destroy. `git stash` instead.
- `git clean -fd`, which deletes untracked files you were never shown.
- Rewriting history that has been pushed and reviewed.

#### Pull requests

- The PR description states the problem, the approach, and how it was verified.
  Link the plan in `docs/plans/` and the preview URL.
- Keep PRs reviewable. Over roughly 400 changed lines, split or explain why not.
- Every review comment is either addressed in code or answered in a reply. None
  are silently closed.
- Squash-merge; the PR title becomes the commit message, so it follows the
  commit rules above.

#### Before you say a task is done

1. `bun run typecheck`, `bun run lint`, `bun run test` are green.
2. `git status` is clean apart from the intended change.
3. `git diff --staged` has been read end to end by you: no stray debug logs, no
   commented-out code, no secrets.
4. Anything you learned that would help next time is written to
   `docs/solutions/` as a solution doc.

### Security rules

Source: `nextjs-vercel`

The guard hooks in `.agents/hooks/` enforce a subset of this mechanically. The
rest is on you. Assume every one of these will be audited by the
`security-auditor` agent before a release.

#### Secrets

- Real secret values live in `.env.local` and in the hosting provider's
  environment settings. Nowhere else. Not in `.env.example`, not in a test, not
  in a comment, not in a commit message, not in a log line, not in a doc.
- `.env.example` lists every key with a placeholder that is obviously fake and a
  comment saying where to get the real one.
- Never `echo`, `cat`, `console.log`, or interpolate a secret into a shell
  command, a URL, an error message, or an analytics event.
- Only `NEXT_PUBLIC_`-prefixed variables may be read from client code. A
  non-prefixed variable read in a `"use client"` file is a leak even if the code
  path looks unreachable.
- Read server env vars through `env()` in `src/lib/env.ts`, inside the function
  that needs them. Never at module scope: `next build` runs without your
  secrets, so a module-scope read throws during the build. Do not sprinkle
  `process.env.X` through feature code.
- If a secret is ever exposed, rotate it first and clean history second. Never
  the other way round.

#### Authentication and authorisation

- Authorisation is checked on the server, on every request, in the handler that
  does the work. A hidden button is not access control.
- Never trust a user id, role, tenant id, or plan from the client. Derive them
  from the session on the server.
- Route Handlers and Server Actions each carry their own check. Middleware is a
  convenience layer, not the boundary.
- Sessions are httpOnly, `secure` in production, `sameSite=lax` or stricter.
- No custom crypto. Use the provider's primitives. No hand-rolled token
  formats, no `Math.random()` for anything security-relevant: `node:crypto`
  `randomUUID` or `randomBytes`.

#### Input and output

- Every external input is parsed with a Zod schema at the boundary: request
  bodies, query params, route params, webhook payloads, form data. Downstream
  code receives the parsed type, never the raw value. `src/lib/validate.ts` has
  `parseBody`, `parseQuery` and `parseForm`: each returns either the parsed data
  or the 400 response to return, so a handler cannot forget to reject.
- A validation error names the field and the problem, never the value. Echoing a
  rejected password, token or card number puts it in a log.
- Database access goes through the ORM's parameterised query builder. Raw SQL
  requires bound parameters: string interpolation into SQL is never acceptable.
- Never render unsanitised user HTML. `dangerouslySetInnerHTML` requires a
  sanitiser and a comment naming it.
- Redirects to a user-supplied URL must be validated against an allowlist of
  paths on this origin.

#### Response headers

- The security headers every route carries are in `next.config.ts`, not in
  `src/proxy.ts`: `headers()` applies to static assets and cached responses too,
  and the proxy does not run for those.
- A battery that needs a wider policy appends a rule at the `security-headers`
  slot **scoped to its own routes**. An entry matching `/:path*` silently undoes
  the block for the whole app.
- Adding a third-party script origin is a decision, not a formality. Say in the
  comment which battery needs it and why.

#### Webhooks

- Verify the signature against the raw request body before parsing it. If the
  framework has already parsed the body, you have already lost: read the raw
  body explicitly.
- Reject events older than a small window to blunt replay.
- Handlers are idempotent: record the provider's event id and no-op on a repeat.
- Return 2xx quickly. Do the slow part after acknowledging, or the provider will
  retry and you will process twice.

#### Dependencies and logging

- New dependencies need a reason. Prefer the platform, then the ORM/SDK already
  installed, then a new package.
- Pin ranges the lockfile can resolve reproducibly. Never install from a git URL
  or a tarball.
- Logs and error-tracking breadcrumbs carry no PII and no tokens. Log ids, not
  people.

## Scoped rules

- `drizzle/AGENTS.md` (1 rule)
- `sanity/AGENTS.md` (1 rule)
- `sanity/lib/AGENTS.md` (1 rule)
- `src/AGENTS.md` (2 rules)
- `src/app/AGENTS.md` (7 rules)
- `src/app/(app)/AGENTS.md` (1 rule)
- `src/app/(auth)/AGENTS.md` (1 rule)
- `src/app/(sanity)/AGENTS.md` (1 rule)
- `src/app/api/draft-mode/AGENTS.md` (1 rule)
- `src/app/api/sanity/AGENTS.md` (1 rule)
- `src/app/api/webhooks/clerk/AGENTS.md` (1 rule)
- `src/app/api/webhooks/resend/AGENTS.md` (1 rule)
- `src/app/studio/AGENTS.md` (1 rule)
- `src/components/AGENTS.md` (6 rules)
- `src/components/app/AGENTS.md` (1 rule)
- `src/components/auth/AGENTS.md` (1 rule)
- `src/components/marketing/AGENTS.md` (1 rule)
- `src/components/sanity/AGENTS.md` (1 rule)
- `src/components/site/AGENTS.md` (2 rules)
- `src/components/ui/AGENTS.md` (1 rule)
- `src/db/AGENTS.md` (3 rules)
- `src/lib/AGENTS.md` (2 rules)
- `src/lib/analytics/AGENTS.md` (3 rules)
- `src/lib/auth/AGENTS.md` (4 rules)
- `src/lib/billing/AGENTS.md` (1 rule)
- `src/lib/email/AGENTS.md` (1 rule)
- `supabase/AGENTS.md` (1 rule)
- `tests/AGENTS.md` (1 rule)

These also cover files at the repo root. Read one before you edit a file it names:

- `.agents/rules/deployment.md`: Deployment rules (`next.config.ts`, `vercel.json`, `package.json`, `src/proxy.ts`, `src/app/**/route.ts`, `.env.example`)
- `.agents/rules/drizzle-migrations.md`: Every schema change ships with its generated migration (`src/db/**`, `drizzle/**`, `drizzle.config.ts`)
- `.agents/rules/sanity-schema.md`: The schema is code, and every GROQ query lives in one file (`sanity/**`, `sanity.config.ts`)

## Skills

Run one by name (`/name` in most agents, `$name` in Codex), or let the agent pick one
from its description:
`add-app-page`, `add-clerk-role`, `add-email-template`, `add-event`, `add-rls-policy`, `add-sanity-type`, `add-table`, `ask-product`, `deploy-to-vercel`, `help`, `landing-copy`, `local-supabase`, `migrate`, `new-component`, `preview-and-test-email`, `preview-draft`, `qa-feature`, `security-audit`, `setup`, `sync-clerk-user`, `verify`, `write-spec`

## Subagents

Hand a task to one by name. What each one is for, and its prompt, is in
`.agents/agents/<name>.md`:
`designer`, `documentarian`, `pr-reviewer`, `product-analyst`, `security-auditor`, `system-manager`
src/lib/auth/AGENTS.mdmarkdown142 lines
# src/lib/auth

Rules for files under `src/lib/auth`. The root `AGENTS.md` and every
`AGENTS.md` between it and this folder apply here too.

## Authorise from the session, never from the client user object

Applies to: `src/app/**`, `src/components/**`, `src/lib/auth/**`
Source: `clerk`

### The client user object is display data

`useUser()`, `useAuth()`, `useOrganization()` and the `<Show>` component
(`<Show when="signed-in">`, `<Show when={{ role: "admin" }}>`; Clerk Core 3
replaced `<SignedIn>`, `<SignedOut>` and `<Protect>` with it) exist to render the
right UI. They read state the browser
holds, which the browser can edit. They decide what is *shown*. They never
decide what is *allowed*.

```tsx
// no — this is a visual hint being used as a control
const { user } = useUser();
if (user?.publicMetadata.role === "admin") {
  await fetch("/api/refunds", { method: "POST", body });
}
```

The route handler behind that call is what an attacker invokes, with curl,
without ever loading your page. It authorises itself:

```ts
const user = await requireApiRole("admin");   // from @/lib/auth/session
```

Hiding the button remains worth doing. It is the second step, not the only one.

### `unsafeMetadata` is never an input to a decision

Clerk gives you three metadata buckets:

| Bucket | Written by | Trust |
|---|---|---|
| `publicMetadata` | your backend only | authorisation input |
| `privateMetadata` | your backend only, never sent to the browser | authorisation input |
| `unsafeMetadata` | **the signed-in user, from the browser** | never |

`unsafeMetadata` is named that way for a reason: it is a scratchpad for user
preferences. Reading a role, an entitlement, a plan or a feature flag from it is
a self-service privilege escalation.

### Read the role through one helper

Every role check in this repo goes through `src/lib/auth/session.ts`, which
reads the `metadata` session claim first and falls back to the Backend API only
when it is absent. Do not re-implement it:

- No `auth().sessionClaims?.metadata?.role === "admin"` inline in a page.
- No `clerkClient().users.getUser(id)` in a component to look up a role.
- No role strings outside `src/lib/auth/roles.ts`.

One helper means one place to fix when the claim shape changes, and one place a
security review has to read.

There are two ways in, and the difference is a network call:

| Helper | Answers | Cost |
|---|---|---|
| `getSessionClaims()` / `requireApiClaims()` | `id`, `role`, `orgId`, `impersonatedBy` | the token only |
| `getSessionUser()` / `requireUser()` / `requireRole()` | the whole `SessionUser`, including `email` and `name` | one Backend API call, cached per request |

Clerk's token does not carry the email address, so a helper that promises one
has to fetch it. Guards that only decide yes-or-no should take the cheap path;
anything that renders or emails the person takes the other. Both resolve the
role identically, so neither is more or less trustworthy than the other.

### Never take identity from the request

The user id comes from the session, never from the body, the query string or a
header:

```ts
// no
const { userId } = await request.json();
await deleteAccount(userId);

// yes
const { id } = await requireApiUser();
await deleteAccount(id);
```

When an action legitimately targets *another* user (an admin banning someone)
the target id may come from the request, but only after the actor has been
authorised for that action.

### `auth()` needs the proxy

`auth()` throws if `clerkMiddleware` did not run for the request. That is why
`clerkProxy` from `src/lib/auth/proxy.ts` is a step in `src/proxy.ts`, and why
the matcher there must cover every route that reads a session. A route that
"randomly" throws an auth error is almost always a route the matcher does not
reach.

The proxy is not the authorisation boundary either. It redirects signed-out
visitors early; the page, handler or action still checks the role. A page
under `src/app/(app)/` calls `requireUser(path)` itself: a layout does not
re-run on client navigation.

Before the Clerk keys are set, `clerkIsConfigured()` is false, the proxy skips
Clerk, and every helper answers "signed out". Keep that path working: never
call `auth()` or a Clerk hook without going through those helpers or
`clerkProviderMounted()`.

### Impersonated sessions change nothing on the account

An administrator can sign in as someone from the Clerk dashboard. The token's
`act` claim then names the administrator, and `SessionUser.impersonatedBy`
carries its `sub` (null otherwise, and null for an AI agent actor). While it is
set, the settings pages are read-only summaries. Any new action that changes a
password, an email, a sign-in method or a payment method checks
`impersonatedBy` on the server and refuses, and anything it does write names
both ids in the log.

Never render `<UserProfile />`, `<UserButton />` or `<OrganizationProfile />`
for an actor session: Clerk does not document hiding their forms for one. And never tell an
operator Clerk itself makes the session read-only. Clerk documents no such
lock, and the browser can call Clerk's Frontend API directly, so the app's
lock stops mistakes, not an admin who goes around it (see
`docs/solutions/clerk/clerk-impersonation-and-the-act-claim.md`).

### Server-only imports

`CLERK_SECRET_KEY` and everything that reads it stay on the server.
`src/lib/auth/session.ts` starts with `import "server-only"` so an accidental
import from a client component is a build error rather than a leaked key.

## More rules

Too long to copy here. Read each one before you edit a file it applies to.

- `.agents/rules/clerk-ui-follows-the-design.md`: Clerk's components wear the design's tokens and only render inside the provider (`src/components/auth/**`, `src/lib/auth/appearance.ts`, `src/app/(auth)/**`, `src/components/site/header.tsx`)
- `.agents/rules/email-sending-discipline.md`: Every email goes through sendEmail, from a verified domain, with a reply-to (`src/lib/email/**`, `src/app/api/webhooks/resend/**`, `src/lib/auth/**`, `src/lib/billing/**`)
- `.agents/rules/verify-the-webhook-first.md`: The Clerk webhook verifies its signature before anything else (`src/app/api/webhooks/clerk/**`, `src/lib/auth/user-sync.ts`, `src/lib/auth/user-store.ts`, `src/lib/auth/webhook-idempotency.ts`)
.agents/hooks/README.mdmarkdown97 lines
# Guard hooks

One copy of every guard lives here. Each agent's own hook config runs them
through `run.mjs`, which reads that agent's payload, runs the guard, and
answers in that agent's format. `guards.json` is the table it reads.

| Agent | Config |
|---|---|
| Claude Code | `.claude/settings.json` |
| Codex | `.codex/hooks.json` |
| Cursor | `.cursor/hooks.json` |
| GitHub Copilot | `.github/hooks/agentic-guards.json` |
| Antigravity | `.agents/hooks.json` |
| Gemini CLI | `.gemini/settings.json` |
| Windsurf | `.devin/hooks.v1.json` |

Notes:

- Not wired: OpenCode, JetBrains AI, Kiro. OpenCode runs hooks as
  plugins and its plugin API changed between v1 and v2. Junie reads hooks from user config
  only. Kiro does not document its tool names. The rules in `AGENTS.md` still apply there.
- Codex, Cursor and Gemini CLI run project hooks only in a folder you trust. Codex also asks you
  to review each hook once in `/hooks`.
- Outside Claude Code a rewrite becomes a block that names the command to run instead.
- Hiding a secret in command output works in Claude Code only. Everywhere else the check
  before the command is what stops it.
- A guard that fails to run lets the call through, with a warning. So does a repo with no
  dependencies installed yet.

Run `verify:hooks` to prove each guard still blocks what it claims to block.

## auto-lint

- Event: `PostToolUse`
- Tools: `Edit|Write|MultiEdit`
- Script: `.agents/hooks/auto-lint.ts`
- Claude Code runs: `bun "${CLAUDE_PROJECT_DIR:-.}/.agents/hooks/run.mjs" auto-lint --from claude`
- Contributed by: `nextjs-vercel`

Runs Biome on the file that was just edited, applies safe fixes, and reports anything it could not fix.

## block-destructive

- Event: `PreToolUse`
- Tools: `Bash`
- Script: `.agents/hooks/block-destructive.ts`
- Claude Code runs: `bun "${CLAUDE_PROJECT_DIR:-.}/.agents/hooks/run.mjs" block-destructive --from claude`
- Contributed by: `nextjs-vercel`

Blocks irreversible shell commands: recursive force deletes, DROP and TRUNCATE sent to a database, force pushes, git reset --hard, git clean, dd, and truncating redirects onto tracked files.

## enforce-doc-meta

- Event: `PostToolUse`
- Tools: `Edit|Write|MultiEdit`
- Script: `.agents/hooks/enforce-doc-meta.ts`
- Claude Code runs: `bun "${CLAUDE_PROJECT_DIR:-.}/.agents/hooks/run.mjs" enforce-doc-meta --from claude`
- Contributed by: `nextjs-vercel`

Checks that files written under docs/solutions/ and docs/plans/ carry the frontmatter those directories depend on, and reports exactly what is missing.

## enforce-typecheck

- Event: `PreToolUse`
- Tools: `Bash`
- Script: `.agents/hooks/enforce-typecheck.ts`
- Claude Code runs: `bun "${CLAUDE_PROJECT_DIR:-.}/.agents/hooks/run.mjs" enforce-typecheck --from claude`
- Contributed by: `nextjs-vercel`

Rewrites a bare tsc, however it is launched, into the project's typecheck script before it runs. Outside Claude Code it blocks the call and names that script instead.

## env-leak-detector

- Event: `PreToolUse`
- Tools: `Bash|Read|Grep`
- Script: `.agents/hooks/env-leak-detector.ts`
- Claude Code runs: `bun "${CLAUDE_PROJECT_DIR:-.}/.agents/hooks/run.mjs" env-leak-detector --from claude`
- Codex: runs on `Bash` only.
- Contributed by: `nextjs-vercel`

Blocks tool calls that would print, transmit or commit a secret: literal credential shapes, reads of local .env files by any command or by the Read and Grep tools, echo of secret variables, environment dumps, and live values from your .env files.

## env-leak-detector-write

- Event: `PostToolUse`
- Tools: `Edit|Write|MultiEdit|Bash|Read|Grep`
- Script: `.agents/hooks/env-leak-detector-write.ts`
- Claude Code runs: `bun "${CLAUDE_PROJECT_DIR:-.}/.agents/hooks/run.mjs" env-leak-detector-write --from claude`
- Codex: runs on `Edit`, `Write`, `MultiEdit` only.
- Cursor: runs on `Edit`, `Write`, `MultiEdit` only.
- GitHub Copilot: runs on `Edit`, `Write`, `MultiEdit` only.
- Antigravity: runs on `Edit`, `Write`, `MultiEdit` only.
- Gemini CLI: runs on `Edit`, `Write`, `MultiEdit` only.
- Windsurf: runs on `Edit`, `Write`, `MultiEdit` only.
- Contributed by: `nextjs-vercel`

The second half of env-leak-detector: redacts live secret values from command, read and search output before the agent sees them (Claude Code only), and flags secrets written into files, private env vars read in client components, and secrets passed to log calls.

After you unzip

cd my-app
bun install
# then, in your AI agent ($setup in Codex):
/setup

The agentic layer

Everything an agent reads on its first run

Written once, then compiled for every agent. Every repo ships AGENTS.md and .agents/: rules, skills, subagents and guard hooks. Each agent you pick also gets the files it needs in its own format. Each entry below names where it came from: a battery, the design or the base stack.

Which agents get their own files

Only what an agent can’t read from AGENTS.md and .agents/.

Claude Code
Skills, subagents, guard hooks and the plugin in .claude/, MCP in .mcp.json.
Codex
Guard hooks, subagents and MCP in .codex/.
Cursor
Guard hooks, subagents and MCP in .cursor/.
GitHub Copilot
Guard hooks, custom agents and the plugin in .github/, MCP in .mcp.json.
Antigravity
Guard hooks and MCP in .agents/.
Gemini CLI
Reads AGENTS.md, guard hooks, subagents and MCP in .gemini/.
OpenCode
Subagents in .opencode/, MCP in opencode.json. No guard hooks.
JetBrains AI
Junie MCP in .junie/, an AI Assistant rule that points at AGENTS.md. No guard hooks.
Windsurf
Guard hooks in .devin/ for Devin Local (Windsurf and the Devin CLI), MCP in .mcp.json.
Kiro
Skills and MCP in .kiro/ (Kiro reads no .agents/skills). No guard hooks.

No files needed: Amp, Factory Droid, Warp, Cline, Kilo Code, Zed, Goose, Augment Code, Qwen Code, Crush and Jules. They read AGENTS.md as it is.

Agents (6)

Subagents in .agents/agents/, each with its own prompt. An agent with a subagent folder of its own gets a copy there, with the tools it may use.

  • designer

    Owns the Paper design system and its shadcn bridge. The only agent allowed to introduce a new visual pattern or a new token. Refuses to ship a raw colour or a single-mode change.

    tools: Read, Grep, Glob, Edit, Write

    Paper
  • documentarian

    Keeps README, AGENTS.md, DESIGN.md, SETUP.md and docs/solutions/ true to the code. Writes solution docs from work that just landed.

    tools: Read, Grep, Glob, Edit, Write, Bash

    Next.js on Vercel
  • pr-reviewer

    Reviews a diff against this repo's rules before it becomes a PR. Convention-aware, blocking on correctness and security, advisory on taste.

    tools: Read, Grep, Glob, Bash

    Next.js on Vercel
  • product-analyst

    Read-only product analyst. Answers questions about user behaviour from the event catalogue and the PostHog project, and says plainly when the instrumentation cannot answer them.

    tools: Read, Grep, Glob, mcp__posthog

    PostHog
  • security-auditor

    Audits the repo or a diff for leaked secrets, broken auth boundaries, injection, unsafe dependencies and unsafe deploy configuration.

    tools: Read, Grep, Glob, Bash

    Next.js on Vercel
Show all 6
  • system-manager

    Maintains the agent layer itself: AGENTS.md, .agents/ (rules, skills, agents, hooks) and each agent's own folder. Adds a rule when a correction repeats.

    tools: Read, Grep, Glob, Edit, Write, Bash

    Next.js on Vercel

Skills (23)

Skills in .agents/skills/, the folder most agents read: the repeatable jobs for this selection. Run one as /name, or $name in Codex.

  • /add-app-page

    Add a page to the signed-in app (sidebar entry, session check, loading state), or a new tab under /settings.

    .agents/skills/add-app-page/SKILL.md

    Next.js on Vercel
  • /add-clerk-role

    Add a role to the Clerk-backed role vocabulary, wire it into the session claim, gate a route with it, and assign it safely.

    .agents/skills/add-clerk-role/SKILL.md

    Clerk
  • /add-email-template

    Add a React Email template, preview it, wire it into a send, and check it renders and lands in a real inbox.

    .agents/skills/add-email-template/SKILL.md

    Resend
  • /add-event

    Add a product event end to end: catalogue entry, the question it answers, the capture call on the correct side of the network, and a check that it arrives.

    .agents/skills/add-event/SKILL.md

    PostHog
  • /add-rls-policy

    Add or fix row level security policies on a Supabase table, with a migration, a policy test and regenerated types.

    .agents/skills/add-rls-policy/SKILL.md

    Supabase
Show all 23
  • /add-sanity-type

    Add or extend a Sanity document type end to end (schema, GROQ projection, result type, renderer and cache tags) so nothing renders blank.

    .agents/skills/add-sanity-type/SKILL.md

    Sanity blog
  • /add-table

    Add a table to the Drizzle schema, generate and apply its migration, and wire the typed queries for it.

    .agents/skills/add-table/SKILL.md

    Drizzle ORM
  • /ask-product

    Answer a question about user behaviour from this repo's event catalogue and the PostHog project, with the caveats that make the number usable.

    .agents/skills/ask-product/SKILL.md

    PostHog
  • /deploy-to-vercel

    Ship my-app to Vercel: local gates, environment variables per scope, preview verification, promotion and rollback.

    .agents/skills/deploy-to-vercel/SKILL.md

    Next.js on Vercel
  • /edit-pricing

    Add, change or remove a plan or a price (monthly, yearly or one-time lifetime) and wire it to the payment provider.

    .agents/skills/edit-pricing/SKILL.md

    Next.js on Vercel
  • /help

    Explain the agentic system in this repo (rules, skills, agents, hooks, solution docs and the CE loop) and where to go for help beyond it.

    .agents/skills/help/SKILL.md

    Next.js on Vercel
  • /landing-copy

    Rewrite the landing page, the metadata and the legal details for the real product from a short brief, by editing src/lib/site.ts only.

    .agents/skills/landing-copy/SKILL.md

    Next.js on Vercel
  • /local-supabase

    Boot, reset, inspect and troubleshoot the local Supabase stack, and pull schema down from a hosted project.

    .agents/skills/local-supabase/SKILL.md

    Supabase
  • /migrate

    Generate, review and apply Drizzle migrations safely, including backfills, destructive changes and the deploy step.

    .agents/skills/migrate/SKILL.md

    Drizzle ORM
  • /new-component

    Add a component to the Paper kit. Prefer pasting from shadcn/ui, fix the two bridge classes, keep it token-only and verify it in both light and dark.

    .agents/skills/new-component/SKILL.md

    Paper
  • /preview-and-test-email

    Diagnose an email problem (not sending, landing in spam, rendering wrong) in the order that finds the cause fastest.

    .agents/skills/preview-and-test-email/SKILL.md

    Resend
  • /preview-draft

    Set up or debug Sanity draft previews: the enable route, the secret, the banner, and why an editor is still seeing published content.

    .agents/skills/preview-draft/SKILL.md

    Sanity blog
  • /qa-feature

    Exercise a feature end to end (happy path, unhappy paths, auth boundaries, refresh and mobile) before anyone calls it done.

    .agents/skills/qa-feature/SKILL.md

    Next.js on Vercel
  • /security-audit

    Run the standing security pass through the security-auditor agent (secrets, auth boundaries, injection, dependencies and deploy config) and turn findings into fixes.

    .agents/skills/security-audit/SKILL.md

    Next.js on Vercel
  • /setup

    Set up this repo after download. Fills .env.local, connects the MCP servers, sets up the database and services, and makes the product yours. Shows a plan first and acts only after a yes. Safe to run again.

    .agents/skills/setup/SKILL.md

    Next.js on Vercel
  • /sync-clerk-user

    Extend, backfill or re-verify the Clerk user mirror: the users table and ClerkSyncStore that this battery already ships.

    .agents/skills/sync-clerk-user/SKILL.md

    Clerk
  • /verify

    Prove the repo is actually configured: every required env var present, every configured service reachable, and the guard hooks still blocking what they claim to block.

    .agents/skills/verify/SKILL.md

    Next.js on Vercel
  • /write-spec

    Turn a loose request into a written spec (problem, scope, behaviour, acceptance criteria) that /ce-plan can consume without guessing.

    .agents/skills/write-spec/SKILL.md

    Next.js on Vercel

Rules (23)

Each rule is in .agents/rules/ and in the AGENTS.md of the folder it covers, so an agent reads it where it applies, not in one long file it skims.

  • app-shell

    Pages in the signed-in app

    src/app/(app)/** · src/components/app/** · src/components/ui/sidebar.tsx · src/lib/app-shell.ts · src/lib/nav.ts

    Next.js on Vercel
  • authorise-on-the-server

    Authorise from the session, never from the client user object

    src/app/** · src/components/** · src/lib/auth/**

    Clerk
  • billing-core

    Billing is one shared layer with one provider adapter

    src/lib/pricing.ts · src/lib/billing/** · src/app/pricing/** · src/app/(app)/billing/** · src/components/billing/**

    Next.js on Vercel
  • clerk-ui-follows-the-design

    Clerk's components wear the design's tokens and only render inside the provider

    src/components/auth/** · src/lib/auth/appearance.ts · src/app/(auth)/** · src/components/site/header.tsx

    Clerk
  • code-style

    Code style and file conventions

    repo-wide

    Next.js on Vercel
Show all 23
  • deployment

    Deployment rules

    next.config.ts · vercel.json · package.json · src/proxy.ts · src/app/**/route.ts · .env.example

    Next.js on Vercel
  • drizzle-migrations

    Every schema change ships with its generated migration

    src/db/** · drizzle/** · drizzle.config.ts

    Drizzle ORM
  • drizzle-schema

    Schema and query conventions for Drizzle

    src/db/**

    Drizzle ORM
  • email-sending-discipline

    Every email goes through sendEmail, from a verified domain, with a reply-to

    src/lib/email/** · src/app/api/webhooks/resend/** · src/lib/auth/** · src/lib/billing/**

    Resend
  • event-naming

    Events are declared in the catalogue, named object_verb, past tense

    src/lib/analytics/** · src/app/** · src/components/**

    PostHog
  • git

    Git and change hygiene

    repo-wide

    Next.js on Vercel
  • identify-timing

    Identify before the first event that matters, reset on sign-out

    src/lib/analytics/** · src/app/** · src/components/**

    PostHog
  • landing-and-legal

    Landing page, legal pages and llms.txt

    src/lib/site.ts · src/lib/llms.ts · src/app/page.tsx · src/app/(legal)/** · src/app/llms.txt/** · src/components/marketing/** · src/components/site/**

    Next.js on Vercel
  • sanity-runtime

    Read tokens stay on the server, Portable Text uses design tokens

    src/app/(sanity)/** · src/app/studio/** · src/app/api/draft-mode/** · src/app/api/sanity/** · src/components/sanity/** · sanity/lib/**

    Sanity blog
  • sanity-schema

    The schema is code, and every GROQ query lives in one file

    sanity/** · sanity.config.ts

    Sanity blog
  • security

    Security rules

    repo-wide

    Next.js on Vercel
  • server-truth-and-pii

    Server events for anything a client can lie about, and never PII in properties

    src/lib/analytics/** · src/app/** · src/components/**

    PostHog
  • supabase-db-access

    Row level security is on by default and the service role is a last resort

    src/db/**

    Supabase
  • supabase-migrations

    Schema changes go through supabase/migrations, never the dashboard

    supabase/**

    Supabase
  • testing

    Testing rules

    tests/** · src/**/*.test.ts · src/**/*.test.tsx

    Next.js on Vercel
  • tokens-only

    Paper: tokens only, and both modes every time

    src/components/** · src/app/**

    Paper
  • ui-kit

    Build UI from the component kit

    src/components/** · src/app/**

    Next.js on Vercel
  • verify-the-webhook-first

    The Clerk webhook verifies its signature before anything else

    src/app/api/webhooks/clerk/** · src/lib/auth/user-sync.ts · src/lib/auth/user-store.ts · src/lib/auth/webhook-idempotency.ts

    Clerk

Hooks (6)

Guard hooks in .agents/hooks/, wired for Claude Code, Codex, Cursor, GitHub Copilot, Antigravity, Gemini CLI and Windsurf. Run verify:hooks to prove each one still blocks what it claims to.

  • auto-lint

    Runs Biome on the file that was just edited, applies safe fixes, and reports anything it could not fix.

    PostToolUse · Edit|Write|MultiEdit

    Next.js on Vercel
  • block-destructive

    Blocks irreversible shell commands: recursive force deletes, DROP and TRUNCATE sent to a database, force pushes, git reset --hard, git clean, dd, and truncating redirects onto tracked files.

    PreToolUse · Bash

    Next.js on Vercel
  • enforce-doc-meta

    Checks that files written under docs/solutions/ and docs/plans/ carry the frontmatter those directories depend on, and reports exactly what is missing.

    PostToolUse · Edit|Write|MultiEdit

    Next.js on Vercel
  • enforce-typecheck

    Rewrites a bare tsc, however it is launched, into the project's typecheck script before it runs. Outside Claude Code it blocks the call and names that script instead.

    PreToolUse · Bash

    Next.js on Vercel
  • env-leak-detector

    Blocks tool calls that would print, transmit or commit a secret: literal credential shapes, reads of local .env files by any command or by the Read and Grep tools, echo of secret variables, environment dumps, and live values from your .env files.

    PreToolUse · Bash|Read|Grep

    Next.js on Vercel
Show all 6
  • env-leak-detector-write

    The second half of env-leak-detector: redacts live secret values from command, read and search output before the agent sees them (Claude Code only), and flags secrets written into files, private env vars read in client components, and secrets passed to log calls.

    PostToolUse · Edit|Write|MultiEdit|Bash|Read|Grep

    Next.js on Vercel

Institutional memory

51 solution docs, seeded on day one

They ship inside the repo under docs/solutions/. They are published here too, so you can read them first.

Show all 51

Clerk (7)

Drizzle ORM (5)

Next.js on Vercel (15)

Paper (4)

PostHog (5)

Resend (5)

Supabase (5)

Use Content Site

The builder opens with these 6 batteries picked. Change anything, then download the zip.