Skip to main content
This runbook keeps AGENTS.md and nested AGENTS files high-signal and low-noise.

​
Goals

  • keep always-loaded agent context concise
  • avoid duplication across constitution.md, AI_GUIDE.md, and AGENTS.md
  • preserve non-discoverable “landmine” guidance
  • detect stale instructions before they mislead agents

​
Canonical Responsibilities

  • constitution.md: normative guardrails and policy
  • AI_GUIDE.md: implementation process and spec workflow
  • AGENTS.md: quick reference, routing, and canonical “What AI Must NEVER Do”
  • nested src/**/AGENTS.md: module-scoped constraints and routing

​
Landmine Date Markers

When adding a non-discoverable gotcha, include [YYYY-MM]. Example:

​
Staleness Audit

Run periodically (full scan of the default high-traffic agent docs):
Fail CI/governance on stale markers:
The strict check flags [YYYY-MM] markers older than 90 days.

​
Changed-file scoping (PRs)

The default run scans a fixed list of high-traffic agent docs. To scope to only the agent docs a PR changed — so any core’s AGENTS.md is covered, not just the default three — pass --since=<ref> and/or explicit paths:
The PR step in docs-coverage.yml runs --since=origin/<base_ref> (warn-only during burn-in). “Agent doc” means any AGENTS.md (root or nested), AI_GUIDE.md, or constitution.md/.mdc; other changed paths in the diff are skipped.

​
Maintenance Cadence

  • monthly:
    • run staleness audit
    • prune duplicated/discoverable instructions
    • verify links and command references
  • quarterly:
    • run agents-memory-updater maintenance pass in Cursor
    • review high-churn module AGENTS files for size and relevance

​
agents-memory-updater Workflow

Suggested prompt:
Apply suggested edits only after human review.