Working with AI agents
The repository is set up so an AI coding agent can work on it with the same conventions as a person — and so a person can read exactly what the agent was told.
AGENTS.md
AGENTS.md at the root is the canonical working guide: commands, module
anatomy, layering rules, cross-cutting patterns, the database workflow, testing and the design
decisions. CLAUDE.md points Claude Code at it; other agents read AGENTS.md directly.
Skills
Task recipes live in .agents/skills/ (canonical) and are mirrored to .claude/skills/ for Claude
Code:
| Skill | Use it for |
|---|---|
add-module |
a new module or endpoint: generator, migration, queries, service, handler, routes, permissions, wiring, OpenAPI, tests |
db-change |
migrations, sqlc queries, regenerating internal/dbgen, nullable columns, sequences |
dev-dashboard |
dashboard endpoints, panels, commands, palette entries, form controls |
verify-changes |
the gates to run before calling a change done, including a live check |
Edit the .agents copy, then sync:
make skills-sync # copies .agents/skills → .claude/skillsmake skills-check # fails on drift (part of make gen-check and CI)Keeping agents honest
The same safety nets that protect human changes protect agent changes:
- route permissions, tenant isolation and wiring tests,
make gen-checkfor generated code and docs,make openapi-checkfor the contract,golangci-lintand the race detector in CI.
When an agent learns something non-obvious about the codebase, the place to write it down is
AGENTS.md, a skill, or Design decisions — not a chat history.

