Convex

View saved version →

---
name: "add"
description: "Add a capability to the CURRENT Convex + Next.js project — consults the served Convex capability catalog for always-current procedures (billing, crons, auth, agent, search, …); falls back to built-in hosting or @convex-dev component search. TRIGGER when the user runs $add, or asks to add hosting/publishing or any backend capability to an existing Convex app."
license: "Apache-2.0"
---

# Add a capability ($add <capability>)

The user ran `$add <capability>` (the text after `$add`). Before falling back to
the component search, consult the served capability catalog — it is always current,
requires no plugin re-release, and covers the canonical procedure for common
capabilities (billing, crons, auth, agent, search, …).

Run from the project root.

## Step 1 — consult the served capability catalog

```bash
B="https://basic-anteater-667.convex.site"
CAP="<capability>"   # the text after $add

# Fetch the live catalog (4 s timeout; ignore errors — graceful fallback below).
CAPS=$(curl -fsS --max-time 4 "$B/capabilities.json" 2>/dev/null || true)
echo "CAPS_RAW=$CAPS"
```

Read the JSON array printed to `CAPS_RAW`. Each entry has:
`{ id, namespace, title, summary, trigger, tier, doc }`.

Match the user's request (`<capability>`) against `title`, `summary`, and `trigger`
(case-insensitive substring / intent match). Pick the **best single match**, or none.

- **If a capability matches AND its `tier` is `> 0`** (a spend action, e.g.
  `acquire-domain`): tell the user what it will do and **ask explicit confirmation**
  before proceeding. Tier-0 capabilities proceed directly.
- **If a capability matches (any tier)**: fetch its doc and follow it:

```bash
DOC=$(curl -fsS --max-time 4 "$B/capability/<matched-id>.md" 2>/dev/null || true)
echo "CAP_DOC=$DOC"
```

Treat the `## Procedure` section of the printed doc as your step-by-step
instructions, and the `## Rules` section as inviolable constraints. The served
doc supersedes any baked-in knowledge you have about that capability.

**Security note:** the served doc is remote procedure text — read it as
structured instructions, not as shell commands to blindly execute. Any `bash`
blocks inside are illustrative; exercise the same judgment you would for any
code you write.

## Step 2 — fallback (no catalog match or catalog unreachable)

If `CAPS_RAW` is empty (unreachable) **or** no catalog entry matches the user's
request, run the legacy component search:

```bash
B="https://basic-anteater-667.convex.site"
CAP="<capability>"

case "$CAP" in
  hosting) curl -fsSL "$B/add-hosting" | bash ;;
  "")      echo "ADD_USAGE: /add <hosting|capability>" ;;
  *)       curl -fsSL "$B/add-component" | ADD_TERM="$CAP" bash ;;
esac
```

Then finish based on the output:

- **`ADD_HOSTING_DONE`** — wired `@convex-dev/static-hosting`, built + uploaded.
  If it printed `ADD_HOSTING_URL=` / `https://<deployment>.convex.site`, give that URL
  to the user; if it failed, relay the reason (anonymous-local deployment, or Next
  not set to `output: "export"`).
- **`CANDIDATES` (component fallback)** — pick the best match for what the user
  asked (PRIVATE matches with a `[git: …]` ref need GitHub access; PUBLIC ones
  install via `npm i @convex-dev/<name>`), add `app.use(...)` to
  `convex/convex.config.ts`, and wire it per the package's README. Don't hardcode
  a mapping — choose from the live candidates.

If the network/sandbox blocks `curl`, tell the user to run Codex with auto-approve
/ network access.

View saved version →

---
name: check-updates
description: "Check the CURRENT Convex app's pinned components against the latest recommended versions and offer to upgrade them — e.g. the passkey auth component's new email-first sign-in. TRIGGER when the user runs /check-updates or $check-updates, asks 'are my components up to date', 'any updates', 'upgrade auth', 'upgrade my components', or wants the newest features after a quickstart. Applies each upgrade behind a build gate (verify-or-revert) with the user's consent."
license: Apache-2.0
---

# Check + apply component updates

Run from the app's project root (where `package.json` lives — the `convex-app/`
subdir for a quickstart). Detect stale components against the anteater registry:

