Extensions · OpenFleet

01 · INSTALLAdd one from a folder or a git URL

add prints what the extension declares, including its permissions, so you can review it. Git sources are pinned to a commit in extensions.lock.json; commit that file and extensions/.

FROM A LOCAL FOLDER

npx openfleet add ../my-extension

FROM GIT, AT A TAG

npx openfleet add https://github.com/acme/audit.git#v1

SEE WHAT’S INSTALLED

npx openfleet extensions

Remove one with npx openfleet remove <name>.

02 · PHASE SLOTSSix points in the run

Each phase entry runs as its own agent at one of these slots.

pre-spec ONCE
Before the specDuring the grill, ahead of the coordinator writing spec.md.
post-plan PER CHILD
After each planOnce the child’s plan is validated against the spec.
plans-ready ONCE
When every plan agreesAfter the consistency gate, before any code is written.
pre-implement PER CHILD
Before each buildAfter the gate and the child’s baseline, right before its implementer.
post-test PER CHILD
After tests passThe child is done only once it finishes, so it can publish a version its dependents use.
post-run ONCE
When the run is doneDuring finalize. For example, an audit of events.jsonl.

03 · PHASESWhat a phase can do

"blocking": true

Hold the run until it passes

A failure gets one retry with a fresh agent. If that fails too, the child is marked failed and its dependents wait. In plans-ready, the gate stays closed and nothing is built.

"when": { "files": [ … ] }

Run only where it applies

The entry runs only if one of the listed files exists in that child’s worktree.

"outputs"

Hand values downstream

A published version or other value reaches every repo that depends on this one, directly or not. A prUrl output means finalize updates that PR instead of opening a second one.

"followUps"

Leave notes for people

Follow-ups are listed in summary.md and in the PRs they affect.

04 · AUGMENTS AND COMMANDSChange what an agent is told

An augment appends instructions to one role’s prompt, for every child. The roles:

coordinator
repo-coordinator
planner
baseline
implementer
tester

An extension can also add commands. Each runs its own agent: npx openfleet <command>.

05 · SETTINGSSet once per workspace

An extension declares its settings with defaults. Your values live in extensions.config.json, shared by every project. The grill asks about any setting that has no value yet, so you only answer once. Settings are stored as plain text, so keep secrets out of them.

npx openfleet ext settings: Every declared setting, with its default and your value
npx openfleet ext settings --unset: Only the settings without a value yet
npx openfleet ext settings set <ext> <key> <value>: Set a value for the whole workspace

06 · PERMISSIONSDeclared up front, enforced

Every extension can read. Anything more, write, shell or web, must be declared in the manifest, and the generated agent’s tool allow-list only includes what was declared.

07 · A MANIFESTopenfleet.extension.json

This one publishes a preview build after tests pass, and tells implementers to pin the version.

{
  "manifest": 2,
  "name": "publish",
  "version": "1.0.0",
  "core": "^1.0.0",
  "permissions": ["shell"],
  "phases": [
    {
      "slot": "post-test",
      "instructions": "publish.md",
      "blocking": true,
      "when": { "files": [".changeset/config.json"] },
      "timeoutMinutes": 45
    }
  ],
  "augments": [{ "role": "implementer", "instructions": "pin.md" }],
  "commands": { "publish-status": "status.md" },
  "settings": {
    "label": {
      "default": "preview",
      "description": "Label that triggers the preview workflow"
    }
  }
}

Write your own

The extension guide covers every field, slot and setting.

READ THE EXTENSION GUIDE QUICK START

Extend any step of the run.