Maintaining Agents Md

Maintain Agent Governance Files

Scope: $ARGUMENTS

Keeps agent governance files synchronized with codebase state. Detects stale references, missing updates, and promotion candidates.

Governance Files

| File | Authority | Purpose | |------|-----------|---------| | AGENTS.md | Behavioral | Rules, role boundaries, compliance requirements | | CONTRIBUTING.md | Technical | Workflows, commands, coding standards | | AGENT_LEARNINGS.md | Knowledge | Accumulated patterns and solutions | | AGENT_REQUESTS.md | Escalation | Active blockers requiring human input |

When to Use

• After PRs that change project structure, commands, or patterns
• At sprint start/end for governance health check
• When promoting patterns from AGENT_LEARNINGS.md to .claude/rules/
• After make validate pipeline or Makefile changes
• When adding/removing skills or plugins

Modes

audit (default)

Scan governance files for staleness and inconsistencies.

Checks:

1. Stale paths: Grep governance files for src/, docs/, tests/ paths.

Verify each path still exists.

1. Stale commands: Parse CONTRIBUTING.md command reference table. Verify

each make recipe exists in Makefile.

1. Missing learnings: Check recent git log for patterns not yet in

AGENT_LEARNINGS.md. If ralph/docs/LEARNINGS.md exists, check it too.

1. Resolved requests: Check AGENT_REQUESTS.md entries — flag any whose

referenced files/issues no longer exist.

1. Role boundary drift: Verify AGENTS.md role definitions match current

.claude/skills/ inventory.

Output: Findings table with file, line, issue type, description.

sync

Fix staleness found by audit. For each finding:

1. Propose the specific edit
2. Apply on user approval
3. Follow priority order: AGENTS.md > CONTRIBUTING.md > AGENTLEARNINGS.md > AGENTREQUESTS.md

promote

Evaluate AGENT_LEARNINGS.md entries for promotion per the criteria in .claude/rules/compound-learning.md (3rd occurrence → rule, recurring → skill).

Procedure:

1. Read AGENT_LEARNINGS.md entries
2. Grep codebase for each pattern's problem statement
3. If pattern appears in 3+ locations or has been referenced in 3+ commits,

recommend promotion to .claude/rules/

1. Draft the rule file content for user approval

full

Run all three modes in sequence: audit → sync → promote.

Maintenance Priority Order

When multiple files need updates, follow this order to prevent hierarchy conflicts:

1. AGENTS.md — behavioral rules first (highest impact)
2. CONTRIBUTING.md — technical standards second
3. AGENT_LEARNINGS.md — patterns third (high-value, low-risk)
4. AGENT_REQUESTS.md — escalations last (time-sensitive, not structural)

References

• .claude/rules/compound-learning.md — promotion path
• CONTRIBUTING.md "Documentation Hierarchy" — authority structure
• AGENTS.md "Decision Framework" — anti-redundancy rules

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: qte77
• Source: qte77/claude-code-plugins
• License: Apache-2.0
• Homepage: https://qte77.github.io/claude-code-plugins/

Install and usage instructions live in the source repository linked above.