wyattowalsh/agents | AI Agent Configs
Docs
reasoning-router

reasoning-router

Classify problems and route to optimal thinking MCP (11 available). Monitor confidence, re-route on stall. Use for complex reasoning.

reasoning-router1539 wordsMITv0.1.0Repo-owned

reasoning-router

Classify problems and route to optimal thinking MCP (11 available). Monitor confidence, re-route on stall. Use for complex reasoning.

Quick Start

Install:

npx skills add github:wyattowalsh/agents --skill reasoning-router -y -g --agent antigravity --agent claude-code --agent codex --agent crush --agent cursor --agent gemini-cli --agent github-copilot --agent grok --agent opencode

Use: /reasoning-router [problem or question]

Works with Claude Code, Gemini CLI, OpenCode, and other agentskills.io-compatible agents.

What It Does

Section titled “What It Does”

Meta-reasoning layer: classify problems, dispatch to the optimal thinking MCP, monitor progress, re-route on stall. Minimize total tokens to a high-confidence conclusion.

Modes

Section titled “Modes”
$ARGUMENTSAction
Problem or question textRoute — classify and dispatch to optimal thinking method
compare <problem>Compare — run 2-3 strategies on the same problem, pick best
statusStatus — show current thinking session state
switch <method>Switch — re-route to specified method mid-session
recapRecap — summarize reasoning so far across all methods used
methodsMethods — show available methods with when-to-use cheatsheet
EmptyGuide — show routing cheatsheet and token tier table

Critical Rules

Section titled “Critical Rules”
  1. Always use the most advanced model — model: opus. Never downgrade.
  2. Minimize total tokens to conclusion — pick the lightest method that handles the problem. Escalate only on evidence of stall.
  3. Present routing decision before invoking — 1 line: method, why, fallback.
  4. Never invoke without classification — even if user names a method, validate fit.
  5. Carry forward on re-route — summarize findings ≤100 words, don’t restart.
  6. Simple gets simple — Tier 1 for simple problems, always. No exceptions.
  7. Token cost breaks ties — equal fit → lower tier wins.
  8. Start minimal, expand on evidence — lowest totalThoughts, expand only when the tool requests more or stall detected.
  9. One method at a time — no simultaneous thinking MCPs. Composition is sequential.
  10. Router ≠ thinker — classify, dispatch, monitor. Don’t duplicate reasoning.
  11. Respect tool workflows — creative-thinking: discover→plan→execute. lotus-wisdom: start with tag: begin. aot: use atomcommands for control.
  12. Track token spend — note approximate tokens per session to refine routing.

Classification

Section titled “Classification”

Run !uv run python scripts/problem-classifier.py "$ARGUMENTS" for deterministic pre-scan, then refine with LLM judgment.

Axis 1 — Structure (what shape is the reasoning?)

Section titled “Axis 1 — Structure (what shape is the reasoning?)”
StructureSignalsPrimary Method
Decomposable”break down”, multi-hop, sub-questionsatom-of-thoughts
Sequential”step by step”, ordered process, debuggingsequential-thinking
Branching”explore options”, “what if”, alternativescascade-thinking
Constrained”given that”, requirements, formal specsshannon-thinking
Interconnecteddependencies, circular, complex systematom-of-thoughts (full)
Creative”brainstorm”, “novel”, “stuck”, “reframe”creative-thinking
Contradictoryparadox, “both true”, tension, dilemmalotus-wisdom
Investigative”why did”, root cause, debug, diagnosecrash

Axis 2 — Complexity (how deep?)

Section titled “Axis 2 — Complexity (how deep?)”
ComplexitySignalsDepth Control
Simple (1-3 steps)Short input, single concept, “quick”Tier 1 ONLY: aot-light or sequential
Moderate (4-8 steps)Multiple factors, some uncertaintyDefault depth, structure-matched method
Complex (9+ steps)Cross-domain, high uncertaintyFull depth, extended steps
Wicked (open-ended)No clear solution, values conflictComposition patterns allowed

Axis 3 — Domain (what kind?)

Section titled “Axis 3 — Domain (what kind?)”
DomainMethodWhy
Engineering/architectureshannon-thinkingConstraints → model → proof
DebuggingcrashTool-aware investigation
Researchcascade-thinkingParallel perspectives
Math/logicatom-of-thoughtsDependency DAG
Strategythink-strategiesStrategy comparison
Creative/designcreative-thinkingLateral techniques
Philosophy/ethicslotus-wisdomNon-dual integration
Planningsequential-thinkingLinear progression
Pattern trackingstructured-thinkingPersistent memory

