Yonto Player is built with AI coding agents, and on most days more than one is working at the same time. There are several checkouts of the repo side by side on one Mac, each with an agent in it, each fixing or testing something different.
What makes that work is a short list of habits. They are plain ones, and plain is what I want from them. Here are the ten I would copy first.
1. One working copy per agent
Every agent gets its own checkout of the repo, and the checkouts are siblings in one folder. Each agent owns its checkout and its branches outright, so it can switch, build and test there whenever it likes. A branch is one issue, one pull request, and its name is a short phrase that says what it does.
Subagents an agent starts for itself belong to that agent's checkout. It directs them, and they never reach into the neighbour's folder.
2. Your own device, in your own port range
An emulator belongs to the agent that booted it, so each agent installs to, drives and tests against its own and nothing else.
Every checkout therefore has its own virtual device, named after its kind and the folder it lives in, and its own block of ports. A simplified sketch of the convention:
# one block of console ports per checkout, never shared # checkout-a: <block A> checkout-b: <block B> checkout-c: <block C> # inside a block: the TV takes the base port, the phone base+2, a tablet base+4 emulator -avd tv_$(basename "$PWD") -port $BASE_PORT -gpu host ANDROID_SERIAL=emulator-$BASE_PORT ./gradlew :app:tv:installDebug The second line matters as much as the first. Gradle's install and connected-test tasks go to every attached device unless the serial is named, so the serial goes in the same command every time, not in an earlier export.
3. A build that is never interrupted
All the checkouts run the same Gradle command, and the daemon is shared. A build runs to completion in its own checkout, and an agent stops only what it started, by that process's own id.
It is a small rule, and it lets a long full-verification run finish while two other agents start theirs.
4. The issue is the meeting place
Agents in different checkouts never assign each other work and never wait for each other. They meet in one place, GitHub. An agent picks its own next issue, reads the claims on it, and claims it with a comment:
Claimed by <session name>. Files: <the files this touches> The files line is the useful part. Two agents in one file is what reliably produces conflicts, so an agent takes what nobody holds files for, and leaves the rest. A claim that has gone quiet gets a "still held?" comment, and is dropped if another day passes with no answer, so about two days of silence in all.
5. Plan before building
The fix-an-issue workflow has an order: reproduce, investigate, plan, file, fix, review, merge. The plan comes before the first edit: the cause, the change, what could break, and what I will not do. It names the alternatives that were rejected, and that later becomes the "what" of the pull request.
In my experience a plan written down first makes for better fixes, and where the choice is a judgement call the agent asks me.
6. Tests that prove something
A green test only helps if it can go red. Every new test is mutated before the pull request goes up: break exactly the line it claims to hold and watch it fail. Then revert each decision separately, because reverting the whole change at once proves that something is pinned, not that everything is.
Where the shape allows it, a compile error beats a test. Dropping the default of a parameter turns "someone forgot to wire it" into a build failure that cannot rot.
7. Verification before done
A change is not done when the tests pass. The pull request carries evidence from the thing itself, and where a device applies the aim is a before and after captured on it; otherwise it is a measurement. It also has a "how to test" section a stranger could follow. A cached green run is not evidence, so the full verification line runs with --rerun-tasks.
8. A reviewer that did not write the code
Review goes to a fresh worker with no part in writing the change. In this repo that is a small agent definition, a few lines long:
--- name: reviewer description: "Reviews one PR as a fresh worker with no part in writing it." effort: medium --- Read the review rules first; the brief can add to them, never relax them. Verify rather than read, stay scoped to the diff and the body's claims, and post the verdict on the PR. The effort is pinned in the file, because a plain subagent inherits the effort of whoever started it. That depends on the tool you use: it is how my agent tooling reads this file, and yours may handle effort differently. The repo defines seven workflows as skills and this one reviewer agent. There are at most two review passes. At the cap, every open point is settled in writing: the code stands and here is why, or it is real and becomes its own issue.
9. Docs change in the same pull request
The docs, the agents' briefing file and the workflow files are what the next session reads. A doc that describes old behaviour is a trap for the next agent, so a change whose docs are not written is unfinished.
Before opening the pull request, I say in one sentence what the change makes false, then search for the subject, not the exact sentence, and read every hit. Nothing re-runs prose, so neither the test suite nor a reviewer reading the diff will catch a stale copy.
10. Lessons kept as files
An agent does not remember yesterday, so what was learned has to be somewhere it will be read. The traps live in plain Markdown, split by area (building, devices, testing, the phone, the TV), and the briefing file has a table that says which one to read for which job:
| Read this when... | File | | --------------------------------- | ----------------------------- | | a build, test or lint fails | docs/agents/build-and-test.md | | you boot or drive an emulator | docs/agents/devices.md | | you write or change a test | docs/agents/testing.md | The workflows are Markdown too, written so any agent, or a person, can follow them, and none of them assumes a particular tool. A rule goes into the file the moment it is learned.
What I would take from this
Agents in parallel are mostly a coordination problem, and the answers are the ones teams already use: their own space, their own tools, one shared place to say what you are doing, and a second pair of eyes that did not write the code. The difference is that an agent only knows what is written down, so the writing down has to be good.
Read more
The documentation covers what the app does, the developer docs describe the plugin contract, the open-source plugin SDK and command-line tool are on GitHub, and every release is in the changelog.
