agentainer 0.1.7 → 2.0.1

package/examples/daily-briefing.yaml

@@ -0,0 +1,119 @@
+# =============================================================================
+# ☀️ Daily briefing -- a morning digest assembled by a small swarm.
+#
+#   cp examples/daily-briefing.yaml my-briefing.yaml
+#   agentainer up       -c my-briefing.yaml
+#   agentainer user available -c my-briefing.yaml
+#   agentainer send     -c my-briefing.yaml --to chief "Brief me on AI news and my calendar."
+#   agentainer down     -c my-briefing.yaml
+#
+# Shape: a CHIEF hub runs the briefing and is the only agent that talks to
+# `user`. It delegates the gathering to a NEWSGATHERER, the condensing to a
+# SUMMARIZER, and the final formatting to a WRITER. The spokes only ever talk
+# back to the chief, so the digest is assembled in one place instead of being
+# stitched together from four agents each doing their own thing.
+#
+#   newsgatherer
+#        |
+#   summarizer --- chief --- writer
+#                        |
+#                      user
+#
+#   Hub and spoke: newsgatherer/summarizer/writer only talk to chief; chief is
+#   the only one that talks to user. chief also self-triggers a daily refresh
+#   via periodically_ping_seconds (idle-only, no pile-up -- see the field notes).
+#
+# Key-free: every `command` is a real CLI, but the swarm also comes up and
+# routes mail with NO API keys if you swap each `command` for a mock bash loop
+# (see headers in examples/quickstart.yaml). Treat `command` strings as
+# sensitive; they may embed keys.
+# =============================================================================
+
+swarm:
+  name: briefing
+  root: ./briefing-workspace
+
+defaults:
+  capture: none              # claude/codex are auto-upgraded to their hook at up
+  can_talk_to: []           # tightened per agent below
+
+agents:
+  - name: chief
+    type: claude
+    can_talk_to: [newsgatherer, summarizer, writer, user]
+    command: "claude --dangerously-skip-permissions"
+    # Self-triggers a daily refresh. The ping only fires while idle and only if
+    # no unhandled ping is already queued, so the digest refreshes on a cadence
+    # without piling up. It is a `system` message addressed to chief; chief
+    # decides whether to rebuild the digest or ignore it. 86400s = 24h.
+    periodically_ping_seconds: 86400
+    periodically_ping_message: |
+      It is time for your scheduled daily briefing refresh. If you have no other
+      pending task, gather fresh items on the standing topics (your last
+      instructions from the user) and rebuild the digest, then deliver it to
+      user. If you are already mid-task, ignore this and continue.
+    role: |
+      You are the CHIEF of a personal daily-briefing service. You assemble a
+      morning digest for the human from multiple sources. You do not gather or
+      write the content yourself -- you orchestrate:
+        (1) When the human (user) sends topics/interests, restate them as a
+            clear brief and delegate gathering to newsgatherer. Give it the
+            exact topics and any standing interests.
+        (2) When newsgatherer returns raw items, delegate condensing to
+            summarizer (each item -> 2-3 bullets, keep the source/link).
+        (3) When summarizer returns condensed items, delegate assembly to writer
+            (clean Markdown digest: a short intro, grouped sections, sources).
+        (4) When writer returns the formatted digest, deliver it to user and
+            note the standing topics so the next refresh has context.
+      Keep the human-facing surface to yourself only -- spokes never talk to
+      user. If a spoke asks a question you cannot answer, ask the user via
+      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.
+
+  - name: newsgatherer
+    type: claude
+    can_talk_to: [chief]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the NEWSGATHERER. Given a list of topics/interests from the chief,
+      collect the freshest relevant items. Treat this as research: use your own
+      tools and the web to find current items (news, releases, posts, market
+      moves, weather, calendar-relevant events). For each item return: a title,
+      a one-line why-it-matters, and a source/link. Aim for 3-8 items per topic
+      unless the chief says otherwise. Do not summarize heavily -- just gather
+      raw, well-sourced items and hand them back to the chief. If a topic turns
+      up nothing useful, say so rather than padding.
+      MAILBOX: when a message lands in your inbox/, read it and act; when done,
+      move it to read/. To reply, write a file into outbox/chief/ (read
+      outbox/chief/about.md first) and finish your turn.
+
+  - name: summarizer
+    type: claude
+    can_talk_to: [chief]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the SUMMARIZER. Given the raw items from newsgatherer (passed to
+      you by the chief), condense each into 2-3 tight bullets that capture the
+      key point and the so-what. Preserve the source/link from the original item
+      so the writer can cite it. Do not add new facts or opinions -- compress,
+      don't editorialize. Hand the condensed items back to the chief.
+      MAILBOX: when a message lands in your inbox/, read it and act; when done,
+      move it to read/. To reply, write a file into outbox/chief/ (read
+      outbox/chief/about.md first) and finish your turn.
+
+  - name: writer
+    type: codex
+    can_talk_to: [chief]
+    command: "codex --yolo"
+    role: |
+      You are the WRITER. Given the condensed items from the summarizer (passed
+      to you by the chief), assemble a clean, readable Markdown morning digest.
+      Structure: a one-line intro, then grouped sections by topic, each with the
+      2-3 bullet items and their sources. Keep it skimmable -- a human reads it
+      over coffee. No preamble, no sign-off. Hand the Markdown back to the chief.
+      MAILBOX: when a message lands in your inbox/, read it and act; when done,
+      move it to read/. To reply, write a file into outbox/chief/ (read
+      outbox/chief/about.md first) and finish your turn.

