agentainer 0.1.7 → 2.0.0

package/agentainer

@@ -1,22 +1,23 @@
 #!/usr/bin/env bash
 #
-# Agentainer -- launch a configurable swarm of coding agents in tmux.
+# Agentainer -- launch a configurable team of coding agents in tmux.
 #
-#   ./agentainer up                    start every agent in agents.yaml
-#   ./agentainer up -c my-swarm.yaml   ...from a different config
-#   ./agentainer agents.yaml           shorthand for `up -c agents.yaml`
-#   ./agentainer status                see who is running
-#   ./agentainer send --to dev "hi"    message an agent
-#   ./agentainer attach dev            jump into an agent's tmux session
-#   ./agentainer down                  stop everything
+#   ./agentainer up                       start every agent in agentainer.yaml
+#   ./agentainer up -c my-swarm.yaml      ...from a different config
+#   ./agentainer my-swarm.yaml            shorthand for `up -c my-swarm.yaml`
+#   ./agentainer validate                 print the resolved config, launch nothing
+#   ./agentainer status                   see who is running
+#   ./agentainer send --to dev "hi"       mail an agent
+#   ./agentainer attach dev               jump into an agent's tmux session
+#   ./agentainer down                     stop everything
 #
 # See README.md for the full reference, or llms.txt if you are an LLM.
 set -euo pipefail
 
-SWARM_HOME="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-export SWARM_HOME
+AGENTAINER_HOME="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+export AGENTAINER_HOME
 
-PYTHON="${SWARM_PYTHON:-}"
+PYTHON="${AGENTAINER_PYTHON:-}"
 if [[ -z "$PYTHON" ]]; then
   for candidate in python3 python; do
     if command -v "$candidate" >/dev/null 2>&1; then
@@ -27,7 +28,7 @@ if [[ -z "$PYTHON" ]]; then
 fi
 
 if [[ -z "$PYTHON" ]]; then
-  echo "xx Agentainer needs python3 on PATH (or set SWARM_PYTHON)" >&2
+  echo "xx Agentainer needs python3 on PATH (or set AGENTAINER_PYTHON)" >&2
   exit 1
 fi
 
@@ -35,9 +36,6 @@ if ! command -v tmux >/dev/null 2>&1; then
   echo "!! tmux was not found on PATH; every command except 'validate' will fail" >&2
 fi
 
-# The config is resolved in lib/swarm.py: -c, then $SWARM_CONFIG, then
-# ./agents.yaml, then the agents.yaml next to this script. Deliberately NOT
-# exported here -- a stale SWARM_CONFIG would shadow the config that a hook
-# discovers from the agent's working directory.
-
-exec "$PYTHON" "$SWARM_HOME/lib/swarm.py" "$@"
+# The config is resolved in lib/cli.py: -c, then $AGENTAINER_CONFIG, then
+# ./agentainer.yaml, then the agentainer.yaml next to this script.
+exec "$PYTHON" "$AGENTAINER_HOME/lib/cli.py" "$@"

package/agentainer.example.yaml

