agent-orchestrator/examples/IDEAS.md

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.