# Intent-Router: a compiler that turns a vague request into a typed IntentSpec

> Intent-Router is a prompt-only skill for AI agents that converges an underspecified request into a typed IntentSpec, probing the repository for what it can, asking only the question no file answers, and refusing to emit while the intent is still ambiguous. It suits teams that want an agent to check its delivered work against a written contract, and its own evaluation numbers come from a small sample with a report file in the repository rather than from a third party.

**angel291592/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

- Repository: https://github.com/angel291592/Intent-Router
- Website: https://angel291592.github.io/Intent-Router/
- Stars: 54 · Forks: 14
- Language: Python
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/angel291592-intent-router

## Three passes and a stopping predicate

Intent-Router is described as an intent compiler for AI agents, and the description of what it does is unusually concrete for that genre of project.

It turns a vague request into a typed `IntentSpec`. Along the way it looks up what it can, asks only what it cannot, calls out a request that contradicts itself, admits two readings, or rests on a premise that the repository already disproves, and refuses to emit while the intent is still underspecified.

The diagram in the project documentation lays out the three passes. The pipeline is parse, then resolve, then typecheck, then emit, and the description says one engine, one spec. Underneath, PROBE covers dependencies, routes, git history and ADRs, with the note that you are not interrupted, while ASK is where the question is put, such as whether to serve stale or serve uncached, described as the one answer no file holds. The closing line summarises the design: same three passes, same stopping predicate, only the places it looks change.

The project description frames this as the input layer for routers and typed-decision models, and the topic tags name the same territory: agent-skills, agentic, clarification, context-engineering, decision-model, llm-routing, prompt-engineering, typed-decisions.

Two details in the framing matter more than the rest. The first is the refusal to emit while the intent is underspecified. Most agent tooling optimises for going ahead; this one has a stopping condition that can end in doing nothing, and that is the whole point of the design. The second is the handoff check: when the work is handed off and carried out, the tool checks the result against the spec it wrote, one constraint at a time, not a vibe check.

The project is written in Python, MIT licensed, with a homepage at angel291592.github.io/Intent-Router, and the last push was on 2026-10-16.

## A prompt-only skill with no install, no key and no dependencies

The delivery model is the simplest thing about the project, and it is what makes it easy to try.

There is no install, no API key, no dependencies, because it is a skill. The installation is one command:

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

For a manual install, or for an agent the installer does not know, the documentation points at a quick start section. The repository carries a `skills/` directory at the top level, alongside `docs/`, `evals/`, a CHANGELOG.md, a CODE_OF_CONDUCT.md, a SECURITY.md and a CONTRIBUTING.md, with Chinese versions of the README, the code of conduct, the contributing guide and the security policy, and an English and Simplified Chinese README pair at the root.

The claim of working without installing anything is carried on a badge in the README, alongside badges for the licence, the release, the CI workflow and the star count.

That is worth pausing on, because a prompt-only deliverable is a different kind of artefact from a library. There is no API to call, no version of a runtime to pin, no configuration file with a schema. What you install is text that tells an agent how to behave, and the agent's own model does the work. The benefit is that it works with whatever agent you already use, and the cost is that its behaviour is only as reproducible as the agent obeying it.

The project does describe itself as the input layer for routers and typed-decision models, which hints at a future in which the skill is one component of a larger system rather than the whole of it.

## The spec is a file, and it is read before the next probe

The most interesting mechanism in the project is persistence, and it is the part that has the longest reach beyond a single session.

Every run ends in a machine-readable `IntentSpec`, saved to `.intent/<intent>.intent.yaml` before the reply that carries it. The probed fields carry evidence pointers, and the spec records its own state: still waiting on a question, settled, or already carried out.

Then the part that makes it more than a scratch file. A later session reads that file before probing anything, so an answered question is never asked again and a settled contract is implemented as written. The result of checking the delivered work against the spec is written back into the same file. The stated consequence is that the next agent, session or teammate starts from what you actually decided instead of zero.

