Concepts

Files, not a hosted loop.

Every object below is something you can open in an editor. The CLI, MCP server, and web console are different windows on the same directory.

Queue

An append-only JSONL state machine: queued → claimed → submitted → waiting/stopped → completed | failed | cancelled, plus needs_recovery. Illegal moves are refused. Duplicate job ids and reused idempotency keys are refused. After a crash the ledger replays; arthur queue recover parks or requeues the abandoned job and releases the dead manager's lease.

Artifact

Advisor and executor text is saved before anything acts on it. Control blocks parse from the final fenced block only. Values must match the hop enums. A plan that says IMPLEMENTATION_STARTED: true is invalid. Failures are quarantined and open a human decision.

Gate

arthur gate implementation --project-id X answers GO or NO-GO from saved artifacts alone: newest plan review is a valid APPROVE_PLAN, nothing re-opened planning, no open decision. A handoff captured while the gate is NO-GO is quarantined. Prompts still ask executors to behave; the gate is what the loop checks.

Human decision

A blocking question lives in human-decisions/open.md. While it is OPEN, that project cannot be claimed, submitted, polled, completed, or failed. Other projects keep moving. Answer it from the CLI, MCP, or the console.

Tick

arthur tick reads durable state and answers WAIT, POLL_DUE, BLOCKED_BY_BROWSER_LOCK, BLOCKED_BY_QUOTA, or HUMAN_INPUT_REQUIRED. It costs no tokens. Run it from cron if you want a heartbeat.

Roles

Planner, implementer, reviewer, and optional QA. Each hop is invoked as the assigned agent. Setup: Roles and run.

The hop sequence

  1. Planner next-plan request
  2. Implementer plan (plan only)
  3. Reviewer plan review
  4. Implementation gate GO
  5. Implementer implementation handoff
  6. QA review, if that role is assigned
  7. Reviewer sprint review, until release-ready

Full operating manual: workflow-runbook.md in the repository.