Routing Algorithm

Section titled “Routing Algorithm”

Optimize for minimum total tokens to reach a high-confidence conclusion.

1. Run problem-classifier.py for deterministic signals
2. Score each axis (structure × complexity × domain)
3. Apply efficiency gate:
   - Simple: ALWAYS Tier 1 (aot-light or sequential-thinking)
   - Moderate: structure-matched method at default depth
   - Complex: full method with extended depth
   - Wicked: composition patterns allowed
4. Resolve conflicts:
   - Structure > domain (HOW > WHAT)
   - Complexity modulates depth AND tier
   - Ties: ALWAYS prefer lower token cost
5. Select primary + fallback
6. Present: "Using [method] — [why]. Fallback: [method]." (1 line)
7. Invoke with minimum viable totalThoughts
8. Monitor for stalls — escalate only on evidence

Token Cost Tiers

Section titled “Token Cost Tiers”
Tier 1 (lightest): aot-light, sequential-thinking
Tier 2 (moderate): structured-thinking, cascade-thinking, crash
Tier 3 (heavy):    shannon-thinking, atom-of-thoughts (full), think-strategies
Tier 4 (heaviest): creative-thinking, deep-lucid-3d, lotus-wisdom

Efficiency Rules

Section titled “Efficiency Rules”
  • Never Tier 3-4 for a problem Tier 1-2 can handle
  • Start with lowest viable totalThoughts; expand only on needsMoreThoughts
  • cascade-thinking: start 2 branches max; add only if coverage insufficient
  • creative-thinking: use timeframe: "quick" unless wicked
  • think-strategies: start with linear or chain_of_thought before heavier strategies

Stall Detection

Section titled “Stall Detection”

Read references/stall-detection.md when any stall signal fires.

4 stall signals:

  1. Confidence plateau — no increase >0.05 in 3+ steps
  2. Circular reasoning — same claim restated
  3. Step overrun — exceeds 2× initial estimate
  4. User signal — “try something else” or /think switch

Re-routing by block type:

BlockNew MethodWhy
Stuck in depthcascade-thinkingBroaden
Too broadatom-of-thoughtsDecompose
Too formalcreative-thinkingReframe
Too abstractcrashGround in evidence
Contradictionslotus-wisdomIntegrate
Wrong methodReclassifyStart routing over

Hard limits: Max 3 re-routes per session. Max 3× step estimate. No ping-pong (can’t return to a method already re-routed from). After 3 re-routes → recovery protocol: present findings, ask user to guide.

Composition Patterns

Section titled “Composition Patterns”

Read references/composition-patterns.md for full protocols.

PatternSequenceWhen
Sketch→Detailaot-light → aot (full)Quick outline then deep dive
Diverge→Convergecreative-thinking → sequentialGenerate options then evaluate
Explore→Formalizecascade-thinking → shannonSurvey landscape then prove
Decompose→Investigateaot → crash (per atom)Break down then debug each
Analyze→Integratecascade-thinking → lotus-wisdomSurface contradictions then synthesize
Strategize→Planthink-strategies → sequentialStep back then plan forward

Context transfer: At every method transition, produce ≤100 word summary of key findings with confidence scores. Carry claims, drop scaffolding.

When NOT to compose: Simple/moderate complexity, first method is converging, time pressure is high.

Compare Mode

Section titled “Compare Mode”

When invoked with compare <problem>:

  1. Classify the problem normally
  2. Select 2-3 candidate methods (primary + 1-2 plausible alternatives)
  3. Run each for 3-5 steps on the same problem
  4. Compare: which produced higher-confidence findings with fewer tokens?
  5. Present comparison table and recommend the winner
  6. Continue with the winning method if user agrees

Methods Quick Reference

Section titled “Methods Quick Reference”

When invoked with methods or for the routing cheatsheet:

MethodMCP ToolTierSweet Spot
sequential-thinkingsequentialthinking1Linear, ordered reasoning
aot-lightaot-light1Quick atomic sketches
structured-thinkingcapture_thought2Cross-session memory
cascade-thinkingcascade_thinking2Multi-perspective exploration
crashcrash2Debugging with tool integration
shannon-thinkingshannonthinking3Formal proof under constraints
atom-of-thoughtsaot + atomcommands3Deep decomposition with DAG
think-strategiesthink-strategies3Named strategy frameworks
creative-thinkingdiscover_techniques → plan → execute4Lateral thinking (3-step required)
deep-lucid-3danalyze_problem4Holistic UCPF analysis
lotus-wisdomlotuswisdom (start: tag: begin)4Paradox and contradiction