That is a small file format with a large behavioural effect. It converts a one-line request into a durable artefact, and it means the second run through the same task does not redo the interrogation. It also means the agent is reading a file it did not write in this session, which is a place where a wrong or stale spec would propagate. The state field, still waiting on a question, settled, or already carried out, is what makes the file self-describing enough to be acted on.

The evidence pointers are the other half of the design. A field that was resolved by probe carries a pointer to where it was resolved from, so a reader can check whether the resolution was right rather than take it on trust. The walkthrough screenshots describe exactly this: the emitted IntentSpec with 6 unknowns found and 4 resolved by probe, every field carrying an evidence pointer.

## The one question, and what the delivery comparison measured

The project's most quoted claim is about a single question, and the numbers behind it are specific enough to evaluate rather than admire.

The claim is that the skill asks one question, and the answer lands in the delivered code. Before anything reaches you it reads what your repository, ticket system or docs already answer, so the forty-six-question interview becomes the one question that genuinely needs your judgment. The comparison is reported as every run with the skill asking exactly that one question, and 3 of 3 delivered caches stating their failure policy, while none of the 5 bare deliveries do.

The example the documentation uses is a failure policy, and it shows the difference in the diff itself. The bare version, with no failure path to read, treats a downed Redis as taking 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;
```

The version produced with the skill, which asked the one question no file could answer and 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 };
  }
}
```

The documentation states that every one of the 5 bare runs shipped the first shape and every one of the 3 skill runs shipped the second, and that neither line was written by hand for the README, both coming straight out of the runs that produced the numbers.

Read carefully, the sample is small. N equals 5 bare and 3 skill, one fixture, one comparison pair, and the report is linked as a file in the repository at evals/reports/2026-09-24-delivery-opencode.md. The claim is also narrow in a way that makes it more credible rather than less: it is not that the skill produces better code in general, it is that in these runs the caches stated a failure policy and in the bare runs none did. A separately cited measured run of 2026-09-23 covered 8 of the 10 cases the suite held that day, with 0 hallucinated evidence, which is the more useful figure for judging the probing behaviour, since a hallucinated evidence pointer would defeat the point of the pointers.

## Two walkthroughs, one in a codebase and one in a support queue

The documentation's table of contents names two walkthroughs, one in a codebase and one in a support queue, and the project diagram shows what each of them probes.

The codebase case is the caching example, and the pipeline diagram shows its PROBE line covering dependencies, routes, git history and ADRs, and its ASK line asking whether to serve stale or serve uncached, described as the one answer no file holds. The other case in the diagram is the support queue, with the request being that a customer is furious and it should be sorted out. Its PROBE line covers order and ticket log, entitlements, and the policy in force, and its ASK line asks whether to refund or to replace, described as the one that cannot be undone.

That pairing is the most informative thing in the project, because the two examples differ in what they are for. The codebase case has a recoverable mistake, since a caching policy that fails open instead of closed is a bug you can find later. The support case has an irreversible decision, where a refund cannot be taken back and no file in the repository can say which the customer is entitled to. The claim of the tool is that it recognises the difference in kind, and asks exactly one question in each case, chosen for whether the answer needs your judgment and whether it can be undone.

The demo screenshots describe the same progression in a real run. One sentence in, it reads the repository itself and asks only what no file can answer, with the images showing the automatic load and probe of package.json, src/routes/users.ts, src/cache/redis.ts and more, then the one question, fail open or fail closed, with A and B options and a recommendation, and then the emitted spec.

The recommendation attached to the question is a detail worth noting. The tool does not just ask, it proposes, which means the answer is a confirmation rather than a blank page, and the answer still ends up in the code as the decision rather than as a comment.

## What the documentation does not settle

Several things a careful reader would want are not in the available documentation, and the honest way to evaluate the project is to name them.

