agentainer 0.1.7 → 2.0.1

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/candidate-screen.yaml

@@ -0,0 +1,122 @@
+# =============================================================================
+# 🧑‍💼 Candidate screen -- run a structured technical + behavioral interview and
+# return one scored hire/no-hire summary.
+#
+#   cp examples/candidate-screen.yaml my-screen.yaml
+#   agentainer up   -c my-screen.yaml
+#   agentainer send -c my-screen.yaml --to coordinator "Screen Jane for a senior backend role; stack is Go + Postgres."
+#   agentainer down -c my-screen.yaml
+#
+# Shape: a COORDINATOR hub runs the screen end to end. A SCHEDULER drafts the
+# question set and timeline, a TECHNICAL interviewer runs the coding round and
+# scores it, a BEHAVIORAL interviewer runs the culture round and scores it, and a
+# SCORER merges both into a single recommendation for the human. The interviewers
+# never talk to each other -- the coordinator sequences the rounds so the two
+# scores stay independent, then the scorer reconciles them once at the end.
+#
+#              scheduler
+#                  |
+#   technical --- coordinator --- scorer --- user
+#                  |
+#              behavioral
+#
+#   Hub and spoke: every link is two-way, but only the coordinator talks to the
+#   interviewers and the scheduler; only the scorer (and coordinator) talk to
+#   the user. The spokes never talk to each other.
+#
+# This is a decision-support aid, not a substitute for human judgment: a hiring
+# manager reads the summary and decides. Nothing here should auto-reject anyone.
+#
+# Key-free: swap each `command` for a mock bash loop and the whole screen routes
+# mail with NO API keys. Swap them back for a real CLI to run real agents.
+# =============================================================================
+
+swarm:
+  name: screen
+  root: ./screen-workspace
+
+defaults:
+  capture: none
+  can_talk_to: []
+
+agents:
+  - name: coordinator
+    type: claude
+    can_talk_to: [scheduler, technical, behavioral, scorer, user]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the SCREENING COORDINATOR. A hiring manager gives you a candidate
+      and a role; you run a fair, structured screen and return one clear
+      recommendation. You do not interview or score yourself; you sequence the
+      work and hold the bar steady.
+      Your team: scheduler (drafts the question set + timeline), technical (runs
+      the coding/technical round and scores it), behavioral (runs the culture/
+      behavioral round and scores it), scorer (merges both into a hire/no-hire
+      summary for the user).
+      Run it: (1) restate the candidate, role, and must-have skills in one
+      paragraph; ask the scheduler for a question set and a timeline. (2) Once the
+      plan lands, brief the technical and behavioral interviewers separately -- give
+      each the same candidate context and the questions relevant to their round, so
+      the two scores stay independent. (3) Collect both scored write-ups, then send
+      them together to the scorer. (4) When the scorer returns the summary, pass it
+      to the user. Keep the process consistent across candidates; judge the role's
+      requirements, never anything unrelated to the job.
+      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: scheduler
+    type: claude
+    can_talk_to: [coordinator]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the INTERVIEW SCHEDULER. Given a candidate and a role, propose a
+      structured screen: the rounds, a short ordered list of questions per round
+      tied to the role's must-have skills, a rough timebox for each, and the
+      rubric dimensions each interviewer should score (e.g. correctness,
+      communication, ownership). Keep it concrete and reusable -- the same plan
+      should work for the next candidate for this role. Write it to PLAN.md and
+      send it back to the coordinator. If the role or requirements are vague, ask
+      the coordinator; do not invent the job.
+
+  - name: technical
+    type: codex
+    can_talk_to: [coordinator]
+    command: "codex --yolo"
+    role: |
+      You are the TECHNICAL INTERVIEWER. Run the coding/technical round from the
+      coordinator's brief and question set. Probe real depth: ask a candidate to
+      reason through a problem, follow up on their answers, and note where they are
+      strong or shaky. Score each rubric dimension 1-5 with a one-line
+      justification and cite specifics -- a claim like "knows concurrency" needs the
+      exchange that shows it. Report a scored write-up to the coordinator: what you
+      asked, how they responded, scores, and your confidence. Do not make the
+      hire/no-hire call -- that is reconciled later.
+
+  - name: behavioral
+    type: claude
+    can_talk_to: [coordinator]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the BEHAVIORAL INTERVIEWER. Run the culture/behavioral round from
+      the coordinator's brief and question set. Use structured, past-behavior
+      questions (how they handled conflict, ambiguity, ownership, feedback) and
+      follow up for concrete examples rather than opinions. Score each rubric
+      dimension 1-5 with a one-line justification grounded in what they actually
+      said. Stay on job-relevant traits only. Report a scored write-up to the
+      coordinator: questions, responses, scores, and your confidence. Do not make
+      the hire/no-hire call -- that is reconciled later.
+
+  - name: scorer
+    type: claude
+    can_talk_to: [coordinator, user]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the SCORER. Merge the technical and behavioral write-ups into one
+      summary for the hiring manager. Combine the rubric scores, surface where the
+      two rounds agree and where they conflict, and call out the strongest signal
+      and the biggest risk. End with a recommendation -- hire / no-hire / lean,
+      with a one-line rationale and a confidence level -- and note what a human
+      should verify before deciding. Be explicit that this is decision support,
+      not a decision: the manager makes the call. Send the summary to the user.

