Building with AI agents

Why this kit suits agent work

An agent writes code fastest where a mistake is caught quickly and the right location is unambiguous. The kit is built around both: every layer is strictly typed, every behaviour has a test layer that runs in seconds, and the module contracts decide where new code belongs so the agent never has to guess.

The archive ships the same contract files this repository is developed with, so an agent working in your fork reads the same rules the maintainers follow.

• AGENTS.md at the repository root: the engineering contract an agent reads before editing.
• docs/AGENT-PLAYBOOK.md: where each kind of code belongs, step by step recipes for the common changes, the traps that caused real bugs, and how to start a new product from the kit.
• CLAUDE.md and .github/copilot-instructions.md: the entry points Claude Code and GitHub Copilot read, pointing at the same rules.
• DESIGN.md: the design authority for colour, typography, spacing and component rules.
• docs/ARCHITECTURE.md: the layering rules and a worked example of adding a feature.
• docs/MODULES.md: how a provider is added behind a contract without touching the application.
• docs/TESTING.md: the test layers and what each one proves.

A safe request to an agent

Ask for one vertical slice at a time and name the boundary it belongs to. The layering rules tell the agent where the code goes; the shared envelope and the repository contracts tell it what it may not bypass.

Add a team invitations feature:
- a teams and invitations schema with a migration
- invitation services with expiry and single use tokens
- routes under /api/teams that use the shared envelope
- ownership checks on every mutation
- tests at the service, route and D1 layers
Follow docs/AGENT-PLAYBOOK.md recipes 5.2, 5.3 and 5.4.
Do not import a provider directly.

The boundaries an agent must not cross

These rules are what keep an agent's output maintainable rather than plausible. They are asserted by review and, where possible, by the suite.

• A route handler validates, resolves the session, calls one service and maps the result. It never holds business logic.
• A service never imports from src/app or src/components.
• A provider is reached through the module registry. The application never imports a vendor directly.
• Every response uses the shared envelope, so the client never parses two shapes.
• New surfaces read the product identity from src/config/product-identity.ts rather than hard coding a name.

The verification loop

Run the loop after every change instead of trusting a plausible diff. Each command is executable as written from the repository root, and bun run verify runs all of them in order.

bun run lint
bun run typecheck
bun run test
bun run build

# or all of them, plus the UI snapshot check
bun run verify

Recipes, not guesses

Most changes touch more places than they appear to. A protected page also needs the proxy policy and both sign in redirect allow lists; a new table also needs the test migration list, both storage drivers and the account erasure. The playbook lists every place for each common change, so an agent completes the change instead of producing one that works locally and fails in production.

It also records the traps that have already caused real bugs in this codebase, such as a vendor specific status map in shared billing code and a request body read twice, so an agent does not reintroduce them.

What the kit does not do for you

An agent produces code, not judgement. These remain the product owner's decisions.

• The agent cannot decide the schema for a domain it is not given; review the migration it writes.
• A passing suite is not a security audit. Read the security page and review what the agent changed around sessions, tokens and payments.
• The agent can write the legal pages from a template, but the terms, the privacy policy and the data map are yours.