sortie CLAUDE.md

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.
• 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.