orly

AI-native development, made deterministic. Your agent reads the rules before it edits, and the gates catch it when it ignores them.

[!NOTE] Are you an agent? Read llms.txt instead of this page.

It carries the same setup written for machines: exact commands, exact paths, and a decision table for every failure. Humans should carry on here.

Why orly exists

Your agent reads your conventions. Then it writes whatever it likes. Nothing checks.

orly ships both halves of the fix:

• Rules — the agent reads them before it edits.
• Gates — scripts wired into git hooks that fail the commit when a rule was ignored.

The rules were derived from gstack and gbrain, then hardened over 500+ merged pull requests shipping agentsfleet.

Where you disagree, your own AGENTS.md wins.

Works with Claude Code, Codex, OpenCode, and Amp.

0.28: no telemetry, a slimmer spec

orly collects no usage telemetry, and orly skill-event and orly lifecycle are gone. The spec template is a skeleton whose comments cite the rules in the spec standard. Each Dimension carries its test tier and result, and baselines come from the base commit's Continuous Integration (CI) run.

docs.language now reports a template slot left on a changed spec line. A configuration that still carries the retired execution key is refused.

0.26: rules become standards

Rules now live in standards: short pages of rule blocks with Applies to, Checked by, Bad, Good and Why. Three skills carry the steps: orly-spec, orly-build and orly-ship. The orly-standards-reviewer agent checks a diff against the standards before the Pull Request.

The always-on AGENTS.md is under 16 KiB, down from 37 KB. The dispatch pages, the audit scripts, the read-logging gate and orly judge are gone. orly gate pr checks code and Git; a spec is reviewed while it is written.

orly doctor checks that every agent runtime has gstack and the Elephant-Goldfish Model (EGM), at whatever version you run. A Codex cloud task gets the same setup; see the architecture page.

See releases for published versions. The install commands below fetch the published package. The release workflow publishes 0.28.0 after its version change merges to main or an explicit release run.

Prerequisites

[!IMPORTANT] git never clones hooks. Every teammate runs orly init once in their own checkout, even after the rules are committed.

Install the published package

Run this inside the repository you want governed.

bunx --bun @agentsfleet/orly init

orly scans your source, detects your languages, and installs only the rules that apply.

[!TIP] Try bunx --bun @agentsfleet/orly init --dry-run first. It previews the generated rules and changes nothing.

Complete any setup items printed by init, then run bunx --bun @agentsfleet/orly doctor and commit the generated files. Use bunx --bun @agentsfleet/orly <COMMAND> for the commands below; <COMMAND> names the command and its options. Generated Git hooks invoke the pinned package through bunx; Bun must be on the hook search path. No global orly installation or project dependency is required.

Teammates get the rules on clone and run orly init to install their hooks.

Declare conform and at least one verify.* command in .orly/orly.json. Orly runs your repository's commands; the verification name does not require a particular language or test runner. For a documentation repository whose Makefile provides test and lint:

"commands": {
  "conform": [["make", "test"]],
  "verify.docs": [["make", "lint"]]
}

Here test checks documentation during work, and lint validates the site and links before the pull request. Markdown and Markdown JSX (MDX) repositories do not need application unit or integration suites. orly doctor checks configuration and installed files; run the gates to verify the commands themselves.

Each invocation has a 30-minute deadline and a 64-mebibyte combined output budget. Exceeding either limit fails the check, stops its child processes and prints a private output receipt path. Set per-command overrides in .orly/orly.json, for example:

"limits": {
  "verify.unit": { "timeout_ms": 1800000, "output_bytes": 67108864 }
}

The receipt retains all captured output until you remove its printed directory. Unknown settings and malformed values are refused; schemas/profile.schema.json describes the repository configuration.

Update

Commit first, then run the update from the consumer repository. If the repository owns its hooks, preserve them explicitly:

bunx --bun @agentsfleet/orly update --no-hooks

Expected: managed files are replaced and the change shows in git diff. A managed file with uncommitted changes stops the update and names the path. Use the installed candidate executable for an unpublished release trial; the command above fetches the published version.

Review existing hooks before choosing an update without --no-hooks.

bunx --bun @agentsfleet/orly doctor

Expected: installed rules match .orly/orly.json and work and verification commands are declared. Then run the repository's declared checks; doctor alone does not run them.

What lands in your repository

your-repo/
│
├── AGENTS.md ─────────────── yours. untouched, except one delimited pointer block
├── .orly/AGENTS.md ────────── the always-on rules and the standards index
│
├── CLAUDE.md ─────────────── one import line; the only file Claude Code loads itself
├── opencode.json ─────────── names both rule files; opencode loads nothing by default
│
├── .orly/standards/ ──────── the rules, one page per language or domain
├── .orly/skills/ ─────────── full skill instructions
├── .claude/agents/ ───────── the standards reviewer
│
├── .claude/skills/ ───────── thin discovery entries per agent host
├── .agents/skills/
├── .opencode/skills/
│
├── .orly/hooks/ ──────────── pinned bunx pre-commit and pre-push calls
└── .orly/orly.json ─────── which packs, which commands, what orly installed

orly init also seeds .orly/orly.json with any gate commands it finds in your Makefile or package.json. Fill in the rest, commit it, and every clone gates identically.

What happens on every commit

flowchart TD
    edit["agent edits a file"] --> rule["the rule page for that file kind fires"]
    rule --> commit["git commit"]
    commit --> pre["pre-commit hook runs orly gate"]
    pre -->|red| back["blocked: back to EXECUTE"]
    back --> edit
    pre -->|green| push["git push runs pre-push hook"]
    push --> prgate["orly gate pr"]
    prgate -->|red| back
    prgate -->|green| open["Pull Request opens"]

