Skip to content
Back to search

Intent-Router

Intent compiler for AI agents — converges vague requests into typed IntentSpec contracts (probe, ask, or halt before routing), the input layer for routers and typed-decision models like Jev & Laya

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/angel291592--intent-router/badge.svg)](/listings/angel291592--intent-router)

HTML

<a href="/listings/angel291592--intent-router"><img src="/api/listings/angel291592--intent-router/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

No install, no API key, no dependencies. It's a skill.

npx skills add angel291592/Intent-Router

That detects the agents you have and installs into each. The skill lands as `intent-router`.

Nothing needs configuring: the skill reads and writes `.intent/` itself. If you keep a project-wide instruction file, one sentence makes the contract load even in a session where the skill does not fire on its own: *"If `.intent/` holds an open spec, read it before starting; check the work against it before claiming done."* That is a suggestion for your own file — the skill never edits it.

<details> <summary>Manual install, or an agent the installer doesn't know</summary>

Copy the `skills/intent-router/` directory (not the repository root) into whichever directory your agent reads:

- `.claude/skills/` — Claude Code - `.agents/skills/` — Cursor, Codex, OpenCode, Gemini CLI, Copilot, Pi, Amp, Zed and others

Add `~/` in front for a global install. Per-harness paths, including the ones that use their own directory name, are in [`references/harness-compat.md`](skills/intent-router/references/harness-compat.md).

**No skill mechanism at all?** `SKILL.md` is a single markdown file with no tool bindings — paste its body into your system prompt. The `references/` files are loaded on demand and can be pasted too, or left out. </details>

Then just work. Intent-Router is meant to fire **when a request arrives underspecified** — not when you remember to invoke it. (`grill-me`, by contrast, documents that *"the agent won't reach for it on its own."*) Force it when you want to:

/intent-router refactor the auth module     # Claude Code, Cursor, Copilot, Zed, Kiro, Augment
$intent-router refactor the auth module     # Codex
/skill:intent-router refactor the auth module   # Pi, Kimi Code

<details> <summary>Which agents it runs in</summary>

