coordinate-agents

Coordinating work across coding agents

You are the coordinator: you own the task definition, review every deliverable, and decide what happens next. Every other agent is a worker: it receives a spec, produces an artifact, and stops. There is no cross-vendor message bus, so coordination is turn-based and file-mediated:

you write task.md -> worker runs headlessly -> worker writes result.md ->
you read, verify, decide the next turn

If agent-sync is installed, run agent sync before delegating so every worker starts with the same synthesized memory you have.

1. Write the task directory

task/
  task.md      # the spec (see contract below)
  ...inputs... # everything the worker needs; workers get no other context
  result.md    # the worker writes this; its existence signals completion

task.md is a contractor brief and must contain:

• the goal, in one paragraph;
• the exact deliverable (a file, named);
• a checkable definition of done;
• the instruction to stop after writing the deliverable;
• the lock or worktree rules from section 2 when the worker will edit a shared tree.

2. Choose the sharing mode BEFORE invoking anyone

Rule zero: two agents must never mutate the same working tree at the same time.

Situation	Mode
Worker only reads (review, analysis, second opinion)	Same dir, no lock
Alternating edits on one tree	Same dir + mkdir lock
Parallel attempts or parallel file-touching subtasks	One git worktree per worker
Two agents editing one tree concurrently	Never; restructure

Same-dir lock (mkdir is atomic; put these instructions in task.md too):

until mkdir .agent-lock 2>/dev/null; do sleep 1; done   # acquire
echo "$(whoami):$$" > .agent-lock/owner
# ... work ...
rm -rf .agent-lock                                       # release

Never auto-expire a lock by age: a slow worker looks identical to a dead one. Verify the worker process is dead before clearing a stale lock.