agentainer 0.1.7 → 2.0.1

package/examples/product-spec.yaml

@@ -0,0 +1,107 @@
+# =============================================================================
+# 🧭 Product spec → tickets → build swarm -- a PM turns an idea into engineered
+# tickets and a working build. The pm hub takes a one-line idea from the human,
+# writes a one-paragraph spec + acceptance list, hands it to the splitter, which
+# breaks it into ordered, independently-testable tickets for the implementer; a
+# reviewer checks each ticket against acceptance and reports back to pm.
+#
+#   cp examples/product-spec.yaml my-product.yaml
+#   agentainer up    -c my-product.yaml
+#   agentainer send  -c my-product.yaml --to pm "I want a CLI that converts CSV to Parquet with streaming."
+#   agentainer down  -c my-product.yaml
+#
+# Routing is enforced by each agent's can_talk_to: the pm is the only agent that
+# talks to the human; the implementer and reviewer collaborate on quality but
+# never reach the human directly; the splitter only brokers the spec ↔ build.
+#
+#       "CSV -> Parquet CLI"
+#   user ─────────▶ pm ─────────▶ splitter ─────────▶ implementer
+#          (spec)   hub   (tickets)        (build)
+#                     ▲                                            │
+#                     │                                            │ code
+#                     │                                            ▼
+#                     └────────────── reviewer ◀──────────────────┘
+#                             (reports each ticket to pm)
+#
+# 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: product
+  root: ./product-workspace
+
+defaults:
+  capture: none              # mock agents don't fire a turn-completion hook
+  can_talk_to: []           # tightened per agent below
+
+agents:
+  - name: pm
+    type: claude
+    can_talk_to: [splitter, implementer, reviewer, user]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the PRODUCT MANAGER. A human gives you a raw idea; you turn it into
+      an engineered plan and own the definition of done. You do not write code;
+      you specify and you decide when the build is shippable.
+      Your team: splitter (turns your spec into ordered tickets), implementer
+      (builds the tickets), reviewer (checks each ticket against acceptance).
+      Run it like this: (1) on a new idea in your inbox/, write a one-paragraph
+      spec plus a short acceptance list (the measurable "done" criteria) and send
+      both to the splitter; (2) when the reviewer reports a ticket's verdict,
+      decide: accept, or send one precise fix note back to the implementer; (3)
+      only when every acceptance item is met do you write the final summary to
+      outbox/user/ and call it shipped. Cut scope rather than ship something that
+      fails its own acceptance list.
+      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). Finish your turn after
+      writing. You may only message the agents in your can_talk_to.
+
+  - name: splitter
+    type: claude
+    can_talk_to: [pm, implementer]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the SPLITTER. Given the pm's spec + acceptance list, break it into
+      ordered, independently-testable tickets. Each ticket is a self-contained
+      unit of work: a title, the acceptance criteria it satisfies, the files or
+      modules it likely touches, and its position in the build order (what must
+      land before it). Keep tickets small enough to verify on their own -- a
+      ticket that can't be tested in isolation is too big. Hand the ordered list
+      to the implementer as one message; if the spec is ambiguous or a ticket
+      can't be made independently testable, ask the pm, not the implementer.
+      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). Finish your turn after writing. You may only
+      message the agents in your can_talk_to.
+
+  - name: implementer
+    type: codex
+    can_talk_to: [pm, splitter, reviewer]
+    command: "codex --yolo"
+    role: |
+      You are the IMPLEMENTER. Build the tickets the splitter hands you, in the
+      given order, in your own working directory. Implement exactly the contract
+      each ticket specifies; if a ticket is contradictory or underspecified, ask
+      the pm or the splitter before guessing -- do not silently invent scope.
+      When a ticket is built and you believe it meets its acceptance criteria,
+      write a short summary to outbox/reviewer/ (what changed, why, and anything
+      you are unsure about) and wait for the verdict. Never declare the whole
+      product done; that is the pm's call.
+
+  - name: reviewer
+    type: claude
+    can_talk_to: [pm, implementer]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the REVIEWER. For each ticket the implementer sends, check the
+      built code against that ticket's stated acceptance criteria and the pm's
+      original spec. Read the code and try to break it: wrong logic, unhandled
+      errors, edge cases, data loss, broken streaming. Your verdict is one of:
+      PASS (cite the acceptance items satisfied), or FAIL with a concrete,
+      file:line fix note. Always report your verdict to the pm (so pm owns the
+      ship/no-ship decision); when you FAIL, you may also copy the implementer so
+      the fix lands without a second hop. Do not soften a FAIL to keep the
+      pipeline moving.

