Orion — Self-Contained AI-Agent Toolkit

Orion is a zero‑dependency framework that turns a high‑level idea into production‑ready code with deterministic, reproducible quality gates — and minimal token usage. Instead of trusting one model's next token, Orion runs every idea through a fixed state machine so the outcome is verifiable no matter which model (or agent) you attach.

• Deterministic pipeline — think → draft → forge → shield → out.
• Token economy built‑in — every expensive command output is cached, deduplicated and compressed; savings are measured, not guessed.
• Test‑first by construction — every task runs the RED‑GREEN‑REFACTOR loop.
• Honest by default — Orion never fabricates a result; stale or unknown answers are labeled as such.

Why process matters more than the model

The same idea, run through the same pipeline, produces the same verifiable outcome regardless of the model. A model can hallucinate an eval() call or an "operation history" the goal never mentioned — the pipeline catches it: shield scans the code, drift compares specs against the implementation, out refuses to trust a stale guard verdict, and draft labels its own inferences [assumption] so a wrong guess is visible instead of silent.

The logical sequence in which a problem is solved matters more than the model used to solve it.

Quick Start

npm i -g orion-spec       # adds the `orion` command to PATH

orion think "Build a CLI utility that converts CSV to JSON"  # guided Qs -> proposal
orion draft csv-tool      # generates proposal, specs/, design.md, tasks.md
orion forge csv-tool      # RED-GREEN-REFACTOR loop over tasks.md
orion shield csv-tool     # lint, type-check, tests, drift, security
orion out csv-tool        # final result.md summary

Each step writes human‑readable, version‑controlled artifacts under changes/<title>/. See Quick Start guide for a walkthrough and Commands Reference for every command.

The pipeline

| Step | What it does | | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | think | Turns a raw idea into a proposal. Asks language‑aware clarifying questions (platform, constraints, budget), refines vague prompts and resolves them to changes/<title>/proposal.json. | | draft | Generates proposal.md, specs/<capability>/spec.md, design.md and tasks.md. Never clobbers your hand edits; supports --lang en\|ru or auto‑picks from your profile. | | forge | Drives every open - [ ] task in tasks.md through TDD, ticking each off live in the terminal. Optional --parallel <n> runs tasks in isolated worker waves. | | shield | Runs the guard‑rails: lint, type‑check, unit tests, drift‑check, YAGNI signal, cache‑economy budget, security scan and project policy gates. Each step caches PASS; a report lands in reports/<id>/. | | out | Writes the final result.md: a verdict assembled from tasks, guard report and artifacts — including any lessons learned. |

Canonical commands (9 total)

The CLI exposes 9 canonical top-level commands. Every command from earlier versions is still reachable as a deprecated alias that prints a warning and forwards to one of these (see the migration note below).

| Command | Purpose | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | orion new "<prompt>" | Pipeline driver: runs think→draft→forge→shield→out (or --step=<name>, --pipeline, --dry, --from=<id>). Replaces the old think/draft/forge/shield/out/verify/tasks/next/pay-debt/resume/init/plan commands. | | orion ls | List/inspect changes. Flags: --watch (live refresh), --diff <a> <b>, --assumptions <id>, --stats, --audit, --cache, --profile, --lessons (with export/import). Replaces list/status/compare/stats/self-audit/track/profile/lessons/history/metrics/tokens/learn. | | orion change <id> | Per-change ops. Flags: --tasks, --review, --archive, --diff, --changelog, --resume, --next, --pay-debt, --verify, --shield, --out, --export, --import. | | orion run | Offline scripts (22 sub-commands: new, generate, show, edit, delete, schedule, watch, repair, explain, log, stats, cache, …). | | orion scale <file> | YAGNI ladder (with --dry). --stage=tdd runs a TDD step (replaces orion tdd). | | orion doctor | Health/init/repair. Flags: --init, --config, --clean, --backup, --restore, --env. Replaces init/config/clean/backup/restore/env. | | orion serve | Web dashboard (default) + orion serve mcp (MCP stdio server for AI agents). Replaces serve/mcp. | | orion plugin | Plugin manager: list, install, remove, new. | | orion autopilot | Closed-loop orchestrator: routes a failing change through correction until it goes green or stops honestly. |

Migration from v0.50: every old command still works (e.g. orion list, orion think, orion shield my-id, orion mcp) but prints a deprecation warning. orion shell, orion completion, and orion route are already removed — they had no real users.

Full details and flags are in docs/commands.md.

Installation

Global CLI (recommended):

npm i -g orion-spec

Local dev dependency:

pnpm add -D orion-spec

Run from source instead:

git clone https://github.com/dadosh1984/orion-spec.git
cd orion-spec
pnpm install && pnpm run build
node dist/cli/index.js think "…"

Updating

npm i -g orion-spec@latest     # global CLI
npm view orion-spec version    # check the latest published version
npm ls -g orion-spec           # check the installed version

orion version (or orion --version/-V) prints the installed version, and orion mcp announces when a newer release is available. Every version is dated and described in CHANGELOG.md.

The packaged CLI ships the Honest Receipt — written into every change's result.md and as a machine-readable receipt.json when out finishes. It reports real guard data (drift, test, hazard) and labels coverage "not measured" when no coverage file exists — so the quality certificate is as honest as the code.

