User guide

Vocabulary #

Command reference #

Run fleetsmith with no arguments for this list at any time.

Core

Quality

Change

Enterprise needs fleetsmith-ee

Authoring a fleet #

Agents #

Write the role as one sentence answering who am I, and the goal as a measurable outcome — it feeds both the agent's description and the orchestrator's delegation decision. A goal like "help with testing" cannot be checked; "a failing test that reproduces the reported bug" can.

- name: risk-reviewer
  role: "Adversarially checks a change brief against the actual diff"
  goal: "A ranked risk list where every entry cites file:line evidence"
  capabilities: { read: true, run: true }
  skills: [adversarial-review]
  effort: high
  turns: 40
  principles:
    - "Default to refuted when the evidence is ambiguous"
  handoff:
    to: []

Handoffs #

An edge without an artifact is a hope. Name the file and state what makes it acceptable — the criteria compile into the producer's prompt as hard requirements, and into the gate that stops the producer finishing without them.

handoff:
  to: [risk-reviewer]
  artifact: change-brief.md
  criteria:
    - "Every changed file is accounted for"
    - "Behavioural changes are separated from pure refactors"
  schema: true   # the default four-field brief:
                 # objective, output_format, sources_and_tools, boundaries

Setting schema compiles to a goose response.json_schema, and on Claude Code and opencode it shapes both the handoff template and the validator gate. An empty to: marks a terminal agent.

Skills #

An agent is who; a skill is how. Skills load on demand, so a long methodology costs nothing until it is needed. Two properties are independent and both matter: whether a skill fires, and whether its output is good. A skill that never fires looks exactly like one that was never written — which is why each generated skill ships an evals/evals.json trigger corpus of should-fire and should-not-fire prompts.

• Write the description to be pushy and trigger-rich — it is the only thing the model sees when deciding.
• Keep the body lean and imperative; push depth into reference files.
• Bundle a script for any step that should be deterministic rather than re-reasoned.

Loops #

Two orthogonal constructs, both declared in the spec.

Iteration — repeat until good enough

orchestrator:
  phases:
    - name: review
      agents: [change-analyst, risk-reviewer]
      loop:
        until: "no unresolved high risks remain"
        max: 5
        check: "npm test"      # exit 0 = satisfied
        noProgress: 2

The loop ends three ways, and all three are rendered on every target:

A cap alone burns the entire budget on a loop that stopped improving after pass one, which is why the other two exits exist. When check is set, goose additionally gets a native recipe-level retry: block, so the loop is enforced rather than described.

Recurring — run the whole fleet on a cadence

fleet:
  schedule:
    cron: "0 9 * * 1"
    note: "Sweep last week's merged PRs for regressions"

Compiles to /loop or the schedule skill on Claude Code, a cron or while sleep wrapper around opencode run, and goose schedule or cron on goose. Neither cron nor interval means self-paced; setting both warns and cron wins.

Build vs install #

build writes the compiled harness to a directory you name. install compiles and then places the files where the tools actually look.

--dry-run lists every file that would be written. Use it the first time you point install at a repo that already has a .claude/.

Keeping it good #

A harness degrades quietly: an agent stops being delegated to, a skill stops firing, the spec drifts from what was compiled. These four commands are how you notice.

qa #

fleetsmith build fleet.yaml --target all --out ./dist
fleetsmith qa fleet.yaml --built ./dist

Checks the compiled output, not the spec's intentions: spec gate, per-target compile, handoff graph against the real generated files, capability leaks, loop bounds, and drift between the spec and what was emitted. --installed runs it against an installed harness instead of a build directory.

eval #

fleetsmith eval fleet.yaml --stage 1     # 3 fleets, fast
fleetsmith eval fleet.yaml --stage 3     # the full corpus

Trigger discrimination: given a prompt that should invoke a skill, does it — and given one that should not, does it stay quiet. The ladder is staged so the fast stage can run on every commit. There is a measured noise floor and a paired baseline comparison, so a two-point move is not read as a win.

