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
- 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.
concord plan <name> <modifies> <uses>), and printsWORKSPACE <name> <path>. Move there and work only there. Runningplanagain replaces your plan. - One function at a time. Touch no file until
claimhas printedCLAIMED. For each function inmodifies:concord claim <fn>waits for your turn. If another agent changed the function before you, it prints that agent's note afterLATESTand 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.
donebefore you claim the next. Holding two claims can deadlock the team. - Finish.
concord finishcommits 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 anyCONFLICTSfiles, adapt your code to every note, re-run the tests, then runconcord finishagain.
- Exit 0,
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>
- Renamed:
subtotal(items) -> int: sum of price*qty; CHANGED: renamed from total - Type change:
subtotal(items, discount_pct=0) -> float; CHANGED: now always float, format before printing
"Returns a number" is not a contract: a caller cannot tell that the result became a float.
Common mistakes
| Mistake | Effect | Instead |
|---|---|---|
Editing before claim prints CLAIMED | your edit races another agent's change to the same function | plan, claim, then edit |
modifies=- while changing a function's body | nobody queues behind you, so a parallel edit to that function goes unnoticed | list every function whose code you touch |
Claiming a second function before done on the first | team deadlock | one claim at a time |
| Running a worker command outside your workspace | ERROR run this inside your workspace | cd to the path from WORKSPACE |
| Treating exit 11 as failure | your turn never comes | run the same command again |
| Treating exit 10 as failure | a caller ships code against a stale contract | fix conflicts, adapt, re-test, finish again |
| Vague note ("updated total") | callers miss the change | state the new contract and what CHANGED |
| An agent crashed while holding a claim | agents 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 |