fleetwright

Running a fleet of subagents

When you spawn ten subagents on one job, two things go wrong and they have the same cause. A subagent you spawn has no context. It cannot see the other nine, and it did not read the reasoning you did before spawning it.

So they all start on the first item. And each one decides for itself what "done" means, so you get ten standards on one corpus.

Putting the task in the spawn prompt does not fix it. That prompt is invisible to the worker you spawn an hour later, and to the one that picks up work a crashed worker dropped.

fleetwright is the shared list they claim from, and the brief travels with each unit. You define the work once; every worker gets it at claim time.

When to use this

Use it when the user wants 3 or more subagents over a list of independent units.

Do not use it for one agent, for two units, or when each step depends on the last. A plain loop is clearer and the setup is not free.

First, in any session: find out where things are

You have no memory of previous sessions. Before deciding anything, run:

fleetwright state

It finds the database even if you do not know its name, and tells you which runs exist, which are still going, what failed, and the single next command. If it says there is no database here, this project has not used fleetwright and you are starting fresh.

If a run is still going, do not start a second one over the same work. Join it: spawn workers against the same database and they will claim what is left.

The whole flow

1. Set up the queue (you, once)

DB=$PWD/work.db

# What this run is. Everything below belongs to it.
RUN=$(fleetwright start --db "$DB" --label "extract claims from tomus II")

# What the work IS. The ninth worker, spawned an hour from now, reads this.
fleetwright define extract --db "$DB" \
  --instructions 'Read $path. Record every claim it makes, quoting verbatim.' \
  --done-when    'every claim in the file is recorded, or you have established there are none' \
  --returns      '{"claims": <int>, "notes": "<string>"}'

# The units. Use ABSOLUTE paths: workers may not share your directory.
ls scans/*.png | xargs -n1 basename > units.txt
fleetwright add extract --db "$DB" --from-file units.txt --run "$RUN" \
  --meta "{\"path\": \"$PWD/scans/\$name\"}"