Core features

• Deterministic workflow — the whole pipeline is a state machine; every non‑trivial step is verified locally with transparent, auditable artifacts.
• Token economy — outputs of lint/type‑check/tests/drift/security are cached by orion-track and compressed before an agent reads them (orion-compress). Blocks and repeats are deduplicated, and orion metrics reports the real bytes/tokens saved from ~/.orion/economy.json.
• YAGNI ladder (orion-scale) — strips only what is provably redundant across a defined stage ladder, keeping code minimal without guesswork.
• RED‑GREEN‑REFACTOR (orion-tdd-core) — a template generates a failing test; your snippet is applied only if it makes the tests pass.
• Self‑correction — when a step honestly fails, Orion records a lesson in ~/.orion/lessons.json and routes back to think with a corrected task, so the same mistake is not repeated. Lessons carry across projects; orion learn also reads real agent‑session JSONL.
• Framework‑agnostic TDD (v0.24) — configure the engine for any language (TypeScript + vitest by default; Python via src/config/orionTdd.json).
• Open templates — proposal/design/tasks/spec skeletons and clarifying questions are data, not code. Override per change or globally.
• Plugin API + agents — unknown commands dispatch to installed plugins; orion mcp exposes a JSON‑RPC 2.0 server (17 tools) that any MCP‑capable agent can attach to.
• Autonomous offline scripts (orion run) — a task written once becomes a local script in ~/.orion/scripts/<name>/ (run.sh/run.js/run.py + orion.json). Run it any time with orion run <name> — no tokens, no LLM. Cross‑platform on Windows (bash/node/python resolved by absolute path) and deterministic: identical orion run <name> <args> calls report [cached] instead of re‑executing (override with --force).
• Observability & skill-first router (v0.48–0.49):
  • orion run list — colorized cards with risk icons, source, schedule.
  • orion run explain <name> — skill summary + token ROI + success rate.
  • orion run log <name> — last 20 events with status icons.
  • orion run stats — token economy dashboard (top-10 by saved tokens).
  • orion run diff <a> <b> — line-level diff of two scripts.
  • orion run generate --interactive — TTY wizard for risk/network/schedule.
  • orion run repair --auto — auto-regeneration via forge --save-as.
  • orion route <prompt> — router: existing-skill / new-skill / direct-AI / ask-user / reject (dangerous patterns blocked).
  • orion think/draft — suggest existing skills before creating changes.
• Optional browser engine (v0.50): for sites with strong anti-bot protection (Akamai, Yandex CDN, captcha) that block plain server-side fetch. Set ORION_SANDBOX=browser to execute a skill in a real headless Chromium via Playwright. Zero-dependency by default — playwright is only required when a script actually opts into browser execution:

  npm i -D playwright && npx playwright install chromium
  ORION_SANDBOX=browser orion run <name>

  A browser-mode script receives a run(ctx) context with a real page, or points at BROWSER_URL and its parser runs on the rendered DOM.

Phone number validator (E.164)

Structural validation only — checks format and length per ITU-T E.164.

import {
  parsePhone, // throws on malformed input
  validatePhone, // non-throwing: { ok, phone?, error? }
  formatPhone, // "+XXX NNN NNN NN"
} from "./src/tasks/phoneValidator.js";

parsePhone("+14155552671"); // → { countryCode: "141", nationalNumber: "55552671", raw: "+14155552671" }
validatePhone("+998901234567"); // → { ok: true, phone: {...} }
validatePhone("14155552671"); // → { ok: false, error: "Must start with +" }
formatPhone({
  countryCode: "141",
  nationalNumber: "55552671",
  raw: "+14155552671",
});
// → "+141 555 526 71"

Rules: must start with +; 7–15 digits total; digits only after +; country code is the first 3 digits. Not in scope: libphonenumber, country-code assignment lookup, number-in-use check (zero-dep project).

Development

pnpm run build          # tsc -> dist/
pnpm run lint           # ESLint (flat config)
pnpm run format         # Prettier --write
pnpm test               # Vitest (unit + e2e)
pnpm run test:coverage  # tests with coverage
pnpm run ci             # lint + format:check + type-check + build + coverage

CI runs the same steps across the OS matrix (ubuntu / macos / windows × Node 22 / 24) and uploads build artifacts.

Documentation

• Quick Start — step‑by‑step first run.
• Architecture — how the pieces fit together.
• Configuration — every ORION_* env var, templates, language.
• Commands Reference — full command and flag reference.
• Agents — connecting Orion to any MCP‑capable agent.
• Sandbox — Docker trust‑model and sandboxed CI.
• Analysis & Roadmap — self‑audit findings and planned phases.
• Changelog — dated semver release notes.
• Contributing — dev setup, style, tests, releases.

Security note. The shield security scan is a best‑effort pattern lint (eval, new Function, process.env.*, child_process, injection chains, secrets) — it flags obvious issues and can both over‑ and under‑match. Treat a PASS as "no obvious issues" and review security‑sensitive code by hand. See CONTRIBUTING.md.

License

MIT — see LICENSE.