--judge and --exec add model-scored quality and live sessions. Both are explicitly advisory and gate nothing — every gate in this system is deterministic.

evolve #

fleetsmith evolve fleet.yaml --budget 3
fleetsmith evolve fleet.yaml --review
fleetsmith evolve fleet.yaml --review --accept fleet-gen/4
fleetsmith evolve fleet.yaml --review --reject fleet-gen/5 --reason "widens capability for no reason"

Observe, evaluate, mutate, validate, promote. Proposals land on a branch, must clear both qa and eval, and then wait for a human. Rollback is git revert fleet-gen/<n>.

playbook & health #

fleetsmith playbook fleet.yaml add risk-reviewer "Check the migration file before the model code"
fleetsmith playbook fleet.yaml helpful risk-reviewer <id>
fleetsmith playbook fleet.yaml harmful risk-reviewer <id>
fleetsmith playbook fleet.yaml dedupe  risk-reviewer
fleetsmith health   fleet.yaml

A playbook is an agent's accumulated working notes, curated by marking entries helpful or harmful rather than by rewriting prose. health reads the run telemetry the handover gate is already producing — gate verdicts, retries, human corrections — and tells you which agents are struggling.

Day to day #

Once a fleet is running, the loop is short:

1. Work. Agents write handoffs into _fleet/local/handoffs/ and rows into LEDGER.md.
2. When something is worth keeping, promote it into _fleet/shared/knowledge/ by pull request. That review is the only path into team knowledge.
3. Periodically run qa and the fast eval stage — ideally in CI, on every pull request.
4. When the fleet's shape is wrong rather than its content, edit fleet.yaml and rebuild. Never hand-edit generated files: the next build overwrites them, and qa reports the drift in the meantime.

Grid commands enterprise #

Every grid verb degrades. grid init is the single exception: it exits non-zero when nothing is configured, because it is meant to be run once, deliberately, not from automation that should degrade quietly.

fleetsmith grid sync --watch

Runs continuously — on an SSE doorbell if the engine emits one, a five-minute interval fallback, local ledger and handoff file changes, and run start and end. Exits cleanly on SIGINT and SIGTERM.

fleetsmith grid overlaps
fleetsmith grid overlaps --git-only

Writes OVERLAPS.md. The --git-only form needs no cortex, no grid configuration and no network access at all — file-level overlaps synthesised straight from local git branches. That is the open-source answer to the same question.

fleetsmith grid import ./meetings --kind meeting            # dry run
fleetsmith grid import ./meetings --kind meeting --apply
fleetsmith grid knowledge "why did we drop the queue" --as-of 2026-06-01

Imports are provenance-tracked and bi-temporal — business time is the meeting date, not the ingest date — so --as-of answers "what did we know then" and --as-recorded answers "what did we believe we knew then". Without a cortex, knowledge degrades to filtering committed _fleet/shared/knowledge/ frontmatter directly.

fleetsmith grid audit --actor alice --since 2026-08-01
fleetsmith grid audit --why <item-id>

--why explains why a specific item was returned to someone. It has no degraded counterpart — with no cortex, audit falls back to local run events only.

In CI #

The installer is non-interactive whenever no terminal is attached, so no flags are strictly required — but pin the version in CI.

- name: Install Infinia Harness
  run: |
    curl -fsSL https://infinia-harness.adid.dev/install.sh \
      | sh -s -- --version 0.7.0 --yes
    . ~/.fleetsmith/env.sh

- name: Gate the harness
  run: |
    . ~/.fleetsmith/env.sh
    fleetsmith validate fleet.yaml
    fleetsmith build fleet.yaml --target all --out ./dist
    fleetsmith qa fleet.yaml --built ./dist
    fleetsmith eval fleet.yaml --stage 1
    fleetsmith protected fleet.yaml --check-diff origin/main

--stage 1 is the fast rung of the eval ladder and is the right one for every-commit CI; save the full corpus for a nightly job. Nothing here needs a cortex, so the same workflow runs unchanged for both editions.