agentainer 0.1.3 → 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mehmetcanfarsak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,11 +1,81 @@
-# Agentainer
+<!-- Banner -->
+<p align="center">
+  <img alt="Agentainer — multi-agent orchestrator for AI coding agents" src="https://raw.githubusercontent.com/mehmetcanfarsak/AgentSwarm/main/assets/banner.svg" width="820">
+</p>
+
+<!-- Badges -->
+<p align="center">
+  <img alt="license" src="https://img.shields.io/badge/license-MIT-blue.svg">
+  <img alt="zero deps" src="https://img.shields.io/badge/dependencies-zero-brightgreen.svg">
+  <img alt="platform" src="https://img.shields.io/badge/platform-linux%20%2F%20macOS-lightgrey.svg">
+  <img alt="tests" src="https://img.shields.io/badge/tests-48%20checks%20passing-success.svg">
+</p>
+
+<h1 align="center">Agentainer — Multi-Agent Orchestrator for AI Coding Agents</h1>
+
+<p align="center">
+  <strong>A zero-dependency multi-agent orchestrator for AI coding agents.</strong><br>
+  Run a team of <b>Claude Code</b>, <b>OpenAI Codex</b>, <b>Gemini CLI</b>, and <b>Hermes</b> side by side in <b>tmux</b> — each in its own directory, each messaging the others only where your config allows.
+</p>
+
+<p align="center">
+  <em>Formerly <strong>AgentSwarm</strong>. Installed globally the command is <code>agentainer</code>; from a clone, <code>./agentainer</code> in the repo root is identical.</em>
+</p>
+
+**Agentainer** is a lightweight, stdlib-only orchestrator (Python 3 + bash + tmux, no runtime dependencies) that launches multiple AI coding agents — Claude Code, OpenAI Codex, Google's Gemini CLI, and Hermes — in isolated tmux sessions, each with its own working directory, and routes messages between them under a configurable access-control list. Define your whole agent team in a single YAML file; one command brings it online.
+
+<!-- Demo -->
+<p align="center">
+  <img alt="Terminal demo: agentainer up starts four agents, status shows them running, send delivers a task, and logs stream the routed messages" src="https://raw.githubusercontent.com/mehmetcanfarsak/AgentSwarm/main/assets/demo.svg" width="760">
+  <br>
+  <em>Start a four-agent swarm, check status, hand it a task, and watch the messages route — in four commands.</em>
+</p>
 
