automaintainer/ docs
Dashboard →

How it works — the verified loop

Automaintainer's core belief is one line:

"I wrote the code" is not done. Done = checked, fixed, and re‑checked clean.

A run may not call itself successful, and a PR may not be opened as merge‑ready, until the work has passed an objective Verification Gate. Everything in the product serves that line.

The loop

trigger → prepare worktree → agents implement → VERIFY → fix → RE‑VERIFY → INTENT CHECK → PR → (review) → (merge)
                                                  ^___________________|
                                              loop until green or capped
  1. Trigger — manual, scheduled, or proposed by explore mode.
  2. Prepare — an isolated git worktree is created on a worker from a fresh checkout of your default branch.
  3. Implement — the team of agents reads the focus (plus any repo memory), makes changes, and commits. Agents coordinate over a peer message bus — no central orchestrator.
  4. Verify — AM runs your verify_cmd from the repo root. Exit 0 = pass.
  5. Fix loop — if the gate fails, a fixer agent attempts a repair and AM re‑verifies. Bounded by an iteration cap and no‑progress / identical‑error guards so it never loops forever.
  6. Intent check — verify proves the change is correct; it doesn't prove it's what was asked. A cheap objective‑adherence review compares the diff against the run's focus/objective. If the change looks off‑objective it flags the PR with a comment and holds auto‑merge — a human still owns the merge. It's advisory: it never discards work.
  7. Publish — AM rebases on the latest base, pushes the branch, and opens a PR. If the gate is still red, the PR opens as a draft marked needs work — so you see the work without it pretending to be ready.
  8. Review / merge — per the trust ladder: self‑review (Free), AM reviews and you merge (Pro), or AM auto‑merges after a green gate + review (Max).

Why a fresh worktree every run

Each run starts from a clean checkout so results are reproducible and one run can never corrupt another. It also means your verify_cmd must run from the repo root with no absolute paths — see Verification Gate.

What AM does NOT do

  • It does not merge unverified work (outside Free self‑review, a red gate blocks merge‑ready PRs).
  • It does not store your provider keys — see BYOK.
  • It does not act outside the bounded objective you (or a vetted playbook) set.