The evaluation sample is small. Five bare runs and three skill runs on a single fixture is not a statistically meaningful comparison, and the report is the project's own file in its own repository rather than an independent study. A separate run of 8 of 10 cases with 0 hallucinated evidence is better but still one day of one suite.

The comparison is also with what the documentation calls bare runs, which is a baseline the project defines rather than one it was measured against, and the assertion that your harness's own plan mode already prefers looking things up over asking suggests the bare baseline is a weaker setup than a good agent harness would give. If your agent already probes before it asks, the difference the skill makes may be smaller than the numbers suggest.

The technology side is thin by design and by consequence. There is no API, no key and no dependency, which is the point, but it also means there is nothing to pin a version of except the skill text itself, and the behaviour depends on the model obeying the instructions rather than on any code the project controls. The repository lists backends as a section of its own, and the project page carries a badge for working without installing anything, so backends are a supported dimension, but the available text does not enumerate them.

The comparison section is also cut off mid-sentence in the available text, where it mentions grill-style prompting as a neighbouring approach, so the project's own account of its prior art is not fully readable here.

The releases tell you the project is moving quickly. v1.4.0 on 2026-10-16, v1.3.0 on 2026-10-09 and v1.2.0 on 2026-09-27 are three minor versions in three weeks, which is the pace of a project still finding its shape and the reason to expect the spec format and the state names to move.

## Conclusion

Adopt Intent-Router if your agent work routinely starts from a one-line request and you want the contract written down before the implementation, because the skill persists a machine-readable spec that a later session reads before probing anything. Do not adopt it if you want measured proof that it improves delivery on your codebase, since the published comparison is five bare runs against three skill runs from a single fixture, and check first that the agent you use supports skills, since the whole thing is delivered as a prompt with no API key and no dependencies.

## FAQ

### What does Intent-Router do?

It is a prompt-only skill for AI agents that converges a vague request into a typed IntentSpec. It probes the repository, ticket system or docs for what it can resolve, asks only the question no file can answer, refuses to emit while the intent is underspecified, and later checks the delivered work against the spec one constraint at a time.

### How do I install Intent-Router?

With `npx skills add angel291592/Intent-Router`. There is no install of a library, no API key and no dependencies, because what gets installed is a skill, and a manual install path is documented for agents the installer does not know.

### What is the IntentSpec file and where is it stored?

Every run ends in a machine-readable IntentSpec saved to `.intent/<intent>.intent.yaml` before the reply that carries it. Probed fields carry evidence pointers, and the spec records its own state, whether it is still waiting on a question, settled, or already carried out.

### Why does a later session read the spec before probing?

So that an answered question is never asked again and a settled contract is implemented as written. The result of checking the delivered work against the spec is written back into the same file, so the next agent, session or teammate starts from what was actually decided instead of zero.

### What evidence is there that the skill improves the delivered code?

The project reports a comparison of 5 bare runs against 3 skill runs on one fixture, where all 3 skill runs shipped caches that stated a failure policy and none of the 5 bare runs did, with the report kept in the repository as evals/reports/2026-09-24-delivery-opencode.md. The sample is small and comes from the project itself.

### Is Intent-Router still being maintained?

The repository is not archived and the last push was on 2026-10-16, with v1.4.0 released the same day, v1.3.0 on 2026-10-09 and v1.2.0 on 2026-09-27. The code is MIT licensed and the homepage is angel291592.github.io/Intent-Router.

## Sources

- [angel291592/Intent-Router on GitHub](https://github.com/angel291592/Intent-Router)
- [License: MIT](https://github.com/angel291592/Intent-Router/blob/main/LICENSE)
- [Project website](https://angel291592.github.io/Intent-Router/)
- [README](https://github.com/angel291592/Intent-Router/blob/main/README.md)
- [Releases](https://github.com/angel291592/Intent-Router/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/angel291592-intent-router