`SKILL.md` names no tools — it asks for *"whatever file-reading, search, or shell capability your environment provides"* — so it runs anywhere that reads the [Agent Skills](https://agentskills.io/) format.

**verified** (run here, report in `evals/reports/`) — OpenCode

**spec-compatible** (its docs say it loads standard `SKILL.md`; not exercised here) — Claude Code, Codex CLI, Cursor, GitHub Copilot (CLI and VS Code), Gemini CLI, Antigravity, Windsurf, DeepSeek Harness (dsh), Pi, Qwen Code, Kimi Code CLI, Trae, Cline, Roo Code, Kilo Code, Goose, OpenHands, Amp, Zed, Warp, Kiro CLI, Junie, Augment, Factory Droid

**needs-adapter** (no documented skill mechanism; paste `SKILL.md` into the system prompt) — Continue

Directories, invocation syntax and per-harness caveats: [`references/harness-compat.md`](skills/intent-router/references/harness-compat.md). </details>

Why `SKILL.md` is written the way it is — a section-by-section Chinese walkthrough (the skill itself stays English-only): [`docs/zh-CN/skill-guide.md`](docs/zh-CN/skill-guide.md).

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 675 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Intent-Router
  2. English | [简体中文](README.zh-CN.md)
  3. **An intent compiler for AI agents.**
  4. Turns a vague request into a typed `IntentSpec`: it looks up what it can, asks only what it
  5. can't, calls out a request that contradicts itself, admits two readings, or rests on a premise
  6. your own repo already disproves, and refuses to emit while the intent is still underspecified.
  7. When the work gets handed off and carried out, it checks the result against the spec it wrote —
  8. one constraint at a time, not a vibe check.
  9. What that buys you:
  10. - **Prompt equity.** You get the interaction of a senior engineer without having to learn prompt
  11. engineering — the gap between the top 1% of prompt writers and everyone else stops deciding what
  12. you get back. Say it the way you'd say it to a capable teammate, *"add caching to the user API"*,
  13. and the skill writes the briefing a senior engineer would have written first. You stop coaxing
  14. the model and start putting it to work.
  15. - It asks one question, and the answer lands in the delivered code. Before anything reaches you it
  16. reads what your repo, ticket system or docs already answer, so the forty-six-question interview
  17. becomes the one question that genuinely needs your judgment — and in the delivery comparison,
  18. every run with the skill asks exactly that one question and 3 of 3 delivered caches state their
  19. failure policy, while none of the 5 bare deliveries do
  20. ([report](evals/reports/2026-09-24-delivery-opencode.md)).
  21. - The work carries further. Every run ends in a machine-readable `IntentSpec`, saved to
  22. `.intent/<intent>.intent.yaml` before the reply that carries it, whose probed fields carry
  23. evidence pointers and which records its own state: still waiting on a question, settled, or
  24. already carried out. A later session **reads that file before probing anything** — an answered
  25. question is never asked again, a settled contract is implemented as written — and the result of
  26. checking the delivered work against it is written back into the same file. So the next agent,
  27. session or teammate starts from what you actually decided instead of zero.
  28. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  29. [![Release](https://img.shields.io/github/v/release/angel291592/Intent-Router)](https://github.com/angel291592/Intent-Router/releases)
  30. [![CI](https://github.com/angel291592/Intent-Router/actions/workflows/ci.yml/badge.svg)](https://github.com/angel291592/Intent-Router/actions/workflows/ci.yml)
  31. [![Stars](https://img.shields.io/github/stars/angel291592/Intent-Router)](https://github.com/angel291592/Intent-Router/stargazers)
  32. [![Works without installing anything](https://img.shields.io/badge/backend-L0%20prompt--only-green.svg)](#backends)
  33. ### What "installed" changes, in the diff itself
  34. Same weak request, same fixture, same permissions, one line apart —
  35. [bare vs. with the skill](evals/reports/2026-09-24-delivery-opencode.md) (N=5 bare, N=3 skill).
  36. Excerpted verbatim from each run's own `diff.patch`, the part that decides what happens when the
  37. cache itself fails:
  38. **Bare** — no failure path exists to read. A downed Redis takes the request down with it:
  39. ```ts
  40. const hit = await getCache<T>(key);
  41. if (hit !== null) {
  42. return hit;
  43. }
  44. const value = await load();
  45. if (value !== null) {
  46. await setCache(key, value);
  47. }
  48. return value;
  49. ```
  50. **With the skill** — asked the one question no file could answer, then wrote the answer into the
  51. code:
  52. ```ts
  53. async function readCache<T>(key: string): Promise<{ hit: boolean; value: T | null }> {
  54. try {
  55. return { hit: true, value: await getCache<T>(key) };
  56. } catch {
  57. return { hit: false, value: null };
  58. }
  59. }
  60. ```
  61. Every one of the 5 bare runs shipped the first shape; every one of the 3 skill runs shipped the
  62. second. Neither line was written by hand for this README — both come straight out of the runs
  63. that produced the numbers in [Evals](#evals).
  64. ```
  65. "add caching to the user API" "this customer is furious — sort it out"
  66. │ │
  67. ▼ ▼
  68. ┌────────────────────────────────────────────────────────────────────────────────────┐
  69. │ parse → resolve → typecheck → emit one engine, one spec │
  70. ├────────────────────────────────────────────────────────────────────────────────────┤
  71. │ PROBE deps, routes, git history, ADRs │ order + ticket log, entitlements, │
  72. │ — you are not interrupted │ the policy in force │
  73. │ │ │
  74. │ ASK serve stale, or serve uncached? │ refund, or replace? │
  75. │ the one answer no file holds │ the one that can't be undone │
  76. └────────────────────────────────────────────────────────────────────────────────────┘
  77. │ │
  78. ▼ ▼
  79. IntentSpec ──────► your planner / agent / workflow / human
  80. ```
  81. Same three passes. Same stopping predicate. Only the places it looks change.
  82. <!-- demo:begin -->
  83. What a real run looks like — one sentence in, it reads the repo itself and asks only what no
  84. file can answer. From the measured run of 2026-09-23 behind the numbers below: 8 of the 10 cases
  85. the suite held that day, 0 hallucinated evidence.
  86. <p align="center">
  87. <img src="docs/assets/demo-1-probe.png" width="760" alt="Intent-Router loads automatically and probes the repo: package.json, src/routes/users.ts, src/cache/redis.ts and more"><br><br>
  88. <img src="docs/assets/demo-2-question.png" width="760" alt="The one question it asks — fail open or fail closed — with A/B options and a recommendation"><br><br>
  89. <img src="docs/assets/demo-3-spec.png" width="760" alt="The emitted IntentSpec: 6 unknowns found, 4 resolved by probe, every field carrying an evidence pointer">
  90. </p>
  91. <!-- demo:end -->
  92. No install, no API key, no dependencies — it's a skill:
  93. ```bash
  94. npx skills add angel291592/Intent-Router
  95. ```
  96. Manual install, or an agent the installer doesn't know: [Quick start](#quick-start).
  97. ---
  98. ## Contents
  99. - [How it compares](#how-it-compares)
  100. - [The problem](#the-problem) · [How it works](#how-it-works) · [The four decision states](#the-four-decision-states)
  101. - [Two walkthroughs](#two-walkthroughs) — one in a codebase, one in a support queue
  102. - [The artifact](#the-artifact) · [Where it works](#where-it-works) · [Quick start](#quick-start) · [Evals](#evals)
  103. - [Design principles](#design-principles) · [Limitations](#limitations)
  104. - [Backends](#backends) · [Prior art](#prior-art) · [Contributing](#contributing)
  105. ---
  106. ## How it compares
  107. **Intent-Router is the layer between a vague request and the work: look it up, ask, or act —
  108. then check what got built.** Your harness's own plan mode already prefers looking things up over
  109. asking, and grill-me converges beautifully and states the right principle — but neither one
  110. checks a stated premise against the evidence, and neither one checks the finished work against
  111. what was decided. spec-kit keeps everything and makes you buy its whole workflow to get it.
  112. Kiro's specs come closest on paper — requirement-level conflict analysis, a correctness check
  113. after delivery — at the cost of a full three-file spec workflow and an IDE. Jev and Laya make the
  114. same bet this skill makes — typed output instead of prose — one layer further down: both turn an
  115. *already-clear* input into a typed, calibrated decision in a single pass, and neither one
  116. converges a vague request into that clear input to begin with. Intent-Router is that upstream
  117. layer as a single skill: no workflow to adopt, no files to keep in sync by hand, no IDE, no
  118. separate decision service to run.
  119. Read the row gaps, not the checkmarks. Every cell below is sourced to the tool's own docs or repo —
  120. quoted cells are verbatim, and an unquoted ✅/⚠️/❌ still traces to a specific page.
  121. | | Converges vague input | Doesn't ask what it can look up | Uses evidence against contradictions & bad premises | Never guesses past irreversible | Cross-session artifact | Checks delivery against intent | Fires automatically |
  122. |---|---|---|---|---|---|---|---|
  123. | **Intent-Router** | ✅ | ✅ `PROBE` | ✅ `ambiguous` / `conflict` / `premise` | ✅ `HALT` | ✅ `.intent/*.yaml` | ✅ `Intent check` | ✅ |
  124. | Your harness's native plan mode + question tool | ✅ asks | ⚠️ varies — Codex's plan template states the rule outright; Claude Code and Cursor explore but document none | ❌ not documented on any of the three | ⚠️ an approval gate, not a risk-based one | ✅ Claude Code, Cursor save a plan file; Codex's plan lives in the reply | ❌ not documented | ⚠️ Claude Code's tool is model-invoked; Cursor only suggests; Codex needs an explicit switch |
  125. | [grill-me](https://github.com/mattpocock/skills) | ✅ rounds/frontier | ✅ *"don't ask the user for anything you could look up yourself"* | ❌ not documented | ✅ *"the decisions are the user's"* | ❌ stateless by design | ❌ not documented | ❌ manual (`/grill-me`) |
  126. | [spec-kit `/clarify`](https://github.com/github/spec-kit) | ✅ category scan, ≤5 questions | ⚠️ excludes questions *"already answered"*, not questions the repo could answer | ⚠️ a separate command, `/analyze`, flags conflicting requirements | ⚠️ flags unresolved items as "Deferred", no reversibility test | ✅ writes into `spec.md` | ✅ a separate command, `/converge` | ❌ manual, one `/speckit-*` command at a time |
  127. | [Kiro specs](https://kiro.dev/docs/specs) | ✅ *"asks clarifying questions if needed"* | ⚠️ *"codebase exploration"*, no stated rule | ⚠️ `analyze-requirements` finds inconsistencies across the requirement set (IDE/CLI only) | not documented | ✅ three files per spec | ✅ property-based "Correctness" checks (IDE only) | ❌ manual (`Shift+Tab` / `/plan`) |
  128. | [Jev](https://www.jevai.org/) (typed decisions) | ❌ needs clear input already | — | — | — | — | — | ✅ |
  129. | [Laya](https://github.com/NandhaKishorM/laya) (open-source System 1) | ❌ needs a formed state to classify | — | — | — | — | — | ✅ |
  130. Jev's and Laya's rows are mostly `—`, not `❌`: they are the System 1 **decision** layer, called
  131. once a request is already well-formed — a different job from converging one, so most of these
  132. columns do not apply to them. Jev is a closed API; Laya is the open-weights, Jev-wire-compatible
  133. alternative you can run locally. The `IntentSpec` this skill emits is the shape of input both of
  134. them assume already exists, which is why both show up again under [Backends](#backends), as the
  135. planned optional L2.
  136. ### What your harness already does — and what this adds
  137. To be fair: a good harness natively prefers looking things up over asking, and offers a
  138. recommended default when it does ask. In the delivery comparison, all 5 bare runs read
  139. `docs/adr/0007-no-inproc-cache.md` on their own and avoided the trap it warns about — that habit
  140. is real, and it is not this skill's contribution. Nothing else on this page should be read as
  141. claiming it is.
  142. What it adds is the part a conversation cannot hold:
  143. - **The contract outlives the session.** Native answers live in the conversation — compress the
  144. context, open a new session, switch models, and they are gone. An `IntentSpec` is a
  145. file-level contract, so the next agent, session or teammate starts from it rather than zero.
  146. - **Two failures stay distinct.** Natively, a probe that failed and a request that was
  147. underspecified collapse into the same "I need more information". Here `degraded` is an
  148. operations signal and `underspecified` is your next step; merging them hides a backend outage
  149. behind what looks like a clarifying question.
  150. - **It refuses to emit past an irreversible guess.** The native bias is "pick a sensible
  151. default, mention it, keep going". When an inferred value touches an irreversible boundary, the
  152. skill refuses to ROUTE — it HALTs and names the field instead.
  153. - **It challenges a premise with evidence, never with taste.** A decision record, a pinned
  154. dependency or a removed file that contradicts what you asked for is worth one question before
  155. the work starts; liking a different approach better is never grounds to raise one.
  156. - **The contract gets checked, not just handed off.** When the work happens in the same
  157. conversation, the skill reruns its own spec against what was actually delivered and reports one
  158. line per constraint — `met`, with a pointer into the code, or `not met`.
  159. ---
  160. ## The problem
  161. > A compiler doesn't guess the address of an undefined symbol.
  162. > Your agent shouldn't guess your intent.
  163. When you hand an agent *"refactor this module"*, *"look into our churn"* or *"sort this customer
  164. out"*, exactly one of two things happens.
  165. **It guesses.** You get 400 lines of confident work built on an assumption you never made. You
  166. read it, realize the premise is wrong, and throw it away. The agent was never wrong about *how* to
  167. do the job — it was wrong about *what you meant*, and it found that out only after spending your
  168. tokens.
  169. **Or it interviews you.** This is better, and it's what `/grill-me`-style skills do well. But the
  170. bill is real: the grill-me docs call **"forty-six questions across four rounds an ordinary
  171. session."** And when it's over, the skill is explicitly stateless — *"it writes no files and
  172. leaves no workspace behind. The only thing it leaves is a sharper version of the idea, in your own
  173. head."*
  174. So you pay twice. Once in questions, and again because nothing downstream can read the answers.
  175. The next agent, the next session, the next teammate — all start from zero.
  176. **Both failures share one root cause: nobody decided whether the missing information was worth
  177. asking a human for.**
  178. Half those forty-six questions already have answers — in your `package.json`, your router file,
  179. your ADRs. Or, in the next queue over, in the order record, the account's entitlements, the
  180. refund policy currently in force. A compiler resolving an undefined symbol doesn't interrupt you
  181. to ask where `malloc` lives; it goes and looks in the libraries it was given. That's the missing
  182. step, and it isn't a step about code.
  183. ---
  184. ## How it works
  185. Three passes, in compiler order.
  186. **1. Parse — request → candidate structure.** The raw request becomes a draft `IntentSpec`: a
  187. normalized action, its objects, explicit constraints, and a list of `unknown` fields. Nothing is
  188. invented; anything the model had to fill in itself is tagged `source: inferred` so you can veto it
  189. in one glance.
  190. **2. Resolve — the part everyone skips.** This is context engineering as a routing decision: every
  191. `unknown` is classified *before* anything reaches you:
  192. | State | When | What happens |
  193. |---|---|---|
  194. | **PROBE** | The answer exists somewhere it can reach | It reads it. Code, deps, config, version history, tests, CI, docs — or a ticket log, an entitlement table, a policy document, your prior notes, an API. **You are not interrupted.** |
  195. | **ASK** | The answer only exists in a human's head — a preference, a trade-off, an irreversible boundary | One question, with two concrete options and a recommended default. |
  196. The rule that makes this work, and the one you should hold it to:
  197. > **If an objective answer exists and you have a way to reach it — PROBE. Never ASK.**
  198. > ASK is reserved for answers that live in a person's head, or decisions that can't be walked back.
  199. **3. Typecheck & emit — a decidable stopping condition.** Interviews that stop "when it feels
  200. done" run to forty-six questions and drift into a full context window. Intent-Router stops on a
  201. predicate instead:
  202. ```
  203. sufficient ⟺ every required field is filled
  204. ∧ no inferred field touches an irreversible boundary
  205. ```
  206. Not sufficient, and out of ASK budget? It **does not emit**. It halts and names the field that is
  207. still open — the same way a compiler refuses to link rather than picking an address at random.
  208. Halts carry a cause, and the two kinds are never merged:
  209. - `underspecified` — the request genuinely isn't decidable yet. Your move.
  210. - `degraded` — a probe failed, a model timed out, a parse broke. **An ops signal, not a user
  211. problem.**
  212. Every clarify/route library I found collapses these into one `FALLBACK`. That's how you end up
  213. with a router that silently sends 100% of traffic to the default handler for a week because one
  214. backend was down, and nothing in your logs says so.
  215. ---
  216. ## The four decision states
  217. | State | Meaning | Emits |
  218. |---|---|---|
  219. | `ROUTE` | Sufficient, one clear target | `IntentSpec` + target |
  220. | `PROBE` | Missing info is lookup-able | (internal — loops back to resolve) |
  221. | `ASK` | Missing info needs human judgment | one question, two options, a default |
  222. | `HALT` | `underspecified` \| `degraded` | a named open field, or an ops alert |
  223. Others state it as a principle — grill-me's `grilling` skill says *"finding facts is your job,
  224. never the user's."* Intent-Router makes it a **state**: every probe leaves an `evidence` pointer,
  225. every run reports `resolved_by_probe / unknowns_found`, and stopping is a predicate, not a
  226. feeling.
  227. ---
  228. ## Two walkthroughs
  229. Same engine, same artifact, two different worlds. The first is the domain the full-suite eval
  230. numbers belong to; the second shows what changes when there is no repository in sight — which
  231. is: the probe surfaces, and nothing else.
  232. ### A. In a codebase — *"add caching to the user API"*
  233. **Parse** finds four unknowns: which cache backend, which endpoints, what TTL policy, what happens
  234. when invalidation fails. **Resolve** classifies them before saying a word to you:
  235. ```
  236. PROBE cache backend → package.json: ioredis@5; src/cache/redis.ts exists ✓ resolved
  237. PROBE which endpoints → src/routes/users.ts: 3 GET handlers ✓ resolved
  238. PROBE TTL policy → src/cache/redis.ts:12 — repo convention is 300s ✓ resolved
  239. ASK invalidation fails → not in the repo. It's a trade-off. Irreversible.
  240. ```
  241. One question reaches you:
  242. > **On invalidation failure, which way should it fail?**
  243. > **A** (recommended) — serve uncached. Slower, always correct.
  244. > **B** — serve stale. Fast, can be wrong for up to 300s.
  245. > *Why you and not me: this is a product decision about whether your users may see stale data. It
  246. > isn't in your code, and it's expensive to reverse once clients depend on it.*
  247. **Emit**: `unknown: []`, so it compiles. `resolved_by_probe: 3, asked: 1`.
  248. And it caught something neither a guesser nor a griller would: ADR 0007 says in-process caching
  249. was already tried and reverted. That constraint is in the spec with a file pointer — not because
  250. you remembered it, but because probing is cheap and memory isn't.
  251. ### B. In a support queue — *"this customer is furious — sort it out"*
  252. Not a line of code involved. The same four categories of unknown appear, and most of them are
  253. still lookups:
  254. ```
  255. PROBE what actually happened → order #8821: delivery 12 days late, carrier marked lost ✓
  256. PROBE what they're entitled to → Pro plan, 30-day guarantee — 9 days of it left ✓
  257. PROBE what we already offered → ticket #4402: 10% credit, declined by the customer ✓
  258. ASK refund or replacement → policy permits both. Issuing one forecloses the other.
  259. ```
  260. > **Refund or replacement?**
  261. > **A** (recommended) — replace, expedited. Keeps the subscription; carrier claim covers cost.
  262. > **B** — full refund. Ends the dispute today, likely ends the account with it.
  263. > *Why you and not me: both are permitted, the customer's preference decides, and a refund
  264. > issued cannot be walked back.*
  265. `resolved_by_probe: 3, asked: 1` — and the agent never asked the customer to re-explain what
  266. happened, because the ticket already said. "Is the purchase inside the warranty window?" is a
  267. record, not an opinion; asking it is the bug this thing exists to remove.
  268. > **Honesty note:** walkthrough A is the domain covered by the [eval suite](#evals) and the
  269. > screenshots above. Walkthrough B's domain is measured on its own terms —
  270. > `support-delegate-irreversible` passed in the [2026-09-23 subset run](evals/reports/2026-09-23-opencode-2.md) —
  271. > while the full-suite numbers still belong to coding. See [Where it works](#where-it-works).
  272. ---
  273. ## The artifact
  274. One file, three consumers: a human reviews it, an agent executes it, an auditor replays it.
  275. ```yaml
  276. intent: add_caching
  277. objects: [GET /api/users, GET /api/users/:id, GET /api/users/:id/prefs]
  278. constraints:
  279. - source: explicit
  280. text: don't change response shape
  281. - source: probed # found in package.json + src/cache/redis.ts
  282. text: use the existing Redis client, not a new dependency
  283. evidence: src/cache/redis.ts:12
  284. - source: probed # found in version history + docs/adr/0007.md
  285. text: in-process caching was tried and reverted in #412 — don't reintroduce
  286. evidence: docs/adr/0007-no-inproc-cache.md
  287. - source: asked
  288. text: on invalidation failure, prefer correctness (serve uncached) over availability
  289. unknown: [] # empty ⟹ sufficient
  290. decision:
  291. state: ROUTE
  292. target: implement
  293. confidence: 0.88
  294. resolution:
  295. unknowns_found: 4
  296. resolved_by_probe: 3 # diagnostic, not a target
  297. asked: 1
  298. trace: [...] # replayable
  299. ```
  300. Outside code the fields don't change — only what an `evidence` pointer names. A file path becomes
  301. a record identifier or a document section (`record:tickets/4402`, `doc:returns-policy#eu`); the
  302. requirement that everything probed carries one does not relax.
  303. The full field list is fixed by
  304. [`intentspec.schema.json`](skills/intent-router/schema/intentspec.schema.json) (JSON Schema draft
  305. 2020-12), with a worked example of each state in
  306. [`schema/examples/`](skills/intent-router/schema/examples/).
  307. Every spec is also saved to `.intent/<intent>.intent.yaml` before the reply that carries it — the
  308. next agent, session or teammate starts from that file, and it sits next to the diff it produced,
  309. so "what was this PR actually trying to do" has an answer that isn't archaeology. Only that one
  310. file is written, nothing is committed, and nothing is written at all when the request is fully
  311. specified and the skill stays silent; whether `.intent/` belongs in version control is your
  312. project's decision. Meanwhile `resolved_by_probe / unknowns_found` still gives you something to
  313. hold the tool to.
  314. ---
  315. ## Where it works
  316. The three passes and the sufficiency predicate are domain-independent. What changes between
  317. domains is one thing only: **where an objective answer can be found.** Status is stated the same
  318. way this project states harness compatibility — measured, specified, or neither.
  319. | Domain | PROBE reaches | The question worth asking | Status |
  320. |---|---|---|---|
  321. | **Coding agents** | repo, deps, version history, tests, CI, ADRs | irreversible technical trade-offs | ✅ **measured** — [eval suite](#evals), 18 cases |
  322. | **Support & service triage** | ticket history, order and event logs, entitlements, the policy in force | refund vs. replace, when both are allowed and one forecloses the other | ✅ **measured** — 1 case (`support-delegate-irreversible`), [subset run](evals/reports/2026-09-23-opencode-2.md) |
  323. | **Research & analysis** | prior notes, previous reports, the source allow-list, cached retrievals | depth vs. breadth, when the deliverable changes shape | 📋 **specified** |
  324. | **Ops & data work** | schema, dashboards, last run's output, deploy and incident history, retention policy | may a backfill rewrite historical rows | 📋 **specified** |
  325. | **Multi-role assistants** | the candidate registry, attachment metadata, conversation history, user tier and locale | which of two genuinely overlapping specialists | 📋 **specified** |
  326. | Your domain | whatever you've given it access to | — | write the probe surfaces, it compiles |
  327. **measured** = at least one case from that domain passed in a published report in
  328. [`evals/reports/`](evals/reports/); each row states how many cases that is. **specified** = probe
  329. surfaces, worth-asking and not-worth-asking examples written into the skill's reference files and
  330. loaded on demand. Nothing here is marked as working because it sounds plausible.
  331. One extra rule earns its place in the multi-role case: **a route must declare what it is not.**
  332. `"route to me when X"` alone lets overlapping specialists absorb each other's requests;
  333. `"don't route to me when Y → send to Z instead"` is what actually pins the boundary. Sharpening a
  334. description never fixes an overlap — naming the neighbour does.
  335. ---
  336. ## Quick start
  337. No install, no API key, no dependencies. It's a skill.
  338. ```bash
  339. npx skills add angel291592/Intent-Router
  340. ```
  341. That detects the agents you have and installs into each. The skill lands as `intent-router`.
  342. Nothing needs configuring: the skill reads and writes `.intent/` itself. If you keep a project-wide
  343. instruction file, one sentence makes the contract load even in a session where the skill does not
  344. fire on its own: *"If `.intent/` holds an open spec, read it before starting; check the work against
  345. it before claiming done."* That is a suggestion for your own file — the skill never edits it.
  346. <details>
  347. <summary>Manual install, or an agent the installer doesn't know</summary>
  348. Copy the `skills/intent-router/` directory (not the repository root) into whichever directory your
  349. agent reads:
  350. - `.claude/skills/` — Claude Code
  351. - `.agents/skills/` — Cursor, Codex, OpenCode, Gemini CLI, Copilot, Pi, Amp, Zed and others
  352. - `.dsh/skills/` — DeepSeek Harness (dsh); it scans one level deep and takes the nearest `.git`
  353. ancestor as the project root, so the copy belongs at `<repo>/.dsh/skills/intent-router/`
  354. Add `~/` in front for a global install. Per-harness paths, including the ones that use their own
  355. directory name, are in
  356. [`references/harness-compat.md`](skills/intent-router/references/harness-compat.md).
  357. **No skill mechanism at all?** `SKILL.md` is a single markdown file with no tool bindings — paste
  358. its body into your system prompt. The `references/` files are loaded on demand and can be pasted
  359. too, or left out.
  360. </details>
  361. Then just work. Intent-Router is meant to fire **when a request arrives underspecified** — not
  362. when you remember to invoke it. (`grill-me`, by contrast, documents that *"the agent won't reach
  363. for it on its own."*) Force it when you want to:
  364. ```
  365. /intent-router refactor the auth module # Claude Code, Cursor, Copilot, Zed, Kiro, Augment, dsh
  366. $intent-router refactor the auth module # Codex
  367. /skill:intent-router refactor the auth module # Pi, Kimi Code
  368. ```
  369. <details>
  370. <summary>Which agents it runs in</summary>
  371. `SKILL.md` names no tools — it asks for *"the read, search and shell capability the environment
  372. has"* — so it runs anywhere that reads the
  373. [Agent Skills](https://agentskills.io/) format.
  374. **verified** (run here, report in `evals/reports/`) — OpenCode, DeepSeek Harness (dsh)
  375. **spec-compatible** (its docs say it loads standard `SKILL.md`; not exercised here) — Claude Code,
  376. Codex CLI, Cursor, GitHub Copilot (CLI and VS Code), Gemini CLI, Antigravity, Windsurf, Pi, Qwen
  377. Code, Kimi Code CLI, Trae, Cline, Roo Code, Kilo Code, Goose, OpenHands, Amp, Zed, Warp, Kiro CLI,
  378. Junie, Augment, Factory Droid
  379. **needs-adapter** (no documented skill mechanism; paste `SKILL.md` into the system prompt) —
  380. Continue
  381. Directories, invocation syntax and per-harness caveats:
  382. [`references/harness-compat.md`](skills/intent-router/references/harness-compat.md).
  383. </details>
  384. Why `SKILL.md` is written the way it is — a section-by-section Chinese walkthrough (the skill
  385. itself stays English-only):
  386. [`docs/zh-CN/skill-guide.md`](docs/zh-CN/skill-guide.md).
  387. ---
  388. ## Evals
  389. Eighteen cases against fixture workspaces built as probe targets, run in a real harness with
  390. nothing mocked. Cases assert the decision state, the counters, and that every evidence pointer
  391. names a file that exists — a single invented citation fails the suite regardless of everything
  392. else.
  393. <!-- evals:begin -->
  394. 2026-09-23 · opencode · dp/deepseek-flash · 8/10 cases · probe ratio 0.56 · 0 over-asks · 0 hallucinated evidence
  395. 2026-09-23 · opencode · dp/deepseek-flash · 8/8 subset cases · probe ratio 1.00 · 0 over-asks · 0 hallucinated evidence
  396. 2026-09-24 · opencode · dp/deepseek-flash · delivery add-caching-delivery · bare 5.0/6 (N=5) · with skill 6.0/6 (N=3) · ADR trap avoided bare 5/5 vs skill 3/3
  397. 2026-09-24 · opencode · (harness default) · 4/4 subset cases · probe ratio 0.25 · 0 over-asks · 0 hallucinated evidence
  398. 2026-09-27 · opencode · dp/deepseek-flash · 6/6 subset cases · probe ratio 0.44 · 0 over-asks · 0 hallucinated evidence
  399. 2026-10-15 · dsh · opencode-go3/deepseek-v4.1-flash · 5/6 subset cases · probe ratio 0.35 · 0 over-asks · 0 hallucinated evidence
  400. <!-- evals:end -->
  401. Line by line: line 1 is a full-suite run of the suite as it stood on 2026-09-23, which was ten
  402. cases; line 2 is a single-run re-test of an 8-case subset after that day's prompt hardening — a
  403. subset result, kept separate from the full-suite figure; line 3 is the delivery comparison, this
  404. project's result metric — the skill arm delivered 6/6 on all three runs and every one stated a
  405. cache failure policy, where none of the 5 bare runs did; line 4 is the v1.1.0 release
  406. verification, a 4-case subset run; line 5 is a subset run verifying the three request-defect
  407. cases (`ambiguous`, `conflict`, `premise`) added for v1.2.0 alongside the three cases that change
  408. could disturb; line 6 is the first DeepSeek Harness (dsh) run, a 6-case subset whose four auto-mode
  409. cases are the evidence for the description rewrite. Its sixth case, `git-only-fact`, failed, and
  410. the failure is the sandbox's rather than the skill's: reaching a fact that lives only in version
  411. history needs a shell that can read the repository, and on Windows the dsh sandbox cannot read the
  412. runner's own temporary workspaces — the same case passes on dsh with confinement off. Probe ratio
  413. is a diagnostic metric, never judged. The suite is eighteen cases,
  414. which puts the full-suite threshold at 15 of 18 with zero hallucinated evidence; no full-suite
  415. run at that size has been published yet. Every published report is in
  416. [`evals/reports/`](evals/reports/).
  417. How to run it yourself, and what each case checks: [`evals/README.md`](evals/README.md).
  418. ---
  419. ## Design principles
  420. 1. **Look up first, ask second.** A question you could have answered yourself is a bug.
  421. `resolved_by_probe / unknowns_found` is a diagnostic to watch, not a score to chase.
  422. 2. **Stopping is computed, not felt.** A predicate over required fields, plus a hard ASK budget.
  423. No session runs to forty-six questions.
  424. 3. **Inference must be visible.** Anything the model filled in is tagged `inferred` with its
  425. evidence. Cheaper to veto one line than to answer three more questions.
  426. 4. **Two failures, two signals.** `underspecified` is the user's move; `degraded` pages an
  427. operator. Merging them hides outages.
  428. 5. **Emit a contract, not a conversation.** If it isn't machine-readable, the next session starts
  429. from zero — and every spec is saved to `.intent/`, so the contract outlives the session.
  430. 6. **Routes declare what they are not.** Negative criteria are what keep overlapping targets from
  431. bleeding.
  432. 7. **Refuse rather than guess.** Not sufficient and out of budget? Halt with a named open field.
  433. 8. **Challenge a premise with evidence, never with taste.** A source that contradicts what the
  434. user stated is worth a question; liking a different approach better never is.
  435. 9. **Check delivery against the contract.** A spec that hands off work isn't finished until the
  436. work is checked against it, constraint by constraint.
  437. ---
  438. ## Limitations
  439. Stated up front, because you'll hit them.
  440. - **No sources, no probes.** The engine is only as good as what it can reach. Non-code domains are
  441. not the problem — a ticket system, a policy document or a notes archive is a rich probe surface.
  442. A *sourceless* setting is: pure conversation with nothing connected, where `PROBE` has nowhere
  443. to look and the run degrades toward asking. Still better than guessing, but the headline win is
  444. smaller.
  445. - **Ungrillable questions stay ungrillable.** *"How should this feel?"* can't be resolved by
  446. probing or asking — it needs something to react to. Intent-Router flags these and tells you to
  447. prototype instead of burning rounds on them. This limitation is inherited honestly from
  448. grill-me, which names it too.
  449. - **Full-suite numbers are coding-only.** The full-suite figures in [Evals](#evals) belong to the
  450. coding suite. Support triage now has a measured case of its own (`support-delegate-irreversible`,
  451. subset run), and every other domain marked *specified* is design and documentation, not
  452. measurement. Believe the ✅ rows; treat the 📋 rows as a starting point you should verify in your
  453. own setting.
  454. - **The premise check only recognizes a contradiction a source actually states.** It reads
  455. decision records, manifests and object definitions looking for something that rules the
  456. request out; it does not second-guess an approach it merely likes less, and silence from your
  457. sources is not evidence of anything. This works the same way in every domain — the three cases
  458. that measure it are code-only for now, same as the rest of [Evals](#evals); the other domains in
  459. [Where it works](#where-it-works) are specified, not measured, for this too.
  460. - **Verify points at your code, it doesn't run it.** A `met` line comes with a `path:line`
  461. pointer, not a test run — it's what a reviewer would check first, not a replacement for
  462. `npm test`. A constraint that needs a running service or live data to confirm is reported
  463. `not checkable here`, never a guessed `met`.
  464. - **Confidence at L0 is a model's self-report.** Treat it as ordinal, not calibrated. Want real
  465. calibration (ECE, Brier)? That's L2.
  466. - **Automatic firing is probabilistic.** Every harness matches your request against the skill's
  467. `description`; none of them guarantee a match. Invoke it explicitly when it matters.
  468. - **Don't let it validate itself.** If you ever train a classifier on Intent-Router's own labels,
  469. you get a system growing confident in its own mistakes. Label from independent evidence.
  470. ---
  471. ## Backends
  472. Same decision semantics at every tier. The default costs nothing, needs no key, and is the layer
  473. that ships today: **L0, prompt-only.** Two paid tiers are planned and optional.
  474. <details>
  475. <summary>The tier table, and why L2 is optional on purpose</summary>
  476. | Tier | Backend | Cost | Use when |
  477. |---|---|---|---|
  478. | **L0** *(default, shipped)* | Prompt-only. No deps, no keys. | $0 | Always start here |
  479. | **L1** *(planned)* | Any OpenAI-compatible endpoint + JSON schema | ~$0.0001/decision | Production, bounded latency |
  480. | **L2** *(planned, optional)* | [Jev](https://www.jevai.org/), [Laya](https://github.com/NandhaKishorM/laya) (open-source, local), or a local classifier | ~$0.0004/decision | You need calibrated confidence and audit trails |
  481. L2 is the division of labor the Jev community landed on — *LLMs create and repair semantic
  482. structure; a System One model repeatedly decides among known structures* — with Intent-Router
  483. supplying the structure. It's optional on purpose: Jev is closed-weights, waitlisted, and its
  484. benchmarks are vendor-reported; [Laya](https://github.com/NandhaKishorM/laya) is the
  485. open-weights alternative (Jev-wire-compatible, runs locally, ships a fine-tuned
  486. typed-decisions checkpoint — its zero-shot base is near chance, per its own benchmarks). L0 must
  487. always be enough to try.
  488. </details>
  489. ---
  490. ## Prior art
  491. This is a synthesis, not a clean-room invention. Five projects shaped it:
  492. [grill-me](https://github.com/mattpocock/skills) (the grilling primitive and the principle this is
  493. built on), [spec-kit](https://github.com/github/spec-kit) (`/clarify`'s bounded budget),
  494. [Jev](https://www.jevai.org/) (typed decisions, the LLM→IR→decider split),
  495. [Laya](https://github.com/NandhaKishorM/laya) (the open-weights, Jev-wire-compatible System 1
  496. model — proof the decision tier can be local) and
  497. [Camunda #63664](https://github.com/camunda/camunda/issues/63664) (the clearest statement of the
  498. problem). They deserve the credit for the parts they named.
  499. <details>
  500. <summary>What each one contributed, and what Intent-Router adds</summary>
  501. - **[mattpocock/skills](https://github.com/mattpocock/skills)** — `grill-me` and the grilling
  502. primitive. The round/frontier model, the passivity failure mode, and the grillable/ungrillable
  503. distinction all come from here. Its `grilling` skill also states the principle this project is
  504. built on — *"finding facts is your job, never the user's… don't ask the user for anything you
  505. could look up yourself"* — and deserves the credit for naming it. Intent-Router's contribution
  506. is to make that principle a state with an artifact behind it: *stateful, self-serving, and
  507. terminating*.
  508. - **[github/spec-kit](https://github.com/github/spec-kit)** — `/clarify`: a taxonomy scan, a
  509. bounded question budget, one question at a time with a recommended option, answers written back
  510. into the artifact. Excellent design, coupled to its own workflow. Intent-Router unbundles it.
  511. - **[TypeSafe Jev](https://www.jevai.org/)** and the
  512. [unofficial toolkit](https://github.com/HiQS-Labs/Jev-unofficial-toolkit) — typed, calibrated
  513. decisions instead of prose, and the LLM→IR→decider split that shapes `IntentSpec`.
  514. - **[Laya](https://github.com/NandhaKishorM/laya)** and its ecosystem
  515. ([laya-mlx](https://github.com/mizorewww/laya-mlx),
  516. [jevbench](https://github.com/dhruvmehra/jevbench)) — the open-weights, Jev-wire-compatible
  517. System 1 tier: the same typed `choice`/`score`/`noul` answers, runnable locally. The natural
  518. L2 target when you don't want a closed API in the loop.
  519. - **[semantic-router](https://github.com/aurelio-labs/semantic-router)**,
  520. **[RouteLLM](https://github.com/lm-sys/RouteLLM)**,
  521. **[vLLM Semantic Router](https://github.com/vllm-project/semantic-router)** — the routing tier
  522. Intent-Router feeds rather than replaces.
  523. - **[reaatech/confidence-router](https://github.com/reaatech/confidence-router)**,
  524. **[JevLang](https://github.com/TimMikeladze/JevLang)** — route/clarify/fallback thresholds and
  525. replayable policy audit, as libraries.
  526. - **[Camunda #63664](https://github.com/camunda/camunda/issues/63664)** — the clearest statement of
  527. the problem: grilling assumes the user owns the solution design, when they should own the
  528. *problem* and let the agent research what's researchable. `PROBE` is that issue, turned into a
  529. state.
  530. </details>
  531. ---
  532. ## Contributing
  533. Issues and PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
  534. ## License
  535. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.