Autonomous Loop

/xavier loop is an autonomous iteration engine for executing large tasks. It reads a task file, identifies phases, spawns agents to execute each one, and verifies progress before moving on — all orchestrated through the Shark pattern.

How it works

The loop acts as the shark (orchestrator). Each task phase runs as a remora (background agent). The cycle is:

1. Read the task file — identify the current phase
2. Backpressure pre-flight — run all verification commands. They must pass before the loop starts
3. Spawn a remora — execute the current phase
4. Verify — run backpressure commands after the phase completes
5. Progress or retry — if verification passes, move to the next phase. If it fails, re-spawn with error context
6. Terminate — when all phases are complete, max iterations are reached, or the completion promise is satisfied

Two modes

Task-file mode

/xavier loop

Xavier lists task files from ~/.xavier/tasks/. You pick one. The loop reads the phases, acceptance criteria, and backpressure commands directly from the file.

State is tracked in ~/.xavier/loop-state/<task-name>.md — current phase, iteration count, and pass/fail history.

Freeform mode

/xavier loop "Refactor all API handlers to use the new error boundary pattern"

For tasks that don't need a full PRD → tasks pipeline. The loop accepts a plain description and iterates on it.

State is lighter: ~/.xavier/loop-state/<slug>.md with iteration count, progress log, and learnings. No phases or backpressure sections.

Backpressure

Backpressure commands are the loop's guardrails. They're defined in your task file and run automatically after each phase to verify progress.

# Example backpressure commands
pnpm typecheck
pnpm test
pnpm lint

Strict pre-flight: all backpressure commands must pass before the loop starts. If you have pre-existing test failures, fix them first or update the commands. This prevents the loop from chasing its tail on issues that existed before it started.

Example: executing the webhook feature

Continuing from the PRDs and Tasks example:

/xavier loop

Xavier shows your task files. You select webhook-support.

── Loop: webhook-support ──
4 phases, backpressure: pnpm typecheck && pnpm test

Pre-flight... ✓ all checks pass

Phase 1/4: Webhook registration endpoint + database schema
  → Spawning remora...
  → Phase complete. Running backpressure...
  → ✓ typecheck pass, ✓ tests pass

Phase 2/4: Event subscription wiring + delivery queue
  → Spawning remora...
  → Phase complete. Running backpressure...
  → ✗ tests fail (2 failing)
  → Re-spawning with error context...
  → Phase complete. Running backpressure...
  → ✓ typecheck pass, ✓ tests pass

Phase 3/4: Retry logic + failure handling
  → Spawning remora...
  ...

Each phase builds on the last. The loop doesn't move forward until verification passes, and it doesn't run forever — max iteration limits prevent infinite retries.

Guardrails

• Max iterations — configurable cap prevents runaway execution
• Backpressure verification — automated checks after every phase
• Strict pre-flight — existing failures must be resolved before starting
• Completion promises — explicit conditions that signal the task is done