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.
Augment Code.augment/rules/*.mdNative Augment adapter directory added in Phase 9.
Mintlify Assistant.mintlify/Assistant.mdChat widget context for the docs site. Not an AI coding assistant adapter.
Codex task layer.github/AGENTS.mdCodex-specific HitL, checkpoint, and lock rules — extends root AGENTS.md via directory-walk.
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
.augment/rules/*.mdimplemented thin native adapter (Phase 9)
.mintlify/Assistant.mdimplemented chat widget context (Phase 9)
.github/AGENTS.mdimplemented Codex task-layer extension

​
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
  • local preview port policy (3000 forbidden for agent-run Mintlify/preview sessions)
  • 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, docs-guide/contributing/**
Internal governance and architecture mapdocs-guide/**
Current user-facing docsv2/**
Hook and structure enforcement.githooks/pre-commit, .githooks/pre-push
Local preview port policyAGENTS.md, native adapter files, contributor agent instructions
Root governancedocs-guide/policies/root-allowlist-governance.mdx
Agent governancedocs-guide/policies/agent-governance-framework.mdx
Validator enforcementoperations/scripts/validators/governance/*
Codex operational governance.codex/*, operations/scripts/dispatch/ai/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
.cursor/rules/no-deletions.mdcCursor no-deletions rulenative adapterkeep thin
.windsurf/rules/repo-governance.mdWindsurf adapternative adapterkeep thin
.augment/rules/repo-governance.mdAugment Code adapter (Phase 9)native adapterkeep thin
.augment/rules/git-safety.mdAugment Code git safety rules (Phase 9)native adapterkeep thin
.augment/rules/no-deletions.mdAugment Code no-deletions rule (Phase 9)native adapterkeep thin
.mintlify/Assistant.mdMintlify chat widget context (Phase 9)chat assistant contextnot an AI coding adapter
.github/AGENTS.mdCodex task-layer HitL / checkpoint extensionCodex task layerkeep as Codex-only extension
docs-guide/contributing/agent-instructions.mdxhuman-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
operations/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.mdrepurposed as Codex task-layer extension (Phase 9)disambiguating comment added; Codex reads both files via directory-walk
ASSISTANT.mdrepurposed as redirect stub (Phase 9).mintlify/Assistant.md (chat widget)
.github/augment-instructions.mdretired; added archived-reference header (Phase 9).augment/rules/ (correct Augment path)
ai-tools/ai-rules/.augment-guidelinesretired to ai-tools/ai-rules/_retired/ (Phase 9).augment/rules/git-safety.md
ai-tools/ai-rules/.cursor/rules/no-deletions.mdcmoved to .cursor/rules/no-deletions.mdc (Phase 9)project-root Cursor path

​
Overlap clusters

Resolved in Phase 9:
  • .github/AGENTS.md now carries disambiguating HTML comment; no longer a duplicate of root AGENTS.md
  • ASSISTANT.md is a redirect stub; canonical content at .mintlify/Assistant.md
  • .github/augment-instructions.md is archived; replaced by .augment/rules/
Remaining:
  • docs-guide/contributing/agent-instructions.mdx still contains contributor-facing parts of the policy set; reduce to a link to AGENTS.md in a future pass
  • 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.mdrepurposed as Codex task-layer extension; disambiguating comment added
ASSISTANT.mdredirect stub; canonical content moved to .mintlify/Assistant.md
.github/augment-instructions.mdarchived; replaced by .augment/rules/ (correct canonical Augment path)
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 legacy assistant surfaces 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/
.augment/rules/          ← added Phase 9
.mintlify/Assistant.md   ← added Phase 9 (chat widget only)
.github/AGENTS.md        ← Codex task-layer extension only
Supporting notes preserved from the prior report, updated for Phase 9:
  • Codex should use AGENTS.md as the cross-repo baseline; .github/AGENTS.md adds Codex-specific task-isolation rules
  • 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
  • Augment Code should use .augment/rules/*.md
  • Mintlify chat widget reads .mintlify/Assistant.md — this is not an AI coding assistant adapter

​
Report Sources

​
Repo evidence

  • .github/AGENTS.md
  • .github/copilot-instructions.md
  • .github/augment-instructions.md
  • ASSISTANT.md
  • docs-guide/contributing/agent-instructions.mdx
  • 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
  • operations/scripts/validators/governance/check-agent-docs-freshness.js
  • docs-guide/tooling/ai-tools.mdx
  • docs-guide/policies/root-allowlist-governance.mdx

​
Official external sources

Last modified on April 7, 2026