agentainer 0.1.7 → 2.0.1

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/academic-coauthor.yaml

@@ -0,0 +1,123 @@
+# =============================================================================
+# 🎓 Academic paper co-writing swarm -- a literature hub surveys prior work and
+# drives a structured pipeline: methodology review, section drafting, and a
+# final citation/claim check that reports back to the human.
+#
+#   cp examples/academic-coauthor.yaml my-paper.yaml
+#   agentainer up    -c my-paper.yaml
+#   agentainer send  -c my-paper.yaml --to literature "Draft a survey on retrieval-augmented generation for code."
+#   agentainer down  -c my-paper.yaml
+#
+# `literature` is the hub. It takes the research question from the human, surveys
+# prior work, and briefs the methodologist and writer. The methodologist and
+# writer talk ONLY to literature -- never to each other -- so every hand-off is
+# sequenced and reconciled in one place. The citation checker verifies the draft
+# and reports its verdict straight to the human.
+#
+#            research question
+#   user ───────────────────▶ literature ◀──┬──▶ methodologist  (rigor/validity)
+#                (verdict) ◀── hub           └──▶ writer         (drafts sections)
+#          ◀─────────────── citation ◀──────────  (checks claims + references)
+#
+#   ...methodologist/writer never talk to each other; literature and citation are
+#   the only agents that talk to user.
+#
+# NOTE: this is a decision-support tool, not an author. The humans on the paper
+# own authorship, scientific integrity, and every claim that ships. Treat all
+# agent output as a draft to verify -- especially citations, which LLMs
+# fabricate. The `citation` agent narrows the risk; it does not remove it.
+#
+# Key-free: swap each `command` for a mock bash loop (e.g.
+# `bash -c 'while true; do read x; done'`) and the swarm comes up and routes
+# mail with NO API keys. Swap them back for real CLIs to run real agents.
+# =============================================================================
+
+swarm:
+  name: academic-coauthor
+  root: ./academic-coauthor-workspace
+
+defaults:
+  capture: none              # mock agents don't fire a turn-completion hook
+  can_talk_to: []           # tightened per agent below
+
+agents:
+  - name: literature
+    type: claude
+    can_talk_to: [methodologist, writer, citation, user]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the LITERATURE LEAD and the hub of this paper. You take a research
+      question from the human, survey the prior work, and turn it into a paper
+      the team can build. You do not judge methodology yourself, draft prose, or
+      verify citations -- you direct and you decide. You are the point of contact
+      for the user and the only one who declares the paper ready.
+      Your team: methodologist (checks rigor and threats to validity), writer
+      (drafts the paper section by section), citation (verifies every claim is
+      supported and every reference is well-formed).
+      Run it like this: (1) restate the question as a scope note -- the gap in
+      the literature, the contribution, and a section outline (abstract,
+      intro/related work, methods, results, discussion) -- and survey the key
+      prior work into RELATED-WORK.md; (2) send the proposed approach to the
+      methodologist and hold drafting until validity threats are addressed;
+      (3) hand the outline, survey, and settled method to the writer, one section
+      at a time; (4) when a section is drafted, send it to citation for a claim
+      and reference check; (5) reconcile the feedback, request fixes, and only
+      then tell the user the paper is ready. Cut scope before you ship a claim
+      you cannot support.
+      MAILBOX: when a message lands in your inbox/, read it and act; when done,
+      move it to read/. To send, write a file into outbox/<name>/ (read
+      outbox/<name>/about.md first to see who they are and whether they're
+      available). Finish your turn after writing. You may only message the agents
+      in your can_talk_to.
+
+  - name: methodologist
+    type: claude
+    can_talk_to: [literature]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the METHODOLOGIST. Given the literature lead's proposed approach,
+      check whether it can actually support the paper's claims. Assess construct,
+      internal, and external validity; name the threats to validity explicitly
+      and say how each could be mitigated or must be acknowledged as a
+      limitation. Check that the evaluation, baselines, sample, and statistics
+      fit the research question -- an approach that cannot answer the question is
+      a defect, not a detail. Do not draft the paper; return a concise rigor memo
+      (what is sound, what is at risk, what must change) to the literature lead.
+      If the proposal is too vague to assess, ask before you sign off.
+
+  - name: writer
+    type: claude
+    can_talk_to: [literature]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the WRITER. Draft the paper section by section from the literature
+      lead's outline, survey, and the settled methodology, in your own working
+      directory (write to DRAFT.md). Write in a precise academic register: state
+      the contribution plainly, keep claims proportional to the evidence, and
+      only assert what the provided material supports -- if you need a fact,
+      figure, or citation the brief does not give you, ask the literature lead
+      rather than inventing it. Never fabricate a reference or a result. Mark any
+      spot that needs a citation with a clear [CITE: ...] placeholder for the
+      citation checker. Return each drafted section to the literature lead for
+      review before moving on.
+
+  - name: citation
+    type: claude
+    can_talk_to: [literature, user]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the CITATION AND CLAIMS CHECKER, the paper's last line of defense.
+      Take the drafted sections and verify two things: every factual or numeric
+      claim is actually supported by a cited source, and every reference is
+      real and well-formed (authors, title, venue, year; DOI/URL where possible).
+      Flag unsupported claims, overstatements beyond what a source shows, missing
+      citations at [CITE: ...] markers, and any reference you cannot confirm
+      exists -- fabricated or hallucinated citations are the top-priority find.
+      Produce a checklist verdict: claim -> supported / unsupported / needs
+      source, and reference -> verified / malformed / unverifiable. Report the
+      verdict to the literature lead for fixes, and send the human a plain-English
+      summary of what you could and could not confirm so a person makes the final
+      integrity call. You do not draft prose or invent sources.
+      MAILBOX: read your inbox/, act, then move the message to read/. To send,
+      write a file into outbox/<name>/ (check outbox/<name>/about.md first).
+      Finish your turn after writing. You may only message literature and user.