Three checkpoints, all running your own declared commands:

The loop you live in

orly init is the setup. This is one task, from prompt to Pull Request.

The spec is a file on disk, and its directory is the status. Only the stages named in the rules move it.

flowchart TB
    you["🤠 you<br/>add webhook retries"]
    agent["🦉 agent<br/>writes the spec"]
    pending["📄 docs/v1/pending/<br/><small>spec committed on default branch</small>"]

    you --> agent
    agent --> pending
    pending -->|"CHORE(open)"| plan

    subgraph active["⚙️ docs/v1/active/"]
        direction TB

        plan["PLAN<br/><small>understand spec · resolve decisions</small>"]
        execute["EXECUTE<br/><small>make the change</small>"]
        conform["CONFORM<br/><small>apply matching rule pages</small>"]
        verify["VERIFY<br/><small>run deterministic gates</small>"]
        review["REVIEW<br/><small>review the resulting diff</small>"]
        document["DOCUMENT<br/><small>update docs / evidence</small>"]
        commit["COMMIT<br/><small>record the completed unit</small>"]

        plan --> execute
        execute --> conform
        conform --> verify
        verify --> review
        review --> document
        document --> commit

        conform -. "gate fails" .-> execute
        verify -. "gate fails" .-> execute
        review -. "changes required" .-> execute
    end

    commit -->|"CHORE(close)"| done["✅ docs/v1/done/<br/><small>all gates green</small>"]
    done --> pr["Pull Request"]

Inside active/, work runs through the stages: PLAN → EXECUTE → CONFORM → VERIFY → REVIEW → DOCUMENT → COMMIT.

The stages are not a status. active/ is the status. The stages are the loop that runs on the spec sitting there.

Three things do three different jobs, and keeping them apart is what makes the lifecycle mechanical:

Each edit activates the rule page for that file kind. A gate proves whether the work may advance, and any red returns the agent to EXECUTE. No stage can be skipped quietly.

Your files stay yours

AGENTS.md stays yours. orly writes its rules beside it and points at them from one delimited block.

The last two files deliver rules through each runtime's loader. Codex and Amp auto-load AGENTS.md, which carries the pointer block onward.

Claude Code loads CLAUDE.md and nothing else. opencode loads only what its instructions name.

orly writes the required import when the loader is missing and refreshes its own delimited block or recognized generated loader. Unrelated owner content stays unchanged. Resolved links inside the repository are preserved; unresolved or escaping links refuse the update.

[!WARNING] orly refuses unowned conflicting content and executable owner hooks. Review explicit --force or --no-hooks choices before proceeding. Preflight conflicts preserve owner bytes. An interruption during writes may leave completed steps and a journal; rerun to recover after resolving conflicts.

Commands

Which packs you get

Chosen by your source

orly scans four directories deep. It skips node_modules, target, .venv, and the other dependency trees, so one stray file cannot select a language you do not write.

Pack	Selected when your source has
language.typescript	.ts, .tsx
language.javascript	.js, .jsx
language.rust	.rs
language.go	.go
language.python	.py
language.shell	.sh
language.mdx	.mdx
domain.sql	.sql

Installed everywhere

Opt-in, only when .orly/orly.json names them

gstack and EGM are required

orly's skills call gstack for code review and the Elephant-Goldfish Model (EGM) for spec review. Any version works, because both upgrade themselves.

orly doctor checks that every agent runtime on the machine has both. A missing one turns it red and prints the install command; the skills stop until it is green. A machine with no agent runtime, such as a CI runner, skips the check.

[!NOTE] The three orly skills (orly-spec, orly-build, orly-ship) and the reviewer come from orly's workflow.skills pack, per repository. gstack and EGM install per agent host.

Local development

For working on orly itself. Pull requests are welcome.

Prerequisites

Set up

git clone [email protected]:agentsfleet/orly.git && cd orly
git config core.hooksPath .githooks
bun install --frozen-lockfile
make audit

The bar

make audit is the bar. If it passes, the change is reviewable. Its steps run in parallel, around half a minute:

• orly verify: the standards catalogue, the root render and every pack copy
• typecheck and unit tests, including render determinism
• gate fixtures: every gate proved against one passing and one failing case

Every commit here runs bin/orly gate work, which runs orly verify. A push runs gitleaks only, and CI runs make audit on every pull request.

Coverage is gated at a 90% line floor. The workflow fails below it.

Install evals

Real installs into throwaway repositories. They cost about twice the local chain's wall-clock, so they run on demand:

make install-evals

CI runs them on every pull request and release.

Rendering orly's own rules

orly governs itself with the same verb everyone else uses:

bin/orly update --no-hooks

--no-hooks because this checkout hand-wrote its .githooks/, and orly refuses to replace hooks it did not write.

Releasing

Merge to main with a new package.json version. That publishes it, tags it, and cuts a GitHub release. There is no second command to remember.

Try it

Run this in a repository you own. It writes nothing until you drop the flag.

bunx @agentsfleet/orly init --dry-run

It prints the rules it would install, already rendered for the languages it found in your source. Read them. If you disagree with one, that is the point: your own AGENTS.md overrides it.

Then hand your agent the prompt orly was built for:

Read .orly/AGENTS.md. Tell me which of my last ten commits would have tripped a
gate, and name the rule that caught each one.

License

MIT