{"id":48994766,"url":"https://github.com/razroo/iso","last_synced_at":"2026-04-25T05:01:21.275Z","repository":{"id":352235173,"uuid":"1214388218","full_name":"razroo/iso","owner":"razroo","description":"Isomorphic agent tooling: author once, run on frontier or 7B. Build, lint, fan out, eval, and trace AI agent harnesses across Cursor, Claude Code, Codex, and OpenCode.","archived":false,"fork":false,"pushed_at":"2026-04-24T03:40:36.000Z","size":715,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-24T04:02:47.130Z","etag":null,"topics":["agent-harness","agents","ai-agents","claude-code","codex","cursor","evals","llm","markdown-linter","monorepo","observability","opencode","prompt-engineering","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/razroo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-18T14:05:07.000Z","updated_at":"2026-04-24T03:40:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"536ab08f-530d-4495-876c-b945db31a965","html_url":"https://github.com/razroo/iso","commit_stats":null,"previous_names":["razroo/iso"],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/razroo/iso","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/razroo%2Fiso","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/razroo%2Fiso/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/razroo%2Fiso/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/razroo%2Fiso/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/razroo","download_url":"https://codeload.github.com/razroo/iso/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/razroo%2Fiso/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32250599,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T04:23:17.126Z","status":"ssl_error","status_checked_at":"2026-04-25T04:21:53.360Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-harness","agents","ai-agents","claude-code","codex","cursor","evals","llm","markdown-linter","monorepo","observability","opencode","prompt-engineering","typescript"],"created_at":"2026-04-18T16:11:27.735Z","updated_at":"2026-04-25T05:01:21.221Z","avatar_url":"https://github.com/razroo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/logo.svg\" alt=\"iso\" width=\"320\"\u003e\n\u003c/p\u003e\n\n# iso\n\n**Write your AI agent instructions once. Run them anywhere, on any model.**\n\n`iso` is Razroo's toolchain for making agent harnesses *isomorphic* — the\nsame authored source produces the same agent behavior across every coding\nharness (Cursor, Claude Code, Codex, OpenCode) and across every model tier\n(frontier models down to 7B local models).\n\nToday, writing agent instructions is fragmented on two axes:\n\n1. **Harness fragmentation.** Each coding agent reads a different file\n   layout — `CLAUDE.md`, `AGENTS.md`, `.cursor/rules/*.mdc`,\n   `.opencode/agents/*.md`, `.mcp.json` vs `opencode.json` vs\n   `.codex/config.toml`. Keeping them in sync is copy-paste drift.\n2. **Model fragmentation.** A prompt written with a frontier model in mind\n   quietly breaks on smaller models: soft imperatives (`should`,\n   `when relevant`), taste words, ambiguous cross-references, and\n   unstructured rationale all drop silently at 7B. You don't find out\n   until the agent misbehaves in production.\n\nSeven packages solve that in one pipeline with a feedback loop:\n\n- **Four build-time tools** turn your authored source into every harness's file layout:\n  [`@razroo/agentmd`](./packages/agentmd) validates *structure*,\n  [`@razroo/isolint`](./packages/isolint) rewrites *prose* for small-model safety,\n  [`@razroo/iso-harness`](./packages/iso-harness) *fans out* to every harness, and\n  [`@razroo/iso-route`](./packages/iso-route) compiles *one model policy* into each harness's config.\n- **One wrapper** runs the whole build chain:\n  [`@razroo/iso`](./packages/iso) chains the above into a single `iso build`.\n- **Two feedback tools** close the loop after deploy:\n  [`@razroo/iso-eval`](./packages/iso-eval) scores *did the agent complete the task?* and\n  [`@razroo/iso-trace`](./packages/iso-trace) parses production transcripts to show *what the agent actually did*.\n\n```\n                authoring                          build                               output                        feedback\n  ┌────────────────────┐  agentmd  ┌───────────────────┐  isolint  ┌─────────────────┐  iso-harness  ┌───────────────────────┐    iso-eval  ──▶  per-task pass / fail\n  │ agent.md           │ ────────▶ │ validated rules,  │ ────────▶ │ small-model-    │ ────────────▶ │ CLAUDE.md             │                    (behavioral scoring)\n  │ + fixtures         │   lint    │ scope labels,     │ lint/fix  │ safe prose      │    build      │ AGENTS.md             │\n  │                    │   render  │ load-bearing why  │           │                 │               │ .cursor/rules/*       │    iso-trace ──▶  production events,\n  └────────────────────┘           └───────────────────┘           └─────────────────┘               │ .opencode/agents/*    │                    which rules ever fired,\n                                                                                                     │ settings.json         │                    regression-fixture mining\n  ┌────────────────────┐                                                                             │ .codex/config.toml    │\n  │ models.yaml        │ ───────────────────── iso-route build ─────────────────────────────────────▶│ opencode.json         │\n  │ (roles + fallback) │                                                                             │ .mcp.json             │\n  └────────────────────┘                                                                             └───────────────────────┘\n\n                    @razroo/iso chains agentmd → isolint → iso-route (when models.yaml exists) → iso-harness in one command.\n```\n\n## Quickstart\n\nMost users want `@razroo/iso` — one install, one command, every harness:\n\n```bash\nnpm install -D @razroo/iso\nnpx iso build .\n```\n\nGiven an `agent.md` (or an existing `iso/instructions.md`) and an `iso/`\nsource directory, this lints the authored source, rewrites it for\nsmall-model safety, and fans it out into `CLAUDE.md`, `AGENTS.md`,\n`.cursor/rules/*`, `.opencode/*`, and the matching MCP config files.\n\nSee [`packages/iso`](./packages/iso) for the full CLI reference and\nlibrary API, or [`examples/dogfood/`](./examples/dogfood) for a runnable\nproject that exercises the wrapper end-to-end.\n\n## Packages\n\n- **[`packages/iso`](./packages/iso)** — [`@razroo/iso`](https://www.npmjs.com/package/@razroo/iso) · *recommended entry point*\n  The wrapper CLI for the whole flow. If `agent.md` is your authored\n  source, `iso build` runs `agentmd lint`, `agentmd render`, `isolint\n  lint`, then `iso-harness build` in one command. Use this unless you\n  have a reason to reach for a sub-package directly.\n\n- **[`packages/agentmd`](./packages/agentmd)** — [`@razroo/agentmd`](https://www.npmjs.com/package/@razroo/agentmd)\n  A structured-markdown dialect for agent prompts. Rules are scoped\n  (`[H1]` hard limit, `[D1]` default) with load-bearing `why:` rationale.\n  Ships a linter for structure (missing rationale, dangling refs, no\n  fallback row) and a fixture-driven harness that measures per-rule\n  adherence against the target model.\n\n- **[`packages/isolint`](./packages/isolint)** — [`@razroo/isolint`](https://www.npmjs.com/package/@razroo/isolint)\n  Lints the compiled prose for phrases weak small models can't parse —\n  `should`, `when relevant`, `one of the usual categories`, taste words,\n  long sentences, unclosed `etc.` lists. `--fix --llm` rewrites offenders\n  and re-lints the rewrite before accepting. Also ships an Isomorphic\n  Plan engine for fully-deterministic large-model-plans → small-model-run\n  pipelines.\n\n- **[`packages/iso-harness`](./packages/iso-harness)** — [`@razroo/iso-harness`](https://www.npmjs.com/package/@razroo/iso-harness)\n  One `iso/` source directory → the file layout each coding agent\n  actually reads. Transpiles instructions, subagents, slash commands, and\n  MCP servers into `CLAUDE.md`, `AGENTS.md`, `.cursor/rules/*.mdc`,\n  `.opencode/agents/*.md`, etc., so all four harnesses stay in lockstep.\n\n- **[`packages/iso-route`](./packages/iso-route)** — [`@razroo/iso-route`](https://www.npmjs.com/package/@razroo/iso-route)\n  One model policy, every harness. Declare a default model plus named\n  roles (`planner`, `fast-edit`, `reviewer`, …) in a single\n  `models.yaml`; iso-route compiles that into `.claude/settings.json`,\n  `.codex/config.toml`, `opencode.json`, and a resolved role map that\n  `iso-harness` consumes when stamping per-subagent frontmatter. Honest\n  about ceilings — warns loudly where a harness (e.g. Cursor) can't bind\n  models programmatically.\n\n- **[`packages/iso-eval`](./packages/iso-eval)** — [`@razroo/iso-eval`](https://www.npmjs.com/package/@razroo/iso-eval)\n  Behavioral eval runner for the produced harness. Snapshots a workspace\n  per task, hands it to a runner with the task prompt, then scores the\n  resulting filesystem / command state — answering \"did the agent\n  actually do it?\" that structural and prose lints can't. Ships a\n  deterministic `fake` runner for CI smoke plus a real `codex` runner;\n  other harnesses plug in via the library `RunnerFn` interface.\n\n- **[`packages/iso-trace`](./packages/iso-trace)** — [`@razroo/iso-trace`](https://www.npmjs.com/package/@razroo/iso-trace)\n  Local observability for real agent transcripts. Parses Claude Code,\n  Codex, and OpenCode sessions into a harness-agnostic event model so\n  you can ask \"which rules ever actually fired?\", \"which\n  tools does my agent reach for most?\", and \"which captured sessions\n  would make good regression fixtures?\" Zero upload — everything is\n  local reads and user-controlled output.\n\nEach package is independently published on npm and works on its own.\nThey're in one repo because they're designed to compose.\n\n**Working on integrations across packages?** Read\n[`INTEGRATIONS.md`](./INTEGRATIONS.md). It now serves as the shipped\ncomposition ledger plus the list of deliberate non-integrations, so an\nAI agent (or human) pointed at this repo can tell what is already wired\nup vs. what is intentionally kept decoupled.\n\n## Commands cheat sheet\n\nInstall any one package globally or per-project; every CLI below is the\nbin exposed by that package.\n\n### `@razroo/iso` — wrapper (recommended)\n\n```bash\niso build                         # run agentmd → isolint → iso-harness on ./\niso build path/to/project         # target another project\niso build . --out dist            # write generated harness files under ./dist\niso build . --target claude,cursor\niso build . --skip-isolint        # skip the portable-prose pass\niso build . --dry-run             # dry-run the final iso-harness write\niso plan  .                       # print planned steps without executing\n```\n\n### `@razroo/agentmd` — author structure\n\n```bash\nagentmd lint   \u003cfile\u003e                                     # structural lint (rule IDs, refs, why:)\nagentmd render \u003cfile\u003e [--out compiled.md]                 # render compiled prompt with scope labels\nagentmd test   \u003cfile\u003e --fixtures \u003cpath\u003e [--via api|claude-code] [--model \u003cid\u003e]\n```\n\n### `@razroo/isolint` — portable prose\n\n```bash\nisolint lint .                                            # default preset\nisolint lint . --preset recommended,performance\nisolint lint . --since origin/main --fail-on warn         # gate PRs\nisolint lint . --format sarif \u003e lint.sarif                # for GitHub code scanning\nisolint lint . --fix --llm --large anthropic/claude-3.5-sonnet\nisolint plan  \u003cspec\u003e                                      # generate portable instructions from a plan\n```\n\n### `@razroo/iso-harness` — fan out to every harness\n\n```bash\niso-harness build                                         # reads ./iso, writes to ./\niso-harness build --target claude,cursor                  # subset of targets\niso-harness build --source path/to/iso --out path/to/project\niso-harness build --dry-run                               # print planned writes\niso-harness build --watch                                 # rebuild on every source change\n```\n\n### `@razroo/iso-route` — one model policy, every harness\n\n```bash\niso-route build models.yaml --out .                       # emit .claude/settings.json, config.toml, etc.\niso-route build models.yaml --targets claude,codex        # subset of harnesses\niso-route build models.yaml --dry-run                     # preview without touching disk\niso-route plan  models.yaml                               # print resolved role table\n```\n\n### `@razroo/iso-eval` — did the agent actually do the task?\n\n```bash\niso-eval run  eval.yml                                    # run the suite\niso-eval run  eval.yml --filter write-greeting --concurrency 2 --json\niso-eval run  eval.yml --keep-workspaces                  # keep tmpdirs for debugging\niso-eval plan eval.yml                                    # list tasks + checks, no execution\n```\n\n### `@razroo/iso-trace` — what the agent *actually* did (production)\n\n```bash\niso-trace sources                                         # detected transcript roots + parser status\niso-trace list                                            # recent sessions across every root\niso-trace list --since 7d --cwd .\niso-trace show \u003cid-or-prefix\u003e [--events tool_call,file_op]\niso-trace show \u003cid\u003e --grep \"H3\"                           # regex across messages + tool input\niso-trace stats [ids…] [--since 7d] [--cwd .]             # aggregate tool/rule stats\niso-trace stats --source path/to/sample.jsonl             # one file, no discovery\niso-trace model-score --cwd . --harness opencode --tool read\niso-trace model-score --cwd . --harness opencode --tool read --since-hours 24 --fail-on-schema\niso-trace model-score --cwd . --harness opencode --tool read --since-hours 24 --fail-on-model openrouter/z-ai/glm-4.5-air:free\niso-trace export \u003cid\u003e --format jsonl \u003e session.jsonl\n```\n\n## Layout\n\n```\niso/\n├── package.json          # workspaces root\n├── tsconfig.base.json    # shared compiler options\n└── packages/\n    ├── agentmd/          # structure + adherence\n    ├── isolint/          # portable prose\n    ├── iso-harness/      # one source, every harness\n    ├── iso/              # one command for the whole pipeline\n    ├── iso-route/        # one model policy → per-harness config\n    ├── iso-eval/         # behavioral eval on the produced harness\n    └── iso-trace/        # parse + query real agent transcripts (observability)\n```\n\n## Build \u0026 test\n\n```bash\nnpm install                 # install all workspace deps\nnpm run build               # build every package\nnpm run test                # run every package's tests\nnpm run typecheck           # typecheck every package\nnpm run test:dogfood        # wrapper-level local dogfood project\nnpm run test:pack           # pack local tarballs and smoke installed CLIs\nnpm run test:pipeline       # end-to-end demo (agentmd → isolint → iso-harness)\nnpm --workspace @razroo/iso-eval  run example   # iso-eval against the bundled example suite\nnpm --workspace @razroo/iso-trace run example   # iso-trace stats on the bundled sample transcript\n\n# Target a single package\nnpm run build --workspace @razroo/isolint\nnpm run test  --workspace @razroo/agentmd\nnpm run test  --workspace @razroo/iso\n```\n\n## Releasing\n\nVersion bumps are driven by [Changesets](https://github.com/changesets/changesets).\nEvery PR that changes a package should include a changeset describing the\nuser-visible impact:\n\n```bash\nnpm run changeset          # interactive — pick packages + bump level + summary\nnpm run changeset:status   # preview what the next `version` would do\n```\n\nWhen you're ready to cut a release:\n\n```bash\nnpm run version            # bumps package versions + writes CHANGELOG.md\ngit commit -am \"Version packages\"\ngit tag \u003cpkg\u003e-v\u003cversion\u003e   # e.g. agentmd-v0.3.0\ngit push \u0026\u0026 git push --tags\ngh release create \u003cpkg\u003e-v\u003cversion\u003e --generate-notes\n```\n\nThe tag-triggered release workflows in `.github/workflows/*-release.yml`\ntake over from there — verify the tag matches `package.json`, run tests,\nbuild, and `npm publish --provenance`.\n\n## End-to-end example\n\n[`examples/pipeline/`](./examples/pipeline) is an executable demonstration\nthat exercises **all seven packages end-to-end** in one `npm run\ntest:pipeline` invocation: `agentmd lint` + `render` → `isolint lint` →\n`iso-route build` (from a bundled `models.yaml` that extends the\n`standard` preset) → `iso-harness build` (which consumes iso-route's\nresolved map and stamps `model:` onto the Claude subagent) →\n`iso-eval run` against a tiny fake-runner suite → `iso-trace stats`\nagainst a bundled sample session. The assertion set includes a\ncross-package check that the `researcher` subagent's emitted\nfrontmatter contains `model: claude-opus-4-7`, driven from the\n`models.yaml` policy.\n\n[`examples/dogfood/`](./examples/dogfood) is a local dogfood project for the\nwrapper CLI itself. It starts from `agent.md` + `iso/` source and runs the\nrepo's local `packages/iso/bin/iso.mjs` entrypoint to produce the full harness\nfan-out. Run `npm run test:dogfood` to exercise the same wrapper path a\ndownstream repo would use.\n\n`npm run test:pack` goes one level further: it packs the local workspaces into\ntarballs, installs them into fresh temp projects, and smoke-tests the packaged\n`iso-harness`, `iso`, `iso-eval`, and `iso-trace` CLIs. This guards against\npackaging regressions that workspace-only tests can miss.\n\n[`packages/iso-eval/examples/suites/echo-basic/`](./packages/iso-eval/examples/suites/echo-basic)\nis a runnable eval suite for the downstream side: a baseline workspace, a\ntask prompt, and a set of file/command checks. Run `npm --workspace\n@razroo/iso-eval run example` to see the full pass-report against the\nbundled `fake` runner.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frazroo%2Fiso","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frazroo%2Fiso","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frazroo%2Fiso/lists"}