orca: Instructions file for Codex

Working on Orca

Internals, architecture, and coding conventions for hacking on the library itself. Build/test commands and the recipes for running a locally modified orca live in CONTRIBUTING.md; end-user documentation at orca.virtuslab.com (source in docs/).

Orca is implemented in Scala 3 on top of Ox for structured concurrency, tapir for JSON Schema derivation, and jsoniter-scala for codec generation.

Project layout

orca/
├── build.sbt / project/
├── tools/      # tool traits + os-backed impls (git/gh/fs), internal LLM SPI + session durability, InStage, events, subprocess
├── flow/       # stage/display/fail + FlowContext/FlowControl; orca.{plan,review,pr,progress}
├── claude/ codex/ gemini/ opencode/ pi/   # one module per coding-agent backend
├── runner/     # flow() entry, DefaultFlowContext/DefaultFlowControl, FlowLifecycle, terminal UI
└── shell/      # `orca-shell`, the `orca` CLI's interactive front-end (ADR 0021)

Dependency graph:

tools   (standalone)
  ├── flow                          → tools
  ├── claude / codex / gemini /
  │     opencode / pi               → tools
  ├── runner                        → tools + flow + all five backends
  └── shell                         → runner (published `orca`)

The runner module owns the flow entry point (package orca) and wires defaults via DefaultFlowContext and DefaultFlowControl (package orca.runner); the stage setup/teardown/recovery state machine is orca.runner.FlowLifecycle. The terminal UI lives in orca.runner.terminal, behind an Interaction, so swapping it for a Slack or HTTP equivalent is one substitution at the call site rather than rewiring modules.

The user-facing surface lives in package orca (the flow entry, the tool accessors — including planningAgent/codingAgent/reviewAgent, the backend-agnostic role accessors (ADR 0020) — stage/display/fail, JsonData, OrcaArgs and the RunTarget its flags parse into). Implementations live in focused subpackages: orca.tools (os-backed git/gh/fs impls + their traits), orca.gitref (validated branch names and commit hashes, and Head), orca.json (JsonData, RawJson, whole-file JsonFile documents), orca.agents + orca.backend (LLM SPI, SessionSupport, per-backend decoders; the SPI is private[orca] or private[backend], so a new harness is added in orca itself), orca.subprocess (subprocess shim), orca.events (event bus), one orca.backend.<backend> per coding agent, and orca.runner / orca.runner.terminal (wiring + terminal UI). The flow module adds orca.{plan,review,pr,progress}.