Read references/capability-map.md for full tool parameters and workflows.

Scope Boundaries

Section titled “Scope Boundaries”

In scope: Problem classification, thinking MCP dispatch, stall detection, re-routing, composition pattern selection, method comparison.

Out of scope: Actually performing the reasoning (the thinking MCP does that), running tools or writing code (use appropriate skills), code review (review), research (research), debugging implementation (use crash MCP directly).

Canonical Vocabulary

Section titled “Canonical Vocabulary”
TermMeaning
methodA specific thinking MCP tool (e.g., cascade-thinking)
tierToken cost classification (1=lightest, 4=heaviest)
structureThe shape of reasoning a problem requires
routingSelecting the best method for a classified problem
stallWhen a method stops making progress (confidence plateau, circular reasoning)
re-routeSwitching to a different method mid-session
compositionChaining 2+ methods sequentially for complex problems
efficiency gateOverride that forces Tier 1 methods for simple problems
context transferSummarizing findings when switching between methods
FieldValue
Source Typerepo-owned
Display Sourcegithub:wyattowalsh/agents
Source Kindrepo
Installabilityportable command
Review Statereviewed
Target Agentsantigravity, claude-code, codex, crush, cursor, gemini-cli, github-copilot, grok, opencode
Full SKILL.md
skills/reasoning-router/SKILL.md
---
name: reasoning-router
description: >-
  Classify problems and route to optimal thinking MCP (11 available). Monitor
  confidence, re-route on stall. Use for complex reasoning. NOT for simple
  questions (answer directly) or code review (review).
license: MIT
argument-hint: "[problem or question]"
model: opus
metadata:
  author: wyattowalsh
  version: "0.1.0"
---
# Reasoning Router


Meta-reasoning layer: classify problems, dispatch to the optimal thinking MCP,
monitor progress, re-route on stall. Minimize total tokens to a high-confidence
conclusion.


Always uses the most advanced model (currently Opus 4.6). Meta-reasoning about
*how to think* is the highest-leverage reasoning task.


## Dispatch


| `$ARGUMENTS` | Action |
|---|---|
| Problem or question text | **Route** — classify and dispatch to optimal thinking method |
| `compare <problem>` | **Compare** — run 2-3 strategies on the same problem, pick best |
| `status` | **Status** — show current thinking session state |
| `switch <method>` | **Switch** — re-route to specified method mid-session |
| `recap` | **Recap** — summarize reasoning so far across all methods used |
| `methods` | **Methods** — show available methods with when-to-use cheatsheet |
| Empty | **Guide** — show routing cheatsheet and token tier table |


---


## Classification


Run `!uv run python scripts/problem-classifier.py "$ARGUMENTS"`
for deterministic pre-scan, then refine with LLM judgment.


### Axis 1 — Structure (what shape is the reasoning?)


| Structure | Signals | Primary Method |
|-----------|---------|----------------|
| **Decomposable** | "break down", multi-hop, sub-questions | `atom-of-thoughts` |
| **Sequential** | "step by step", ordered process, debugging | `sequential-thinking` |
| **Branching** | "explore options", "what if", alternatives | `cascade-thinking` |
| **Constrained** | "given that", requirements, formal specs | `shannon-thinking` |
| **Interconnected** | dependencies, circular, complex system | `atom-of-thoughts` (full) |
| **Creative** | "brainstorm", "novel", "stuck", "reframe" | `creative-thinking` |
| **Contradictory** | paradox, "both true", tension, dilemma | `lotus-wisdom` |
| **Investigative** | "why did", root cause, debug, diagnose | `crash` |


### Axis 2 — Complexity (how deep?)


| Complexity | Signals | Depth Control |
|------------|---------|---------------|
| **Simple** (1-3 steps) | Short input, single concept, "quick" | Tier 1 ONLY: `aot-light` or `sequential` |
| **Moderate** (4-8 steps) | Multiple factors, some uncertainty | Default depth, structure-matched method |
| **Complex** (9+ steps) | Cross-domain, high uncertainty | Full depth, extended steps |
| **Wicked** (open-ended) | No clear solution, values conflict | Composition patterns allowed |


