# intent-router

Adopt this skill: https://proskills.md/skills/other/angel291592-intent-router-skills-intent-router

Page: https://proskills.md/skills/other/angel291592-intent-router-skills-intent-router
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/intent-router/SKILL.md
size: 8062
upstream: https://github.com/angel291592/intent-router/blob/main/skills/intent-router/SKILL.md

```text
---
name: intent-router
description: >-
  Converges an underspecified request into a typed IntentSpec before planning or acting. Use when
  the user asks to implement, add, change, refactor, fix, migrate, configure, handle, triage, sort
  out, look into or decide something and the request leaves decisions open (which objects, which
  approach, what happens on failure, which trade-off), contradicts itself, admits two readings, or
  rests on an approach its sources may rule out — in a codebase, a ticket queue, a research brief
  or a runbook — or when the user says "clarify the intent", "what do you need from me", or
  invokes intent-router. Looks up what its sources hold (code, history, decision records, a ticket
  log, an order record, the policy in force) before asking; asks only preference or irreversible
  questions, one at a time, with a recommended default; halts instead of guessing; checks the
  delivered work against the spec. Silent on a fully stated task its sources do not contradict.
  Not for explaining existing state ("what does X do", "why is Y slow").
license: MIT
metadata:
  version: "1.2.0"
  author: angel291592
  homepage: https://github.com/angel291592/Intent-Router
---

# Intent-Router

A compiler does not guess the address of an undefined symbol. Do not guess the user's intent.

This runs one layer *before* planning, routing or coding. It converges a request into an
`IntentSpec` — a typed, machine-readable statement of what is actually being asked — and hands
that off. It does not implement anything itself.

## 1. Purpose and when this fires

Three passes, in compiler order: **Parse** the request into a draft spec, **Resolve** every
open question by looking it up or asking, then **Typecheck and emit** — route, ask, or halt.

Start when **both** hold:

1. The request is a *do-something* request: implement, add, change, refactor, fix, migrate,
   configure, handle, triage, sort out, look into, decide, write, set up, wire up, rename, remove,
   upgrade, optimise.
2. A quick scan finds **at least one decision-bearing unknown** — an answer that would change
   which files are touched, which approach is taken, how failures behave, or what counts as done.

Do not start when:

- the request asks you to explain existing state ("what does X do", "why is Y slow") rather than
  to find something out and produce a deliverable;
- the silence check below passes and its premise check finds no contradiction — the request
  already states every decision-bearing item, so there is nothing to converge;
- the request is trivially scoped and reversible (fix a typo, bump a patch version).

**The silence check.** Run it once, against the request text alone, before probing anything. The
request is fully specified when all four hold:

1. **Objects** — it names what is acted on, precisely enough to enumerate: endpoints, files,
   records, tickets. A collective noun ("the user API", "this customer") does not qualify.
2. **Approach** — it names the method or dependency to use, or rules the alternatives out.
3. **Failure behaviour** — for every step it asks for that can fail, a rule is stated. **A rule
   stated once covers the cases it subsumes**: "on invalidation failure serve uncached" is
   stated — you do not reopen it for read failures, write failures or timeouts the request did
   not separately enumerate. A step whose failure the request is *silent* about is unstated.
4. **Acceptance** — it names what counts as done: an observable end state one can check to
   declare the work complete ("done when both endpoints serve from cache and the suite passes").
   **A parameter the work must use is not a done condition** — a TTL, a limit or a response shape
   bounds the work without saying when it is done, and naming one does not close this item.

If all four hold, make **one premise check** before staying out of the way: at most two lookups,
aimed at the sources most likely to rule out what the request states — a decision record or
history entry about the named approach, the manifest entry for a named dependency, the definition
of a named object. If nothing you open contradicts the request, **do not run**: emit no spec, no
fenced block, no announcement that you considered this skill or checked anything — treat the
request as ordinary and carry it out directly. A spec emitted after a passed silence check is a
false positive, costing the user more than this skill saves. If a source you opened does
contradict it — the approach was tried and reverted, the dependency is pinned or removed, the
object does not exist — run, with that contradiction as a `premise` issue (section 3). An
approach you merely like better is never a contradiction.

If any one of the four is unstated, run — and do not downgrade an unstated item to "inferable"
because a plausible default exists: if the user had to be trusted with the outcome, or the
spec could be wrong without contradicting the request, that item is unstated.

**No-ask mode.** If the user says "no questions", "just do it", "don't ask me anything", keep
looking things up but never ask: whatever stays open is recorded with `source: inferred` and its
reasoning. If an inferred item touches an irreversible boundary, halt and name the field rather
than guessing it — the one thing worse than a question is a silent irreversible choice. Inference
may fill in **how** something is done; it may never invent **what** is being asked for. If the
request itself is unclear — it names neither the object nor an observable outcome ("make it
better" with nothing to make better) — no-ask mode halts with `cause: underspecified` and the
open fields, rather than inferring three concrete improvements and routing them as the user's
intent. This halt is specific to no-ask mode: when asking is allowed, the same unclear request is
answered with a question, not a halt.

**Explicit invocation.** When the user names this skill in any way, start unconditionally and
treat the text after the name as the request.

## 2. Vocabulary

- **unknown** — a field of the spec whose value is not yet established.
- **decision-bearing** — an unknown whose answer changes the files touched, the approach, the
  failure behaviour, or the acceptance criteria. Everything else is an implementation detail and
  is left to whoever executes.
- **required field** — a field the spec cannot be emitted without: `intent`, `objects`, and every
  constraint needed to act without guessing.
- **inferred** — a value the model supplied itself. Always visible, always evidenced, always
  cheap for the user to veto in one line.
- **evidence** — a pointer to where a value came from: one **token with no whitespace**, naming
  something you actually opened, in one of these forms only: `path`, `path:line`, `path:line-line`,
  `path#heading`, `git:<short-sha>`, `git:#<pr-number>`, `user:delegated` (a decision handed back),
  `record:<system>/<id>` (a record in a system of record) or `doc:<slug>#<section>` (a section with
  no path). Not evidence: the repository root (`.`), paths under `.git/`, `.claude/`, `.agents/`
  or `.intent/`, the harness config file, and above all a reasoning sentence — that goes in the
  constraint `text`. Anything else is a defect, even if the thing it names exists.
