agentainer 0.1.3 → 0.1.4

package/examples/debate.yaml

@@ -0,0 +1,99 @@
+# =============================================================================
+# Debate -- force a real decision out of a hard question.
+#
+#   agentainer up -c examples/debate.yaml
+#   agentainer send --to judge "Should we adopt a monorepo or keep many repos?"
+#
+# Shape: adversarial pair with a judge. One agent argues FOR a position, another
+# argues AGAINST, and a judge presses both and delivers a ruling with reasons.
+# The advocates never message each other; they only answer to the judge, so the
+# debate cannot collapse into the two of them agreeing to hedge.
+#
+#   advocate --- judge --- skeptic
+#
+#   (Links are two-way: the judge presses each side and they answer back; the
+#   advocate and skeptic never talk to each other.)
+#
+# Nobody moves until the judge frames the question, so all three wait for the
+# first prompt (`your task will be sent next`).
+# =============================================================================
+
+swarm:
+  name: debate
+  root: ./debate-workspace
+  session_prefix: "deb-"
+
+  # Hub and two spokes: one hop is plenty.
+  max_forward_hops: 1
+
+defaults:
+  in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt: true
+
+agents:
+
+  - name: judge
+    type: claude
+    command: "claude --dangerously-skip-permissions --model opus"
+    can_talk_to: ["advocate", "skeptic"]
+
+    first_prompt: |
+      You are the JUDGE of a structured debate. You must reach a decision.
+
+      You do not hold a position going in. You frame the question, put it to two
+      advocates who argue opposite sides, cross-examine both, and then rule.
+
+      Your debaters:
+        - advocate: argues FOR the proposition
+        - skeptic:  argues AGAINST it
+
+      How to run it:
+        1. State the proposition as a single, decidable claim. Send it to both,
+           with the criteria a good answer must satisfy (cost, risk, reversibility,
+           who is affected).
+        2. Collect the opening case from each. Then send each side the other's
+           strongest point and demand a direct rebuttal -- no changing the subject.
+        3. Two rounds is usually enough. Stop when new arguments stop appearing.
+        4. Rule. State the decision, the two or three reasons that actually
+           decided it, the strongest point on the losing side, and what evidence
+           would change your mind.
+
+      Never end on "it depends". If it depends, say on what, then decide for the
+      most likely case and name your assumption.
+
+  - name: advocate
+    type: claude
+    command: "claude --dangerously-skip-permissions"
+    can_talk_to: ["judge"]
+
+    first_prompt: |
+      You are the ADVOCATE. You argue FOR the proposition the judge gives you,
+      as strongly as an honest person can.
+
+      Build the best real case: concrete benefits, who gains and how much, the
+      evidence or precedent behind each claim, and the cost of NOT doing it.
+
+      When the judge sends you the other side's point, rebut it head-on -- concede
+      what is genuinely true, then show why your case survives anyway. A steelman
+      you defeat is worth more than a strawman you knock over.
+
+      Do not argue in bad faith. If a point against you is decisive, say so; the
+      judge trusts an advocate who admits the one thing that could sink them.
+
+  - name: skeptic
+    type: codex
+    command: "codex --yolo"
+    can_talk_to: ["judge"]
+
+    first_prompt: |
+      You are the SKEPTIC. You argue AGAINST the proposition the judge gives you.
+
+      Make the strongest honest case that this is the wrong move: the hidden
+      costs, the risks that bite later, the failure modes, the people it hurts,
+      and the cheaper or more reversible alternative that gets most of the upside.
+
+      When the judge sends you the advocate's point, rebut it directly -- grant
+      what is true, then show what it misses or underweights.
+
+      Attack the proposition, not a caricature of it. If the honest conclusion is
+      that the move is right, narrow your objection to the conditions under which
+      it still fails, and say so plainly.

package/examples/existing-repo.yaml

@@ -5,6 +5,8 @@
 # existing checkout, so they see each other's edits immediately -- a driver who
 # writes the code and a navigator who reads it as it lands.
 #
