auto

# /ork:auto — Intent Router

The front door to OrchestKit. **You describe a goal in plain English; the router classifies it and hands off to the right specialist.** One entry point, many execution paths.

> **Why this exists:** OrchestKit has 106 skills, but usage telemetry shows users fire only the handful they can name by memory (10 distinct skills across thousands of sessions). The dominant cause of "dead" skills is **no front door** — not low quality. This router turns "you must know the exact `/ork:<name>`" into "describe what you want."

**Core principle:** routing is a *deterministic workflow*, not an autonomous agent (Anthropic, *Building Effective Agents*). Classify → confirm → hand off. The router never does the work itself — it picks who does.

## When to use

**By default, for any goal-shaped request.** An unambiguous goal is a 1-step
route: auto classifies, confirms in one line, and hands off — no extra hops,
so there is no "too obvious for auto".

| Use `/ork:auto` for… | Skip only when… |
|---|---|
| Any goal description ("fix X", "get Y to Z") | Already executing inside another skill (no recursion) |
| The right skill isn't obvious | Chaining a known multi-skill workflow you're mid-way through |
| You think you know the skill — auto confirms & short-circuits | |

> **Design note (2026-07-12):** this table previously said "Go direct when you
> already know the skill / the request maps unambiguously to one". That inverted
> instruction made the front door structurally unreachable — a competent model
> always believes it knows the target, so the router recorded near-zero
> invocations across thousands of sessions (the exact dead-skill problem the
> "Why this exists" note above describes). Routers must be framed as the
> default path, not an escape hatch for confusion.

## Intent categories → OrchestKit skill

| intent | signal words | routes to |
|---|---|---|
| **fix** | fix, debug, broken, failing, error, crash, regression | `/ork:fix-issue` |
| **diagnose** | why, why isn't, why does, why can't, investigate | `/ork:fix-issue` (investigation-first) |
| **optimize** | faster, reduce, latency, bundle, minimize, below N ms | a **`/goal` optimization loop** (see Gaps) |
| **cover** | coverage, untested, get to N% | `/ork:cover --target N` |
| **design** | design, architect, how should we, explore, idea | `/ork:brainstorm` |
| **build** | build, implement, create, add feature, from ticket | `/ork:implement` |
| **review** | review, PR, MR, pull request, #N | `/ork:review-pr` |
| **verify** | verify, check, make sure, passes, green | `/ork:verify` |
| **improve-skill** | improve the skill, optimize the prompt, SKILL.md | the **holdout-promotion gate** (see Gaps) |
| **(fallback)** | no confident category | clarify with ONE question |

Full per-category parameter extraction + edge cases: `references/routing-rules.md`.

## Model weight (orthogonal second dimension)

Intent picks **who** does the work. Weight picks **how expensive that worker should be**. A route is `{intent} @ {weight}`. Weight never changes the intent and never replaces it. The taxonomy above and the 7 disambiguation rules are untouched by it.

Tiers are the ones already declared in `src/agents/*.md` frontmatter (`haiku` 7 · `sonnet` 10 · `opus` 6 · `inherit` 13). No parallel taxonomy.

| weight | tier | the task is… |
|---|---|---|
| **Light** | `haiku` | mechanical or IO-bound, single file, deterministic output, trivially revertible |
| **Standard** | `sonnet` | the default: bounded judgment, known pattern |
| **Heavy** | `opus` | adversarial, security, safety, architecture, cross-cutting, or ambiguous |

**Resolution is asymmetric:** ANY heavy signal ⇒ Heavy; Light requires ALL light signals; everything else is Standard. Under-powering a security review yields a confident wrong answer nobody catches; over-powering a rename only wastes money.

Weight is **per leg, not per route**. A PR review can be a Heavy security leg plus a Light lint leg. Full signal table, per-intent defaults, and the honest limits of this lever: `references/routing-rules.md`.

> **This is the selector, not the cap.** `src/hooks/src/pretool/task/team-size-gate.ts` is an ex-post, per-session counter keyed on `ORK_TEAM_OPUS_MAX` (default 8). Its default posture is advisory (`outputWarning`); with `ORK_TEAM_SIZE_HARD=1` it escalates to `outputDeny` and refuses the spawn outright. Either way it reads the model read-only: it can refuse a premium spawn, but it cannot *choose* a cheaper one for you. Routing is what chooses. The two compose, cap as backstop and routing as selector; never duplicate the cap's counting here.

## The flow

```
  CLASSIFY  ->  CONFIRM  ->  HAND OFF
     |            |             |
  intent       show the     invoke the
  + weight     route        target skill;
  out loud     + nod        follow ITS phases
```

### 1. Classify (reason out loud first)

State your reasoning **before** committing to a route — this triggers chain-of-thought and is the single biggest accuracy lever (Anthropic, *Writing Effective Tools for Agents*). Example: *"'get latency under 200ms' names a metric + a direction → optimize, not fix."*

Apply the disambiguation rules (most specific wins; explicit verb beats inferred intent). **The load-bearing one: explicit verb wins** — "Fix the slow query" → `fix`, not `optimize`. For the full ordered ruleset (all 7, including the truly-ambiguous fallback), `references/routing-rules.md` is canonical.

Then classify **weight in the same pass**, naming the signal that decided it: *"touches auth and models an attacker → Heavy."* Intent first, weight second; a weight call never rewrites the intent you just committed to.

### 2. Confirm (low ceremony)

Show the chosen route in one line and get a nod before handing off:

```
Goal:   "{original goal}"
Intent: {category}
Weight: {Light|Standard|Heavy} ({tier}), decided by: {signal}
Route:  {/ork:skill or loop} {extracted args}
        [run] · [adjust] · [cancel]