Writing plans

agb plan compiles a plan for you, but a plan is just JSON and you can write one by hand. This guide covers the rules agb validate enforces and the judgment calls it cannot make. The full field list is in the plan schema.

SkeletonCopy Anchor Link

{
  "repo": "/abs/path/to/repo",
  "base": "main",
  "gate": { "build": "npm run build", "test": "npm test" },
  "prosecution": { "dryPasses": 1 },
  "tickets": [
    {
      "id": "T1",
      "title": "Short imperative title",
      "body": "Self-contained spec: files to create, behavior, tests to write.",
      "scope": ["src/feature/**", "test/feature.test.mjs"],
      "rails": ["src/shared/types.ts"],
      "edges": [{ "to": "T2" }],
      "tier": "mid",
      "pool_hint": "auto"
    }
  ]
}

Plan-level rulesCopy Anchor Link

These are checked by validatePlan, shared by agb validate, agb run and the plan compiler (validatePlan):

• repo is required; relative paths are resolved against the current directory (loadPlan).
• gate must declare build, test, or both, and each must match npm test or npm run <script>. Put anything more complex in a package.json script.
• adlcBin is prohibited; the ADLC binary is resolved and authenticated by the runtime.
• base defaults to main (base default). agb run refuses to start unless that branch is checked out in repo.

Ticket rulesCopy Anchor Link

EdgesCopy Anchor Link

An edge { "to": "B" } on ticket A means A must merge before B starts. The scheduler turns each edge into a predecessor of its target (predecessors) and starts a ticket only when every predecessor has merged (ready check). There are no waves: independent tickets run as soon as a pool slot is free.

• Edges must name an existing ticket; self-edges and cycles are rejected (edge checks, cycle check).
• If a predecessor fails, every ticket downstream of it fails as blocked by failed predecessor without running (blocked).
• Add an edge whenever one ticket reads code another ticket writes. Two tickets with no edge between them run concurrently against the same base.

Scopes and railsCopy Anchor Link

Scope is what a ticket may change; rails are what it must not. After the build, any change outside scope or inside a rail fails the attempt (scope check).

• Keep concurrent scopes disjoint. agb preflight vetoes pairwise scope overlap between tickets that can run at the same time (preflight overlap).
• Rail the foundation. When B depends on A, list A's files in B's rails so B cannot rewrite them.
• Tests belong in scope. A builder told to write tests needs the test file in its scope.

SizingCopy Anchor Link

Each ticket gets two strikes: one regeneration with the failure appended, then it fails (two-strike rule). A ticket that cannot be finished in one focused builder session is too big. Practical heuristics:

• One coherent change per ticket: a module plus its tests, not a feature spread across layers.
• Put shared types, directory layout and dispatchers in a foundation ticket that everything else depends on.
• Prefer more, smaller tickets with clean edges over a few large ones; parallelism comes from width, and failures stay cheap.
• Write the body so a fresh agent with no other context can execute it: name the files, the behavior and the tests.
• Use cheap for mechanical work, mid by default, frontier for design-heavy or subtle work. See Pools and tiers.

Check before you runCopy Anchor Link

agb validate plan.json    # exit 2 if invalid, prints every error
agb preflight plan.json   # scope overlap + coldstart on each ticket body

Then follow the walkthrough from the run step.