orchestra-code: Instructions file for Codex

AGENTS.md

What this repo is

Go CLI (cmd/orchestra) that orchestrates multiple AI coding agents (Claude Code, OpenCode, Mimo, etc.) through a single supervised interface. Agents run headless; human approves via diff review.

Build & verify (run these in order before pushing)

go build ./...          # compile
go vet ./...            # static analysis
go test ./...           # all tests
gofmt -w .              # format (CI enforces this)

No shortcuts. CI runs exactly these four steps against Go 1.22.

Single-focus commands

go test ./internal/scheduler/...   # test one package
go vet ./internal/engine/...       # vet one package
gofmt -l .                         # list unformatted files

Build the binary

go build -o bin/orchestra ./cmd/orchestra
./bin/orchestra --help

Binary is at bin/orchestra (gitignored).

Project structure

• cmd/orchestra/ — Cobra CLI (main.go + one file per subcommand: run, do, plan, dashboard, agents, etc.)
• internal/engine/ — the core supervised loop (dispatch → validate → retry → review). Every front door (run, shell, do) drives this.
• internal/agent/ — Agent interface + registry. This is the extension point for adding new agents.
• internal/router/ — AI routing: classifies intent → picks agent. CLI classifier by default; optional direct-API classifier (router.classifier); history-aware agent resolution via the History interface.
• internal/planner/ — decomposes requests into ordered steps with depends_on for parallelism.
• internal/scheduler/ — bounded-concurrency DAG runner for parallel isolated tasks.
• internal/parallel/ — shared plan → waves → isolated task logic (Graph, BaseGuard, RunStep) used by do --parallel and the dashboard's /parallel.
• internal/worktree/ — task isolation behind the Isolator interface: worktree.New(dir) picks git worktrees in a repository (branch per task, merge + conflict detection) or a CopyIsolator in plain folders (temp copy per task, all-or-nothing merge, conflict if a touched file changed in the source).
• internal/validate/ — build → lint → test pipeline, auto-detects toolchain, stops on first failure.
• internal/config/ — YAML config + built-in agent defaults + toolchain auto-detection.
• internal/memory/ — SQLite history at ~/.orchestra/orchestra.db (never in the repo tree): runs, diffs, benchmarks, tokens/cost, and the per-directory agent scores the router uses.
• internal/update/ — self-updater: checks GitHub Releases (throttled to once per 24h), verifies checksums.txt, swaps the binary in place. Relies on the GoReleaser archive name template — see docs/RELEASING.md.
• internal/tui/ — Bubble Tea dashboard: Chat (live run panel + file-by-file review), Changes, History, Agents, Benchmarks, Logs. One file per concern (chat, live, review, views, chrome, theme, table).
• internal/ui/ — terminal styling (gradients, spinners, diffs). TTY-aware.
• internal/shell/ — interactive chat REPL.
• internal/review/ — diff display + accept/reject prompt.
• internal/runner/ — generic process exec (stream/capture/timeout). The engine's engine.
• internal/gitutil/ — git helpers (is-repo, is-clean, diff, restore, commit).
• internal/fsdiff/ — git-free supervision for plain folders: directory snapshots, a Myers line-diff emitting git-style unified output, and snapshot restore. Used by the engine whenever --dir is not a git repository.
• internal/llm/ — HTTP LLM providers (Provider interface; openai-compatible + anthropic). No new deps: stdlib net/http.
• internal/patch/ — extracts unified diffs / whole-file blocks from model output and applies them (git apply --check dry-run first; traversal-guarded writes).