How Auriga is built

Component overview

The repo contains three independent subsystems. None is a dependency of any other — each has its own package.json and npm test.

The router

The router at src/router/ is the core of Auriga. It has zero runtime dependencies — plain Node.js ESM modules, no npm packages required to run. All decisions are pure functions; all I/O goes through injectable adapters.

Key files

No class declarations

The entire codebase has zero class declarations. All modules export plain factory functions (createXAdapter(cfg)) returning frozen object literals. This is a stated project convention in .pHive/CONTEXT.md.

Adapter interface

Auriga's routing core (lib/core.mjs) never calls Multica or any external system directly. All I/O goes through a typed adapter boundary. This makes the routing logic pure and testable, and makes it possible to swap the underlying board system without touching the routing policy.

// cycle() accepts injectable adapters — tests can pass stubs
export async function cycle({ backlog, spawn, cfg, core, log, sleep, ...opts }) {
  // backlog: BacklogAdapter — read/write the work board
  // spawn:   SpawnAdapter   — dispatch/assign/rerun agents
  // core, log, sleep: injectable for testing
}

Synchronous by design

BacklogAdapter and SpawnAdapter are synchronous — every method returns its result directly, never a Promise. This matches the real Multica-backed implementation (which uses execFileSync) and all existing call sites — several methods are called inside .some()/.filter() callbacks where await cannot be used. Do not make these adapters async without a concrete story that requires it.

MemoryAdapter is the deliberate exception: it has no synchronous consumer today and Mnemosyne's real transport is genuinely async.

Three adapters, not one

The backlog (where work items live), the runner (what actually executes work), and memory (what context informs a decision) are genuinely different concerns with different failure modes. A future implementation of any one should be swappable independently of the others.

Implementations

No speculative methods

Neither BacklogAdapter nor SpawnAdapter has any method that cycle() doesn't actually consume today. Do not add methods speculatively. Every method in these contracts exists because the real dispatch loop calls the equivalent capability. When a new need arises, add the method in the story that needs it.

Configuration split

Configuration is split into two files to separate policy (what the router decides) from substrate (who it routes to and where):

An optional external JSON override file can replace any key in either module via the AURIGA_CONFIG environment variable. Only keys present in the override file are replaced — absent keys keep their defaults. This allows per-deployment overrides without forking the config source.

Pantheon integration

In a Pantheon deployment, Auriga runs as a Docker container service defined in the pantheon-v2 compose stack. The container image is built from a plain git checkout of this repo at ${AURIGA_LOCAL_PATH:-./plugins/auriga}.

pantheon-v2-l2 stub

The adapters/pantheon-v2-l2/ directory is the intentionally-unbuilt stub for Auriga's future direct integration with the Pantheon L2 host (bypassing the external Multica CLI). It is the only sanctioned path for Auriga to call into Pantheon internals. It is not production code yet — the stub exists to hold the interface contract, not to be wired in.

Repo layout

auriga/
├── src/
│   ├── router/                 # The auto-router (production)
│   │   ├── auriga-router.mjs   # Entrypoint, exports cycle()
│   │   ├── supervisor.sh       # Single-instance supervisor
│   │   ├── bin/auriga.mjs      # CLI subcommands
│   │   ├── lib/
│   │   │   ├── core.mjs        # Pure decision logic
│   │   │   ├── config.mjs      # Policy config
│   │   │   ├── config-substrate.mjs  # Substrate config
│   │   │   ├── config-loader.mjs     # External JSON override
│   │   │   └── adapters/       # BacklogAdapter, SpawnAdapter, MemoryAdapter
│   │   ├── agents/             # Agent instruction files
│   │   ├── scripts/            # Export human queue, launchd install
│   │   └── test/               # Unit + e2e tests
│   ├── server/                 # Read-only API over .pHive/ state
│   └── ui/                     # Operator dashboard (Vite + Tailwind)
├── docs/                       # GitHub Pages source (this site)
│   ├── index.html              # Project page
│   └── docs/                   # Full documentation
├── scripts/                    # Repo-root convenience scripts
├── install/                    # Git hooks for Pantheon auto-redeploy
└── .pHive/                     # Planning state (epics, stories, audits)