@@ -0,0 +1,86 @@
+# =============================================================================
+# agentainer.example.yaml — reference configuration for Agentainer v2.
+#
+# Copy it to start your own swarm:
+#
+#     cp agentainer.example.yaml my-swarm.yaml
+#     agentainer up       -c my-swarm.yaml
+#     agentainer status   -c my-swarm.yaml
+#     agentainer send     -c my-swarm.yaml --to orchestrator "Build a CSV->Parquet CLI."
+#     agentainer down     -c my-swarm.yaml
+#
+# This file is FULLY COMMENTED and KEY-FREE: every `command:` runs a tiny
+# `bash` loop instead of a real agent CLI, so the swarm comes up and routes
+# mail with NO API keys and NO model calls. To run real agents, swap each
+# `command` for the actual CLI you installed and drop `capture: none` so turns
+# get detected.
+#
+# The v2 model: agents RECEIVE by reading a file (inbox/) and SEND by writing a
+# file (outbox/<name>/). The orchestrator owns routing, ACL, message IDs,
+# read-state, queueing, retries, and the durable log.
+# =============================================================================
+
+swarm:
+  name: my-swarm                 # any label; shown in `status` / logs
+  root: ./my-swarm-workspace     # disposable working dir; agents get <root>/<name>/ subdirs
+  supervise: true                # run the liveness supervisor (heartbeat) at up
+  supervise_interval_ms: 15000   # how often the supervisor reconciles agents
+  ready_timeout_ms: 30000       # give up waiting for an agent's input prompt after this
+  busy_timeout_ms: 120000       # mark a silent agent idle after this long
+  user_available: false         # the human mailbox starts away (set `agentainer user available`)
+
+# Optional Telegram bridge (off by default). When enabled, the orchestrator
+# mirrors mail to a Telegram chat over HTTPS (stdlib only, no dependency), and a
+# Telegram reply to a mirrored message routes back into the swarm as `user` mail.
+# Create a bot with @BotFather for the token; get your chat id from @userinfobot.
+# It is easiest to set all of this from the UI (`agentainer serve` -> Settings).
+# telegram:
+#   enabled: true
+#   bot_token: "123456:ABC-DEF..."   # keep this secret; it is a credential
+#   chat_id: "123456789"             # the chat/user id to send to & accept replies from
+#   mirror: "*"                      # "*"/all, or a list of agent names to mirror
+#   mirror_user: true                # also mirror mail addressed to you (default true)
+#   mirror_system: false             # mirror system pings/bounces too (default false)
+
+defaults:
+  # capture: how the orchestrator knows a turn finished.
+  #   hook  -> per-type hook/notify (claude Stop hook, codex `notify`)  [default for those types]
+  #   pane  -> poll the tmux pane (gemini / hermes, or any CLI without a hook)
+  #   none  -> no turn detection (mock agents; the agent never "finishes")
+  # `capture: none` is auto-upgraded to `hook` on hook-backed types at load time.
+  capture: none
+  can_talk_to: []                # tightened per agent below
+
+agents:
+  # The orchestrator fans work out to the workers. It may also talk to the human.
+  - name: orchestrator
+    type: claude
+    can_talk_to: [developer, reviewer, user]   # may also talk to the human mailbox
+    # Real agent: command: "claude --dangerously-skip-permissions"
+    command: "claude --dangerously-skip-permissions"
+    role: "You are the orchestrator. Wait for the user's task, then delegate to workers."
+
+  # A worker that can only reply to the orchestrator (enforced by the ACL).
+  - name: developer
+    type: codex
+    can_talk_to: [orchestrator]
+    # Real agent: command: "codex"
+    command: "codex --yolo"
+    role: "You are a developer. Implement what the orchestrator asks."
+
+  # A reviewer that checks the developer's work.
+  - name: reviewer
+    type: claude
+    can_talk_to: [developer]
+    # Real agent: command: "claude"
+    command: "claude --dangerously-skip-permissions"
+    role: "You are a reviewer. Read the developer's output and critique it."
+
+  # An optional idle pinger: every N seconds, if idle, the orchestrator drops a
+  # `system` nudge into this agent's queue (idle-only, no pile-up, min-cadence).
+  # - name: researcher
+  #   type: gemini
+  #   can_talk_to: [orchestrator]
+  #   command: "bash -c 'while true; do read -r l || sleep 1; done'"
+  #   periodically_ping_seconds: 600
+  #   periodically_ping_message: "Any progress to report? Reply, or stay quiet."

package/bin/agentainer.js

@@ -4,14 +4,15 @@
 // npm symlinks this file into a bin directory (e.g. /usr/local/bin/agentainer).
 // Node resolves that symlink before setting __dirname, so __dirname always
 // points at the real bin/ inside the installed package -- which makes the
-// package root, and therefore SWARM_HOME, reliable no matter where npm puts us.
+// package root, and therefore AGENTAINER_HOME, reliable no matter where npm
+// puts us.
 "use strict";
 
 const path = require("path");
 const { spawnSync } = require("child_process");
 
 const PKG_ROOT = path.resolve(__dirname, "..");
