Sweeps

agb has three workload shapes: a ticket DAG (agb run, see the walkthrough), a sweep (the same operation applied to many targets), and a read-only review fleet. This page covers sweeps and recursive mode, where an Antigravity session decomposes work and drives agb on its own.

Sweep modeCopy Anchor Link

A sweep is for embarrassingly parallel work: migrations, mechanical refactors, JSDoc or test backfills. agb sweep turns a sweep.json into a normal plan with one generated ticket per target, then runs it through the same build, gate, prosecute and merge pipeline as agb run (sweep command).

agb sweep sweep.json      # defaults to ./sweep.json

{
  "repo": "/abs/path/to/repo",
  "gate": { "test": "npm test" },
  "operation": "Add JSDoc to every exported function in {target}.",
  "targetGlob": "src/**/*.mjs",
  "scopePerTarget": ["{target}"]
}

How a sweep becomes a planCopy Anchor Link

sweepToPlan does the conversion (sweepToPlan):

• repo is required, and operation must contain {target}.
• Targets come from targets, or from targetGlob expanded with git ls-files, so only tracked files match (expandTargets). No targets is an error.
• Target n becomes ticket S<n> with title sweep: <target>. Its body is operation with {target} and {i} (1-based) substituted, plus a note that identical work is happening on other targets in parallel.
• Each ticket's scope is scopePerTarget with the same substitution (default ["{target}"]).
• tier defaults to cheap and pool_hint to auto. base defaults to main; gate, caps and prosecution are copied through.
• Generated tickets have no edges and no rails: every target runs independently.

The generated plan is validated with the same rules as agb run; an invalid sweep exits 1, and the run exits 2 if any target failed (sweep exit codes). The schema is in Sweep schema.

A global --project <name> applies to the whole sweep: it is passed to the run, so every builder and prosecutor session uses it.

Tips for sweepsCopy Anchor Link

• Keep scopePerTarget tight. Two targets whose scopes overlap are not independent and will fight at merge time.
• Make operation complete on its own: each builder sees one target and nothing else.
• Shared files (a barrel index, a changelog) should not be in any target's scope. Update them in a follow-up ticket.
• Large sweeps are bounded by pool capacity, not by the number of targets; see Operating tips.

Recursive modeCopy Anchor Link

In recursive mode an Antigravity session is the planner: it decomposes a large task into a ticket DAG, writes plan.json and runs agb while it supervises. The doctrine for this lives in the adlc-self-orchestrate skill, shipped by the @adlc/antigravity plugin that agb bootstrap installs (it is not vendored in this repo). The skill teaches foundation-first decomposition, a single writer per partition and self-contained ticket bodies.

1. Run agb bootstrap once so the skill and the ~/.local/bin/agb shim are installed (see Bootstrap).
2. In an agy session, ask for the work to be built in parallel with agb. The session writes a plan, runs agb validate and agb preflight, then agb run.
3. The session reads the report and decides what to do with failed tickets. Control flow stays in agb; judgment stays with the model.

Sessions launched this way can also use the /agb-* slash commands and the MCP tools; see Headless and MCP.