Your first agent

You will be able to point a coding agent at commission so it claims work, records what it learns, proves what it finished, and closes tasks — without you narrating the state of the project into every prompt.

Assumes: you have run your first task by hand. Do that first; you cannot debug an agent operating a loop you have not seen.

Teach the agent the loop

commission prime

prime prints commission’s operating manual, addressed to an agent and scoped to the project it resolved from .commission.json — the session-start commands, the breadcrumb discipline, the finishing rules, and the exit codes. It is generated from the same source the CLI is, so it cannot drift from the binary.

Put it where your agent reads its instructions:

commission prime > CLAUDE.md

Append it if the file already has content you care about. For Cursor, Codex, or anything else that reads a rules file, the destination changes and nothing else does.

That single file is why Commission does not need an integration per agent: the agent already has a shell, and commission is a command.

The one command a session starts with

commission next --project myapp --claim

This is the whole handoff. It selects the highest-priority ready task the actor is eligible for, claims it atomically under a lease, and returns the context bundle: body, acceptance criteria, dependency state, linked documents, recent notes, answered decisions, approval state, and the commands that come next.

Atomic means what it says. Two agents running that command against the same project get two different tasks — the claim is decided by a single conditional statement in SQLite, so there is no window in which both can win. That is the primitive parallel dispatch is built on, and it is the same primitive behind POST /v1/next and the commission_next MCP tool.

Give each agent a distinct actor name, and the log afterwards is legible:

COMMISSION_ACTOR=claude:api commission next --project myapp --claim

If the bundle is too large for the context you want to spend, cap it:

commission next --project myapp --claim --budget 4000

Sections are dropped in a fixed order — events first, then older notes, links, dependents, children, bindings, evidence, dependencies, criteria, body, vision — and the response declares what it omitted. Task identity and state are never dropped, because a bundle that cannot say which task it is is broken rather than small.

When Bash is not available

Register the MCP server once, and the agent gets the same core as typed tools:

claude mcp add commission -- commission mcp

The MCP surface is deliberately narrower than the CLI: the working loop (claim, record, prove, close) and planning, not project administration or import. Refusals come back in commission’s standard shape — message, missing, and the fixing command — marked isError, so a model can correct itself without a human. Every tool and parameter is in the MCP reference, which is generated by reading the live server over the protocol.

What the agent does while working

Three commands carry the whole session, and they are worth putting in your own words in the rules file:

commission note myapp-2 -m "signature check needs the raw body — express.json() ate it"
commission check myapp-2 0
commission evidence myapp-2 pr=https://github.com/acme/myapp/pull/14 test=ci-2211

Notes are the durable part. The reasoning behind a decision is normally the first thing lost between sessions — it lives in a chat log nobody opens again — and a note attached to the task is carried in every future context bundle and is full-text searchable.

If the agent hits a decision that is not its to make, it escalates instead of guessing:

commission ask myapp-2 -m "Reject unsigned webhooks, or log and continue?" --blocking

--blocking is a control, not a label: while the question is open, no agent may claim the task, and the refusal names the question. A human answers, and work resumes. See execution policies.

Finishing, and why it refuses

commission done myapp-2

Commission refuses until the acceptance criteria are ticked and the gate’s evidence is attached, and the refusal names the exact command that fixes it. An agent should treat exit code 2 as an instruction and act on it; it should not --force, and --force requires -m "<why>" which is written to the event log. See exit codes.

A session, start to finish

commission next --project myapp --claim
commission start myapp-2
commission note myapp-2 -m "signature check needs the raw body"
commission check myapp-2 0
commission check myapp-2 1
commission evidence myapp-2 pr=https://github.com/acme/myapp/pull/14 test=ci-2211
commission done myapp-2
commission next --project myapp --claim

That last line is not decoration. An agent that ends a task by asking for the next one runs until the frontier is empty, and every step of it is attributable afterwards.

Fanning out

commission ready --project myapp

ready reports which tasks are workable now, which of them overlap on touches, and suggests batches with no overlap at all. Dispatch a batch to several agents, each with its own COMMISSION_ACTOR, and let the claim decide who gets what.

An honest limit, stated where you will read it before relying on it: a touches-overlap warning is a signal, not a proof. Commission compares labels you wrote; it does not read your code. No warning does not mean two tasks are safe to run at once. Parallel work covers how to use it well.

Next

• Guides → task lifecycle — every transition and what refuses.
• Guides → parallel work — fan-out without collisions.
• Reference → MCP — every tool, generated from the live server.
• Reference → JSON output — what to parse.

Part of Start here.