Orka

High-throughput engineering orchestration with bounded autonomy.

A reusable harness for running a small team of coding agents against real tickets or a dependency-linked Jira sprint, with independent review and security gates and a mechanical merge-guard, so that parallel agent work does not degrade what lands on the configured target branch.

It is packaged as a Claude Code plugin and as a Codex plugin source tree. One orchestrator session dispatches work; each ticket is implemented by one agent role in an isolated git worktree, then reviewed by a separate code-review role and a separate security-review role that never see the implementer's reasoning, and only merged when every gate is green. The sanctioned merge script validates the marker, plugin version, and exact PR head/base identity itself on both Claude Code and Codex. A trusted PreToolUse hook can additionally block raw merge commands, while branch protection remains the out-of-band layer.

The harness is config-driven: every repo-specific fact (branch model, state graph, gate commands, CI categories, approvals, adapter seams) lives in one small config file, and the actual engineering rules live in the target repo's own CLAUDE.md / AGENTS.md. The plugin itself carries no project knowledge, so the same harness ports across codebases.

For a new installation, use the Claude Code or Codex plugin instructions below. The supported plugin snapshot is the version recorded in both Claude Code and Codex manifests on main. The Claude marketplace entry points at this repository; update the marketplace and plugin to pick up a newer snapshot.

GitHub Releases are tagged, reproducible source snapshots with release notes. GitHub's Latest Release means the newest published tag, which can trail the plugin version on main until a matching release is published. Check the manifest version when installing through the marketplace, and select a tag if you need a fixed source revision. The release process explains how these versions are published. Orka 2.0 is still in development; the durable runtime roadmap distinguishes shipped slices from the remaining cutover work.

The one-year product vision describes the founder-first future state: a durable supervisor, stable CLI and browser surfaces, provider-independent workers, and capacity-aware local or ephemeral execution without making adoption or a hosted service the goal.

Orka 1.0 is designed to keep a long-running sprint moving without choosing between brittle stop-and-go automation and an unbounded agent that can spend or loop indefinitely:

• Large-ticket decomposition. An opt-in scoping pass scores ticket complexity before implementation. Oversized technical work can be split into two to ten independently testable Jira children with explicit dependencies, while product and security decisions still stop for an operator. Existing Jira subtasks become sibling slices because Jira does not support nesting them.
• Finish-first throughput. Repair and recovery work takes precedence over fresh tickets, and an unfinished-PR ceiling prevents lane concurrency from turning into a growing review and CI backlog.
• Verified PR recovery. Repositories may opt into automatic recovery of a clean, quiescent worktree whose open PR, branch, head, and tree all match authenticated GitHub and checkpoint evidence. Existing PRs drain before new implementation work without resetting review or attempt history.
• Reusable product decisions. Approved, repository-owned decisions can be keyed once and supplied to later scoping passes. Orka re-scopes affected tickets under that policy instead of asking the same operator question for every related slice.
• Complete decomposition contracts. Repositories may require named product, migration, security, compatibility, or ownership contracts on every generated slice. Jira dependencies are created, re-read, and verified before the controller makes a child launchable.
• Progress-aware worker lifetimes. Output and verified milestones reset an inactivity timer; a separate absolute lifetime still stops a runaway worker. Productive continuations do not consume the crash/relaunch allowance.
• Progress-aware spend control. Warning thresholds are informational; spending without a durable milestone triggers recovery or decomposition instead of silently buying more retries. Hard ticket, run, reviewer, and sprint ceilings remain mechanical.
• Autonomous intervention queues. Recoverable work, bounded repairs, and approved decomposition are first-class controller queues. An independent blocked ticket does not freeze the rest of the sprint.
• Durable, ticket-scoped continuations. Root-issued, expiring capabilities can raise one ticket's absolute budget or relaunch ceiling and recover one preserved attempt without weakening repository-wide gates.
• Authoritative Jira synchronization. Sprint parents are fetched first and the exact returned keys define the child query, avoiding stale inventory and project-specific query assumptions.
• Provider-safe execution. OpenAI and Anthropic requests use compatible payloads, conservative retry classification, durable usage reservations, and explicit reconciliation when a provider accepts a request but the response is lost.

These controls preserve the central rule: Orka may recover, repair, decompose, and continue within declared policy, but it cannot manufacture authority, bypass a failed gate, or merge unverifiable work.

Spinning up parallel coding agents naively degrades output, in four specific ways:

