elizaos--eliza/.github/FLEET.md

Agent Fleet — coordination guide

Canonical rules for every AI agent (and human) working this repo as part of the fleet. Code conventions live in AGENTS.md/CLAUDE.md; the evidence bar lives in CONTRIBUTING.md. This file covers the third thing: how we coordinate — the board, the claims, the lanes, and where each kind of conversation goes.

Where things live

Surface	Used for	Not for
GitHub Project 12 (org board)	Live work state: every card is an issue, columns below	Chat, design debate
Issues	Actionable cards only — one bug/feature/task each, launch-qa labels	Status chatter (that's the Discussion)
Discussions → "Agent Fleet — Coordination HQ" (pinned, General)	Standups, claims visibility, cross-lane questions, incident threads	Anything needing a card (open an issue)
PRs	The work itself + its evidence	Coordination side-talk
.github/FLEET.md (this file)	The rules — PR a change to propose a rule change	—

Long-running "tracking issues" with hundreds of linear comments are deprecated for coordination: threads in the Discussion replace them. Keep tracking issues only as durable logs of a specific push, closed by the owner.

Identity

• Every agent has a lane tag — [qa-agent], [maintainer], [cloud-agent], [core-brain], … — and signs every comment with it.
• One lane tag = one running context. If you inherit a lane, say so in the Discussion before acting in it.

The loop

1. Read first: the Discussion's latest posts + the board. Never start work someone has claimed.
2. Claim: comment CLAIMING: <card> (Discussion thread or the card itself), move the card Todo → Claimed, then In progress when you start.
3. Work to the evidence bar (CONTRIBUTING.md): real end-to-end proof, no mocks, no shortcuts.
4. Deliver: post evidence (PR links, screenshots, logs) on the card, move it to Needs-human-verify. Only the owner (nubs) moves cards to Done or closes the push.
5. Next card immediately. Blocked >30 min → say so where you claimed, move the card back, pick another.

Board columns: Todo → Claimed → In progress → Needs-agent-verify → needs-human-verify → Done(owner-only).

Shared levers — claim before you mutate

Some things exist once. Announce before touching, wait for objections when another lane is active on it, release when done:

• Prod deploys (Workers, Pages) and the develop→main promote
• Staging environment (deploys, env vars, secrets, seeded data)
• The production database (any write — even additive grants get a transparency note with the ledger row id)
• DNS / Cloudflare settings / repo settings & rulesets
• Physical devices (the Seeker phone + its adb) — one installer at a time
• Worker secrets, CI runner capacity

Case study: two agents built + installed on the Seeker in parallel (2026-07-05). Cost: a duplicated build and a mid-air de-conflict. The rule exists so the second agent finds the claim before spending the compute.

Merge & deploy etiquette

• Never self-merge your own PR into a lane that has a reviewer (maintainer shepherds merges). Never solo-merge money, schema, or deploy changes — those need a second lane or the owner.
• Sync before PR: git fetch origin && git rebase origin/develop; a branch that can't fast-forward is not ready. develop history gets rewritten by squash-merges — if rebase replays foreign commits, recover with git checkout -B tmp origin/develop && git cherry-pick <your-commits>.
• Re-verify against current develop before filing or contesting — the tip moves fast; stale findings burn everyone's time.
• Deploy lanes: develop → staging is the default flow; prod rides the main promote (maintainer lane) or an explicitly-claimed out-of-band deploy.
• Live verification uses real flows — real sign-in, real devices, real money paths on staging. Auth injection / fabricated state proves nothing and is banned as evidence.

Using the Discussion HQ (features, not flat chat)

The HQ is #14308 — Agent Fleet Coordination HQ. Use the platform's features — a flat comment stream doesn't scale to a fleet:

• One claim = one thread. Your standup/claim is a top-level comment; every update, question, and hand-off about it goes as a reply under it — not a new top-level post.
• React to ack (👍 seen / 👀 looking / 🚀 shipped) instead of posting "ack"/"+1" comments.
• Don't create new Discussions for coordination — that's how duplicate rooms happen (#14292, locked). Per-topic workstream discussions (e.g. the LifeOps MVP rooms) are for deep design/build threads; fleet-wide standups, claims, and cross-lane asks stay in the HQ, cross-linked.
• Categories: 📣 Announcements = owner directives / GO signals only · 🙏 Q&A = cross-lane questions — mark the resolving reply as the Answer · 🗳️ Polls = fleet decisions · 🙌 Show and tell = shipped demos + evidence.
• Link, don't paste — reference PRs/issues/cards by number so GitHub cross-links them.

Communication hygiene

• Sign everything. Link evidence, not adjectives.
• Read the last hour of the Discussion before posting — don't duplicate.
• New bug found mid-task → new issue (card) + one Discussion line, then keep going. Don't bury findings in comment threads.
• When two lanes collide, the one holding the physical/exclusive lever finishes; the other yields and takes the review. Escalate to the owner only on real deadlock.