-const ENTRY = path.join(PKG_ROOT, "lib", "swarm.py");
+const ENTRY = path.join(PKG_ROOT, "lib", "cli.py");
 
 // `agentainer doctor` re-runs the dependency check without touching Python.
 if (process.argv[2] === "doctor") {
@@ -21,11 +22,11 @@ if (process.argv[2] === "doctor") {
   process.exit(r.status === null ? 1 : r.status);
 }
 
-// Locate a Python interpreter, mirroring ./agentainer (SWARM_PYTHON, then python3,
-// then python).
+// Locate a Python interpreter, mirroring ./agentainer (AGENTAINER_PYTHON, then
+// python3, then python).
 function findPython() {
-  const candidates = process.env.SWARM_PYTHON
-    ? [process.env.SWARM_PYTHON]
+  const candidates = process.env.AGENTAINER_PYTHON
+    ? [process.env.AGENTAINER_PYTHON]
     : ["python3", "python"];
   for (const cand of candidates) {
     const probe = spawnSync(cand, ["--version"], { stdio: "ignore" });
@@ -42,7 +43,7 @@ function has(cmd, args) {
 const python = findPython();
 if (!python) {
   process.stderr.write(
-    "xx Agentainer needs python3 on PATH (or set SWARM_PYTHON).\n" +
+    "xx Agentainer needs python3 on PATH (or set AGENTAINER_PYTHON).\n" +
       "   Run `agentainer doctor` for install hints.\n"
   );
   process.exit(1);
@@ -59,7 +60,7 @@ if (!has("tmux", ["-V"])) {
 
 const result = spawnSync(python, [ENTRY, ...process.argv.slice(2)], {
   stdio: "inherit",
-  env: { ...process.env, SWARM_HOME: PKG_ROOT },
+  env: { ...process.env, AGENTAINER_HOME: PKG_ROOT },
 });
 
 if (result.error) {

package/examples/brainstorm.yaml

@@ -1,147 +1,46 @@
 # =============================================================================
-# Brainstorm -- diverge into many ideas, then converge on a few worth doing.
+# 💡 Brainstorm -- two agents riff on a prompt, each extending the other, with no
+# orchestrator in the middle. A pure ping-pong of ideas via the mail model.
 #
-#   agentainer up -c examples/brainstorm.yaml
-#   agentainer send --to facilitator "Ways to cut our cloud bill by 30%."
+#   cp examples/brainstorm.yaml my-session.yaml
+#   agentainer up   -c my-session.yaml
+#   agentainer send -c my-session.yaml --to a "We need a name for a CLI tool."
+#   agentainer down -c my-session.yaml
 #
-# 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.
+# Shape: A <--> B, two-way, and that's the whole graph. Useful for ideation,
+# rubber-ducking, or adversarial "yes, and..." loops. Either agent may also
+# talk to `user` (the human can drop in).
 #
-#           wildcard   pragmatist   contrarian
-#                \          |          /
-#                 `----- facilitator -----'
-#                             |
-#                        synthesiser
+#   a <----> b
 #
-#     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.
+# Real agents: commands launch the actual CLIs (claude / codex / gemini / hermes). For a key-free demo, swap each `command` for a mock bash loop.
 # =============================================================================
 
 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
+  capture: none
+  can_talk_to: []
 
 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
+  - name: a
     type: claude
+    can_talk_to: [b, user]
     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.
+    role: |
+      You are BRAINSTORMER A. You receive an idea in your inbox/ and extend it
+      -- build on it, add a twist, or sharpen it -- then send your riff back to
+      agent b (write a file into outbox/b/). Keep the energy up; one concrete
+      improvement per message. If the human (user) writes to you, answer them.
 
-      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
+  - name: b
     type: claude
+    can_talk_to: [a, user]
     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.
+    role: |
+      You are BRAINSTORMER B. You receive A's riff in your inbox/ and push it
+      further -- a new angle, a risk, a concrete next step -- then send it back
+      to agent a (write a file into outbox/a/). One concrete improvement per
+      message. If the human (user) writes to you, answer them.

package/examples/bug-hunt.yaml

@@ -1,112 +1,67 @@
 # =============================================================================
-# Bug hunt -- an automatic pipeline: reproduce -> diagnose -> fix -> verify.
+# 🐛 Bug hunt -- one orchestrator fans a bug report out to several hunters who
+# each investigate a different area, then report findings back.
 #
-#   agentainer up -c examples/bug-hunt.yaml
-#   agentainer send --to reproducer "Uploads over 2MB fail with a 500 in prod."
+#   cp examples/bug-hunt.yaml my-hunt.yaml
+#   agentainer up   -c my-hunt.yaml
+#   agentainer send -c my-hunt.yaml --to orchestrator "Intermittent 500s on /api/login."
+#   agentainer down -c my-hunt.yaml
 #
-# This is the one shape where `forward_responses_to` earns its keep: each stage
-# hands its finished turn to the next stage automatically, with no human in the
-# loop. Everything flows one way, so the hop guard never has to save you.
+# Shape: orchestrator is the hub. Hunters never talk to each other (they'd
+# double up or step on each other's fixes); they report only to the orchestrator,
+# who de-duplicates and assigns the fix.
 #
-#   reproducer --> diagnoser --> fixer --> verifier
+#   orchestrator <--> hunter-a, hunter-b, hunter-c   (spokes silent among selves)
 #
-# Auto-forwarding is chatty by nature. If you want agents to speak only when
-# they have something to say, delete `forward_responses_to` and let them call
-# `swarm send` themselves.
+# Real agents: commands launch the actual CLIs (claude / codex / gemini / hermes). For a key-free demo, swap each `command` for a mock bash loop.
 # =============================================================================
 
 swarm:
-  name: bughunt
-  root: ./bughunt
-  session_prefix: "bug-"
+  name: bug-hunt
+  root: ./bug-hunt-workspace
 
-  # A straight line needs exactly as many hops as it has stages.
-  max_forward_hops: 4
+defaults:
+  capture: none
+  can_talk_to: []
 
 agents:
-
-  - name: reproducer
+  - name: orchestrator
+    type: claude
+    can_talk_to: [hunter_a, hunter_b, hunter_c, user]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the HUNT COORDINATOR. You receive a bug report (as mail in your
+      inbox/) and split it into disjoint leads -- one per hunter. Each hunter gets a
+      sharp, independent question and the file/area to focus on. Collect their
+      findings, de-duplicate, and decide who fixes what. Never let two hunters
+      investigate the same thing.
+
+  - name: hunter_a
     type: codex
+    can_talk_to: [orchestrator]
     command: "codex --yolo"
-    can_talk_to: ["diagnoser"]
-    forward_responses_to: ["diagnoser"]
-
-    first_prompt: |
-      You are the REPRODUCER, the first stage of a bug-hunting pipeline.
-
-      Given a bug report, your only job is to turn it into a deterministic,
-      minimal reproduction: a script or test that fails now and would pass if
-      the bug were fixed.
-
-      Report, in this order:
-        1. The exact command to reproduce.
-        2. The observed output, verbatim.
-        3. The expected output.
-        4. What you had to assume, because the report did not say.
-
-      If you cannot reproduce it, say so and explain precisely what you tried.
-      Do not attempt a fix -- the next stage does that. Everything you say at
-      the end of your turn is forwarded automatically to the diagnoser.
-
-  - name: diagnoser
-    type: claude
-    command: "claude --dangerously-skip-permissions --model opus"
-    can_talk_to: ["fixer"]
-    forward_responses_to: ["fixer"]
-
-    first_prompt: |
-      You are the DIAGNOSER, the second stage of a bug-hunting pipeline.
-
-      You receive a reproduction. Find the root cause -- the specific line or
-      design decision that makes the failure inevitable. Not the symptom, and
-      not the first suspicious thing you see.
-
-      Report:
-        1. Root cause, at file:line, in one paragraph.
-        2. The causal chain from input to wrong output.
-        3. Why it was not caught: the missing test, the wrong assumption.
-        4. The smallest correct fix, and one alternative you rejected (say why).
-
-      Do not write the fix. Describe it. Your turn is forwarded to the fixer.
+    role: |
+      You are HUNTER A (backend/logic). When the orchestrator sends you a lead,
+      read the code and reproduce the failure with evidence (the log line, the
+      input, file:line). Report back to the orchestrator: what you found and how
+      confident you are. Do not fix it -- just find it.
 
-  - name: fixer
+  - name: hunter_b
     type: codex
+    can_talk_to: [orchestrator]
     command: "codex --yolo"
-    can_talk_to: ["verifier"]
-    forward_responses_to: ["verifier"]
-
-    first_prompt: |
-      You are the FIXER, the third stage of a bug-hunting pipeline.
-
-      You receive a diagnosis. Implement the smallest change that fixes the root
-      cause, plus a regression test that fails without your change and passes
-      with it.
-
-      Do not refactor surrounding code, rename things, or fix unrelated bugs you
-      notice on the way. Mention them instead.
-
-      Report the diff you made, the test you added, and the test output. Your
-      turn is forwarded to the verifier, who does not trust you.
-
-  - name: verifier
-    type: claude
-    command: "claude --dangerously-skip-permissions"
-
-    # End of the line: it forwards to nobody, so the pipeline stops here.
-    can_talk_to: []
-    append_agents_that_you_can_talk_to_prompt: false
-
-    first_prompt: |
-      You are the VERIFIER, the last stage of a bug-hunting pipeline.
-
-      You receive a proposed fix. Assume it is wrong until you have checked.
-
-      Do all of these:
-        1. Run the original reproduction. Does it now pass?
-        2. Run the whole test suite. Did anything else break?
-        3. Read the fix. Does it address the root cause, or only the symptom
-           that the reproduction happened to exercise?
-        4. Find one input near the boundary of the change that would still
-           break. If you find one, the fix is not done.
-
-      Print a verdict: SHIPPABLE or NOT SHIPPABLE, then the evidence. Be blunt.
+    role: |
+      You are HUNTER B (frontend/UX). When the orchestrator sends you a lead,
+      trace the user-facing path that triggers the bug and capture the exact
+      steps + screenshots/state. Report to the orchestrator with evidence. Do not
+      fix it -- just find it.
+
+  - name: hunter_c
+    type: gemini
+    can_talk_to: [orchestrator]
+    capture: pane
+    command: "gemini --yolo"
+    role: |
+      You are HUNTER C (dependencies/config). Check recent dependency bumps,
+      config changes, and environment drift that could explain the symptom. Report
+      to the orchestrator with evidence. Do not fix it -- just find it.

package/examples/code-review.yaml

@@ -0,0 +1,73 @@
+# =============================================================================
+# 🧐 Code review -- several developers each build a slice and a single REVIEWER
+# checks every one of them. (v1 had a `broadcast` primitive; v2 has no
+# broadcast -- instead the reviewer's `can_talk_to` simply lists all the
+# developers, so it can address each one directly.)
+#
+#   cp examples/code-review.yaml my-repo.yaml
+#   agentainer up   -c my-repo.yaml
+#   agentainer send -c my-repo.yaml --to reviewer "Review the open PRs, report per dev."
+#   agentainer down -c my-repo.yaml
+#
+# Shape: developers never talk to each other; each talks only to the reviewer,
+# who is the hub. This keeps every critique flowing through one consistent
+# reviewer voice instead of N pairwise arguments.
+#
+#   dev-1 \
+#   dev-2  > reviewer (hub)
+#   dev-3 /
+#
+# Key-free: commands are bash loops. Swap for real CLIs to review real code.
+# =============================================================================
+
+swarm:
+  name: code-review
+  root: ./code-review-workspace
+
+defaults:
+  capture: none
+  can_talk_to: []
+
+agents:
+  - name: reviewer
+    type: claude
+    can_talk_to: [dev_1, dev_2, dev_3, user]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the REVIEWER -- the hub. When a developer sends you their work
+      (mail in your inbox/), read it and try to break it: wrong logic,
+      unhandled errors, race conditions, data loss, auth holes. Cite file:line.
+      Send each critique back to the specific developer who wrote it (write a file
+      into outbox/<their-name>/). Never let two developers argue with each other
+      directly -- all feedback goes through you. If the human (user) writes to
+      you, answer them.
+
+  - name: dev_1
+    type: codex
+    can_talk_to: [reviewer]
+    command: "codex --yolo"
+    role: |
+      You are DEVELOPER 1. Build your slice in your own directory. When a unit
+      of work is done, send the reviewer a short summary (write a file into
+      outbox/reviewer/): what changed, why, and what you are unsure about.
+      Ask for review. Act only on the reviewer's feedback.
+
+  - name: dev_2
+    type: codex
+    can_talk_to: [reviewer]
+    command: "codex --yolo"
+    role: |
+      You are DEVELOPER 2. Build your slice in your own directory. When a unit
+      of work is done, send the reviewer a short summary (write a file into
+      outbox/reviewer/): what changed, why, and what you are unsure about.
+      Ask for review. Act only on the reviewer's feedback.
+
+  - name: dev_3
+    type: codex
+    can_talk_to: [reviewer]
+    command: "codex --yolo"
+    role: |
+      You are DEVELOPER 3. Build your slice in your own directory. When a unit
+      of work is done, send the reviewer a short summary (write a file into
+      outbox/reviewer/): what changed, why, and what you are unsure about.
+      Ask for review. Act only on the reviewer's feedback.