agent-contracts

name	agent-contracts
description	Edit the shared agent contract — the chezmoi-managed AGENTS.md / CLAUDE.md instruction files generated from home/.chezmoitemplates/agents/ partials. Use when adding, changing, or removing a durable behavior rule for the agents, or when asked to update AGENTS.md, CLAUDE.md, the shared partials, or a tool's contract residue.

Agent Contracts

The global agent contract is not hand-written per tool. It is generated by chezmoi from shared partials, so each tool stays in sync. Edit the source under home/, never the rendered target.

Architecture

Source lives in the chezmoi repo (~/.local/share/chezmoi, source root home/):

• Shared partials — home/.chezmoitemplates/agents/:
  • epistemic-honesty.md — evidence, inference, re-examination, sub-agent output.
  • engineering-contract.md — working posture, execution gate, engineering design, editing/docs.
  • rtk.md — RTK shell-command prefixing, raw-command proxying, and RTK self-checks.
  • validation-tooling.md — project-native validation, exit-code authority, bunx/uvx runners, no unrequested installers or package-manager paths.
• Per-tool templates — each composes the shared partials with {{ template "agents/<partial>.md" . }} and then adds its own residue.

Consumer map

Source template	Renders to	Tool-specific residue
home/private_dot_claude/CLAUDE.md.tmpl	~/.claude/CLAUDE.md	Maintaining-this-file, Response style, Context assumptions
home/dot_codex/AGENTS.md.tmpl	~/.codex/AGENTS.md	Pull requests
home/dot_omp/private_agent/AGENTS.md.tmpl	~/.omp/agent/AGENTS.md	none
home/dot_config/opencode/AGENTS.md.tmpl	~/.config/opencode/AGENTS.md	Secret redaction

Workflow

1. Classify the change. Is the rule a shared behavior (applies to every agent) or tool-specific?
   • Shared → edit the matching partial in home/.chezmoitemplates/agents/. The change propagates to all consumers.
   • Tool-specific → edit that tool's residue section in its *.tmpl. Do not fork shared behavior into one tool unless it is genuinely tool-specific.
2. Edit the source only. Never edit a rendered target (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, etc.) — it is overwritten on the next chezmoi apply.
3. Rewrite the section cleanly rather than appending bullets. Keep the convergence policy: shared baseline in partials, minimal residue per tool.
4. Verify the render before applying:
   • chezmoi cat ~/.codex/AGENTS.md (and the other targets) to inspect output.
   • chezmoi diff to see exactly what apply would change.
5. Apply: chezmoi apply once the diff looks right.

Adding a new consumer

When a new tool gains description-loaded instructions (e.g. a GEMINI.md or a Cursor rules file), add its source as a *.tmpl, compose the same three partials, and put only its unique rules in a residue section. No new partial is needed unless the shared content itself changes.