From 11843f41a40ed9dd9792fd3b42aa3b88040e27cd Mon Sep 17 00:00:00 2001 From: mfowler Date: Sun, 14 Jun 2026 18:13:48 +0000 Subject: [PATCH] =?UTF-8?q?docs(examples):=20add=20IDEAS.md=20=E2=80=94=20?= =?UTF-8?q?backlog=20of=20creative=20example=20topologies?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A sketch backlog of further examples, each teaching a distinct orchestration topology (anthill/stigmergy, kitchen line/pipeline, incident room/blackboard, senate/debate, baton/mutex+failover, immune system/reactive, evolution chamber, plus ATC and day-night extras). Not implemented — ideas only. Co-Authored-By: Claude Opus 4.8 --- examples/IDEAS.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 examples/IDEAS.md diff --git a/examples/IDEAS.md b/examples/IDEAS.md new file mode 100644 index 0000000..d1fb619 --- /dev/null +++ b/examples/IDEAS.md @@ -0,0 +1,93 @@ +# 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.