Rewrite the agent instructions and split them by folder

[wasimxyz]

What changes

• Root AGENTS.md: rewritten to hold only the rules every task needs: secrets in commits, the changelog, generated snapshots, docs, testing before you call a change done, the Python 3.12 floor, how to load skills, and a pointer for Cursor Cloud.
• New AGENTS.md files next to the code they cover: web/lib/api, web/lib/db, web/lib/mcp, web/components, web/tests, web/mcp-apps, lambda, infra, and packages/shared.
• Rewritten: web, watcher, and docs/site.
• Skills: 31 agent skills are named in the file nearest the code they help with.
  • The four community skills (nuqs, zod, drizzle-orm-patterns, tanstack-form) are pinned to reviewed commits.
  • Agents ask before installing anything else.
• External docs: each service the code calls (Slack, Linear, Vercel, Better Auth, Drizzle, MCP, AWS) is linked from the nearest file, using its llms.txt.
• Next.js block: agentRules: false in web/ and docs/site/ stops next dev from writing its block into AGENTS.md. Our own Next.js 16 line replaces it.
• Deleted files:
  • web/CLAUDE.md, because Claude Code 2.1.277 and later reads AGENTS.md directly.
  • The two Cursor-only rules in .cursor/rules/.
• Cursor Cloud notes: moved to docs/developer/cursor-cloud.md. It now covers a VM where Postgres isn't installed, and includes a recommended install script for the Cloud environment.
• Stale developer docs fixed:
  • the Node.js version (24 with npm 11);
  • the local DATABASE_URL, which the reset and seed scripts refused;
  • the old parse_s3_event claim;
  • the make check description;
  • the missing infra-validate.yml section;
  • a broken link to the MCP Apps spec.

Why

• A 2026 study of context files found that repository overviews don't help agents, while specific rules do get followed. Claude Code's docs recommend under 200 lines per file. The new files are all under 65 lines.
• The rules come from mistakes in the last 25 PRs:
  • changelog files with the wrong date in 9 entries;
  • comments, docs, or changelog text that didn't match the code in 7 PRs;
  • snapshot drift after the zod upgrade (Upgrade Better Auth to 1.7.10 so MCP clients can register #324);
  • hard-coded tool counts left stale (Answer questions about Data Hub through the MCP server #301);
  • an integration test pushed without being run (Return to the page you opened after signing in #322);
  • a Better Auth upgrade that bumped one package (Bump @better-auth/oauth-provider from 1.6.27 to 1.7.0 in /web #308).

How I checked

• Every path, make target, and npm script named in the files exists, and every URL returns 200.
• All 31 skills resolve with npx skills add <source> --list. Each pinned skill loads from its commit, and a made-up commit fails.
• /_next/mcp, which next-dev-loop uses, still responds under make dev with agentRules: false.
• make check passes, and the MCP docs bundle is unchanged.
• Fresh agents answered 8 scripted questions correctly using only the repo: an MCP schema change, a zod upgrade, a watcher bug fix, a machine-only route, Postgres on Cursor Cloud, regenerating the Better Auth schema, the nuqs skill, and today's changelog entry. One gap, the exact command for a pinned skill, was fixed, and the question passed when asked again.

After merging

• Add the install and start scripts from docs/developer/cursor-cloud.md to the Cloud environment in the Cursor dashboard, so agents stop installing Postgres and uv by hand.
• Follow-up, not changed here: _LAMBDA_PRESET_SCOPES in lambda/tests/integration/test_lambda_api.py is missing runs:read, which the lambda preset in web/lib/api/scope-catalog.ts includes.

There's no changelog entry, because this changes only agent instructions and developer docs. There's no watcher version bump, because nothing under watcher/src/ changed.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
data-hub	Ready	Preview	Oct 16, 2026 10:48pm UTC
data-hub-docs	Ready	Preview	Oct 16, 2026 10:48pm UTC