concord

Worker protocol

Every agent follows the same four commands. After plan, an agent runs everything inside its own workspace and edits files only there; concord knows who it is from that folder.

The steps

  1. Plan before editing anything. concord plan <modifies> <uses>, with comma lists and - for none.
    • modifies: every existing function, type or method whose code you will touch, even if its signature stays the same.
    • uses: existing functions you call whose behavior your code depends on.
    Without a workspace yet, run it from anywhere in the project. It joins you under a free name, or the name from your brief (concord plan <name> <modifies> <uses>), and prints WORKSPACE <name> <path>. Move there and work only there. Running plan again replaces your plan.
  2. One function at a time. Touch no file until claim has printed CLAIMED. For each function in modifies:
    • concord claim <fn> waits for your turn. If another agent changed the function before you, it prints that agent's note after LATEST and has already merged the change into your workspace (MERGED). CONFLICTS <files>: fix the conflict markers in those files first.
    • Edit, run the tests.
    • concord done <fn> "<contract note>" commits your work so far. You never commit yourself.
    Finish one function with done before you claim the next. Holding two claims can deadlock the team.
  3. Finish. concord finish commits leftover work and waits until nobody else holds or queues a function you use.
    • Exit 0, FINISHED: report it. Landing is not your job.
    • Exit 10, NEW CONTRACT CHANGES: functions you use changed, and those changes are already merged into your workspace. Fix any CONFLICTS files, adapt your code to every note, re-run the tests, then run concord finish again.

Waiting and blocked agents

claim and finish wait at most 100 seconds per call, then exit 11 with WAITING for .... Run the same command again. The limit keeps each call inside an agent tool's command timeout (Claude Code kills commands after 2 minutes by default), where a killed wait would look like a failure.

Waiting continues as long as the agents it waits on are alive. When one of them has run no command for 30 minutes, the wait stops with exit 1 and BLOCKED by <agent>. Run concord status; if that agent crashed, concord release <agent>, then retry. A silent agent is reported, never stripped of its claim: editing one function for a long time is normal.

Writing a contract note

The note is all a caller sees. Write the new contract, not the story:

<name>(<params>) -> <return type>: <behavior>; CHANGED: <what callers must do differently>

"Returns a number" is not a contract: a caller cannot tell that the result became a float.

Common mistakes

MistakeEffectInstead
Editing before claim prints CLAIMEDyour edit races another agent's change to the same functionplan, claim, then edit
modifies=- while changing a function's bodynobody queues behind you, so a parallel edit to that function goes unnoticedlist every function whose code you touch
Claiming a second function before done on the firstteam deadlockone claim at a time
Running a worker command outside your workspaceERROR run this inside your workspacecd to the path from WORKSPACE
Treating exit 11 as failureyour turn never comesrun the same command again
Treating exit 10 as failurea caller ships code against a stale contractfix conflicts, adapt, re-test, finish again
Vague note ("updated total")callers miss the changestate the new contract and what CHANGED
An agent crashed while holding a claimagents waiting on it stop after 30 min with BLOCKED by <agent>check concord status, then concord release <agent> and concord add <new-agent> for its task