recipe-maintainers/agent-orchestrator
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
781db071dd15d82b37f14cd17f15dc3e58fad207
agent-orchestrator/examples/snakepit/pit/README.md
mfowler e4453dcfdd docs(examples): add the "snake pit" worker-pool example 
Based on @ponder.ooo's "snake pit agent orchestrator" idea (bsky 2026-05-28) and
Claude's metaphor-mapping elaboration: agents are snakes, tasks are food tossed
into a shared pit; snakes devour/digest/regurgitate/excrete.

A worker-pool-over-a-shared-queue topology (contrast the builder-adversary phase
machine):
- pit/ is a filesystem queue; snakes claim by atomic mv (no two eat the same food)
- species = specialized agents: keeper (zookeeper), planner (regurgitation IS
  task decomposition), snake-1..3 (worker pool), cleanup (scavenger + coprophagy)
- no [loop] phase machine; persistent agents self-pace via /loop
- README carries the full bio→compute mapping table from the thread image

Verified: `agents.py status --config agents.toml` lists all 6 agents + service.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-14 17:50:42 +00:00

2.5 KiB
Raw Blame History

The pit — a filesystem task queue

The pit is just directories. Snakes coordinate entirely through atomic mv between them — moving a file within one filesystem is atomic, so two snakes can never devour the same food.

pit/
  food/      the queue: tasks waiting to be eaten        (food-<id>-<slug>.md)
  claimed/   in digestion: a snake is working this one   (<snake-id>.food-<id>-<slug>.md)
  done/      regurgitated WHOLE: a finished result        (food-<id>-<slug>.result.md)
  scraps/    regurgitated in PARTS: notes/leftovers        (anything; informational)
  waste/     excreted waste: chat logs, debug traces       (<snake-id>-<ts>.log)

Sub-tasks ("broken / digested parts") are regurgitated back into food/ as new food items, so any snake can devour them. scraps/ is for non-actionable leftovers a snake wants to keep around.

Food schema (pit/food/food-<id>-<slug>.md)

# food-0007-reverse-string
- **task:** Implement a `reverse(s)` function in scraps/reverse.py and a test that proves it.
- **done-when:** `python -m pytest scraps/test_reverse.py -q` is green.
- **tossed-by:** keeper        # or another snake, if this is a regurgitated sub-task

Keep food small and self-contained — one unit a snake can digest in a sitting. If a task is too big, a snake regurgitates it as several smaller food items.

The eating protocol (snakes)

  1. Devour — atomically claim one item: mv pit/food/food-0007-reverse-string.md pit/claimed/snake-2.food-0007-reverse-string.md If the mv fails, another snake beat you to it — pick a different one.
  2. Digest — do the work described in the food.
  3. Regurgitate — whole: write the result to pit/done/food-0007-reverse-string.result.md and git-free remove the claimed file. In parts: if it decomposes, write new food-* items into pit/food/ for other snakes, and note that in your result.
  4. Excrete — drop your working log/trace as pit/waste/snake-2-<ts>.log; don't let it pile up in the workspace.
  5. Choke? On the 3rd identical failure, regurgitate the food back to pit/food/ (or leave it in claimed/ past the cleanup timeout) with a note in scraps/, so another snake or the keeper takes it.

Cleanup duty

The cleanup snake sweeps waste/ (summarise then prune old logs) and reclaims food left in claimed/ longer than the abandonment timeout — a sign the snake choked or died — by moving it back to food/ so a healthy snake can devour it.