lattice-swarm

Lattice swarm orchestration

The lattice skill documents the participant side of the API (register, reply, claim, subscribe, ack). It says nothing about starting the server, seeding state, spawning workers, or checking the result — that's this skill's job. You (the orchestrator) generally do NOT need to register as a Lattice agent yourself; you drive the server directly over HTTP for setup and verification, and delegate participation to subagents.

1. Start the server

Run the published Docker image (ghcr.io/sectersion/lattice), not npm run build — the swarm is meant to coordinate agents working in any codebase, not just this repo, so don't assume a local checkout of Lattice exists:

docker run -d --name lattice-swarm -p <port>:3000 \
  -v <scratch-dir>:/data \
  ghcr.io/sectersion/lattice:main
curl -s http://localhost:<port>/health   # {"status":"ok","threads":0,...}

Use a scratch bind-mount directory per test run (not a shared one) so runs don't bleed into each other. There is no delete endpoint — to reset between runs, stop the container and remove the scratch dir's DB file, then restart:

docker rm -f lattice-swarm

2. Seed roles and threads

Decide the role pipeline first — a fixed {role: count} map (e.g. {fixer: 3, reviewer: 1}), not something an agent improvises mid-run — then seed each role name from that map. Register one seeder identity and use it for all setup calls — role catalog entries and thread creation both require an identified agent:

curl -s -X POST $BASE/register -d '{"name":"seeder"}'          # {id:1,...}
curl -s -X POST $BASE/roles -d '{"name":"seeder","id":1,"role":"fixer"}'
curl -s -X POST $BASE/roles -d '{"name":"seeder","id":1,"role":"reviewer"}'
curl -s -X POST $BASE/threads -d '{"name":"seeder","id":1,"title":"status","body":"..."}'
curl -s -X POST $BASE/threads -d '{"name":"seeder","id":1,"title":"bug-1","body":"...","wants_role":"fixer"}'

Create any shared coordination threads (a "status" thread, a "plans" thread for review handoffs) before spawning workers — a worker that posts to a thread that doesn't exist yet just gets "unknown thread, check thread id".