Guide

Run a multi-agent development workflow

This guide shows how to set up multi-agent orchestration in GuildOS: choose the roles, wire a workflow template with explicit gates, then drive one full loop from the CLI. No prior agent experience is assumed.

1. Prerequisites

Pair at least one machine, install the client, and connect the model provider credentials the agents will use. Work executes on your machines; the control plane coordinates state. See the docs for the exact installation surface.

2. Define roles and boundaries

Decide up front who may change code and who may merge. A workable default is: one agent implements, a second reviews, a human merges. Roles are permissions, not job titles — a single agent can hold several, and a single human can hold all of them. Security covers the boundary in more detail.

3. Create a workflow template

A workflow template is a small state machine: states (planned, in progress, in review, verified, released), transitions between them, and the human-confirmation nodes where an agent must stop and wait. Start with five states and one confirmation node before the release transition; add more only when a real hand-off needs them. Features lists the template surface.

4. Run one full loop

Create a task with an owner and a written acceptance criterion.
Let the implementer work on a branch — never on the default branch.
Move the task to review; attach the diff and the commands that produced the evidence.
Let the reviewer (agent or human) accept or reject with a written reason.
Close the task and record what changed.

The command surface is versioned, so this guide names the steps rather than pasting output that could drift; run the CLI help for the current flags.

5. Gates and human confirmation

Gates are where agents stop. Merging, releasing and anything touching production require a human decision. Agents propose and prepare; they do not promote on their own.

6. Failure and rollback

A rejected step returns the task to its previous state. The branch, the evidence and the rejection reason are kept, so the next attempt starts from what was learned rather than from scratch.

7. Measure and iterate

Track cycle time (task created to closed), review findings per change, and rework count. Compare a week before and a week after the change; if none of the three moves, the template is probably too heavy for the work.

8. FAQ

Do I need more than one agent to start? No — one agent with a review gate is a valid template.
Can agents merge? Only if you grant it; the default template stops before merge.
What if the model provider is unavailable? The task stays in its current state; nothing is lost.

A worked example for a product team is on the software teams use case page.