1. Shared state. Agents working in the same checkout overwrite each other's branches and files.
2. Thin context. Each agent gets a one-line task and re-discovers the repo's rules badly, differently, every time.
3. No independent scrutiny. The agent that wrote the code also "reviews" it, so it confirms its own implementation instead of testing the requirement.
4. No gates. Work merges on vibes rather than on a green pipeline.

This harness addresses all four: isolated worktrees, fat per-ticket briefs, an adversarial test matrix and security-sensitive design gate before code, separate review/security agents run against the diff with fresh context, and a hard all-green gate before anything lands. Claude Code and Codex share the same marker and merge scripts; trusted hooks add local defense in depth when the host supports them.

                          +---------------------+
                          |   ORCHESTRATOR      |  (one Claude Code/Codex session)
                          |   - reads the ticket|
                          |   - dispatches work |
                          |   - owns the queue  |
                          +----------+----------+
                                     | spawns (worktree-isolated agents)
         +---------------+-----------+-----------+---------------+
         v               v           v           v               v
   +-----------+   +-----------+  +-----------+  (N implementers run concurrently,
   |Implementer|   |Implementer|  |Implementer|   each in its own git worktree +
   |  ticket a |   |  ticket b |  |  ticket c |    and configured source branch)
   +-----+-----+   +-----+-----+  +-----+-----+
         | opens PR -> configured target branch
         v
   +---------------------------------------------+
   |            GATE PIPELINE (per PR)            |
   |  1. self-check   typecheck + build + test   |
   |  2. code review  (fresh agent, diff only)   |
   |  3. security     (fresh agent, when warranted)|
   |  4. verify       (e2e / visual-qa, optional)|
   +---------------------+-----------------------+
                         | ALL green?
              +----------+----------+
         yes  v                     v  any red
   +-------------------+   +----------------------+
   | record marker +   |   | loop the findings    |
   | merge to          |   | back to a fresh      |
   | target branch,    |   | implementer, re-gate |
   | verify + clean up |   | (never merge on red) |
   +-------------------+   +----------------------+

• The author never reviews their own work. Review and security agents run with fresh context against the diff only.
• Design before security-sensitive infrastructure. A pre-code gate records trust boundaries, impossible guarantees, failure recovery, rejected fragile alternatives, and the adversarial tests that falsify its invariants.
• Architecture must fit the authorized boundary. The design gate identifies invariants that require a root-owned installation, distinct UID, daemon, container, cloud resource, or operational rollout before code starts; those become separately scoped work instead of late review discoveries.
• Worker trust is explicit and portable. cooperative-worker covers mistakes, crashes, loops, duplicate execution, and accidental misuse. isolated-worker opts into independently owned process and credential isolation. Neither profile relaxes application, tenant, or external-input security.
• Reviews batch the whole sweep. Finding one blocker never ends a review; reviewers finish the diff, checklist, and matrix and report all findings once.
• A failed repair triggers scoped redesign. A stable component-key ledger, persisted by scripts/review-ledger.py, prevents an endless sequence of narrow patches to the same broken design.
• The review loop is bounded and converges. Round 1 sweeps the whole diff with full blocking authority. From round 2 review follows the repair delta and affected boundaries; only open ledger findings, regressions, and security issues may block, so the blocking set shrinks. Findings split into blocking and advisory, and max_design_rounds (default 5) and max_repair_cycles (default 2) end their respective loops at a human rather than a merge. Repairs are recorded against stable finding IDs and re-reviewed on one exact head. See docs/review-loop.md.
• Enforcement is mechanical, not advisory. The sanctioned merge script refuses stale or mismatched evidence even without hooks. A trusted merge-guard hook can also veto raw merge commands. See docs/merge-guard.md.
• Config over fork. Repo-specific facts live in a per-repo config file. The knowledge (conventions, gotchas) lives in the repo's own CLAUDE.md / AGENTS.md, which the gate agents read. Workflow policy is declared in schema-versioned config and enforced by shared scripts, not by Claude/Codex adapter text.
• Worktree isolation by default. Parallel agents never share a checkout. Cleanup defaults to manual; repositories may opt into explicit post-merge and trusted-hook cleanup, which always preserves dirty or locked worktrees.
• The orchestrator relays grep targets, not stale facts. Summarizing agent reports into briefs into docs drops the uncertainty marker at each hop, so the orchestrator never hands down a file:line or an unrun snippet (both drift), labels every relayed claim's provenance, and re-derives any fact before it enters a durable artifact -- anything learned before a merge it performed is stale.

