# mergetrain for LLM agents

Queue committed branches from parallel coding-agent worktrees, test the
combined tree in order, give integration pushes one approval-gated owner, and
recover interrupted Git pushes.

The normal product grammar is intentionally small:

```text
init  status  enqueue  validate  deploy  inspect
```

## Shared operating protocol

<!-- BEGIN GENERATED: mergetrain-agent-protocol -->
Purpose: Serialize committed local task branches through one merge/test/push/verify runner.

### Existing queues and explanations

- Existing mergetrain repositories keep status → enqueue → stop even for one branch. Queue counts alone do not establish health, runner ownership, or recovery needs; read `health`, `state`, and `next_action` together.
- For explanation-only requests, read the skill documentation when permitted and explain the procedure without Git or product commands. Distinguish hypothetical steps from observed state.

### Current command reference

- The v3 core commands are `init`, `status`, `enqueue`, `validate`, `deploy`, and `inspect`.
- Start with `mergetrain status --json`. Use `mergetrain status --diagnose --json` only for configuration, Git, runtime, or lock detail, and `mergetrain inspect JOB_ID --json` for job evidence. `doctor` is removed, not an alias for `status --diagnose`.
- Confirm uncertain syntax with the installed `mergetrain --version` and command-specific `--help` only when command execution is permitted. Otherwise use this reference and identify missing details; do not invent commands or copy older syntax from unversioned web results. Inspection and `next_action` do not authorize recovery or deployment.

### Rules

1. Work on a task-specific branch and worktree.
2. Commit a clean HEAD before handing work off.
3. Read mergetrain status --json and follow its next action before changing queue state.
4. Enqueue every named finished branch in the requested order using only its task and branch; mergetrain resolves the worktree and captures the exact commits. Stop after the last successful enqueue unless the user explicitly authorized validation or the complete validation-and-deployment workflow.
5. Never push configured integration refs directly. One authorized runner owns validation and deployment; recovery and destructive actions require their stated approval.

### Safety boundary

- A task agent enqueues every named finished branch, then stops. "Queue for validation" authorizes enqueue only; only an explicit request to run validation or the complete end-to-end workflow authorizes `validate`.
- Only a separately authorized runner uses `deploy` or a daemon.
- Deployment requires either confirmation of the human-readable exact plan or prior bounded unattended approval. Agents never select train IDs or supply plan hashes; structured evidence may include identifiers for inspection.
- Unattended approval is bound to the exact destination and execution policy. Any change blocks before push.
- Recovery and destructive cleanup require their stated approval. Follow `status.next_action`; never rewrite permanent deploy audit refs.

### Stable machine contract

- Every JSON payload carries `contract_version`; ignore unknown keys and fail closed on unknown safety actions.
- `deploy` means the atomic Git ref update plus configured verification. A downstream provider release is separate.
<!-- END GENERATED: mergetrain-agent-protocol -->

## Normal workflow

```sh
mergetrain status --json
mergetrain enqueue --task "TASK" --branch BRANCH
```

After ordinary enqueue, stop. With explicit end-to-end authority, the operator
path is `mergetrain status` followed by `mergetrain deploy`. `deploy` validates
if needed, shows one exact plan, requires human confirmation, rechecks the plan,
and only then may push. `validate` is the optional non-pushing path for running
gates earlier. Use `inspect JOB_ID --json` only when status points to a job.

`status` projects internal detail into Waiting, Running, Ready, Attention, and
Done. If exceptional recovery is needed, follow its exact
`next_action.command`; do not guess or edit the SQLite database.

## Integrations

- MCP: install `mergetrain[mcp]` and run `mergetrain mcp`; the default server
  exposes exactly five tools matching status, inspect, enqueue, validate, and
  deploy.
- Claude Code: install `mergetrain@mergetrain` from the
  `yongjip/mergetrain` marketplace. `/mergetrain:deploy` still requires the
  MCP client's human confirmation dialog.
- agy: install `https://github.com/yongjip/mergetrain` as a native plugin. Its
  skill uses the same generated protocol and its MCP configuration launches the
  release-pinned wheel through `uvx`.

See `docs/agent-contract.md`, `docs/contract.md`, and `docs/cli.md` for the
authoritative details.
