RepoGrammar: Instructions file for Claude Code

Repository Agent Contract

Authority

• This file and its mirror are the repository's compact, mandatory agent contract. They must remain byte-for-byte identical.
• Read docs/README.md, then the relevant files under .agents/skills/, .agents/memories/, and docs/ before changing code.
• After editing either mirrored guide, immediately run cargo run --quiet --bin repo-guard -- sync-agent-guides --from <edited-file>.
• Do not create nested AGENTS.md, CLAUDE.md, override files, or competing instruction files without explicit maintainer approval.

Repository Boundaries

• Put all source, executable, test, benchmark, migration-tool, fixture-source, and automation-tool code under src/.
• Outside src/, only manifests, lockfiles, configuration, documentation, non-code assets, and generated build output are allowed.
• Rust tests live beside modules under #[cfg(test)], in src/rust/integration_tests/, or in another documented path under src/.
• Keep nontrivial CI and repository automation logic in src/rust/bin/repo_guard.rs; declarative workflow files may only invoke it.
• Respect the module boundaries and dependency direction defined in docs/architecture/.

Change Discipline

• Inspect repository status and existing instructions before editing. Preserve unrelated user changes.
• Make the smallest coherent change. Do not perform unrelated refactors, broad formatting, dependency upgrades, or speculative rewrites.
• For nontrivial implementation work, use parallel agent teams where independent slices exist. Assign disjoint ownership, preserve other agents' and users' edits, and integrate results only through the main session after review.
• After implementation, inspect the changed code logic before accepting or merging agent-team output into the main session. Verify behavior with the required checks and resolve conflicts semantically, not by blindly choosing one side.
• During active implementation, batch validation at coherent feature or workstream checkpoints instead of running tests after every small helper or subchange. Run early targeted tests only when they materially unblock diagnosis or protect high-risk behavior; final required checks still gate completion, commit, and merge.
• Treat checkout-local and agent-worktree Cargo target/ directories as disposable build caches, not project history. After the required gate for a completed workstream, clean only exact Git-ignored, untracked, inactive targets under docs/development/testing.md; never delete worktrees, Git state, evidence, or user changes as cache cleanup.
• Every code change must include corresponding tests and documentation changes in the same atomic commit.
• Current v0.1 implementation planning is tracked in docs/plans/v0.1-parallel-development-plan.md, docs/plans/python-v0.1-implementation-plan.md, and durable memories under .agents/memories/. Update those plan/memory files whenever phase scope, Python v0.1 analysis, CodeGraph provider integration, or UNKNOWN policy changes.
• Update normative requirements in docs/, reusable workflows in .agents/skills/, durable learned context in .agents/memories/, and only cross-cutting mandatory rules in this mirrored contract.
• Never leave duplicated requirements inconsistent. Update the canonical document and every affected reference.