Why this question matters

When people ask how we manage multiple coding agents in one repository, they often expect a hidden supervisor runtime that decides who exists, who owns what, and when work is really done.

What we actually use is simpler: repo-native scripts, tracked rules, local registry files, mailboxes, and explicit Git boundaries.

That choice is deliberate. We want the coordination layer to stay inspectable in the repository instead of trapped inside one long chat or one opaque orchestration service.

The goal is not only machine action. It is dual readability: agents should be able to execute against these surfaces directly, and humans should still be able to open the same files and understand what is going on.

The main surfaces we rely on

The workflow is built around a few visible surfaces:

  • AGENTS.md and AGENTS-LOCAL.md for shared operating rules
  • .agent-local/agents.json for identity, role, and lifecycle state
  • .agent-local/mailboxes/*.md for durable handoffs
  • .agent-local/agents/<agent_uid>/checklists/ for per-agent execution state
  • scripts/ for the thin tools that update those surfaces

The important point is that a resumed or replacement session can inspect these files and recover enough context to continue safely.

These are shared coordination artifacts, not agent-only internals. A checklist copy is a good example: an agent can mark stable item states, while a human can read the same Markdown file and see what was checked, skipped, or left unresolved.

Bootstrap and identity

The first coordination question is who this agent is and what role it currently holds. We handle that with scripts/agent_bootstrap.py and scripts/agent_registry.py.

Bootstrap is the fast path for claiming a role, recording model metadata, creating checklist copies, and starting the tracked work cycle. The registry owns the durable identity model: stable agent_uid, human-facing display_id, role, scope, mailbox path, and lifecycle state.

That registry is designed to work for both audiences. Agents can parse it as structured state. Humans can inspect it as a repo-local status surface instead of treating the workflow as invisible background magic.

Workcycles instead of vague progress

We do not treat agent work as one endless in-progress blob. We use scripts/agent_work_cycle.py begin and scripts/agent_work_cycle.py end to give each user-command cycle an explicit boundary.

Begin marks the agent active and emits a canonical before-work timestamp. End checks closeout requirements, validates mailbox state, records the after-work timestamp, and refuses a clean finish if important obligations are still missing.

Handoffs that survive interruption

Sessions get compacted, disconnected, or resumed later by someone else. That is why continuation context lives in mailbox files and is usually written with scripts/mailbox_handoff.py.

A good handoff records current state, scope, evidence, next suggested step, and whether the entry is still open, resolved, or superseded. That is much more reliable than assuming another agent can safely continue from chat memory alone.

The same structure helps humans too. A maintainer can read a short handoff and understand where work stands without replaying a whole chat log just to recover intent.

Git safety is part of the workflow

We also use repo-native scripts to keep Git boundaries aligned with actual work ownership. The key tools are scripts/agent_safe_commit.py and scripts/agent_push.py.

The commit helper stages only the allowlisted paths for the work item and adds agent metadata trailers. The push helper lands the specific agent commit instead of pushing a branch by habit. This turns coordination rules into executable guardrails.

Checklists and planning refresh

Not every workflow problem is about current file ownership. Some are about planning drift. For that layer we rely on per-agent checklist copies, scripts/item_id_checklist_mark.py, and scripts/check-plan-refresh.py.

Those tools help us keep tracked rules, execution state, and planning surfaces aligned without editing the tracked source docs directly or guessing whether doc sync is overdue.

This is one of the clearest human-agent dual-use examples. The checklist is agent-usable because scripts can create it, find stable item ids, and mark exact states. It is also human-readable because the output stays plain Markdown instead of disappearing into a special dashboard or hidden runtime console.

The tradeoff

This approach is more explicit than a hidden orchestrator. It asks agents to touch multiple small surfaces, and it makes process more visible.

But it also keeps state inspectable, lets the pieces fail independently, and makes it possible to tighten one primitive without rewriting the whole stack.

Just as importantly, the same files remain useful to both human maintainers and agent sessions. That shared readability is part of the point, not a side effect.

Takeaway

The workflow is not managed by one secret master agent. It is managed by a small repo-native coordination layer: registry for identity, workcycles for lifecycle, mailbox handoffs for continuation, checklist copies that agents can update and humans can read, Git guardrails for ownership, and planning checks for drift.

That stack is less glamorous than agent hype, but it is much closer to what real multi-agent repository work actually needs.