canon/usage.md

usage.md — operating Savante

Practical instructions: install, invoke, adapt, wire into CI, and read the verdicts.

Install

Into one repository:

git clone https://github.com/cryptoAGI/savante
cp    savante/.claude/agents/savante.md  <your-repo>/.claude/agents/
cp -r savante/.claude/skills/sagi        <your-repo>/.claude/skills/

For every project on the machine, use ~/.claude/agents/ and ~/.claude/skills/ instead.

The agent type registers at the next Claude Code session start. Until then the /sagi skill's fallback path works immediately (it instructs a general-purpose agent to adopt the charter).

Invoke

Inside Claude Code, any of:

/sagi review the payment router changes
have savante review the parsec-wallet production readiness
savante: is this suite deploy-ready?
render a verdict on <claim>

Give it a claim to verify, not a vibe to discuss: "production-ready?", "does the code do what QUANTUM.md says?", "should this merge?". Savante verifies — it runs the tests and reports actual counts, reads the actual git state, greps for the capability a document asserts. Reviews of a full repo take minutes, not seconds; that is the verification running.

Read the verdict

FINDINGS       what is KNOWN, with file:line evidence
               + "not yet known" items, each with its deciding experiment
VERDICT:       APPROVE | APPROVE_WITH_CONDITIONS | REJECT | DEFER
RATIONALE:     the deciding constraint, board-minute style
CONDITIONS:    numbered; each independently verifiable
RISKS WATCHED: what Savante keeps watching if this proceeds

Interpretation:

• APPROVE — the claim survived verification as stated.
• APPROVE_WITH_CONDITIONS — sound core, enumerated gaps; the conditions are the work list, each one checkable when done.
• REJECT — the claim failed against evidence; the rationale names where.
• DEFER — the decision belongs to the operator's signature, not to gatherable evidence. Treat as "stop and ask the human," never as failure.
• not yet known — not hedging: a fact about the current evidence, with the experiment that would decide it. Run the experiment, re-review.

Re-reviews: after satisfying conditions, invoke again with "re-verify the conditions from the last savante review of ."

Adapt to your repository

Edit one section of .claude/agents/savante.md — "Canon you measure against" — to point at your own doctrine documents (architecture docs, ADRs, strategy files). Optionally adjust the standing constraints to your project's equivalents (budget baseline, governance gates). If your charter lives at a nonstandard path, update the absolute path in the skill's fallback instruction. Everything else — epistemology, verdict contract, read-only tools — is the invariant core; leave it.

No canon at all still works: Savante measures claims against the code itself.

CI gate (headless)

# .github/workflows/savante.yml
name: savante
on: [pull_request]
jobs:
  verdict:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - name: Savante review gate
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          out=$(claude -p "Invoke the sagi skill: review this branch's diff
            against the base branch. Print ONLY the verdict block." \
            --allowedTools "Read,Grep,Glob,Bash")
          echo "$out"
          echo "$out" | grep -qE 'VERDICT.*APPROVE'   # blocks on REJECT/DEFER

Use grep -qE 'VERDICT.*: *APPROVE$' to also block on APPROVE_WITH_CONDITIONS. Add a step posting CONDITIONS as a PR comment if you want the work list surfaced.

Scheduled audit

# weekly: one verdict over the week's changes
claude -p "Invoke the sagi skill: review everything changed in the last 7
days (git log --since='7 days ago'); render one verdict per subsystem." \
  --allowedTools "Read,Grep,Glob,Bash"

Cron it and route the output wherever your team reads reports. This is the standing-audit mode: rarely intervenes, always watching.

Boundaries (by design)

• Savante never edits files — it has no Write/Edit tools. If a review should lead to fixes, that is a separate, ordinary coding task afterward.
• Savante does not approve what it has not read. Point it at what matters; it reads before it rules.
• Savante renders DEFER rather than guessing on operator-jurisdiction decisions. That is the charter working, not a limitation.