System architecture
The reference view shows what Orion is made of, layer by layer, and where it falls short of an enterprise platform. The flow view shows how one idea moves through it.
Reference view
The middle stack runs from the people using Orion down to the platforms it calls. Governance and observability are pillars because they apply to every layer.
Solid boxes are built. Dashed boxes are layers an enterprise AI delivery platform needs that Orion lacks or has only in part.
| Gap | Today | Status |
|---|---|---|
| Evaluation | Orion's own evals/cases holds a starter example, not real cases, so "green" says little on its own about agent work landing unattended | gap |
| Retention | watch logs and events.jsonl accumulate; nothing prunes them | gap |
| Shared service | one machine, one user, by design; no high availability, no team queue | gap |
| Production feedback | orion aiops reads Orion's own run logs; nothing brings incidents from the shipped product back as tickets | gap |
| Identity | a Slack approver allowlist and a local web login; no SSO, no secrets vault | partial |
| Audit | the events log is complete but local and editable, not tamper-evident | partial |
The Roadmap tracks progress on each gap.
Flow view
1. Plan
orion new interviews you about the idea. orion plan KEY then runs its
planning chain, ending in a Jira Epic / Story / Task tree, which you approve
once before anything is created. Each step skips itself when its artifact
exists, so re-running plan resumes. Inception
has the detail.
2. Deliver
orion watch KEY claims queued tickets (label ORION) one
sweep at a time. Each ticket is routed, implemented, tested by QA, pushed and
marked ready on its own branch. collect assembles ready branches into a
batch, runs CI once and lands it on develop. A red batch is split until the
culprit is found, and the culprit goes back to an agent. A failed ticket is
retried at most twice, then named under NEEDS YOU. Landing needs no click
unless slack.merge_approvers names people.
Construction has the detail.
3. Inside every stage
The supervisor starts claude -p in an isolated
workspace. Every tool call goes through orion hook (breaker, gate,
shield), which blocks deterministically. The record lives under ~/.orion
and in each workspace's .orion/events.jsonl.
The sandbox has the detail.
Orion and its toolkits
Orion owns orchestration, gating, artifacts and the tracker contract. An external toolkit supplies the method inside a stage: a delegated skill runs as one step in a stage Orion is already sequencing and reports a verdict back. It never decides what runs next, never merges, and keeps no record of its own.
| Concern | Owner |
|---|---|
| Deterministic enforcement: loops, budgets, wall clock, gates | Orion |
| Isolated sandboxed workspaces | Orion |
| Process supervision: kill, quota wait, retry, notify | Orion |
| Cross-project lesson memory | Orion |
| Review, security, testing, PR, docs, work decomposition | the toolkit (nj-agents by default) |
| Constitution, spec, plan, analyze for a new project | spec-kit by default |
So Orion declines any part of a toolkit, such as a workflow engine, that wants to decide what runs next. The reasoning and two worked examples are in ADR 0001, ADR 0002 and ADR 0021.
The toolkit block in orion.json maps a stage to a command and rejects a
block that expresses an order
(nj-agents and other toolkits).
Where spec-kit comes in
A new project's orion.json delegates the four planning steps tagged
spec-kit in the flow view:
| Step | Default command |
|---|---|
| constitution | /speckit-constitution |
| spec | /speckit-specify |
| plan | /speckit-plan |
| analyze | /speckit-analyze |
decompose then reads spec-kit's tasks.md to build the ticket tree.
Change any of these in toolkit.stages; a project whose stages name no
spec-kit command never installs it. Background:
ADR 0019,
ADR 0021,
ADR 0022.
Storage
Config, event logs and the audit trail are plain files you can read, grep and
diff, and config can carry inline _comment_* explanations beside its
values. Without SQLite, Orion stays a single static binary with no cgo. An
advisory lock protects the shared state under ~/.orion across processes
(ADR 0004).
Code layout
The Go packages under internal/ are grouped by role:
| Group | What it covers |
|---|---|
| planning | discovery, decomposition, provisioning, the tracker, the toolkit, adoption, workspaces |
| delivery | the watch, a ticket's run, collecting and landing, the queue, claims, the supervisor, advisors, promotion and the changelog |
| guardrails | the hooks, breaker state, budget, quota handling, process-safe locking |
| reporting | events, reports, cost, aiops, the dashboards, export, the web server, notifications, Slack |
| plumbing | config, credentials, the agent roster, lessons, sessions, doctor, update checks |
The generated Packages page lists every package and what it is for.
What neither view shows
- Releasing a milestone in detail: Releasing a milestone.
- The advisor path for a question an agent cannot answer, and how a recommendation becomes a decision: Advisors and decisions.
- The package-level call graph. It is not documented.