Working on this repository with AI agents

This repository is meant to be developed mostly by agents: Claude Code, Codex, Cursor, or anything else that can read files and run commands. This page lists the tools that make that reliable, what each is for, and how to turn off the parts you do not want.

The rules themselves are in AGENTS.md. Every agent that follows the AGENTS.md convention reads it automatically, and CLAUDE.md imports it for Claude Code. This page is about the instruments.

The four questions an agent has, and where each is answered

project.map.json

It is written by hand and checked by machine. scripts/check-map.sh fails when it disagrees with the code:

• a file it names is missing;
• the site reads an env var the map does not list, or the map lists one that nothing reads;
• site/.env.example and the map disagree;
• a workflow uses a secret the map does not list;
• the frozen URLs differ from what mac/App/Core/Brand.swift compiles in.

Running it also rewrites docs/MAP.md. CI runs --check, so a stale human copy fails the build.

When you add an env var, a route the app calls, a command or an owner file, add it to the map in the same change. The check will tell you if you forget.

scripts/doctor.sh

It changes nothing, prints no secret values, and exits 0 whatever the project's state: an unfinished project is not an error.

• Offline by default.
• --online also asks GitHub (release secrets, published releases) and Apple (the notary profile).
• --json gives the same report as JSON, for agents.

scripts/verify.sh --json

It runs the same checks as scripts/verify.sh (add --quick to skip the builds). Progress goes to stderr, and stdout gets one document:

• ok and failed summarise the run;
• per check, findings holds the FAIL lines, each with its fix and, where the check lists them, where (file:line hits);
• per failed check, tail holds the last lines of output, for tools that do not print FAIL lines;
• manual lists the human-only checks.

Hooks (Claude Code)

.claude/settings.json wires scripts/agent-hook.sh into two moments:

• After every edit, it runs only the checks that file can break: the brand scan always, plus the palette, wiring, scheme, map or docs check depending on the path. It takes a second or two.
• When the agent stops, it runs every fast weld, but only if the tree changed since the last green run. It takes a few seconds, and nothing when nothing changed.

On a failure the agent is shown the FAIL lines and has to deal with them before going on. The builds and unit suites are not in the hooks: they stay in verify.sh, which the rule books require before finishing.

Other harnesses can call the same script. It reads the hook JSON on stdin (tool_input.file_path for post-edit, stop_hook_active for stop).

Turning hooks off:

• for yourself: { "disableAllHooks": true } in .claude/settings.local.json, which git ignores;
• for one session: AGENT_HOOKS=off in the environment.

Skills (Claude Code)

Recipes live in .claude/skills/<name>/SKILL.md. Each one names the files it touches, never weakens a check to pass it, and ends by running scripts/verify.sh --json and reporting manual.

More arrive with the features they cover: payments, emails, content, release. Agents without Claude's skills can read the same SKILL.md files as plain instructions.