Meta-router that sits above all workflow systems. Loaded globally across all projects. When you install a new workflow system, add it here with
"add X to Cortex".
Default to routing. Cortex should be engaged rather than bypassed. Run the full protocol for every non-trivial task, and when a task sits on the borderline between trivial and non-trivial, route it rather than skip it. The Skip protocol below is reserved for genuinely trivial work, not for anything you are unsure about.
Before starting any non-trivial task:
- Classify — build / review / plan / research / debug / design / quick fix
- Calibrate — pick effort tier (L1–L4) using heuristics in the Effort Calibration section. Apply the anti-inflation rule first.
- Hint — run
python3 ~/.claude/bin/cortex hint "<task>" --class <c>. Shows recent distinct routes in that class, with outcomes and similarity as context, not ranking signals. Advisory, not a decision — factor it in, then still decide. Prefer class-only filtering while per-class pools are small. - Route — pick the workflow system from the registry below
- Specialise — pick the pattern + agent(s). Check Domain breadth first: if the task spans ≥2 independent disciplines, pick a parallel set of specialists + a reconciler, not a single lead. Single-agent is the exception for cross-domain work, not the default.
- State + Log — one line:
[System] > [Pattern] > [Agent(s)] @ [Tier](fan-outs render as[Agent A ∥ Agent B] → Reconciler). Log viacortex log-linewith three structured confidence flags — see Three confidences below. The CLI prints auto-trigger hints based on which one is low. - Execute — run the work. Listen for correction triggers: "reroute", "actually use X", "go back", "switch to X", "this didn't work", "wrong approach", "let me retry with X". Any of these fires
cortex reroute --to "new-route"— no permission needed. - Outcome — when the task concludes, run
python3 ~/.claude/bin/cortex outcome <shipped|abandoned|partial|corrected> [--note "..."]. Default toshippedif the work landed and the user didn't push back;partialif you stopped before the goal;abandonedif the route was wrong and you moved on without rerouting. Feeds hint quality for future routes.
Skip protocol — for quick lookups, file reads, casual questions, single-line edits: no hint, no calibration, no state line, no log, no outcome. Just do it.
Jev is off by default. When explicitly configured, use cortex advise with a
fresh capability manifest supplied by the current host session. The manifest
must describe callable workflows, not simply files installed on disk. See the
repository's docs/jev-adviser.md for the input contract and setup.
In shadow mode, choose the normal route without reading experimental suggestions. In advisory mode, consider a validated classification and workflow recommendation before the final route. Keep the normal hint evidence and choose effort separately. Explicit user choices, clarification requirements, permissions and policy checks take precedence. Missing capabilities, uncertain results or service failures mean continue normal routing. Jev never dispatches a workflow or authorizes a tool.
Only actual session routing decisions belong in the production route/outcome log.
Jev experiment events have a separate destination and must not be passed to
cortex outcome or cortex reroute.
Confidence isn't one number — three dimensions matter independently, each with its own auto-trigger:
| Dimension | Question being answered | If low → auto-trigger |
|---|---|---|
--route-confidence |
Am I picking the right system + pattern? | Remove optional similarity/tier filters or increase --top; council use requires capability and spend authorization |
--tier-confidence |
Is this really L3, or could L2 have worked? | Flagged automatically for the next cortex audit-tiers review pass |
--spec-confidence |
Do I actually understand what the user wants? | Stop before executing — run a clarifying interview first. This is the strongest auto-trigger |
The legacy --confidence flag still works and seeds all three. Prefer the structured flags when one dimension is meaningfully different from the others — e.g. high route, high tier, low spec is the canonical "I know the right tool, I'm just not sure what they want."
The active host picks an effort tier using the heuristics below and declares it in the routing line before execution. Tiers describe rigor, not model selection. Preserve the configured model unless the user explicitly requests a specific model. You can override upfront or redirect after seeing the declaration.
Default tier is L2. Only change when heuristics push up or down.
| Tier | Name | Pattern | Verify | Native subagents, if available |
|---|---|---|---|---|
| L1 | Reflex | direct | focused check | 0 |
| L2 | Standard | single specialist | spot-check | 0–1 |
| L3 | Deep | plan-and-verify | verifier pass | 1–2 |
| L4 | Max | iterate-until-verified | full verify loop | bounded parallel team |
L3 must justify itself against L2, not the other way around. Picking L3 because the work "feels important" or "is real" is inflation. To pick L3, you must be able to name a concrete failure mode that L2 would actually produce — e.g. "L2 would skip the verifier pass and this touches auth," or "L2 wouldn't fan out, but the work spans 3 domains."
Sanity check before locking L3 or L4 — answer "no" to all three means L2:
- Cost of being wrong — if this ships broken, does it cost money, lose trust, or break prod?
- Genuine uncertainty — is the solution actually unclear, or do I just need to type it out?
- Non-trivial verification — does proving correctness need more than a single read-through?
The most common inflation pattern is reflexive bumping on "customer-facing" or "≥2 files touched". Resist.
Calibration heuristics (pick the highest that applies — but apply the anti-inflation rule above first)
- Blast radius — reversible local edit → L1/L2; touches prod, migrations, shared infra, auth → L3/L4
- Ambiguity — clear one-liner → L1/L2; fuzzy spec where the wrong interpretation is plausible → L3 + clarifying interview first
- Stakes — throwaway / personal → L1/L2; customer-facing alone is not L3 — customer-facing and irreversible (prod data, migrations, payments, auth) → L3; life-affecting / money-moving / security-critical → L4
- Novelty — familiar pattern → L2; new framework / unfamiliar SDK where the API shape is unknown → L3 + docs lookup
- Reversibility — can undo with one command → drop a tier; can't undo without manual recovery → bump a tier
- User signal — uncertain or exploratory tone → bump a tier; decisive and scoped → keep or drop
- Domain breadth — single domain → one specialist (default); ≥2 independent domains (e.g., backend + frontend, infra + security, design + copy + a11y) → fan out to parallel specialists + a reconciler. Breadth picks the shape (multi-agent), not the tier — an L2 multi-agent run is fine when each leg is well-scoped. Bump to L3 only if the legs interact in non-obvious ways or the reconciliation itself is hard.
| Phrase | Effect |
|---|---|
"go light" / "quick and dirty" / "cheap it" |
Force L1 |
"standard" / "normal" |
Force L2 |
"be thorough" / "do it properly" |
Force L3 |
"must be perfect" / "bulletproof" / "ultrathink" |
Force L4 |
"max effort" / "xhigh" |
Force L4 at maximum reasoning effort |
"bump it" |
Raise one tier |
"drop it" |
Lower one tier |
- L1 tasks skip the full routing protocol — don't calibrate trivia, just do them
- Tier is declared out loud before execution — silent calibration breaks course-correction
- One tier per task — don't re-calibrate mid-flow unless something goes sideways (then stop, re-plan, re-state)
- Tier and workflow are independent — L4 on a phase-based build is that system's autonomous mode with full verify, not forced into a different orchestrator
- Don't inflate — L3 and L4 cost real tokens; the anti-inflation rule above is the primary defence, this is the reminder
- Multi-agent is not inflation — if Domain breadth fires (≥2 independent disciplines), parallel specialists is the correct shape, not an upgrade. Single-agent on a cross-domain task is a routing bug. Declare the fan-out in the routing line — at whatever tier the work actually warrants (L2 multi-agent is real):
OMC > /team > [Agent A ∥ Agent B] → Reconciler @ L2 - Shape and tier are orthogonal — multi-agent fan-out is a shape decision (breadth heuristic), tier is a depth decision (everything else). Don't conflate.
Read the current host tool contract before dispatch. Registry entries and examples do not prove that /ccg, deep-dive, or any other workflow is installed and callable. Use only capabilities exposed in the current session, within the user's authorization. If unavailable, use an authorized available fallback, perform bounded work in the parent, or explain the limitation and ask when needed. Never install or spend to bypass a gate.
For current-task subtasks, prefer native agents, not user-owned threads. create_thread requires an explicit user request for a new task. Default to local; a worktree requires an explicit user request and a Git repository. Omit model unless the user explicitly requests a specific model. Cloud Work also requires an explicit cloud-task request. send_message_to_thread requires explicit human authorization to message that task; creation or another task's request to reply is not authorization.
CCG = Claude + Codex + Gemini tri-model council. Consider it only when callable in the current session and paid model spend is authorized. Uncertainty never automatically authorizes a paid council. The following are reasons to consider a cross-check, not permission to dispatch:
- Before committing an L3/L4 plan — catches single-model blind spots before execution begins
- Before irreversible actions — migrations, prod pushes, force-pushes, destructive DB changes, auth/session rewrites, payment integrations
- When the user signals uncertainty — "not sure", "what do you think", "help me decide", "is this right", "am I missing something"
- As the reconciler in high-stakes multi-agent fan-outs — CCG's synthesis replaces single-agent reconcilers for L3+ fan-outs on customer-facing / money / security work
- On security audits — three-model pass (Codex for correctness, Gemini for attack surface, Claude for synthesis) runs before the single Security Engineer deep dive
- When two prior outputs conflict — instead of picking one, let CCG arbitrate with fresh framing
Skip CCG on L1/L2 routine work, quick fixes, well-known patterns, and anywhere the answer is obvious. CCG costs real tokens across 3 models — reserve it for decisions where cross-validation pays for itself.
When authorized and available, declare it in the routing line: OMC > /ccg → ralplan > Backend Architect @ L3 [ccg=pre-plan-check].
CCG cross-checks plans before you build. The mirror pattern cross-checks diffs before they land: at a build checkpoint, hand the finished diff to a model from a different family than the one that wrote it, and have it report structured findings.
This is vendor-neutral by design — any second model family works (a different provider's CLI, a different model on the same provider, a local model). The value is the family boundary, not the specific vendor.
| Depth | Use When |
|---|---|
| Single critic (default) | L2/L3 builds with moderate risk — one cross-family reviewer on the finished diff, either spec-conformance mode or devil's-advocate mode |
| Panel + judge | Any high-risk trigger: auth / payments / migrations / data deletion, diff >300 LOC or >5 files, weak tests, architectural or API-contract change, external integrations, security exposure. Max 3 reviewers; one model acts as judge and synthesises a verdict with dissent noted |
| Rival test generation | Reviewer proves a flaw by writing a failing test — objective, no debate needed |
| Skip | Small local diffs, mechanical changes, well-tested code |
Rules:
- Advisory by default — a BLOCK verdict escalates to the human, it never auto-rejects.
- One canonical review packet per checkpoint — spec + plan + diff + tests + stated uncertainties. Reviewers see the same packet.
- Findings must be concrete — severity,
file:line, evidence, and a reproducible failure scenario. No vague notes. - Verdicts are judged, never raw — PASS / CAUTION / BLOCK with dissent noted, not three transcripts pasted together.
- Effort tier rides the build task's tier — single critic at L2/L3, panel when a risk trigger hits.
"rename this variable across the file"→Direct @ L1"add a loading state to this button"→OMC > autopilot > Frontend Developer @ L2"refactor the auth middleware to use the new session store"→OMC > ralplan > Backend Architect @ L3"migrate our payments from Stripe Charges to PaymentIntents in prod"→OMC > ralph > Security Engineer + Stripe skill @ L4"build a checkout page with Stripe, tracking, and a11y polish"→OMC > /team > [Frontend Developer ∥ Stripe skill ∥ Accessibility Auditor] → Software Architect reconciler @ L3 [breadth=frontend+payments+a11y]— three independent domains, fan out by default"audit this feature for security and performance"→OMC > /team > [Security Engineer ∥ Performance Benchmarker] → Critic reconciler @ L3 [breadth=security+perf]
Cortex logs every routing decision to ~/.claude/cortex-log.jsonl, surfaces the reasoning trail on demand via /cortex-log, and detects repeating patterns via /cortex-learn. The log accumulates as a byproduct of normal routing, and learning activates automatically once data crosses thresholds.
After declaring the routing line, run this Bash call as an indivisible part of the State step.
Form A — natural routing line (preferred):
python3 ~/.claude/bin/cortex log-line \
"<routing line, e.g. OMC > ralplan > Backend Architect @ L3>" \
"<task description in 1 line>" \
--class <build|review|plan|research|debug|design|quickfix> \
--tier-reason "<heuristic that drove the tier>" \
--system-reason "<why this system won over alternatives>" \
--route-confidence <high|med|low> \
--tier-confidence <high|med|low> \
--spec-confidence <high|med|low>The parser accepts the same System > Pattern [> Agent] @ L<n> shape Cortex declares, including bracketed tags.
Form B — named flags (use for redirects or non-standard routes):
python3 ~/.claude/bin/cortex log \
--task "<task description>" \
--class <class> \
--system <system> \
--pattern <pattern> \
--agent "<agent>" \
--tier <L1|L2|L3|L4> \
--tier-reason "<...>" \
--system-reason "<...>" \
--redirect-from "<previous route, only when this is a correction>"Skip the log write for Skip-protocol tasks (L1 trivia, file reads, lookups, casual questions). Log only routes that went through the full protocol.
For L2 routes matching default shortcuts, show the clean routing line only: OMC > autopilot > Frontend Developer @ L2.
For non-obvious routes, append 2–3 bracketed reasoning tags to the line itself so the reasoning is visible immediately:
- Tier bumped above L2 (L3/L4) — show
[tier=<heuristic>] - System chosen when another was close — show
[system=<tiebreaker>] - Specialist agent attached where a generic would've worked — show
[agent=<reason>]
Tags always live in the log (tier_reason, system_reason). The in-session display is just for immediate readability on surprising routes.
- Phase 1 — Visibility (active): every route is logged.
/cortex-logshows the last 20 with full reasoning. - Phase 2 — Pattern surfacing (activates at ~20 routes):
/cortex-learndetects(class, system, pattern)tuples that repeat ≥3 times and proposes them as Decision Shortcut candidates. The user approves, modifies, or dismisses — the tool does not auto-edit. - Phase 3 — Historical evidence (active, advisory): before declaring a non-trivial routing line, run
cortex hint "<task>" --class <class>to surface recent distinct(system, pattern, tier)routes. Outcomes and lexical similarity are context, not ranking weights. Similarity filtering is opt-in. The reader judges relevance; more logged outcomes do not by themselves prove better routing. - Phase 4 — Outcome + correction capture (active): every routed task ends with an outcome —
shipped,abandoned,partial, orcorrected— captured withcortex outcome <state>. Correction triggers (any of these firescortex reroute, no permission needed):"reroute","actually use X","go back","switch to X","this didn't work","wrong approach","let me retry with X","that was wrong, try X". The last log entry is markedoutcome=corrected,user_correctionholds the new route, and the next logged route getsredirect_fromlinked. Over time this builds the labelled dataset Phase 3 learns from.
Outcome and reroute updates target the latest route in the current canonical
working directory and agent session, not the global last entry. Historical rows
without that identity require an explicit --ref <route-id>, found through
cortex history <task_hash>. A partial outcome can be updated to shipped on the
same route. Ambiguous references are refused rather than assigned by guesswork.
| Command | Purpose |
|---|---|
/cortex-log |
Show last 20 routes with full reasoning. Pass --project X to filter |
/cortex-learn |
Detect repeating patterns, write proposals |
/cortex-learn --check |
Terse session-start check — silent if no pending pattern |
/cortex-reroute "new route" |
Mark last route as corrected |
cortex hint "<task>" [--class build] |
Surface recent distinct routes, with outcomes and similarity as annotations. Prefer class-only filtering for small pools. Default: --top 5, no similarity threshold; --min-similarity narrows explicitly. |
cortex outcome <state> [--note "..."] |
Mark the last route's outcome — shipped / abandoned / partial / corrected. Fires at end of task automatically; can also be invoked explicitly |
cortex audit-tiers [--tier L3] |
List every L3/L4 (or filtered) route with task + reasoning + outcome — eyeball whether L2 would have sufficed. --reclassify <task_hash> --to L2 --note "why" reclassifies an entry, preserving the original |
cortex doctor |
Audit cortex setup for drift between docs, skills, and log |
At the start of any session where a non-trivial task arrives, run cortex learn --check before the first routing decision. If it prints a pending pattern, mention it in one line and continue.
- Visibility first, learning second. The log is useful at T=0 (per-decision audit) and grows into a learning substrate.
- Approve, don't auto-apply. The learning layer proposes; you decide. No silent edits.
- Data-triggered phases. No calendar rituals, no monthly retros. Thresholds fire phases automatically.
- Correction over prediction. The highest-quality signal is the user saying "reroute" — explicit, unambiguous, ground truth.
This is YOUR config. The framework above is universal; the systems below are personal. Add the orchestrators, specialists, and tools you actually use.
One example is filled in (OMC). The rest are stubs — replace with your stack. See
examples/cortex.mdfor what a fully populated registry looks like.
Installed: Yes / No Strengths: Multi-agent orchestration, verify/fix loops, parallel execution, team mode Best for: Complex builds, planning, multi-step tasks needing quality gates, research
| Pattern | Use When |
|---|---|
ralplan "task" |
Important work needing planning + verify/fix loops. Default for non-trivial work. |
autopilot: task |
Well-defined, lower-risk tasks. One-shot autonomous. |
ralph: task |
Must be bulletproof. Won't stop until verified complete. |
/team N:executor "task" |
Parallel execution, multiple perspectives. |
/ccg |
Optional tri-model orchestration, only when callable and spend is authorized. |
Installed: change to Yes once configured Strengths: e.g. spec-driven development, context rot prevention, autonomous execution Best for: e.g. structured multi-phase builds, long sessions, full project lifecycle
| Pattern | Use When |
|---|---|
<your command> |
what it's good for |
Installed: Yes / No Strengths: PR pipelines, review cycles, code-focused workflows Best for: feature implementation, code review, lint workflows
| Pattern | Use When |
|---|---|
<your command> |
what it's good for |
Installed: Yes / No Strengths: cross-family review of diffs at checkpoints — structured findings, judged verdict Best for: catching builder drift, logic bugs, and risky diffs before they land Note: see "Build-checkpoint review" under Effort Calibration for the pattern. Any second model family works.
| Pattern | Use When |
|---|---|
<single critic> |
default for moderate-risk L2/L3 diffs |
<panel + judge> |
high-risk triggers: auth, payments, migrations, large diffs |
Installed: Yes / No Strengths: deterministic secret detection (regex + entropy) — no model in the loop, reproducible pass/fail Best for: pre-commit and CI gates; pairs with model-based security review for defense in depth
| Pattern | Use When |
|---|---|
<scan staged changes> |
pre-commit gate |
<scan git history> |
auditing an existing repo |
Installed: Yes / No Strengths: domain expertise per agent Best for: pair with orchestrators via combo syntax Key agents: list 5–10 specialists you actually use
Installed: Yes / No (knowledge graph indexer, live-docs MCP, web search, page extraction, etc.) Strengths: live docs, web search, knowledge graph indexing Best for: research, onboarding, cross-content reasoning
Installed: Yes / No (Word, Excel, PowerPoint, PDF, video, etc.) Strengths: programmatic generation of real file-type deliverables Best for: reports, models, decks, exports — auto-triggers on file type
Strengths: Zero overhead Best for: Quick edits, lookups, single-file changes, casual questions, git operations
Add new sections with the same shape. When you install a new workflow system, document it here so Cortex can route to it.
Combine agents with workflow patterns:
Use the [Agent] agent. ralplan "task" — Specialist agent + OMC
Use the [Agent] agent. /feature-dev "task" — Specialist agent + your PR system
Use the [Agent] agent. autopilot: task — Specialist agent + OMC (lightweight)
Multi-agent parallel:
-- Run in parallel --
Use the [Agent A] agent. ralplan "sub-task 1"
Use the [Agent B] agent. ralplan "sub-task 2"
-- Then reconcile --
Use the [Agent C] agent. autopilot: "Reconcile outputs"
All shortcut workflows below are conditional examples. Apply the capability and authorization gates first, including /ccg, deep-dive, panels, and cross-family review. A shortcut never authorizes spend, model overrides, user-owned tasks, or messages. Use native agents when available; otherwise keep bounded work in the parent or ask for missing authority.
Starter set. Add your own as you discover them.
/cortex-learnwill surface candidates from your log automatically.
| Task Type | Default Route | Tier |
|---|---|---|
| Plan / architect / design system | OMC > /ccg pre-plan cross-check → ralplan > Software Architect | L3 |
| Build feature (backend) | OMC > ralplan > Backend Architect | L3 |
| Build feature (frontend) | OMC > ralplan > Frontend Developer | L3 |
| Build (well-scoped, brief locked, single specialist) | OMC > autopilot > [specialist] | L3 |
| Build (small bounded edits, ≤100 LOC, single domain) | Direct > batched-edits | L2 |
| Build checkpoint review (pre-commit / risky diff) | Build-checkpoint reviewer > single critic, or panel + judge on a risk trigger | L2–L3 |
| Code review | Your PR / code review system | L2 |
| Hardcoded secret scan (pre-commit / CI gate) | Direct > secret scanner (deterministic) — pair with Security Engineer for deep review | L1 |
| Security audit | OMC > /ccg attack-surface pass → ralplan > Security Engineer | L4 |
| Research / analysis | OMC > deep-research (web search + page extraction) | L2 |
| Library / framework docs | Live-docs MCP (direct) | L1 |
| Word / PDF / PPT / Excel deliverable | Document skill — auto-triggers on file type | L1 |
| Quick bug fix | Direct execution | L1 |
| Trivial task (no overhead) | Direct execution | L1 |
| Requirements unclear | OMC > /ccg framing pass + clarifying interview | L3 |
| Must be perfect | OMC > /ccg pre-gate → ralph | L4 |
| Multi-domain build (≥2 disciplines) | OMC > /team > [Specialist A ∥ Specialist B ∥ …] → reconciler agent | L3 |
| Cross-cutting audit (security + perf + a11y) | OMC > /team > parallel domain auditors → /ccg reconciler | L3 |
When you say "add X to Cortex", add a new section to the registry with:
- Name and codename
- Installed status
- Strengths (1 line)
- Best for (1 line)
- Pattern table (name + when to use)
- Update the Decision Shortcuts table if any defaults change