Blueprints

A blueprint is a named, ordered list of steps an organization owns. Each step is one of two kinds: deterministic (a shell command) or agentic. An agentic step's action is a curated system skill, a custom markdown prompt, or run-linters, and every agentic step carries a review-in-separate-subagent flag.

Editing a blueprint never mutates its steps. Each edit creates a new immutable version — the version number bumps automatically, and prior versions and their step rows are never rewritten. Blueprints belong either to a single organization or to the shared system catalog. System blueprints are read-only: editing one answers 403 System blueprints are read-only.

Projects bind the blueprints they may run. A dispatch names one blueprint — or, when none is named, uses the Implement GitHub Issue system blueprint — pins the run to that blueprint's latest version, and copies its steps onto the run as run steps at dispatch time. Later edits never reach an in-flight run.

How to test it

pnpm vp run @firops/api#test

The blueprint definition, versioning, and binding routes have no dedicated automated suite yet; the suites below exercise blueprints as fixtures for the dispatch and runner path, and the remaining behavior is verified manually.

• dispatch-queue.test.ts — seeds a blueprint version with a step, then proves the runner claim, lease, and requeue lifecycle operates over the run steps snapshotted from that version. Confirms a run carries blueprint-derived step rows a runner can claim.
• opencode-events.test.ts — drives the dispatch route against a seeded blueprint. Proves the route rejects invalid input (an unprefixed model, a non-admin caller) before any run or task is queued, and that a queued task references the seeded blueprint version.

Manual smoke: create a blueprint in Blueprints, bind it on a project's Blueprint tab, dispatch a run with it, and confirm the run's steps match the blueprint. Then edit the blueprint and confirm the in-flight run's steps are unchanged.

Decisions

• Immutable versions plus snapshot at dispatch — a run must stay reproducible and auditable while a blueprint keeps evolving. Editing a blueprint mid-flight must not change a run already executing, so each edit forks a new version and dispatch copies the version's steps onto the run rather than pointing at the live definition.
• System blueprints are read-only — the shared catalog (Implement GitHub Issue) is a curated baseline every organization can dispatch. Letting one organization edit it would change behavior for all of them, so writes answer 403 and an organization diverges by creating its own blueprint instead.
• Default blueprint on dispatch — a dispatch with no named blueprint still needs a runnable definition. Defaulting to Implement GitHub Issue makes the common "implement this issue" path work with zero setup instead of erroring.

Next: Environment entries — the frozen environment a run carries.