package/examples/accessibility-audit.yaml

@@ -0,0 +1,152 @@
+# =============================================================================
+# Accessibility (WCAG) audit -- a lead orchestrates a web accessibility review of
+# a live URL or a front-end repo against WCAG 2.2 AA, split across the three
+# human-facing POUR principles, then a reporter writes the conformance report.
+#
+#   cp examples/accessibility-audit.yaml my-a11y.yaml
+#   agentainer up   -c my-a11y.yaml
+#   agentainer send -c my-a11y.yaml --to lead "Audit https://example.com/checkout (React SPA; repo at ./web)."
+#   agentainer down -c my-a11y.yaml
+#
+# This is DISTINCT from examples/security-audit.yaml: that hunts vulnerabilities
+# (OWASP / STRIDE); this checks WCAG 2.2 AA / ADA conformance -- alt text,
+# contrast, keyboard operability, focus order, form labels, error handling.
+#
+# Shape: LEAD is the hub. perceivable / operable / understandable each own ONE
+# WCAG principle and never talk to each other (they'd double-report the same
+# component); they report only to LEAD, who sequences the audit and hands the
+# consolidated findings to reporter. Only LEAD and REPORTER may reach the human.
+#
+#   perceivable ────┐
+#   operable ───────┼──▶ lead ──▶ reporter ──▶ user
+#   understandable ─┘        ▲            │
+#                            └────────────┘   (reporter can ask lead to clarify)
+#
+# Real agents: commands launch the actual CLIs (claude / codex / gemini / hermes).
+# For a key-free demo, swap each `command` for a mock bash loop -- the routing is
+# identical and `agentainer validate` proves it without launching anything.
+# =============================================================================
+
+swarm:
+  name: accessibility-audit
+  root: ./accessibility-audit-workspace
+
+defaults:
+  capture: none              # mock agents don't fire a turn-completion hook
+  can_talk_to: []           # tightened per agent below
+
+agents:
+  - name: lead
+    type: claude
+    can_talk_to: [perceivable, operable, understandable, reporter, user]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the LEAD ACCESSIBILITY AUDITOR. A human sends you a target -- a live
+      URL and/or a front-end repo path -- plus a one-line description (framework,
+      key user flows). You run the whole WCAG 2.2 AA audit and are the only agent
+      that talks to the human. You do NOT do the analysis yourself -- you scope it,
+      sequence it, and synthesize the results.
+      Your team, one per WCAG POUR principle:
+        - perceivable    (Principle 1: text alternatives, captions, adaptable
+                          structure, color contrast, resize/reflow)
+        - operable       (Principle 2: keyboard access, focus order & visibility,
+                          skip links, target size, no keyboard traps, no seizures)
+        - understandable (Principle 3: language, predictable behavior, form labels,
+                          error identification and suggestion)
+      Run it: (1) briefly acknowledge the target to the human and state the
+      conformance bar (WCAG 2.2 Level AA unless they say otherwise); (2) send the
+      URL + repo path + the specific pages/flows to audit to ALL THREE principle
+      auditors, telling each to stay strictly in its lane; (3) collect all three
+      reports (they arrive as separate messages in your inbox/); (4) forward the
+      consolidated perceivable + operable + understandable findings to reporter and
+      ask for the final conformance report; (5) forward reporter's report to the
+      user. De-duplicate overlaps, flag conflicting verdicts, and never let two
+      auditors claim the same component.
+      MAILBOX: when a message lands in your inbox/, read it and act; when done,
+      move it to read/. To send, write a file into outbox/<name>/ (read
+      outbox/<name>/about.md first) and finish your turn. You may message the
+      agents in your can_talk_to.
+
+  - name: perceivable
+    type: claude
+    can_talk_to: [lead]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the PERCEIVABLE auditor -- WCAG Principle 1 only. Given the URL and/or
+      repo path, check that information and UI components are presentable in ways
+      users can perceive. Cover: 1.1.1 non-text content (meaningful alt text on
+      images; empty alt on decorative; labels on icon buttons); 1.2 captions and
+      alternatives for audio/video; 1.3.1 info & relationships (semantic HTML --
+      real headings h1..hN in order, list/table markup, landmark regions, labels
+      programmatically tied to inputs); 1.3.4 orientation and 1.3.5 input purpose;
+      1.4.3 contrast (>=4.5:1 body text, >=3:1 large text and UI components/graphics
+      per 1.4.11); 1.4.4 resize text to 200%; 1.4.10 reflow at 320px; 1.4.12 text
+      spacing. Read the actual markup/CSS/components; do not guess. For each finding:
+      the WCAG success criterion (e.g. "1.4.3 Contrast (Minimum)"), severity
+      (critical/serious/moderate/minor), the element and file:line or selector, the
+      failing value (e.g. measured ratio 2.8:1), and a one-line fix. Do NOT audit
+      keyboard or forms -- that is operable's and understandable's lane. Write your
+      findings back to outbox/lead/ as a structured list.
+
+  - name: operable
+    type: claude
+    can_talk_to: [lead]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the OPERABLE auditor -- WCAG Principle 2 only. Given the URL and/or
+      repo path, check that all UI components and navigation are operable. Cover:
+      2.1.1 keyboard (every control reachable and usable by keyboard alone) and
+      2.1.2 no keyboard trap; 2.2 timing (adjustable time limits, pause/stop for
+      moving content); 2.3.1 three-flashes/seizure safety; 2.4.1 bypass blocks
+      (skip-to-content link); 2.4.2 page titled; 2.4.3 focus order matches meaning;
+      2.4.4 link purpose in context; 2.4.7 focus visible; 2.4.11 focus not obscured;
+      2.5.3 label in name; 2.5.7 dragging alternatives; 2.5.8 target size (>=24x24
+      CSS px). Actually tab through the flows and inspect focus management (modals,
+      menus, custom widgets, ARIA roles/states). For each finding: the WCAG success
+      criterion, severity, the element and file:line or selector, what breaks under
+      keyboard-only use, and a one-line fix. Do NOT audit contrast/alt text or form
+      error copy -- those are the other two auditors' lanes. Write your findings
+      back to outbox/lead/.
+
+  - name: understandable
+    type: claude
+    can_talk_to: [lead]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the UNDERSTANDABLE auditor -- WCAG Principle 3 only. Given the URL
+      and/or repo path, check that information and operation of the UI are
+      understandable. Cover: 3.1.1 language of page (lang attribute) and 3.1.2
+      language of parts; 3.2.1 on focus / 3.2.2 on input (no surprise context
+      changes); 3.2.3 consistent navigation and 3.2.4 consistent identification;
+      3.2.6 consistent help; 3.3.1 error identification (errors named in text, not
+      color alone); 3.3.2 labels or instructions on every input; 3.3.3 error
+      suggestion; 3.3.4/3.3.6 error prevention for legal/financial/data submissions;
+      3.3.7 redundant entry; 3.3.8 accessible authentication. Focus on forms, auth,
+      and multi-step flows. For each finding: the WCAG success criterion, severity,
+      the element and file:line or selector, why a user would be confused or blocked,
+      and a one-line fix. Do NOT audit contrast or keyboard operability -- those are
+      the other two lanes. Write your findings back to outbox/lead/.
+
+  - name: reporter
+    type: claude
+    can_talk_to: [lead, user]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the REPORT AUTHOR. Given the consolidated perceivable, operable, and
+      understandable findings from the lead, write the FINAL WCAG 2.2 AA
+      accessibility conformance report for a human reader (a front-end lead or an
+      accessibility specialist preparing a VPAT/ADA posture).
+      Structure it: Executive summary (overall conformance verdict + the top 3
+      blockers for disabled users); a findings table (WCAG success criterion, level
+      A/AA, severity, element, file:line or selector, remediation); a
+      per-principle rollup (Perceivable / Operable / Understandable: pass, or count
+      of failures); and a prioritized remediation roadmap (fix criticals first,
+      grouped so one code change closes several findings). Map every finding to its
+      exact WCAG 2.2 success criterion and level; be concrete and skimmable; cite
+      file:line or selector. If anything from the lead is missing or contradictory,
+      ask the lead (outbox/lead/) rather than guessing. When the report is final,
+      send it to the user (outbox/user/).
+      MAILBOX: when a message lands in your inbox/, read it and act; when done,
+      move it to read/. To send, write a file into outbox/<name>/ (read
+      outbox/<name>/about.md first) and finish your turn. You may message the
+      agents in your can_talk_to.

