> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livepeer.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```text icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
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](https://developers.openai.com/codex/guides/agents-md)
* [Claude Code memory and project instructions](https://code.claude.com/docs/en/memory)
* [Cursor rules for AI](https://docs.cursor.com/context/rules-for-ai)
* [Windsurf memories](https://docs.windsurf.com/plugins/cascade/memories)
* [Windsurf AGENTS.md](https://docs.windsurf.com/windsurf/cascade/agents-md)
* [GitHub Copilot custom instructions](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions)
* [Mintlify Assistant](https://www.mintlify.com/docs/guides/assistant)