Building on the kit with a coding agent: the guardrails that matter

A coding agent is fast and confident, which is exactly the problem in a codebase it does not know. It invents a pattern the project does not use, skips a check, or spends an hour on a setup error someone already solved. shipanysaas is set up so the agent starts with the answers. Here is what that consists of, and where you still need to pay attention.

The kit itself has no AI features. Everything below is for the agent you build with: Claude Code, Codex, Cursor, Copilot or another one.

1. Tell the agent where things are

AGENTS.md at the repository root is the agent's map: the monorepo layout, how accounts and teams own data, which helpers to use for server actions, route handlers and database clients. Sixteen more AGENTS.md files sit in apps and packages, so an agent working in apps/web/supabase also reads the database rules there.

Agents find the root file in different ways. Claude Code reads CLAUDE.md, which imports AGENTS.md. Codex and Grok Build read AGENTS.md directly. Copilot, Cursor, Junie, Antigravity, Devin, Kiro and Cline each have a short pointer file that sends them to it. The files are all committed, so switching agents costs nothing.

2. Give it skills for specific jobs

A skill is a folder with instructions for one task. The kit ships 49. Nine are written for this codebase: postgres-expert for tables and policies, server-action-builder, service-builder and react-form-builder for the app layer, playwright-e2e for tests, and reviewer, rls-review, bug-hunt and bug-hunt-lite for checking work. The other 40 come from Supabase, Stripe, Expo, Vercel and others, each with its licence. Where general advice conflicts with how the kit works, the AGENTS.md files say which rule wins.

3. Make it check its own work

The root AGENTS.md lists what the agent must run before it says it is done:

pnpm typecheck
pnpm lint:fix
pnpm format:fix
/reviewer, an adversarial review of the change
/rls-review if anything in the database changed: a policy, a grant, a function, a migration

The fifth step is the important one. A type error shows up on its own. A policy that lets one team read another team's rows does not, until a customer notices. /rls-review looks for that kind of hole and proves it is closed with pgTAP tests that sign in as an outsider and try to get in.

4. Write down the errors already solved

docs/troubleshooting/agent-known-issues.md has 17 numbered entries: errors met while running this kit, most with the exact message, the cause and the fix. Most are about the phone app and Expo; others cover a Supabase clock-drift error, stale environment values and two CSS pitfalls. AGENTS.md tells the agent to check this file before it starts investigating.

A worked example

Say you want projects inside each team. One request covers it:

Add a projects feature for team accounts: a projects table with /postgres-expert, server actions with /server-action-builder, a create form with /react-form-builder. Then run /reviewer and /rls-review.

A good result has these parts, and you can check each one:

A new schema file and migration with account_id, row-level security on, revoke all from the API roles, and an update grant that leaves out id and account_id.
Policies that use has_role_on_account (and has_permission if only some roles may write).
A pgTAP test that signs in as someone outside the team and fails to read, insert, update or delete.
Server actions built on authActionClient with a Zod input schema, using the normal Supabase client so the policies apply.
A form built with react-hook-form and the kit's form components.
Regenerated types (pnpm supabase:web:typegen) and passing checks.

If the agent reaches for getSupabaseServerAdminClient() to make something "just work", stop and ask why. That client skips row-level security, and in a feature like this it is almost never needed.

What still needs you

Product decisions. Which roles can do what, what a plan includes, what to build next.
Reading the policies. They are short. Read every new one, and run pnpm supabase:web:test yourself.
Accounts and secrets. Supabase, Stripe or Lemon Squeezy, your email provider and the app stores need you to sign up and paste keys into your host's environment settings. Keep them out of committed files.

More detail: Coding agents and Agent skills.

1. Tell the agent where things are

2. Give it skills for specific jobs

3. Make it check its own work

The root AGENTS.md lists what the agent must run before it says it is done:

pnpm typecheck

pnpm lint:fix

pnpm format:fix

/reviewer, an adversarial review of the change

/rls-review if anything in the database changed: a policy, a grant, a function, a migration

4. Write down the errors already solved

A worked example

Say you want projects inside each team. One request covers it:

Add a projects feature for team accounts: a projects table with /postgres-expert, server actions with /server-action-builder, a create form with /react-form-builder. Then run /reviewer and /rls-review.

A good result has these parts, and you can check each one:

A new schema file and migration with account_id, row-level security on, revoke all from the API roles, and an update grant that leaves out id and account_id.

Policies that use has_role_on_account (and has_permission if only some roles may write).

A pgTAP test that signs in as someone outside the team and fails to read, insert, update or delete.

Server actions built on authActionClient with a Zod input schema, using the normal Supabase client so the policies apply.

A form built with react-hook-form and the kit's form components.

Regenerated types (pnpm supabase:web:typegen) and passing checks.

If the agent reaches for getSupabaseServerAdminClient() to make something "just work", stop and ask why. That client skips row-level security, and in a feature like this it is almost never needed.

What still needs you

Product decisions. Which roles can do what, what a plan includes, what to build next.

Reading the policies. They are short. Read every new one, and run pnpm supabase:web:test yourself.

Accounts and secrets. Supabase, Stripe or Lemon Squeezy, your email provider and the app stores need you to sign up and paste keys into your host's environment settings. Keep them out of committed files.

Building on the kit with a coding agent: the guardrails that matter

What a coding agent needs from a codebase, how shipanysaas provides it, and a worked example of adding a feature without weakening the security rules.

1. Tell the agent where things are

2. Give it skills for specific jobs

3. Make it check its own work

4. Write down the errors already solved

A worked example

What still needs you

Building on the kit with a coding agent: the guardrails that matter

What a coding agent needs from a codebase, how shipanysaas provides it, and a worked example of adding a feature without weakening the security rules.

1. Tell the agent where things are

2. Give it skills for specific jobs

3. Make it check its own work

4. Write down the errors already solved

A worked example

What still needs you