Autonomous Workflow

Buildd is autonomous by default. Agent PRs merge automatically once green CI and a set of safety rails all pass, missions self-complete when their work is done, and progress tracking excludes housekeeping tasks so the number you see reflects real work. You opt out of automation selectively — per task or per mission — rather than opting in.

Auto-Merge on Green CI

When an agent creates a PR, Buildd evaluates it for auto-merge once CI reports back.

This is on by default for every workspace. When a PR does merge, it merges as a squash, and a release is triggered automatically.

What must pass before a merge

First the merge policy is resolved, with task settings overriding mission settings overriding the workspace default. Only the auto-threshold tier is eligible to merge at all — human holds the PR for you, and agent-review defers to the reviewer agent, which triggers the merge itself on approval.

The same tier governs the merge_pr MCP action, so an agent cannot merge its own PR under agent-review or human — see merge_pr is gated by the merge policy tier.

An eligible PR then has to clear every one of these:

A PR file listing that cannot be fetched, or that comes back malformed, also blocks.

The migration classifier

Because a bad migration is not something CI reliably catches, any PR touching generated SQL migrations or the schema file is classified by operation class:

• EXPAND — purely additive and reversible. Passes.
• CONTRACT — destructive or irreversible. Blocked for human review.

Classified as CONTRACT: dropping a table or column; renaming a column or table; changing a column's type; adding a NOT NULL constraint to an existing column; adding a NOT NULL column with no default; and data migrations (UPDATE/DELETE/INSERT) inside a migration.

The classifier also blocks on structural problems rather than statement content: changing the schema file without generating a migration, editing or deleting a migration that already exists, a migration number that collides with one in another open PR, and mixing EXPAND and CONTRACT migrations in a single PR (ship the additive change first, then the destructive one once nothing reads the old shape).

It is deliberately conservative: any statement it cannot parse is treated as CONTRACT, so an unrecognised migration is held rather than merged.

Disabling auto-merge

To require human review of every agent PR in a workspace, clear Auto-merge on green CI under the workspace's Git configuration.

This applies workspace-wide. To hold individual PRs instead, use requiresReview on the task (see below).

What a Reviewer Approval May Merge

Under agent-review the reviewer agent's approve can merge the PR — but what it may merge into is bounded by the branch the PR targets, not by the verdict.

The merge additionally requires that your build/test workflow reported success for the PR's head commit. An absent check run is not a passing one: if the workflow never ran for that ref, the approval escalates instead of merging.

Escalation triggers — schema migrations, deny-path files, risk classes your policy reserves for humans — are enforced from the PR's file list on the server, not from anything the reviewer reports. They are re-checked when the verdict lands, so a file added while the PR was being revised is still caught.

Giving the Reviewer the Diff

By default the reviewer sees the PR's changed filenames, not its contents. Set reviewerPatchEvidence in the workspace's policyConfig to pre-inject the patch itself:

curl -X PATCH https://buildd.dev/api/workspaces/{id} \
  -H "Authorization: Bearer $BUILDD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "gitConfig": { "policyConfig": { "reviewerPatchEvidence": true } } }'

The patch is rendered with a line number on added lines only, so a finding that cites path:line is citing a line the PR introduced. Files that do not fit the token budget are listed by name under an explicit "not reviewed" heading rather than silently dropped. Off by default, since it changes what your reviewer's verdicts are based on.

requiresReview Opt-In

requiresReview: true holds a PR open for human review before it can merge. Use it when a task or mission produces changes that warrant a manual look.

On a task

Set requiresReview when you create the task:

curl -X POST https://buildd.dev/api/tasks \
  -H "Authorization: Bearer bld_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Refactor auth middleware", "requiresReview": true }'

The agent creates the PR as usual, but Buildd does not merge it.

What does not work

To hold an already-created task, hold its PR instead — set the workspace or mission merge policy to human (below), or turn off Auto-merge on green CI for the workspace.

On a mission

Set requiresReview on a mission to hold every PR created by that mission's tasks. Again, create-time and REST only:

curl -X POST https://buildd.dev/api/missions \
  -H "Authorization: Bearer bld_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Q3 API hardening", "requiresReview": true }'

buildd action=manage_missions — with action: "create" or action: "update" — does not accept requiresReview. It is not in the action's parameter set, so it is dropped without an error and the mission is created or updated with review off.

To require review on an existing mission, set its merge policy instead. PATCH /api/missions/{id} accepts a validated mergePolicy, and tier: "human" produces the same "never auto-merge" outcome:

curl -X PATCH https://buildd.dev/api/missions/{id} \
  -H "Authorization: Bearer bld_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "mergePolicy": { "tier": "human" } }'

requiresReview on a mission also gates mission completion: the mission will not auto-close until you confirm it in the dashboard (see Mission dormancy below).

Mission Dormancy / Auto-Complete

Missions monitor their own task health and close themselves when the work is done. You do not need to manually close a mission.

How it works

A mission is eligible to close when:

1. All deliverable tasks are completed with merged PRs.
2. No tasks are actively in progress.

When both conditions are true, the mission status transitions to completed and its check-ins stop automatically.

requiresReview gate

If the mission was created with requiresReview: true, auto-close is suspended. The mission enters a dormant state and waits for a human to confirm completion in the dashboard:

1. Open the mission detail page.
2. Review the completed tasks and merged PRs.
3. Click Close mission to confirm.

Until you confirm, check-ins continue, but they will not create new tasks.

Mission Progress (Deliverables Only)

The progress percentage shown on a mission counts only deliverable tasks — tasks that produce real output (engineering work, research, design). Orchestration and housekeeping tasks are excluded.

What counts

This means a mission whose real work is done shows 100% even if there are failed or ongoing organizer runs. The percentage reflects outcome, not operational overhead.

Why this matters

A multi-phase mission typically includes:

• Execution tasks that build or fix things (deliverables)
• Organizer runs (planning tasks) that coordinate the work (housekeeping)

Without this distinction, a single failed organizer run would drag a complete mission below 100%. Buildd excludes housekeeping tasks so progress always reflects the state of the actual work.

Summary