About Executing
Executing is the second stage of the Vinaya process. One Issue goes in. One pull request the Principal can merge comes out, or a pause that says why and who must act. See Overview for where it sits in the whole process.
Executing has three modes. They all run on the same Issue object, and any Issue kind (planned, backlog or hot) can take any mode. Every pull request lands on its Issue's parent branch.
| Mode | Who codes | Rounds | Gates and review |
|---|---|---|---|
| The loop | A Developer agent in a sandbox, through controller-run tools | Until ready, or a pause | Every gate; two reviewers each round; the controller decides |
| Batch | The loop over many Issues; the controller picks the next within capacity | Per Issue | Same as the loop |
| Hot mode | The Principal and an agent, live, editing directly | None | Every gate at commit and push; two reviewers once, on demand; review again after a push |
How it works
Some promises hold in every mode:
- The brief freezes at dispatch. A change is a new Intent version with a reason, never an edit.
- Named documentation is delivered. Documentation the brief names reaches the Developer, and the Developer cites it in its result.
- Two independent reviewers. Code and Security are both required. They run in parallel, each in a fresh session. A missing or malformed review counts as no review.
- The Developer publishes only through the controller's tools. In hot mode the Principal publishes; the gates are the same.
- A pause names who acts.
- Ready for merge is terminal. Merge is the Principal's.
In the loop, a run goes like this:
- 1
Prepare the run
Fast-forward the checkout, check dispatch readiness, then freeze and pin the brief.
- 2
Prepare required sources
The controller builds a manifest of the documentation the brief names, with a receipt for each delivery.
- 3
Dispatch the Developer
Round 1 gets a full context packet; later rounds get a delta packet.
- 4
Publish through the controller's tools
The Developer commits and pushes through the tools. Ring 0 runs at commit and push.
- 5
Accept the Developer's result
The controller accepts a typed turn result from the Developer.
- 6
Read the mechanical gate
CI on the current head, mergeability, and a re-check of the premises. From round 2, the confidence rule applies.
- 7
Review
Fresh Code and Security reviewers judge the pull request on one review-input manifest.
- 8
Assess the round
The controller decides: revise sends current findings to the same Developer session; pause is retried by the controller itself, repaired by the Operator, corrected by the Planner, or ruled on by the Principal; publish posts the verdicts and the pull request is ready for the Principal's merge.
You start a run in one of three ways:
vinaya task run <tranche> <n>
vinaya task run --issue <n>To walk through a run end to end, follow a guide: Deploy backlog issues, Deploy medium work, or Deploy hot issue now for hot mode.
Who takes part
| Role | In Executing | Human or agent |
|---|---|---|
| Developer | Executes one frozen brief in a sandbox through the controller's seven tools. Never holds a forge credential; never pushes, merges or rules. | Agent; one session resumed across rounds |
| Reviewer (Code) | Judges the pull request against its brief and objectives | Agent; fresh each round |
| Security | Judges secrets, unsafe configuration and exposed surfaces | Agent; fresh each round |
| Operator | Starts, watches, resumes and cancels tasks through six task tools; presents pauses. Never plans, codes, rules, approves or merges. | Agent |
| Principal | Rules on pauses, merges, enters hot mode | Person |
| Execution Planner | Proposes a versioned plan correction when a running task proves its plan wrong (planned, with batches) | Agent |
| Planner | Receives missing_source pauses and pre-pull-request widen_surface requests, and supersedes the brief | Agent |
The controller (also called the driver) is not a role. It is harness machinery: it spawns every agent, holds the forge login, and derives every decision through one pure decision function. See Roles.
The parts of Executing
The loop
The developer-review loop, step by step
Batches
Many Issues within capacity, dependencies and conflicts, the Execution Planner
Hot mode
The Principal and an agent, live, with no loop
The Operator
The six task tools, refusals and authority
Pauses and rulings
Pause classes, pause and ruling records, resume and cancel
Parent and integration branches
Where work lands
Where the gates run
Each step of a loop run meets these gates. See Gates for every check.
| Step | What runs | Ring |
|---|---|---|
| Prepare the run | dispatch- and a recompute of the facts; the brief is frozen and pinned | 1 |
| Developer works | The Developer publishes only through the controller's tools | — |
| Commit and push | The commit checks (brief-shape, pr-, doc-coverage, exec-bits, changeset-, main- and the rest), then the push checks (coherence, branch-topology, first-, quoted-command and the rest). A refusal returns to the Developer in the same session. | 0 |
| Pull request opened or updated | closes-n, surface-scope, test-plan, evidence-fresh, body-bare-digits, plus every Ring 0 check again | 1 |
| Mechanical gate read | Scope, evidence and CI for the current head | 1 |
| Reviewers | Code and Security, fresh, on one immutable review-input manifest | — |
| Assess the round | review-gate validity; the controller decides | 1 |
| Before merge | principal-; every required check green on the current head | 1 |
The controller also runs gates of its own, outside the 37 checks:
- the publication preconditions (wrong branch, unexpected base, moved head);
- the protected-path gate;
- the credential scan;
- the enforcement-controls check before every unattended dispatch;
- the after-turn confinement check;
- the agent-config security scan (
securityScan.) when a change touchescommand .claude/**,.mcp.jsonor.agents/**.
In hot mode there is no loop and no controller. Ring 0 runs at the Principal's commit and push, Ring 1 on the pull request, and review runs once on demand. See Hot mode.
Configuration
These keys in vinaya. shape a run. See Vinaya keys.
| Key | What it sets | Default |
|---|---|---|
reviewPolicy. | The severity at which code review blocks | MAJOR |
reviewPolicy. | The severity at which security review blocks | HIGH |
reviewPolicy. | Revision rounds before a Principal ruling | 3 |
reviewPolicy. | Active working-time budget; 0 turns it off | 180 (Vinaya's own repository sets 600) |
dispatch.agent | Which runtime plays the roles (claude, codex) when --agent is absent | — |
dispatch. | Wall-time ceiling for a Developer dispatch | Four hours |
dispatch. | Ceiling for each reviewer dispatch | Twenty minutes |
runtimeDir | Where the controller keeps its files. Absolute, outside the repository, repo-local only. | ~/ |
securityScan | The agent-config scan the controller runs | — |
The rule that pauses on a finding open for two rounds is fixed, not a setting.
What gets logged
| Step | Events |
|---|---|
| Loop lifecycle | dev_review_loop · loop_started, round_started, round_ended, paused, resumed, cancelled, stop_, journal_ |
| Liveness, for Mission Control | dev_review_loop · driver_heartbeat (at most every five minutes), driver_exited |
| Developer and reviewer turns | dispatch · dispatched, outcome_received or dispatch_failed; role_attempt · attempted; usage · observed |
| Gate results | dev_review_loop · gate_result_read; gate · summary and checked |
| Reviews | dev_review_loop · verdicts_read (with a findings array), findings_ |
| Pauses | handoff · raised and resolved |
| Recovered hiccups | dev_review_loop · infrastructure_ |
| Writes to the forge | effect · verified |
| Operator and broker calls | operation · completed |
The Log is fail-open telemetry. It never authorizes or resumes a run: recovery reads the control store and principal-authored forge markers, never a Log event. See Events for every field.