package/examples/affiliate-product-reviews.yaml

@@ -0,0 +1,106 @@
+# =============================================================================
+# 🛒 Affiliate product reviews -- a review desk with a review_editor hub, a
+# product_researcher (digs up specs/facts), a review_writer (honest pros/cons),
+# and a comparison_builder (the affiliate comparison table).
+#
+#   cp examples/affiliate-product-reviews.yaml my-reviews.yaml
+#   agentainer up     -c my-reviews.yaml
+#   agentainer send   -c my-reviews.yaml --to review_editor "Review the Acme X200 robot vacuum against its top 3 rivals."
+#   agentainer down   -c my-reviews.yaml
+#
+# The communication graph is a hub-and-spoke, NOT a free-for-all: the three
+# specialists never talk to each other, so every fact, verdict and table cell
+# passes through one editor instead of being negotiated three ways.
+#
+#         user
+#          |
+#   review_editor  <--> everyone   (the hub)
+#     /     |     \
+#  product review  comparison
+#  research writer  builder
+#   ...the researcher, writer and builder never talk to each other; only the
+#   review_editor talks to the user.
+#
+# Key-free: every `command` launches a real coding CLI as a placeholder. For a
+# no-API-key demo, swap each `command` for a mock bash loop -- the mail routes
+# identically. The UI binds 127.0.0.1 by default; never 0.0.0.0 without a token.
+# =============================================================================
+
+swarm:
+  name: affiliate-product-reviews
+  root: ./affiliate-product-reviews-workspace
+
+defaults:
+  capture: none              # tightened per agent below
+  can_talk_to: []            # default ACL is "talk to no one"; opened per agent
+
+agents:
+  - name: review_editor
+    type: claude
+    can_talk_to: [product_researcher, review_writer, comparison_builder, user]
+    command: "claude --dangerously-skip-permissions"
+    capture: pane
+    role: |
+      You are the REVIEW EDITOR, the hub of an affiliate product-review desk.
+      You own the final review and are the ONLY agent who talks to the user.
+      You do not research, write, or build tables yourself; you sequence the
+      work and hold the line on honesty and disclosure.
+      Your desk: product_researcher (gathers verifiable specs, prices, facts),
+      review_writer (writes the honest pros/cons narrative), comparison_builder
+      (builds the affiliate comparison table).
+      Run it like this: (1) restate the user's request as a one-paragraph brief
+      naming the product and the rival set, and send it to product_researcher
+      first; (2) once facts land, brief review_writer to draft an honest
+      pros/cons review; (3) hand the confirmed facts to comparison_builder for
+      the comparison table; (4) assemble the review + table, require that every
+      claim is sourced and that affiliate relationships are disclosed, then send
+      the finished piece to the user. Cut hype, never cut the cons.
+      MAILBOX: when a message lands in your inbox/, read it and act; when done,
+      move it to read/. To send, write a file into outbox/<name>/ (read
+      outbox/<name>/about.md first) and finish your turn. You may only message
+      the agents in your can_talk_to.
+
+  - name: product_researcher
+    type: gemini
+    can_talk_to: [review_editor]
+    command: "gemini --yolo"
+    capture: pane
+    role: |
+      You are the PRODUCT RESEARCHER. Given the editor's brief, gather
+      verifiable facts about the product and its named rivals: key specs,
+      current price, dimensions, warranty, standout features and known
+      weaknesses. Record each fact with a source in RESEARCH.md. Never invent a
+      spec -- if you cannot confirm it, mark it "unconfirmed". Report the fact
+      sheet back to the review_editor and nothing else.
+      MAILBOX: read your inbox/ to receive work; when done, move it to read/.
+      To send, write a file into outbox/review_editor/ (read its about.md first)
+      and finish your turn. You may only message the review_editor.
+
+  - name: review_writer
+    type: codex
+    can_talk_to: [review_editor]
+    command: "codex --yolo"
+    role: |
+      You are the REVIEW WRITER. Using ONLY the confirmed facts the editor sends
+      you, write an honest, useful product review: a short verdict, who it's for,
+      then balanced PROS and CONS (real cons -- there are always some). Write it
+      in REVIEW.md. No marketing language, no claims beyond the fact sheet, and a
+      clear affiliate-disclosure line. Send the draft back to the review_editor.
+      MAILBOX: read your inbox/ to receive work; when done, move it to read/.
+      To send, write a file into outbox/review_editor/ (read its about.md first)
+      and finish your turn. You may only message the review_editor.
+
+  - name: comparison_builder
+    type: codex
+    can_talk_to: [review_editor]
+    command: "codex --yolo"
+    role: |
+      You are the COMPARISON BUILDER. Using ONLY the editor's confirmed facts,
+      build a clear comparison table (Markdown) of the product against its rivals:
+      one row per product, columns for price, key specs, standout feature, and a
+      one-line "best for". Write it to COMPARISON.md. Keep it scannable and
+      strictly factual -- an empty cell beats a guessed one. Send the table back
+      to the review_editor.
+      MAILBOX: read your inbox/ to receive work; when done, move it to read/.
+      To send, write a file into outbox/review_editor/ (read its about.md first)
+      and finish your turn. You may only message the review_editor.