Work with an AI agent

A kit site is made for changes by AI coding agents, such as Claude Code, Codex or Cursor. Content is in plain files, the build checks every change, and the kit gives the agent its rules.

The rules an agent reads

• The site's AGENTS.md points the agent to the kit's rules, in node_modules/@hostsmith/site-kit-astro/AGENTS.md, and holds the notes for this site only. Add those notes below its heading.
• The site's CLAUDE.md loads both files for Claude Code.
• The kit's rules come with the package, so a kit update updates them too.

Before an agent's first change, the site needs its packages installed, with npm ci, so the kit's rules are there to read.

What the rules tell an agent

• Content goes in src/content/. Pick a library section type that fits a block before writing a new one.
• A fact is written once. The phone number, the address or a license number go in the settings' facts, and the content writes {phone}. A header button, opening hours or a link column is a block in the settings, never a new component.
• No visible text in templates. A label in the site's own markup is an interface string, translated with the rest of the content.
• Every locale. A new page or entry gets its translations, or the agent says which locales go without it. Translations keep their section ids.
• Styles go through the theme. Colors only in the color presets, fonts only in the type tokens, kit parts styled through their sk- hooks.
• The kit stays the kit's. The agent never edits node_modules or the assembled CMS config, public/admin/config.yml, and never copies the kit's code into the site.
• No new packages. The site uses only the kit, Astro and Tailwind. A change that seems to need another package is raised with you instead.
• Third-party files need a license. A font or image from elsewhere is added only under a license that allows it, and listed in CREDITS.md. One whose license is unknown, such as a font from the old site, is listed as awaiting confirmation, and the agent tells you.

The checks an agent runs

The deploy workflow runs the style checks and the build again on every push, so a change that fails them never deploys.

Review a change

1. Ask the agent for the change on a branch, such as "On a new branch, add an FAQ section to the services page with these three questions, then push it".
2. The push deploys the branch to the preview site. Check it, and send the client the link.
3. Merge the branch to main once the client approves: the merge deploys it to production.

Every change is a commit, so you can see what the agent changed, and undo it with git revert.

The kit's rules are in its repository, in full.