- **probe surface** — a place in the workspace where objective answers live: manifests, route
  definitions, configuration, tests, CI, version history, decision records.
- **ASK budget** — the hard cap on questions for one request. Default **3**.
- **irreversible** — a decision that cannot be walked back once shipped, because clients, data
  or users will depend on it.

## 3. Pass 1 — Parse

Produce a draft spec. Do not emit it, do not act on it.

1. Record the user's own words in `request`, truncated to 500 characters. Never paraphrase: the
   point is that a reviewer can compare the spec against what was actually said.
2. Normalise the action into `intent`, a snake_case verb-object identifier: `add_caching`,
   
```

## File: README.md
upstream: https://github.com/angel291592/intent-router/blob/main/README.md

````text
# Intent-Router

English | [简体中文](README.zh-CN.md)

**An intent compiler for AI agents.**

Turns a vague request into a typed `IntentSpec`: it looks up what it can, asks only what it
can't, calls out a request that contradicts itself, admits two readings, or rests on a premise
your own repo already disproves, and refuses to emit while the intent is still underspecified.
When the work gets handed off and carried out, it checks the result against the spec it wrote —
one constraint at a time, not a vibe check.

What that buys you:

- **Prompt equity.** You get the interaction of a senior engineer without having to learn prompt
  engineering — the gap between the top 1% of prompt writers and everyone else stops deciding what
  you get back. Say it the way you'd say it to a capable teammate, *"add caching to the user API"*,
  and the skill writes the briefing a senior engineer would have written first. You stop coaxing
  the model and start putting it to work.
- It asks one question, and the answer lands in the delivered code. Before anything reaches you it
  reads what your repo, ticket system or docs already answer, so the forty-six-question interview
  becomes the one question that genuinely needs your judgment — and in the delivery comparison,
  every run with the skill asks exactly that one question and 3 of 3 delivered caches state their
  failure policy, while none of the 5 bare deliveries do
  ([report](evals/reports/2026-09-24-delivery-opencode.md)).
- The work carries further. Every run ends in a machine-readable `IntentSpec`, saved to
  `.intent/<intent>.intent.yaml` before the reply that carries it, whose probed fields carry
  evidence pointers and which records its own state: still waiting on a question, settled, or
  already carried out. A later session **reads that file before probing anything** — an answered
  question is never asked again, a settled contract is implemented as written — and the result of
  checking the delivered work against it is written back into the same file. So the next agent,
  session or teammate starts from what you actually decided instead of zero.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Release](https://img.shields.io/github/v/release/angel291592/Intent-Router)](https://github.com/angel291592/Intent-Router/releases)
[![CI](https://github.com/angel291592/Intent-Router/actions/workflows/ci.yml/badge.svg)](https://github.com/angel291592/Intent-Router/actions/workflows/ci.yml)
[![Stars](https://img.shields.io/github/stars/angel291592/Intent-Router)](https://github.com/angel291592/Intent-Router/stargazers)
[![Works without installing anything](https://img.shields.io/badge/backend-L0%20prompt--only-green.svg)](#backends)

### What "installed" changes, in the diff itself

Same weak request, same fixture, same permissions, one line apart —
[bare vs. with the skill](evals/reports/2026-09-24-delivery-opencode.md) (N=5 bare, N=3 skill).
Excerpted verbatim from each run's own `diff.patch`, the part that decides what happens when the
cache itself fails:

**Bare** — no failure path exists to read. A downed Redis takes the request down with it:

```ts
const hit = await getCache<T>(key);
if (hit !== null) {
  return hit;
}
const value = await load();
if (value !== null) {
  await setCache(key, value);
}
return value;
```

**With the skill** — asked the one question no file could answer, then wrote the answer into the
code:

```ts
async function readCache<T>(key: string): Promise<{ hit: boolean; value: T | null }> {
  try {
    return { hit: true, value: await getCache<T>(key) };
  } catch {
    return { hit: false, value: null };
  }
}
```

Every one of the 5 bare runs shipped the first shape; every one of the 3 skill runs shipped the
second. Neither line was written by hand for this README — both come straight out of the runs
that produced the numbers in [Evals](#evals).

```
          "add caching to the user API"       "this customer is furious — sort it out"
                        │                                         │
                        ▼                                         ▼
 ┌────────────────────────────────────────────────────────────────────────────────────┐
 │  parse  →  resolve  →  typecheck  →  emit                    one engine, one spec  │
 ├────────────────────────────────────────────────────────────────────────────────────┤
 │  PROBE   deps, routes, git history, ADRs   │  order + ticket log, entitlements,    │
 │          — you are not interrupted         │  the policy in force                  │
 │                                            │                                       │
 │  ASK     serve stale, or serve uncached?   │  refund, or replace?                  │
 │          the one answer no file holds      │  the one that can't be undone         │
 └────────────────────────────────────────────────────────────────────────────────────┘
                        │                                         │
                        ▼                                         ▼
              IntentSpec  ──────►  your planner / agent / workflow / human