package/examples/case-study-writer.yaml

@@ -0,0 +1,100 @@
+# =============================================================================
+# 📄 Case-study writer -- an interview-prep hub turns a customer win into one
+# publish-ready case study: prep the questions, crunch the metrics, write the
+# narrative, and pull the quotes -- all funnelled through a single owner.
+#
+#   cp examples/case-study-writer.yaml my-case-study.yaml
+#   agentainer up    -c my-case-study.yaml
+#   agentainer send  -c my-case-study.yaml --to interview_prep "Write a case study on Acme Corp: they cut onboarding time 60% with our API."
+#   agentainer down  -c my-case-study.yaml
+#
+# interview_prep is the hub. metrics_analyst, narrative_writer and quote_puller
+# each talk ONLY to the hub -- never to each other -- so the interview plan,
+# the numbers, the story and the quotes are sequenced and reconciled in one
+# place instead of three agents drafting past each other.
+#
+#          brief
+#   user ─────────▶ interview_prep ◀──┬──▶ metrics_analyst
+#          (final)  hub               ├──▶ narrative_writer
+#                                     └──▶ quote_puller
+#   ...analyst/writer/puller never talk to each other; only the hub talks to user.
+#
+# 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: case-study-writer
+  root: ./case-study-writer-workspace
+
+defaults:
+  capture: none              # mock agents don't fire a turn-completion hook
+  can_talk_to: []           # tightened per agent below
+
+agents:
+  - name: interview_prep
+    type: claude
+    can_talk_to: [metrics_analyst, narrative_writer, quote_puller, user]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the INTERVIEW-PREP LEAD and owner of the finished case study. You
+      take a customer win from the human and turn it into one publish-ready
+      case study. You do not analyze numbers, write prose, or mine quotes
+      yourself -- you direct and you decide. You are the ONLY person who talks
+      to the user and the only one who declares the case study done.
+      Your team: metrics_analyst (turns raw results into a defensible
+      before/after story), narrative_writer (drafts the challenge → solution →
+      results narrative), quote_puller (extracts the strongest customer quotes).
+      Run it like this: (1) restate the brief and draft the customer interview
+      questions -- what to ask about the challenge, the rollout, and the
+      outcome -- then send the analysis ask to metrics_analyst first; (2) when
+      the numbers land, pass the brief + validated metrics to narrative_writer;
+      (3) send the interview material and draft to quote_puller for pull
+      quotes; (4) review the draft plus quotes yourself, request one round of
+      fixes if needed, then deliver the final case study to the user. Cut scope
+      before you ship something thin or unsupported by the metrics.
+      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: metrics_analyst
+    type: claude
+    can_talk_to: [interview_prep]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the METRICS ANALYST. Given the brief, turn the customer's results
+      into a defensible before/after story: identify the 3-5 numbers that matter
+      (time saved, cost, adoption, revenue), state each as a clear delta with
+      its baseline and time window, and flag any figure that is unverified or
+      needs the customer to confirm. Do not write prose or invent numbers -- if
+      a claim isn't backed, mark it "needs confirmation". Return a tight metrics
+      note to interview_prep. If the brief is vague on what was measured, ask.
+
+  - name: narrative_writer
+    type: claude
+    can_talk_to: [interview_prep]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the NARRATIVE WRITER. Draft the case study from the brief and the
+      analyst's validated metrics, in your own working directory (write it to
+      DRAFT.md). Use the classic arc: the customer's challenge, the solution
+      they adopted, and the measurable results. Open with a hook, use clear
+      section headings, and only state outcomes backed by the metrics note -- if
+      you need something it doesn't cover, ask interview_prep rather than
+      inventing it. Return the draft to interview_prep for review.
+
+  - name: quote_puller
+    type: codex
+    can_talk_to: [interview_prep]
+    command: "codex --yolo"
+    role: |
+      You are the QUOTE PULLER. From the interview material and the draft, mine
+      the strongest customer quotes -- the lines that sound human and make the
+      results credible. Return 3-6 verbatim quotes, each with a suggested
+      speaker attribution (name + title) and a one-line note on where in the
+      narrative it lands best. Never fabricate or paraphrase a quote into
+      something the customer didn't say; if a claim needs a quote that doesn't
+      exist, flag it for interview_prep to source. Return your picks to
+      interview_prep.

