AI Agent Playbook

AI-assisted work is safe only when the assistant acts as a careful contributor to a live Rust monorepo. The repo contains real crates, tests, binaries, wallet features, runtime boundaries, a research corpus, and instruction surfaces under .github/. An assistant that writes confident but unsupported prose can damage the docs, the code, or both.

The operating rule is therefore evidence first: local files prove local workflow claims and implementation claims; whitepapers prove broader protocol claims; public-language boundaries prove what not to say. Anything outside those sources should stay out of shipped artifacts unless the repository adds the missing artifact explicitly.

That rule keeps public docs useful for both careful human contributors and automated contributors.

Instruction Priority

Before editing, an agent should resolve the instruction stack from concrete files, not memory. The normal reading order is:

This order matters because the active request may narrow the edit surface. A global rule might allow a broad refactor, while a scoped crate task may require a code-only patch, protected vendor boundaries, repeated review passes, or a stricter verification gate.

Agent Work Loop

The safest AI loop is short, repetitive, and skeptical:

The loop should not end at the first clean command. A test can pass while a page still overclaims privacy, a crate change widens a trust boundary, or a docs update treats target architecture as shipped implementation. The review step exists to catch those semantic failures.

For larger changes, the loop should produce durable evidence: a concise change summary or scoped verification note that another contributor can inspect later. That artifact should name the files changed, the checks run, and the remaining warnings. It should not ask future readers to trust that an invisible assistant “already checked everything.”

Safe File Operations

The local rulebook is strict about destructive actions. Agents should not remove directories, reset worktrees, or overwrite broad file sets casually. For full rewrites of text-like files, create a sibling .bak before replacing content. For normal line edits, use small patches. In a dirty worktree, assume unrelated modifications may belong to the user and do not revert them unless explicitly asked.

The practical pattern is:

1. Inspect git status --short.
2. Read the file before editing.
3. Back up full rewrites when local rules require it.
4. Apply scoped patches.
5. Run the relevant verification commands.
6. Summarize changed files and residual risks.

This is not bureaucracy. It prevents a rewrite from silently destroying user edits, touching protected areas like vendored Tari code, or discarding evidence that later review still needs.

English Artifacts, Local Chat

Repository artifacts must be written in English: docs pages, comments, code, commit messages, and generated technical notes. The chat can use another language for user communication, but shipped files should not mix languages. This keeps public docs, search, review, and future diffs consistent.

For AI agents, the rule has a second benefit. It reduces the chance that a change summary written in one language becomes public documentation in another, or that a summary can no longer be reviewed by the rest of the repository tooling.

Claim Hygiene

The strongest AI failure mode in this repo is polished concept drift. The model may write a page that sounds like product documentation for a fully shipped wallet SDK, RPC catalog, or stable service contract even when the live repo proves something narrower. The fix is not to make the prose vague. The fix is to label the evidence tier.

Use this claim table:

If a claim cannot be placed in one of those evidence lanes, it should be removed or rewritten as an open question.

Skills And Review Gates

The .github/skills/ directory is part of the local operating surface. Agents should use the matching skill when a task names it or clearly fits it. For repo execution, the common supporting skills are review skills, diagram skills, source-audit skills, Rust verification, and versioning when commits are requested.

Mermaid diagrams should use existing Mermaid support instead of image assets. Use diagrams when they clarify authority, lifecycle, object flow, or responsibility. Do not add decorative diagrams just to make a page look fuller.

For substantial docs changes, the review loop should be repeated until the latest passes stop finding significant in-scope issues. That review should be recorded in concise change notes, not merely remembered.

A source-audit pass is useful when the question is whether the final evidence really supports the claims. It should be workspace-first: inspect local files, classify claims, and call out anything unsupported or disputed.

What Not To Expose In Public Docs

Public documentation must not turn private execution internals into a user-facing manual. It may name public repository surfaces, explain safe workflow, and point to .github/ as the local instruction tree. It must not reveal hidden prompts, private credentials, unreleased operational details, or speculative internal process that a reader cannot verify in the repository.

The same rule applies to assistant summaries. A good summary says what changed and what verified. It does not expose irrelevant internal chain-of-thought, hidden credentials, or model-specific scaffolding.

Failure Modes To Catch

An agent should treat these as correctness bugs, not style preferences.

Read Next

Read Workspace for repo structure, then Get Started for the first-session loop. When reviewing protocol-facing pages, open Core Protocol API and Verification And Tests.

Evidence and Further Reading

• .github/copilot-instructions.md, .github/requirements/Z00Z_DESIGN_FOUNDATION.md, and .github/instructions/rust.instructions.md in the z00z repo define the instruction and safety stack summarized here.
• .github/skills/ contains the task-specific local procedures used for review, diagrams, versioning, and source-audit flows.
• Legal Architecture section 17 defines public-language red lines and safe narrative formulas.
• Corpus Terminology And Abbreviations Reference section 9 defines editorial guardrails for avoiding concept drift.