Skip to main content

Agent guide

Status: Scaffolded 2026-09-24

Much of this codebase is written with AI coding agents. The repos are set up so an agent gets the same instructions a person would, in the same order, and so the checks that matter cannot be talked around.

Read order​

Every repo has AGENTS.md at the root and a CLAUDE.md containing only @AGENTS.md, so any agent that reads either file lands on the same text. The order is fixed:

  1. SOUL.md: what the product is and the three forces (compassion, action, community).
  2. PRODUCT-PRINCIPLES-CHECKLIST.md: the checklist worked through before proposing completion.
  3. Then implement.

AGENTS.md ends with a repo-specific section: where the layout is described, which script runs the tests, what the repo must never contain. For the API that section points at backend overview; for the clients, at mobile and web.

Non-negotiables, restated for agents​

  • Privacy first. A new field means a new row in the data inventory in the same change. Profiles are never public. Nothing personal reaches logs or third parties.
  • The principal comes from the session, never from a request body.
  • Every list is filtered by visibility on the server before it is returned.
  • Shared tokens only: --vg-* in web CSS, src/theme/tokens.ts in mobile. No new hex values in components, no third-party fonts or icon CDNs.
  • Smaller scope with tests beats larger scope without. When uncertain, choose the smaller scope and ask.
  • Never write an infrastructure identifier into a file: no host, IP, instance id, port, PEM name, process name, or SSH command. The disclosure policy is binding on generated docs too.

The completion triple​

Before proposing that a change is done, an agent runs npm run validate and states three things: what activist outcome improved, what privacy and trust checks were run, and what signal should be monitored. These are the first, third, and fourth lines of the PR summary block; the agent's completion message should be pasteable into it.

secretlint is a stop​

The pre-commit hook runs secretlint on every staged file. An agent that sees a finding does not retry with --no-verify, does not widen the allowlist, and does not rewrite the value to dodge the pattern. It stops, reports the finding, and waits. See pre-commit hooks.

Commits​

Conventional subjects. Agent-assisted commits are authored by the maintainer; the agent stages and hands off. Squash merges into main with validate green.

The docs' own agent surface​

This site is built to be read by agents as well as people:

  • /llms.txt at the site root lists every page with its one-sentence description, in sidebar order.
  • Every page has a .md twin at the same path with the extension (/engineering/agent-guide.md) serving the raw Markdown, so an agent can fetch a page without parsing HTML.
  • The description frontmatter field is required by the build for exactly this reason: it is what the index and the twins lead with.

When you add a page, write the description as the sentence you would want an agent to see when deciding whether to open it.