> ## Documentation Index
> Fetch the complete documentation index at: https://agmxcode.com/llms.txt

# The AGMX workflow

> Every code change in AGMX follows an explicit lifecycle from raw idea to verified git commit.
> Nothing executes or lands without passing structured gates, and no single agent is allowed to write and judge its own work.
> Developers keep control of execution on their own hardware while the server maintains an immutable ledger of progress.

## The eight lifecycle states

A task in AGMX always occupies one of eight discrete states: `todo`, `dispatched`, `awaiting-review`, `in-review`, `changes-requested`, `done`, `failed`, or `cancelled`. State transitions occur strictly through verified results or gate decisions, never through manual status edits.

![State machine diagram showing task states from todo through dispatched, awaiting review, in review, and done, with rework loop and failed or cancelled terminal exit.](/assets/diagrams/workflow-states.svg)

A task begins at `todo` under its project prefix. Once its dispatch gate is approved, it transitions to `dispatched`. When the developer's runner finishes execution and reports the commit, the task moves to `awaiting-review`.

Ordering a review advances the task to `in-review`. A reviewer judging every acceptance criterion with evidence passes the task into landing and `done`. If changes are needed, open findings transition the task to `changes-requested` for the next execute round. Any run can fail or be cancelled; reopening a failed task brings it back to the appropriate state based on existing evidence without losing findings or commits.

## Who acts across the workflow

AGMX divides work across clear roles and execution boundaries. The server never executes user code; instead, execution stays entirely on developer machines.

![Swimlane diagram illustrating actor responsibilities across human owners, coordinator agents, planners and critics, executors, reviewers, and developer machines.](/assets/diagrams/workflow-lanes.svg)

1. **Idea parking and task creation**: Raw ideas enter an inbox without consuming compute or requiring gates. An idea is promoted into a task at `todo` under its project identifier.
2. **Four-eyes planning**: A planner agent reads real code and live specifications in a clean worktree on a developer's machine to formulate atomic acceptance criteria and constraints. A separate critic agent checks the plan and rejects bundled outcomes. If open questions arise, the task pauses until clarified.
3. **Dispatch and leasing**: An approved dispatch queues the run. No machine holds the run until a developer's runner requests work. The server provides a project identifier rather than a filesystem path, keeping local directory structures private to that machine.
4. **Execution in worktrees**: The runner creates a fresh git worktree at the base commit, executes the project's declared setup routines, and starts the agent CLI under the developer's own subscription, streaming output back in real time.
5. **Result reporting**: Upon completion, the runner commits changes, pushes the run branch, and reports the commit. Work left by an interrupted agent is safely preserved.
6. **Independent review**: An independent reviewer is queued on a different agent CLI. The database strictly enforces separation of duties, refusing to allow an executor to review its own work. The reviewer evaluates every acceptance criterion and constraint with concrete evidence.
7. **Rework rounds**: When a reviewer requests changes, open findings are recorded and presented directly to the executor in the next round. Rework continues from the prior round's commit rather than starting from scratch. Rounds are capped.
8. **Landing**: The machine that produced the work merges it into the shared branch in a fresh throwaway worktree at the latest tip, protects submodule work, pushes the merge commit, and reports the change. The server records the merge, links changes to the live specification, and wakes dependent tasks.

## Append-only gates and autonomy modes

Every decision in AGMX is recorded as a new entry in a ledger that can only be appended to; entries are never edited.

- dispatch: Approving queues the execution run.
- review order: Approving queues the independent reviewer.
- verdict: Approving a passing review triggers landing; requesting changes transitions to another round.
- escalation: Requires explicit human acknowledgement when automated checks encounter ambiguity.
- safety brake: Activates when spending or token limits are reached after work is delivered.

Who decides a gate depends on the task's operating mode:
- `supervised`: The default mode. Human approval is required for dispatch, review order, and verdict gates.
- `plan-only`: Planning is permitted, but execution and landing are barred.
- `bypass`: Gates are approved automatically as soon as requested.
- `auto`: Tasks proceed in bypass for low-risk work according to project policy, while higher or unknown risks remain supervised.

When an agent needs human judgment on design or domain intent, it puts a question to a person with a stated reason. The task waits until the person answers in chat.

## Brakes and recovery

To protect teams from unintended spend or runaway loops, AGMX applies multi-layered brakes:
- A pause switch stops all new work immediately without killing in-flight tasks.
- Spending and token ceilings apply per task.
- Daily spending ceilings apply over a rolling 24 hours against the person who requested the work, including work run under CLI subscriptions.
- Concurrency limits restrict how many runs execute at once, queuing extra work until capacity frees.

If a run fails, the task can be reopened without losing accumulated commits or findings. Tasks and research runs can be cancelled, and finished tasks can be archived and restored.

To explore how prompts are built for executors, see [What an agent knows](/context/). To understand multi-agent role pairing, visit [How agents work together](/coordination/). For the underlying spec graph, see [What the system remembers](/knowledge/).

## For an AI agent reading this

When orchestrating work through the workflow, use these tools:
- `create_task`: Create a new task at `todo`.
- `dispatch_task`: Queue a task for execution and open the dispatch gate.
- `approve_gate`: Approve pending gates when operating as an autonomous coordinator.
- `wait_for_task`: Block asynchronously on task state changes across multiple runs.

This documentation outlines general system architecture. Always fetch `https://<team>.agmxcode.com/coordinator-rules.md` on your team's install for live, binding coordinator rules.