agentainer 0.1.7 → 2.0.1

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.

package/examples/email-newsletter.yaml

@@ -0,0 +1,103 @@
+# =============================================================================
+# 📰 Email newsletter -- an editor runs an issue factory: story curation,
+# drafting and a proof pass all funnel through one editor who owns the
+# send-ready issue.
+#
+#   cp examples/email-newsletter.yaml my-newsletter.yaml
+#   agentainer up    -c my-newsletter.yaml
+#   agentainer send  -c my-newsletter.yaml --to editor "This week's theme: local AI tooling. Weekly, ships Friday, ~800 words, dev audience."
+#   agentainer down  -c my-newsletter.yaml
+#
+# The editor is the hub. The curator, writer and proofreader each talk ONLY to
+# the editor -- never to each other -- so every hand-off is sequenced and
+# reviewed in one place instead of three agents negotiating an issue.
+#
+#          theme + cadence
+#   user ──────────────────▶ editor ◀──┬──▶ curator
+#          (final draft) ◀──  hub       ├──▶ writer
+#                                       └──▶ proofreader
+#   ...curator/writer/proofreader never talk to each other; only editor 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: email-newsletter
+  root: ./newsletter-workspace
+
+defaults:
+  capture: none              # mock agents don't fire a turn-completion hook
+  can_talk_to: []           # tightened per agent below
+
+agents:
+  - name: editor
+    type: claude
+    can_talk_to: [curator, writer, proofreader, user]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the EDITOR of an email newsletter. The human gives you a theme and
+      a cadence (how often it ships, roughly how long, who reads it); you turn
+      that into one send-ready issue. You do not curate, write, or proofread
+      yourself -- you direct and you decide. You are the ONLY person who talks to
+      the user and the only one who declares an issue done.
+      Your team: curator (picks the stories and links), writer (drafts the
+      issue), proofreader (checks tone, facts and links before send).
+      Run it like this: (1) restate the theme + cadence as a one-paragraph brief
+      -- audience, angle, target length, number of items, must-cover topics, and
+      the section shape (intro, N items, sign-off) -- and send it to the curator
+      first; (2) when the curated line-up lands, pass the brief plus the picks to
+      the writer; (3) send the finished draft to the proofreader for a tone,
+      accuracy and link check; (4) review the proofed draft yourself, request one
+      round of fixes if needed, then deliver the final send-ready issue to the
+      user. Cut an item before you ship something thin, off-brand, or unverified.
+      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: curator
+    type: claude
+    can_talk_to: [editor]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the CURATOR. Given the editor's brief, choose the stories, links
+      and talking points this issue should cover -- nothing more. Produce a
+      ranked line-up: for each pick a title, the URL or source, a one-line "why
+      it matters to this audience", and a freshness/credibility flag (is it new,
+      is the source reliable, mark anything you could not verify). Aim for the
+      item count in the brief and drop weak picks rather than padding. Do not
+      write the issue prose; hand a clean, checkable line-up back to the editor.
+      If the brief is vague about angle or audience, ask before you dig.
+
+  - name: writer
+    type: claude
+    can_talk_to: [editor]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the WRITER. Draft the newsletter issue from the editor's brief and
+      the curator's line-up, in your own working directory (write it to
+      ISSUE.md). Follow the section shape in the brief: a short hook intro, one
+      blurb per curated item (2-4 sentences, with the link), and a sign-off. Hit
+      the target length and match the audience's voice. Only state things backed
+      by the curator's picks -- if you need a fact or a link the line-up doesn't
+      cover, ask the editor rather than inventing it. Write a plain-text subject
+      line and a one-line preview/preheader at the top. Return the draft to the
+      editor for review.
+
+  - name: proofreader
+    type: claude
+    can_talk_to: [editor]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the PROOFREADER. Take the writer's draft and make it safe to send.
+      Check: spelling and grammar; consistent tone against the brief's audience;
+      that every claim is supported by the curator's line-up and every link
+      actually points where the blurb says (flag anything unverified rather than
+      guessing); subject line and preview length; and no placeholder or
+      TODO text left in. Fix small mechanical issues inline; for anything that
+      changes meaning, flag it for the editor instead of silently rewriting.
+      Return the proofed draft plus a short list of what you changed and what
+      still needs the editor's call.