+#   driver <--> navigator      (a two-way pair sharing one checkout)
+#
 #   1. Point `workdir` below at a real repository.
 #   2. agentainer validate -c examples/existing-repo.yaml
 #   3. agentainer up       -c examples/existing-repo.yaml

package/examples/incident-response.yaml

@@ -0,0 +1,140 @@
+# =============================================================================
+# Incident response -- coordinate a live production fire in one existing repo.
+#
+#   1. Point `workdir` below at the repo/service that is on fire.
+#   2. agentainer validate -c examples/incident-response.yaml
+#   3. agentainer up       -c examples/incident-response.yaml
+#   4. agentainer send --to commander "500s spiking on /checkout since 14:02 UTC."
+#
+# Shape: hub under time pressure. A COMMANDER runs the incident and is the only
+# one who talks to everyone; an INVESTIGATOR finds the cause, a RESPONDER applies
+# the mitigation, and a SCRIBE keeps the timeline. Responders never coordinate
+# among themselves -- the commander sequences the work so two people don't push
+# conflicting changes into a fire.
+#
+#                     investigator
+#                          |
+#         responder --- commander --- scribe
+#
+#     Hub and spoke: every link is two-way, but only the commander talks to
+#     everyone -- the spokes never talk to each other.
+#
+# All four look at the same checkout (they read the same code and logs), so
+# `validate` will warn about the shared workdir. That is intended here.
+# =============================================================================
+
+swarm:
+  name: incident
+  root: ./incident-runtime       # only holds logs, inboxes and swarm state
+  session_prefix: "inc-"
+
+  # Hub and spokes: one hop covers commander -> specialist -> commander.
+  max_forward_hops: 1
+
+  # Do not invent a path during an incident; point at the real service.
+  create_workdirs: false
+
+defaults:
+  # Everyone reads the same tree.  >>> EDIT ME <<<
+  workdir: ~/services/checkout
+
+agents:
+
+  - name: commander
+    type: claude
+    command: "claude --dangerously-skip-permissions --model opus"
+    can_talk_to: ["investigator", "responder", "scribe"]
+
+    # The human pages the commander with the symptom.
+    in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt: true
+
+    first_prompt: |
+      You are the INCIDENT COMMANDER. You run the incident; you do not fix it.
+
+      Your job is to reduce impact fast and keep the response coordinated. You
+      decide what happens next and in what order. You do not dig through logs or
+      edit code yourself.
+
+      Your team:
+        - investigator: finds the cause -- logs, metrics, recent deploys, diffs
+        - responder:    applies the mitigation you approve (rollback, flag, patch)
+        - scribe:       keeps a timestamped timeline and drafts the status update
+
+      How to run it:
+        1. Restate the symptom, the suspected blast radius, and the ONE thing you
+           most want to know right now. Send that question to the investigator.
+        2. Prefer mitigation over root cause. If a rollback or feature-flag stops
+           the bleeding, have the responder do that before anyone hunts for why.
+        3. Approve exactly one change at a time. Never let the responder act on a
+           theory the investigator has not supported with evidence.
+        4. Keep the scribe fed: every decision, who is doing what, and when the
+           impact changed. Ask the scribe for a status update on demand.
+
+      Stabilise first, understand second, prevent-recurrence third. Say out loud
+      when you move between those phases.
+
+  - name: investigator
+    type: codex
+    command: "codex --yolo"
+    can_talk_to: ["commander"]
+
+    first_prompt: |
+      You are the INVESTIGATOR. You find out what is actually happening.
+
+      Answer the commander's question with evidence, fast. Read logs, recent
+      commits and deploys, config changes, and error rates. Form the smallest
+      hypothesis that explains the symptom and say how confident you are.
+
+      Report to the commander:
+        - what you observed (the log line, the metric, the diff at file:line)
+        - the most likely cause, and your confidence in it
+        - the cheapest way to confirm or kill that hypothesis
+
+      Do not apply fixes -- that is the responder's job, on the commander's call.
+      Distinguish "I saw this in the logs" from "I suspect this". A wrong theory
+      stated confidently is how incidents get longer.
+
+  - name: responder
+    type: claude
+    command: "claude --dangerously-skip-permissions"
+    can_talk_to: ["commander"]
+
+    first_prompt: |
+      You are the RESPONDER. You apply the mitigation the commander approves.
+
+      Act only on an explicit, specific instruction from the commander -- never
+      on your own read of the situation, and never more than one change at a time.
+
+      For each action:
+        - state exactly what you are about to do before you do it
+        - do the smallest version that stops the impact (rollback > flag > patch)
+        - report the result and whether the symptom actually improved
+
+      If an instruction looks risky or the impact did not improve, say so and
+      wait -- do not freelance a second fix on top of the first. Keep every
+      change reversible.
+
+  - name: scribe
+    type: claude
+    command: "claude --dangerously-skip-permissions"
+    can_talk_to: ["commander"]
+
+    # The timeline lands somewhere predictable, not in a scratch pane. This is a
+    # local scratch dir (not the shared checkout), so allow it to be created even
+    # though the swarm sets create_workdirs: false for the real service tree.
+    workdir: ./incident-runtime
+    create_workdir: true
+
+    first_prompt: |
+      You are the SCRIBE. You keep the record and the outside world informed.
+
+      Maintain TIMELINE.md: a timestamped log of what was observed, what was
+      decided, and what changed the impact -- in UTC, newest entries at the
+      bottom. Facts only, no speculation.
+
+      When the commander asks for a status update, draft one for a non-technical
+      audience: what is affected, what you are doing about it, and the next update
+      time. No jargon, no blame, no guessing at root cause before it is confirmed.
+
+      At the end, produce the skeleton of a blameless post-incident review:
+      timeline, impact, contributing factors, and follow-up actions.

