# Conveyor — Agent Protocol

You are an AI coding agent working in a repository that merges through
**Conveyor** (https://conveyor-docs.vercel.app), not the GitHub merge button.
Source: https://github.com/trilogy-group/conveyor. Follow this protocol
exactly. If your repo has an `AGENTS.md` or `CLAUDE.md` with a "Merging
(Conveyor)" section, that section takes precedence over this page.

## The five rules

1. **Claim before you code.** Reserve the files you intend to touch:

       conveyor claim "<glob>" [more globs...] --task <task-id>

   If the claim is refused, those files belong to another in-flight task.
   Do not start — pick another task or wait. Never work on files you could
   not claim.

2. **Write the intent first.** Create the manifest:

       conveyor intent new --task <task-id>

   This writes `.conveyor/intents/<task-id>.md`. Fill the body with a full,
   self-contained prompt for redoing the task from scratch on a fresh
   checkout of a future main: goal, constraints, named edge cases,
   acceptance criteria. Keep the `write_set` globs accurate as you work.
   Conveyor may re-run you (or another agent) from this file alone — a vague
   manifest regenerates into a different change every time.

3. **Stay inside your write-set.** If the task needs files outside it, stop,
   widen the claim (`conveyor claim` again with the extra globs), and update
   the manifest's `write_set`. Never silently touch unclaimed files.

4. **Enqueue, then walk away.** Before opening the PR, run:

       conveyor intent check

   and make sure the fast check passes locally (see `conveyor.yml` →
   `fast_check.run`). Open the PR, add the `conveyor:queued` label (or run
   `conveyor merge <pr>`). You are done. Do not watch the queue. Do not
   rebase. Do not resolve merge conflicts. If your PR is evicted or
   conflicts, Conveyor regenerates it from your intent manifest against
   fresh main — that attempt supersedes yours.

5. **A fix-forward task is a normal task.** If you are invoked with a
   `.conveyor/fix-task.md`, it contains the failure log and the original
   intent. Fix the failure, keep the original acceptance criteria true, and
   enqueue as usual.

## Regeneration jobs

If you are running inside a Conveyor regeneration job, the environment
provides `CONVEYOR_INTENT` (path to the intent manifest to execute) and
`CONVEYOR_TASK` (the task id). Your working tree is fresh main with only the
manifest restored. Redo the task from the manifest, commit, and exit 0 —
the job pushes and re-enqueues for you.

## Never do these

- Merge directly, press the GitHub merge button, or bypass the queue
  (`conveyor bypass` is a human, audited, emergency action).
- Rebase or resolve conflicts on an enqueued PR — regeneration will
  overwrite the branch anyway.
- Force-push a PR branch after enqueueing.
- Reuse a task id — claims, regeneration counts, and history key on it.
- Put more than one intent manifest in a PR — one task per PR.

## Reading system state

- `conveyor status` — queue, train positions, check states, claims.
- `conveyor claims` — active write-set reservations.
- PR labels tell you where a PR is: `conveyor:queued`, `conveyor:in-train`,
  `conveyor:evicted`, `conveyor:regenerating`, `conveyor:failed` (needs a
  human — move on).

Full documentation: https://conveyor-docs.vercel.app/docs/