Agent Coding Contract

2026 Best Practice Rust Template - This is the single canonical instruction file for all AI agents. Tool-specific files (CLAUDE.md, GEMINI.md, etc.) are thin adapters that point here.

Quick Reference

Project Structure

• .agents/skills/: Executable task knowledge and canonical workflows.
• .agents/skills/harness/: Harness engineering — sensor response protocol and self-correction.
• crates/: Workspace members (libraries and applications).
• scripts/: Development, quality, and release automation.
• plans/adr/: Architecture Decision Records.
• .githooks/: Pre-commit quality enforcement.
• AGENTS.md: THIS FILE (Canonical Project Contract).

Agent Skills (.agents/skills/)

The skills index is auto-generated from skill frontmatter. Do not edit the table below manually.

Regenerate after adding/modifying skills:

bash scripts/generate-skills-md.sh

Consult .agents/SKILLS.md for the complete skills index, or read individual skill docs at .agents/skills/<name>/SKILL.md.

Multi-Agent Support

Skill symlinks are managed automatically. After cloning, run:

./scripts/bootstrap.sh    # One-command setup
./scripts/doctor.sh        # Environment diagnostics

CLI-specific directories read from .agents/skills/ via symlinks:

• .claude/skills/ → Claude Code
• .qwen/skills/ → Qwen Code
• .gemini/, .opencode/, .windsurf/ → Read directly

Session Bootstrap

The repository includes a SessionStart hook to auto-inject project context at the start of an agent session. This helps agents orient themselves quickly without manual discovery.

• Hook: hooks/session-start.sh
• Config: docflow.json
• Integration: Registered in .claude/settings.json for Claude.

Cross-Repo Context

Derived repositories should check .agents/context/ for shared conventions and related repository links.

• .agents/context/external-repos.json: Links to related repos and their agent context URLs
• .agents/context/shared-conventions.md: Cross-repo coding conventions (commit format, branch naming, PR requirements)

Merge precedence: Local repo instructions > imported context > template defaults.

Coding Conventions

Rust & Concurrency

• Edition: Rust 2024 (MSRV 1.88). Edition 2024 requires ≥1.85; 1.88 is intentional for broader codespace/toolchain compatibility. Do not bump MSRV unless required by a dependency. https://doc.rust-lang.org/edition-guide/rust-2024/index.html
• Versions: VERSION / workspace 0.0.0 is the adopter app version (start here). Template meta-releases (e.g. v0.3.x) live only in .template/CHANGELOG-TEMPLATE.md — do not sync them into VERSION.
• Safety: #![forbid(unsafe_code)] at workspace and crate roots.
• Errors: thiserror for libraries, anyhow for binaries. No unwrap() in libs.
• Async: Use tokio when you need a runtime. CLI apps that use async: prefer #[tokio::main(flavor = "current_thread")]. Sync main is fine when no async is required (sample-app).
• Async Safety & Execution: Choose execution models based on workload characteristics: keep short bounded CPU work on Tokio worker threads, offload genuinely blocking operations or long CPU work to spawn_blocking or dedicated worker pools, default to bounded concurrency/channels for backpressure, and keep lock scopes minimal (never across .await). Reference .agents/skills/tokio-performance/SKILL.md for Tokio architecture choices.
• Tracing: Minimize CLI tracing metadata (thread IDs/names) unless high-concurrency.
• Quality SSOT: ./scripts/quality-gates.sh (the xtask engine) is the single source of truth for all project quality tiers, Cargo compilation, lints, tests, and security checks.
• Harness & Tool Ownership: xtask owns project quality checks and telemetry (.agents/ci/quality-run.json). do-harness is an optional agent tool (scripts/setup-harness.sh) used for agent diagnostics (do-harness doctor) and PR readiness (do-harness pr review, do-harness pr ready). do-harness.toml delegates quality verification to ./scripts/quality-gates.sh without running duplicate Cargo/clippy/test passes. Never treat one tool's green status as proof that the other tool's checks ran.
• Diagnostics & PR Context Behavior: When do-harness is absent, use ./scripts/doctor.sh and ./scripts/quality-gates.sh. If no PR context or gh CLI is available, do-harness pr review / do-harness pr ready report missing PR context gracefully. Uncommitted working tree changes or stale evidence require a fresh ./scripts/quality-gates.sh run.
• Verification tiers: Which checks run for each lifecycle trigger (pull request / protected branch / scheduled / release) is configured in config/xtask.json (tiers map: pull-request, protected-branch, scheduled, release) — not in workflow YAML. Override per run via xtask quality run --tier <name> or $XTASK_TIER. Legacy names fast-pr and full-gate/all are aliases for pull-request and protected-branch.
• When-changed check selection: xtask quality run --changed-from <ref> uses declarative when_changed glob mappings in config/xtask.json (e.g. crates/**/*.rs -> Rust checks, scripts/**/*.sh -> ShellCheck). Use xtask quality explain --changed-from <ref> to inspect selected vs skipped checks and matched patterns. Unreadable git state fails closed by selecting all checks and recording fallback_used: true.
• Workspace documentation tests: Run cargo test --workspace --doc --all-features so restricted Cargo default-members cannot hide doctests in other members.