```

Same three passes. Same stopping predicate. Only the places it looks change.

<!-- demo:begin -->
What a real run looks like — one sentence in, it reads the repo itself and asks only what no
file can answer. From the measured run of 2026-09-23 behind the numbers below: 8 of the 10 cases
the suite held that day, 0 hallucinated evidence.

<p align="center">
  <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>
  <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>
  <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">
</p>
<!-- demo:end -->

No install, no API key, no dependencies — it's a skill:

```bash
npx skills add angel291592/Intent-Router
```

Manual install, or an agent the installer doesn't know: [Quick start](#quick-start).

---

## Contents

- [How it compares](#how-it-compares)
- [The problem](#the-problem) · [How it works](#how-it-works) · [The four decision states](#the-four-decision-states)
- [Two walkthroughs](#two-walkthroughs) — one in a codebase, one in a support queue
- [The artifact](#the-artifact) · [Where it works](#where-it-works) · [Quick start](#quick-start) · [Evals](#evals)
- [Design principles](#design-principles) · [Limitations](#limitations)
- [Backends](#backends) · [Prior art](#prior-art) · [Contributing](#contributing)

---

## How it compares

**Intent-Router is the layer between a vague request and the work: look it up, ask, or act —
then check what got built.** Your harness's own plan mode already prefers looking things up over
asking, and grill-me converges beautifully and states the right principle — but neither one
checks a stated premise against the evidence, and neither one checks the finished work against
what was decided. spec-kit keeps everything and makes you buy its whole workflow to get it.
Kiro's specs come closest on paper — requirement-level conflict analysis, a correctness check
after delivery — at the cost of a full three-file spec workflow and an IDE. Jev and Laya make the
same bet this skill makes — typed output instead of prose — one layer further down: both turn an
*already-clear* input into a typed, calibrated decision in a single pass, and neither one
converges a vague request into that clear input to begin with. Intent-Router is that upstream
layer as a single skill: no workflow to adopt, no files to keep in sync by hand, no IDE, no
separate decision service to run.

Read the row gaps, not the checkmarks. Every cell below is sourced to the tool's own docs or repo —
quoted cells are verbatim, and an unquot
````
