auto

# Smart Router (/octo:auto)

Single entry point for all Claude Octopus workflows. Analyzes your natural language request and routes to the optimal workflow automatically.

```
/octo:auto research OAuth authentication patterns
/octo:auto debug the failing test in auth.ts
/octo:auto should we use Redis or Memcached?
/octo:auto write tests for the payment module
/octo:auto create a complete e-commerce platform
```

All `/octo:*` commands also work directly, bypassing the router.

---

## EXECUTION CONTRACT (Mandatory)

When the user invokes `/octo:auto <query>` or says `octo <query>`, you MUST follow these steps in order:

### STEP 1: Input Validation

If the query exceeds 500 characters, use only the first 500 characters for intent analysis. Pass the full original query to the target workflow.

### STEP 2: Meta Command Check

If the query matches any of: `help`, `list`, `commands`, `what can you do`, `capabilities`, `options`, `workflows`:
- Display the **Complete Workflow Menu** (see STEP 5c) and STOP. Do not route.

### STEP 3: Analyze Intent

Match the query against keywords below. Check categories **in priority order** — higher priority wins when intents conflict.

#### Priority 1 — Specialized Workflows (check first, highest specificity)

| Intent | Trigger Keywords | Routes To |
|--------|-----------------|-----------|
| Lifecycle | end-to-end, complete lifecycle, full workflow, entire project, whole system | `octo:embrace` |
| Multi-LLM | multi, multi-llm, multi-provider, all providers, force multi, cross-model | `octo:multi` |
| Parallel | parallel, team of teams, decompose, work packages, split into | `octo:parallel` |
| Specification | spec, nlspec, specification, requirements doc, define scope, write spec | `octo:spec` |
| Security | security audit, OWASP, vulnerability, pentest, threat model, CVE, attack surface | `octo:security` |
| TDD | TDD, test-driven, write tests, test first, unit test, test coverage | `octo:tdd` |
| Debug | debug, fix bug, troubleshoot, broken, error trace, stacktrace, failing, crash | `octo:debug` |
| Design | UI design, UX design, wireframe, mockup, design system, layout, prototype | `octo:design-ui-ux` |
| PRD | PRD, product requirements, product spec, feature requirements | `octo:prd` |
| Brainstorm | brainstorm, ideate, ideas, creative, thought experiment, what if | `octo:brainstorm` |
| Deck | presentation, slides, deck, pitch deck, slide deck | `octo:deck` |
| Docs | document, documentation, README, API docs, write docs, docstring | `octo:docs` |

#### Priority 2 — Core Workflows

| Intent | Trigger Keywords | Routes To |
|--------|-----------------|-----------|
| Research | research, investigate, explore, study, understand patterns, analyze ecosystem | `octo:discover` |
| Review | validate, review code, check quality, audit code, inspect, verify, code review | `octo:review` |
| Debate | should we, X vs Y, compare, versus, decide between, which is better, trade-off | `octo:debate` |

#### Priority 3 — Build Workflows (broadest keywords, check last)

| Intent | Trigger Keywords | Routes To |
|--------|-----------------|-----------|
| Build (Clear) | build X, create X, implement X, develop X — where X is a specific target noun | `octo:develop` |
| Build (Vague) | build, create, make — without a clear target noun | `octo:plan` |
| Quick | quick, just do it, simple, fast, straightforward | `octo:quick` |

**Priority resolution:** When keywords from multiple intents match, the highest-priority intent wins. Example: "analyze the security of our API" matches both Research ("analyze") and Security ("security") — Security wins because Priority 1 > Priority 2.

### STEP 4: Determine Confidence

Apply this decision tree (NOT percentage-based scoring):

```
Single intent matched + specific target noun present
  → HIGH confidence

Single intent matched + target is vague or absent
  → MEDIUM confidence

Multiple intents matched + resolved by priority ordering
  → HIGH confidence (route to the higher-priority intent)

Multiple intents matched at same priority level
  → MEDIUM confidence (present top 2 candidates)

No explicit intent + query asks between two named technologies/options (`X or Y`, `X vs Y`, two code-formatted names)
  → MEDIUM confidence debate candidate (`octo:debate`)

No explicit intent + substantial what/how/why/which question (40+ characters)
  → MEDIUM confidence research candidate (`octo:discover`)

No intent keywords matched
  → LOW confidence
```

### STEP 5: Route Based on Confidence

Before loading any route, validate it against this closed allowlist: `embrace`,
`multi`, `parallel`, `spec`, `security`, `tdd`, `debug`, `design-ui-ux`, `prd`,
`brainstorm`, `deck`, `docs`, `discover`, `review`, `debate`, `develop`, `plan`, `quick`.
The token is control data, never user input: do not derive it from the query or
accept a user-supplied path. Reject `..`, `/`, `\\`, or non-allowlisted values;
then load exactly `${HOME}/.claude-octopus/plugin/commands/<validated-token>.md`.
The full query is passed only as workflow arguments.

**STEP 5a — HIGH confidence (auto-route):**

Display:
```
Routing to [Workflow Name] (/octo:[command])
```

Then display the visual indicator banner (STEP 6), read the entire validated
command file, and treat its body as the active instructions in this same
conversation: follow its workflow in order and supply the full query as its
arguments. Do not use the Skill tool; Octopus components are hidden from model
invocation by design.
```
Read: ${HOME}/.claude-octopus/plugin/commands/<validated-token>.md
Arguments: <full user query>
```

**STEP 5b — MEDIUM confidence (confirm first):**

Display:
```
I detected [intent]. Route to:
  [Primary] (/octo:[command]) — [one-line description]
  [Alternative] (/octo:[command]) — [one-line description]

Which would you prefer, or rephrase your request?
```

Wait for user confirmation before loading the selected command file.

**STEP 5c — LOW confidence (show complete menu):**

Display: