ARI is an Agent Skills-compatible protocol and toolchain for producing a snapshot-bound, evidence-traceable project canon. It images code, configuration, tests, data contracts, CI/CD, infrastructure, documentation, and authorized runtime observations, then publishes the strongest account the captured evidence supports.
It combines an agent orchestration protocol with deterministic standard-library utilities that preserve inventory and custody through validation and publication. A run follows a governed imaging workflow rather than a single repository-analysis command.
ARI is deliberately stricter than an architecture summary. It separates direct observations from inference. Disputes and unknowns remain visible, as do exclusions and stale evidence. ARI can prove coverage of a named discovery universe under declared methods. That result cannot establish metaphysical completeness or certify project correctness and security.
Profiles at Canon depth or higher publish one validated CANON.md as their
public entry point. Its terminal human briefing contains:
- a 100–150 word TL;DR;
- a one-page executive brief;
- a representative system heartbeat;
- one coherent memory-palace analogy with a literal bridge to real components and edges;
- one grounded, GitHub-renderable Mermaid architecture diagram; and
- a provenance and evidence footer that also states unknowns and staleness.
Those views are compiled from the same settled ledgers as the detailed canon. They do not trigger another scan, swarm, model, or independent architecture. The validator rejects missing, templated, uncited, or ungrounded briefing blocks.
The private run workspace also preserves the machine-verifiable basis:
| Artifact | Purpose |
|---|---|
run.json, scope.json, snapshot.json, inventory.json |
Frozen authority and subject; exact discovery universe |
sections.json, claims.jsonl, edges.jsonl, disagreements.jsonl |
Semantic ownership, assertions, boundaries, and unresolved conflict |
packets/, reports/, evidence/ |
Independent examination and exact evidence custody |
CANON.draft.md |
Pre-publication reconstruction |
coverage.json, validation.json |
Separate raw coverage dimensions and gate results |
CANON.md, canon.lock.json |
Published canon and exact-hash publication lock |
Survey runs remain DRAFT and cannot publish a closed canon.
flowchart TB
A["1. Freeze<br/>scope + snapshot"]
B["2. Discover<br/>units + edges"]
C["3. Image independently<br/>anatomy + physiology"]
D["4. Reconcile<br/>claims + boundaries"]
E["5. Challenge<br/>bounded gaps"]
F["6. Reconstruct<br/>canon + briefing"]
G["7. Validate + publish<br/>CANON.md"]
A --> B --> C --> D --> E --> F --> G
Each material claim must resolve to current admissible evidence. Independent agreement counts as overlap when the reviewers share the same evidence; corroboration requires independent evidence. Negative claims remain bounded by their searched universe and exact method.
ARI's default diagram is a page-width briefing. Wall-sized graphs fail the
briefing contract. The diagram must remain readable at normal GitHub or editor
width without zooming or horizontal scrolling. The canon contract therefore requires a portrait-first
TB/TD layout for larger flowcharts, no more than 12 major nodes, short
wrapped labels of at most 32 visible characters per line, and one level of
architectural abstraction. A compact LR view is permitted only for four or
fewer nodes; sequence views stop at six participants. Detailed evidence,
secondary edges, and long identifiers belong in adjacent prose or the
reality-bridge table—not in tiny diagram text.
| Profile | Intended use | Required imaging |
|---|---|---|
| Survey | Fast, full-surface orientation | One consistent anatomy or physiology pass at I1 or higher; always DRAFT |
| Canon | Default trustworthy project canon | Independent anatomy and physiology passes at I2 over every section |
| Deep | Material uncertainty and dynamic behavior | Canon plus an independent contrast lane at I2 and authorized validation scenarios |
| Assurance | Highest procedural confidence | Three independent I3 lanes with cross-model, cross-method review |
| Incremental | Refresh a previously sealed canon | Exact change impact, reverse invalidation, and targeted independent rescans |
Scan depth and agent topology are recorded separately. ARI never represents a
solo repeat as independent review. I1 means classified, I2 means traced,
and I3 means directly observed under a captured environment; authorization
is still required before execution.
- Python 3.9 or newer; the runtime uses only the Python standard library.
- A POSIX-like shell environment on macOS, Linux, or WSL.
- Git for remote ref resolution and repository snapshot metadata.
- Host and operator authorization for any action beyond static reads.
Native Windows execution is not claimed; use WSL.
The safest installation path is a reviewed local checkout:
git clone https://github.com/sirouk/ari-skill.git
cd ari-skill
./install.sh install --targets autoauto detects compatible local hosts without launching them. Use all to
install every supported physical target, or choose explicit targets:
./install.sh install --targets shared,claude,hermesThe agent handoff includes the convenience bootstrap for an agent-managed installation. Review remote bootstrap code before piping it to a shell. For reproducible installation, use a reviewed checkout or pin both the bootstrap URL and payload resolution to a trusted full commit:
COMMIT=<trusted-40-character-commit>
curl -fsSL "https://raw.githubusercontent.com/sirouk/ari-skill/${COMMIT}/install.sh" \
| ARI_COMMIT="$COMMIT" sh -s -- install --targets autoPaste this into the agent that should install ARI:
Install or update the ARI skill from https://github.com/sirouk/ari-skill.
Run exactly:
`curl -fsSL https://raw.githubusercontent.com/sirouk/ari-skill/main/install.sh | sh -s -- install --targets auto`
Record every destination printed by the installer. For each installed ARI
directory, verify that SKILL.md, agents/openai.yaml, payload.manifest.json,
.ari-install.json, install.sh, and scripts/ari_doctor.py exist. Then run:
`python3 <ARI_DIR>/scripts/ari_doctor.py --skill-dir <ARI_DIR>`
and require ARI_DOCTOR OK with zero errors.
If sandboxing blocks a standard skill-home write, report the exact destination
and ask for the required permission. Do not silently choose a different path,
disable the sandbox, or use a symlink.
Tell me to reload or restart the agent host before invoking ARI. For Codex,
use `$ari` or select ARI through the skills interface; do not assume `/ari` is
a built-in command. Gemini may use `/skills reload`; Hermes uses
`/reload-skills`. Other hosts should be restarted or have their skill registry
refreshed when cached.
Explain that every managed ARI invocation checks for an update before creating
a run. A canonical update may be applied automatically, but the agent must then
stop, reload/restart, and invoke ARI again. It must never continue imaging with
instructions loaded before the update. Dirty, custom-source, or provenance-
mismatched installs require an explicit operator decision; never force them.
Do not start an ARI scan yet. Return the installed destinations, doctor result,
reload instruction, and how to invoke `$ari` after reload.
| Target | Default user installation | Hosts |
|---|---|---|
shared |
${AGENTS_HOME:-$HOME/.agents}/skills/ari |
Codex, Gemini CLI, OpenCode, Cursor, GitHub Copilot, and Agent Skills-compatible hosts |
claude |
${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/ari |
Claude Code |
hermes |
${HERMES_HOME:-$HOME/.hermes}/skills/software-development/ari |
Hermes Agent |
Aliases codex, gemini, opencode, cursor, and copilot resolve to the
shared target. User and project scopes, an exact --dest, dry runs, offline
status, and managed uninstall are supported. See
the portability contract for the complete matrix.
Choose the install scope explicitly when auto is not the intended result:
# User scope for every supported host
./install.sh install --scope user --targets all
# Project-local availability for shared hosts and Claude Code
./install.sh install --scope project --project "$PWD" --targets shared,claude
# One exact nonstandard destination
./install.sh install --dest /absolute/path/to/skills/ariHermes has no universal project-scope directory; use an explicit --dest for
that case. Installation scope controls which agent hosts can discover ARI. It
does not define the project that a later ARI run will image.
After refreshing the host's skill registry, invoke ARI explicitly. For example:
Use $ari to build a Canon-profile project canon for this repository.
Other natural triggers include “ARI this project,” “MRI this codebase,” “establish project ground truth,” and “refresh the project canon.” Canon is the default profile for an explicit ARI request.
ARI creates its mutable run state outside the subject project by default. It instructs the host to use native subagents where available; optional cross-model federation can strengthen overlap, but ARI has no dependency on a particular transport or model provider.
ARI does not update in the background. Update awareness is the first visible
step of every managed invocation, before a run workspace or project snapshot is
created. ARI checks the exact physical installation against the explicit
canonical source/ref and writes a private, hash-bound
ari.update-preflight.v1 receipt. Run creation imports and re-verifies that
exact receipt without making its own network claim.
| Result | ARI behavior |
|---|---|
UP_TO_DATE |
Continue to run creation with the receipt bound into methodology custody |
UPDATE_AVAILABLE on an unchanged canonical install |
Apply through the transactional installer, then stop and require reload/restart plus a fresh ARI invocation |
LOCAL_CHANGED or dirty local source |
Preserve local work and ask whether to stop, repair, or explicitly replace it |
PROVENANCE_MISMATCH |
Skip remote lookup and require the operator to confirm the trusted source/ref |
| Other error or unavailable network | Report the limitation and ask whether to stop or continue with qualified update awareness |
An offline check verifies installed bytes only. It does not establish that the
installation matches the latest publisher state. .ari-install.json records
custody and provenance; it is never authority to redirect future updates.
After any applied update, do not resume the current imaging attempt. Reload the
host so it reads the new SKILL.md and scripts, invoke $ari again, and let the
new version repeat its preflight. ARI refuses updates after ari_run.py start.
For one installed destination, declare the trusted source once:
ARI_DIR="${AGENTS_HOME:-$HOME/.agents}/skills/ari"
ARI_SOURCE="https://github.com/sirouk/ari-skill.git"
"$ARI_DIR/install.sh" status --dest "$ARI_DIR" \
--source "$ARI_SOURCE" \
--ref main
"$ARI_DIR/install.sh" update --dest "$ARI_DIR" \
--source "$ARI_SOURCE" \
--ref mainTo check or update every detected coordinator installation from a checkout,
reuse the same ARI_SOURCE value:
./install.sh status --targets auto \
--source "$ARI_SOURCE" --ref main
./install.sh update --targets auto \
--source "$ARI_SOURCE" --ref mainThe remote bootstrap also supports a direct manual update:
curl -fsSL https://raw.githubusercontent.com/sirouk/ari-skill/main/install.sh \
| sh -s -- update --targets auto \
--source "$ARI_SOURCE" --ref mainA reviewed checkout remains the clearest manual update path.
For project scope, repeat the original --scope project --project PATH flags.
For an exact install, use update --dest ARI_DIR as shown above. Managed
uninstall follows the same target/scope/destination selection with the
uninstall action.
Use --offline for local integrity-only status. Use --force only after the
operator explicitly chooses to replace a reported local modification or
unmanaged destination. Every manual update still requires the same host reload
before ARI is used.
- The subject project is read-only by default; mutable imaging state is kept in a private external workspace.
- Repository files, comments, fixtures, and tool output are treated as untrusted evidence, never as governing instructions.
- Builds, tests, containers, network calls, credentialed commands, migrations, and live-system inspection require the host and operator authorization they normally require.
- Secret values never belong in packets, ledgers, logs, or the canon. ARI records names, providers, paths, and flow instead.
- Managed installs fetch immutable commit-pinned payload bytes and verify the payload manifest before staging or execution.
- SHA-256 custody detects accidental or local payload mutation; it is not a substitute for signed publisher identity or repository-account security.
- Multi-target installation provides process-lifetime transactional rollback, not a claim of crash-atomic commit across filesystems.
Closure means the scoped imaging procedure closed. It does not mean that the project is correct, safe, deployed as configured, or free of undiscoverable behavior.
ari-skill/
├── SKILL.md # Agent-facing workflow and closure law
├── agents/openai.yaml # Codex UI metadata
├── assets/ # Canon, packet, and report templates
├── references/ # Protocol, evidence, canon, authoring, portability
├── scripts/ # Inventory, run, validation, finalization, updates
├── scripts/tests/ # Hermetic standard-library test suite
├── payload.manifest.json # Exact installed-payload allowlist and hashes
└── install.sh # Portable installer and update bootstrap
README.md, repository metadata, and CI are intentionally excluded from the
installed payload manifest so agent hosts load only the operative skill.
No third-party Python packages are required:
python3 -m unittest discover -s scripts/tests -q
python3 scripts/build_payload_manifest.py --check
python3 scripts/ari_doctor.py --skill-dir .
sh -n install.shWhen an operative payload file changes, rebuild the manifest once after all edits are stable:
python3 scripts/build_payload_manifest.pyThe release suite covers inventory and snapshot custody, evidence and closure gates, adversarial mutation cases, refresh invalidation, final publication, portable installation, update receipts, and rollback behavior.
- Imaging protocol
- Evidence model
- Canon and publication contract
- Machine-ledger authoring example
- Portability and distribution
ARI is released under the MIT License.