Agent Governance Framework

Canonical policy for repo-wide agent governance, native adapter files, rule taxonomy, and retirement of legacy rule surfaces.

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 family	Approved canonical path	Notes
OpenAI Codex / repo-wide baseline	AGENTS.md	Cross-agent baseline and the primary repo-wide rules file.
GitHub Copilot	.github/copilot-instructions.md	Native Copilot adapter. Path-scoped .github/instructions/*.instructions.md remains optional.
Claude Code	.claude/CLAUDE.md	Native Claude adapter under a dedicated root directory.
Cursor	.cursor/rules/*.mdc	Native Cursor rules location.
Windsurf	.windsurf/rules/*.md	Native Windsurf rules location.
Augment Code	.augment/rules/*.md	Native Augment adapter directory added in Phase 9.
Mintlify Assistant	.mintlify/Assistant.md	Chat widget context for the docs site. Not an AI coding assistant adapter.
Codex task layer	.github/AGENTS.md	Codex-specific HitL, checkpoint, and lock rules — extends root AGENTS.md via directory-walk.

Current implementation state:

Target path	Current status
AGENTS.md	implemented canonical repo-wide baseline
.github/copilot-instructions.md	implemented thin native adapter
.claude/CLAUDE.md	implemented thin native adapter
.cursor/rules/*.mdc	implemented thin native adapter
.windsurf/rules/*.md	implemented thin native adapter
.augment/rules/*.md	implemented thin native adapter (Phase 9)
.mintlify/Assistant.md	implemented chat widget context (Phase 9)
.github/AGENTS.md	implemented 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

Recommended shared rules

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 domain	Canonical sources
Docs routing and navigation	docs.json
Repo orientation and maintainer workflow	README.md, docs-guide/contributing/**
Internal governance and architecture map	docs-guide/**
Current user-facing docs	v2/**
Hook and structure enforcement	.githooks/pre-commit, .githooks/pre-push
Local preview port policy	AGENTS.md, native adapter files, contributor agent instructions
Root governance	docs-guide/policies/root-allowlist-governance.mdx
Agent governance	docs-guide/policies/agent-governance-framework.mdx
Validator enforcement	operations/scripts/validators/governance/*
Codex operational governance	.codex/*, operations/scripts/dispatch/ai/codex/*

Current Active Rule Inventory and Overlap Map

Surface	Current role	Classification	Migration target
AGENTS.md	repo-wide baseline covering safety, source-of-truth order, structure, and validation expectations	must-have canonical	canonical source
.github/copilot-instructions.md	GitHub Copilot adapter with only GitHub-specific path guidance	native adapter	keep thin
.claude/CLAUDE.md	Claude Code adapter	native adapter	keep thin
.cursor/rules/repo-governance.mdc	Cursor adapter	native adapter	keep thin
.cursor/rules/no-deletions.mdc	Cursor no-deletions rule	native adapter	keep thin
.windsurf/rules/repo-governance.md	Windsurf adapter	native adapter	keep thin
.augment/rules/repo-governance.md	Augment Code adapter (Phase 9)	native adapter	keep thin
.augment/rules/git-safety.md	Augment Code git safety rules (Phase 9)	native adapter	keep thin
.augment/rules/no-deletions.md	Augment Code no-deletions rule (Phase 9)	native adapter	keep thin
.mintlify/Assistant.md	Mintlify chat widget context (Phase 9)	chat assistant context	not an AI coding adapter
.github/AGENTS.md	Codex task-layer HitL / checkpoint extension	Codex task layer	keep as Codex-only extension
docs-guide/contributing/agent-instructions.mdx	human-facing contributor workflow doc	recommended supplemental	keep as contributor-facing summary with links to canonical policies
ai-tools/agent-packs/*	generated cross-agent adapter outputs	recommended supplemental	keep generated; never treat as canonical source
.codex/README.md	Codex local lock guidance	recommended supplemental	keep as operational documentation
.codex/task-contract.yaml	Codex task contract	recommended supplemental	keep as operational contract
.codex/locks-local/*	Codex local lock state	recommended supplemental	keep as operational state, not rule docs
operations/scripts/validators/governance/check-agent-docs-freshness.js	validator for canonical agent governance docs and adapters	recommended supplemental	keep 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 surface	Retirement status	Replacement
.github/AGENTS.md	repurposed as Codex task-layer extension (Phase 9)	disambiguating comment added; Codex reads both files via directory-walk
ASSISTANT.md	repurposed as redirect stub (Phase 9)	.mintlify/Assistant.md (chat widget)
.github/augment-instructions.md	retired; added archived-reference header (Phase 9)	.augment/rules/ (correct Augment path)
ai-tools/ai-rules/.augment-guidelines	retired to ai-tools/ai-rules/_retired/ (Phase 9)	.augment/rules/git-safety.md
ai-tools/ai-rules/.cursor/rules/no-deletions.mdc	moved 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 surface	Approved destination
.github/AGENTS.md	repurposed as Codex task-layer extension; disambiguating comment added
ASSISTANT.md	redirect stub; canonical content moved to .mintlify/Assistant.md
.github/augment-instructions.md	archived; replaced by .augment/rules/ (correct canonical Augment path)
duplicated repo-policy blocks inside .github/copilot-instructions.md	reduced 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

• OpenAI Codex: AGENTS.md
• Claude Code memory and project instructions
• Cursor rules for AI
• Windsurf memories
• Windsurf AGENTS.md
• GitHub Copilot custom instructions
• Mintlify Assistant