# Agent cheatsheet

A single‑page recipe for driving Automaintainer from an **agentic CLI** (hermes,
Claude Code, etc.). Everything an orchestrating agent needs: setup, the full
command surface, the JSON contract to branch on, and copy‑paste loops. You can
save this page as a skill — or fetch the raw markdown at
`/docs/agent-cheatsheet.md`.

## What AM does

You give a repo a bounded objective; a fleet of agents implements it, **verifies**
it (build → test → fix → re‑verify), and opens a merge‑ready PR. *Done = verified.*

## Setup

`am-cloud platform` is the control CLI. Authenticate with two values (flags or env):

```bash
export AM_PANEL=wss://automaintainer.intrane.fr   # or --panel <url>
export AM_API_KEY=amk_...                          # or --api-key <key>
```

Output is **JSON by default** (stable schema + exit codes); add `--human` for text.

## Command surface

```
platform status                                 # account + workers
platform repo list                              # → {repos:[{id,name,enabled,focus}]}
platform repo add <url> --focus <text>          # → {repo:{id,...}}
platform repo set <id> [flags]                  # see flags below
platform repo run <id> [--wait]                 # trigger; --wait polls to terminal
platform repo run --repo <url> [--focus <t>] [--wait]   # one-shot: add-if-missing → run
platform runs [--repo <id>]                     # → {runs:[...]}
platform explore <id>                           # kick a scout (Pro+)
platform candidates <id>                        # → {candidates:[{id,category,title,...}]}
platform candidate run|reject <cid>             # act on a candidate
platform probe --cli <c> [--model <m>]          # → {probe:{ok,reason,latency_ms}}
```

`repo set` flags (only the ones you pass are written):
`--focus` · `--verify` (gate cmd) · `--objective` · `--acceptance` · `--team` (JSON)
· `--clis` (JSON) · `--arch-context` · `--name` · `--spawn-interval` (int)
· `--explore` · `--auto-merge` · `--reviews` · `--issues` · `--issue-scout`
· `--pr-watch` · `--enabled` (bools; disable with `=false`).

## JSON contract — what to branch on

| Field | Where | Use |
|---|---|---|
| `result` | every response | `"success"` vs error envelope |
| `probe.ok` / `probe.reason` | `probe` | gate spend: only run if `ok==true` |
| `run.status` | `repo run --wait`, `runs` | `success` / `verify_failed` / `success_no_changes` / `no_op` (silent failure) / `failed` |
| `run.verify_status` | run | `passed` / `failed` / `skipped` |
| `run.pr_url` | run | the merge‑ready PR (empty if none) |
| `candidates[].id` | `candidates` | feed to `candidate run` |

Run statuses: `spawning` · `running` · `success` · `success_no_changes` ·
`no_op` (agents did nothing — usually a key/balance issue) · `verify_failed` ·
`pushed` · `failed`. Exit code `0` = success; non‑zero = error (type + message in
the JSON).

## Recipe 0 — one-shot (the fastest path)

"Use AM to enrich docs/ in this repo, run now" — a single idempotent command that
adds the repo if it's new, sets the focus, runs, and waits for the verified PR:

```bash
am-cloud platform repo run \
  --repo https://github.com/javimosch/supercli \
  --focus "enrich docs/" --wait
#   → {"run":{"status":"success","verify_status":"passed","pr_url":"…/pull/42"}}
```

Re-running the same `--repo` URL reuses the existing repo (no duplicate) and
updates the focus. To configure the gate/team/etc. first, use `repo set` (below),
then `repo run <id> --wait`.

## Recipe 1 — maintain a repo (verify before you spend)

```bash
# 1. confirm the EXACT model works (avoids silent no-op runs)
am-cloud platform probe --cli pi --model opencode-go/deepseek-v4-flash
#   → {"probe":{"ok":true,"latency_ms":2598}}   # if ok==false, fix the key/balance first

# 2. set the focus + the gate
am-cloud platform repo set r-123 \
  --focus "add a unit test for the untested parseConfig()" \
  --verify "npm ci && npm run test:unit"

# 3. run it and WAIT for the verified result
am-cloud platform repo run r-123 --wait
#   → {"run":{"status":"success","verify_status":"passed","pr_url":"…/pull/42"}}
```

## Recipe 2 — let AM choose the work (explore)

```bash
am-cloud platform explore r-123                 # scout proposes bounded work
am-cloud platform candidates r-123              # → pick a candidate id
am-cloud platform candidate run <candidate-id>  # applies its focus+gate and runs
```

## Recipe 3 — self‑healing loop (pseudo)

```
probe → if !ok: stop, report reason
repo set --focus … --verify …
loop up to N:
  run --wait
  if run.verify_status == "passed":   done → run.pr_url
  if run.status == "no_op":            stop → probe the cli/model (key/balance)
  if run.status == "success_no_changes": refine focus, retry
  else: read run, adjust, retry
```

## Gotchas (save a run)

- **Probe first.** A green background probe tests the *default* model; always
  `probe` the exact cli/model you'll use — *out of balance* is the #1 no‑op cause.
- **Gate runs from the repo root**, relative paths only — no `cd /abs/path`.
- **Objective vs focus:** `--focus` is this run; `--objective` is a persistent
  campaign AM keeps working until `--acceptance` passes.
- **A red gate never auto‑merges** — it opens a draft.

> Prefer native tool-calls over shelling out? Run the same surface as an MCP
> server: [MCP server](/docs/mcp-server) (`am-cloud mcp`, stdio).

## Full reference

- [CLI](/docs/cli) · [MCP server](/docs/mcp-server) · [API](/docs/api) · [Verify readiness](/docs/verify-readiness)
- [Explore mode](/docs/explore-mode) · [My run made no changes](/docs/no-changes)
- Machine‑readable index for scrapers: [`/llms.txt`](/llms.txt)