### Axis 3 — Domain (what kind?)


| Domain | Method | Why |
|--------|--------|-----|
| **Engineering/architecture** | `shannon-thinking` | Constraints → model → proof |
| **Debugging** | `crash` | Tool-aware investigation |
| **Research** | `cascade-thinking` | Parallel perspectives |
| **Math/logic** | `atom-of-thoughts` | Dependency DAG |
| **Strategy** | `think-strategies` | Strategy comparison |
| **Creative/design** | `creative-thinking` | Lateral techniques |
| **Philosophy/ethics** | `lotus-wisdom` | Non-dual integration |
| **Planning** | `sequential-thinking` | Linear progression |
| **Pattern tracking** | `structured-thinking` | Persistent memory |


---


## Routing Algorithm


Optimize for **minimum total tokens to reach a high-confidence conclusion**.


```
1. Run problem-classifier.py for deterministic signals
2. Score each axis (structure × complexity × domain)
3. Apply efficiency gate:
   - Simple: ALWAYS Tier 1 (aot-light or sequential-thinking)
   - Moderate: structure-matched method at default depth
   - Complex: full method with extended depth
   - Wicked: composition patterns allowed
4. Resolve conflicts:
   - Structure > domain (HOW > WHAT)
   - Complexity modulates depth AND tier
   - Ties: ALWAYS prefer lower token cost
5. Select primary + fallback
6. Present: "Using [method] — [why]. Fallback: [method]." (1 line)
7. Invoke with minimum viable totalThoughts
8. Monitor for stalls — escalate only on evidence
```


### Token Cost Tiers


```
Tier 1 (lightest): aot-light, sequential-thinking
Tier 2 (moderate): structured-thinking, cascade-thinking, crash
Tier 3 (heavy):    shannon-thinking, atom-of-thoughts (full), think-strategies
Tier 4 (heaviest): creative-thinking, deep-lucid-3d, lotus-wisdom
```


### Efficiency Rules


- Never Tier 3-4 for a problem Tier 1-2 can handle
- Start with lowest viable `totalThoughts`; expand only on `needsMoreThoughts`
- `cascade-thinking`: start 2 branches max; add only if coverage insufficient
- `creative-thinking`: use `timeframe: "quick"` unless wicked
- `think-strategies`: start with `linear` or `chain_of_thought` before heavier strategies


---


## Stall Detection


Read `references/stall-detection.md` when any stall signal fires.


**4 stall signals:**
1. **Confidence plateau** — no increase >0.05 in 3+ steps
2. **Circular reasoning** — same claim restated
3. **Step overrun** — exceeds 2× initial estimate
4. **User signal** — "try something else" or `/think switch`


**Re-routing by block type:**


| Block | New Method | Why |
|-------|-----------|-----|
| Stuck in depth | `cascade-thinking` | Broaden |
| Too broad | `atom-of-thoughts` | Decompose |
| Too formal | `creative-thinking` | Reframe |
| Too abstract | `crash` | Ground in evidence |
| Contradictions | `lotus-wisdom` | Integrate |
| Wrong method | Reclassify | Start routing over |


