# Example ideas β€” creative multi-agent topologies A backlog of *example* projects for `examples/`, each chosen to teach a **different orchestration topology** on the same harness. Nothing here is implemented yet β€” these are sketches. Built so far: - **`builder-adversary/`** β€” a **phase machine**: an ordered plan, two roles (Builder + Adversary) handing off via `claim(`/`review(` commits. (The cc-ci pattern.) - **`snakepit/`** β€” a **worker pool over a pull-queue**: identical worker "snakes" claim tasks from a shared filesystem pit by atomic `mv`, plus planner + cleanup specialist species. Each idea below lists: the metaphor, the topology it teaches, the star harness primitive, and what makes it distinct from what we already have. --- ## Strong candidates ### 🐜 Anthill (stigmergy) Ants coordinate with *no direct messaging*: they lay pheromone trails, others follow the strong ones, and trails **evaporate** over time. Agents drop weighted "trail" files toward promising solutions/paths; a `[[service]]` slowly decays them. - **Teaches:** indirect coordination through a decaying shared environment (opposite of snakepit's explicit claim). - **Star primitive:** a background **service** as the evaporation clock; emergent routing with zero agent-to-agent chat. ### 🍳 The Line (kitchen brigade) A restaurant pass: prep β†’ sautΓ© β†’ plating β†’ **expo**. A ticket (order) flows station to station; the expo bounces a bad plate back down the line. Many tickets in flight at once. - **Teaches:** a true multi-stage **pipeline** (>2 roles) with backpressure / rework β€” distinct from builder-adversary's two roles over a whole-task phase. - **Star primitive:** chained `handoff` inboxes + per-station commit prefixes (`fire(`, `plate(`, `expo(`). ### πŸ•΅οΈ The Incident Room (blackboard) A corkboard of pinned facts and red string. Specialist detectives (forensics, alibi, motive, witnesses) each watch the board and pin a new deduction *only when their preconditions appear*; a lead declares the case closed. - **Teaches:** opportunistic, **data-driven activation** β€” agents fire when the shared state makes them relevant, not on a schedule. - **Star primitive:** a shared blackboard file + watchdog pings on board changes; no fixed order. ### βš–οΈ The Senate (debate panel) N agents argue a question from assigned stances; a moderator synthesizes; rounds repeat until consensus or a vote. - **Teaches:** structured **multi-round deliberation** with diverse "minds." - **Star primitive:** the **phase machine** where each phase = one debate round, plus **per-phase model overrides** to give each seat a genuinely different model; `on_complete` writes the verdict. ### πŸƒ The Baton (relay / token ring) Exactly one runner holds the baton (a lock file) and works; passes it on completion. Drop the baton (crash) and the next runner picks it up. - **Teaches:** **mutual exclusion + failover** β€” enforced serialization, the mirror image of the snakepit's parallelism. - **Star primitive:** `watch = "heal"` + the watchdog reaping a dead holder so the baton never gets stuck. ### 🦠 The Immune System (detect β†’ respond) Sentinels patrol logs/metrics/files for anomalies (pathogens); on a hit they raise an antigen (alert file); responder "macrophages" swarm that specific threat; memory cells record signatures so repeats resolve faster. - **Teaches:** an **event-driven monitoring/reactive** topology with escalation. - **Star primitive:** a watcher **service** emitting alerts + reactive agents woken by inbox pings. - **Bonus:** genuinely *useful* β€” a self-healing "watch my repo/CI" tool wearing a fun costume. ### 🧬 The Evolution Chamber (genetic algorithm) A population of candidate solutions; breeder agents mutate/crossbreed; a selector culls by fitness; generations advance until fitness plateaus. - **Teaches:** **population-based iterative search** with a fitness gate. - **Star primitive:** phase machine where each phase = one generation; `done_marker` trips when fitness stops improving. --- ## Quick extras (less fleshed out) - **πŸ—Ό Air Traffic Control** β€” many workers contend for *one* scarce runway (a single deploy/build slot); a controller grants timed landing slots. Teaches centralized **scarce-resource arbitration** (snakepit has plentiful work; here the *resource* is the bottleneck). - **πŸŒ™ Day/Night (sleep consolidation)** β€” workers act by day; a "sleep" agent on a `wake` timer consolidates the day's artifacts into long-term memory each night. Teaches **scheduled batch consolidation** (the "memory builder / coprophagy" idea as its own example). --- ## Engine idea: unify the phase machine and per-agent pipelines (one apparatus) The `[loop]` **phase machine** advances an ordered plan for a *fixed* set of loop agents (Builder + Adversary) that run **every** phase in **one** worktree, detecting completion via a `## DONE` commit-subject in a status file. A common variant, though, is a sequence of **distinct** agents β€” different prompt/model, sometimes a different worktree β€” handed off one at a time (e.g. build β†’ review β†’ e2e β†’ integrate, each a separate agent). That's *the same shape* β€” an ordered sequence of stages, each with a completion signal and the right agent(s) running β€” so it shouldn't need a **separate pipeline apparatus**; it should be **the same phase machine**, generalized. **The missing primitive is a per-stage `agent` + `dir`.** Agents already carry a `dir` (used for per-agent token attribution). If a **phase entry** could optionally name the agent(s) that run it and the directory they run in (plus a `done` marker as an alternative to `## DONE`), the one phase machine covers both cases: - **loop-style phase** (default/back-compat): no `agent` β†’ the fixed loop agents run it; completion = `## DONE` in the phase's status file, in the loop dir. - **pipeline-style phase:** `agent = "fork-iroh"`, `dir = "work-fork"`, `done = "work-fork/.ao-state/FORK-IROH-COMPLETE"` β†’ advancing the phase stops the previous stage's agent and starts this one in its dir; completion = the marker. Advancing a phase then means "stop the outgoing stage's agent(s), start the incoming stage's agent(s) in their dir" β€” a superset of today's "re-kickoff the same loop agents." The `p-lichen-orchestrator` project prototyped this as a standalone `[pipeline]` block (stages = `{agent, done}`, reconciled by the watchdog each tick, markers as source of truth); the lesson is that **that logic belongs in the phase machine**, not beside it β€” fold `[pipeline]` into `[loop].phases` via optional `agent`/`dir`/`done` per phase and delete the parallel mechanism. (Bonus: `on_complete`, per-phase model overrides, and the DONE-nudge all already live on the phase machine, so pipeline-style phases inherit them for free.) --- ## Suggested next trio If picking three that cover the most new ground: **The Line** (pipeline), **The Incident Room** (blackboard), and **The Immune System** (reactive monitoring β€” and actually useful). Each should follow the snakepit shape: a README with the metaphorβ†’compute mapping, an `agents.toml`, role prompts, and a tiny runnable task.