mfowler
e4453dcfdd
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>
50 lines
2.5 KiB
Markdown
50 lines
2.5 KiB
Markdown
# 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`)
|
|
|
|
```markdown
|
|
# 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.
|