The durable supervisor and disposable workers communicate through a versioned, provider-neutral phase-worker protocol. Codex, Claude, and API adapters share the same capability and envelope fixtures. A host process may remain available, but every phase dispatch starts a fresh model context and carries immutable attempt and supervisor-fence identity.

Per-repo mechanics live in .orchestration/config.yaml (template). There are two compatibility levels:

• schema_version: 1 or no schema version: the legacy ticket pipeline using integration_branch, production_branch, self_check, verification, and ci_checks_*. Existing installations stay here until they opt in.
• schema_version: 2: the configurable workflow engine using branch roles, states, transitions, transition-specific evidence, CI categories, approval classes, candidate/artifact identity, tags, environments, and adapters.

Legacy key blocks:

The legacy scalar/list parser is pure bash. The schema v2 workflow is validated by scripts/orchestration-engine.py, a shared engine used by both Claude and Codex adapters. See docs/workflow-configuration.md. Desktop/API selection and inherited per-role overrides are documented in docs/llm-routing.md. The constrained provider runner, usage ledger, cost and performance reporting (api_agent.py report), and recovery procedure are documented in docs/api-agent.md.

The plugin is a marketplace-installable Claude Code plugin. In an interactive Claude Code session:

/plugin marketplace add Dusttoo/orka
/plugin install orka@builtbydusty

Installing it activates the agents and commands. Hosts that support plugin hooks can additionally expose the merge guard and worktree sweep after trust review. Then, from inside a target repo, scaffold the per-repo wiring:

/orchestration-init

