Workflows for developers: give a coding agent a goal, get a result with evidence.
Documentation · Getting started · Concepts · Mission guides · Contributing · Security · Install · Examples · Local development · Ops

Choose your starting point:

Install — one command (needs git + Python ≥ 3.11; to run missions add Orca ≥ v1.4.215, gh, Claude Code — pinned list):

git clone https://github.com/ravidsrk/orca-fleet.git && cd orca-fleet && sh scripts/install.sh

The installer validates the catalog, links every mission into ~/.claude/skills, and tells you how to wire the completion gate. Verified from a clean container (transcript); every install-path PR re-runs it in CI.

orca-fleet is a catalog of missions for the Orca runtime. It is an independent, community-maintained project, not affiliated with or endorsed by Stably, the maker of Orca (third-party notices). Use it to build a feature, address known defects, improve tests, or review a PR. A mission is one workflow: a coordinator breaks the goal into tasks, dispatches workers, checks their evidence and reports the outcome or the remaining blockers. Provide a bounded goal in your coding-agent session in the repository you want worked on; the recipes show concrete inputs. Most missions are still declared doctrine-only; inspect the Proof column and retained runs before choosing one. The glossary explains the terms used below.

 YOU SAY                          THE FLEET RUNS                        YOU GET
┌──────────────────────┐      ┌─────────────────────────────┐      ┌──────────────────────────────┐
│ "ship this"          │ ───▶ │ freeze → build → review     │ ───▶ │ PROMOTION_READY + evidence   │
│ "close every issue"  │ ───▶ │ triage → fix → re-enumerate │ ───▶ │ backlog at zero, SHA-linked  │
│ "harden this"        │ ───▶ │ audit → exploit → re-attack │ ───▶ │ CLEAN re-audit, or named gaps│
│ "why is this flaky"  │ ───▶ │ reproduce → falsify → prove │ ───▶ │ demonstrated root cause      │
└──────────────────────┘      └─────────────────────────────┘      └──────────────────────────────┘

What makes it different is not the ingredients. Other packs ship sharper TDD loops, stricter reviews, evidence ledgers, even completion gates — all graded inside the run that produced the work. Here the claim is checked by mechanism, outside the run that made it: the scope is frozen against a coordinator-held digest the worker cannot quietly shrink, the commits are real on the intended base, the review is looked up on GitHub and bound to the head tree, and every fix carries a negative control the verifier can execute — revert the change in a fresh worktree and require the proof to go red. What that does and does not prove is spelled out in the evidence protocol; how it compares with other packs is in the positioning snapshot.

No mission is named for a vendor or a technique. The upstream packs (mattpocock/skills, garrytan/gstack, addyosmani/agent-skills) are sources of recipes that missions compose — one pack per worker, never two in the same context (why).

What a mission does on your machine, stated before the first one:

