Architecture decisions

One file per decision: what was decided, why, and what it binds later work to. Read before re-proposing something that looks like a gap — it may already have been decided against, on purpose.

• 0001 — Orion owns orchestration; a toolkit supplies methodology inside a stage, never control flow across stages
• 0002 — Superpowers declined as a dependency; three of five ideas adopted natively
• 0003 — Ponytail kept, scoped to development only
• 0004 — No SQLite; config, event logs and the audit trail stay as files
• 0005 — Agent roster is global, not per-repo
• 0006 — orion new and the plan stage are sequential phases, not two front doors
• 0007 — Auto effort is a standing preference, not per-ticket
• 0008 — Parallelism ships level 3, then level 1, then level 2
• 0009 — One canonical slug names the Jira project, workspace and git repo
• 0010 — The routing vocabulary is a published contract, and five actors are routable
• 0011 — Orion owns the landing queue; GitHub's merge queue is not adopted
• 0012 — A tracker project gets one workspace; a second orion plan refuses
• 0013 — orion new creates the tracker project and no workspace
• 0014 — a supervised run gets a config directory Orion curates, and no MCP servers
• 0015 — under a merge ref Orion is the gate on landing, and develop keeps a post-merge check as the backstop
• 0016 — implementation fans out by Go package, the implementer proposes and a deterministic check disposes, and only the parent verifies
• 0017 — the integration state machine carries the sophistication; the queue is Go channels and JSON, with a git SHA recorded at every transition
• 0018 — the fan-out unit is per stage: the Go package for implementation, the case group for test authoring, where 0016's two hazards do not apply
• 0019 — Orion is toolkit-agnostic; nj-agents ships as the default, not a hardcoded dependency
• 0020 — A toolkit must ship a skills/ directory, and vendoring is global to the machine
• 0021 — spec-kit runs inside Orion's stages; its workflow engine, extension hooks and bundles are declined
• 0022 — spec-kit is installed per project by specify init at provisioning, and Orion pins the feature directory
• 0023 — One tracker project is one .specify/; features accrue as specs/NNN-*/; the spec is a living document
• 0024 — the local web surface is authenticated by a per-process token in a custom header; Origin and Host checks are additive layers, not alternatives
• 0025 — the web front end moves to React + TypeScript + Fluent UI 2, built at dev time and committed like the current UI
• 0026 — the web surface writes configuration from an allowlist, through the CLI's own validation; agents first
• 0027 — a person's answer reaches the ticket through an inbox the watcher drains; the web process holds no tracker credential
• 0028 — a person clears a gate from the browser through four CLI commands, argument lists built server-side; local approval is off unless turned on
• 0029 — a person starts work from the browser through three planned commands; children belong to the web server and stop with it
• 0030 — a project is the web surface's unit, held in the registry; orion new and orion plan run from the browser, the remote is never edited there
• 0031 — failed tickets retry when the work branch moves, at most twice; evictions are a record, and a ticket evicted twice goes to a person
• 0032 — the label is the lock; a PID and a heartbeat together decide whether anyone still holds it
• 0033 — merge approval is a Slack reaction from a named approver, read by polling; any rejection wins
• 0034 — the watch draws a full-screen view on the alternate screen and keeps every line in a log file
• 0035 — watch events export over OTLP, never block the watch, and never carry a secret
• 0036 — a release is promoted by a person through five named checks that block only what would ship something wrong
• 0037 — QA's tests run against the pre-change commit, and fix mode keeps a failing test from being weakened
• 0038 — the web surface sets Jira and Slack credentials write-only, into Orion's own 0600 file; never sent back, Linear not offered
• 0039 — an answered question continues the run that asked, on its own branch; a retry still gets a fresh one; the agent session is not resumed

Ticket references

Some decisions mention keys such as OR-149. They point into Orion's own tracker, which is not public; each decision is written to stand without them.