Rules for every repo

Written by charter docs (the same page in every repo that uses it): don’t edit it here, change cmd/charter/docs/repo/rules.md in charter. A repo’s own rules are in its rules.md, and add to these.

Binding, for developers and agents alike.

Rule Why
One source for each fact. docs/ is where things are written; README.md, AGENTS.md and CLAUDE.md only point to it. What can be written from the code is generated from it Two copies drift, and the wrong one gets read
Never edit what is generated, or what charter writes. The first lines of such a file say so, and say what to change instead A hand edit is lost, and the check fails
Everything is a mise task. A workflow runs one task and nothing else, so what GitHub runs you can run. Never use GitHub as the edit loop, and never wait for it: run the task here A runner may not come for an hour; your machine is here now
Every task is safe to run again, and says what it acts on before it acts Nobody remembers what was run once
Start with the issues: mise run issues. One labelled needs-triage comes before anything else That is where a person said something is wrong
A plan is an issue, never a page: mise run issue -- plan prints the form. So is a bug, and a fault in something this repo is built on The docs say what is true now; an issue has a state, and people can see it
Workarounds name their issue: Upstream: <owner>/<repo>#<n> (when fixed: ...) in the code. mise run upstream:status lists them Otherwise it is never removed
Say what failed, first, unasked. Report as working only what you ran, and say where and when A reader acts on it
Do the whole job in one pass: what a change makes stale, the pages and the tests among it, changes in the same commit A half-done change is found by someone else, later
mise run check before a commit that matters, mise run release -- vX.Y.Z to release The check is the same one a release and GitHub run
Add files to a commit by name. No secret, token or personal address in a file, a commit or a log Other work is in the same tree, and a repo may be public

Working beside other agents

More than one agent may be working on a machine, and on a repo.

  • Your own git worktree, and your own ports for anything you start.
  • Do not stop, reset or delete what you did not start. A folder where someone has something running is not yours.
  • Never clear a cache other projects share (mise cache clear): pin a version instead.
  • One heavy job at a time, and a lock where two runs would use the same deployed thing.