Working with AI

How Claude Code, Codex, Cursor and Copilot are set up to work in this codebase — and the MCP server that lets them ask instead of grep.

This kit is written to be extended by an agent, which mostly means two things: the conventions are written down where the agent will read them, and the codebase can answer questions about itself.

# The files

File	Read by
`AGENTS.md`	Codex, Cursor, Jules, Amp, Copilot — the cross-agent standard, and the source of truth
`CLAUDE.md`	Claude Code — deeper architectural notes
`.cursor/rules/*.mdc`	Cursor — six glob-scoped rules, loaded only when relevant
`.github/copilot-instructions.md`	GitHub Copilot
`.windsurfrules`	Windsurf
`.mcp.json`	any MCP client

AGENTS.md states three rules that override everything else: translate every user-visible string, never trust an id that arrived from a form, and npm run audit must report nothing when you are done.

# The MCP server

scripts/mcp-server.mjs is a read-only Model Context Protocol server over stdio. No dependencies — a boilerplate that drags a dependency tree in to expose eight tools is a liability.

claude mcp add saas-starter -- node scripts/mcp-server.mjs

Any other client reads .mcp.json, which is already committed:

{
  "mcpServers": {
    "saas-starter": { "command": "node", "args": ["scripts/mcp-server.mjs"] }
  }
}

Everything is read-only

No tool writes a file, runs a migration or touches your database. An agent can explore the whole codebase without asking permission, which is the point of exposing it this way.

# The tools

Tool	Answers
`audit`	what the code declares and does not do
`route_map`	every route, its kind, whether the middleware guards it
`data_model`	Prisma models and how many times src/ queries each
`plans`	the PLANS object verbatim — prices, limits, seats, features
`locales`	per-locale missing keys, empty values, placeholder drift
`env_check`	declared vs read environment variables
`size`	files and non-comment lines, per directory
`conventions`	AGENTS.md and CLAUDE.md verbatim

route_map in one call replaces reading twenty files to work out whether an endpoint is protected. plans means a plan gate is never written against a retyped number.

The analyzer behind it is open source and runs on any Next.js repository: github.com/THE-KIPDEV/saas-audit.

# Skills and commands

For Claude Code, .claude/ ships four skills and four slash commands:

	What it covers
`ship-feature`	page, guard, plan gate, translations, tests — end to end
`translate`	the eight-file workflow, plurals, placeholder drift
`rebrand`	name, theme, landing copy, emails, assets
`pre-deploy`	the checks that catch failures which are silent in staging
`/verify`	types, tests, audit, build — and what actually failed
`/audit`	every finding with the smallest honest fix
`/i18n`	locale drift, then fix it
`/new-page`	scaffold a page the way this repo requires

# The verification loop

Ask your agent to run these before it claims to be finished, in this order:

npm run verify
# tsc --noEmit  &&  vitest run  &&  audit --strict  &&  next build

“It typechecks” is not done

Two failure modes are invisible to tsc: a function prop passed across the server/client boundary, which only npm run build catches, and a translation added to en.json and nowhere else, which only npm test catches. Both have shipped here.

# Prompts that work

A fuller set is in AI Prompts and in docs/PROMPTS.md. The shape that works here:

Add a "Projects" page to the dashboard, limited by the plan's
projects allowance. Read the limit from PLANS rather than typing a
number. Translate every string in all eight message files. Then run
npm run verify and show me what failed.

Naming the constraints up front is what stops an agent from inventing a second convention beside the existing one.

# Why this matters

An agent that greps for “where is auth checked” reads twenty files and guesses. An agent that calls one tool gets twenty-three routes and their protection in a single turn, spends no context on file contents, and cannot be wrong about it.

The same applies to you: the audit output on the landing page and the answers the agent gets come from the same analysis. Nobody is reading a different version of this codebase.