Why autopilot vs interactive
| Use | Mode |
|---|---|
| Specific feature you're building | xc i — you stay in the loop |
| Multi-day grind on roadmap items | xc autopilot — set goal, walk away |
| Mixed — autonomous between checkins | both: autopilot continuous; jump in with `xc i` for the hard stuff |
The 9-phase lifecycle
The autopilot runs a finite-state machine over each agent. Phases progress sequentially; some phases spawn coding-agent sessions (async), others run synchronously inside the autopilot tick.
analyze → catalog → plan → selecting → branching → implementing → verifying → merging
↓
idle-between-tasks
↓
(loop back to selecting)| Phase | What it does |
|---|---|
analyze | Calibrate, OWASP, typecheck, build — capture quality-gate baseline. |
catalog | Scan features in the repo; merge with existing catalog. |
plan | LLM-driven planner — produce a prioritized roadmap of items. |
selecting | Pick the next pending item by priority and complexity. |
branching | Create the feature branch; pre-flight setup. |
implementing | Spawn a coding-agent session with the implementation prompt. |
verifying | Run scoped verification (build, typecheck, tests, scope gate). |
merging | Push branch, open PR, fire merge-gate, optionally automerge. |
Getting started
# 1. Attach an agent to a workspace
xc add ~/code/your-project --goal "harden flow adherence and document everything"
# 2. Bind autopilot to that agent
xc autopilot assign ~/code/your-project
# 3. Start the supervisor (heartbeat-driven loop)
xc start
# Supervisor checks every 5 minutes. Stuck agents get killed and restarted.
# 4. Watch
xc autopilot status
xc autopilot roadmap
xc flow events --type flow.transitionStuck-agent recovery
The supervisor watches for liveness. If a session hasn't produced progress in stuckThreshold seconds (default 3600), the supervisor kills the session and restarts it with a fresh approach prompt. Sessions that fail maxSessionsPerItem times mark the item failed and move on.
The merge gate
Before merging, autopilot runs every gate producer in .xcoder/merge-policy.yaml:
- scope — diff stays inside the item's stated scope.
- zone — kernel-zone changes always escalate to human.
- owasp — security regressions block.
- calibrate-delta — quality-gate must not regress.
- preview-smoke — UI screenshots, smoke tests on the preview deployment.
- visual-diff — pixel diff against baseline.
- vision-pass — LLM-driven UX review.
The gate produces a Verdict — permitted, needs-human, or blocked — and emits it as a gate.* event. Permitted PRs auto-merge in the next automerge sweep.
FlowEngine integration (I-11)
The autopilot phase machine emits flow.transition events at every phase change. v1 is observability — you can audit every transition in .xcoder/flow-events.jsonl. Hard-gating (the engine refuses to advance the autopilot when an acceptance check fails) is v2.
Supervisor protocol (post-v1)
The full design (Part 2 of specs/flow-adherence.md) adds:
- Non-blocking questions — when xCoder needs human input, it doesn't block. It marks the task waiting-for-reply, pops the next priority, and keeps working. Reply unblocks asynchronously.
- Pluggable notifiers — Twilio, x402.Dial.WTF, Resend, Slack, generic email, digest, silent. Per-event channel routing, throttling, quiet hours, allowlisting.
- Performance profiling — auto-benchmark every 50 tasks; route new tasks based on success-rate by complexity tier.
- Resource caps — hierarchical session / daily / monthly budgets. Halt-on-exceed.
- Scope-down behavior — at the edge of capability, decompose tasks into smaller acceptance criteria.