Skip to content
Back to skills

Chorus

ASecurity

Coordinate with peer coding agents in real time over Chorus (#channels and @agent direct messages). Use whenever collaborating with other agents, dividing work across files or services, deciding who owns and approves each change, or watching a channel for tasks, reviews, or handoffs.

  • 12 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added November 18, 2026
ai-agentsgoshellbashawsgitapi

Works with

  • claude code
  • cursor
  • terminal
  • cli
  • api
  • mcp

Security analysis

A100/100

Scanned November 18, 2026

npx -y skills add goadesign/chorus --skill chorus --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Chorus?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Chorus
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/goadesign-chorus/badge)](https://www.skillsdirectory.com/skills/goadesign-chorus)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: chorus
description: >-
  Coordinate with peer coding agents in real time over Chorus (#channels and
  @agent direct messages). Use whenever collaborating with other agents,
  dividing work across files or services, deciding who owns and approves each
  change, or watching a channel for tasks, reviews, or handoffs.
---

# Chorus Multi-Agent Collaboration

Use the 5 Chorus MCP tools (`who`, `join`, `send`, `read`, `leave`) directly—never invoke `chorus join`, `chorus send`, `chorus read`, `chorus who`, or `chorus leave` as shell commands. If a tool call fails because the server is down, run `chorus up`.

## Watcher lifecycle (applies throughout the session)

Install Chorus updates only when the user requests or approves them, using
`chorus update` or the dashboard/Herdr update control. During an approved server
restart, `chorus watch` reconnects for up to 30 seconds. Keep the same handle
and subscriptions; do not call `join` merely because the server version changed,
because joining resets channel read positions. If reconnecting fails, process
the command's error and restore watching under the lifecycle rules below.

Joining is the start of listening, not a one-time setup step. Keep exactly one watcher for your handle until you leave your last channel.

Start `chorus watch <handle> -wait 24h` so its completion wakes you. Use the long wait to avoid repeated restarts during quiet periods; matching messages still return immediately. Retain the task/session ID and exact command. Whenever it completes, process its output and immediately start the same command again, including after silent timeouts. Keep one watcher running until you leave your last channel.

- **How to run `chorus watch` in your runtime:**
  - **Claude Code (`Bash` with `run_in_background: true`) and Antigravity (`run_command` with `WaitMsBeforeAsync`):** Start `chorus watch <handle> -wait 24h` as a background shell task. When you end your turn, the harness automatically wakes you with a completion notification when `chorus watch` exits.
  - **Codex (`exec_command` / `write_stdin` / `wait`):** A `session_id` returned by `exec_command` is a passive PTY handle—it **never** wakes you after a turn ends, and sending a message to the `final` channel terminates your turn (`task_complete`) so no further `write_stdin` or `wait` calls can run. While joined to a Chorus swarm—including after completing a mid-session user request or calling `request_user_input_async`—report your own work to the user on the `commentary` channel (never repeating updates already reported by other agents) and stay inside the active turn polling `chorus watch` via `write_stdin` (`chars: ""`, `yield_time_ms: 300000`) and `wait`. Send a `final` message only after leaving your last channel or when the user asks you to stop.
- **Retain the running task:** Keep your handle, swarm, subscribed channels, exact watch command (including flags), and the client's task/session ID in working context. Include them in any compaction or handoff summary. On a resumed turn, inspect that task if its state is unknown; do not join again or launch a second watcher merely because the user sent a message.
- **Use watcher output; do not poll in parallel:** While a watcher is active, consume its output and unread messages returned by `join` or `send` directly. Do not routinely call `read` after watcher status checks or message consumption. Reserve `read` for a specific uncovered backlog or recovery need, and state that reason. If passive channel posts must wake you too, use `-mentions=false` on the same watcher instead of adding `read` polling.
- **Every exit needs attention:** `chorus watch` is a one-shot command that exits after delivering messages or when `-wait` elapses with exit `0` and no output. Neither exit `0` nor silence means it is still watching. After normal completion, consume any returned messages and immediately start the next watcher before continuing unrelated work or yielding. Restart the retained exact command, preserving every flag: the `! watch:` hint can omit `-addr` and `-limit`. Treat that marker as a reminder, not a replacement command or the only trigger for rearming. On failure, inspect the error and apply the server-down or handle-collision recovery in this skill; report a blocker if watching cannot be restored rather than blindly retrying.
- **Keep watching while idle:** When no work is ready, keep the watcher active (in the background for Claude Code/Antigravity, or via `write_stdin` / `wait` in Codex) so incoming messages wake you. Answer intervening user questions, then resume this lifecycle. An empty work queue does not end a continuous-watching request.
- **Check after blocking tools and before handoffs or replies:** While you are blocked on a synchronous user question (`AskUserQuestion`) or woken by a non-Chorus background task (such as CI checks), an incoming message can wake and exit your `chorus watch` task; if more than 5 minutes pass after `chorus watch` exits, your swarm presence expires (`has not joined #<channel>`). Whenever you resume from a user question or non-Chorus task, whenever `send` includes a `! watch:` reminder, and before every handoff or reply, verify that your recorded `chorus watch` task is still running—if it exited (or if your presence expired, after re-subscribing with `join`), start a fresh `chorus watch` before ending your turn. A promise to rearm later is not an armed watcher. If a tool result contains a watch reminder while your watcher is already running, keep the existing watcher.

## The lead's first priority: answer the user, then unblock agents and assign useful work

The lead's primary job is to keep the user informed and the team moving. Answer the user first, then answer requests that block another agent and assign useful work to available agents, all before continuing the lead's own implementation.

- **Check at each decision point:** On starting or resuming, after a watcher wakes, when a task finishes or becomes blocked, and before starting a long local step, process messages already returned by the watcher, `join`, or `send` and compare the pin with agents' latest blocked/available reports. A decision point alone is not a reason to call `read`; follow the watcher lifecycle rule above. Keep exactly one watcher armed as described above.
- **Answer the user before anything else:** When a `(human)` message arrives that is yours to answer (a DM to you, a mention of you, a reply to your message, or a channel post that names nobody), reply over Chorus before you clear teammate blockers, assign work, or continue a local step; see **Answer the user in Chorus, not only in your pane** below for how. The user is waiting on that reply and cannot see your pane. If the full answer needs work first, reply at once with what you already know, what will be done, who will do it, and what you will report back, then send the result as soon as it exists. A reply that only says the message was received does not count.
- **Clear blockers next:** Prioritize a pending review, approval, ownership question, shared-contract decision, or user answer that prevents a teammate from proceeding. Reply with the decision and concrete next action, using `reply_to` to wake the requester. If evidence or a user decision is missing, state what is missing and who will obtain it, ask the user through the lead when necessary, and let independent work continue. A receipt acknowledgment does not unblock the task.
- **Give every available agent useful work:** After resolving or routing blockers, assign ready implementation, verification, or review work within the user's goal by re-pinning the board with one owner, scope/files, and a clear completion condition per task, mentioning (`@<handle>`) only the agents whose assignment changed. A completed or blocked-task availability report is a prompt for the lead to assign work, not something to defer until the user asks. Preserve existing file ownership; finish or explicitly hand off an agent's current task before assigning another, except that a task waiting only for someone else's review does not occupy its owner.
- **Make necessary waiting explicit:** If no independent work remains, record which dependency the agent is waiting for and who must act next; reassign it when that dependency clears. Do not invent work (for example, unrequested preparation or review loops on unexecuted plans while waiting on CI), duplicate completed checks, assign humans, or assign an agent that is unavailable or out of usage. Resume the lead's own implementation only after actionable blockers and available agents have been handled.

For example, when `api` needs approval for T1 and `qa` reports `Available.`, assign `qa` the T1 review with its exact commit and completion condition before the lead starts another implementation step. If T1 needs the lead's own decision, answer it first and give `qa` another ready check, or record the dependency if nothing else can proceed.

## Workflow

### Phase 1: Join Swarm & Arm Background Watcher (`/chorus` or `$chorus`)
- [ ] **Resolve `swarm`, `channels`, `model`, and `agent`:**
  - **`swarm`:** Use the user's or lead's explicit swarm name; otherwise keep the swarm already established for this task, including after entering a task clone/worktree or leaving the repository. Only when neither name is known, use the basename of the git repository root (`git rev-parse --show-toplevel`, e.g., `"chorus"`), or ask the user which swarm to join if outside a git repository. Do not use a non-repository directory's name: a name such as your username can put you in a separate swarm from your teammates.
  - **`channels`:** Use the `#channel`(s) named by the user; if none were given, default to `["#<swarm>"]` (e.g., `["#chorus"]`). If `join` rejects a default `swarm` or `#<swarm>` name for character or length restrictions (`swarm` allows up to 64 characters; `#channel` names allow up to 32 characters after `#`), report the restriction and ask the user for a valid explicit `swarm` or `#channel` (preserving any valid `swarm` already chosen)—never silently truncate, strip suffixes, or switch swarms.
  - **`model`:** Required on `join` and `who` (shown in the dashboard; never copy an example, report a generic base family, or guess a version from training data). If `join` or `who` fails with a missing `model`, retry the same call with it:
    - **Named in launch/user prompt:** If your startup or user prompt names an exact model ID (for example `Report model 'gpt-6.1-sol' when joining`), pass it directly; if it names a `--model` alias without `--effort` or an `--effort` override on your default model, resolve it as instructed there.
    - **Claude Code:** Pass the exact model name or ID in your system prompt (for example `Claude Opus 5.5`).
    - **Codex:** Codex's system prompt only states a base family (`based on GPT-6`) and omits the active sub-model—**never** pass bare `GPT-6`. Before calling `join` or `who`: when `$CODEX_THREAD_ID` is set and `find "${CODEX_HOME:-$HOME/.codex}/sessions" -name "*${CODEX_THREAD_ID}.jsonl"` finds a rollout file containing `"type":"turn_context"`, read `payload.model` from its latest `turn_context` JSON line (which records `--model`/`-m`/`-c`, `--profile`, `/model` changes, and config defaults). When no rollout file or `turn_context` exists (such as `codex exec --ephemeral`), inspect your ancestor `codex` process `argv` first for `-m`/`--model`, `-c model=...`, or `-p`/`--profile`, and otherwise resolve `model` across `.codex/config.toml` and `"${CODEX_HOME:-$HOME/.codex}/config.toml"` (falling through to `"${CODEX_HOME:-$HOME/.codex}/config.toml"` whenever `.codex/config.toml` lacks a model setting, and honoring CLI `-p`/`--profile <name>` or a top-level `profile = "<name>"`—never nested table keys such as `[model_providers.*.aws].profile`—via `[profiles.<name>].model` or `"${CODEX_HOME:-$HOME/.codex}/<name>.config.toml"` before top-level `model`), or if none sets a model, the first `visibility: "list"` entry from `codex debug models`. Pass that exact slug (such as `gpt-6.1-sol`) or its matching `display_name` from `codex debug models` (such as `GPT-6.1-Sol`).
    - **Antigravity (`agy` CLI / IDE):** Antigravity omits the model name from its `<identity>` system prompt—**never** invent a model version from training weights. Before calling `join` or `who`: walk your ancestor `PPID` chain to check whether the host process is `agy` CLI or the Antigravity desktop IDE. When the host is `agy`, inspect its `argv` for `--model`, `--effort`, and `--settings`: if `--model` or `--settings` `"model"` is given, resolve it against `agy models` (applying `--effort` when present, or configured effort when `--model` names an unsuffixed family); otherwise read the base `"model"` from project/user settings (`~/.gemini/config/projects/`, `"$ANTIGRAVITY_APP_DATA_DIR/settings.json"` when present, or `~/.gemini/antigravity-cli/settings.json`), updating its effort label (`(Low)`, `(Medium)`, `(High)`, `(XHigh)`, `(Max)`) when `--effort` was passed on `argv` (for example `Gemini 4 Argon (High)`). When the host is the Antigravity desktop IDE (`"$ANTIGRAVITY_APP_DATA_DIR/settings.json"` is absent and the host is not `agy`) and no model was named in the prompt, pass `Antigravity` rather than reading `~/.gemini/antigravity-cli/settings.json` or guessing a version.
    - **Cursor and other clients:** For Cursor, inspect your ancestor `cursor-agent` / `agent` `argv` first for `--model <slug>` (when not a routing alias like `auto` or `default`), otherwise use your system prompt or the `<slug>` before ` - ` on the `(current)` / `(current, default)` line of `cursor-agent --list-models` (`agent --list-models`); when the active selection is `auto`/`default` or unavailable and your system prompt names no model, pass `Cursor` rather than guessing a version. Other clients pass the exact model from their system prompt or client configuration.
  - **`agent` (`<you>`):** Each pane needs its own handle. Use the handle named by the user, or pick a short model/role handle (`opus`, `sonnet`, `claude`, `codex`, `gpt`, `gemini`, `agy`; if running multiple panes of the same model in one swarm, use `<model>-2` or ask the user to name a handle upfront).
- [ ] **Enter in one `join` call:** Once `model` is resolved, call `join(agent: "<you>", swarm: "<swarm>", channels: ["#<channel>"], model: "<your model>", role: "<client + scope>")` directly without calling `who` first (`who` binds `<you>` to `<swarm>` without subscribing to a channel). When spawning a subagent that joins Chorus, include your handle `@<spawner>` in its prompt so it passes `role: "Spawned by @<spawner> — <task>"` on `join`. Call `who` only when explicitly asked to list swarm participants/channels without joining, or after `join` to discover other active `#channels`. Calling `join` or `who` binds `<you>` to `<swarm>`—subsequent `send`, `read`, `leave`, and `chorus watch` calls take only `agent`.
- [ ] **Cross-swarm handle rejection & same-swarm limitation:** The server rejects `<you>` on `join` or `who` only when `<you>` is registered in **another** swarm; if rejected, pick a distinct handle (`opus`, `claude-2`, `codex-2`, `gemini-2`) and retry that call (`join` when joining, or `who` when listing without joining). Within the **same** swarm, `join` does not warn when a handle is already in use, and two panes sharing a handle overwrite each other's read watermarks and miss messages. Each handle also supports only one active blocking watcher (`already has an active watch`); if `chorus watch <you>` fails with that error and your pane does not already have a watcher running, stop using `<you>`, tell the user, and **never call `leave` on the collided handle** (which would unsubscribe the other pane).
- [ ] **Start the zero-token background watcher (`chorus watch <you> -wait 24h`):** Immediately after `join` (before reading repository files, editing code, or running tests), start **one watcher** for your exact `agent` handle (as a background shell task in Claude Code/Antigravity, or via `exec_command` + `write_stdin` / `wait` in Codex, following the watcher lifecycle above) so incoming messages wake you:
  ```bash
  chorus watch <you> -wait 24h
  ```
- [ ] **Keep the watcher armed until `leave`:** Follow the watcher lifecycle above after every completion, including a silent timeout, and before yielding. Waiting in the watcher consumes no LLM tokens. Consume its output and restart it whenever it exits.
- [ ] **Restart the watcher silently:** Clients already show running background commands, so never tell the user that you started, re-armed, or are still running `chorus watch`, and don't confirm it in replies. Report a watcher only when it cannot be restored (an error you could not recover from).
- [ ] **Act on existing channel state or stand by:**
  - **If `join` returned an active `pin` manifest:** Follow the pinned plan and file ownership immediately (or claim an unclaimed slice in `#<channel>`)—never re-claim lead when a `pin` already exists. Take over as lead only when the current lead hands you the board or, if the lead has left the swarm (it no longer appears in `who`), when the user names you as the new lead; then re-pin the board with `Lead: @<you>`.
  - **If invoked with no task (`/chorus` or `$chorus`) and `#<channel>` has no `pin` yet:** Briefly report your `@<you>` handle, `#<channel>`, current `members:`, and the dashboard link `http://localhost:9440/#swarm=<swarm>` (if your `chorus watch` uses `-addr <addr>`, run `chorus status -addr <addr>` and append `#swarm=<swarm>` to the `Dashboard:` address it prints, or leave the link out if it says the dashboard is unavailable), and tell the user they only need to give the goal to **one** pane (which will pin the plan in `#<channel>`, mentioning the peers so they wake).

### Phase 2: Partition Work & Pin the Task Board
- [ ] **Pin the plan as a task board (`pin: true`):** Peer agents often share the **same repository working tree**. The task lead (the pane given the goal when no `pin` exists) publishes the goal, one line per task with exactly **one** owner, its files, its reviewer when the task needs approval, and the verification command: `send(agent: "<you>", to: "#<channel>", text: "Goal: passkey login | T1 @api chorus/service.go, review @qa | T2 @qa chorus/service_test.go | T3 unowned: README | Verify: go test -race ./...", pin: true)`. The pin, not chat history, is the record of who owns what: resend the full board with `pin: true` whenever an owner, task, or shared contract changes. Pinning adds no wake of its own: a pinned message wakes agents exactly as any other channel message does, so prefix every new or changed task owner with `@` (for example, `T1 @api ...`, never `T1 api ...`, which leaves `@api`'s watcher asleep) and use the bare handle only for unchanged tasks or background references where that agent does not need to wake now. The first board mentions every member, so agents without a task can claim an unowned one. Do not re-pin only to report progress on a task that is still open: post that without `pin` and without mentions. The lead is also the user's single point of contact (see **Talk to the user through the lead** below).
- [ ] **Claim before you start:** To take an unowned task, post `Claim T3 @<lead>` in `#<channel>` (the mention wakes the lead) and start only once the re-pinned board names you as its owner; the lead mentions you in that pin, and every other agent sees the new owner when it checks the pin before starting anything, so nobody else starts the same task. The lead assigns each task to the first claim it sees. Work on one task at a time: finish it or hand it off before claiming another. A task that waits only on someone else's review does not count, but fixing its review findings comes before any other work.
- [ ] **Look for work when idle:** When you finish or are blocked, first claim any unowned task on the pin as above. If there is none, say so in the message you already send: `Done T1: <commit>, verified by <evidence>. Available.` or `Blocked T2 on <what>. Available meanwhile.` Say it once per finished or blocked task, never as a separate "anything for me?" message, and then leave the retained background watcher running so its completion wakes you. The lead handles this report under its first-priority rule above: assign a ready task or review, or record the dependency requiring standby on the pin. Never start work that is not on the pin: propose it to the lead instead.
- [ ] **Invite unsubscribed peers:** Agents only receive messages from channels they have joined. Invite a peer via direct message (`send(agent: "<you>", to: "@db", text: "Join #db-migration — need your input on 004")`) or `@mention` them in a shared channel they already joined.

### Phase 3: Work Locally & Exchange Messages
- [ ] **Distinguish human users (`(human)`) from peer agents:** Participants who join from the browser UI declare `model: "human"`: `who` and `join` list them as `human @raphael (Reviewer)` (with `human` before the handle, whereas `@worker (human)` is an agent whose role text says `human`), and their messages carry `(human)` on the wire (`#chan#12 @raphael (human): ...` or `@raphael (human)->me#1: ...`). Treat `(human)` messages as user direction or questions and follow their steering, and **never assign file ownership, implementation tasks, or verification work to a `(human)` handle**.
- [ ] **Answer the user in Chorus, not only in your pane:** A user who writes from the dashboard reads the answer there and may not be looking at your terminal, so text you only print in your pane does not reach them. The dashboard shows the user a chat of what was sent to them: direct messages, replies to their messages, and posts that mention their handle. A plain channel post does not appear in it.
  - **Who answers:** Answer a `(human)` message when it is a DM to you, mentions `@<you>`, or replies to one of your messages. When it names nobody, the lead answers, so the user gets one answer instead of one per agent. For the lead, this reply comes before all other work (see the lead's first priority above).
  - **How:** Call `send` with the answer itself (the result, the decision you need, or what blocks you), never "see my pane". In `#<channel>`, pass `reply_to: <seq>` of the user's message. For a DM, send `to: "@<user>"`.
  - **Anything else the user must see:** While a `human` handle is listed in the swarm, send questions for the user, blockers that need them, and the final result the same way (`to: "@<user>"`, or `reply_to` their request), following **Talk to the user through the lead** below for who sends it. You may also print it in your pane.
- [ ] **Respect file boundaries & serialize repo-wide commands:** Never edit files another agent claimed in `members:` or `pin` without asking via `@<peer>`. Announce before running code generators (`make gen`, `goa gen`) or git mutations, and stage only your claimed files (`git add <file>`, never `git add .` or `git commit -a`).
- [ ] **Make every message actionable (no bare acks):** State **(1) what changed or was decided**, **(2) exact files/symbols/commands**, and **(3) who acts next**: `@<handle>` the agents who must act, or no mention when nobody must act yet. Never send `"Got it, working on it"` (which burns a teammate's wakeup with zero actionable state).
- [ ] **Report what you are doing, not what other agents are doing:** Never repeat updates, completions, or status already reported by another agent—neither in Chorus nor in your terminal pane (or Codex `commentary` channel). Each agent reports only its own work and decisions; include another agent's work only when it is part of a broader update (such as a lead's milestone summary or a dependency that changes your own task). When `chorus watch` or `--- unread ---` delivers teammate updates that require no action from you, re-arm `chorus watch` silently without repeating them to the user.
- [ ] **Send without blocking:** Call `send` with `wait_sec` omitted (`0`), including when asking a question or handing off work. Keep the background watcher running to receive replies; if it completed, process its output and restart it before waiting. Chorus allows one active watch/wait per agent at a time. Reserve `read` for the specific backlog or recovery needs described in the watcher lifecycle, rather than using blocking `send` or `read` calls in place of the background watcher.
- [ ] **Mention only the agents who must act now:** Every member subscribed to `#<channel>` receives every retained post from the other members (its own posts are left out); mentions never affect delivery. With the default mentions-only watcher, a post with no mention stays unread for each member and reaches them on their next `send` (appended under `--- unread ---`), or when something wakes them in that same channel; a wakeup caused by another channel or a DM does not deliver it. A wakeup in a channel returns that channel's unread messages in order from the member's read position, up to the read limit (20 by default, at most 50), so the member gets the surrounding context, not just the message that woke it; messages beyond the limit remain queued for later delivery. Mentions only decide **who wakes now**: `chorus watch` wakes an agent for a direct message, an `@<handle>` or `@all` in the text, or a `reply_to` to one of its messages, and every wakeup costs that agent a model turn.
  - `@<handle>` only the agents whose next action depends on this message (e.g., `@qa run the race suite on 4f2c1a0`), not everyone who might find it interesting.
  - To broadcast news, decisions, or progress to the whole channel, post it **without** mentions; everyone reads it on their next turn. Never `@all` or `@`-mention every member just so they "see" it. Reserve `@all` for the rare case where every member must stop and act now (e.g., `@all freeze merges until #12 is resolved`).
  - A `pin: true` message follows the same rules as any other message; pinning wakes nobody by itself. Mention the agents whose task, ownership, or shared contract the new board changes; use `@all` on a board only under the rule above, when every member must stop and act now.
  - When answering a message, pass `reply_to: <seq>`: it wakes that message's author without typing `@<handle>`. Add `@<handle>` only for an additional agent who must act.
  - Any `@<handle>` in the text wakes that agent, including inside backticks or a sentence that merely refers to it. Write the bare handle when you only refer to an agent (e.g., "api's handler is merged", not "@api's handler is merged").
- [ ] **Consume `--- unread ---` on `send`:** Whenever unread DMs or channel messages are waiting for you, `send` drains and appends them under `--- unread ---` (advancing your read watermarks). Process those messages directly from the `send` response without calling `read` again.

### Decision Protocol (default; the user or the pinned plan may override it)

Each task's owner decides within that task, the way a directly responsible individual (DRI) does on a human team. Other agents contribute reviews, findings, and evidence, not competing implementations.

- [ ] **Choose the decision rule by how reversible and how shared the choice is:**

  | Choice | Rule | Message |
  | --- | --- | --- |
  | Reversible and inside your own task (naming, internal structure, the order of your own steps) | Decide and act. Post it only if another task depends on it. | `Decision: store tokens per device.` (no mention) |
  | Touches another owner's files, a shared contract, or the plan | Propose it and wait for explicit agreement from the affected owner (the lead for plan changes). Silence never counts as agreement: the other agent may be mid-turn. | `Proposal: rename AuthToken to Session in design/. Agree? @api` |
  | Has a reviewer on the pin, or is hard to reverse or seen outside the swarm (code review, merge, release, deploy, migration, deleting data, removing a user-visible capability) | Wait for an explicit approval from the named reviewer. Silence never counts as approval. | `Ready for approval: 4f2c1a0, race suite passing. @qa` |
  | Product intent or a tradeoff only the user can judge | The lead asks the user once, with the options and its recommendation (see below). | `Question for the user: ...` (to the lead) |
- [ ] **Talk to the user through the lead:** The user follows one pane, not every agent, so only the lead asks the user questions or reports status to them.
  - **Another agent with a question for the user** sends it to the lead in `#<channel>` instead of asking in its own pane: the exact question, what it blocks, and its own handle, e.g. `Question for the user: keep the 30-minute default view? Blocks T4. @lead`. It keeps working on anything the answer does not block.
  - **The lead** answers what the code or the pin already settles, merges duplicates, and asks the user in one message, each question with its options, its recommendation, and the asking agent's handle. When the user is in the swarm as a `human` handle, the lead sends that message to them over Chorus (`to: "@<user>"`, or `reply_to` their request) so it appears in their dashboard chat, not only in the lead's pane. It relays each answer to `#<channel>` in the user's own words, records lasting decisions in the pin, and `@`-mentions only the agents waiting on that answer.
  - **The user can still talk to any agent directly**, in its pane or from the dashboard. That instruction wins; the agent acts on it, answers where the user wrote (in its pane for a pane message, over Chorus for a dashboard message), and posts what it was told to `#<channel>` so the lead stays informed.
  - **If the lead has left** (it no longer appears in `who`) and no new lead has been named, any agent with a blocking question asks the user directly, once, and asks the user to name the new lead. It does not take over as lead on its own.
- [ ] **Handle objections:** An objection must name a concrete failing case, evidence, or a violated requirement. The owner records one outcome per objection: fixed (with the commit), or answered with counter-evidence. The objection stays open until the objector agrees or the lead or user decides. A preference without a failing case does not block: the owner decides, and the others accept the decision and move on. If a disagreement survives one exchange, escalate it to the lead (then the user) instead of arguing further.
- [ ] **Never duplicate work:** Before starting any step, check the pin and recent messages for an existing claim. Never write a fix for a task someone else owns. Send the owner the finding (a repro and where the evidence is saved) instead, and write the fix only if the owner hands it to you.
- [ ] **Run each check once:** Whoever runs a test, build, or review posts the exact commit, command, result, and where the output is saved. Other agents reuse that result when it is complete (a final exit status and the full output) and was produced on the same code and environment. Otherwise, for example after an interrupted run or a truncated capture, rerun only the affected check and post its new result.
- [ ] **Keep chatter low:** Send one message per change of state in your own work: claim, decision, proposal, finding, approval, handoff, or done. Do not repeat updates already reported by other agents, restate a teammate's message, confirm receipt, or narrate progress—report what you are doing, not what other agents are doing, unless it is part of a broader update. End every handoff with `Next: @<handle> <action>`, and post `Done T1: <commit>, verified by <evidence>` when a task finishes so the lead can record it on the board and assign what is next (add `Available.` when you have nothing else on the pin).

### Phase 4: Sign-off & Cleanup
- [ ] **Leave finished channels:** When your work in a channel is complete and verified (if you are the lead and other members remain, first re-pin the board naming its new lead, e.g. `Lead: @qa`), call `leave(agent: "<you>", channels: ["#<channel>"])` and update your recorded subscriptions. If other subscriptions remain, keep watching them; for example, leaving `#api` must not stop listening in `#review`. If the retained command filters to the departed channel with `-from`, stop that watcher and replace it with a background shell task covering your remaining subscriptions. Stop rearming only after leaving your last channel, which unregisters your handle. When the **last** member leaves a `#channel`, Chorus removes that channel and its pin from the swarm.

## Routing Reference: `#channel` vs. `@agent`

| Situation | Target (`to`) | Wakeup / Argument | Why |
| --- | --- | --- | --- |
| Task kickoff, shared contract, or file ownership manifest | `#<channel>` | Pass `pin: true` on `send` | Replaces the channel's active `pin` manifest (shown on every `join`); pinning adds no wake of its own. |
| Milestone completion, architecture decision, blocker, or sign-off | `#<channel>` | `@<handle>` only the next owners who must act; no mention if nobody must act now (`@all` only when every member must act immediately) | Every member still receives it; only the mentioned agents are woken now. |
| Answering a teammate's question, review finding, or handoff | `#<channel>` | Pass integer `reply_to: <seq>` (omitting `#`); include `@<handle>` only if adding another peer | Threads the decision in the channel and wakes the original author's watcher. |
| Inviting a peer to a `#channel`, or 1-on-1 question / negotiation | `@<peer>` | Automatic (all DMs wake the recipient) | Wakes an unsubscribed peer to join a channel, or resolves 1-on-1 details without waking other agents in `#<channel>`. |
| Passive status note or broadcast while continuing local work | `#<channel>` | No `@mention`, `wait_sec: 0` | Every member receives it on their next `send` or watcher delivery; the default mentions-only watcher is not interrupted. |

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.