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).

---

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.