Agents files

Coding agents (Claude Code, Codex, and others) read instructions from files in the repository. Every Inky Labs repository has them, so that an agent knows the project’s conventions, and knows where the org-wide ones live, before it changes anything.

The rules

Every repository has an AGENTS.md at its root. It’s the one file of instructions; agents that look for another name get a pointer to it.
CLAUDE.md is a one-line pointer, because Claude Code reads that name:
```
See [AGENTS.md](./AGENTS.md) for instructions.
```

Every AGENTS.md names this handbook as the source of defaults. Put this near the top:

## Defaults

Inky Labs’ org-wide practices, covering builds, CI, domains, tools and these
agent files, are at https://developers.inkylabs.com
(source: https://gitlab.com/inkylabs/developers.inkylabs.com). Follow them unless
this file says otherwise; where it does, this file wins for this project.

Write down only what’s specific to the project. Don’t copy the handbook into each repository, where copies drift. Link to the page instead. When a project departs from a default, say so and say why.

What belongs in a project’s `AGENTS.md`

What the project is, in a paragraph: what it serves, how it deploys, and where the moving parts live.
Conventions an agent would otherwise get wrong: typography, brand spellings, generated files that mustn’t be hand-edited, commands that must run after a change.
The reasons behind them. A rule with its reason gets applied sensibly to cases nobody anticipated.
Traps that already cost time, so the next agent doesn’t repeat them.

What doesn’t belong

Secrets. Many Inky Labs repositories are public, and agent files are read by tools that may send them to a model provider.
Personal setup, such as one person’s paths, machines or accounts. That goes in the person’s own global agent instructions.
Anything already in this handbook. Link to it.

Send and ship

Two words for asking an agent to take a change out of the working tree, so that nobody has to spell out the steps, and every agent takes them the same way in every Inky Labs repository:

Say	The agent	Which is
send	commits on a topic branch, rebases onto `origin/master`, and opens the merge request	`inkylabs-mr`
ship	does all that with the release in it: bumps the version, sets auto-merge, and watches it to the deploy	`inkylabs-mr --ship` (`minor` or `major` when asked)

Saying it is the go-ahead. “Ship it” authorizes every step through the deploy, so the agent doesn’t stop to ask before pushing, opening the merge request or setting auto-merge. It doesn’t authorize anything the steps don’t include: approving for another owner, or --no-build when the build fails. “Send” stops at the open merge request, for someone to look at first.

Shipped means deployed. The agent runs inkylabs-mr --ship in the background and reports what it exits with (Releases): deployed, failed (with the link), or waiting for a person, naming whom. It doesn’t report a change as shipped when auto-merge is set, nor when it merges. A project whose AGENTS.md names a page to check after a deploy gets that check too.

Plans

Before writing code for a new project, or for a feature that changes what people see or will take more than one merge request, an agent asks whether to write a plan first. Ask once, at the start, and take the answer. Don’t ask for a bug fix, a refactor, a dependency update or an infrastructure-only change. If the answer is yes, the inkylabs-plan skill drafts the plan in inkylabs/plans.inkylabs.com (not yet created), and the work waits until it’s accepted.

Skills

Some org-wide tasks get an agent skill: a SKILL.md that tells an agent when and how to do the job. Skills live in this repository’s skills/ directory. Link each into your agent’s skills directory, so a git pull updates it:

mkdir -p ~/.claude/skills
ln -sfn ~/projects/developers.inkylabs.com/skills/inkylabs-audit ~/.claude/skills/inkylabs-audit
ln -sfn ~/projects/developers.inkylabs.com/skills/inkylabs-plan ~/.claude/skills/inkylabs-plan

Skill	For
`inkylabs-audit`	Auditing every repository and site against this handbook with `inkylabs-audit`, then working through the findings
`inkylabs-plan`	Asking whether new work needs a plan, and drafting one with its mockups in `inkylabs/plans.inkylabs.com`

When a lesson applies org-wide

If an agent learns something that would help in every repository (a tool’s quirk, a service’s misleading error), add it here, not to one project’s AGENTS.md. The Domains page’s note on Porkbun’s INVALID_DOMAIN error started this way, in SVRBC’s handbook, which this one copies.