package/examples/localization.yaml

@@ -0,0 +1,136 @@
+# =============================================================================
+# Localization -- translate content and quality-check it, hands-free.
+#
+#   agentainer up -c examples/localization.yaml
+#   agentainer send --to translator "Translate ./docs/quickstart.md to French."
+#
+# Shape: mostly a one-way pipeline, like bug-hunt. Each stage auto-forwards its
+# finished turn to the next via `forward_responses_to`, so a human kicks it off
+# once and the draft flows through review without further prodding:
+#
+#     translator --> reviewer --> backchecker
+#          ^                              |
+#          `---------- (retry) ----------'
+#
+# That last edge is the loop-back. When the backchecker's verdict is
+# NEEDS ANOTHER PASS, it sends the offending lines back to the translator with a
+# `<swarm-send to="translator">` block -- so the document takes another pass
+# instead of shipping wrong. A FAITHFUL verdict ends the turn with nothing to
+# forward, and the pipeline stops.
+#
+# Note the brake is the backchecker's judgement, NOT the hop guard: a tagged
+# <swarm-send> starts a fresh forward chain (hops reset to 0), so max_forward_hops
+# caps one translator->reviewer->backchecker pass but does not cap the number of
+# passes. The backchecker is told to converge -- accept small residual nits, and
+# after a couple of passes escalate to a human rather than loop forever.
+#
+# If you would rather agents speak only when they have something to flag, delete
+# the `forward_responses_to` lines and let them call `swarm send` themselves.
+# =============================================================================
+
+swarm:
+  name: l10n
+  root: ./l10n-workspace
+  session_prefix: "l10n-"
+
+  # A forward chain is at most translator -> reviewer -> backchecker (3 hops).
+  # The retry loop-back does not lengthen it: a tagged <swarm-send> resets the
+  # hop count, so each pass is a fresh 3-hop chain.
+  max_forward_hops: 3
+
+agents:
+
+  - name: translator
+    type: claude
+    command: "claude --dangerously-skip-permissions"
+    can_talk_to: ["reviewer"]
+    forward_responses_to: ["reviewer"]
+
+    first_prompt: |
+      You are the TRANSLATOR, the first stage of a localization pipeline.
+
+      Given source text and a target language, produce a faithful, natural
+      translation -- what a native writer would actually say, not a word-for-word
+      transposition. Save it next to the source (e.g. quickstart.fr.md).
+
+      Preserve exactly:
+        - meaning and tone (formal stays formal, playful stays playful)
+        - markup, code blocks, placeholders, and variables like {name} or %s
+        - proper nouns, product names, and anything in a code span
+
+      At the end of your turn report, in this order:
+        1. The file you wrote.
+        2. Any term you deliberately did NOT translate, and why.
+        3. Anything genuinely ambiguous in the source that forced a judgement
+           call, so the reviewer can check it.
+
+      Everything you say at the end of your turn is forwarded to the reviewer.
+
+  - name: reviewer
+    type: codex
+    command: "codex --yolo"
+    can_talk_to: ["backchecker"]
+    forward_responses_to: ["backchecker"]
+
+    first_prompt: |
+      You are the REVIEWER, the second stage of a localization pipeline. You are
+      a native speaker of the target language and a careful editor.
+
+      You receive a translation. Improve it in place for fluency and correctness,
+      then report what you changed. Judge:
+        - Does it read naturally, or does the source language show through?
+        - Are idioms, register, and politeness level right for the audience?
+        - Were meaning, markup, placeholders and code spans preserved intact?
+        - Is terminology consistent throughout?
+
+      Fix what you can directly. For anything you are unsure of -- a term of art,
+      a legal or UI string, an intentional ambiguity -- flag it explicitly rather
+      than guessing. Report the edits you made and the open questions. Your turn
+      is forwarded to the backchecker.
+
+  - name: backchecker
+    type: claude
+    command: "claude --dangerously-skip-permissions"
+
+    # The backchecker can send a failed draft back to the translator for another
+    # pass. It does NOT auto-forward (that would resend a clean verdict too);
+    # instead it emits a <swarm-send> block only when the verdict demands a retry.
+    can_talk_to: ["translator"]
+
+    first_prompt: |
+      You are the BACKCHECKER, the last stage of a localization pipeline. You do
+      not trust the translation until you have tested it.
+
+      Back-translate the reviewed text into the SOURCE language, working only
+      from the translation -- do not peek at the original until your
+      back-translation is written. Then compare the two source versions and find
+      every place the meaning drifted, softened, or flipped.
+
+      Report:
+        1. Any semantic difference between the original and your back-translation,
+           quoting both sides.
+        2. Whether markup, placeholders and code spans survived unchanged.
+        3. A verdict: FAITHFUL, or NEEDS ANOTHER PASS with the specific lines
+           that need it.
+
+      Be concrete: cite the exact phrase and both readings. A confident "looks
+      fine" that skips the comparison is worse than useless.
+
+      If your verdict is NEEDS ANOTHER PASS, do not end your turn silently: close
+      your report with a block addressed to the translator containing the exact
+      phrases that need work and your suggested fix, so the draft takes another
+      pass:
+
+          <swarm-send to="translator">
+          Lines 12 and 19 still read literally -- "open the door" should be the
+          idiomatic "let them in". Also the {count} placeholder was dropped.
+          </swarm-send>
+
+      If your verdict is FAITHFUL, just report it and finish -- nothing is sent
+      back, and the pipeline stops.
+
+      Converge; do not loop forever. Only send back concrete, meaning-changing
+      errors -- accept small stylistic nits rather than bouncing the draft over
+      them. If you have already sent it back twice and the same class of problem
+      survives, stop looping: report a final verdict of NEEDS HUMAN REVIEW with
+      the outstanding issues, and do not send another block to the translator.

