review-agents-tree

Audit the tracked `AGENTS.md` tree against best practices, write `.agents/AGENTS_TREE_REVIEW.md`, and propose cleanup, compaction, conflict resolution, or sharding when needed. May auto-apply only tri

SKILL.md

GitHub

review-agents-tree

Manual durable-context hygiene pass.

Not a workflow gate. Not a replacement for distill-knowledge.

Run this periodically to keep the tracked AGENTS.md tree lean, conflict-free, and aligned with current code/tests.

Read first

  • ../references/persistent-artifacts-contract.md
  • ../../references/communication-mode.md
  • root tracked AGENTS.md
  • all tracked local AGENTS.md files under the repository
  • tracked AGENTS.override.md paths only to detect misuse or drift; never treat them as canonical repo truth
  • relevant code/tests only when a guidance conflict or staleness finding needs verification

Scope

This skill owns:

  • periodic best-practice audit of the tracked AGENTS.md tree
  • writing .agents/AGENTS_TREE_REVIEW.md
  • proposing cleanup, compaction, conflict resolution, and sharding plans
  • auto-applying only trivial non-semantic hygiene fixes when they are clearly safe
  • being the only non-distill skill allowed to touch tracked AGENTS.md, and only for those trivial non-semantic hygiene fixes

It does not own:

  • writing AGENTS.override.md
  • semantic doctrine changes without explicit human approval
  • shard creation, shard moves, or meaning-changing conflict resolution without explicit human approval
  • task-local packet work unless a current task explicitly asked for this audit as part of that packet

Audit workflow

  1. Discover the tracked tree.
    • Enumerate all tracked AGENTS.md files.
    • Note any tracked AGENTS.override.md files as likely hygiene smells.
    • Build the effective hierarchy from root downward.
  2. Audit file shape.
    • Confirm every tracked AGENTS.md has ## Scope.
    • Confirm section names stay canonical when present.
    • Flag missing, tautological, or low-value ## Scope sections.
    • Flag ## Entrypoints sections in deep leaf shards when they add no real wayfinding value.
    • Confirm other sections are present only when they contain real content.
    • Flag files that drift from canonical section names.
  3. Audit lean-ness.
    • Treat broad overview prose, directory dumps, repeated boilerplate, and generic cookbook content as compaction smells.
    • Treat roughly 200+ lines as a review trigger for compaction or sharding, not an automatic failure.
  4. Audit specificity.
    • Flag vague, non-verifiable instructions.
    • Prefer exact commands, stable owner/module names, hard constraints, and durable rationale.
    • Treat raw file-path links as a fragility smell unless they are unusually stable and clearly necessary.
  5. Audit hierarchy quality.
    • Flag parent/child duplication when the child adds no meaningful specialization.
    • Flag local files that restate root doctrine instead of carrying only boundary-local guidance.
    • Flag guidance placed too high or too low relative to the stable owner boundary.
  6. Audit conflicts and ambiguity.
    • Flag contradictory rules across parent/child tracked files.
    • Flag ambiguous wording that could lead different agents to make different choices.
    • Verify suspicious conflicts against code/tests before concluding.
  7. Audit staleness.
    • Flag stale paths, commands, owner/module references, or other brittle anchors.
    • Flag entries that are now better encoded in code/tests and should be pruned.
  8. Audit for task-state leakage.
    • Flag plan recaps, worklog residue, temporary migration notes, or current-task chatter that belongs in .plans/*, not tracked AGENTS.md.
  9. Decide whether a trivial hygiene fix is safe.
    • Safe auto-fix classes:
      • section heading normalization to canonical names
      • whitespace / formatting cleanup
      • deduping exact duplicate bullets
      • removing obviously broken file references when the correct target is unambiguous
      • reordering within one section when meaning does not change
    • If any fix changes meaning, defers a judgment call, or changes topology, do not apply it automatically.
  10. Write .agents/AGENTS_TREE_REVIEW.md.
    • Summarize current tree health.
    • Record any auto-applied hygiene fixes.
    • Emit concrete findings and approval-gated proposals.

Findings categories

Use compact AT# findings.

Good finding classes:

  • bloated file that should be compacted
  • duplicated guidance across parent/child files
  • conflict or ambiguity between tracked layers
  • stale path/command/reference
  • task-local residue leaking into durable context
  • missing, tautological, or low-value Scope
  • low-value leaf Entrypoints
  • fragile raw file-path links
  • file broad enough that sharding should be considered
  • tracked AGENTS.override.md or override misuse smell

Best-practice bar

A strong tracked AGENTS.md tree is:

  • lean
  • specific
  • path-scoped by stable owner boundary
  • conflict-free
  • low-duplication
  • explicit about commands/validation, constraints, and durable decisions only where needed
  • consistently shaped, with a lean non-tautological Scope in every tracked file
  • sparing with Entrypoints, mainly at root/hub levels
  • resistant to path fragility

Report shape

Default .agents/AGENTS_TREE_REVIEW.md should include:

  • Status: healthy | needs_cleanup | needs_approval_for_refactor
  • Auto-applied hygiene fixes:
  • AT# findings: ordered by severity
  • Approval-gated proposals:
  • Suggested next pass: no_op | compact_existing_files | apply_semantic_cleanup_after_approval | propose_sharding_after_approval

Do not

  • treat AGENTS.override.md as canonical repo context
  • auto-apply semantic changes
  • auto-create new tracked shards
  • auto-merge or move tracked shards
  • rewrite guidance just to make it prettier
  • preserve stale or redundant prose because it feels helpful

Initiative-mode note

Initiative packets and child packets are not tracked durable memory. Review them only if a human explicitly asks how they should later distill into tracked AGENTS.md.

Communication

Honor active caveman mode for user-facing replies per ../../references/communication-mode.md. Keep durable artifacts normal unless the human asks otherwise. Drop caveman for safety/clarity when needed, then resume.