# Task Router

> Route a task description to the right processkit skill, project-specific process override, and MCP tool in a single deterministic call — use this at the start of every processkit domain task.

- Skill: `projectious-work/task-router-6` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add projectious-work/task-router-6`
- Raw SKILL.md: https://api.skillmd.com/api/skills/projectious-work/task-router-6/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: projectious-work (https://skillmd.com/u/projectious-work)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/projectious-work/task-router-6

---


# Task Router

## Intro

`task-router` is the primary routing entry point for processkit agents.
Call `route_task(task_description)` once at the start of any domain
task. It returns — in a single call, without an LLM — the matching
skill, the project-specific process override (if any), and the
recommended MCP tool. Use it instead of calling `find_skill()` directly.

## Overview

### When to use

Call `route_task()` before any `create_*`, `transition_*`, `link_*`,
or `record_*` MCP tool. The 1% rule applies: if there is even a 1%
chance a processkit skill covers this task, route first.

### Routing algorithm

Two-phase heuristic, no LLM call required:

1. **Phase 1 — domain group match** (cheap keyword classifier).
   Scores the task against 13 domain groups by keyword overlap.
   Eliminates ~90% of candidates in one pass.

2. **Phase 2 — tool ranking** (token overlap or local embedding-style
   cosine scoring within the matched group). Scores the ~3–6 tools in
   the matched group. Returns the top tool with rationale and two
   runner-up candidates.

3. **Fallback** — if no group scores ≥ 0.3, falls back to the
   skill-finder trigger-phrase table for cross-domain or meta tasks.

### Reading the result

| Field | What it means |
|---|---|
| `skill` | Load this skill's SKILL.md before acting |
| `skill_description_excerpt` | First 150 chars of skill description — judge fit without loading the full file |
| `process_override` | If present: read this file before the skill — it contains project-specific overrides |
| `tool_qualified` | `{server}__{tool}` — collision-safe tool identifier |
| `confidence` | 0.0–1.0 geometric mean of group and tool scores |
| `routing_basis` | `keyword_match` = confident; `needs_llm_confirm` = escalate to user/LLM |
| `candidate_tools[]` | Top-3 scored tools with rationales for fallback |

### When `confidence < 0.5`

`routing_basis` will be `needs_llm_confirm`. Show `candidate_tools[]`
to the user or pass them to an LLM for disambiguation. Do NOT call a
`create_*` tool without confirmation when confidence is low.

Callers may pass `allow_llm_escalation=true`; the router then returns a
`llm_escalation` status with the configured `fast` model class hint. The
stdio MCP server does not make provider network calls itself, so the caller
owns the actual cheap-model confirmation step.

### When `process_override` is present

Read the process override file **before** the generic skill. It
contains project-specific step overrides, gates, and blockers that
supersede the skill defaults. Example: `context/processes/PROC-release.md`
overrides `release-semver` for this project.

## Gotchas

- **Do not call `find_skill()` directly** in normal flow — `route_task()`
  calls it internally as a fallback. Direct `find_skill()` calls skip
  the process override lookup and the domain group fast path.
- **Low confidence is a signal, not a failure.** Confidence < 0.5 means
  the task straddles multiple domains or uses uncommon vocabulary. Use
  `candidate_tools[]` to present options.
- **Task description quality matters.** Verb-noun phrases score best:
  "create work item", "record decision", "log event". Single words
  ("task", "log") are ambiguous — add context.

## Full reference

### MCP server

See `mcp/SERVER.md` for tool schema and return-shape details.

### Domain groups

The 13 registered groups: `workitem`, `decision`, `discussion`,
`event`, `actor`, `scope`, `index`, `skill`, `gate`, `model`,
`id`, `role`, `binding`.

### Extending the router

To add a new domain group:
1. Add an entry to `DOMAIN_GROUPS` in `mcp/server.py`.
2. Add trigger phrases to the `skill-finder` trigger table.
3. Run the smoke tests: `uv run scripts/smoke-test-servers.py`.