How Auriga thinks

The routing cycle

cycle() is the core function exported from auriga-router.mjs. It runs one complete scan-and-dispatch pass. In production, main() calls it in a while(true) loop separated by sleep(cfg.CAPS.cycleMs). Each pass runs exactly this sequence:

1. acquireLock()                  // pidfile — single-instance safety
2. detectZombies()                 // find stale in_progress → requeue or give up
3. detectRunCompletions()          // in_progress → in_review on run done
4. detectVerifiedDone()            // in_review → done on PR merged
5. detectCascadeCompletions()      // enqueue dependents of newly-done issues
6. detectFalseDone()               // wrongly-done → in_review correction
7. reviewDispatch()                // fire review squad for in_review + open PR
8. selectAssignments()             // pick unassigned todos for this cycle
9. assignAndVerify() per pick      // assign, check a run actually started

Steps 2–6 are pure status-machine passes derived entirely from live board state. Steps 7–9 are the dispatch passes. The cycle is always bounded: each step has an explicit cap on how many mutations it can make per cycle, so a single bad run can never mass-flip the board.

State machine

Issue status transitions are driven entirely by verifiable board facts — not by trusting what a run or agent reports about itself. This is a deliberate constraint from a past incident where run-status trust caused false completions.

Transitions Auriga drives

Idempotency

Every transition scan re-derives its candidate set from live board state each cycle. A transitioned issue falls out of its source filter next cycle by definition — no explicit "already processed" tracking is needed.

Capacity model

Auriga enforces a layered capacity model to prevent mass-dispatch and to keep the Claude account from being saturated by a burst of simultaneous agent runs.

Cap layers

Runtime buckets

Agents are grouped into runtime buckets (e.g. claude, claude-review, claude-planning). Each bucket has its own RUNTIME_CAP so review dispatches don't compete with build-lane dispatches for the same Claude account slots.

// Example: review agent gets its own bucket, capped at 1
RUNTIME_CAP['claude-review'] = 1;

// Build lane agents share the 'claude' bucket (default cap)
RUNTIME_CAP['claude'] = 4; // set in config-substrate.mjs

Capability routing

Not every agent can run every kind of work. Auriga classifies each issue as a "hive story" or not, and routes accordingly.

Hive stories

A hive story is one authored for the plugin-hive SDLC workflow (/hive:execute, /hive:review, /hive:test). Only Claude+plugin-hive lanes can run hive stories — Codex/Opencode lanes do not have the plugin-hive install. isHiveStory(issue, cfg) detects this from the issue's content.

Lane selection

Lane maps are configured in config-substrate.mjs as PROJECT_LANE — a map from Multica project ID to the lane for that project's stories. This lets different Pantheon tenants or gods route to different lane pools.

Human-todo filter

Some issues are flagged for human attention, not agent dispatch. Auriga's priority-1 filter excludes these from the dispatch pool before any lane or capacity logic runs.

How an issue becomes human-todo

An issue is a human-todo if it carries the label human-todo, or if its metadata includes waiting_on: <human name> where the name matches one of the configured HUMAN_NAMES (matched case-insensitively, substring OK).

Human queue export

Human-todo issues are never just silently dropped. Run the export script to write them to .pHive/human-queue.yaml for a human to triage:

# from repo root
node scripts/export-human-queue.mjs

# or from src/router/
node ../../scripts/export-human-queue.mjs

Review squad

When an issue enters in_review with an open PR, Auriga fires the review squad — the "back-half" of the loop. The squad runs four perspectives and either ships the PR (merge to dev + story done) or sends it back with concrete per-perspective feedback.

The four perspectives

Squad sizing (scale by ticket type)

Running the full four perspectives on every ticket wastes resources. Auriga's reviewSquadPlan(issue, cfg) classifies the issue from REVIEW_SQUAD_RULES and drops inapplicable perspectives:

The plan (tier, perspectives, playwright flag) is logged and posted as a comment on the ticket before the squad runs — so what the squad will do is always visible up front.

Zombie recovery

A zombie is an in_progress issue whose run has stalled, failed, or simply gone quiet for longer than zombieStaleMs (default: 20 minutes). Auriga's detectZombies() pass recovers them each cycle.

Recovery behavior

1. Detect — find in_progress issues where the latest run is done/failed or stale past the threshold.
2. Requeue — if attempts < zombieMaxAttempts (default: 3), re-assign and re-run the issue.
3. Give up — if max attempts exhausted, set status to blocked and post a comment explaining why. Never silently drops — always leaves a visible record.