**Hard limits:** Max 3 re-routes per session. Max 3× step estimate. No ping-pong
(can't return to a method already re-routed from). After 3 re-routes → recovery
protocol: present findings, ask user to guide.


---


## Composition Patterns


Read `references/composition-patterns.md` for full protocols.


| Pattern | Sequence | When |
|---------|----------|------|
| **Sketch→Detail** | `aot-light` → `aot` (full) | Quick outline then deep dive |
| **Diverge→Converge** | `creative-thinking` → `sequential` | Generate options then evaluate |
| **Explore→Formalize** | `cascade-thinking` → `shannon` | Survey landscape then prove |
| **Decompose→Investigate** | `aot` → `crash` (per atom) | Break down then debug each |
| **Analyze→Integrate** | `cascade-thinking` → `lotus-wisdom` | Surface contradictions then synthesize |
| **Strategize→Plan** | `think-strategies` → `sequential` | Step back then plan forward |


**Context transfer:** At every method transition, produce ≤100 word summary of key
findings with confidence scores. Carry claims, drop scaffolding.


**When NOT to compose:** Simple/moderate complexity, first method is converging, time
pressure is high.


---


## Compare Mode


When invoked with `compare <problem>`:


1. Classify the problem normally
2. Select 2-3 candidate methods (primary + 1-2 plausible alternatives)
3. Run each for 3-5 steps on the same problem
4. Compare: which produced higher-confidence findings with fewer tokens?
5. Present comparison table and recommend the winner
6. Continue with the winning method if user agrees


---


## Methods Quick Reference


When invoked with `methods` or for the routing cheatsheet:


| Method | MCP Tool | Tier | Sweet Spot |
|--------|----------|------|-----------|
| sequential-thinking | `sequentialthinking` | 1 | Linear, ordered reasoning |
| aot-light | `aot-light` | 1 | Quick atomic sketches |
| structured-thinking | `capture_thought` | 2 | Cross-session memory |
| cascade-thinking | `cascade_thinking` | 2 | Multi-perspective exploration |
| crash | `crash` | 2 | Debugging with tool integration |
| shannon-thinking | `shannonthinking` | 3 | Formal proof under constraints |
| atom-of-thoughts | `aot` + `atomcommands` | 3 | Deep decomposition with DAG |
| think-strategies | `think-strategies` | 3 | Named strategy frameworks |
| creative-thinking | `discover_techniques` → `plan` → `execute` | 4 | Lateral thinking (3-step required) |
| deep-lucid-3d | `analyze_problem` | 4 | Holistic UCPF analysis |
| lotus-wisdom | `lotuswisdom` (start: `tag: begin`) | 4 | Paradox and contradiction |


Read `references/capability-map.md` for full tool parameters and workflows.


---


## Reference File Index


| File | Read When |
|------|-----------|
| `references/capability-map.md` | First invocation or unfamiliar with a tool's parameters |
| `references/routing-matrix.md` | Resolving routing conflicts, ties, or edge cases |
| `references/composition-patterns.md` | Problem needs a multi-tool sequence |
| `references/stall-detection.md` | Stall signal fires or session exceeds expected steps |


Load ONE reference at a time. Do not preload.


---


## Scope Boundaries


**In scope:** Problem classification, thinking MCP dispatch, stall detection,
re-routing, composition pattern selection, method comparison.


**Out of scope:** Actually performing the reasoning (the thinking MCP does that),
running tools or writing code (use appropriate skills), code review (review),
research (research), debugging implementation (use crash MCP directly).


---


## Canonical Vocabulary


| Term | Meaning |
|------|---------|
| method | A specific thinking MCP tool (e.g., cascade-thinking) |
| tier | Token cost classification (1=lightest, 4=heaviest) |
| structure | The shape of reasoning a problem requires |
| routing | Selecting the best method for a classified problem |
| stall | When a method stops making progress (confidence plateau, circular reasoning) |
| re-route | Switching to a different method mid-session |
| composition | Chaining 2+ methods sequentially for complex problems |
| efficiency gate | Override that forces Tier 1 methods for simple problems |
| context transfer | Summarizing findings when switching between methods |


---


## Critical Rules


1. **Always use the most advanced model** — `model: opus`. Never downgrade.
2. **Minimize total tokens to conclusion** — pick the lightest method that handles
   the problem. Escalate only on evidence of stall.
3. **Present routing decision before invoking** — 1 line: method, why, fallback.
4. **Never invoke without classification** — even if user names a method, validate fit.
5. **Carry forward on re-route** — summarize findings ≤100 words, don't restart.
6. **Simple gets simple** — Tier 1 for simple problems, always. No exceptions.
7. **Token cost breaks ties** — equal fit → lower tier wins.
8. **Start minimal, expand on evidence** — lowest `totalThoughts`, expand only when
   the tool requests more or stall detected.
9. **One method at a time** — no simultaneous thinking MCPs. Composition is sequential.
10. **Router ≠ thinker** — classify, dispatch, monitor. Don't duplicate reasoning.
11. **Respect tool workflows** — creative-thinking: discover→plan→execute.
    lotus-wisdom: start with `tag: begin`. aot: use `atomcommands` for control.
12. **Track token spend** — note approximate tokens per session to refine routing.

Download from GitHub

Resources

Section titled “Resources”
Skill CatalogBrowse custom and external skills.
CLI ReferenceInstall and manage skills.
agentskills.ioThe open ecosystem for cross-agent skills.

View source on GitHub

HomeOverviewInstallSurfacesRuntimesReferenceContributing

Surfaces

OverviewInstructionsTools

Reference

OverviewCLIHarness support

Popular Tags

Docs platformPlugin stackView all tags