• Workers run your coding agent with its permission prompts off (--dangerously-skip-permissions and each agent's equivalent), because a worker that blocks on a prompt kills the run. Orca's worktree is an isolated checkout, not a security sandbox.
• Each worker gets a git worktree under your checkout and opens pull requests on your repository against an integration branch the fleet creates. The fleet never merges to your default branch; that promotion is always your click.
• The completion gate is advisory inside a worker's own session, and deny-hook.sh is not registered by default; the sound verification surface is off-worker (CI, or a process the worker cannot influence).
• For a first run use a repository you can afford to lose, a VM, or the offload-it recipe. The full boundary is in docs/verify-gate.md and runtime/sandbox-policy.md; what a run asks you to decide, step by step, is in Getting started.

• Before you run a mission
• Requirements
• Quick start
• The mission catalog
• Proof status
• Which mission do I want?
• How a fleet works
• The evidence protocol
• Three layers, strictly separated
• Install
• Repository layout
• Validate and test
• FAQ
• Further reading
• Credits
• License

Every mission has a hard dependency on companions not published in this repo (the enforced-vs-observed pin table is in distribution):

1. The Orca app, running, with the orchestration experimental feature enabled — at or above the catalog pin, currently v1.4.215 (runtime/pins.json; the installer warns below it, and scripts/validate.py fails when this number and the pin disagree). Tested against v1.4.209 through v1.4.215; upstream ships almost daily, and a weekly probe files an issue when the catalog falls behind (runtime/orca-pin.md).
2. The orca CLI (orca-ide on Linux outside Orca terminals).
3. Orca's two public skills, orchestration and orca-cli, installed for the agent host — they provide the worktrees, terminals, task DAG, ask/reply and worker_done primitives. orca-fleet is the outcome layer; those two are the substrate, and without them no mission can dispatch.
4. git and gh, authenticated — or a tracker reachable via orca linear.
5. Python 3.11 or newer for the catalog gates and the runtime scripts; stdlib only. CI runs the suite on 3.11, 3.12 and 3.13; the installer refuses to run below 3.11.

Each mission declares any extra tooling in its SKILL.md frontmatter; the per-mission list lives in Getting started.

# 1. Clone
git clone https://github.com/ravidsrk/orca-fleet.git
cd orca-fleet

# 2. Link the review and build missions into Claude Code — link, don't copy. A mission names its
#    playbooks and runtime policies by bare name and finds them in playbooks/ and
#    runtime/ two levels above its own directory; a symlink keeps that tree intact.
mkdir -p ~/.claude/skills
ln -s "$(pwd)/skills/review-it" ~/.claude/skills/review-it
ln -s "$(pwd)/skills/ship-it" ~/.claude/skills/ship-it

# 3. A symlink install loads NO plugin, so nothing fires the completion gate. Wire it:
sh hooks/print-settings-snippet.sh   # merge the output into ~/.claude/settings.json

# 4. Open a Claude Code session in the repository you want worked on (Orca app
#    running, both Orca skills installed) and type:
#    "review this PR: <PR URL>; use <issue or spec path> as the spec"
#    For new work: "ship this: <your goal>; stop at the promotion PR"

Step 3 is not optional if you want the gate. hooks/hooks.json wires the verifier through ${CLAUDE_PLUGIN_ROOT}, which Claude Code sets only for plugin installs. A ln -s into ~/.claude/skills/ loads no plugin, so without the snippet above the missions run with no completion gate at all (#262). A plugin install declares these hooks itself; confirm activation in the plugin manager.

Getting started walks a first run end to end: what the coordinator does, what the workers do, where the evidence lands, and what the two human gates look like from your side of the terminal. Install covers every install path and which ones carry the gate.

The shell commands above run in the catalog clone. The mission prompt runs in the target project. Keep the clone available: symlinks and the settings snippet point back to it. For install checks, updates and removal, use the install guide.

Every mission is one outcome with its own state machine, its own convergence proof, and an evidence-based definition of done. Click through for the full guide to each.

The Proof column is each mission's metadata.proof tier, bound to its SKILL.md by a contract test; what a tier means and how one is earned is under Proof status.

Every mission is a coordinator plus parallel isolated workers, which is level L4 on Addy Osmani's autonomy ladder; a scheduled unattended run is the L5 shape. The derivation is in docs/concepts.md. Missions can also run as a gated sequential chain ("harden-it, then prove-it, then ship-it") where each link proceeds only on the previous mission's verified terminal state — see runtime/mission-chaining.md.

Diagram note (2026-09-16): the callout baked into the image predates the first promotion — it still reads the old state. Regen tracked in #434.

Every mission's metadata: block carries a validator-enforced proof: field: doctrine-only, self-run, or external-run. A tier cannot be claimed without artifacts that hash true at a named commit: a run report with a RUN: header, an evidence manifest inside the run's own docs/runs/ directory, and an integrity inventory that re-hashes at the commit the header names.

Today clean-sweep, harden-it and prove-it read self-run; every other mission reads doctrine-only; no mission reads external-run yet.

The run archive records every run that really happened and says, per run, whether and why it binds. Be precise about what the gate buys: it hashes, it does not re-run the verifier, and the 2026-09-11 review showed that a fabricated run can pass it; closing that is #281 and #286. Why the number went down as the mechanism got stronger is explained in docs/concepts.md.

flowchart TD
    S([What do you have?]) --> A{A goal to build?}
    A -->|too foggy to spec| MAP[🗺️ map-it<br/>chart it into a frozen map]
    A -->|spec or clear intent| SHIP[🚢 ship-it<br/>build → review → release]
    MAP -->|frozen map| SHIP
    S --> B{A set of known problems?}
    B -->|issues / audit findings / lying docs| SWEEP[🧹 clean-sweep]
    B -->|upstream issues, fork-only access| OSS[🤝 oss-contribute]
    B -->|security posture| HARD[🛡️ harden-it]
    B -->|performance budget| SPEED[⚡ speed-it]
    B -->|outdated dependencies| MOD[📦 modernize-it]
    B -->|untested critical paths| PROVE[🧪 prove-it]
    B -->|flaky suite| FLAKE[🎯 deflake-it]
    B -->|no enforced quality bar| FLOOR[🧱 floor-it<br/>written bar, tools that fire]
    B -->|architecture erosion / god files| RESHAPE[🧬 reshape-it<br/>deepen, behaviour unchanged]
    B -->|compliance evidence| ATTEST[📋 attest-it]
    B -->|accessibility| ACCESS[♿ access-it]
    B -->|breaks on a real device| FIELD[📱 field-test-it<br/>on-device proof]
    B -->|a schema or data shape to move| MIG[🗄️ migrate-it<br/>expand → contract, phase by phase]
    B -->|blind in production| ONCALL[📟 oncall-it<br/>telemetry, alerts, runbooks]
    B -->|an inbound PR queue| ABSORB[📥 absorb-it<br/>land with credit or refute]
    B -->|an undocumented public surface| DOC[📚 document-it<br/>coverage map, claims anchored]
    B -->|no cloud workspace recipe| OFFLOAD[☁️ offload-it<br/>recipe, proven by provisioning]
    S --> C{A question, not a change?}
    C -->|is this diff ready to merge| REV[🔍 review-it<br/>read-only verdict]
    C -->|why is this happening| RC[🔬 root-cause<br/>diagnosis only]
    S --> D{our own tooling drifted?}
    D -->|policy lags the Orca binary| PIN[📌 pin-it<br/>re-witness + re-pin doctrine]

Missions also hand work to one another, each handoff a separately authorized run:

Two workflows are the same mission only if they share all six identity points: unit of work, per-unit state machine, convergence proof, ordering and isolation, parking semantics, and the oracle the proof binds to. That test — and why closing audit findings, tracker issues and lying docs are one mission while security, performance, dependencies, test debt and flakes are each their own — is in ARCHITECTURE.md.

Every mission runs the same shape: a coordinator that never writes code, and disposable workers that never coordinate.

flowchart LR
    subgraph you [You]
        H[Human gates:<br/>freeze · promotion · one-way doors]
    end
    subgraph coord [Coordinator — one terminal]
        L[Ledger file]
        V[Independent verifier]
    end
    subgraph workers [Workers — fresh worktree + terminal each]
        W1[builder]
        W2[reviewer<br/>build-blind]
        W3[conductor<br/>owns all merges]
    end
    coord -->|task spec + playbook| W1
    W1 -->|evidence manifest| V
    coord -->|artifact, not the claim| W2
    W2 -->|reviewed_sha| W3
    W3 -->|merge, ancestry-verified| V
    V -->|verified state| L
    H <-->|gates only| coord

The specifics that make this reliable are documented runtime policies, each preserved because it paid for itself the hard way:

• Wrong-base detection. Every per-unit PR merges into an integration BASE that must not be the default branch, compared on canonical refs so origin/main can't alias past the guard — runtime/dispatch-lifecycle.md.
• Reviewed-SHA freshness. A review is valid for the exact SHA it reviewed. A rebase, a bot autofix, or a late push voids it — runtime/reviewed-sha-freshness.md.
• One merge train. A single conductor drains merge_ready signals in arrival order; hot files form chains, never fan-outs — runtime/merge-serialization.md.
• Attention budget. Scale concurrent builders to verification capacity (default ≤3), not the spawn UI — runtime/attention-budget.md.
• Liveness and resume. Stalled workers are respawned in fresh terminals with bounded attempts and reflection-before-retry; a dead coordinator resumes from the ledger and re-verifies every "completed" unit against git before trusting it — runtime/liveness-resume.md.
• Gates below the model. Every decision is classified mechanical / taste / one-way; one-way doors are always human, never defaulted on timeout. Units default lit (a reviewer reads the change); dark-eligible is opt-in and narrow — runtime/gate-classification.md.
• Least-privilege workers. ro for report-only, rw for fix work, danger only inside a disposable sandbox with an explicit grant — runtime/sandbox-policy.md.

The human-readable tour of all of this lives in docs/concepts.md.

A trace proves an action was attempted, not that the resulting state is correct — an agent can run the right-looking commands against the wrong SHA. So completion is never graded on narration. Every unit emits a SHA-bound evidence manifest, and a fresh session re-derives its claims from authoritative state:

sequenceDiagram
    participant W as Worker
    participant C as Coordinator
    participant V as Verifier (fresh session)
    participant G as Authoritative state (git / tests / deploy)
    W->>C: worker_done + evidence manifest
    C->>V: manifest (the claim)
    V->>G: re-derive the criterion set from the frozen source
    V->>G: merge-base --is-ancestor head_sha origin/BASE
    V->>G: clean-env test run at head_sha (coordinator-run)
    V->>G: revert or mutate — does the proof go RED?
    V->>G: reviewed_sha == head_sha?
    V-->>C: verified — advance (or SUSPECT — re-dispatch)

The difference that matters is checkable. On the same gamed manifest a self-scoring gate goes GREEN and the verifier goes RED, reproducibly (demo/negative-control/):

verify.py checks scope first — the criterion set re-derived from the frozen contract, so a worker cannot shrink its own denominator — then that head_sha is a real ancestor of the integration BASE, then the review on GitHub bound to the head, then the negative control: read by default, executed in a throwaway worktree when the coordinator passes --execute-nc and names the command with --nc-command. Two checks stay doctrine the coordinator performs rather than mechanism the verifier performs: the clean-environment suite run at head_sha, and the ≥10% re-execution sample of controls. The manifest schema and the full checks table are in docs/concepts.md and runtime/evidence-manifest.md; the hook that turns the verifier into a completion gate is in docs/verify-gate.md. Verify, never trust.

Missions are discoverable. Playbooks are callable. Runtime mechanisms are invisible unless directly administered.

Only skills/ holds a SKILL.md, and scripts/validate.py fails the build if that breaks: publishing a playbook or a runtime policy as an auto-triggering skill would recreate the routing collisions this repo exists to remove. The design rationale, including what counts as a new mission versus a new playbook, is in ARCHITECTURE.md.

Two paths work today and a third does not yet; each is walked step by step in docs/install.md.

• Symlink the catalog (recommended while evaluating): the one command at the top — sh scripts/install.sh validates the catalog and links every mission, or hand-roll one ln -s per mission as in the Quick start above — then wire the completion gate with sh hooks/print-settings-snippet.sh.
• Claude Code plugin (whole catalog): /plugin marketplace add ravidsrk/orca-fleet, then /plugin install orca-fleet@orca-fleet. The plugin declares the gate hooks; confirm activation as described in Install.
• skills CLI: not from this repository, today. A copy installer severs the tree a mission resolves its playbooks against. It needs a published dist/ bundle; publication and install-witness status are covered in Install. python3 scripts/bundle.py --check validates a temporary bundle without publishing it.

skills/          missions — the discoverable catalog (one SKILL.md each)
playbooks/       callable phase protocols missions compose by name
runtime/         policies + runtime/scripts/ (verify, verify-gate, preflight, spawn_worker, pm, …)
hooks/           hooks.json — the native completion-gate wiring
scripts/         validate.py, gen-badges.py, eval.py, bundle.py
tests/           architecture contracts + validator negative-path fixtures (stdlib unittest)
evals/           routing eval fixtures
bench/           vf-bench — verifier-soundness benchmark
demo/            negative-control head-to-head
docs/            getting started, concepts, install, mission guides, run archive, research
assets/          banners, diagrams (dark + light), generated badges, and the image generator
.claude-plugin/  plugin.json — the Claude Code plugin manifest

These are local contributor commands from the catalog root. They use Python's standard library and do not need a running Orca app. The development guide covers focused tests, CI shards, generated content and the difference between local checks and CI.

python3 scripts/validate.py                # agentskills.io spec + three-layer separation
                                           #   + composition/cross-doc reference checks
                                           #   + eval JSON schema checks
python3 scripts/eval.py run --suite all    # mission-routing baseline + per-skill eval count
python3 -m unittest discover -s tests -v   # architecture contract tests + validator
                                           #   negative-path fixtures + eval contracts

The validator is deliberately paranoid: every composition reference must resolve, every mission must expose at least one machine-checkable composition, dangling or typo'd <name>.md references fail the build anywhere in the catalog, every mission must declare an honest metadata.proof: status (with a run report that re-hashes at the commit it names before it can claim one) and all six identity points, and instruction-budget line caps stop doctrine creep at CI. The contract tests keep the mission catalog, the outcome-naming rule, the orphan-protocol guarantee, and script interpolation hygiene locked.

• Documentation index — tutorials, procedures, explanations and reference by task.
• Prompt recipes — requests with concrete inputs and stop conditions.
• Troubleshooting — installation, gates, stopped runs and PR blockers.
• Local development — work on this repo and run its checks.
• ARCHITECTURE.md — the three-layer design, the mission-identity test, and the proof-over-doctrine guards.
• docs/install.md — every install path and which ones carry the completion gate.
• docs/verify-gate.md — the verifier as a native completion gate, its env surface, and its trust boundary.
• docs/runtime-scripts.md — reference for the runtime scripts and operator config: usage, flags, keys, and exits.
• Anatomy of a run — one real run, hour by hour, incidents included.
• docs/platform-ride.md — what to ride from Claude Code, the Agent SDK and MCP, and the absorption-risk register.
• docs/distribution.md — install paths, indexers, and what the proof records establish.
• docs/compliance-provenance.md — the manifest's provenance block against the EU AI Act's logging obligations.
• docs/research/ — dated research snapshots and the ledger of rejected mission candidates.
• REVIEW.md — the 2026-09-11 review; the earlier one is docs/reviews/2026-09-10-review.md, the later one docs/reviews/2026-09-14-holistic-review.md (filed as #349–#386).
• docs/reviews/2026-09-28-release-readiness-review.md — the 2026-09-28 release-readiness review: every frozen gate re-run, the 1.0 checklist walked against live state, findings ranked P0–P2, and the tiered path to 0.7.0, a public beta, and 1.0.
• docs/announcements/public-beta-draft.md — the public-beta announcement as a draft, with the witnessed acts it waits on listed above the text.
• AGENTS.md — the agent-facing summary of this page; docs/about.md — the canonical repository description; docs/ops.md — maintainer ops.

Missions compose recipes from three excellent upstream packs — one router per worker, credit where it is due:

And the substrate everything rides: the Orca runtime. Upstream notices are collected in THIRD_PARTY_NOTICES.md.

MIT — see LICENSE.