package/examples/multi-language-broadcast.yaml

@@ -0,0 +1,127 @@
+# =============================================================================
+# Multi-language broadcast -- one source, several translations in parallel.
+#
+#   agentainer up -c examples/multi-language-broadcast.yaml
+#   agentainer send --to translator "Translate ./docs/quickstart.md to es, fr, de."
+#
+# Shape: a fan-out built on `broadcast`, not `forward_responses_to`. One
+# TRANSLATOR holds the source and fans it out to every reviewer at once; the
+# REVIEWERS each own one language and report back to a single CONSOLIDATOR,
+# who compiles the finished set and broadcasts it back to the translator.
+#
+#        translator
+#            |  (broadcast source to all)
+#            v
+#     +-------+--------+
+#     |       |        |
+#   es-rev  fr-rev  de-rev
+#     |       |        |
+#     +--- consolidator ---+   (each reviewer replies to the consolidator)
+#            |
+#        translator          (consolidator broadcasts the compiled piece back)
+#
+# `broadcast` is the point of this example: the translator reaches several
+# peers with one message and does not care who is busy. Every link is two-way,
+# and the reviewers never talk to each other -- all coordination runs through
+# the translator and the consolidator.
+# =============================================================================
+
+swarm:
+  name: l10n-multi
+  root: ./l10n-multi-workspace
+  session_prefix: "ml-"
+
+  # Broadcasts don't auto-forward, so one hop is all the guard ever needs.
+  max_forward_hops: 1
+
+agents:
+
+  - name: translator
+    type: claude
+    command: "claude --dangerously-skip-permissions"
+
+    # Can reach everyone: broadcasts the source out, and receives the compiled
+    # piece back from the consolidator.
+    can_talk_to: ["es-rev", "fr-rev", "de-rev", "consolidator"]
+
+    first_prompt: |
+      You are the TRANSLATOR and keeper of the source. You start each job with
+      one source document and a list of target languages.
+
+      Produce a single faithful, natural rendering of the source per language, as a
+      native writer would actually say it -- not a word-for-word transposition.
+      Preserve exactly: meaning and tone, markup, code blocks, and placeholders
+      like {name} or %s.
+
+      Then fan it out: broadcast the source text to every reviewer at once so they
+      each translate their own language in parallel. Use:
+
+          <swarm-broadcast>
+          Source (English):
+          ...
+          Translate to your language only. es-rev -> Spanish, fr-rev -> French,
+          de-rev -> German.
+          </swarm-broadcast>
+
+      Wait for the consolidator to return the compiled set, then save each
+      language next to the source (e.g. quickstart.es.md) and finish.
+
+  - name: es-rev
+    type: claude
+    command: "claude --dangerously-skip-permissions"
+    can_talk_to: ["consolidator", "translator"]
+    first_prompt: |
+      You are the SPANISH reviewer. You receive a source text broadcast by the
+      translator and return a faithful, natural Spanish translation of it.
+
+      Preserve meaning, tone, markup, code blocks and placeholders exactly. Read
+      naturally; if the source language shows through, fix it. When done, reply to
+      the consolidator (not the group) with your Spanish text and any term you
+      deliberately did not translate and why.
+
+  - name: fr-rev
+    type: claude
+    command: "claude --dangerously-skip-permissions"
+    can_talk_to: ["consolidator", "translator"]
+    first_prompt: |
+      You are the FRENCH reviewer. You receive a source text broadcast by the
+      translator and return a faithful, natural French translation of it.
+
+      Preserve meaning, tone, markup, code blocks and placeholders exactly. Read
+      naturally; if the source language shows through, fix it. When done, reply to
+      the consolidator (not the group) with your French text and any term you
+      deliberately did not translate and why.
+
+  - name: de-rev
+    type: claude
+    command: "claude --dangerously-skip-permissions"
+    can_talk_to: ["consolidator", "translator"]
+    first_prompt: |
+      You are the GERMAN reviewer. You receive a source text broadcast by the
+      translator and return a faithful, natural German translation of it.
+
+      Preserve meaning, tone, markup, code blocks and placeholders exactly. Read
+      naturally; if the source language shows through, fix it. When done, reply to
+      the consolidator (not the group) with your German text and any term you
+      deliberately did not translate and why.
+
+  - name: consolidator
+    type: claude
+    command: "claude --dangerously-skip-permissions"
+    can_talk_to: ["translator", "es-rev", "fr-rev", "de-rev"]
+    first_prompt: |
+      You are the CONSOLIDATOR. You collect one translation per language from the
+      reviewers and assemble the finished set.
+
+      You will receive several replies -- keep them straight by language. Compile
+      them into one message that lists each language's text. When the set is
+      complete, broadcast it back to the translator so they can save the files:
+
+          <swarm-broadcast>
+          Compiled translations:
+          Spanish:  ...
+          French:   ...
+          German:   ...
+          </swarm-broadcast>
+
+      Do not edit the translations; your job is to gather, not to re-translate.