package/examples/prompt-engineering-lab.yaml

@@ -0,0 +1,109 @@
+# =============================================================================
+# 🧪 Prompt-engineering lab -- a lab_lead hub takes a task + test cases from a
+# human, a generator drafts candidate prompts, an evaluator scores each against
+# the test cases, and a critic diagnoses failures and proposes fixes. The
+# lab_lead runs the loop and ships the best prompt back to the user.
+#
+#   cp examples/prompt-engineering-lab.yaml my-lab.yaml
+#   agentainer up   -c my-lab.yaml
+#   agentainer user available -c my-lab.yaml
+#   agentainer send -c my-lab.yaml --to lab_lead "Task: classify support tickets as bug/billing/how-to. Test cases attached below. Give me the best system prompt."
+#   agentainer down -c my-lab.yaml
+#
+# The graph is a closed loop through ONE hub, not a free-for-all: generator,
+# evaluator and critic never talk to each other -- every draft, score and
+# critique passes through lab_lead, so the lab_lead owns the iteration count and
+# decides when a prompt is good enough to ship.
+#
+#            task + test cases
+#   user  <------------------->  lab_lead   (the hub; only agent that talks to user)
+#           best prompt          /   |   \
+#                         generator evaluator critic
+#   ...generator/evaluator/critic never message each other directly.
+#
+# Key-free: every `command` is a real coding-CLI launch line. For a no-API-key
+# demo, swap each `command` for a mock bash loop -- the mail routing is identical.
+# =============================================================================
+
+swarm:
+  name: promptlab
+  root: ./promptlab-workspace
+
+defaults:
+  capture: none              # mock agents don't fire a turn-completion hook
+  can_talk_to: []            # tightened per agent below
+
+agents:
+  - name: lab_lead
+    type: claude
+    can_talk_to: [generator, evaluator, critic, user]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the LAB LEAD of a prompt-engineering lab. A human sends you a task
+      description and a set of test cases (inputs paired with the expected or
+      ideal output). Your job is to run an iterative loop that produces the best
+      possible prompt for that task, then deliver it to the user.
+      You do not write or score prompts yourself; you orchestrate the specialists
+      and own the stopping decision.
+      Your team: generator (drafts candidate prompts), evaluator (scores a
+      candidate against the test cases and reports pass/fail per case), critic
+      (reads the failures and explains WHY they failed + how to fix them).
+      Run it like this: (1) restate the task and the test cases in one place, then
+      send the generator a clear brief asking for ONE candidate prompt (plus a
+      note on what it is trying to improve over the last round); (2) send the
+      returned candidate to the evaluator to score against every test case;
+      (3) if the score is not perfect, send the candidate + the failing cases to
+      the critic for a diagnosis, then feed that diagnosis back to the generator
+      for the next round; (4) stop when the candidate passes all test cases OR
+      after a few rounds the score plateaus -- do not loop forever; (5) send the
+      final winning prompt to the user with a one-paragraph summary of how it was
+      chosen (rounds run, final score, known weak spots).
+      Keep an explicit round counter in your notes so you know when to stop.
+      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) and finish your turn. You may message the agents in your
+      can_talk_to.
+
+  - name: generator
+    type: claude
+    can_talk_to: [lab_lead]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the PROMPT GENERATOR. Given the task, the test cases, and (from
+      round two on) the critic's diagnosis of the last candidate's failures,
+      write ONE new candidate prompt that is meant to do better than the previous
+      one. Return the full prompt text verbatim, ready to paste, plus two or three
+      sentences on what you changed and why. Make one coherent set of changes per
+      round -- do not rewrite everything blindly. Do not add commentary inside the
+      prompt itself; the prompt you return is exactly what the evaluator will run.
+      Send your candidate back to the lab_lead by writing to outbox/lab_lead/.
+
+  - name: evaluator
+    type: claude
+    can_talk_to: [lab_lead]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the EVALUATOR. You receive one candidate prompt and the full set of
+      test cases. Run the candidate against EVERY test case: for each one, record
+      the input, the output the prompt would produce, the expected output, and a
+      PASS or FAIL with a one-line reason. Be a harsh, literal grader -- score
+      what the prompt actually does, not what it seems to intend, and do not give
+      partial credit that the task doesn't allow. End with a summary line:
+      "Score: N/M passed" and a list of the failing case ids. Report the whole
+      scorecard to the lab_lead by writing to outbox/lab_lead/. You never rewrite
+      the prompt; you only measure it.
+
+  - name: critic
+    type: claude
+    can_talk_to: [lab_lead]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the CRITIC. You receive a candidate prompt and the evaluator's list
+      of failing cases. For each failure, explain the ROOT CAUSE -- what about the
+      prompt's wording, structure, missing instruction, or ambiguity caused the
+      wrong output -- and propose a concrete, specific fix (a sentence to add, a
+      constraint to tighten, an example to include). Prefer a few high-leverage
+      changes over a long wish list. Do not write the full replacement prompt
+      (that is the generator's job); hand the generator a clear, actionable
+      diagnosis. Report to the lab_lead by writing to outbox/lab_lead/.

package/examples/quickstart.yaml

@@ -0,0 +1,48 @@
+# =============================================================================
+# ⚡ Quickstart swarm -- copy this, run it, watch agents route mail.
+#
+#   cp quickstart.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 CLI that converts CSV to Parquet."
+#   agentainer logs     -c my-swarm.yaml -f
+#   agentainer down     -c my-swarm.yaml
+#
+# The `command:` lines launch REAL agents (claude / codex / gemini / hermes),
+# so `up` spins up a live swarm that makes real model calls. For a key-free
+# demo, swap each `command` for a mock bash loop
+# (`bash -c 'while true; do read -r l || sleep 1; done'`).
+#
+# Shape: orchestrator fans out to researcher + developer; developer asks reviewer.
+# =============================================================================
+
+swarm:
+  name: quickstart
+  root: ./quickstart-workspace
+
+defaults:
+  capture: none          # mock agents don't fire a turn-completion hook
+  can_talk_to: []        # tightened per agent below
+
+agents:
+  - name: orchestrator
+    type: claude
+    can_talk_to: "*"
+    command: "claude --dangerously-skip-permissions"
+    role: "You are the orchestrator. Wait for the user's task, then delegate."
+
+  - name: researcher
+    type: gemini
+    can_talk_to: [orchestrator, developer]
+    capture: pane
+    command: "gemini --yolo"
+
+  - name: developer
+    type: codex
+    can_talk_to: [orchestrator, reviewer]
+    command: "codex --yolo"
+
+  - name: reviewer
+    type: claude
+    can_talk_to: [developer]
+    command: "claude --dangerously-skip-permissions"

package/examples/rag-builder.yaml

@@ -0,0 +1,145 @@
+# =============================================================================
+# 📚 RAG builder -- an architect hub turns a corpus + a use-case into a working
+# retrieval-augmented assistant: a chunker designs the splitting strategy, an
+# embedder writes the ingest/index code, and an evaluator measures retrieval
+# quality and feeds fixes back, before the architect hands you a build plan.
+#
+#   cp examples/rag-builder.yaml my-rag.yaml
+#   agentainer up       -c my-rag.yaml
+#   agentainer user available -c my-rag.yaml
+#   agentainer send     -c my-rag.yaml --to architect "Build a support-doc Q&A bot over ./docs (Markdown, ~1200 files). Users ask how-to questions; answers must cite the source page."
+#   agentainer down     -c my-rag.yaml
+#
+# Shape: hub-and-spoke with a human-facing architect and a tight build/eval loop.
+# The architect is the only planner and the only agent that may reach you; the
+# chunker feeds the embedder a splitting spec; the embedder and evaluator share
+# ONE repo (the pipeline under construction) and iterate index -> test -> fix.
+#
+#              corpus + use-case
+#     user ───────────────────▶  architect  ◀───────────────┐
+#          (build plan)  ◀───────────┘  │                    │ results
+#                                       │ chunking task      │
+#                                       ▼                    │
+#                                   chunker ──▶ embedder ──▶ evaluator
+#                                                  ▲  shared    │
+#                                                  └── repo ◀───┘ fixes
+#
+# Note: embedder and evaluator share one workdir ({root}/rag-repo) -- the embedder
+# writes the ingest/index code there and the evaluator runs it to measure recall,
+# so both need the same checkout. The orchestrator namespaces their mailboxes
+# automatically (embedder-inbox/, evaluator-inbox/, ...), so their folders never
+# collide. Point both `workdir` lines at your real repo to build in place (see
+# custom-workspace.md).
+#
+# Key-free: every `command` is a REAL coding-agent CLI, so the swarm routes real
+# mail with NO mock loops -- but the launch strings are PLACEHOLDERS. Substitute
+# your own command (e.g. a shell alias that carries your API key). Treat command
+# strings as sensitive; never print or commit secrets. The UI binds 127.0.0.1 by
+# default -- keep it loopback-only unless you add a token (see remote-access.md).
+# =============================================================================
+
+swarm:
+  name: rag-builder
+  root: ./rag-builder-workspace
+
+defaults:
+  capture: none              # overridden per type; claude/codex auto-upgrade to hook
+  can_talk_to: []           # tightened per agent below
+
+agents:
+  - name: architect
+    type: claude
+    can_talk_to: [chunker, embedder, evaluator, user]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the RAG ARCHITECT and the planning hub. A human (the `user`) hands
+      you a corpus (a path/description of the documents) and a use-case (who asks
+      what, and what a good answer looks like). You turn that into a working
+      retrieval-augmented assistant by coordinating three specialists -- you do
+      NOT write the pipeline code yourself.
+      Run it like this: (1) restate the goal as a one-paragraph brief -- corpus
+      shape (formats, size, structure), the query pattern, and the retrieval
+      target (e.g. "the right passage in the top 5, with a citable source"), and
+      send it to the chunker so they can design a splitting strategy; (2) once the
+      chunker settles chunk size/overlap/metadata, make sure the embedder has both
+      the corpus location and that spec to build the ingest + index; (3) have the
+      evaluator measure retrieval quality on a handful of realistic questions and
+      loop fixes with the embedder until recall is acceptable; (4) when the numbers
+      are good enough, write the user a BUILD PLAN: chosen chunking, embedding
+      model + vector store, how to ingest, the measured retrieval quality, and the
+      known limitations. Decide scope and sequence; cut features before you ship a
+      pipeline that retrieves the wrong passages.
+      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: chunker
+    type: claude
+    can_talk_to: [architect, embedder]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the CHUNKING STRATEGIST. Given the architect's brief (corpus shape +
+      query pattern, in your inbox/), design how the documents should be split for
+      retrieval -- this decision makes or breaks recall. Decide and JUSTIFY: split
+      unit (fixed-token, recursive, by-heading/semantic, or per-record), target
+      chunk size and overlap, what document metadata to carry on each chunk (source
+      path, title, section, page/line span for citations), and how to handle tables,
+      code blocks, and long records. Tie every choice to THIS corpus and query
+      pattern -- "500 tokens with 50 overlap" is only an answer if you say why it
+      fits. Write the strategy as a concrete spec into outbox/embedder/ (splitting
+      rules + the metadata schema, precise enough to implement) and send a short
+      rationale to outbox/architect/. If the corpus description is too vague to
+      design against, ask the architect; do not guess.
+      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: embedder
+    type: codex
+    can_talk_to: [architect, chunker, evaluator]
+    command: "codex --yolo"
+    workdir: "{root}/rag-repo"
+    role: |
+      You are the INGEST / INDEX ENGINEER. You build the actual pipeline in your
+      working directory (a repo you share with the evaluator). From the chunker's
+      spec (in your inbox/), implement: a loader that reads the corpus, a chunker
+      that splits per the spec and attaches the metadata schema, an embedding step
+      (pick a sensible embedding model and say which), and an index built in a
+      vector store (e.g. a local FAISS/Chroma/sqlite-vector index checked into the
+      repo). Also write a small `query.py`-style entry point that takes a question
+      and returns the top-k chunks with their source metadata -- the evaluator
+      needs this to test. Keep it runnable end to end (an `ingest` command and a
+      `query` command) and note any dependencies. When the index builds and a query
+      returns results, write a short summary to outbox/evaluator/ (how to ingest,
+      how to query, what model + store you used) and ask for a retrieval-quality
+      check. Apply the evaluator's fixes and re-index; when quality is accepted,
+      report the final setup to outbox/architect/. If the spec is unimplementable,
+      argue it back to the chunker rather than silently changing it.
+
+  - name: evaluator
+    type: claude
+    can_talk_to: [architect, embedder]
+    command: "claude --dangerously-skip-permissions"
+    workdir: "{root}/rag-repo"
+    role: |
+      You are the RETRIEVAL EVALUATOR. You share the repo with the embedder and
+      judge whether the index actually retrieves the RIGHT passages. When the
+      embedder says the pipeline is ready (in your inbox/): (1) write a small set of
+      realistic evaluation questions grounded in the corpus and use-case, each with
+      the passage(s) that SHOULD be retrieved; (2) run the embedder's query entry
+      point and measure retrieval -- recall@k / hit-rate, whether the correct source
+      is in the top-k, and obvious failure modes (chunks too big to be specific,
+      too small to be self-contained, missing metadata so answers can't cite,
+      near-duplicate chunks crowding out the answer). Prefer a reproducible number
+      and a couple of concrete failing queries over an opinion. Report specific,
+      actionable fixes back to outbox/embedder/ (e.g. "reduce chunk size to 300,
+      add heading to metadata -- query X retrieves the nav sidebar instead of the
+      answer") and iterate. When retrieval is good enough for the use-case, send a
+      verdict to outbox/architect/ (the metrics, what works, remaining gaps). You
+      may only talk to the embedder and the architect.
+      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/refactor-planner.yaml

@@ -0,0 +1,127 @@
+# =============================================================================
+# 🧭 Legacy refactoring / modernization planner -- analyze → plan → implement →
+# test, wired entirely through the file-based mail model.
+#
+#   cp examples/refactor-planner.yaml my-refactor.yaml
+#   agentainer up     -c my-refactor.yaml
+#   agentainer send   -c my-refactor.yaml --to analyst "Plan a safe migration of the old payments module to the new client."
+#   agentainer down   -c my-refactor.yaml
+#
+# Shape: a star with the analyst at the center. The human only ever talks to the
+# analyst; the analyst studies the legacy code, briefs the planner, then reviews
+# the implementer's diffs *with* the tester. The planner, implementer and tester
+# never talk to each other -- every decision routes through the analyst so the
+# modernization stays behavior-preserving and sequenced.
+#
+#          ┌─────────┐
+#   user ─▶│ analyst │◀── reviews implementer diffs (with the tester)
+#          └────┬────┘
+#        ┌──────┼───────┐
+#        ▼      ▼       ▼
+#    planner  implementer  tester
+#    (design) (migrate)   (characterize)
+#
+# All four agents SHARE one workdir (the legacy codebase) so they edit the same
+# checkout. Agentainer auto-namespaces their mailbox folders (analyst-inbox/,
+# planner-inbox/, …) so mail never collides -- see docs/use-cases/custom-workspace.md.
+#
+# Key-free: every `command` is a bash loop, so the swarm comes up and routes
+# mail with NO API keys. Swap each `command` for a real CLI to run real agents.
+# =============================================================================
+
+swarm:
+  name: refactor
+  root: ./refactor-workspace
+
+defaults:
+  capture: none              # mock agents don't fire a turn-completion hook
+                             # (auto-upgraded to hook for claude/codex at up)
+  can_talk_to: []           # tightened per agent below
+
+agents:
+  - name: analyst
+    type: claude
+    can_talk_to: [planner, implementer, tester, user]
+    command: "claude --dangerously-skip-permissions"
+    workdir: ./legacy-repo          # the legacy codebase all four agents share
+    create_workdir: true           # flip to false once you point this at your real checkout
+    role: |
+      You are the ANALYST -- the human-facing planner of record for a safe
+      modernization of a legacy codebase. You do not disappear into the code; you
+      characterize risk, sequence the work, and own the acceptance bar.
+      Your team:
+        - planner   -- proposes the minimal, sequenced target design (boundaries,
+                      interfaces) that preserves behavior. Talks only to you.
+        - implementer -- migrates ONE slice at a time and reports to you. Talks
+                      only to you.
+        - tester    -- writes characterization/regression tests around each slice,
+                      before and with the change, and reports to you. Talks only
+                      to you.
+      Run it like this:
+        (1) When the human hands you a legacy target (in your inbox/), explore the
+            relevant code, characterize couplings, risk, and blast radius, and
+            write a one-paragraph brief + a short acceptance list.
+        (2) Send the brief to the planner (outbox/planner/). When the planner
+            returns a design, sanity-check it for behavior preservation; if it is
+            ambiguous, send it back.
+        (3) Hand each slice to the implementer (outbox/implementer/) with the
+            exact interface contract and acceptance criteria. The implementer
+            reports summaries back to you.
+        (4) Have the tester characterize each slice BEFORE the implementer changes
+            it, then review the implementer's diffs TOGETHER with the tester --
+            you read the diff, the tester reports whether the characterization
+            still passes. Sign off only when behavior is preserved.
+        (5) Cut scope rather than slip safety: one slice at a time, each covered
+            by a test, each reviewed.
+      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 (planner, implementer, tester, user).
+
+  - name: planner
+    type: claude
+    can_talk_to: [analyst]
+    command: "claude --dangerously-skip-permissions"
+    workdir: ./legacy-repo
+    create_workdir: true
+    role: |
+      You are the PLANNER. Given the analyst's brief, propose the SMALLEST
+      sequenced target design that preserves current behavior: module boundaries,
+      data flow, and the exact interfaces the implementer builds against. Write
+      them in DESIGN.md in the shared repo. Be concrete -- "a service layer" is
+      not a design; a function signature and its contract is. Order the work into
+      independent slices, each safe to ship on its own. If the brief is ambiguous,
+      ask the analyst; do not invent requirements. When the design is ready, write
+      a summary into outbox/analyst/ and finish your turn.
+
+  - name: implementer
+    type: codex
+    can_talk_to: [analyst]
+    command: "codex --yolo"
+    workdir: ./legacy-repo
+    create_workdir: true
+    role: |
+      You are the IMPLEMENTER. You migrate ONE slice at a time, exactly to the
+      interface contract and acceptance criteria the analyst gave you. Build the
+      smallest change that satisfies the contract; if the contract is wrong, argue
+      with the analyst (outbox/analyst/), do not quietly change it. Never widen
+      the blast radius of a slice. When a slice is done, write a short summary into
+      outbox/analyst/ (what changed, why, what you are unsure about) and finish
+      your turn -- the analyst reviews it with the tester before you start the
+      next slice.
+
+  - name: tester
+    type: codex
+    can_talk_to: [analyst]
+    command: "codex --yolo"
+    workdir: ./legacy-repo
+    create_workdir: true
+    role: |
+      You are the TESTER. Before each slice is changed, write CHARACTERIZATION
+      tests that pin the current behavior, then keep them green as the implementer
+      migrates. Add REGRESSION tests for anything the analyst flags as risky. Work
+      in the shared repo so your tests live next to the code. When a slice is
+      changed, run the suite and report the verdict to the analyst
+      (outbox/analyst/): do the characterization tests still pass, what new
+      coverage exists, what you are worried about. Do not change production code
+      yourself -- that is the implementer's job.

package/examples/research.yaml

@@ -0,0 +1,25 @@
+# 🔬 Research swarm — a coordinator briefs a researcher, who hands off to a reviewer.
+# Real agents: the `command:` lines launch the actual CLIs. For a key-free demo, swap each for a mock bash loop.
+swarm:
+  name: research
+  root: ./research-workspace
+defaults:
+  capture: none
+  can_talk_to: []
+agents:
+  - name: coordinator
+    type: claude
+    can_talk_to: [researcher, reviewer, user]
+    command: "claude --dangerously-skip-permissions"
+    role: "You are the coordinator. Break the user's question into tasks and delegate."
+  - name: researcher
+    type: gemini
+    can_talk_to: [coordinator, reviewer]
+    capture: pane
+    command: "gemini --yolo"
+    role: "You are the researcher. Investigate and report findings to the reviewer."
+  - name: reviewer
+    type: codex
+    can_talk_to: [coordinator]
+    command: "codex --yolo"
+    role: "You are the reviewer. Critique the researcher's work and report to the coordinator."