# mergetrain for LLM agents

mergetrain serializes committed coding-agent branches through one local
merge/test/push/verify runner. Its 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.

### 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 with only the task, branch, and optional worktree; mergetrain captures the exact commits. Stop after a successful enqueue unless the user explicitly authorized end-to-end validation and deployment.
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 stops after ordinary `enqueue`. Only a separately authorized runner uses `validate`, `deploy`, or a daemon.
- Deployment requires either confirmation of the human-readable exact plan or prior bounded unattended approval. Train IDs and hashes stay internal.
- 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.

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