That detects the branch model and CI checks, writes .orchestration/config.yaml for you to review, confirms a CLAUDE.md exists (the harness provides discipline; CLAUDE.md provides the repo's knowledge), and gitignores the runtime marker directory.

Exact /plugin syntax can vary by Claude Code version. Regardless of hook support, /orchestration-init scaffolds the same configuration and the sanctioned scripts enforce merges and cleanup directly.

This repository is also a Codex plugin folder via .codex-plugin/plugin.json. Codex installs plugins from marketplace roots, so local development typically means cloning or symlinking this repo to ~/plugins/orka, ensuring the personal marketplace entry points at ./plugins/orka, then running:

codex plugin add orka@personal

Codex users invoke the same flows in natural language: "orchestrate PROJ-90 end to end", "orchestrate the active sprint", "gate PR 123", "advance the configured release transition", or "bootstrap orchestration in this repo". See docs/codex.md for the full marketplace layout and hook trust notes.

/orchestrate <ticket-id or description>

drives one unit of work through the whole pipeline: scope/adversarial matrix -> design gate for security-sensitive infrastructure -> implement (worktree, TDD) -> code review (fresh agent) -> security review (when the diff warrants) -> optional verification -> record the all-green marker -> merge -> verify it landed. Any gate returning a structured FAIL result loops back with a complete batch of findings; a finding that survives an evidenced repair forces scoped redesign before the final attempt. Nothing merges red.

The slash command is the explicit, deterministic entry point. Natural language works too: asking to "orchestrate PROJ-90" or "run this ticket through the pipeline" triggers the orchestrate-ticket skill, which runs the same flow. Use the slash command when you want to be explicit; use plain English when you don't want to remember the syntax.

Code and security gates use concise structured results: passing checks carry no explanation, while actual findings carry the actionable detail. See reviewer output.

For API execution, place repository-specific provider keys in the gitignored .orchestration/.env beside config.yaml. Cloud/container environment variables with the same names take precedence. See API agent runner.

/gate <pr> runs just the review gates on an existing PR. /release advances a configured release or candidate transition through the shared workflow engine. Schema v1 repositories keep their legacy process until they migrate.

/orchestration-report [window] [group-by] in Claude Code, or "report orchestration usage" in Codex, groups the durable usage ledger into cost and performance insights -- spend and cache hit rate by role, model, ticket, or day, latency percentiles, rate-limit stalls, and run outcomes -- then recommends config changes. It covers API-routed roles only; roles left on execution: desktop never reach the ledger.

/orchestrate-sprint [sprint] in Claude Code, or “orchestrate the configured sprint” in Codex, queries the configured Jira project/sprint and launches the same one-ticket pipeline for every unblocked ticket. A plugin-owned controller normalizes dependencies, orders ready tickets by optional per-ticket priority then key, atomically enforces concurrency_max, and checkpoints running and terminal work under .orchestration/.sprint-state/. Restarts reconcile existing worker references before dispatch, blocked tickets do not stop independent lanes, and recoverable work, repairs, and decomposition remain actionable controller queues. When enabled, the scoping gate can turn an oversized technical ticket into bounded, dependency-linked Jira children before implementation. The final report separates completed, blocked, and user-action items. Repositories provide configuration and project-specific acceptance criteria; they do not vendor the controller or its tests. See docs/sprint-controller.md for the trust boundary, impossible guarantees, restart invariant, and rejected fragile designs. The accepted Orka 2 lifecycle semantics are specified separately in the durable supervisor lifecycle contract; the current implementation provides a host-owned supervisor process with an exclusive repository lease, detached session, deterministic synchronization/planning, durable cooldown wakes, controller-owned worker dispatch, strict terminal-result bindings, ticket-local parking and decision resolution, authenticated external dependency wakeups, authenticated crash takeover, immediate lane refill, and explicit pause, drain, resume, and stop transitions. Desktop and API workers pass through the same versioned lifecycle contract; stale or malformed results cannot become successful work.

The enforcement centerpiece. A raw gh pr merge is blocked unless a recorded all-green marker exists whose SHA matches the PR head and is within a freshness window. Configured guard policy can also block selected target branch roles or direct squash merges. It fails closed: if it cannot precisely parse the command or resolve policy, it blocks anything resembling a merge rather than disabling itself.

Full threat model, hook contract, and the marker lifecycle: docs/merge-guard.md.

The scripts have shell test suites covering the config parser, the merge-guard (every gate path, including the fail-closed fallback), the safe-merge guard rails, the verification handshake, and the worktree lifecycle (the destructive paths, on real git worktrees).

bash tests/run.sh

The reusable merge-guard, merge-on-green, worktree-cleanup, and host-parity suites are plugin conformance tests. Initialization can run them from any target repo with <plugin>/scripts/run-plugin-conformance.sh; it does not install test or script copies. Target repositories supply configuration, their rules and acceptance criteria, and only tests specific to their own behavior.

The harness is designed to move across codebases with only a config change. See docs/porting.md for the checklist and docs/workflow-configuration.md for schema v2 workflow design.

Orka is open source and welcomes focused bug fixes, tests, documentation, provider adapters, observability improvements, and work toward the durable supervisor runtime. Start with CONTRIBUTING.md, search the issue tracker, and comment before starting an issue so work is not duplicated.

Issues labelled status: ready have an accepted implementation boundary. Cross-cutting state-machine, persistence, recovery-authority, spending, and merge-policy changes begin with an architecture proposal. The accepted Orka 2 direction is described in docs/orka-2-durable-runtime.md.

The durable supervisor uses typed, capacity-aware resource claims so a migration, PR, worktree, provider route, visual-QA slot, or heavy process can delay only conflicting work. See Durable resource admission for the claim contract and the optional Jira-label convention.

Orka 2's state-store direction is defined by ADR 0001: one repository-scoped SQLite event store, a supervisor-owned writer, deterministic JSON export, and an explicit fail-closed migration from existing checkpoints. The current JSON runtime remains authoritative until the tracked cutover slices are complete.

Orka 1.8.20 adds the first implementation slice: an explicitly initialized, private repository identity beneath the absolute Git common directory and a canonical policy binding to an exact Git ref and blob. This works for normal, linked-worktree, and bare-backed layouts without allowing sibling bare repositories to share an enforcement domain. See Repository identity and canonical policy. The existing JSON controller state is intentionally not relocated until the separate import and cutover slices are complete.

Orka 1.8.21 adds the transactional store core behind that boundary. A single supervisor-owned writer now provides atomic job reservation, launch, completion, resource-claim release, retry timers, and idempotent external operation receipts over the versioned SQLite schema. WAL remains opt-in and is enabled only after the caller proves a local filesystem and the loaded SQLite contains the documented reset fix; otherwise the store reports its rollback journal fallback. This API is not yet the production controller authority. See Transactional event-store core.

Orka 1.8.23 adds the offline, content-addressed legacy state importer and deterministic redacted JSON export used to prove a shadow migration before cutover. See Legacy state migration. The existing JSON controller remains authoritative until the separate cutover slice ships.

Orka 1.8.24 adds the next guarded cutover foundation: a repository-bound minimum-version marker, generation-fenced transactional runtime documents, and rollback that is permitted only before the first authoritative database write. It does not silently activate SQLite or run dual writers; explicit activation places the legacy runtime into a maintenance hold until the remaining controller/supervisor integration slices are installed.

Multi-lane supervisors allocate work through durable queue classes rather than globally pausing for the oldest repair. Repair and recovery retain greater weight, one lane is reserved for dependency-unlocking work when eligible, and a persisted cursor prevents continuation or fresh work from starving. A one-lane repository keeps strict finish-first behavior. The selected class and reason are visible in supervisor status; all WIP, dependency, resource, route, budget, and heavy-process fences still apply.

Recovery decisions use the versioned orka.recovery-eligibility/v1 contract. Host observers normalize execution, provider, worktree, revision, and history evidence into a side-effect-free evaluator that returns eligible, waiting, or operator_action with stable reason codes. The durable supervisor automatically requeues an exact stopped attempt only after repeating that evaluation under the controller lock, proving provider settlement, and verifying the recovery mutation preserved attempt, spend, progress, branch, worktree, PR, and review history. Eligibility never grants budget, review, repair, or merge authority.

The same contract now drives preserved-PR recovery. A clean, quiescent worktree whose branch, PR, head, tree, execution receipt, provider settlement, and review-history digests agree is reconciled by the durable supervisor and re-enters the existing continuation pipeline automatically. Dirty or active worktrees, moved heads, unknown owners, and unsettled reservations remain visible with stable refusal codes and are never relaunched speculatively.

Recovery crash behavior is specified by orka.recovery-crash-boundaries/v1. Preserved-PR fence identities are content-derived and idempotent, so replay after a crash cannot supersede the original fence or duplicate a provider reservation. Compact transition traces identify the last committed recovery boundary while atomic checkpoints keep each replay on either the old or new side of a state transition.

Operational stops are classified by orka.breaker-classification/v1. The contract inventories every current budget, run-count, review, timeout, provider-health, capacity, and integrity stop by scope and strength. Its validator rejects missing or duplicate mappings, ticket/route breakers that claim global authority, and any attempt to soften protected safety controls. Ticket and route stops now carry deterministic runtime records through planning and supervisor status. Retry wakeups require the exact ticket binding; provider holds bind one role and route so healthy routes and unrelated tickets continue. Sprint pressure now degrades only new admission while active work continues. Only contract-declared sprint breakers may pause or stop the supervisor, and each global activation and resume is bound to one durable breaker generation. Authenticated schema-v1 supervisor checkpoints migrate once to the v2 breaker model without losing attempts, spend, reviews, PRs, dependencies, or history. Status keeps queued, active, retrying, parked, route-held, pressure-limited, globally paused, blocked, and terminal work distinct; parked work is never reported as complete.

Disposable phase execution uses orka.phase-worker-protocol/v1. Adapters negotiate mandatory fencing, fresh-context, progress, cancellation, and terminal-result capabilities before dispatch. Stale or malformed envelopes remain ticket-local failures and never authorize scheduler state changes. The durable supervisor now records a stable logical phase job and a fresh dispatch/execution identity for every invocation. Failed units can be replaced without changing the job or external-operation key, cancellation requires a bound acknowledgement or a fence, and restart reconciliation keeps a proven live unit instead of launching a duplicate. Existing 1.x ticket-workflow launches remain compatible while narrower phase adapters are introduced.

Please report security-sensitive findings privately according to SECURITY.md and follow the Code of Conduct.

Every change merged into main, including documentation and tests, must have a new version in BOTH manifests. Contributors do not need to guess that version: the maintainer chooses it when the PR is ready to merge, after reconciling other open changes. The maintainer updates:

• .claude-plugin/plugin.json (version)
• .codex-plugin/plugin.json (version) -- keep the two in lockstep

The maintainer also adds docs/releases/<version>.md to the PR and publishes a matching signed tag and GitHub Release after merge. Use semver: patch for compatible fixes, documentation, and tests; minor for backward-compatible features; major for breaking configuration or contract changes. See the maintainer release process.

Why this is non-optional: an installed plugin is a pinned snapshot, not a live checkout of this repo (Claude Code caches it under ~/.claude/plugins/cache/<marketplace>/orka/<version>/). Update detection keys off the version string. Merging to main without bumping the version means a user's next plugin update sees the same version and does nothing -- the fix never lands, silently. A version bump makes the plugin snapshot available; the signed tag and GitHub Release identify the same source revision for users who need a fixed version.

After merging, users pick up the change by updating the plugin (/plugin -> update the marketplace, then the plugin), not by starting a new session.

MIT. See LICENSE.