Skip to main content
By default a failing gate fails the task, but the work still ships as a draft pull request. A policy block changes that. It lists the evidence a task must have before it is published. reviewers defines named reviewers the agent can ask for a second opinion.

​
Policy

.bellows.yaml (excerpt)
required is the only value. Any other value, an unknown key or a repeated key is an error. Leave a key out to require nothing. You can set one or both. gates: required needs an environment block; without one the file is refused. Declare at least one gate there too, or the requirement has nothing to check.

​
What counts as evidence

  • Gates: a full, unfiltered pass that passed. Runs the agent made with a filter do not count, and neither do runs on a tree that has since changed.
  • Review: the latest review of the task must be clean. A review that is unfinished, failed or cancelled does not approve. One that found blockers rejects.
  • Evidence is tied to the exact revision of the work. If the agent edits anything after a clean review, the review is stale and must be asked for again.

​
Policy comes from the base branch

Bellows reads .bellows.yaml, including policy and reviewers, from the tip of the task’s base branch, or the default branch if none is set. It reads it through GitHub, never from the agent’s working tree. A task can edit the file in its own branch, but that edit changes nothing for that task. It takes effect only after it is merged into the base branch. So an agent can’t weaken its own requirements. To change policy, merge a change to .bellows.yaml first.

​
When policy blocks

Nothing is pushed. The task fails with the badge evidence required, and the reason is one of these:

​
Reviewers

A reviewer is a separate agent run with its own instructions and time budget. It reads a frozen copy of the tree and reports findings and a verdict (clean or blockers). It can’t publish anything and is told to change nothing. The main agent calls it by name.
.bellows.yaml
You can declare up to 8 reviewers. The format is a list that starts each item with - name:. Indent with spaces, as in the rest of the file. A reviewer grants a time budget and the connections you name. It is not a tool allowlist.

​
How reviews reach the policy

With review: required, the agent asks for a review by reviewer name before it finishes. The latest review decides. If the agent changes the tree after a clean verdict, it must ask again. A review that finds blockers must be answered with a fix and a new review. Declaring reviewers without policy: review: required makes reviews available, but optional.
Start with gates: required alone. Add review: required once you have a reviewer whose instructions are narrow enough to give clear verdicts.

​
Common errors

Add an environment block with an image and your gates, or drop gates: required.
Policy is read from the base branch. Merge the change first, then start a new task.
Every reviewer needs a non-empty instructions line.