How do several Agents work in one repository without stepping on each other, and how does their work reach my stable branch?
Put three Agents in one checkout and they overwrite each other, because one folder shows one branch at a time. A Git worktree gives each branch its own folder, so Agents work apart. That creates the second problem: their work has to be put back together on purpose. Ronin Worktrees does both halves. This page explains the problem and the choice, then walks the whole journey of using it in Ronin.
The topic
Git gives you as many branches as you like, but a checkout shows one of them. "Just make your own branch" is still everyone sharing one set of files: each switch swaps the files out from under whoever else is working there. Three Agents on three branches in one folder collide exactly as if they were on one branch. A worktree is a branch with its own folder. Many Agents edit at once, and nobody's half-finished work reaches anyone else until it is accepted. Choose once per repository; both models are first-class, and one Agent can hold both in different repositories.
Fits a workspace: notes, plans, a scratch repository, anything without a release.
Fits a product: a codebase with a release, tests, and several Agents at once.
The branches
A small file at the repository root names its working line and its stable line. Every tool reads that file; nothing is decided by whichever branch happens to be checked out.
Usually dev. Nobody edits it in place. Work reaches it by promotion, and every worktree is cut from it.
Usually master or main on GitHub. It moves only by a pull request from the working line, which you review and merge yourself.
One line per Team, a worktree branch per Agent, candidate folders. Each has an owner, a recorded starting point, and a place it hands in to. Once its work is promoted, its worktree is closed explicitly; unfinished work at a session's end is kept in visible custody, never deleted quietly.
How to use it in Ronin · setup
Ask your agent
Hand this to any Agent in your Ronin. It reads, it does not change anything, and it tells you which station each piece of work is at.
Tell me where my Team's repository work stands. Read only; change nothing. For each Agent on the Team, say which worktree it holds, whether it has unsaved files or commits it has not handed in, and whether it is waiting on the lead. Say what is on the Team's review line and whether promotion is due. Say who is marked team lead, or that nobody is. Say whether the working branch is ahead of the stable branch on the remote and whether a release pull request is open. Use Ronin's own status tools and receipts, not memory.
How to use it: the journey in one look
On the Team page, mark one session as team lead. Nothing infers it from behaviour; it is your designation.
A coding Agent born onto the Team starts in its own folder on its own branch, cut from your accepted work.
Checkpoints stay private. A hand-in gives committed work to the Team's review line and leaves a receipt.
The lead rules on conflicts, verifies the combined line, and promotes it onto your local working branch.
Promotion tells each contributor its work is in. Only then is a worktree finished, and it closes.
One rolling pull request carries the working branch to the stable branch. Merging it is your hand, nobody else's.
Work runs in parallel at stations two and three. Landing is one at a time at station four. Nothing reaches GitHub until station six.
What to notice
Station one
A Team lead is a person's designation, not a guess. You mark one from any session's tile on the Team page, and you can move it later. Ronin never decides that a session is the lead because of what it did.
Why bother? Because the review line needs one reader. When an Agent hands work in, Ronin tells the lead, in its tile, that the line has moved and is waiting for review. When two hand-ins disagree, the lead is the one asked to rule. When the line is coherent, the lead is the one who promotes it. One gate, one reader, one set of receipts with one name on them. The lead does not have to write code; a coordinator that only reads, rules and promotes does fine.
If nobody is marked. Ronin does not stall, and it does not guess. A hand-in still lands on the Team line and tells the Agent that it holds the lead's job for that hand-in. Promotion refuses and asks you to mark a lead on the Team page. An owner can promote anyway on their own word, but the ordinary answer is to mark one.
Station two
The lead does not hand out worktrees one by one. When a coding Agent is launched onto a Team, and the repository has Worktrees switched on and the Agent carries the Worktrees Routine, Ronin opens the worktree before the Agent's first prompt: a private branch in a private folder, cut from your current accepted work. Ronin's own status output calls this a desk; this page says worktree.
Two choices about the starting point are worth knowing. Fresh work starts from your accepted work, the local working branch. An Agent joining a Team already mid-flight can start from the Team's own line instead, so it sees what its teammates have handed in but you have not yet promoted. The Agent can choose; the lead can also make that choice centrally for a named Agent. Either way the hand-in destination is the same: the Team's line.
Falling behind is ordinary. Status says how far behind accepted work a worktree is, and one update merges it in. Twenty commits behind is a notice, never a block.
Where the tools help. The Agent's whole contract is three verbs: get a worktree, update it, hand it in. Its birth reading names them and the commands behind them, so you never have to teach the loop. tejun-desk status answers "where am I" from Git at the moment of asking, never from prose.
Station three
A commit on the worktree is a private checkpoint. It publishes nothing and nobody else sees it, so an Agent commits as often as the work deserves. The birth reading asks for coherent checkpoints and the smallest relevant test at each one, not a full verification run.
A hand-in is the deliberate act of giving committed work to the Team. Ronin builds a throwaway candidate from your current accepted work, then the Team's already-accepted work, then this worktree's commits, and advances the Team line to that candidate only if the merge is clean. Unsaved files are left behind and named. A receipt records what arrived and from whom, the lead is told, and the Agent is told whether its worktree is level with the line. The Team line is a funnel: nobody edits it directly, and a hand-in refuses if someone has.
A hand-in is not verification of the whole repository, and it is not a push. Those belong to later stations.
Where the macros help. Give an Agent +cutcode: with a plan you have agreed and it builds a step at a time in its own worktree, commits privately, and offers a hand-in when a step is whole; it never opens a pull request or merges anything. +tell: carries one line to the lead; +wipeboard: is where the Team says things everyone should see.
When two hand-ins disagree
Two Agents can both change the same lines. The first hand-in lands. The second cannot merge cleanly, so Ronin stops inside the throwaway candidate: the Team line is untouched, the second worktree is marked blocked, the receipt names the files, and the lead is told there is a conflict to rule on.
The lead's job is the decision, not the edit. The lead reads both sides and says which wins, or how they combine, on the Team wipeboard or in the Agent's tile. The Agent then updates its worktree, resolves the files, commits, and hands in again from the same worktree. The line moves only when that second hand-in merges cleanly. Nobody edits the Team line by hand, including the lead.
Station four
Reviewing the Team line and promoting it is the lead's primary job. The line holds every accepted hand-in as one state, with receipts. The lead reads it as a whole, runs the repository's full verification on it, and sends back anything that is not coherent. A correction is an ordinary commit and a second hand-in from the same worktree.
Promotion is one command and one transaction. Ronin builds a candidate from your current working branch plus the Team line, writes a promotion receipt before anything moves, then advances the working branch by compare-and-swap. If another Team promoted a moment earlier, the candidate is simply rebuilt on top. For a repository that drives a live app, promotion also restarts it and checks its health, and a failed health check lands a revert through the same door. For a repository that is only code, those steps are recorded as skipped, and the receipt says so.
When it completes, promotion posts the moved line on the Team wipeboard and tells each Agent whose hand-in rode in, in its own tile, that its work is on the working branch and its worktree may close. After that, every other worktree on the machine sees the new work on its next update.
Where the tools help. The lead runs bin/ronin-promote <team>. A dry run builds the candidate and moves nothing. The same tool resumes an interrupted promotion from its receipt, and lands a revert of a promotion that turned out wrong. One machine-wide lock means two leads never promote at once; the second is told who holds it.
Station five
Accepted is not finished. A hand-in that sits on the Team line is still waiting for the lead, and a correction may come back. The Agent keeps its worktree until promotion tells it, in its tile and on the wipeboard, that the hand-in is on the working branch. Then it closes the worktree, and the next assignment gets a fresh one from current accepted work.
Closing is safe because it refuses. Close removes only a clean worktree whose commits are already on its line; unsaved files or unhanded commits are named and left exactly where they are, never bundled into a commit on your behalf. When a session ends, Ronin's ending check names every worktree it still owns that holds unfinished work, and offers to prompt the Agent to finish or to keep the work in visible custody. The only thing that deletes unfinished work is an explicit discard, which asks for an exact confirmation and writes a receipt naming the commits first.
Where the macros help. +land: writes the work down where it will last, hands in the assignment, closes every worktree whose promotion has reached it, and ends the session. +delete: ends a session without a write-up, but its ending check still names any worktree that holds work.
Station six
Your repository names two branches that count: a local working branch, usually dev, where promotions land, and a stable branch on the remote, usually master or main, which is what you ship. Everything else, Team lines and worktrees and candidates, is on loan and stays on your machine.
The release is one rolling pull request from the working branch to the stable branch. The release step pushes the working branch to the remote and opens that pull request, or updates the one already open; it never opens a second. The pull request body carries the promotion receipt, and your continuous integration verifies that the head commit is the one the receipt names. A pull request without a receipt fails.
Merging is your gate. No Agent merges, no lead merges, and no macro merges. The push that opens the pull request is the only push in this whole journey, and it is a release act, not a hand-in.
Where the tools help. bin/ronin-promote pr <team> is the release action: it reads the repository's declared branches, takes the Team's last complete promotion receipt, pushes the working branch, and opens or updates the pull request. Then it stops and reports the URL.
In short
+cutcode: builds from an agreed plan; +land: finishes up and leaves.+tell: and the wipeboard carry the rulings back.