agentleFS
robertn702robertn702/reasoning-router/AGENTS.md

reasoning-router

AGENTS.md4 starsChanged 35 days agoMITView on GitHub

reasoning-router is a pre-alpha npm-workspaces monorepo that generalizes opencode-jev-router to multiple agent harnesses and multiple classifiers. It contains the port of opencode-jev-router (see "Layout"). docs/architecture.md frames the problem and the open design questions. Use Node.js 24.x from the repo root. CI (.github/workflows/ci.yml) runs install, typecheck, lint, test, and smoke:package on pushes to main and on pull requests, plus the plugin and Pi smokes as separate jobs. The plugin smoke needs openssl and an existing /tmp/opencode; set OPENCODE_V2_BIN or OPENCODE_V2_VERSION to…

  • Reads credentials
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository2 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use Node.js 24.x from the repo root.

    line 11
  2. Very specific:

    Create only the packages listed under "Packages" in docs/architecture.md: @reasoning-router/core, @reasoning-router/opencode, …

    line 67
  3. Very specific:

    Never run npm publish or changeset publish locally.

    line 79
  4. Very specific:

    Do not modify opencode-jev-router from here.

    line 88
  5. Very specific:

    Every README.md has a Simplified Chinese README_CN.md, a Japanese README_JA.md, and a Korean README_KO.md beside it.

    line 93
  6. Distinctive:

    Use the terms from OpenAI's and Anthropic's localized docs: effort is 推理强度 / 推論強度 / 추론 수준, classifier is 分类器 / 分類器 / 분류기, and prompt cache …

    line 101

≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Working on this repo

reasoning-router is a pre-alpha npm-workspaces monorepo that generalizes opencode-jev-router to multiple agent harnesses and multiple classifiers. It contains the port of opencode-jev-router (see "Layout"). docs/architecture.md frames the problem and the open design questions.

Commands

Use Node.js 24.x from the repo root.

TaskCommand
Install dependenciesnpm ci
Typecheck, lint, and testnpm run check
Typechecknpm run typecheck
Lint and format check (Biome)npm run lint
Apply lint fixes and formattingnpm run format
Run tests (Vitest)npm test
Build every package to dist/, in dependency ordernpm run build
Pack, install, and run the packagesnpm run smoke:package
Install the packed plugin in OpenCode 2.0.18npm run smoke:plugin:v2
Install the packed extension in Pi 1.0.4npm run smoke:pi

CI (.github/workflows/ci.yml) runs install, typecheck, lint, test, and smoke:package on pushes to main and on pull requests, plus the plugin and Pi smokes as separate jobs. The plugin smoke needs openssl and an existing /tmp/opencode; set OPENCODE_V2_BIN or OPENCODE_V2_VERSION to test another OpenCode V2. The Pi smoke needs openssl and runs the pinned Pi devDependency; set PI_BIN (and PI_VERSION, the version it reports) to test another Pi.

Orca runs ./scripts/setup.sh from orca.yaml and waits for it to finish before starting an agent. The script runs npm ci, copies local .env* files (except .env.example) from the main checkout into a new worktree, and creates .env from .env.example if none exists. If present, it links .scratch/shared and AGENTS.local.md. It never overwrites existing files.

Layout

  • packages/core (@reasoning-router/core): validation, rewrite, lineage, forwarding, logging, model registry, and the classifier interface.
  • packages/classifiers (@reasoning-router/classifiers): every classifier, as presets selected by classifier.provider.
  • packages/opencode (@reasoning-router/opencode): the OpenCode V2 plugin.
  • packages/pi (@reasoning-router/pi): the Pi extension.
  • packages/proxy (@reasoning-router/proxy): the standalone proxy, run as the reasoning-router command.
  • Each package has src/, test/, and a tsconfig.build.json that compiles src/ to dist/. Package exports resolve the @reasoning-router/source condition to src/*.ts, which the root tsconfig.json and vitest.config.ts enable, so typecheck and tests run against source without building.
  • scripts/: package, plugin, and Pi smoke tests.
  • tsconfig.base.json: shared compiler options for packages to extend.
  • biome.json: lint and format configuration.
  • .changeset/: Changesets configuration (independent versions).

Conventions

  • The classifier (the component that picks the reasoning effort, such as Jev) is configuration. Do not make shared code depend on Jev or any single classifier provider; provider-specific code and dependencies stay out of the core.
  • Create only the packages listed under "Packages" in docs/architecture.md: @reasoning-router/core, @reasoning-router/opencode, @reasoning-router/classifiers, @reasoning-router/pi, and @reasoning-router/proxy. Harness adapters use the bare harness name. Add a classifier as a preset in classifiers, not as a new package. Follow the "Porting" decisions in docs/architecture.md when porting code into them.
  • Reach every classifier over HTTP. A classifier that runs a local model (such as Laya) is a server the user runs; never install, download, load, or start a model, its weights, or its runtime from these packages, and add no model runtime dependency.
  • Each test lives in the package whose code it covers.
  • Never run npm publish or changeset publish locally; releases go through .github/workflows/release.yml. Add a changeset (npx changeset) to any PR that changes a package's published behavior. On main, the workflow opens a "Version Packages" PR that applies pending changesets; merging it publishes the new versions to npm with provenance through npm trusted publishing, so no npm token is stored. If npm stages a release instead of publishing it, a maintainer approves it with npm stage approve. A new package has no trusted publisher, so its first version is published manually by a maintainer.
  • Do not modify opencode-jev-router from here; read it for reference only.
  • Make the smallest change that works. Add no speculative abstractions and no configuration without a current requirement.
  • Record reversible decisions in the commit message and, when they affect contributors, under "Decisions" in docs/architecture.md.
  • Every README.md has a Simplified Chinese README_CN.md, a Japanese README_JA.md, and a Korean README_KO.md beside it. Any change to a README must make the same change to every translation in the same commit, and a new README needs all three translations. Translations link to each other's _CN/_JA/_KO counterparts. In a translation, put <a id="..."></a> with the English anchor above any heading that is linked to, so #fragment links keep working, and point links to a package directory at that directory's translated README. Use the terms from OpenAI's and Anthropic's localized docs: effort is 推理强度 / 推論強度 / 추론 수준, classifier is 分类器 / 分類器 / 분류기, and prompt cache is 提示缓存 / プロンプトキャッシュ / 프롬프트 캐시 (CN / JA / KO). Chinese writes "token", not 令牌.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.