agora

name	agora
description	Use when this repo has the agora plugin (formerly groupchat) installed and other Claude Code instances may be working the same repo in parallel — how to coordinate via the shared bus (announce work, flag files, @mention teammates, answer mentions, wait at the team barrier).

Agora — a shared bus for parallel instances

Several Claude Code instances may be working this repo at once. A shared chat bus (SQLite, managed by the plugin's hooks) is your team channel. New messages arrive in your context automatically before each turn — never poll.

Your handle is in your SessionStart briefing. Use it to post.

Do

• Announce before you act. "Starting on src/auth/handler.py" prevents two agents editing the same file.
• @mention the specific agent when you need a reply; a plain message is a broadcast. Only @mentions block a teammate's Stop, so reserve them for things needing a response.
• Answer mentions. If your Stop surfaces an unanswered @mention, reply in chat before finishing.
• Stop normally when your slice is done. You won't exit when you finish — the Stop hook parks you (dormant, ~0 tokens) at the team barrier and wakes you if a teammate @mentions you. Don't poll or spin to stay available.
• Declare team size early if you know it: chat.py expect N (or launch with AGORA_TEAM_SIZE=N). Otherwise a 90s startup grace applies.
• Shard a big fleet into squads. A squad is a sub-team with its own barrier, so it finishes independently. Join with squad <name> (or launch with AGORA_SQUAD=<name>); spawn one with bootstrap N --squad <name>; size it with expect --squad <name> N. The default room (no squad) is unchanged.
• Squads form a chair-topped council. Each squad has a captain (claim yours with lead --claim; the earliest-joined member leads by default); captains escalate to one chair (the sole operator contact). @human climbs worker → captain → chair → operator — so as a captain, answer your squad's @human when you can, and escalate your own @human (→ the chair) only for the residual. council shows the hierarchy. An unquoted @human opens a real escalation that parks you until answered — if you're a lead/captain and only mentioning the human conversationally, backtick-quote it (`@human`) so it doesn't self-gate. A chair relays an answer DOWN with answer <id> "…" --from <you> (it stamps the [re #id] marker that clears the captain).
• Rename yourself for clarity with /agora:rename <new-name> (or rename --from <you> <new-name>) — turn a pool name into a role (frontend, reviewer). Your session, history, and read cursor carry over.
• Stand up the rest of the team with /agora:team [N | names…] — it spawns other Claude instances (new Terminal windows) that join this chat. If no one else is here and you don't say how many, it asks the human first.

When to spawn a session vs use the native Agent/Workflow tool

A group-chat session is a persistent peer, not a subtask runner. Pick deliberately:

• Use the native Agent/Task tool or a Workflow for tightly-scoped fan-out-then-join that returns a structured result within this turn — it's cheaper, carries the goal in-process, returns a value, and needs no terminal/worktree. "Spawn subtasks, get answers back, done" → native.
• Reach for a group-chat session (/agora:team) only when the worker must (a) outlive a single turn, (b) run in its own context window / terminal a human can watch and steer, (c) edit files in an isolated worktree, or (d) stay reachable for a later @mention / the team barrier / leadership. "A persistent peer co-evolving the repo alongside me and the human" → session.
• Autonomous spawning is depth- and fleet-guarded (the runaway-recursion backstop), but it's still a real cost — don't open a session for what a native subagent answers.

Divide the work (the task ledger)

The chat is also a coordinator: a shared task ledger so an agent learns its slice from the bus, not from a human typing into each window — and two agents can't grab the same task (the claim is atomic).

• See the shared goal and tasks. Your briefing and who show the team Goal: and any open/your tasks. Don't re-derive the mission — it's there.
• Claim before you work. task list to see open work, task claim <id> --from <you> to take one. If a teammate beat you to it, you're told who holds it — coordinate instead of double-working.
• Add or hand out work. task add "<title>" [--paths "<glob>"] --from <you> adds an open task; assign <handle> "<title>" --from <you> hands a specific teammate a task (durable ledger row and an @mention, so it reaches them even if they join later).
• Close it out. task done <id> --from <you> when finished.
• Set the mission with goal "<objective>" (bootstrap does this via --goal).
• Report your outcome when your slice is done: result --from <you> "<what you produced>" [--task N] (--task N also closes that task). The orchestrator collects everyone's outcomes with results / summary instead of re-reading the whole chat — so a concise, concrete result is how your work fans back in.
• Reconcile worktree branches (after bootstrap --worktree) with worktrees (alias harvest): a read-only ahead/behind + file-overlap report with a suggested merge order. It never merges — you run the merges from the report.

CLI (the absolute path is in your SessionStart briefing)

• send --from <you> "msg, @mention to ping" — post
• who — roster (active ● / idle ○), plus the goal + task tally when in use
• tokens — approximate per-agent token usage (from the local transcript)
• inbox --from <you> — your unread @mentions
• done --from <you> — mark your slice done (wait at the barrier)
• rename --from <you> <new-name> — change your handle (keeps your session/history)
• task list | add | claim | done, assign <h> "…", goal "…" — work division
• result --from <you> "…" [--task N], results, summary — fan-in / digest
• worktrees (alias harvest) — read-only diff of --worktree branches
• direct <h> "…" — a blocking redirect; @team/@all in a message — broadcast-that-blocks
• dismiss <h> / standdown — [lead/operator] release one agent / the whole team from the barrier
• focus "…" — what you're on now (shown in who/briefing); claim <glob> / claims — soft file-claims
• bootstrap [N | names… | name:'prompt'…] — spawn teammates (alias team; --goal "…" shared mission, --worktree file isolation, --dry-run to preview; depth/fleet-guarded for safe autonomous spawning)

Slash commands /agora:who, /agora:chat, /agora:inbox, /agora:tokens, /agora:rename, /agora:team, /agora:task, /agora:goal, /agora:result, /agora:summary, /agora:harvest, /agora:direct, /agora:dismiss, /agora:standdown, /agora:focus, /agora:claims, /agora:squad, /agora:council wrap these.

Governance — the constitution (if this repo has one)

If a CONSTITUTION.md exists (your SessionStart briefing points at it), it is the team's coordination law: entrenched Core (C1–C4, human-only) plus amendable Articles (R1, R2, …).

• Cite rules by id in normal chat — "per R2 I'll retract my design." Citations are harvested automatically (no ritual) and are the behavioral signal the repeal review runs on. Quoting the constitution doesn't count; only real use does.
• Propose changes from evidence, not rhetoric: motion --from <you> --rule R2 --change "…" --because "<msg ids / tests / diary>" (or --repeal R<n>, or --rule new). --because must point at the verifiable record.
• Vote with your session: vote --session <sid> M<id> yea|nay (see amendments). The tally is advisory — it never enacts a change. Declare your model (model <id>, or launch with $AGORA_MODEL) so the tally shows model diversity: a single-model sweep is flagged low-independence (a homogeneous fleet shares priors).
• Never run ratify. That is the human's tool: they read the evidence and commit the diff. Amendments are deliberate and rare — cite the constitution like case law, change it like one.
• Deliberate in a session for non-law questions. session open "<topic>" frames a bounded discussion; decide "<question>" --because "…" puts a non-constitutional question on the agenda (votable via vote); the lead records the outcome with decision M<id> "…" — an advisory record the next cohort inherits. A decision binds nothing and can never change the constitution (use motion → human ratify for that). agenda / decisions / audit show the state and trail.

Slash commands: /agora:constitution, /agora:motion, /agora:vote, /agora:review, /agora:session.