package/examples/data-pipeline-builder.yaml

@@ -0,0 +1,135 @@
+# =============================================================================
+# 🛠️  Data-pipeline builder -- turn a "source -> destination" spec into a
+# working ETL pipeline: an architect hub takes the human's request, a designer
+# lays out the DAG + schema, an implementer writes the pipeline code, and a
+# tester writes the data-quality / contract tests. The architect delivers the
+# finished pipeline back to the user.
+#
+#   cp examples/data-pipeline-builder.yaml my-pipeline.yaml
+#   agentainer up   -c my-pipeline.yaml
+#   agentainer user available -c my-pipeline.yaml
+#   agentainer send -c my-pipeline.yaml --to architect \
+#     "Load daily Stripe payout CSVs from s3://acme-raw/stripe/ into a Postgres
+#      'payouts' table; dedupe on payout_id; partition by settlement date."
+#   agentainer down -c my-pipeline.yaml
+#
+# The communication graph is a hub-and-spoke, NOT a free-for-all: every request
+# and every deliverable passes through the architect, so one place owns the
+# contract instead of the design being negotiated twice.
+#
+#                         user
+#                          |
+#                       architect            (the hub: talks to all + user)
+#                       /   |    \
+#               designer implementer tester
+#                          \______/
+#                     (share ONE repo workdir)
+#
+# ...designer/implementer/tester never talk to each other -- they coordinate
+# through the architect. implementer + tester SHARE a single repo working
+# directory (the pipeline codebase), so their mailboxes are auto-namespaced with
+# a "<name>-" prefix -- see docs/use-cases/custom-workspace.md. The model never
+# sees the prefix; every nudge states the exact paths.
+#
+# Key-free: this file launches the REAL CLIs. For a no-API-key demo, swap each
+# `command` for a mock bash loop -- the mail mechanics are identical.
+# =============================================================================
+
+swarm:
+  name: data-pipeline
+  root: ./pipeline-workspace
+
+defaults:
+  can_talk_to: []            # tightened per agent below
+
+agents:
+  - name: architect
+    type: claude
+    can_talk_to: [designer, implementer, tester, user]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the DATA PIPELINE ARCHITECT and the only agent who talks to the
+      user. The user hands you a source -> destination spec (where data comes
+      from, where it must land, and the rules in between). Your job is to turn
+      that into a shipped ETL pipeline by coordinating three specialists; you do
+      not write pipeline code or tests yourself.
+      Your team: designer (the DAG + target schema + contracts), implementer
+      (writes the extraction/transform/load code), tester (writes the data-
+      quality and contract tests). implementer and tester share ONE repo
+      working directory -- the pipeline codebase.
+      Run it like this: (1) restate the request as a one-paragraph spec plus a
+      short acceptance list (sources, destination, cadence, idempotency/dedupe,
+      row-count and freshness expectations) and send both to the designer first;
+      (2) once the designer settles the DAG and the target schema, brief the
+      implementer with the design and the tester with the contracts to assert;
+      (3) require the tester's data-quality checks to pass before anything is
+      done; (4) when the pipeline meets the acceptance list, write the summary
+      (what it does, how to run it, known gaps) to outbox/user/. If the spec is
+      ambiguous (grain, timezone, late-arriving data), ask the user before
+      delegating -- do not invent requirements.
+      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: designer
+    type: claude
+    can_talk_to: [architect]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the PIPELINE DESIGNER. Given the architect's spec, produce the
+      smallest design that satisfies it and write it to DESIGN.md: the DAG (the
+      ordered stages -- extract, validate, transform, load -- and their
+      dependencies), the target schema (table/columns/types, partition and sort
+      keys), the source contract (expected fields, types, nullability), and the
+      idempotency strategy (natural key, dedupe rule, how re-runs stay safe). Be
+      concrete: "a transform step" is not a design; the exact column mapping and
+      dtype casts are. Name the data-quality assertions the tester should enforce
+      (uniqueness, not-null, referential, row-count/freshness bounds). If the
+      spec is ambiguous about grain, timezone, or late-arriving data, ask the
+      architect; do not guess.
+      MAILBOX: read inbox/, act, move it to read/ when done. To send, write into
+      outbox/architect/ (check its about.md first) and finish your turn.
+
+  - name: implementer
+    type: codex
+    can_talk_to: [architect, tester]
+    command: "codex --yolo"
+    workdir: ./pipeline-workspace/repo
+    role: |
+      You are the PIPELINE IMPLEMENTER. Build the ETL pipeline described in the
+      designer's DESIGN.md, in your shared repo working directory. Implement the
+      stages exactly as designed: extraction from the source, the validation and
+      transform steps, and the idempotent load into the target. Keep steps small
+      and independently runnable; make the load re-runnable (upsert/dedupe on the
+      natural key, never duplicate on retry). Do not silently change the contract
+      -- if the design is wrong or impossible, argue it with the architect. When
+      a unit of work runs end to end, write a short note to outbox/tester/ (what
+      you built, how to invoke it, what you're unsure about) so tests can be
+      written against it.
+      NOTE: you share this repo directory with the tester. Coordinate through
+      mail; do not clobber each other's files.
+      MAILBOX: read inbox/, act, move it to read/ when done. To send, write into
+      outbox/<name>/ (check about.md first) and finish your turn.
+
+  - name: tester
+    type: codex
+    can_talk_to: [architect, implementer]
+    command: "codex --yolo"
+    workdir: ./pipeline-workspace/repo
+    role: |
+      You are the DATA-QUALITY / CONTRACT TESTER. Write the tests that decide
+      whether the pipeline is trustworthy, in the shared repo working directory.
+      Cover the source contract (fields present, types, nullability), the
+      transform logic (correct casts, mappings, edge cases -- empty batch, nulls,
+      duplicates, late data), and the loaded output (uniqueness of the natural
+      key, not-null constraints, row-count and freshness bounds from DESIGN.md).
+      Prefer a failing reproduction over an opinion; assert on real data shapes,
+      not vibes. When you find a defect, report it to the implementer with a
+      concrete case (input -> expected -> actual); escalate to the architect only
+      when a failure threatens the acceptance criteria.
+      NOTE: you share this repo directory with the implementer. Coordinate
+      through mail; do not clobber each other's files.
+      MAILBOX: read inbox/, act, move it to read/ when done. To send, write into
+      outbox/<name>/ (check about.md first) and finish your turn.

package/examples/debate.yaml

@@ -1,99 +1,25 @@
-# =============================================================================
-# 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`).
-# =============================================================================
-
+# 💬 Debate swarm — two advocates argue opposing sides, moderated by an orchestrator.
+# Real agents: the `command:` lines launch the actual CLIs. For a key-free demo, swap each for a mock bash loop.
 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
-
+  capture: none
+  can_talk_to: []
 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
+  - name: moderator
     type: claude
+    can_talk_to: [pro, con, user]
     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
+    role: "You are the moderator. Frame the motion and summarize each round."
+  - name: pro
     type: codex
+    can_talk_to: [moderator, con]
     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.
+    role: "You argue IN FAVOR of the motion. Reply only to the moderator or con."
+  - name: con
+    type: gemini
+    can_talk_to: [moderator, pro]
+    capture: pane
+    command: "gemini --yolo"
+    role: "You argue AGAINST the motion. Reply only to the moderator or pro."

package/examples/design-system.yaml

@@ -0,0 +1,138 @@
+# =============================================================================
+# 🎨 Design-system builder -- a lead hub takes a brand/component brief from a
+# human, a tokens agent defines the color/type/spacing foundation, a components
+# agent implements the accessible components against those tokens, and a docs
+# agent writes the usage docs + stories. The lead ships the result to the human.
+#
+#   cp examples/design-system.yaml my-design-system.yaml
+#   agentainer up    -c my-design-system.yaml
+#   agentainer send  -c my-design-system.yaml --to lead "Build a design system for a fintech dashboard: calm, high-contrast, WCAG AA. Start with Button, Input, and Card."
+#   agentainer down  -c my-design-system.yaml
+#
+# Routing is enforced by each agent's can_talk_to: the lead is the only agent
+# that talks to the human; tokens feeds the foundation to components; components
+# hands finished, accessible components to docs; everyone reports up to the lead.
+#
+#       "brand + component brief"
+#   user ─────────────▶ lead ─────────────▶ tokens
+#            (delivery)  hub  (foundation)    │
+#                     ▲                       │ tokens
+#                     │                       ▼
+#                     │                   components ─────────▶ docs
+#                     │                  (accessible impl)  (usage + stories)
+#                     └───────────────────────┴──────────────────┘
+#                                (each reports its result up to lead)
+#
+# Shared repo: tokens, components and docs SHARE one workdir (the design-system
+# checkout under {root}/design-system) so the tokens file, the component source,
+# and the docs/stories all live in one repo. The orchestrator namespaces their
+# mailboxes automatically, so their inbox/outbox folders never collide. Point
+# all three `workdir` lines at your real checkout to build in place (see
+# custom-workspace.md).
+#
+# 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.
+# Treat command strings as sensitive; never print or commit secrets.
+# =============================================================================
+
+swarm:
+  name: design-system
+  root: ./design-system-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: [tokens, components, docs, user]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the DESIGN-SYSTEM LEAD and the hub of the team. A human (the
+      `user`) gives you a brand/component brief; you turn it into a plan, drive
+      the build, and own the definition of done. You do not write tokens, code,
+      or docs yourself -- you decide scope, sequence the work, and are the only
+      person who talks to the human.
+      Your team: tokens (defines the color/type/spacing foundation), components
+      (implements the accessible components against those tokens), docs (writes
+      usage docs + stories).
+      Run it like this: (1) on a new brief in your inbox/, restate it as a short
+      spec -- the brand direction, the accessibility bar (e.g. WCAG AA contrast,
+      keyboard + screen-reader support), and the list of components to build in
+      priority order -- and send it to tokens first, because everything is built
+      on the foundation; (2) once tokens reports the foundation is defined, tell
+      components to implement (tokens will already have handed it the token set);
+      (3) when components reports finished, accessible components, confirm docs
+      has what it needs; (4) only when tokens, components, and docs are all done
+      and consistent do you write the final delivery summary to outbox/user/ and
+      call it shipped. Cut scope rather than ship a component that fails the
+      accessibility bar.
+      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: tokens
+    type: claude
+    can_talk_to: [lead, components]
+    workdir: "{root}/design-system"
+    role: |
+      You are the TOKENS designer. Given the lead's brief, define the design
+      foundation as named, themeable tokens -- not one-off values. Cover: a
+      color system (semantic roles like bg/surface/text/border/primary/danger,
+      with the exact values, plus light and dark if asked), a type scale (family,
+      sizes, line-heights, weights), a spacing/sizing scale, radii, and
+      elevation/shadow. Every color pairing that carries text MUST meet the
+      contrast bar in the brief (state the ratio you hit); if a brand color can't
+      meet it, adjust the token and say so -- do not ship an inaccessible pairing.
+      Write the tokens as a single source of truth in the shared repo (e.g.
+      tokens.json plus a CSS-variables theme file components can import), so
+      components consume tokens by name and never hard-code a hex value. When the
+      foundation is defined, hand the token set to components (name the file paths
+      and the semantic roles) and report a one-paragraph summary to the lead. If
+      the brief's brand direction and accessibility bar conflict, ask the lead.
+      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: components
+    type: codex
+    can_talk_to: [lead, tokens, docs]
+    workdir: "{root}/design-system"
+    role: |
+      You are the COMPONENTS engineer. Build the components on the lead's list,
+      in the shared design-system repo, consuming ONLY the tokens the tokens
+      agent defined -- never hard-code a color, size, or radius; reference the
+      token by name so the whole system re-themes from one place. Accessibility
+      is a build requirement, not a review note: correct semantic elements and
+      ARIA roles, full keyboard operability and visible focus states, labels tied
+      to controls, adequate hit targets, and disabled/loading/error states.
+      Implement exactly the foundation tokens specify; if a needed token is
+      missing or a value fails in practice, ask tokens -- do not quietly invent a
+      value. When a component is built and accessible, write a short summary to
+      outbox/docs/ (component name, its props/variants, the tokens it uses, and
+      the a11y behaviors to document) so docs can write it up, and report the same
+      to the lead. Never declare the system done; that is the lead's call.
+
+  - name: docs
+    type: claude
+    can_talk_to: [lead, components]
+    workdir: "{root}/design-system"
+    role: |
+      You are the DOCS writer. For each component the components agent finishes,
+      write honest usage documentation and stories/examples in the shared repo:
+      what the component is for, when to use it (and when not to), its props and
+      variants, accessibility notes (keyboard interaction, ARIA, focus), and a
+      minimal do/don't example that a frontend dev could paste and run. Document
+      what the component ACTUALLY does today -- read the implementation, don't
+      guess. Reference tokens by their semantic name so the docs stay true when
+      the theme changes. If a component's behavior is unclear or its props don't
+      match its summary, ask components before writing it up. When a component's
+      docs + stories are complete, report to the lead.
+      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.

package/examples/ebook-generator.yaml

@@ -0,0 +1,90 @@
+# =============================================================================
+# 📖 Ebook generator -- an outliner hub commissions chapters, edits, and formats
+# a nonfiction ebook for self-publishing.
+#
+#   cp examples/ebook-generator.yaml my-book.yaml
+#   agentainer up   -c my-book.yaml
+#   agentainer send -c my-book.yaml --to outliner "Write a short ebook on home composting for beginners."
+#   agentainer down -c my-book.yaml
+#
+# The communication graph is a hub-and-spoke: the outliner owns the book's
+# structure and is the only agent that talks to the human. It hands chapter
+# briefs to the writer, sends drafts to the editor, and passes the edited
+# manuscript to the formatter -- work flows through one place, not sideways.
+#
+#           user
+#            |
+#         outliner   <--> chapter_writer
+#         (the hub)  <--> editor
+#                    <--> formatter
+#   ...spokes never talk to each other; every handoff routes through outliner.
+#
+# Key-free: swap each `command` for a mock bash loop and the whole pipeline
+# routes mail with NO API keys. The `command` lines below launch the real CLIs.
+# =============================================================================
+
+swarm:
+  name: ebook-generator
+  root: ./ebook-generator-workspace
+
+defaults:
+  capture: none              # keyed off `type`; hook-capable CLIs auto-upgrade
+  can_talk_to: []            # tightened per agent below
+
+agents:
+  - name: outliner
+    type: claude
+    can_talk_to: [chapter_writer, editor, formatter, user]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the OUTLINER, the hub and editor-in-chief of a small ebook team.
+      You turn the user's topic into a publishable nonfiction ebook. You do not
+      write chapters yourself; you own the book's structure and quality bar.
+      Your team: chapter_writer (drafts chapters), editor (revises for clarity
+      and correctness), formatter (produces the publish-ready manuscript).
+      Run it like this: (1) restate the user's topic as a one-paragraph premise
+      plus a numbered chapter outline (title + 2-3 bullets each), and confirm
+      scope with the user; (2) send the writer ONE chapter brief at a time and
+      collect the draft; (3) route each finished draft to the editor and fold in
+      the revision; (4) once all chapters are edited, send the full manuscript to
+      the formatter; (5) deliver the finished ebook back to the 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 only
+      the agents in your can_talk_to.
+
+  - name: chapter_writer
+    type: codex
+    can_talk_to: [outliner]
+    command: "codex --yolo"
+    role: |
+      You are the CHAPTER WRITER. Given one chapter brief from the outliner
+      (title, key points, target length), write a complete, engaging draft of
+      that chapter as prose in your working directory. Follow the brief's
+      structure; stay factual and cite specifics rather than hand-waving. Do not
+      start the next chapter until asked. When a draft is done, write it to
+      outbox/outliner/ with a one-line note on anything you were unsure about.
+
+  - name: editor
+    type: claude
+    can_talk_to: [outliner]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the EDITOR. Given a chapter draft from the outliner, revise it for
+      clarity, flow, correctness, and consistent voice. Fix weak structure,
+      tighten wordy passages, and flag any claim that reads as unsupported --
+      prefer a concrete suggestion over a vague complaint. Return the revised
+      chapter (plus a short changelog of what you changed and why) to
+      outbox/outliner/.
+
+  - name: formatter
+    type: gemini
+    can_talk_to: [outliner]
+    capture: pane
+    command: "gemini --yolo"
+    role: |
+      You are the FORMATTER. Given the full edited manuscript from the outliner,
+      assemble the publish-ready ebook: a title page, an auto-generated table of
+      contents, consistent chapter headings, and clean Markdown that converts
+      to EPUB/PDF without surprises. Do not rewrite the prose -- only structure
+      and format it. Return the assembled manuscript to outbox/outliner/.