Security & Configuration

• Hardening: Enforce #[serde(deny_unknown_fields)] on config structs.
• Safe Loading: Use file.take(limit) and is_file() check before reading.
• Validation: Sanitize strings (is_control()) and enforce bounds on numeric fields.
• Dependencies: Declare versions in [workspace.dependencies] with caret ranges (e.g. "1" ≡ ^1). Library/template crates should ignore Cargo.lock (rely on Cargo.toml constraints); binary applications should commit it for reproducible builds. Audit with cargo tree and deny.toml. Prefer lockfile pins over exact = requirements in manifests. https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html
• Secrets: Never hardcode; use environment variables or .env.
• Template Portability: Never hardcode project name, repo URL, or author across source files. All project-specific values must derive from Cargo.toml at runtime or be rewriteable via scripts/init-template.sh. Avoid magic number thresholds — define named constants.

Quality & Workflow

• File Size: Max 500 LOC per source file.
• Docs: All public items must have /// doc comments.
• TDD: Add or update tests before implementing logic.
• Snapshots: Treat snapshot changes as behavior changes. Inspect them with cargo insta review and accept only intentional, deterministic output changes; never update snapshots just to clear a failing test.
• Search: Always use --exclude-dir=target (and .git) in search commands.
• Context: Run bash scripts/generate-llms-txt.sh after significant arch changes.
• Commits: Strictly use lowercase for the subject line (e.g., fix(scope): add ... not fix(scope): Add ...). Sentence-case or start-case will fail CI.

Change Workflow

1. Discover: Read code patterns, module structure, and .agents/ci/ci-summary.md.
2. Plan: Identify affected files and required test coverage.
3. Test-First: Add or update tests before logic implementation.
4. Implement: Write code adhering to conventions.
5. Quality Check: Run ./scripts/quality-gates.sh.
6. Commit: Use conventional commit format.

Stacked PRs (Optional)

For large features with 3+ distinct concerns, stacked PRs are available via gh stack. This is OPTIONAL — default to single-PR atomic commits. See .agents/skills/stacked-prs/SKILL.md. Requires GitHub and gh CLI. Install: gh extension install github/gh-stack

Agentic Metrics Reporting

After completing any task, write a JSON event file to .agents/events/YYYY/MM/DD/. This event-based pattern is also used for CI benchmarks in benchmarks/events/ to prevent merge conflicts. See .agents/skills/metrics-reporter/ for the schema and event writing procedures. Set human_interventions > 0 if a human corrected your code or provided rework instructions.

Release Failures (Priority 1)

If a release-failure issue is open:

1. Create a hotfix/ branch and apply the minimal fix.
2. Open a PR with the hotfix label.
3. Close the issue with: Recovered at: <TIMESTAMP>. FDRT: <HOURS>.