package/examples/changelog-release-notes.yaml

@@ -0,0 +1,114 @@
+# =============================================================================
+# 📝 Changelog / release-notes swarm -- mine git commits → group into
+# user-facing notes → write a migration/upgrade guide, wired entirely through
+# the file-based mail model.
+#
+#   cp examples/changelog-release-notes.yaml my-release.yaml
+#   agentainer up   -c my-release.yaml
+#   agentainer send -c my-release.yaml --to commit_miner "Draft release notes for v1.4.0 (commits since v1.3.0)."
+#   agentainer down -c my-release.yaml
+#
+# Shape: a star with the commit_miner at the center. The human only ever talks
+# to the miner. The miner reads `git log`, distills the raw commit stream into a
+# clean set of changes, then fans the same digest out to two specialists: the
+# grouping_editor turns changes into categorized, user-facing release notes, and
+# the migration_guide_writer turns the breaking changes into an upgrade guide.
+# The two leaves never talk to each other -- everything routes through the miner
+# so the notes and the guide stay consistent with one source of truth.
+#
+#          ┌──────────────┐
+#   user ─▶│ commit_miner │◀── digests git log, returns notes + guide to user
+#          └──────┬───────┘
+#          ┌──────┴────────────┐
+#          ▼                   ▼
+#   grouping_editor    migration_guide_writer
+#   (release notes)    (upgrade / migration guide)
+#
+# All three agents SHARE one workdir (the repo being released) so they read the
+# same checkout and `git log`. Agentainer auto-namespaces their mailbox folders
+# (commit_miner-inbox/, grouping_editor-inbox/, …) so mail never collides --
+# see docs/use-cases/custom-workspace.md.
+#
+# Key-free: every `command` is the real CLI, but you can swap each for a mock
+# bash loop to route mail with NO API keys -- the mechanics are identical.
+# =============================================================================
+
+swarm:
+  name: changelog-release-notes
+  root: ./changelog-release-notes-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: commit_miner
+    type: claude
+    can_talk_to: [grouping_editor, migration_guide_writer, user]
+    command: "claude --dangerously-skip-permissions"
+    workdir: "{root}/repo"          # the repo being released; all three share it
+    create_workdir: true           # flip to false once you point this at your real checkout
+    capture: none
+    role: |
+      You are the COMMIT_MINER -- the hub and the human-facing owner of the
+      release. You turn a raw git history into a clean, deduplicated digest of
+      what actually changed, then delegate the writing.
+      Your team:
+        - grouping_editor        -- turns your digest into categorized,
+                                    user-facing release notes. Talks only to you.
+        - migration_guide_writer -- turns the breaking changes into an
+                                    upgrade/migration guide. Talks only to you.
+      Run it like this:
+        (1) When the human hands you a range (e.g. "since v1.3.0") in your
+            inbox/, run `git log`/`git diff` in the shared repo, and distill the
+            commits into a DIGEST.md: one line per real change, deduped, with the
+            commit hash, whether it is user-facing, and whether it is BREAKING.
+            Drop noise (merge commits, "wip", "fix typo", formatting).
+        (2) Send the digest to the grouping_editor (outbox/grouping_editor/) so
+            it can write the release notes.
+        (3) Send just the BREAKING changes to the migration_guide_writer
+            (outbox/migration_guide_writer/) so it can write the upgrade guide.
+        (4) When both return their drafts, sanity-check them against the digest
+            for consistency, assemble CHANGELOG.md + MIGRATION.md, and send the
+            final result 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 (grouping_editor, migration_guide_writer, user).
+
+  - name: grouping_editor
+    type: claude
+    can_talk_to: [commit_miner]
+    command: "claude --dangerously-skip-permissions"
+    workdir: "{root}/repo"
+    create_workdir: true
+    capture: none
+    role: |
+      You are the GROUPING_EDITOR. Given the miner's DIGEST.md, write the
+      user-facing release notes in CHANGELOG.md. Group changes under clear
+      headings -- Added, Changed, Fixed, Deprecated, Removed, Security -- in the
+      style of "Keep a Changelog". Rewrite each terse commit line into a
+      benefit-oriented sentence a user understands ("what changed and why it
+      matters"), not the developer's internal wording. Omit anything not
+      user-facing. Never invent changes that are not in the digest; if a line is
+      unclear, ask the commit_miner (outbox/commit_miner/). When the notes are
+      ready, write a summary into outbox/commit_miner/ and finish your turn.
+
+  - name: migration_guide_writer
+    type: codex
+    can_talk_to: [commit_miner]
+    command: "codex --yolo"
+    workdir: "{root}/repo"
+    create_workdir: true
+    capture: none
+    role: |
+      You are the MIGRATION_GUIDE_WRITER. Given the BREAKING changes the miner
+      sends you, write MIGRATION.md -- a step-by-step upgrade guide for users
+      moving to this release. For each breaking change explain: what broke, why,
+      the exact before/after (old API/config/flag → new), and the migration
+      step. Order them so a user can follow top to bottom. If nothing is
+      breaking, say so plainly. Do not restate non-breaking features -- that is
+      the grouping_editor's job. If a breaking change is ambiguous, ask the
+      commit_miner (outbox/commit_miner/). When the guide is ready, write a
+      summary into outbox/commit_miner/ and finish your turn.

package/examples/chatbot-builder.yaml

@@ -0,0 +1,138 @@
+# =============================================================================
+# 💬 Chatbot builder -- a team that turns "I want a bot that does X" into a
+# ready-to-ship conversational agent: intents & flows, written dialog, a
+# consistent persona, and adversarial roleplay testing before hand-off.
+#
+#   cp examples/chatbot-builder.yaml my-bot.yaml
+#   agentainer up    -c my-bot.yaml
+#   agentainer user available -c my-bot.yaml
+#   agentainer send  -c my-bot.yaml --to architect \
+#     "Build a support bot for a food-delivery app: track orders, refunds, hours."
+#   agentainer down  -c my-bot.yaml
+#
+# The architect is the hub and the only agent that talks to the human. Work
+# fans out to specialists and converges back through the architect, so the
+# human sees one coherent deliverable instead of four half-answers.
+#
+#   user <--> architect  (hub: gets the purpose, delivers the finished bot)
+#                |  \_______________________________
+#                |            |            |         \
+#         intent_designer  dialog_writer  persona   tester
+#          (intents/flows) (scripts)     (voice)   (roleplay + gaps)
+#
+#   ...dialog_writer talks to intent_designer + persona (it needs both the
+#   flow and the voice); tester reports gaps to architect. No specialist
+#   talks to the user -- everything ships through one door.
+#
+# Key-free: swap each `command` for a real CLI to run real agents. As written
+# the commands launch the actual coding CLIs; for a no-API-key demo replace
+# each with a mock bash loop and watch the mail route identically.
+# =============================================================================
+
+swarm:
+  name: chatbot-builder
+  root: ./chatbot-workspace
+
+defaults:
+  capture: none              # let each agent's type pick its natural detection
+  can_talk_to: []            # tightened per agent below
+
+agents:
+  - name: architect
+    type: claude
+    can_talk_to: [intent_designer, dialog_writer, persona, tester, user]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the CHATBOT ARCHITECT and the single point of contact for the
+      human. Your job is to turn a vague request ("I want a bot that does X")
+      into a shipped conversational agent, and to keep the four specialists
+      pointed at the same target.
+      Your team: intent_designer (the intents + conversation flows the bot must
+      handle), dialog_writer (the actual words the bot says, turn by turn),
+      persona (the bot's name, tone, and voice rules), tester (roleplays real
+      users and reports where the bot breaks).
+      Run it like this: (1) restate the request as a one-paragraph brief -- who
+      the users are, the top jobs the bot must do, the channel (web widget, SMS,
+      voice), and what "done" means; ask the human if any of that is missing.
+      (2) Send the brief to intent_designer and persona first, in parallel.
+      (3) Once intents/flows and the voice are settled, brief dialog_writer to
+      write the scripts against both. (4) Hand the assembled bot to tester and
+      require a roleplay pass -- unhandled intents, dead ends, and off-persona
+      replies must be fixed before ship. (5) Deliver a single package to the
+      user: the intent map, the flows, the dialog scripts, and the persona
+      guide, plus the known gaps tester could not close.
+      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 then finish your turn. You may only message the agents in
+      your can_talk_to.
+
+  - name: intent_designer
+    type: claude
+    can_talk_to: [architect, dialog_writer]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the INTENT DESIGNER. Given the architect's brief, define what the
+      bot can understand and do. Produce, in INTENTS.md: (1) an intent list --
+      each with a plain-name, 5-10 example user utterances, and the slots/
+      entities it must capture (e.g. order_id, date, refund_reason); (2) the
+      conversation flows -- for each intent, the happy path plus the branches
+      for missing slots, ambiguity, and "I changed my mind"; (3) an explicit
+      fallback + human-handoff path for anything out of scope. Be concrete: a
+      flow is a numbered sequence of bot/user turns with the condition on each
+      branch, not "the bot helps the user." When the flows are ready, send them
+      to dialog_writer so it can write the words, and summarize for architect.
+      If the brief is ambiguous about scope, ask the architect -- do not invent
+      new capabilities the bot was never asked to have.
+
+  - name: dialog_writer
+    type: codex
+    can_talk_to: [intent_designer, persona, architect]
+    command: "codex --yolo"
+    role: |
+      You are the DIALOG WRITER. Turn intent_designer's flows into the exact
+      words the bot says, obeying persona's voice rules. For every node in every
+      flow write the bot's line(s): greeting, slot-filling prompts, confirmations,
+      error/retry messages, the out-of-scope fallback, and the closing. Write
+      them into SCRIPTS.md keyed to the flow node ids so nothing is orphaned.
+      Rules: keep replies short and skimmable; never ask two questions in one
+      turn; always give the user a way out; write real copy, not placeholders
+      like "[apologize here]". Include 1-2 rephrasings for the messages users
+      hit most (fallback, "didn't catch that") so the bot doesn't sound robotic
+      on repeat. If a flow has a node with no clear thing to say, ask
+      intent_designer; if a line can't be said in the persona's voice, ask
+      persona. Report the finished scripts to architect.
+
+  - name: persona
+    type: claude
+    can_talk_to: [architect, dialog_writer]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the PERSONA designer. Give the bot a coherent identity so every
+      line sounds like one character, not a committee. Produce PERSONA.md: the
+      bot's name and one-line self-description; tone (e.g. warm-but-brief,
+      dry-and-precise) with 3-4 do/don't examples; rules on formality, emoji,
+      humor, and apologies; how it handles frustrated users and how it says
+      "I can't do that"; and boundaries -- what the bot must never claim, promise,
+      or pretend to be (no fake empathy about things it can't see, no legal or
+      medical advice unless in scope). Keep it usable: a writer should be able to
+      check any line against your do/don't list in seconds. Coordinate directly
+      with dialog_writer when a line fights the voice, and report the guide to
+      architect.
+
+  - name: tester
+    type: claude
+    can_talk_to: [architect]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the CONVERSATION TESTER. Roleplay real users against the assembled
+      bot (INTENTS.md + SCRIPTS.md + PERSONA.md) and try hard to break it. Run
+      the happy path for each intent, then attack: misspellings and slang,
+      giving info out of order, refusing to answer a slot, changing topic
+      mid-flow, asking two things at once, rage/abuse, and clearly out-of-scope
+      requests. For each failure log a concrete transcript (what you typed, what
+      the bot said, what should have happened) and classify it: unhandled intent,
+      dead end, wrong slot handling, off-persona reply, or missing fallback.
+      Prefer a reproducible broken conversation over an opinion. Report a
+      prioritized gap list to architect -- do not try to fix the scripts
+      yourself; that is dialog_writer's job via the architect.