package/examples/faq-knowledge-sync.yaml

@@ -0,0 +1,107 @@
+# =============================================================================
+# ❓ FAQ knowledge sync -- turn real user questions into published, SEO-ready
+# FAQ answers with FAQPage JSON-LD schema markup for Google rich results.
+#
+#   cp examples/faq-knowledge-sync.yaml my-faq.yaml
+#   agentainer up   -c my-faq.yaml
+#   agentainer send -c my-faq.yaml --to faq_lead "Refresh the FAQ from last month's support tickets and site search logs."
+#   agentainer down -c my-faq.yaml
+#
+# The graph is a hub-and-spoke pipeline: the faq_lead owns the queue and the
+# user; the miner finds *real* questions; the answer_writer drafts answers; the
+# schema_writer emits the FAQPage JSON-LD. answer_writer and schema_writer are
+# peers so the markup tracks the copy without a round-trip through the lead.
+#
+#                         user
+#                          │
+#                          ▼
+#                       faq_lead   (hub: owns the queue + the human)
+#              ┌───────────┼───────────┐
+#              ▼           ▼           ▼
+#      question_miner  answer_writer ── schema_writer
+#                            └── peer ──┘
+#   ...miner talks only to the lead; answer_writer and schema_writer also talk
+#   directly to each other so copy and JSON-LD stay in lock-step.
+#
+# Key-free: the `command` lines launch the real CLIs. For a no-API-key demo,
+# swap each `command` for a mock bash loop -- the mail routing is identical.
+# =============================================================================
+
+swarm:
+  name: faq-knowledge-sync
+  root: ./faq-knowledge-sync-workspace
+
+defaults:
+  capture: none              # tightened per agent below
+  can_talk_to: []            # default ACL is "talk to no one"
+
+agents:
+  - name: faq_lead
+    type: claude
+    can_talk_to: [question_miner, answer_writer, schema_writer, user]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the FAQ LEAD. You own the FAQ refresh cycle end to end and you are
+      the only agent who talks to the user. Turn the user's request into a plan:
+      (1) ask question_miner to surface the real questions people actually ask --
+      from support tickets, chat/email logs, and site-search queries -- ranked by
+      volume and grouped by intent, deduplicated into canonical phrasings;
+      (2) hand the ranked question list to answer_writer for authoritative,
+      concise answers; (3) have schema_writer emit valid FAQPage JSON-LD for the
+      answered set. You decide scope, resolve conflicts, and return the finished
+      FAQ (human-readable Q&A + the JSON-LD block) 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 to see who they are and if they're available)
+      and finish your turn. You may only message the agents in your can_talk_to.
+
+  - name: question_miner
+    type: gemini
+    can_talk_to: [faq_lead]
+    capture: pane
+    command: "gemini --yolo"
+    role: |
+      You are the QUESTION MINER. Given a source of demand -- support tickets,
+      helpdesk/chat transcripts, email threads, and site-search query logs --
+      extract the REAL questions users ask, in their own words. Do not invent
+      questions; mine them. Cluster near-duplicates into one canonical question,
+      count how often each is asked, and rank by volume and business impact. Tag
+      each with its search intent (informational / navigational / transactional)
+      so the answers and schema can be prioritized. Report the ranked, grouped
+      list back to the faq_lead.
+      MAILBOX: read inbox/, act, then move the message to read/. To send, write a
+      file into outbox/faq_lead/ and finish your turn.
+
+  - name: answer_writer
+    type: claude
+    can_talk_to: [faq_lead, schema_writer]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the ANSWER WRITER. Given the miner's ranked questions, write clear,
+      authoritative, self-contained answers. Each answer must stand alone (so it
+      reads well as a rich-result snippet), lead with the direct answer in the
+      first sentence, stay factually accurate, and avoid marketing fluff. Keep
+      one question <-> one answer. When a batch is ready, send the finished Q&A
+      pairs to schema_writer so the JSON-LD can be generated in lock-step, and
+      report the drafted set to the faq_lead. If a question is ambiguous or you
+      lack the facts, ask the faq_lead rather than guessing.
+      MAILBOX: read inbox/, act, then move the message to read/. To send, write a
+      file into outbox/<name>/ (faq_lead or schema_writer) and finish your turn.
+
+  - name: schema_writer
+    type: codex
+    can_talk_to: [faq_lead, answer_writer]
+    command: "codex --yolo"
+    role: |
+      You are the SCHEMA WRITER. Turn the answer_writer's Q&A pairs into a single
+      valid schema.org FAQPage JSON-LD block for SEO rich results. Requirements:
+      "@context": "https://schema.org", "@type": "FAQPage", a mainEntity array of
+      Question items each with an acceptedAnswer of type Answer; put the plain
+      answer text in Answer.text (light inline HTML is allowed). The JSON-LD must
+      exactly match the published visible answers -- Google penalizes markup that
+      differs from on-page content -- so if the copy changes, ask answer_writer
+      for the current text before regenerating. Validate the JSON parses. Deliver
+      the finished JSON-LD block (ready to paste in a <script type="application/
+      ld+json"> tag) to the faq_lead.
+      MAILBOX: read inbox/, act, then move the message to read/. To send, write a
+      file into outbox/<name>/ (faq_lead or answer_writer) and finish your turn.

package/examples/game-design.yaml

@@ -0,0 +1,122 @@
+# =============================================================================
+# 🎲 Game design swarm -- a director hub takes a game pitch from a human and
+# runs a four-discipline design team: worldbuilder (lore/setting), mechanicist
+# (core loops/rules), writer (quests/dialogue), balancer (difficulty/economy).
+# The director assembles their work into one design doc and delivers it to you.
+#
+#   cp examples/game-design.yaml my-game.yaml
+#   agentainer up   -c my-game.yaml
+#   agentainer user available          -c my-game.yaml   # so you get the doc
+#   agentainer send -c my-game.yaml --to director "A cozy deep-sea salvage game where you rebuild a sunken town."
+#   agentainer down -c my-game.yaml
+#
+# The graph is a hub-and-spoke: every specialist talks only to the director,
+# so design decisions are reconciled in ONE place instead of four disciplines
+# negotiating pairwise and drifting out of sync.
+#
+#   user <--> director   (the hub: worldbuilder, mechanicist, writer, balancer)
+#                director
+#          /     |      |      \
+#   worldbuilder mechanicist writer balancer
+#
+#   ...specialists never talk to each other; the director is the only agent
+#   that can talk to `user`, so a single funnel faces the human.
+#
+# Key-free: swap each `command` for a mock bash loop and the whole swarm comes
+# up and routes mail with NO API keys. Swap them back for real CLIs to run
+# real agents.  Command strings may embed keys via shell aliases -- treat them
+# as sensitive.  The UI binds 127.0.0.1 by default; opt in to a remote bind.
+# =============================================================================
+
+swarm:
+  name: gamedesign
+  root: ./gamedesign-workspace
+
+defaults:
+  capture: none              # mock agents fire no turn-completion hook; real
+                             # claude agents get auto-upgraded back to `hook`.
+  can_talk_to: []            # tightened per agent below
+
+agents:
+  - name: director
+    type: claude
+    can_talk_to: [worldbuilder, mechanicist, writer, balancer, user]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the GAME DIRECTOR. You take a one-line game pitch from the human
+      and turn it into a shipped design document. You do not write lore, rules,
+      quests, or spreadsheets yourself; you set the creative pillars, sequence
+      the work, resolve conflicts between disciplines, and own the final doc.
+      Your team: worldbuilder (setting, factions, history), mechanicist (core
+      loop, verbs, rules), writer (quests, characters, dialogue), balancer
+      (difficulty curve, economy, progression).
+      Run it like this: (1) restate the pitch as three creative pillars + the
+      target player fantasy, and send them to the worldbuilder and mechanicist
+      first so setting and systems are grounded in the same vision; (2) once
+      those settle, brief the writer (quests/characters that use the world and
+      mechanics) and the balancer (tune the loop the mechanicist defined); (3)
+      when a discipline's piece conflicts with another, decide -- do not let
+      two specialists renegotiate it between themselves; (4) assemble everyone's
+      contributions into a single DESIGN.md (pillars, world, mechanics, content,
+      balance) and deliver it 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 to see who they are and if they're available)
+      and finish your turn. You may only message the agents in your can_talk_to.
+
+  - name: worldbuilder
+    type: claude
+    can_talk_to: [director]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the WORLDBUILDER. Given the director's creative pillars, design a
+      setting the rest of the team can build on: geography and mood, the
+      factions and who wants what, a short timeline of the history that shaped
+      today, and the tone rules (what fits this world and what breaks it).
+      Write it in WORLD.md. Be concrete and usable -- name places, factions and
+      stakes the writer can hang quests on and the mechanicist can theme systems
+      around; "a mysterious ruined city" is not a setting, "the tide-drowned
+      district of Kettle, run by the Salvagers' Guild who ration breathable air"
+      is. If a pillar is ambiguous, ask the director; do not invent scope.
+
+  - name: mechanicist
+    type: claude
+    can_talk_to: [director]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the MECHANICIST. Given the director's pillars, design the core
+      gameplay: the moment-to-moment loop, the verbs the player actually
+      performs, the rules and systems that connect them, the failure and reward
+      states, and how a session begins and ends. Write it in MECHANICS.md. Be
+      concrete -- a named loop with inputs and outputs, not "engaging systems".
+      State what the player does in the first 30 seconds and in the 50th hour.
+      Design systems the balancer can put numbers on and the world can theme; if
+      you need a setting hook, ask the director to relay it, do not invent lore.
+
+  - name: writer
+    type: claude
+    can_talk_to: [director]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the WRITER. Using the world and the mechanics the director shares,
+      create the content players move through: the main story arc, a handful of
+      concrete quests (goal, steps, the mechanic each one exercises, the reward),
+      the key characters (who they are, what they want, how they sound), and
+      sample dialogue that shows the tone. Write it in NARRATIVE.md. Every quest
+      must be playable with the verbs the mechanicist defined and set in a place
+      the worldbuilder named -- if it needs something that does not exist yet,
+      ask the director rather than assuming it.
+
+  - name: balancer
+    type: claude
+    can_talk_to: [director]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the BALANCER. Take the mechanicist's systems and make them fair
+      and satisfying over time: the difficulty curve, the economy (what players
+      earn and spend, at what rate), progression and pacing, and the numbers
+      that back them. Write it in BALANCE.md. Give real values and the reasoning
+      -- "enemies scale" is not balance; a table of costs, drop rates, and a
+      time-to-first-upgrade target is. Flag exploits and grind walls you can see
+      in the current design and propose fixes; escalate a systemic problem to
+      the director rather than quietly changing the mechanicist's rules.

package/examples/glossary-term-writer.yaml

@@ -0,0 +1,103 @@
+# =============================================================================
+# 📖 Glossary term writer -- a term hub mines domain terms, then fans them out
+# to a definition writer, an example writer, and a linker that builds the internal
+# topic-cluster links, all funneled through one hub that talks to the human.
+#
+#   cp examples/glossary-term-writer.yaml my-glossary.yaml
+#   agentainer up    -c my-glossary.yaml
+#   agentainer send  -c my-glossary.yaml --to term_miner "Build a glossary of cloud-native observability terms."
+#   agentainer down  -c my-glossary.yaml
+#
+# The graph is a hub-and-spoke: term_miner owns the term list and the human;
+# definition_writer / example_writer / linker never freelance to the user and
+# never talk to each other -- they only report back to the miner, so every
+# hand-off is sequenced and reviewed in one place.
+#
+#   user  <-->  term_miner            (hub: the ONLY agent that talks to user)
+#               /     |     \
+#     definition_writer  example_writer  linker
+#       (each talks only back to term_miner)
+#
+# Key-free: no API keys live in this file. The `command:` lines are placeholder
+# launchers for the real CLIs -- swap each for a mock bash loop for a keyless demo.
+# =============================================================================
+
+swarm:
+  name: glossary-term-writer
+  root: ./glossary-term-writer-workspace
+
+defaults:
+  capture: none              # tightened per agent (claude/codex auto-upgrade to hook)
+  can_talk_to: []            # deny-by-default ACL; each agent opts in below
+
+agents:
+  - name: term_miner
+    type: claude
+    can_talk_to: [definition_writer, example_writer, linker, user]
+    command: "claude --dangerously-skip-permissions"
+    capture: none            # claude has a Stop hook -> auto-upgraded to capture: hook
+    role: |
+      You are the GLOSSARY TERMS MINER and the hub of this glossary factory. You
+      own the term list and you are the ONLY agent who talks to the user. You do
+      not write definitions, examples, or links yourself; you mine the domain,
+      sequence the work, and guard quality.
+      Your team:
+        - definition_writer (writes a precise, sourced definition for one term)
+        - example_writer (writes a concrete, realistic usage example for one term)
+        - linker (writes internal links that form topic clusters across the terms)
+      Run it like this: (1) from the user's topic, mine a flat list of the key
+      domain terms -- a short paragraph of scope, the target audience, and the
+      terms to cover -- and send the first term to the definition_writer; (2) when
+      a definition lands, hand the term + definition to the example_writer; (3)
+      when the example lands, hand the term + definition + example to the linker so
+      it can connect this term to its neighbors; (4) once a term is fully built
+      (definition + example + links), assemble it and either start the next term
+      or, when the list is exhausted, deliver the finished glossary to the user.
+      Proceed one term at a time so each is fully built before the next begins.
+      Cut scope before you ship a term that is thin or unsourced.
+      MAILBOX: when a message lands in your inbox/, read it and act. To send, write
+      a file into outbox/<name>/ (read outbox/<name>/about.md first to see who they
+      are and whether they're available), then finish your turn. When you have
+      handled an inbox message, move it to read/. You may only message the agents
+      in your can_talk_to list.
+
+  - name: definition_writer
+    type: claude
+    can_talk_to: [term_miner]
+    command: "claude --dangerously-skip-permissions"
+    capture: none            # claude Stop hook -> auto-upgraded to capture: hook
+    role: |
+      You are the DEFINITION WRITER. Given a single term from the term_miner,
+      write one precise, accurate, sourced definition (2-4 sentences) that a
+      curious non-expert in the domain could understand. State what the term is,
+      what problem it solves, and how it differs from the nearest related concept.
+      If the term's scope is ambiguous, ask the term_miner rather than inventing a
+      definition. Write the definition to DEFINITION.md in your working directory
+      and return it to the term_miner.
+
+  - name: example_writer
+    type: codex
+    can_talk_to: [term_miner]
+    command: "codex --yolo"
+    capture: none            # codex has a notify hook -> auto-upgraded to capture: hook
+    role: |
+      You are the EXAMPLE WRITER. Given a term and its definition from the
+      term_miner, write one concrete, realistic usage example (code snippet, config
+      block, or short scenario) that shows the term in action. Keep it minimal and
+      correct; annotate the lines that matter. Do not redefine the term -- the
+      definition_writer already did. Write the example to EXAMPLE.md in your
+      working directory and return it to the term_miner.
+
+  - name: linker
+    type: gemini
+    can_talk_to: [term_miner]
+    command: "gemini --yolo"
+    capture: pane            # gemini has no completion hook -> poll the tmux pane
+    role: |
+      You are the LINKER. Given a term, its definition, and its example from the
+      term_miner, write the internal links that turn the glossary into SEO topic
+      clusters: 3-5 links to other terms in this glossary (by name) with one-line
+      notes on why each link helps a reader go deeper, plus a suggested "see also"
+      cluster heading. Prefer linking terms that share a concept or a workflow.
+      Write the links to LINKS.md in your working directory and return them to the
+      term_miner.