Write a Blueprint

A Blueprint describes a kind of work that your team asks devboxes to do again and again. Any member of your Organization can write and change Blueprints, or ask devboxes in Chat to set up or change a way of working. Work that reaches a sensitive integration starts only with a version that an owner approved.

A Blueprint is a graph. A Blueprint's nodes are the steps of the work: a turn of the agent, one of the Project's commands, publishing the commits, or a Review. The edges decide which step runs next, so a Blueprint can publish only when the tests pass.

Write a Blueprint for your repository

A Blueprint for a repository runs its tests, its linter, and its build with the repository's own commands. You add these commands to the Project, and the Blueprint names them. The onboarding prompt does both for you. To do it for a repository that is already set up, use this prompt:

Start from the catalogue

devboxes offers ready Blueprints for common work, such as drafting replies to customer emails, researching a company before a call, or turning an issue into a pull request, and bundles of them. These Blueprints work from your request and the web, and some also read your issue tracker or your repository. A Run works only from what its request contains: when you ask in Chat, the Chat agent copies the thread messages the work needs into the request, such as the stand-up updates people posted. catalogue.list lists the templates, and for the templates that use an issue tracker or a repository it says whether your Organization has connected them. Pass for with startup, agency, online-shop, local-business or professional-firm to list only the templates for that kind of company. Pass kind with team or solo to list the tools that kind of Organization is offered, with the ones it is suggested first.

A template runs as a series of steps, and every step has checks that decide when it is done. When the request leaves a decision open that belongs to you, such as which market to research or which costs to cut, a step asks you before the work goes on. Anyone can read the templates and their steps at GET /api/catalogue, before signing in.

{
  "organizationId": "<organization id>",
  "blueprints": ["customer-email-replies", "company-brief"],
  "projectId": "<project id>"
}

devboxes invoke catalogue.install --input @install.json

Installed templates become Blueprints of your Organization under their catalogue names, committed as version 1 and bound to projectId when you give one. Only an owner's install is approved; a member's waits for an owner to approve it. Installing it again returns the same Blueprint. catalogue.remove with the same entries archives their Blueprints, including ones you changed since. Installing an entry again restores its archived Blueprint with its versions, and every Schedule that uses it stays paused until you resume it. When a Blueprint you made yourself already has the name, live or archived, the install is refused. Change an installed Blueprint like any other. A Blueprint that publishes a pull request needs a Project with a repository and Project commands named install, test and lint.

devboxes ships newer versions of catalogue entries. An installed Blueprint that still matches the catalogue's version moves to the newer version on its own. The audit log records that new version, and the Blueprint's Schedules stay as they are. The new version keeps the approval of the version it replaces, unless it calls operations that the approved version doesn't: then work keeps the approved version until an owner applies the update. A Blueprint that you changed keeps your changes. catalogue.list then sets the entry's update, with the changes it makes to your Blueprint, and catalogue.update with the same entries commits the newer version as your Blueprint's next version, in place of your changes:

{
  "organizationId": "<organization id>",
  "blueprints": ["customer-email-replies"]
}

devboxes invoke catalogue.update --input @update.json

Create a Blueprint

To do it yourself:

{ "organizationId": "<organization id>", "name": "Fix a bug" }

devboxes invoke blueprints.create --input @blueprint.json

The result contains the Blueprint and its first, empty draft. The draft's id is the version that you write.

Write the draft

Write the graph into the draft:

{
  "organizationId": "<organization id>",
  "versionId": "<draft id>",
  "graph": {
    "description": "Reproduce a bug with a failing test, fix it, and open a pull request once the tests pass.",
    "requirements": [],
    "capabilities": [],
    "groups": [],
    "nodes": [
      {
        "key": "fix",
        "label": "Fix the bug",
        "group": null,
        "kind": "agent",
        "instructions": "Reproduce the bug with a failing test, then fix it.",
        "outcomes": ["A test reproduces the bug and passes after the fix."]
      },
      { "key": "test", "label": "Test", "group": null, "kind": "command", "command": "test" },
      { "key": "publish", "label": "Publish", "group": null, "kind": "publish" }
    ],
    "edges": [
      { "from": "fix", "to": "test", "when": "succeeded" },
      { "from": "test", "to": "publish", "when": "succeeded" }
    ]
  }
}

devboxes invoke blueprints.replace-draft --input @draft.json

The test node runs the Project Command named test. Add it to the Project first, as shown in Add the repository's commands.

The graph reference describes the fields and node kinds.

Commit the version

{ "organizationId": "<organization id>", "versionId": "<draft id>" }

devboxes invoke blueprints.commit --input @commit.json

The draft becomes the Blueprint's next version number and keeps its id. New tasks run the latest committed version. A version needs a description and at least one agent node before you can commit it.

A committed version never changes, so a running task keeps the graph it started with. To change a Blueprint, copy a version into a new draft with blueprints.draft, edit the draft, and commit it. blueprints.read returns any version's graph, and blueprints.discard deletes a draft that you no longer need.

Choose what the agent may do

Only the publish node pushes the agent's changes. Publishing explains what it commits, pushes, and opens.

A capability takes a name of your choice and one of the capability operations. Agent nodes can use the capabilities, for example to comment on the pull request. When the Session works on a tracker issue and no capability has issues.read, the agent also gets a linked-issue capability that reads that issue.

Review the pull request automatically

Add a review node with one succeeded edge from the publish node:

{ "key": "review", "label": "Review", "group": null, "kind": "review" }

When the task succeeds after reaching the review node, a second agent reviews the open pull request of the task's branch. See Review pull requests.

Ask for values

A requirement asks for a value when someone starts a task:

{
  "name": "environment",
  "type": "string",
  "source": "dispatch",
  "optional": false,
  "description": "Where to deploy, such as staging."
}

The person who starts the task passes it in inputs, for example { "environment": "staging" }.

With "source": "organization", the value comes from the Organization variable with the same name instead. See variables and secrets. With "source": "issue", the value is the id of the issue the task is linked to: the issue that sessions.dispatch names in its issue field, or sessions.continue for a task linked to none, or the issue whose conversation or new-issue Schedule starts the task.

A task that starts without a required value starts nothing. devboxes asks for every missing value at once, using each description. In Chat, devboxes asks in the thread. Start a task in the dashboard hands your message to devboxes, which takes the values from it or asks you. In a terminal, devboxes invoke sessions.dispatch asks for them and starts the task again. A script or an agent gets one refusal that lists every input without a usable value, with its source, type and description: BLUEPRINT_INPUT_MISSING when any value is missing, and BLUEPRINT_INPUT_TYPE when every listed value only has the wrong type.

Reuse steps from another Blueprint

Put related nodes in a group. blueprints.place-group copies a group from any version in your Organization into a draft, with its child groups, their nodes, and the edges between those nodes. A prefix keeps the copied keys unique. Then connect the group with blueprints.replace-draft.

Limit a Blueprint to some Projects

All Projects can use a Blueprint until you bind it to one. Then only bound Projects can use it:

{
  "organizationId": "<organization id>",
  "blueprintId": "<blueprint id>",
  "projectId": "<project id>",
  "enabled": true
}

devboxes invoke blueprints.bind --input @bind.json

Binding also makes it the Blueprint that tasks naming none use. See Start a task.

When the Chat policy can't start a Blueprint that a Chat Channel's Project can use, blueprints.bind and blueprints.commit still succeed and return a warning. See Turn on Chat.

List and archive Blueprints

blueprints.list shows your Blueprints with their versions, and when a task last used each one in lastUsedAt. blueprints.archive retires a Blueprint, and its versions can no longer start tasks.