AGENTS.md — parallel merge & deploy coordination for AI agents via Agent Relay

AGENTS.md

AGENTS.md — Merging in parallel via Agent Relay

Many agents work this repo at once, each in its own worktree. Never merge to main yourself. One coordinator owns main and merges everything, one at a time, so parallel merges don't collide, trip branch protection, or stack deploys.

Setup (every agent, on startup)

1. Connect Agent Relay as an MCP server if it isn't already: claude mcp add relay -- npx -y agent-relay mcp (or add a stdio MCP server running npx -y agent-relay mcp). More: https://agentrelay.com/skill.md
2. Join the one shared workspace for this repo. Its key lives at a path every worktree can see:

   KEYFILE="$(git rev-parse --git-common-dir)/relay-workspace"

   • If KEYFILE is missing, you're first — you are the coordinator. Call create_workspace, then write the returned rk_live_... key to KEYFILE. Guard with mkdir "$KEYFILE.lock" first so only one agent creates the workspace.
   • If KEYFILE exists, read it and call set_workspace_key <key>. You are a worker.
3. register_agent, then join_channel #release-lane.

The workspace key is a real server-issued secret — it can't be guessed or derived, which is why the first agent creates it and shares it through the file.

Coordinator (the agent that created the workspace)

You own main. create_channel #release-lane, join_channel, set the topic to lane: FREE. Then watch the channel and handle merge requests one at a time:

• If the branch is behind main, reply rebase onto <sha> and wait for the worker to repost. Help resolve merge conflicts if they're stuck.
• When clean and CI is green, merge it. Optionally batch several ready PRs into one merge + deploy.
• After each merge, post_message main-updated @ <new-sha> and update the topic (lane: BUSY — merging #<pr> / lane: FREE).

Workers (everyone else)

1. join_channel #release-lane.
2. Finish your work, open a PR, wait for CI to pass.
3. post_message a merge request:

   { "type": "merge-request", "pr": 482, "branch": "feat/foo",
     "base_sha": "<main sha you branched from>", "ci": "green" }

4. Do what the coordinator replies: rebase, resolve conflicts, repost. When you see merged @ <sha>, you're done.
5. Whenever you see main-updated @ <sha>, rebase your worktree onto it right away — staying current means a fast merge when your turn comes.

One-time repo setup

• Use the GitHub merge queue instead of "require branches up to date" (avoids serial re-CI on every merge).
• Deploy workflow: concurrency: { group: production, cancel-in-progress: false }.