projectious-work 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:
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.
Phase 2 — tool ranking (token overlap within the matched group). Scores the ~3–6 tools in the matched group. Returns the top tool with rationale and two runner-up candidates.
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.
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. Directfind_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:
- Add an entry to
DOMAIN_GROUPSinmcp/server.py. - Add trigger phrases to the
skill-findertrigger table. - Run the smoke tests:
uv run scripts/smoke-test-servers.py.