sortie: Instructions file for Codex

sortie

An agent orchestrator that ships as one statically-linked binary with no runtime dependencies. Most of its structure is enforced by convention rather than by the compiler: go build accepts every layering violation listed below.

Commands

make help lists the build, test, and lint targets; they carry the flags CI uses, so prefer one when it fits. Calling the Go toolchain directly is fine when no target does what you need.

Gotchas

• Go resolves through the asdf shim at ~/.asdf/shims/go. Overriding GOPATH, GOMODCACHE or the binary path breaks the pinned toolchain; GOFLAGS is not such an override and is allowed.
• Symphony is prior art, not a template. Sortie derives from OpenAI Symphony but diverges intentionally. Do not port Symphony patterns or Elixir idioms.
• Generic naming in core code. Use agent_*, tracker_*, session_* in orchestrator core. Never jira_*, claude_*, codex_* outside their adapter packages.
• The orchestrator resolves adapters by kind through internal/registry. Importing a package that registers a kind in its init() is a layering violation there even though go build accepts it; a package alongside it that registers none may be imported directly. cmd/sortie blank-imports every kind package solely to trigger that registration.
• internal/scm/ is an adapter family. Apply the same boundary rules as internal/tracker/*/: no cross-adapter imports, must not import the orchestrator, normalize external responses to domain types at the boundary.
• Shared adapter helpers go in an internal/ package named for the concern it serves, never duplicated per adapter and never in internal/domain/. Logic scoped to one adapter family nests under that family instead.
• Integration tests are env-gated by a per-adapter SORTIE_<ADAPTER>_TEST=1. Without the gate set they must skip cleanly — never fail.
• Tests wait on events, never on a clock. A test stops the code after its readiness or completion signal (for run(), runUntilStarted on the startupDone hook), never by handing it a short deadline, and proves a fast path by its result or under testing/synctest, not by timing it. Every wait goes through internal/waittest: HangGuard is the one hang guard, and a live suite passes its measured bound to the same waits. No time.Sleep for ordering. A raised timeout or a rerun job does not fix a flake.
• workflow.Manager.Reload() is fail-safe. On parse or validation error the previous currentConfig and currentPrompt are retained and LastLoadError() reports the failure. Preserve that invariant; never os.Exit on a bad WORKFLOW.md.
• Prompt templates render with Option("missingkey=error"). Adding a template variable without wiring its data field is a runtime error, not an empty string.
• The dashboard draws structure with layout, never with characters. No Unicode arrows, check marks, bullets or box glyphs to connect or mark values (a → b, ✓ done), and no · separator where a column, a second line, a chip or a stepper can carry the split. Glyphs come from web/src/components/icons.tsx.
• The dashboard's build output under internal/server/ui/dist is committed. make ui-build regenerates it from web/; commit it with the sources it was built from, and resolve a conflict in it by rebuilding, never by hand.