-Run a team of coding agents — **Claude Code, Codex, Gemini CLI, Hermes** — side by
-side in tmux, each in its own directory, each able to message the others only if
-your YAML file says it may.
+---
+
+## <span id="table-of-contents"></span>Table Of Contents
+
+- [Why Agentainer](#why-agentainer)
+- [How it fits together](#how-it-fits-together)
+- [Requirements](#requirements)
+- [Install](#install)
+- [Quickstart](#quickstart)
+- [FAQ](#faq)
+- [How it works](#how-it-works)
+- [Capturing what an agent says](#capturing-what-an-agent-says)
+- [Subagents, parallel work, and busy agents](#subagents-parallel-work-and-busy-agents)
+- [Configuration reference](#configuration-reference)
+- [Examples](#examples)
+- [Commands](#commands)
+- [Project layout](#project-layout)
+- [Tests](#tests)
+- [Troubleshooting](#troubleshooting)
+- [A note on flags](#a-note-on-flags)
+
+
+## <span id="why-agentainer"></span>✨ Why Agentainer
 
-> Formerly **AgentSwarm**. Installed globally the command is `agentainer`; from a
-> clone, the `./agentainer` script in the repo root is the same thing.
+- **Multi-agent, one command.** Spin up a whole team with `agentainer up` — folders, hooks, tmux sessions, and first prompts, all wired automatically.
+- **Zero runtime dependencies.** Just Python 3 + bash + tmux. No pip installs, no bloated toolchain.
+- **Real ACLs, not vibes.** Agents only message who your YAML `can_talk_to` list permits. `"*"` for everyone, an explicit list for tight graphs.
+- **Survives restarts.** Each turn's conversation id is recorded; `up --resume` reattaches instead of starting cold.
+- **Self-healing routing.** Busy agents queue inbound work, stranded messages get swept, and agents are nudged when a reply reaches nobody.
+- **Any mix of CLIs.** Claude, Codex, Gemini, Hermes — or your own type — in the same swarm.
+
+## <span id="how-it-fits-together"></span>🏗️ How It Fits Together
+
+*Architecture at a glance: a single `agents.yaml` file maps each AI coding agent to its own tmux session and working directory, while Agentainer routes and logs every message between them under a `can_talk_to` access-control list.*
+
+<p align="center">
+  <img alt="Agentainer architecture: one YAML file maps each agent to its own tmux session and working directory; Agentainer routes and logs permission-checked messages between them" src="https://raw.githubusercontent.com/mehmetcanfarsak/AgentSwarm/main/assets/architecture.svg" width="900">
+</p>
+
+One command starts the swarm: it creates a folder per agent, installs a
+completion hook inside each folder, opens a tmux session per agent, launches
+the CLI, and types each agent's first prompt into it.
+
+<details>
+<summary>Plain-text diagram</summary>
 
 ```
    agents.yaml                 tmux
@@ -21,22 +91,20 @@ your YAML file says it may.
    one folder per agent    messages routed + logged
 ```
 
-One command starts the swarm: it creates a folder per agent, installs a
-completion hook inside each folder, opens a tmux session per agent, launches
-the agent's CLI, and types each agent's first prompt into it.
+</details>
 
 ---
 
-## Requirements
+## <span id="requirements"></span>📋 Requirements
 
-- `tmux` (3.0+)
-- `python3` — PyYAML is used if present, otherwise a bundled parser handles the config
-- `node` (16+) — only for the global `agentainer` command; not needed if you run `./agentainer` from a clone
+- **`tmux`** (3.0+)
+- **`python3`** — PyYAML is used if present, otherwise a bundled parser handles the config
+- **`node`** (16+) — only for the global `agentainer` command; not needed if you run `./agentainer` from a clone
 - whichever agent CLIs you reference: `claude`, `codex`, `gemini`, `hermes` — install only the one(s) you actually use
 
-## Install
+## <span id="install"></span>🚀 Install
 
-Global, via npm:
+**Global, via npm:**
 
 ```bash
 npm install -g agentainer
@@ -47,14 +115,14 @@ agentainer doctor        # check tmux/python3 are present; report which agent CL
 which agent CLIs are available — it never fails on a missing *agent* CLI, since
 you may only use one of them.
 
-Or from a clone (no npm needed):
+**Or from a clone (no npm needed):**
 
 ```bash
 git clone https://github.com/mehmetcanfarsak/AgentSwarm.git && cd AgentSwarm
 ./agentainer --help      # same commands as the global `agentainer`, straight from the repo
 ```
 
-## Quickstart
+## <span id="quickstart"></span>⚡ Quickstart
 
 ```bash
 cp agents.example.yaml agents.yaml
@@ -80,9 +148,43 @@ agentainer logs reviewer -n 20  # one agent
 agentainer inbox developer      # messages an agent received
 ```
 
+`agentainer status` gives you the whole swarm at a glance — who is up, who is mid-turn, and how deep each queue is:
+
+<p align="center">
+  <img alt="agentainer status output: a table of agents with their type, state, turn, queue depth, capture mode, and can_talk_to permissions" src="https://raw.githubusercontent.com/mehmetcanfarsak/AgentSwarm/main/assets/screenshot-status.svg" width="820">
+</p>
+
+---
+
+## <span id="faq"></span>❓ FAQ
+
+**What is Agentainer?**
+Agentainer is a zero-dependency multi-agent orchestrator that runs a team of AI coding agents — Claude Code, OpenAI Codex, Google's Gemini CLI, and Hermes — in isolated tmux sessions, each with its own working directory, and routes messages between them under a configurable access-control list. You describe the whole team in one YAML file and start it with a single command.
+
+**Which AI coding agents does Agentainer support?**
+Claude Code (`claude`), OpenAI Codex (`codex`), Google's Gemini CLI (`gemini`), and Hermes (`hermes`) out of the box. You can also define your own agent type via `agent_types:` — any CLI that takes input on stdin/tty works, with `capture: pane` or `capture: none`.
+
+**Does Agentainer need Docker or any runtime dependencies?**
+No. It is stdlib-only: Python 3, bash, and tmux. PyYAML is used if present, but a bundled parser handles the config without it. Node is only needed for the global `npm` launcher — running `./agentainer` from a clone needs no Node at all.
+
+**How do I run multiple coding agents together?**
+Write a YAML config listing your agents (and who may talk to whom), then run `agentainer up`. It creates a folder and a tmux session per agent, installs a turn-completion hook, launches each CLI, and types in the first prompt. `agentainer send --to <agent> "…"` messages any agent; `agentainer validate` previews the resolved swarm without launching anything.
+
+**Can agents communicate with each other, and how is that controlled?**
+Yes. Agents exchange tagged `<swarm-message>` / `<swarm-send>` blocks. Messaging is a whitelist: an agent may only reach the agents in its `can_talk_to` list (`"*"` means everyone else); anything else is refused. Auto-forwarding (`forward_responses_to`) can relay finished turns hands-free, bounded by a hop count to prevent loops.
+
+**How do I resume a swarm after a crash or reboot?**
+Each finished turn records the agent's conversation id in `.swarm/sessions.yaml`. `agentainer up --resume` reattaches every agent to its own conversation instead of starting cold, keeping any queued mail. Claude resumes with `--resume <id>`, Codex with `resume <id>`; Gemini and Hermes have no recoverable session id and always start fresh (with a warning).
+
+**Is it safe to let agents run unattended?**
+Agents run with whatever privileges their CLI is launched with. Flags like `claude --dangerously-skip-permissions`, `codex --yolo`, and `gemini --yolo` let them act without confirmation, which is usually what you want for an unattended swarm — so point `root` at a disposable directory and never run a swarm over a checkout you can't afford to lose.
+
+**How is Agentainer different from just opening several terminals?**
+It automates the brittle parts: detecting when each turn finishes (via a Stop/notify hook for Claude/Codex, or pane polling for Gemini/Hermes), typing multi-line prompts reliably into a live TUI, pre-trusting folders so the "trust this directory?" modal doesn't eat the first prompt, enforcing the comms ACL, queueing messages to busy agents, and resuming conversations after a restart.
+
 ---
 
-## How it works
+## <span id="how-it-works"></span>🔧 How It Works
 
 **One folder + one tmux session per agent.** Agent `developer` gets
 `workspace/developer/` and a tmux session named `developer` (plus any
@@ -121,9 +223,8 @@ agents:
   checkout), but agents then overwrite each other's files and interleave commits,
   so `validate` and `up` warn when it happens. See
   [`examples/existing-repo.yaml`](examples/existing-repo.yaml).
-
-`root` is still used even when every agent lives elsewhere: it holds `.swarm/`
-with the logs, inboxes and the `swarm` shim.
+- `root` is still used even when every agent lives elsewhere: it holds `.swarm/`
+  with the logs, inboxes and the `swarm` shim.
 
 **Prompts are typed in, not piped.** `swarm up` drops each first prompt into the
 agent's input box with a tmux bracketed paste, as one block, then presses Enter.
@@ -260,7 +361,7 @@ agent sees on its own terminal. Use `can_talk_to: "*"` for "everyone else".
 
 ---
 
-## Capturing what an agent says
+## <span id="capturing-what-an-agent-says"></span>🎬 Capturing What An Agent Says
 
 Agentainer needs to know when an agent finishes a turn — both to log it and to
 support auto-forwarding. How it finds out depends on the CLI, and the two
@@ -293,7 +394,7 @@ mechanisms are **not** equally good:
 
 Set `capture:` per agent to override the default for its type.
 
-### Subagents, parallel work, and busy agents
+### <span id="subagents-parallel-work-and-busy-agents"></span>🧩 Subagents, parallel work, and busy agents
 
 Coding agents spawn subagents and background tasks. Four things follow from that.
 
@@ -408,7 +509,7 @@ speak, and leave `forward_responses_to` unset.
 
 ---
 
-## Configuration reference
+## <span id="configuration-reference"></span>⚙️ Configuration Reference
 
 Full annotated example: [`agents.example.yaml`](agents.example.yaml).
 Machine-readable summary for agents: [`llms.txt`](llms.txt).
@@ -485,7 +586,7 @@ placeholders.
 
 ---
 
-## Examples
+## <span id="examples"></span>🧪 Examples
 
 Ready-to-run swarms in [`examples/`](examples/):
 
@@ -495,6 +596,16 @@ Ready-to-run swarms in [`examples/`](examples/):
 | [`software-company.yaml`](examples/software-company.yaml) | Org chart | Six agents across all four CLIs, with a deliberately restricted comms graph |
 | [`bug-hunt.yaml`](examples/bug-hunt.yaml) | Pipeline | `forward_responses_to` chaining reproduce → diagnose → fix → verify, hands-free |
 | [`existing-repo.yaml`](examples/existing-repo.yaml) | Pairing | Two agents in one **existing** checkout, with `create_workdirs: false` |
+| [`red-team.yaml`](examples/red-team.yaml) | Adversarial triad | Attacker vs defender arbitrated by a referee, over one **existing** checkout |
+| [`debate.yaml`](examples/debate.yaml) | Debate + judge | Two advocates argue opposite sides; a judge cross-examines and rules |
+| [`writers-room.yaml`](examples/writers-room.yaml) | Hub + review cycle | An editor driving a writer, fact-checker and critic to a finished article |
+| [`incident-response.yaml`](examples/incident-response.yaml) | Incident hub | A commander coordinating investigator/responder/scribe under time pressure |
+| [`tdd-pingpong.yaml`](examples/tdd-pingpong.yaml) | Tight 2-agent loop | Tester writes one failing test, coder makes it pass, in one shared repo |
+| [`brainstorm.yaml`](examples/brainstorm.yaml) | Diverge + converge | Three angled idea-generators fanning out, then a synthesiser ranks them |
+| [`localization.yaml`](examples/localization.yaml) | Pipeline | Translate → review → back-check, auto-forwarded via `forward_responses_to` |
+| [`multi-language-broadcast.yaml`](examples/multi-language-broadcast.yaml) | Broadcast fan-out | One translator broadcasts a source to N language reviewers; a consolidator compiles and broadcasts back |
+| [`code-review-broadcast.yaml`](examples/code-review-broadcast.yaml) | Broadcast hub | One PR broadcast to specialist reviewers (correctness/security/perf); each replies to the coordinator who synthesizes |
+| [`ping-pong.yaml`](examples/ping-pong.yaml) | Round-robin | Two agents trade a unit of work, each broadcast naming who is up next (distinct from tdd-pingpong's fixed `forward_responses_to`) |
 
 ```bash
 agentainer validate -c examples/research-swarm.yaml   # look before you leap
@@ -505,7 +616,7 @@ agentainer send --to lead "Research the state of WebGPU compute shaders."
 `existing-repo.yaml` intentionally refuses to start until you point `workdir` at
 a repository that exists.
 
-## Commands
+## <span id="commands"></span>💻 Commands
 
 | Command | Purpose |
 |---|---|
@@ -526,7 +637,7 @@ a repository that exists.
 `agentainer my-swarm.yaml` is shorthand for `agentainer up -c my-swarm.yaml`.
 `-c` and `$SWARM_CONFIG` both select a config; `-c` wins.
 
-## Layout
+## <span id="project-layout"></span>📁 Project Layout
 
 ```
 AgentSwarm/
@@ -541,19 +652,19 @@ AgentSwarm/
 │   ├── config.py           # schema, defaults, validation
 │   └── minyaml.py          # YAML subset parser, used when PyYAML is absent
 ├── tests/validate.sh       # full suite: mock agents, no model calls
-├── examples/               # research swarm, software company, bug hunt, pairing
+├── examples/               # research, software company, bug hunt, pairing, red team, debate, writers' room, incident, tdd, brainstorm, l10n, multi-language + code-review (broadcast), ping-pong (round-robin)
 └── workspace/              # created by `up`
     ├── <agent>/            # one folder per agent
     └── .swarm/
         ├── state.json      # what `up` started
-    ├── sessions.yaml   # each agent's conversation id, for `up --resume`
+        ├── sessions.yaml   # each agent's conversation id, for `up --resume`
         ├── bin/swarm       # the `swarm` command agents call
         ├── logs/           # <agent>.jsonl + swarm.jsonl
         ├── inbox/<agent>/  # archived messages
         └── run/            # watcher pids, hop counters
 ```
 
-## Tests
+## <span id="tests"></span>✅ Tests
 
 ```bash
 tests/validate.sh
@@ -565,7 +676,7 @@ nothing. It covers the awkward cases: the check-and-set race between concurrent
 senders, a queued message beating a reply reminder, a subagent's sidechain turn
 being skipped, and a transcript read before Claude has flushed it.
 
-## Troubleshooting
+## <span id="troubleshooting"></span>🛠️ Troubleshooting
 
 **"could not confirm the text arrived; NOT pressing Enter".** The agent's input
 box never echoed the prompt, so Agentainer refused to submit it. Attach to the
@@ -585,7 +696,7 @@ other. Raise `max_forward_hops`, or break the cycle in `forward_responses_to`.
 **Nothing captured from a claude agent.** Check `<agent-dir>/.claude/settings.json`
 exists and `.swarm/logs/hooks.log` for errors. If the agent also looks busy forever,
 its `type` probably does not match the CLI its `command` runs (see the capture note
-under [Busy agents](#busy-agents-and-backpressure)).
+under [Busy agents](#subagents-parallel-work-and-busy-agents)).
 
 **Can't scroll up in an attached session.** Agentainer raises tmux's scrollback to
 `tmux_history_limit` (50000 lines) and turns on `tmux_mouse`, so the wheel scrolls
@@ -594,10 +705,22 @@ use `Ctrl-b [` then PageUp. Both options are set on the tmux server before sessi
 are created, so a server that was already running keeps its old panes' smaller
 buffer — restart the swarm (or that pane) to pick up the larger one.
 
-## A note on flags
+## <span id="a-note-on-flags"></span>⚠️ A Note On Flags
 
 `claude --dangerously-skip-permissions`, `codex --yolo` and `gemini --yolo` let
 agents act without asking for confirmation. That is usually what you want for an
 unattended swarm, and it means several models are running tools unsupervised in
 these directories. Point `root` somewhere disposable, and don't run a swarm over
 a directory you can't afford to lose.
+
+---
+
+## 🤝 Contributing
+
+Pull requests and issues are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for
+the zero-dependency principles, a key-free smoke test, and the PR checklist. A
+safe first run with no API keys lives in [quickstart.yaml](quickstart.yaml).
+
+## 📜 License
+
+Released under the [MIT License](LICENSE).

package/examples/brainstorm.yaml

@@ -0,0 +1,147 @@
+# =============================================================================
+# Brainstorm -- diverge into many ideas, then converge on a few worth doing.
+#
+#   agentainer up -c examples/brainstorm.yaml
+#   agentainer send --to facilitator "Ways to cut our cloud bill by 30%."
+#
+# Shape: fan-out then funnel. A FACILITATOR poses the prompt to three idea
+# generators who each riff from a different angle and never see each other's
+# lists (so they don't converge too early), then hands the pile to a SYNTHESISER
+# who clusters, de-dupes and ranks. The generators talk only to the facilitator.
+#
+#           wildcard   pragmatist   contrarian
+#                \          |          /
+#                 `----- facilitator -----'
+#                             |
+#                        synthesiser
+#
+#     Every link is two-way (the facilitator prompts each generator and they
+#     answer back). Ideas diverge across the three generators, then converge
+#     through the facilitator to the synthesiser.
+#
+# Deliberately divergent roles keep the three from producing the same list three
+# times. This swarm creates its own folders under `root` -- no repo needed.
+# =============================================================================
+
+swarm:
+  name: brainstorm
+  root: ./brainstorm-workspace
+  session_prefix: "bs-"
+
+  # Fan-out then one funnel step: a single hop is enough.
+  max_forward_hops: 1
+
+defaults:
+  type: claude
+
+agents:
+
+  - name: facilitator
+    type: claude
+    command: "claude --dangerously-skip-permissions --model opus"
+    can_talk_to: ["wildcard", "pragmatist", "contrarian", "synthesiser"]
+
+    # Waits for the human to supply the actual prompt.
+    in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt: true
+
+    first_prompt: |
+      You are the FACILITATOR. You run a divergent-then-convergent session.
+
+      You do not generate ideas or judge them yourself. You frame the prompt,
+      keep the three generators pulling in different directions, then hand the
+      raw pile to the synthesiser and relay the result.
+
+      Your room:
+        - wildcard:   unconstrained, ambitious, "what if budget were no object"
+        - pragmatist: ships this quarter with what we already have
+        - contrarian: attacks the framing and the obvious answers
+        - synthesiser: clusters, de-dupes and ranks everything at the end
+
+      How to run it:
+        1. Sharpen the human's prompt into one clear question with a success
+           metric. Send it to all three generators, and tell each to lean fully
+           into ITS angle -- no self-censoring, no converging yet.
+        2. Do NOT show generators each other's ideas mid-round; that collapses
+           the diversity you are paying for.
+        3. When all three have reported, forward the combined, unedited list to
+           the synthesiser.
+        4. Relay the synthesiser's ranked shortlist to the human, with the one
+           bold idea and the one safe idea called out.
+
+      In the diverge phase, quantity and range beat quality. Save judgement for
+      the synthesiser.
+
+  - name: wildcard
+    type: claude
+    command: "claude --dangerously-skip-permissions"
+    can_talk_to: ["facilitator"]
+
+    first_prompt: |
+      You are the WILDCARD. Your job is range and ambition, not feasibility.
+
+      Given the question, produce 8-12 genuinely different ideas, including ones
+      that sound expensive, weird, or premature. Assume constraints can be
+      renegotiated. Chase the idea that would matter most if it worked.
+
+      For each: a one-line pitch and the single reason it could be a big deal.
+      Do not filter for practicality -- the pragmatist and synthesiser do that.
+      Avoid the obvious answer everyone already thought of; go past it.
+
+  - name: pragmatist
+    type: codex
+    command: "codex --yolo"
+    can_talk_to: ["facilitator"]
+
+    first_prompt: |
+      You are the PRAGMATIST. Your job is ideas that ship soon, cheaply.
+
+      Given the question, produce 8-12 ideas that a small team could start this
+      quarter with tools it already has. Favour reversible, low-risk moves with a
+      clear owner and a visible payoff.
+
+      For each: a one-line pitch, the rough effort, and the expected payoff. Bias
+      toward things measurable within a few weeks. Leave the moonshots to the
+      wildcard; you own "what can we actually do on Monday".
+
+  - name: contrarian
+    type: claude
+    command: "claude --dangerously-skip-permissions"
+    can_talk_to: ["facilitator"]
+
+    first_prompt: |
+      You are the CONTRARIAN. You attack the question and the easy answers.
+
+      First, challenge the framing: is the stated goal the real goal? Is the
+      metric measuring the right thing? Name the assumption everyone is making.
+
+      Then produce 6-10 ideas that come from rejecting the obvious approach:
+      do the opposite, remove the thing instead of optimising it, or solve the
+      problem one level up so it disappears.
+
+      For each: the conventional answer you are rejecting, and your alternative.
+      Be provocative but honest -- the goal is better options, not just dissent.
+
+  - name: synthesiser
+    type: claude
+    command: "claude --dangerously-skip-permissions"
+    can_talk_to: ["facilitator"]
+
+    # The shortlist lands somewhere predictable.
+    workdir: ./brainstorm-output
+
+    first_prompt: |
+      You are the SYNTHESISER. You turn a messy pile of ideas into a decision.
+
+      You receive every idea from all three generators. Write the result to
+      SHORTLIST.md.
+
+      Do this:
+        1. Cluster near-duplicates into single themes; note where two angles
+           independently converged (that is a signal).
+        2. Score each theme on impact vs effort. Be explicit about the criteria.
+        3. Produce a ranked shortlist of 3-5 things worth doing, each with why it
+           made the cut and the first concrete step.
+        4. Call out the single boldest bet and the single safest quick win, and
+           name any idea that is a trap (looks great, fails in practice).
+
+      Do not just list everything back. The value you add is cutting.

package/examples/code-review-broadcast.yaml

@@ -0,0 +1,109 @@
+# =============================================================================
+# Code review by broadcast -- one PR, several specialist lenses at once.
+#
+#   1. agentainer validate -c examples/code-review-broadcast.yaml
+#   2. agentainer up       -c examples/code-review-broadcast.yaml
+#   3. agentainer send --to coordinator "Review PR #42 (git diff main...HEAD)."
+#
+# Shape: a hub built on `broadcast`. The COORDINATOR fans the diff out to
+# every reviewer in one message; each REVIEWER owns one concern (correctness,
+# security, performance) and reports back to the coordinator, who synthesizes a
+# single review. The reviewers never talk to each other -- cross-cutting findings
+# are the coordinator's job to merge.
+#
+#        coordinator
+#            |  (broadcast the PR to all)
+#            v
+#     +-------+--------+
+#     |       |        |
+#  correctness security  perf
+#     |       |        |
+#     +--- coordinator ---+   (each reviewer replies to the coordinator)
+#
+# `broadcast` is the point of the example: the coordinator reaches several
+# peers with one message and does not care which are mid-task. Every link is
+# two-way. The change under review is passed in the prompt, so the swarm
+# validates and runs without pointing at any repo.
+# =============================================================================
+
+swarm:
+  name: review
+  root: ./review-runtime        # only holds logs, inboxes and swarm state
+  session_prefix: "rv-"
+
+  # Broadcasts don't auto-forward, so one hop is all the guard ever needs.
+  max_forward_hops: 1
+
+  # Each agent gets its own scratch folder under `root` for logs and state.
+  # The change under review is passed in the prompt (a `git diff`), so the agents
+  # never need to read a repo off disk -- point `workdir` here only if you want
+  # them to read the tree directly.
+  create_workdirs: true
+
+agents:
+
+  - name: coordinator
+    type: claude
+    command: "claude --dangerously-skip-permissions --model opus"
+    can_talk_to: ["correctness", "security", "perf"]
+
+    in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt: true
+
+    first_prompt: |
+      You are the REVIEW COORDINATOR. You do not review code yourself; you run
+      the review and merge the findings.
+
+      When the human gives you a change (a PR or a `git diff`), broadcast it to
+      every reviewer at once, each with the one concern they own:
+
+          <swarm-broadcast>
+          Review this change (PR #42, git diff main...HEAD):
+            - correctness: does it do what it claims? logic, edge cases, regressions
+            - security:    injection, authz, secrets, unsafe deserialization
+            - perf:        hot paths, N+1s, allocations, unbounded growth
+          Reply to me (the coordinator) with findings only for your lane.
+          </swarm-broadcast>
+
+      Collect the three replies. Merge overlapping findings, dedupe, and rank by
+      severity. Produce ONE consolidated review: a short verdict (Approve / Request
+      changes) followed by a bullet list of findings with file:line and the lane
+      that raised each. Do not invent findings the reviewers did not make.
+
+  - name: correctness
+    type: claude
+    command: "claude --dangerously-skip-permissions"
+    can_talk_to: ["coordinator"]
+    first_prompt: |
+      You are the CORRECTNESS reviewer. You receive a change broadcast by the
+      coordinator; review ONLY whether it does what it claims.
+
+      Look for: logic errors, off-by-one and boundary mistakes, wrong types or
+      null handling, missing or wrong edge-case handling, and silent regressions
+      in behaviour. Quote the offending line. When done, reply to the coordinator
+      with findings for this lane only -- nothing about security or performance.
+
+  - name: security
+    type: claude
+    command: "claude --dangerously-skip-permissions"
+    can_talk_to: ["coordinator"]
+    first_prompt: |
+      You are the SECURITY reviewer. You receive a change broadcast by the
+      coordinator; review ONLY for security risk.
+
+      Look for: injection (SQL/command/HTML), broken or missing authz, secrets
+      committed or logged, unsafe deserialization, path traversal, and trust of
+      unvalidated input. Quote the offending line and the abuse scenario. When done,
+      reply to the coordinator with findings for this lane only.
+
+  - name: perf
+    type: codex
+    command: "codex --yolo"
+    can_talk_to: ["coordinator"]
+    first_prompt: |
+      You are the PERFORMANCE reviewer. You receive a change broadcast by the
+      coordinator; review ONLY for performance.
+
+      Look for: accidental O(n^2) or N+1 patterns, allocations in hot loops,
+      unbounded growth (caches, lists), missing batching or indexes, and blocking
+      calls on the request path. Quote the offending line and the expected cost.
+      When done, reply to the coordinator with findings for this lane only.