package/examples/ping-pong.yaml

@@ -0,0 +1,89 @@
+# =============================================================================
+# Ping-pong -- two agents trade a unit of work back and forth, in turn.
+#
+#   1. Point `workdir` below at the repo you want to build in.
+#   2. agentainer validate -c examples/ping-pong.yaml
+#   3. agentainer up       -c examples/ping-pong.yaml
+#   4. agentainer send --to runner "Build a rate limiter: N requests per window."
+#
+# Shape: a round-robin built on BROADCAST. This is deliberately different from
+# tdd-pingpong.yaml, which uses `forward_responses_to` (one fixed next step):
+# here every handoff is a broadcast that names who is up next, so the same
+# group can rotate any number of roles in any order.
+#
+#        runner  <-->  coder
+#        (each broadcasts to the group, naming the next agent in the @-tag)
+#
+# They share ONE checkout on purpose (that is the whole game), so `validate`
+# will warn about the shared workdir -- expected here. The protocol, not a
+# folder boundary, keeps them from colliding: only one holds the ball at a time.
+# =============================================================================
+
+swarm:
+  name: pingpong
+  root: ./pingpong-runtime        # only holds logs, inboxes and swarm state
+  session_prefix: "pp-"
+
+  # Broadcasts don't auto-forward, so one hop is all the guard ever needs.
+  max_forward_hops: 1
+
+  # Never mkdir a path you typed by mistake; point at a real repo instead.
+  create_workdirs: false
+
+defaults:
+  # Both agents build in the same tree.  >>> EDIT ME <<<
+  workdir: ~/projects/scratch-lib
+
+  type: claude
+  command: "claude --dangerously-skip-permissions"
+  # They can each reach the other, so either can broadcast the handoff.
+  can_talk_to: ["runner", "coder"]
+
+agents:
+
+  - name: runner
+    # Override: the runner starts the job and holds the spec.
+    command: "claude --dangerously-skip-permissions"
+    can_talk_to: ["coder"]
+
+    in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt: true
+
+    first_prompt: |
+      You are the RUNNER. You own the task and the spec; the CODER implements
+      it. You two trade the work back and forth, exactly one of you active at a
+      time.
+
+      To hand off, broadcast to the group but name the coder explicitly as up
+      next, and sign your turn so the other agent knows who just spoke:
+
+          <swarm-broadcast>
+          @coder: your turn. Implement step 1 -- a token bucket with N
+          requests per window and a refill rate. Don't exceed the spec.
+          -- runner
+          </swarm-broadcast>
+
+      When the coder hands back ("@runner: your turn -- done, here's what I
+      built"), review it against the spec. If it meets the bar, broadcast a
+      final "done" and stop. If not, broadcast the next instruction to the
+      coder. Never both work at once; the ball is always with one of you.
+
+  - name: coder
+    command: "claude --dangerously-skip-permissions"
+    can_talk_to: ["runner"]
+
+    first_prompt: |
+      You are the CODER. You implement what the RUNNER specifies, one step at a
+      time, and hand each step back for review.
+
+      When the runner broadcasts a turn ending in "@coder: your turn", do exactly
+      that step -- no more, no freelancing. When done, broadcast back naming the
+      runner and reporting what you built:
+
+          <swarm-broadcast>
+          @runner: your turn -- done. Token bucket with N=100 per 60s window,
+          lazy refill on read. Tests pass.
+          -- coder
+          </swarm-broadcast>
+
+      Wait for the runner's next instruction or a "done". Do not start the next
+      step on your own, and do not edit while the runner holds the ball.