Skip to main content

​
Agent Governance Framework

This document is the canonical governance policy for agent-facing instructions in this repository. It remains a docs-guide/policies/ page, not a docs-guide/frameworks/ page, because canonical agent-file locations, overlap boundaries, and retirement targets are enforced governance decisions rather than optional improvement guidance. The approved governance model is:
  • one cross-agent baseline
  • one native adapter per supported agent family
  • one shared repo knowledge set
  • no policy drift between overlapping instruction files
Future governance changes must update the runtime files, validators, and this policy together.

​
Approved Canonical Layout

Approved target locations:
Agent familyApproved canonical pathNotes
OpenAI Codex / repo-wide baselineAGENTS.mdCross-agent baseline and the primary repo-wide rules file.
GitHub Copilot.github/copilot-instructions.mdNative Copilot adapter. Path-scoped .github/instructions/*.instructions.md remains optional.
Claude Code.claude/CLAUDE.mdNative Claude adapter under a dedicated root directory.
Cursor.cursor/rules/*.mdcNative Cursor rules location.
Windsurf.windsurf/rules/*.mdNative Windsurf rules location.
Current implementation state:
Target pathCurrent status
AGENTS.mdimplemented canonical repo-wide baseline
.github/copilot-instructions.mdimplemented thin native adapter
.claude/CLAUDE.mdimplemented thin native adapter
.cursor/rules/*.mdcimplemented thin native adapter
.windsurf/rules/*.mdimplemented thin native adapter

​
Governance Taxonomy

​
Must-have canonical rules

These rules must live in the canonical cross-agent baseline and must not drift by agent:
  • destructive git safety
  • hook and validation policy
  • root allowlist policy
  • source-of-truth order
  • v1 freeze / legacy content boundary
  • branch and lock governance
  • path-migration discipline
These rules should be shared across agents unless a native adapter requires different syntax:
  • response and review hygiene
  • component and style conventions
  • route-placement heuristics
  • change-propagation expectations
  • generated-file handling
  • contributor workflow norms

​
Native adapter rules

Native adapter files should contain only:
  • tool-specific file format or metadata requirements
  • minimal bootstrap instructions for that tool
  • a pointer back to the canonical repo baseline
They should not become separate copies of the full repo policy.

​
Required Repo Knowledge for Every Agent

Every supported agent must be grounded in the same repo knowledge set:
Knowledge domainCanonical sources
Docs routing and navigationdocs.json
Repo orientation and maintainer workflowREADME.md, contribute/**
Internal governance and architecture mapdocs-guide/**
Current user-facing docsv2/**
Hook and structure enforcement.githooks/pre-commit, .githooks/pre-push
Root governancedocs-guide/policies/root-allowlist-governance.mdx
Agent governancedocs-guide/policies/agent-governance-framework.mdx
Validator enforcementtools/scripts/validators/governance/*
Codex operational governance.codex/*, tools/scripts/codex/*

​
Current Active Rule Inventory and Overlap Map

SurfaceCurrent roleClassificationMigration target
AGENTS.mdrepo-wide baseline covering safety, source-of-truth order, structure, and validation expectationsmust-have canonicalcanonical source
.github/copilot-instructions.mdGitHub Copilot adapter with only GitHub-specific path guidancenative adapterkeep thin
.claude/CLAUDE.mdClaude Code adapternative adapterkeep thin
.cursor/rules/repo-governance.mdcCursor adapternative adapterkeep thin
.windsurf/rules/repo-governance.mdWindsurf adapternative adapterkeep thin
contribute/CONTRIBUTING/AGENT-INSTRUCTIONS.mdhuman-facing contributor workflow docrecommended supplementalkeep as contributor-facing summary with links to canonical policies
ai-tools/agent-packs/*generated cross-agent adapter outputsrecommended supplementalkeep generated; never treat as canonical source
.codex/README.mdCodex local lock guidancerecommended supplementalkeep as operational documentation
.codex/task-contract.yamlCodex task contractrecommended supplementalkeep as operational contract
.codex/locks-local/*Codex local lock staterecommended supplementalkeep as operational state, not rule docs
tools/scripts/validators/governance/check-agent-docs-freshness.jsvalidator for canonical agent governance docs and adaptersrecommended supplementalkeep aligned with the implemented canonical set

​
Retired Legacy Surfaces

These files were intentionally retired during the approved governance rollout and should not be recreated as active governance sources:
Legacy surfaceRetirement statusReplacement
.github/AGENTS.mdretiredAGENTS.md
.cursorrulesretired.cursor/rules/repo-governance.mdc
ASSISTANT.mdretiredAGENTS.md
.github/augment-instructions.mdretirednone; Augment is not in the current supported matrix

​
Overlap clusters

Current duplication clusters:
  • .github/AGENTS.md, .github/copilot-instructions.md, .github/augment-instructions.md, .cursorrules, and ASSISTANT.md all duplicate repo structure and safety guidance
  • contribute/CONTRIBUTING/AGENT-INSTRUCTIONS.md duplicates contributor-facing parts of the same policy set
  • ai-tools/agent-packs/* are generated from separate sources and must remain outputs, not canonical rule inputs

​
Approved Migration Map

The current governance contract maps legacy surfaces to the following destinations:
Legacy surfaceApproved destination
.github/AGENTS.mdmerged into root AGENTS.md
.cursorrulesreplaced by .cursor/rules/repo-governance.mdc
ASSISTANT.mdmerged into root AGENTS.md; no .mintlify/ASSISTANT.md adoption in the current contract
.github/augment-instructions.mdretired from the supported matrix
duplicated repo-policy blocks inside .github/copilot-instructions.mdreduced to a thin adapter that references AGENTS.md

​
Prior Reports Incorporated

This policy incorporates the following prior reports and decisions:

​
Prior report: Root entry re-review (2026-03-16)

Relevant preserved findings:
  • not everything currently discussed in .allowlist is required at repo root
  • nested agent paths such as .github/copilot-instructions.md are not valid .allowlist entries because the root gate is root-only
  • the current repo still uses ASSISTANT.md and .cursorrules, but both were identified as move or retire candidates

​
Prior report: Agent root file decision set (2026-03-16)

Approved decision set carried forward into this policy: 
USE:
AGENTS.md
.github/copilot-instructions.md
.claude/CLAUDE.md
.cursor/rules/
.windsurf/rules/
Supporting notes preserved from the prior report:
  • Codex should use AGENTS.md as the cross-repo baseline
  • GitHub Copilot should use .github/copilot-instructions.md
  • Claude Code should use .claude/CLAUDE.md
  • Cursor should use .cursor/rules/*.mdc
  • Windsurf should use .windsurf/rules/*.md

​
Report Sources

​
Repo evidence

  • .github/AGENTS.md
  • .github/copilot-instructions.md
  • .github/augment-instructions.md
  • .cursorrules
  • ASSISTANT.md
  • contribute/CONTRIBUTING/AGENT-INSTRUCTIONS.md
  • ai-tools/agent-packs/README.md
  • ai-tools/agent-packs/claude/CLAUDE.md
  • ai-tools/agent-packs/cursor/rules.md
  • ai-tools/agent-packs/windsurf/rules.md
  • .codex/README.md
  • .codex/task-contract.yaml
  • tools/scripts/validators/governance/check-agent-docs-freshness.js
  • docs-guide/catalog/ai-tools.mdx
  • docs-guide/policies/root-allowlist-governance.mdx

​
Official external sources

Last modified on March 16, 2026