Blueprints
The step sequence an agent runs on your repo, how edits version it, and which one a dispatch picks.
A blueprint is the ordered list of steps an agent runs on your repository — a mix of shell commands and agentic work. Projects bind the blueprints they allow, and every dispatch runs exactly one. Devboxes ships a shared Implement GitHub Issue blueprint you can use as-is, and you can build your own.
Browse the catalog
Open Blueprints from the admin rail. Each row shows the blueprint's name, its step count, and how many projects use it. A System badge marks the shared, read-only blueprints Devboxes maintains.
Select a blueprint to open its detail. Definition lists its status, step count, and author. Steps shows the sequence in order — each step is tagged Command (a deterministic shell step) or Agentic (a step the agent reasons through), with its action underneath. Click any step to read its full markdown in the side panel.
Create and edit a blueprint
- Click New blueprint and enter a Blueprint name (unique within your organization).
- Add steps in order with Add command or Add agentic.
- A command step takes a single Command — prefer a repo script or package-manager command over a long inline shell fragment.
- An agentic step takes an Action: System Skill (choose a curated skill under Select Skill), Custom (give it a Name and write the Agentic markdown the agent follows), or Run linters (with optional Instructions).
- Reorder steps with the up and down arrows, or remove one with the trash button. Click Create blueprint.
To change a blueprint later, open it and click Edit steps.
Editing never rewrites a blueprint's steps. Each save creates a new version — that is why the save button reads Save version — and the version number bumps automatically. Runs that are already dispatched keep the exact steps they started with; new dispatches use the latest version.
System blueprints have no Edit steps button. They are read-only; to change one, create your own blueprint instead.
Bind blueprints to a project
A project can only dispatch blueprints it is bound to. Open the project, go to its Blueprint tab, and click Edit bindings under Blueprint bindings.
Add a blueprint from the Add blueprint list. Each bound blueprint shows its version and step count; Remove unbinds one. Click Save bindings.
Pick a blueprint when you dispatch
The Dispatch run dialog has a Blueprint field grouped into Project blueprints (the ones bound to the project you chose) and System blueprints. Choose the project first; if it has no blueprints of its own, Create one links back to the catalog. You must select a blueprint before Dispatch run is enabled.
The run captures the blueprint's steps at the moment you dispatch, so editing the blueprint afterward never changes a run that is already going.
A run dispatched without naming a blueprint — for example through the API — falls back to the Implement GitHub Issue system blueprint, so the common "implement this issue" path works with no setup.
Next: Dispatching runs — starting work and how runs find a runner.