Skip to content

README.md

Latest commit

 

History

History
95 lines (70 loc) · 4.63 KB

README.md

File metadata and controls

95 lines (70 loc) · 4.63 KB
Raw

autonomous-fleet-adapter-orca

autonomous-fleet-adapter-orca, autonomous-fleet skill

Reference runtime adapter for autonomous-fleet-core on Orca. Maps engine primitives to Orca orchestration CLI commands and routes fleet missions vs platform handoffs. Load alongside autonomous-fleet-core and one mission when running on Orca.

🟦 Tier 2 · Adapter — Orca is the primary distribution path for autonomous-fleet: structural build-blind review, native multi-terminal orchestration, and the production topology this framework was distilled from.

On this page: When to use it · Routing · What it produces · What it expects · Common failure modes · Quick install · Learn more

When to use it

  • You are running a fleet mission on Orca (doc-sync, adversarial-review-and-fix, fleet-program, …) and want each worker in its own worktree and terminal.
  • You need structural build-blind review: @codex or @grok builds in one terminal, a fresh @claude reviews in another — isolation is mechanical, not instructed.
  • You want parallel, independent PRs: independent work in a fresh worktree off BASE, dependent work in the active worktree on a fresh terminal.
  • You are supervising workers — waiting for worker_done, coordinating a DAG, syncing task state.

Not this adapter: one-shot ownership handoffs ("give this to Codex and stop watching") → use orca-cli instead. See Routing and SKILL.md.

Routing

Intent Path
Fleet mission or campaign This adapter — task-create + dispatch --inject + check --wait
Full handoff without supervision orca-cli — no orchestration lifecycle
Terminal / worktree / embedded browser ops orca-cli
Desktop UI outside Orca Computer Use

Full routing table: references/orca-platform.md.

What it produces

  • Orca worktrees and terminals per worker, with orchestration tasks via task-create and dispatch --inject.
  • Interactive builder CLIs (codex, grok, claude in terminals) — not codex exec for supervised Orca runs.
  • A file ledger kept aligned with Orca task state via task-update on every lifecycle change.
  • One merge-commit PR per unit (gh pr merge --merge --delete-branch, never --squash).
  • Runtime-goal bookkeeping in the ledger (check --wait loop; Orca has no /goal API).

What it expects from your repo

  • Orca orchestration CLI, git, and gh installed. Experimental orchestration enabled; orca status --json must report a running runtime.
  • gh auth status for PR workflows (else local merge-commits into BASE).
  • A BASE branch (created off default branch at HEAD if absent).
  • gitleaks for core precondition checks.
  • On Orca, companion skills orchestration and orca-cli for non-fleet platform cases.

Common failure modes

  • Dispatching before tui-idle: inject on a non-idle terminal is lost. Wait first.
  • Worker looks done but sent no worker_done: use dispatch-show, re-send via terminal send — never kill a live worker.
  • Treating Orca's 3-consecutive-failure circuit break as a stop: it is a reassign signal.
  • Using task-create / dispatch --inject for a full handoff the user did not ask to supervise.
  • Addressing lifecycle messages to broadcast handles (@all, @idle): target the concrete coordinator handle.

Headless campaign mode (run-campaign.sh) accepts only grok, claude, and codex CLIs. Interactive Orca orchestration is the supported path for Orca missions.

Quick install

npx skills add https://github.com/ravidsrk/autonomous-fleet \
  --skill autonomous-fleet-adapter-orca -y

Or use the repo starter set: ./scripts/install-skills.sh (defaults to Orca adapter).

Then load autonomous-fleet-core + one mission and run on Orca.

Learn more

← Guide Index