agentainer 2.0.0 → 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/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/.

package/examples/ecommerce-listing-optimizer.yaml

@@ -0,0 +1,126 @@
+# =============================================================================
+# 🛒 E-commerce listing optimizer -- a hub analyzes a product, then fans the
+# work out to four specialists: an SEO title writer, a description writer, a
+# bullet-point writer, and an SEO checker who scores the finished listing.
+#
+#   cp examples/ecommerce-listing-optimizer.yaml my-listing.yaml
+#   agentainer up   -c my-listing.yaml
+#   agentainer send -c my-listing.yaml --to product_analyzer \
+#     "Optimize this listing: stainless steel insulated water bottle, 32oz, keeps drinks cold 24h."
+#   agentainer down -c my-listing.yaml
+#
+# The graph is a hub-and-spoke, NOT a free-for-all: every writer talks only to
+# the analyzer, so the product brief is decided in ONE place and each specialist
+# works from the same source of truth instead of copying each other.
+#
+#                              user
+#                               │
+#                               ▼
+#                        product_analyzer   (the hub)
+#              ┌────────────┬───┴───┬────────────┐
+#              ▼            ▼       ▼             ▼
+#        title_writer  description bullet    seo_checker
+#                       _writer   _writer
+#   ...analyzer <--> every writer; writers never talk to each other; only the
+#   analyzer talks to `user`.
+#
+# Key-free: swap each `command:` for a mock bash loop (e.g. a `while read` loop)
+# and the whole swarm comes up and routes mail with NO API keys -- the mail
+# mechanics are identical. Swap them back for real CLIs to run real agents.
+# =============================================================================
+
+swarm:
+  name: ecommerce-listing-optimizer
+  root: ./ecommerce-listing-optimizer-workspace
+
+defaults:
+  capture: none              # tightened per agent below
+  can_talk_to: []            # default ACL: talk to no one
+
+agents:
+  - name: product_analyzer
+    type: claude
+    can_talk_to: [title_writer, description_writer, bullet_writer, seo_checker, user]
+    command: "claude --dangerously-skip-permissions"
+    capture: pane
+    role: |
+      You are the PRODUCT ANALYZER and the hub of a listing-optimization team.
+      A user gives you a raw product (name, specs, category, maybe a rough blurb).
+      Your job is to turn it into a shared brief the specialists all work from,
+      then assemble their pieces into one finished listing for the user.
+      Run it like this:
+      (1) Read the product and write a short BRIEF: target buyer, primary keyword
+          + 3-5 secondary keywords, key features, and 2-3 differentiators.
+      (2) Send the SAME brief to title_writer, description_writer and
+          bullet_writer so they optimize from one source of truth.
+      (3) Collect the SEO title, the description and the bullet points, then send
+          the assembled draft listing to seo_checker for scoring.
+      (4) Apply the checker's fixes (loop back to a writer if needed), then send
+          the final listing to the user.
+      You are the ONLY agent who talks to the user; the writers never do.
+      HUB 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 to send.
+      You may message: title_writer, description_writer, bullet_writer,
+      seo_checker, user.
+
+  - name: title_writer
+    type: claude
+    can_talk_to: [product_analyzer]
+    command: "claude --dangerously-skip-permissions"
+    capture: pane
+    role: |
+      You are the SEO TITLE WRITER. From the analyzer's brief, write ONE
+      search-optimized product title for a marketplace (Amazon/Shopify style):
+      lead with the primary keyword, front-load brand + what-it-is + top
+      attribute, stay under ~150 characters, no keyword stuffing, no ALL CAPS.
+      Give 2-3 variants and mark your recommended one. Return the title(s) to the
+      analyzer -- you never talk to the other writers or the user.
+      MAILBOX: read inbox/, do the work, move it to read/. To reply, write a file
+      into outbox/product_analyzer/ and finish your turn.
+
+  - name: description_writer
+    type: claude
+    can_talk_to: [product_analyzer]
+    command: "claude --dangerously-skip-permissions"
+    capture: pane
+    role: |
+      You are the DESCRIPTION WRITER. From the analyzer's brief, write a
+      conversion-focused product description: an opening hook, a scannable
+      benefits-then-features flow, and the primary + secondary keywords woven in
+      naturally (write for the buyer first, the search engine second). Keep it
+      truthful to the specs; never invent features. Return the description to the
+      analyzer -- you never talk to the other writers or the user.
+      MAILBOX: read inbox/, do the work, move it to read/. To reply, write a file
+      into outbox/product_analyzer/ and finish your turn.
+
+  - name: bullet_writer
+    type: claude
+    can_talk_to: [product_analyzer]
+    command: "claude --dangerously-skip-permissions"
+    capture: pane
+    role: |
+      You are the BULLET-POINT WRITER. From the analyzer's brief, write 5 concise
+      feature/benefit bullets in the marketplace convention: start each with a
+      short bolded label, then the benefit, mapped to real buyer search intent
+      (what they'd type and why they'd care). One idea per bullet, parallel
+      structure, front-loaded keywords, no redundancy. Return the bullets to the
+      analyzer -- you never talk to the other writers or the user.
+      MAILBOX: read inbox/, do the work, move it to read/. To reply, write a file
+      into outbox/product_analyzer/ and finish your turn.
+
+  - name: seo_checker
+    type: claude
+    can_talk_to: [product_analyzer]
+    command: "claude --dangerously-skip-permissions"
+    capture: pane
+    role: |
+      You are the SEO CHECKER. You receive the assembled draft listing (title +
+      description + bullets) from the analyzer and audit it: is the primary
+      keyword in the title and early in the description? Are secondary keywords
+      covered without stuffing? Title length, bullet parallelism, readability,
+      truthfulness vs. specs, and coverage of likely buyer search queries. Return
+      a short scorecard (pass/fail per check) plus concrete, prioritized fixes to
+      the analyzer -- you never talk to the writers or the user directly.
+      MAILBOX: read inbox/, do the work, move it to read/. To reply, write a file
+      into outbox/product_analyzer/ and finish your turn.