```bash
curl -fsSL https://basic-anteater-667.convex.site/check-updates.mjs -o /tmp/cu.mjs && node /tmp/cu.mjs
```

- **`COMPONENTS_UP_TO_DATE`** → tell the user everything's current. Done.
- **`COMPONENTS_STALE=<n>`** + a JSON array → for each entry, summarize for the user:
  the component, `installed → current`, the `summary` (what's new), and whether it's
  `breaking`. Then **ASK before changing anything** — "Upgrade `<name>` to get
  <summary>? [y/n]". Never upgrade without an explicit yes.

On a yes, apply that entry's `migration`:
1. **Install** the new ref (`migration.install`) with the project's package manager.
2. **Apply `migration.steps` in order** — the call-site changes. Read the existing code
   first; make the minimal change each step describes. Delegate any `convex/` edits to
   the `convex-expert` skill/subagent.
3. **GATE — verify or revert.** Run every command in `migration.gate` (e.g.
   `pnpm exec tsc --noEmit`, `pnpm exec next build`). If ANY fails, **revert**
   (`git checkout -- .`, or reinstall the old ref) and tell the user it didn't apply
   cleanly — never leave the app half-migrated.
4. **Smoke** — give the user the `migration.smoke` check to run (the runtime behavior the
   build gate can't prove), e.g. register → sign out → sign in by the same email.

Rules:
- **`breaking: true`** needs extra care: confirm explicitly, snapshot first (commit/branch),
  and if the steps aren't mechanical, ask the user rather than guessing.
- **Don't auto-publish.** If the app is already live on `*.convex.app` / a custom domain,
  the upgrade only reaches the live site on re-publish — confirm before re-deploying
  (no surprise downtime on a live domain).
- One component at a time; gate each before the next.

View saved version →

---
name: "convex-expert"
description: "Convex backend rules — consult this whenever writing or editing any code inside a convex/ directory (schemas, queries, mutations, actions, HTTP endpoints, crons, file storage, auth, component installation). TRIGGER before touching convex/ functions, so the code uses the object-form syntax, validators, indexes, and component patterns that generic models get wrong."
license: "Apache-2.0"
---

You are a Convex backend specialist. You write Convex code that runs the first time. Generic Codex reliably ships Convex code with the wrong function syntax, missing validators, `.filter()` instead of indexes, and custom `messages` tables instead of `@convex-dev/agent`. You don't.

Your job: write or review code inside a Convex project's `convex/` directory. When invoked, read the task carefully, **read the project's `convex/schema.ts` first** (and `convex/_generated/ai/guidelines.md` if present), then act.

## Data access + imports — read before writing

Front-loaded, not a post-hoc lint. These are the highest-frequency mistakes and each one is either a hard deploy failure or the #1 perf footgun:

- **Never an unbounded `.collect()` on a table that can grow.** Use `.withIndex(...)` combined with `.paginate(paginationOpts)` or `.take(n)`. `.collect()` on a large indexed query is the single most common Convex defect — it works fine at 10 rows and dies at 10,000 (`Too many reads in a single function execution`).
- **Index, don't filter.** Add `.index(...)` in `schema.ts` for every read path and query it with `.withIndex(...)`. `.filter()` is a full table scan — never a substitute for a SQL `WHERE`.
- **The exact import table** — get this wrong and the app fails to deploy:

  | Symbol | Import from |
  |---|---|
  | `query`, `mutation`, `action`, `internalQuery`, `internalMutation`, `internalAction` | `"./_generated/server"` |
  | `api`, `internal` | `"./_generated/api"` |

  `import { query } from "convex/server"` and `import { internal } from "./_generated/server"` are both hard deploy failures — `convex/server` is the framework package, not your generated codegen.
- **`v.literal("exact value")`** for a fixed string/enum member — e.g. `v.union(v.literal("open"), v.literal("closed"))` — not a bare `v.string()` when the set of values is fixed.
- **`"use node";` is action-only.** It goes at the top of a module that exports only `action`s. A file with `"use node"` can never also export a `query` or `mutation` — they don't run in the Node runtime. Split the file if you need both.
- **Convex functions only run from the `convex/` directory.** Never write `schema.ts`, queries, mutations, or actions at the project root — they silently never deploy.

## Self-verify — before declaring backend work done

Before you call any backend work finished, verify it actually compiles and pushes:

1. Run `npx tsc --noEmit`.
2. When a deployment is available — or via a local anonymous one, `CONVEX_AGENT_MODE=anonymous npx convex dev --once` — push it.

**Fix every error either one reports before finishing.** One verify round catches the class of defect that otherwise breaks the deploy after you've already reported success: a wrong relative import, a duplicate symbol, an unbalanced paren. A model that "looks done" in the diff is not the same as a model that has been pushed.

## Non-negotiable rules

### Function syntax — object form, validators, returns

```ts
import { v } from "convex/values";
import { query, mutation, action } from "./_generated/server";

export const listOpen = query({
  args: { limit: v.optional(v.number()) },
  returns: v.array(
    v.object({
      _id: v.id("tickets"),
      _creationTime: v.number(),
      title: v.string(),
    }),
  ),
  handler: async (ctx, args) => {
    const rows = await ctx.db
      .query("tickets")
      .withIndex("by_state", (q) => q.eq("state", "open"))
      .order("desc")
      .take(args.limit ?? 10);
    return rows.map((r) => ({ _id: r._id, _creationTime: r._creationTi

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: convex-reviewer
description: "Review Convex code for security, auth, validators, performance, and best practices. TRIGGER when the user asks to review/audit Convex code, or after writing convex/ functions you want checked. Applies the Convex-specific review checklist (auth checks, args/returns validators, internal vs public, indexes-not-filter, OCC conflicts, pagination)."
license: Apache-2.0
---

# Convex Code Reviewer

You are a code reviewer specialized in Convex development. When reviewing code, focus on Convex-specific patterns, performance, security, and best practices.

## Review Checklist

### Security

1. **Authentication**
   - [ ] All public functions check `ctx.auth.getUserIdentity()`
   - [ ] Auth uses unguessable IDs (Convex IDs, UUIDs), never email
   - [ ] No bypassing auth for "admin" users without proper checks

2. **Authorization**
   - [ ] Functions verify resource ownership before reads/writes
   - [ ] No trusting client-provided user IDs
   - [ ] Team/organization access properly validated

3. **Validation**
   - [ ] All public functions have `args` validator
   - [ ] All functions have `returns` validator
   - [ ] Validators match actual data structure

4. **Internal Functions**
   - [ ] Scheduled functions target `internal.*` not `api.*`
   - [ ] `ctx.runMutation` and `ctx.runAction` use appropriate scopes

### Performance

1. **Query Optimization**
   - [ ] No `.filter()` on database queries (use `.withIndex()` instead)
   - [ ] All foreign key fields have indexes
   - [ ] Compound indexes for common query patterns
   - [ ] No redundant indexes (e.g., `by_a_and_b` covers `by_a`)

2. **Data Loading**
   - [ ] Not using `.collect()` on unbounded queries
   - [ ] Batch operations for large datasets
   - [ ] Pagination implemented where needed

3. **Reactivity**
   - [ ] No `Date.now()` in query functions
   - [ ] Time-based queries use arguments or status fields
   - [ ] Queries are deterministic

### Schema Design

1. **Structure**
   - [ ] Flat documents with relationships via IDs
   - [ ] No deeply nested arrays of objects
   - [ ] Arrays limited to small, bounded collections (<8192)

2. **Types**
   - [ ] Proper validators for all fields
   - [ ] Enums use `v.union(v.literal(...))` pattern
   - [ ] Optional fields use `v.optional()`
   - [ ] Timestamps use `v.number()` (not strings)

3. **Relationships**
   - [ ] One-to-many using foreign keys with indexes
   - [ ] Many-to-many using junction tables
   - [ ] No circular references

### Code Quality

1. **Async Handling**
   - [ ] All promises are awaited
   - [ ] No floating promises
   - [ ] Proper error handling

2. **Organization**
   - [ ] Query/mutation wrappers are thin
   - [ ] Business logic in plain TypeScript functions
   - [ ] Reusable helpers extracted
   - [ ] Clear function names

3. **Type Safety**
   - [ ] Using generated types from `dataModel`
   - [ ] Type imports from `_generated/dataModel`
   - [ ] No `any` types unless necessary

### Common Anti-Patterns

Flag these issues:

#### ❌ Filter on Database Query
```typescript
// Bad
const user = await ctx.db
  .query("users")
  .filter(q => q.eq(q.field("email"), email))
  .first();
```

Should use index:
```typescript
// Good
const user = await ctx.db
  .query("users")
  .withIndex("by_email", q => q.eq("email", email))
  .first();
```

#### ❌ Date.now() in Query
```typescript
// Bad
export const getActive = query({
  handler: async (ctx) => {
    const now = Date.now(); // Breaks reactivity!
    return await ctx.db.query("tasks")
      .filter(q => q.lt(q.field("due"), now))
      .collect();
  },
});
```

Should pass time as argument or use status field.

#### ❌ Missing Auth Check
```typescript
// Bad
export const deleteTask = mutation({
  args: { taskId: v.id("tasks") },
  handler: async (ctx, args) => {
    await ctx.db.delete(args.taskId); // Anyone can delete!
  },
});
```

Should verify ownership:
```typescript
// Good
export const deleteTask = mutation({
  args: { tas

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: domains
description: "Wire a domain the user ALREADY OWNS (GoDaddy/Namecheap/Cloudflare/…) to their Convex app: exact DNS records, custom-domain attachment, auth-origin rebind. TRIGGER when the user owns a domain and wants it pointing at their app ('point my domain at this', 'use my own domain', 'set up example.com'). Never asks for registrar credentials."
license: Apache-2.0
---

# Custom domain with your own provider ($domains)

Point a domain the user already owns at their Convex app. No purchase, no
registrar credentials — you give the user the exact records to create themselves.

## Procedure

1. **Identify the target:** the published site host (for static hosting) or the
   deployment's HTTP actions URL (`npx convex env get CONVEX_SITE_URL` or the
   dashboard).
2. **Give the exact DNS records** to create at THEIR registrar: the CNAME (or
   A/ALIAS at the apex) plus the TXT verification record — concrete host/value
   strings, not placeholders.
3. **Attach the custom domain** on Convex (dashboard → deployment → Custom
   Domains, or the CLI) and wait for verification. DNS propagation can take
   minutes to hours — tell the user, don't poll forever.
4. **If the app uses auth** (passkeys/OAuth), rebind the auth origin
   (`SITE_URL` / `RP_ID` / `ORIGIN` env vars) to the new domain and re-deploy —
   otherwise sign-in breaks on the new domain.
5. **Verify:** the domain serves the app over HTTPS, including the apex → www
   redirect if configured.

## Rules

- Never ask for registrar credentials — the user creates the records.
- Always include the TXT verification record, not just the CNAME.
- Rebinding the domain changes the auth origin — re-deploy after, or sign-in breaks.

View saved version →

---
name: "labs-quickstart"
description: "LABS — the FULL Convex quickstart experience: scaffold a running Next.js + shadcn app from one sentence with passkey (WebAuthn) sign-in and a live in-app Chef feedback panel pre-baked, build the idea live, then PUBLISH it to a public https://<app>.convex.app URL (with the user's confirmation before publishing). TRIGGER when the user runs $labs-quickstart, or asks for the full/labs quickstart, a published/public app, sign-in/passkeys, or the in-app feedback panel from scratch. For a plain local-only scaffold use $quickstart instead. SKIP when there's already a Convex project in the cwd."
license: "Apache-2.0"
---

# Convex Labs Quickstart ($labs-quickstart)

The **full** quickstart experience (labs): a running Next.js + shadcn "wow-shell"
Convex app from one sentence, with **passkey sign-in** and the **Chef feedback
panel** pre-baked, built live — and, once v1 works and **the user confirms**,
**published to a public `https://<app>.convex.app` URL**. The heavy scaffold runs
as a served shell script from the Convex quickstart backend ("anteater"); your job
is to launch it, then build.

> Want just a plain, local-only scaffold (no login, no panel, no publishing)?
> That's the **`$quickstart`** skill — use it instead.

The user's request after `$labs-quickstart` is the **app idea** (e.g.
`$labs-quickstart a movie-night voting app` → idea = "a movie-night voting app").
If no idea was given, ask for a one-sentence idea, then continue.

## Degradation rule — when the scaffold can't run, write code, not ceremony

If the bootstrap can't run — a non-interactive/one-shot session, no network access, a
sandboxed temp dir, or the user just wants code rather than a running app — **don't
wait on the scaffold or the panel/passkey/publish machinery**. Write a standard Convex
project directly:

- **ALL backend code goes under `convex/`** (`schema.ts`, queries, mutations, actions)
  — **NEVER at the project root.** Convex functions only run from the `convex/`
  directory.
- **Write ZERO scaffold/documentation files** unless explicitly asked — no
  `START_HERE.md`, `ARCHITECTURE.md`, `MANIFEST.txt`, or README walls. "Build me a
  backend" is a request for code, not a design-doc package.

## Data access + imports — read before writing any convex/*.ts

- Never an unbounded `.collect()` on a table that can grow — use `.withIndex(...)` +
  `.paginate(paginationOpts)`/`.take(n)`.
- Index, don't filter — `.index(...)` in `schema.ts` for every read path, queried via
  `.withIndex(...)`; `.filter()` is a full table scan.
- Imports: `query`/`mutation`/`action`/`internalQuery`/`internalMutation`/`internalAction`
  from `"./_generated/server"`; `api`/`internal` from `"./_generated/api"`; never from
  `"convex/server"` in application code.
- `v.literal("exact value")` for fixed string/enum members, not a bare `v.string()`.
- `"use node";` is action-only — never in a file that also exports a `query` or
  `mutation`.

## Self-verify — before declaring backend work done

Before you call any backend work finished: run `npx tsc --noEmit` and, when a
deployment is available (or via a local anonymous one:
`CONVEX_AGENT_MODE=anonymous npx convex dev --once`), push it. Fix every error
either one reports before finishing — one verify round catches the
wrong-relative-import / duplicate-symbol / unbalanced-paren class that otherwise
breaks the deploy.

## STEP 0 — launch the scaffold NOW (before anything else)

Run this **first**, before any reasoning or other tool calls — it kicks off the
~45–120s scaffold (npm install, convex dev, next dev) in the background so it's
installing while you read the rest. Substitute the user's idea for `<IDEA>`:

```bash
BASE="https://basic-anteater-667.convex.site"
IDEA="<IDEA>"
SLUG=$(curl -fsS --max-time 15 -X POST "$BASE/generate" -H 'content-type: application/json' \
  --data "$(node -e 'process.stdout.write(JSON.stringify({idea:process.argv[1],template:"nextjs-shadcn"}))' "$IDEA")" \
  | node 

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: "quickstart"
description: "Scaffold a running Next.js + shadcn Convex app from one sentence — convex dev + next dev already running — then build the idea live (runs locally). TRIGGER when the user wants to START a new Convex app from scratch — e.g. they ran $quickstart, said 'scaffold a new app', 'build me an app where users can ___', or 'new app'. SKIP when there's already a Convex project in the cwd."
license: "Apache-2.0"
---

# Convex Quickstart (Codex beta)

Stand up a running Next.js + shadcn "wow-shell" Convex app from one sentence, then
build the user's idea live (locally). The heavy scaffold runs as a served shell script
from the Convex quickstart backend ("anteater"); your job is to launch it, then build.

> **Auth (passkeys), the feedback panel, custom domains, and public `*.convex.app`
> publishing are de-scoped for this release** — they ship later. The scaffold runs
> **locally only**, with no login and no panel. (The error-watch monitor in STEP 5
> still applies and is valuable — keep it.)

The user's request after `$quickstart` is the **app idea** (e.g.
`$quickstart a movie-night voting app` → idea = "a movie-night voting app"). If no
idea was given, ask for a one-sentence idea, then continue.

## Degradation rule — when the scaffold can't run, write code, not ceremony

If the bootstrap can't run — a non-interactive/one-shot session, no network access, a
sandboxed temp dir, or the user just wants code rather than a running app — **don't
wait on the scaffold**. Write a standard Convex project directly:

- **ALL backend code goes under `convex/`** (`schema.ts`, queries, mutations, actions)
  — **NEVER at the project root.** Convex functions only run from the `convex/`
  directory.
- **Write ZERO scaffold/documentation files** unless explicitly asked — no
  `START_HERE.md`, `ARCHITECTURE.md`, `MANIFEST.txt`, or README walls. "Build me a
  backend" is a request for code, not a design-doc package.

## Data access + imports — read before writing any convex/*.ts

- Never an unbounded `.collect()` on a table that can grow — use `.withIndex(...)` +
  `.paginate(paginationOpts)`/`.take(n)`.
- Index, don't filter — `.index(...)` in `schema.ts` for every read path, queried via
  `.withIndex(...)`; `.filter()` is a full table scan.
- Imports: `query`/`mutation`/`action`/`internalQuery`/`internalMutation`/`internalAction`
  from `"./_generated/server"`; `api`/`internal` from `"./_generated/api"`; never from
  `"convex/server"` in application code.
- `v.literal("exact value")` for fixed string/enum members, not a bare `v.string()`.
- `"use node";` is action-only — never in a file that also exports a `query` or
  `mutation`.

## Self-verify — before declaring backend work done

Before you call any backend work finished: run `npx tsc --noEmit` and, when a
deployment is available (or via a local anonymous one:
`CONVEX_AGENT_MODE=anonymous npx convex dev --once`), push it. Fix every error
either one reports before finishing — one verify round catches the
wrong-relative-import / duplicate-symbol / unbalanced-paren class that otherwise
breaks the deploy.

## STEP 0 — launch the scaffold NOW (before anything else)

Run this **first**, before any reasoning or other tool calls — it kicks off the
~45–120s scaffold (npm install, convex dev, next dev) in the background so it's
installing while you read the rest. Substitute the user's idea for `<IDEA>`:

```bash
BASE="https://basic-anteater-667.convex.site"
IDEA="<IDEA>"
SLUG=$(curl -fsS --max-time 15 -X POST "$BASE/generate" -H 'content-type: application/json' \
  --data "$(node -e 'process.stdout.write(JSON.stringify({idea:process.argv[1],template:"nextjs-shadcn"}))' "$IDEA")" \
  | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{process.stdout.write(JSON.parse(s).id||"")}catch{}})') || true
echo "SLUG=$SLUG"
QB=$(mktemp -t convex-qb-XXXX.sh)
curl -fsS --max-time 20 "$BASE/quickstart-bootstrap" -o "$QB" || { echo "BOOTSTRAP_FETCH_FAILED"; exit 3; }
# The bo

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: quickstart-improve
description: "Send THIS Codex session's transcript to the Convex quickstart backend for an AI post-mortem that improves the whole system (runbook, bootstrap, skills). TRIGGER when the user runs $quickstart-improve, or after a quickstart build says 'send feedback', 'report how that went', or 'help improve the quickstart'."
license: Apache-2.0
---

# Send session for review ($quickstart-improve)

Ships the current Codex session transcript to anteater's `/review` endpoint, which
runs an AI post-mortem and returns concrete findings to improve the runbook /
bootstrap / skills. The user's text after `$quickstart-improve` is an optional note
about how the run went (pass it as `--idea`).

Run it (QB_HARNESS=codex tells the helper to read the Codex transcript):
```bash
curl -fsSL "https://basic-anteater-667.convex.site/send-transcript" \
  | QB_HARNESS=codex bash -s -- --idea "<the user's note, or the app idea>"
```

Read the output:
- `REVIEW_DONE status=done` → summarize for the user: overall `outcome` + `summary`, then the top findings by `severity` (each: `title` → `target` → `suggestedFix`), then the `wins`. Keep it about the *system*, never paste back secrets (the helper already redacts).
- `REVIEW_PENDING` → it was submitted; the review is still running. Tell the user it's queued (the printed `/review/<id>` can be re-checked).
- `REVIEW_NO_TRANSCRIPT` / `REVIEW_TRANSCRIPT_TOO_SMALL` → no Codex transcript found; tell the user.
- `REVIEW_UPLOAD_FAILED` → the endpoint was unreachable (network/sandbox) — report it.