Adopting Roteiro in your own repository is one command. roteiro init
scaffolds the store, installs the git hooks that keep it fresh and gate drift,
and writes an AGENTS.md snippet so your AI agents are graph-aware.
# From the root of your git repository
roteiro init
# builds the initial graph (stored under .git/, not committed)
# installs managed git hooks (see below)
# writes/updates an AGENTS.md section pointing agents at the graphinit sets up| Piece | What it does |
|---|---|
| The store | A content-addressed graph under .git/ — per-worktree, shared cache, never committed. |
post-checkout · post-merge · post-commit hooks | Keep the graph fresh automatically as HEAD moves — no manual sync. |
pre-commit hook | Runs roteiro check and blocks a commit that introduces drift (a dangling ADR link, a stale @rto: annotation, or an #[allow(…)] that says why it is there in neither a reason = "…" field nor a comment). Skip once with git commit --no-verify. |
AGENTS.md | A managed section telling agents to query the graph and to run roteiro review/check — the cross-tool standard many agents read. |
After init, the hooks keep the graph current for you. As you work:
# Review your change against the graph — not just the diff:
# each touched symbol's callers/callees, the ADRs governing it, the
# drift & intent-debt it adds, and the dependents to re-check.
roteiro review
# Verify authored intent still holds (the pre-commit hook runs this too):
roteiro check
# Explain any node, or trace how two are connected:
roteiro query 'sym:rust:src/lib.rs#Thing'
roteiro path 'file:src/main.rs' 'adr:0001'Make the graph a merge gate — check exits non-zero on drift, so a PR
that breaks an ADR link or annotation fails the build:
# In your pipeline (validates the committed HEAD tree)
cargo install roteiro --locked # or download a release binary
roteiro check --committed[[path#Symbol]] wiki-links) and inline // @rto:<adr-id>
annotations. check keeps them honest; roteiro spec helps you
draft house-style, graph-grounded ADRs to begin with.