mfowler
b739504e1f
Adds a [pipeline] block: an ordered sequence of DISTINCT agents (different prompt/model/dir) run one at a time, advancing when each writes its completion marker — the standalone-agent analog of the [loop] phase machine (which drives FIXED loop agents via ## DONE). The watchdog reconciles it every tick, stateless (markers are the source of truth): exactly the first not-yet-complete stage runs, earlier stages are retired, the active stage is stall/heal-watched. Pipeline agents are enabled=false (the pipeline owns their lifecycle). Also fixes a latent watchdog crash: wake_elapsed is built once at startup but config is re-read each tick, so removing an agent's 'wake' mid-run (e.g. winding down a wake) hit agent['wake'] -> KeyError and killed the whole watchdog silently (stalling phase advancement + stall recovery). Now skips agents whose wake was removed. IDEAS.md: note that [pipeline] and [loop].phases are the same shape and should be unified via an optional per-phase agent/dir/done (fold pipeline into the phase machine, delete the parallel path). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UWTdUq2bsic7JZGqJp3nD6
124 lines
7.1 KiB
Markdown
124 lines
7.1 KiB
Markdown
# 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.
|