/nexus

Full Routing Matrix

Purpose: Canonical task-type → default chain mapping with Recipe Hints (per-step sub-skill commands) and conditional Additions. Read when: The quick-start matrix in SKILL.md is insufficient and you need the full task-type catalog.

Boundary vs agent-chains.md: This file gives one row per task type with the default chain. agent-chains.md lists complexity variants (e.g., FEATURE/S, FEATURE/M, FEATURE/L, FEATURE/UI, FEATURE/UX) and dynamic adjustment rules. Start here to pick the task type; switch to agent-chains.md when complexity sub-typing matters.

Complete task type → agent chain mapping. The SKILL.md Routing Quick Start contains the top patterns; this file contains the full matrix.

Classify Flow — Internal Default Dispatch Phase Contract

CLASSIFY is the internal phase:CLASSIFY Default dispatch when no Recipe subcommand and no Signal-Keyword match fires; it is not a Recipe or subcommand. It resolves intent and routes to the best chain, preferring a curated Recipe over an ad-hoc one. Phases: RESOLVE → GATE → MULTI? → REDIRECT? → SELECT → LADDER? → CHAIN_SELECT.

• RESOLVE (intent) — apply intent-clarification.md (GATHER git log / .agents/PROJECT.md / history → READ tone/scope/urgency → DECIDE). Produce a one-line intent statement with stated assumptions (Three Laws #3: never hide assumptions).
• GATE (confidence floor) — assign context_confidence from the discrete evidence bands in confidence-scoring.md. < 0.60 OR 2+ valid interpretations → ask ONE focused question with options (CIPHER_GATE), integrate the answer, re-type the unknown dimensions, and assign a new band. Never build a chain on a sub-floor classification — proceeding on a guessed intent is forbidden (Never: ignore blocking unknowns). GATE is not skippable by reaching LADDER: a sub-floor score on the SCOPE dimension (how literal/broad the ask is — _common/CONTEXT_SUFFICIENCY.md) still requires GATE's clarifying question before proceeding, even when the intent also turns out to match no Recipe/task-type. Only routing-dimension certainty ("no skill fits, and SCOPE/intent are otherwise clear") skips straight to LADDER without a further GATE question. Tone precedence: a frustrated tone compresses GATE's question to exactly ONE tightest-framing question with pre-filled safest-default options — it never authorizes zero questions on a sub-floor classification (intent-clarification.md § Tone & Scope Interpretation Patterns, Precedence rule).
• MULTI? (multi-domain check — mandatory step, not a disconnected note) — before REDIRECT/SELECT commit to a single chain, explicitly test whether the resolved intent spans 2+ independent domains (e.g. "add OAuth and fix the slow dashboard"). This check must fire on every walk of the flow, immediately after GATE — a literal, mechanical walk of RESOLVE→GATE→REDIRECT that never pauses to ask "is this actually one domain?" is exactly how the second domain of a mixed request silently drops. If 2+ domains are found: do NOT force one chain — decompose with Sherpa into per-domain subtasks, route each independently (each subtask re-enters at its own GATE — a subtask can be sub-floor on confidence even when the combined request passed GATE — then proceeds through REDIRECT? and the rest of the flow), then run as parallel tracks under hub-spoke ownership. One chain straddling domains is an anti-pattern. If exactly one domain, proceed to REDIRECT.
• REDIRECT (Recipe-match check — the key step) — before building an ad-hoc chain, translate the resolved intent to English canonical intent and test it against the Recipe set (semantic match, per the Signal Keywords table). If it maps to a Recipe (bug / feature / security / refactor / optimize / kaizen / apex / …), redirect to that Recipe and run its phase contract — do NOT hand-roll a chain that shadows a curated one. CLASSIFY builds an ad-hoc chain ONLY for task types with no Recipe (the matrix-only types below). This prevents a worse ad-hoc chain from silently replacing a maintained Recipe.
• SELECT (task-type → chain) — for the no-Recipe case: classify into one of the task types below, take its default chain, apply Sherpa-skip / add-when adjustments (§ Sherpa Skip & Chain Adjustment below), and check guardrail needs (L4 / destructive / 10+ files).
• LADDER (no task-type match — the true-gap case) — if RESOLVE's intent matches neither a Recipe (REDIRECT) nor a row in the Task Type table below (SELECT), do NOT hand-roll a chain yet. Spawn compass(recommend) as a hub-spoke step with the resolved intent. If compass returns a fit (1-3 candidate skills), redirect to that skill's default Recipe or explicit Default dispatch and record fallback_taken: compass-invoked. If compass returns Gap mode (no matching skill — compass/SKILL.md Output Routing, "No matching skill" row), spawn architect with the gap signal to produce a proposal artifact (ARCHITECT_TO_NEXUS_HANDOFF) and record fallback_taken: architect-invoked. Present the proposal to the user before building a new skill (Ask First: "Approving creation of a new skill via LADDER" — nexus/SKILL.md § Ask First; distinct from the "first-time use of a newly registered agent" bullet, which governs a subsequent chain that includes an already-registered new agent). Only on explicit user decline does CLASSIFY fall back to an ad-hoc chain — record fallback_taken: neither — reason: user declined gap-fill and log it as Fallback: ad-hoc (reason: user declined gap-fill), never silent. Exception (LADDER triviality/meta carve-out): a direct-answer request — a one-line factual/lookup question with a single correct answer, or a meta-question about the harness itself (e.g. "what does CLASSIFY do?") — answers directly without walking the ladder; this carve-out is narrow and bounded to non-task-shaped requests only (see nexus/SKILL.md § Never). A one-line judgment/decision question (e.g. "REST or GraphQL for the new API?") is NOT carve-out-eligible — it is task-shaped (DECISION → Magi, or gedanken per the verdict-seeking rule in signal-keywords.md) and routes through REDIRECT with Three-Laws assumption disclosure. Any request that asks for work product (code, a document, an analysis, a chain of steps) is task-shaped and the ladder remains mandatory. Non-closable gap: if architect determines the requested act is legally/physically restricted to a licensed human (e.g. a USPTO filing under 37 CFR 11.5), it declines the gap-fill proposal and surfaces the boundary instead — outcome remains fallback_taken: architect-invoked with an explicit boundary note (not neither; the ladder was walked, it just could not close the gap with a skill). Both compass and architect spawns use the standard Agent Spawn Template (reference/hub-authoring.md § Agent Spawn Template) and therefore inherit the same agy/codex silent-output mitigations (_common/CLI_COMPATIBILITY.md §9.2/§9.3) as every other Nexus spawn — no separate handling needed.

Exit: a selected chain (or Recipe redirect, or LADDER outcome) + confidence ≥ floor + documented intent/assumptions → CHAIN_SELECT → gated SPECIFY? (specify-phase.md) → EXECUTE. SPECIFY never substitutes for GATE: it hardens the language of an intent contract that already cleared the confidence floor, and specifying a guessed intent only yields a precise instruction to do the wrong thing.

Anti-patterns prevented (prevents: ad-hoc chain shadowing a curated Recipe → REDIRECT, routing on a guessed intent → GATE, one overloaded chain for a multi-domain ask → MULTI?, hidden assumptions → RESOLVE, silent ad-hoc fallback with no compass/architect consultation → LADDER)

Orchestration Gate — the rung below "one agent"

Core Rule #1 picks the smallest chain. This gate asks the question underneath it: should this be orchestrated at all? The rule minimizes among chains and therefore always yields one; a request that wants a fixed sequence, or a single tool call, or an answer, gets a chain anyway — and pays coordination cost for structure it never needed.

Climb from the bottom, and record why each rung failed. Evaluate in order — direct answer · single tool call · fixed sequence · one agent · a chain — and take the first that suffices. When you skip a rung, name the specific thing it could not do. "It might get more complex later" is not that reason: the future is discounted, the coordination cost is paid today.

Do not orchestrate when any of these holds:

• The steps are fixed and the exceptions are enumerable. A known sequence with deterministic checks is a procedure, and a procedure executed by a chain is slower, costlier, and harder to audit than the same procedure written down.
• One agent already has the context and the authority. Splitting it produces context transfer and merge work, not parallelism.
• The split is by role name only. Planner/Researcher/Critic over one model, one context, and one set of permissions adds call count and failure points, not capability. If ownership, authority, knowledge, failure containment, and independent evolution are the same on both sides, it is one agent with stages.
• Nobody owns the outcome if it fails. If you cannot name, in advance, who is accountable when the chain produces a wrong result, the chain has no owner — it has participants. Fix that before adding steps.
• Nothing verifies the result. With no independent check, more steps produce more confident output, not more correct output.
• The effect is irreversible and the controls for it do not exist. See the Action-Tier ceiling in routing-learning.md — a T4 effect under a T1 ceiling is not a chain-design problem; it is a decision to make the effect reversible or to keep a human on the commit.

Prefer proposal-then-commit over an agent that commits. A chain that produces a proposal and lets a deterministic step or a human commit needs almost none of the machinery above. Embedding the final irreversible effect inside the agent loop is the most expensive available option, and it is rarely the one the request required.

Record the rejection, and make it re-openable. When the answer is "do not orchestrate", say so with the rung that sufficed and the reason the next rung was unnecessary — and name what would change the answer (a second owner appears, the exception set stops being enumerable, an independent release cadence is needed). A rejection with a stated re-open condition is a decision; a rejection without one gets silently re-litigated on the next similar request.

This gate cannot be satisfied by adding agents. If it fires, the remedy is a smaller shape, never a better-supervised larger one.

Sherpa Skip & Chain Adjustment

FEATURE Phase Contract

feature is the highest-traffic Recipe; its chain row is a summary. Phase semantics (read before executing a non-trivial feature):

• SURVEY (Lens, conditional) — reuse before you build — for any feature added to an existing codebase, scan for reusable implementations BEFORE decomposing: does the function / component / hook / pattern already exist? Extend or compose the existing one instead of reinventing it. Skip only for greenfield. The most common feature-implementation waste is re-deriving code that already ships — this step is the guard (repo rule: don't re-implement what already exists).
• SPEC (Sherpa) — decompose into atomic steps AND lock acceptance criteria + scope boundary before any code (front-loaded ACs become Radar's test targets and the VERIFY gate). Fold SURVEY's reuse findings into the plan (build-on-existing vs build-new, stated per step). Skip Sherpa only when the change is single-file atomic, but still state the ACs inline.
• PROTOTYPE (Forge, conditional) — run only when the approach is unproven (new UI pattern, uncertain API shape, integration risk). Forge output is a throwaway spike to validate feasibility, NOT the shipped artifact. Skip for well-understood CRUD/backend additions — Builder goes straight to production. Prevents both "rebuild from scratch, lose the spike's learnings" and "ship the prototype as production".
• BUILD (Builder; +Artisan for frontend production) — production implementation carrying forward the spike's validated decisions and SURVEY's reuse plan. UI surface routing: +Muse when introducing new design tokens/visual primitives, +Palette when interaction-heavy, Artisan owns frontend production code. Backend/CLI features skip all three.
• VERIFY (Radar + gate) — Radar adds edge-case/regression tests; THEN the VERIFY gate requires existing build + test + lint/typecheck green against the locked ACs. Not "new tests pass" — the whole check suite. Additionally confirm each locked AC is actually satisfied (covered by a test or demonstrated behavior), not merely that the suite is green — convergence on green ≠ the feature does what the spec required. A feature is not done until the gate passes (repo quality rule).
• SHIP (Guardian) — PR-prep: commit granularity, PR title/description, ACs linked to evidence.

Anti-patterns prevented (prevents: prototype-shipped-as-production → PROTOTYPE, feature-without-acceptance-criteria → SPEC, new-tests-green-but-build-broken → VERIFY full suite, no PR discipline → SHIP, reinventing code that already ships → SURVEY, green suite that doesn't meet the spec → VERIFY per-AC)

BUG Phase Contract

Bug-fixing has a best-practice order the default chain must honor — reproduce before you fix:

• RCA (Scout) — root-cause analysis: why the bug occurs, where to fix, reproduction steps, impact/blast radius. Confirm it IS a defect (not expected behavior / misconfig / user error) before proceeding — a misread "bug" exits here with an explanation, no code.
• DECOMPOSE (Sherpa, conditional) — only when the fix touches 3+ files or spans components. Skip for single-component atomic fixes.
• REPRODUCE-FIRST (Radar) — encode Scout's reproduction steps as a failing automated test BEFORE any fix. The failing test is the acceptance criterion: red now, green after the fix. A regression test written after the fix can't prove it actually addresses the reported bug — it never failed.
• FIX (Builder) — fix the root cause Scout identified, not the symptom. Symptom-only patches (swallowing the error, masking the output, broad try/except) are rejected — repo rule: fix root causes, don't silence.
• VERIFY (Radar + gate) — the repro test now passes (bug gone), the existing build + test suite stays green (no new regression), and Scout's blast-radius areas are spot-checked. +Sentinel when the bug has a security dimension.
• SHIP (Guardian) — PR carrying the repro test + root-cause explanation, so the fix is auditable and the regression is permanently guarded.

IMAGE BRANCH (screenshot attached) — when the bug report carries a screenshot/error-screen image, two extra obligations bind:

• At CLASSIFY: run the full _common/IMAGE_INPUT.md pipeline including the mandatory five-section bug-report analysis (Observations / Inferred context / Problem points / Improvement proposals / Open questions). The structured reading — never the raw image alone — enters Scout's _AGENT_CONTEXT; image Ask-First triggers override AUTORUN.
• At VERIFY: when the defect is visually observable and a capture path exists, add the Visual Fix Loop (IMAGE_INPUT.md § Visual Fix Loop): re-capture the same screen post-fix and compare per Problem point (resolved/unresolved/regressed/not-capturable). No capture path → the visual claim is marked UNVERIFIED in NEXUS_COMPLETE, never silently asserted.
• Improvement proposals from the analysis that the user did not bundle stay incidental — listed in NEXUS_COMPLETE follow-ups, not folded into the fix scope.

Anti-patterns prevented (prevents: regression test that never actually failed → REPRODUCE-FIRST red→green, symptom patch leaving the cause live → FIX root-cause, fix that breaks something else → VERIFY suite+blast-radius, "fix" for a non-bug → RCA gate, no PR/regression guard → SHIP, downstream agents re-interpreting raw screenshot pixels → IMAGE BRANCH structured reading, visually-reported defect claimed fixed without an after-capture → IMAGE BRANCH Visual Fix Loop)

SECURITY Phase Contract

A security fix is only real when the exploit is confirmed closed — static detection alone is faith-based. Order:

• TRIAGE (Sentinel + severity) — classify the finding: severity (CVSS), exploitability, and scope (own code vs dependency CVE vs config/secret). Severity sets urgency; scope sets the route — a dependency CVE routes to Shift (upgrade path), not a code patch. Confirm it is a real vulnerability, not a SAST false positive, before mobilizing.
• CONFIRM-EXPLOIT (Probe / Breach, conditional) — for dynamically-reachable vulns, prove it is actually exploitable (DAST / red-team) before fixing: don't burn effort on a false positive, and capture the working exploit as the verification oracle (the security analogue of bug's failing repro test). Skip for self-evident static issues (hardcoded secret, obvious injection sink).
• FIX (Builder) — fix the root cause at the right layer (parameterize the query, validate/encode at the boundary, rotate-and-vault the secret) — not a surface filter the next payload bypasses. Repo rule: defense at the boundary, don't silence.
• VERIFY-CLOSED (Probe / Radar + gate) — re-run the exploit/DAST: the vuln no longer reproduces. Radar encodes the attack as a regression test; the existing suite stays green. For secrets: confirm rotation AND removal from git history (a fix that leaves the secret in history is not closed).
• DETECT (Vigil, conditional) — add a detection rule (Sigma / Detection-as-Code) so reintroduction or in-the-wild exploitation is caught. Recommended for high-severity or recurring vuln classes.
• SHIP (Guardian) — security-aware PR: do NOT disclose exploit details in a public commit before the patch is deployed; link to the advisory/CVE; coordinate disclosure timing.

security mode=to-zero — the scanner-finding sweep

The phases above handle a vulnerability (or a triaged set) once. mode=to-zero wraps them in a loop whose completion oracle is a scanner's finding set over a frozen scope driven to zero at a CVSS floor. It is a member of _common/FINDING_LEDGER.md — read that file before running this mode — and declares its five slots there rather than restating the machinery:

Disposition added: RISK-ACCEPTED (owner, expiry). Risk acceptance is this domain's WONTFIX, and it is also its self-dismissal analogue (FINDING_LEDGER.md §6): a scan reaches zero fastest by accepting everything. So an acceptance without a named owner and an explicit expiry date is invalid; acceptance of a CRITICAL/HIGH finding is Ask First; and an acceptance whose expiry has passed re-opens as OPEN on the next run rather than persisting silently. FALSE-POSITIVE-RATIFIED keeps CONFIRM-EXPLOIT as its refute-polarity mechanism — the attempt to prove exploitability is what a dismissal must fail at.

Scope stays frozen: a fix requiring changes outside the scan scope is DEFERRED with a route, and a dependency CVE still routes to Shift for the upgrade path rather than being patched in place.

Recurrence-prevention note: "make sure it never happens again" is a distinct ask from DETECT — Vigil's detection rule catches this vuln class recurring or being exploited in the wild (reactive, after-the-fact). A recurrence-prevention request additionally adds +Hone (HOOKS — e.g. a pre-commit/CI hook that blocks the specific pattern from being reintroduced, proactive/mechanical). Both can apply together; neither substitutes for the other.

Add-ons: +Crypt (cryptographic design fix), +Shift (dependency CVE → upgrade), +Cloak/+Canon[regulatory] (privacy/compliance dimension), +Sentinel re-scan after fix, +Hone (recurrence-prevention hook, distinct from Vigil detection — see note above).

Anti-patterns prevented (prevents: "fixing" a SAST false positive → TRIAGE+CONFIRM-EXPLOIT, band-aid filter → FIX root-cause/right-layer, faith-based unvalidated fix → VERIFY-CLOSED re-run, vuln class silently reintroduced → DETECT rule, premature exploit disclosure → SHIP, secret left in git history → VERIFY-CLOSED history check)

REFACTOR Phase Contract

Refactoring's invariant is no external behavior change — and the only proof of that is a test suite that passes identically before and after. The order matters:

• SAFETY-NET (Radar, first — green before you refactor) — refactoring is safe only under a passing suite; the tests are what prove behavior is preserved. Confirm the code under refactor has green coverage; if it's untested, add characterization tests that pin current behavior FIRST. You cannot preserve behavior you never captured. (This is the Fowler precondition the default Zen → Radar order inverts.) Skip only for tool-assisted pure rename/extract where the compiler/type-system guarantees equivalence.
• SCOPE-GUARD — confirm this is internal-only: no public API / signature / output-contract change. If external behavior must change, it is a feature or bug, not a refactor — redirect. Keeps the invariant honest.
• REFACTOR (Zen) — rename / extract / constant-ify / dead-code removal in small reversible steps. +Atlas when module boundaries move, +Grove/+Grove[llm] for structure, +Sherpa for multi-file.
• VERIFY-EQUIVALENCE (Radar + gate) — re-run the SAME suite: identical pass results (no behavior delta), build/lint green, public surface unchanged. Not just "tests pass" — the same tests pass the same way. A refactor that changes a test's expected value is a behavior change masquerading as a refactor.
• SHIP (Guardian) — behavior-neutral PR/commit, reviewable as a pure refactor, kept separate from any behavior-changing work.

Anti-patterns prevented (prevents: refactoring untested code with no behavior proof → SAFETY-NET green-first, "refactor" that changes external behavior → SCOPE-GUARD, silent behavior drift → VERIFY-EQUIVALENCE, behavior change mixed into an unreviewable commit → SHIP behavior-neutral)

OPTIMIZE Phase Contract

Performance work has one law — measure, don't guess — and the default Bolt/Tuner → Radar chain skips the measurement entirely.

Deep contract → reference/optimize-recipe.md (layer taxonomy → tool binding, Profile-Validity gate incl. the Amdahl share, Speedup Report schema, checkpoint-resume, handoffs). Phase order:

DEFECT-CHECK → LOCATE → MEASURE → PROFILE-VALIDITY → TARGET-GATE → OPTIMIZE → VERIFY → [ITERATE] → SHIP

Full phase-by-phase detail, Add-ons, and Boundary → reference/optimize-recipe.md §3 / §13 / §10.

Anti-patterns prevented (prevents: MEASURE-FIRST, DEFECT-CHECK redirect, TARGET-GATE+ITERATE cap, VERIFY prove-with-number, VERIFY prod-representative, VERIFY cold-path/invalidation — full list reference/optimize-recipe.md §9)

Sherpa Skip Conditions

Skip Sherpa from the default chain only when ALL apply:

• Task touches ≤ 2 files
• No implicit intermediate steps
• Single atomic operation completable in one focused step

Chain Adjustment Rules

• 3+ files touched → add Sherpa (if not already in chain).
• Ambiguous or multi-step requirements → add Sherpa.
• 3+ test failures → add Sherpa for re-decomposition.
• Security-sensitive changes → add Sentinel or Probe.
• UI changes → add Muse or Palette.
• Slow database path → add Tuner.
• 2+ independent implementation tracks → consider Rally.
• <10 changed lines with existing tests → Radar may be skipped.
• Pure documentation work → skip Radar and Sentinel unless the change affects executable behavior.

Clarification and Decision Rules

Canonical: SKILL.md § Routing Quick Start (unclear context → inspect git state + .agents/PROJECT.md → one focused question) and § Safety Contract (auto-decision reversibility rule; the Ask First confirm triggers).

Chain Design Rejection Rules

Reject a proposed expansion before execution when any row applies. These are structural gates, not advisory anti-pattern labels.