Harness Router

# Harness Router

> Natural language entry point to all harness skills. Classifies intent by scope/domain, confirms routing with reasoning, dispatches to the appropriate skill.

## When to Use

- When the user invokes `/harness` with a natural language description
- When the user is unsure which harness skill to use
- NOT when the user already knows the specific skill (e.g., `/harness:tdd`)
- NOT for non-harness tasks (general coding, file operations, etc.)

## Process

### Iron Law

**The router confirms before dispatching.** Never silently route. Always present the chosen skill, scope classification, and reasoning — then wait for confirmation.

---

### Phase 1: CLASSIFY — Parse Intent and Search

1. **Check for empty input.** Show usage help and stop:

   ```
   Usage: /harness <describe what you want to do>
   Examples:
     /harness fix the button spacing on the settings page
     /harness we need a notification system
     /harness this page is slow
     /harness redesign how the sidebar filters work
     /harness clean up my code
   I'll figure out the right skill and process level for you.
   ```

2. **Search the skill catalog.** Call `search_skills({ query: "<user's intent>" })` to get ranked matches.

3. **Classify scope** into one of four tiers:

   | Scope                | Signal Words                                       | Description                                |
   | -------------------- | -------------------------------------------------- | ------------------------------------------ |
   | **quick-fix**        | fix, tweak, adjust, update, change X to Y, correct | Small targeted change, no design decisions |
   | **guided-change**    | redesign, refactor, improve, rework                | Moderate scope, clear architecture         |
   | **full-exploration** | build, create, add system for, we need, design     | Ambiguous scope, design decisions needed   |
   | **diagnostic**       | broken, slow, failing, debug, review, analyze      | Something broken or needs analysis         |

   Additional signals: single file → lower ceremony; multiple systems → higher ceremony; error messages → diagnostic.

4. **Map scope to entry skill:**

   | Scope            | Primary Skill           | Alternates                                                        |
   | ---------------- | ----------------------- | ----------------------------------------------------------------- |
   | quick-fix        | `harness-tdd`           | `harness-refactoring` if structural                               |
   | guided-change    | `harness-planning`      | `harness-architecture-advisor` if tradeoffs involved              |
   | full-exploration | `harness-brainstorming` | —                                                                 |
   | diagnostic       | `harness-debugging`     | `harness-code-review` for reviews, `harness-perf` for performance |

   If `search_skills` results strongly favor a different skill, prefer search results. Scope classification is the fallback when search is ambiguous.

5. **Assess confidence:**
   - **High:** Top result clearly dominates and aligns with scope classification
   - **Low:** Top 2-3 results close in score, or scope classification conflicts with search results

---

### Phase 2: CONFIRM — Present Decision with Reasoning

**High confidence:**

```
This looks like a [scope-level] — [reasoning].
I'll route to `harness:[skill]` because [why this skill fits].
Proceed? (y / n / suggest another)
```

Wait for confirmation.

**Low confidence (multiple candidates):**

```
This could be a few things:
1. `harness:[skill-1]` — [description]
2. `harness:[skill-2]` — [description]
3. `harness:[skill-3]` — [description]
Which fits best? (1 / 2 / 3)
```

Wait for the user to choose.

**User rejects:** If they name a skill, confirm and dispatch. If they re-phrase, re-run CLASSIFY. Do not loop more than twice — after two misses, list all available skills and let the user pick.

---

### Phase 3: DISPATCH — Invoke Selected Skill

1. **Pass original intent as context** so the user does not repeat themselves.
2. **Invoke via `run_skill`:** `run_skill({ skill: "<selected-skill>", path: "<project-root>" })` with original intent as argument context.
3. **Hand off cleanly.** Once invoked, the router's job is done. The dispatched skill owns all subsequent interaction.

---

## Examples

**Quick Fix:** "fix the button spacing on the settings page"
quick-fix — single component, clear target → `harness-tdd`

**Guided Change:** "redesign how the sidebar filters work"
guided-change — moderate scope, some decisions → `harness-planning` or `harness-architecture-advisor`

**Full Exploration:** "we need a notification system"
full-exploration — ambiguous scope, multiple approaches → `harness-brainstorming`

**Diagnostic:** "this page is slow"
diagnostic — performance symptom → `harness-perf`

**Ambiguous:** "clean up my code"
Could be refactoring, dead code, or architecture cleanup → Present candidates: `harness-refactoring`, `harness-codebase-cleanup`, `harness-cleanup-dead-code`

## Harness Integration

- **`search_skills`** — Phase 1: matches intent against the skill catalog. Returns ranked results.
- **`run_skill`** — Phase 3: dispatches to selected skill with project path and original intent.
- **`harness validate`** — Not used by the router. Validation is the dispatched skill's responsibility.

## Success Criteria

- Quick-fix intents route to `harness-tdd`, full-exploration to `harness-brainstorming`, diagnostics to appropriate diagnostic skill
- Ambiguous intents present top 2-3 candidates for user choice
- Confirmation always includes scope classification, chosen skill, and one-line reasoning
- User can reject and re-phrase or pick a different skill
- Dispatched skill receives original intent as context
- `search_skills` MCP tool is used for matching — no custom scoring code
- `/harness` with no arguments shows usage help

## Rationalizations to Reject

| Rationalization                                                           | Reality                                                                                                                                       |
| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| "The intent is obvious, I can skip confirmation"                          | The Iron Law requires confirmation before every dispatch. Even obvious intents benefit from the user seeing scope classification.             |
| "I should suggest downstream skills the dispatched skill will chain into" | Each skill owns its own transitions. Surfacing the full chain adds noise and duplicates logic in the dispatched skill.                        |
| "Search results don't match well, so I'll guess based on keywords"        | If `search_skills` returns poor results, present top candidates and let the user choose. Guessing silently is worse than admitting ambiguity. |
| "The user rejected twice, I should keep trying"                           | After two misses, list available skills and let the user pick directly. Do not loop indefinitely.                                             |

## Gates

- **No silent dispatch.** Every routing decision must be confirmed before the skill is invoked.
- **No bypassing search_skills.** The skill catalog search must be used. Do not hardcode intent-to-skill mappings.
- **No downstream chaining.** The router dispatches to exactly one skill. Do not pre-load or suggest follow-on skills.
- **No more than two re-classification attempts.** After two rejections, show the full list.

## Escalation

- **`search_skills` returns no results:** Skills index may be stale. Suggest `harness update-skills-index` to regenerate, then retry.
- **Intent spans multiple skills:** Ask: "This involves both [skill A] and [skill B]. Which should we start with?" Do not dispatch to multiple skills.
- **Intent outside harness catalog:** Say so plainly: "This doesn't match any harness skill. Handle directly, or re-describe if you think a skill should apply."