People and coding agents follow the same AGENTS.md contract in the Template. Work starts from the assigned card, follows the relevant skill, changes tests and documentation with code, and ends with checks and a reviewable Studio request. The person tagged on the card owns the outcome.
What an agent reads first
Read the contract and the card
Read AGENTS.md, docs/Home.md and the assigned card in docs/cards/. Its observable Done when defines the outcome; agents do not choose product decisions or invent their own work.
Read architecture and the owner
Read ARCHITECTURE.md, docs/engineering/Coding Standards.md and the affected system note. Read Server Authority before remotes, currency, purchases or saves.
Find the procedure
Use the index in
.agents/skills/README.md, then read its SKILL.md. Inspect nearby code and the folder README before adding a pattern.Work through the vault
Keep scope, waiting-on information and results in the card. Update system notes when code changes their facts, and propose a decision record for a significant architectural choice.
AGENTS.md is the only instruction file. Everything else for agents lives in .agents/: skills/ (the procedures), reviewers/ (review briefs for a fresh agent) and hooks/ (Lune scripts run around an agent's tool calls: the main-branch guard and format-on-edit). .claude/settings.json runs the hooks by the checkout's root (git rev-parse --show-toplevel), so they work from any folder of the checkout. There is no CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, .codex/ or .gemini/: a second instruction file would drift, and Claude Code stops reading AGENTS.md while a CLAUDE.md exists.
| Tool | Reads | Also |
|---|---|---|
| Claude Code | AGENTS.md, while no CLAUDE.md exists | Skills and subagents from their copies in .claude/; .claude/settings.json holds the permissions and runs .agents/hooks/ |
| Codex | AGENTS.md, .agents/skills/ | No hooks or custom agents; run a reviewer by starting a subagent with its brief |
| Gemini CLI | .agents/skills/; AGENTS.md once context.fileName names it | Once per machine, in ~/.gemini/settings.json: context.fileName set to AGENTS.md |
| GitHub Copilot, Cursor | AGENTS.md, .agents/skills/ | Nothing |
Without hooks (every tool but Claude Code), run lune run format before lune run check, and check the branch before a commit: never commit on main. Session memory helps navigation; the code and repository documentation remain the truth.
One skill set, nineteen procedures
The editable source is .agents/skills/, the Agent Skills location most tools read. Claude Code reads skills and subagents only from .claude/, so lune run skills-sync copies .agents/skills to .claude/skills and .agents/reviewers to .claude/agents. Nobody edits the copies; commit both in the same PR, and lune run check refuses drift.
| Work | Skill names |
|---|---|
| Track and review a change | card, verify, playtest |
| Add a game feature | add-service, add-remote, ui-screen |
| Save, charge and tune | data-field, monetization, balance |
| Measure and support | analytics-event, admin-command, performance-pass |
| Art and safety | add-asset, security-review |
| Maintain the system's explanation | docs-sync, adr |
| Adopt, clean and ship | new-game, delete-demo, release |
Each procedure names the files and checks for its task. add-service and add-remote include covering the feature with the anti-cheat: classify the currency reasons it pays with, call AntiCheatService.teleport, exempt or excuse before a server move, name a client-made body mover, flag only a request honest play cannot send, and never let the client send what a remote's check rejects (anti-cheat). ui-screen covers HUD widgets (declared in Config/Layout and bound with UI/Util/widget), what the top bar is kept for, the Dropdown modes and FriendshipController as the one source of who is a friend. admin-command covers a Template built-in's category module under AdminService/Commands/ and optional arguments; add-asset the icon folder's README row and drawing a Template icon with tools/assets/make_icons.py; security-review a change to two players' saves (TradeService is the pattern); and docs-sync what an added admin command and a .lune/ script must update. Skills describe how to follow the rules; they do not override AGENTS.md. Two review briefs in .agents/reviewers/ are run by a fresh agent on the diff before a pull request opens: server-authority-reviewer for anything touching remotes, currency, purchases, saving or randomness, and docs-auditor for anything that adds, moves, renames or removes something. They only report; their findings go in the pull request description, and a person remains responsible for approval and playtesting.
Cards and the board are the progress record
The Template's vault is separate from the Platform's vault. The Template ships docs/Board.md empty and docs/cards/ with only its README; a game's lune run init adds the starter board and the Template adopted card. On the board, work moves through Backlog, Ready, In Progress, Review, Testing and Done; Blocked records work that cannot move. A Backlog idea becomes a card from docs/templates/Card.md before Ready. There are at most two In Progress cards per person.
Agents fill Result and move a card to Review, or record its block. They never move it to Testing or Done and never write in the vault Log. Out-of-scope discoveries become a Backlog line; a small related bug can stay with the card.
Branches and commits
One card uses one branch and one PR, based on up-to-date main, ideally under 400 changed lines. Only one of the team's pull requests is open at once: it is finished (checks green, merged) before the next opens; release and Dependabot pull requests do not count. Template branches use feature/, fix/, balance/, docs/, chore/, refactor/, test/, ci/, perf/ or build/.
feat(shop): buy an item with coins
fix(data): release the profile before kicking a duplicate session
balance(economy): halve the cost of the first upgradeThe title is type(scope): subject, imperative, lowercase, no final full stop, at most 72 characters. The scope is optional. A ! marks a breaking change, such as feat(data)!: for a save-format change. Squash PR titles become commits and feed release-please; balance values change separately on a balance branch. Commit as the developer running the work, without co-author trailers or tooling attribution. An agent may open and merge its pull request once the checks pass: git fetch, merge a moved main into the branch and wait for the checks again, then squash-merge with --match-head-commit. In the Template repository, a pull request that makes a handbook page untrue lists the pages under Handbook in its description, and the handbook is brought up to date in one Platform pull request per wave of Template changes. A game never writes to the handbook, and lune run init removes that section from its pull request template.
In the Template, and in a game until delete-demo removes the showcase, every note in docs/systems/ and every Config/Features switch has a scenario in Config/Showcase, and every UI component is shown in the showcase gallery; specs fail when one is missing. A new system, switch, component or admin command therefore adds its showcase entry with it, and lune run new prints that step.
What needs a person
- Product and architecture decisions
Agents implement the assigned outcome and may propose a decision record with status Proposed. They do not accept their own record or add a package or tool without asking. The Template ships no records: its decisions are one line each in
ARCHITECTURE.mdDecisions, and a game's own records are numbered from001indocs/decisions/(theadrskill).- Protected actions
No direct main commits, pushes or merges, force-pushes,
git stash(stashes are shared by every worktree, so one agent's can be popped onto another's branch), administrative merges, repository-setting changes, reading.envor place publishing by agents. Asset uploads work only when the developer has putASPHALT_API_KEYon the machine, which is their consent. Branch work and normal PR operations follow the contract and passed checks; Claude Code enforces this through.claude/settings.jsonand the main-branch guard hook.- Runtime evidence
A person runs visual, audible, physical, networking, real DataStore and purchase checks. Passing pure specs and a Rojo build cannot prove that a screen rendered or a purchase persisted.
- Review and release
Every pull request is reviewed before it merges: by another developer when the team has one, else by its author, with the reviewer agents in
.agents/reviewers/. The reviewer checks server authority first, plays the written Studio check and handles the board's post-merge states. No approval count is required, and the author squash-merges once the checks are green. GitHub enforces these rules only where branch protection is available (a public repository, or a paid plan for a private one); elsewhere the process and the hooks hold them. Live publication follows the release procedure.
The final report names commands and results, anything skipped and the exact human check still needed. Use the playtest skill to write what to open, do and expect, including the refused case and rejoin for saved state. The full rules are in the Template's AGENTS.md, docs/engineering/Working with Agents.md, Workflow.md and CONTRIBUTING.md.
See the required checks and release pipeline.
Adopt the Template before taking the first card.
Updated