Proposal: Governance Policy Section in AGENT.md Spec

[imran-siddique]

Proposal: Governance Policy Section in AGENT.md Spec

Problem

AGENT.md currently focuses on coding agent behavior: build commands, code style, boundaries, and project structure. However, as agents become more autonomous - executing code, making API calls, delegating to sub-agents - there's a missing piece: governance policies.

Organizations deploying agents need a standardized way to express:

• Security constraints - What patterns/actions are forbidden (with regex/glob support)
• Resource limits - Max tokens, tool calls, execution time per task
• Trust requirements - Minimum trust scores for agent delegation
• Audit requirements - What must be logged and how
• Compliance rules - Data handling, PII protection, geographic restrictions

Proposed addition

A Governance section in AGENT.md that uses YAML to define enforceable policies:

yaml governance: policy: name: "production-safety" version: "1.0" max_tokens_per_request: 4096 max_tool_calls_per_request: 10 blocked_patterns: - pattern: "rm -rf /" type: substring - pattern: ".*password.*=.*['\"].*['\"]" type: regex - pattern: "*.env" type: glob allowed_tools: - read_file - search_code - edit_file trust: min_delegation_score: 0.7 require_identity_verification: true audit: level: full merkle_chain: true

Why this matters

1. Universal enforcement - Any AGENT.md-aware tool (Copilot, Cursor, Codex, etc.) could enforce these policies
2. Declarative - Policies are versioned alongside code, reviewed in PRs, auditable
3. Machine-readable - YAML in markdown is parseable; agents can self-enforce
4. Composable - Root-level governance applies globally; subdirectory AGENT.md files can tighten (never loosen) policies
5. Standards alignment - Maps to CSA's Agentic Trust Framework and emerging AI governance standards

Reference implementation

We've built a working implementation in Agent-OS:

• GovernancePolicy data class with YAML import/export
• PatternType enum (substring, regex, glob) with pre-compiled patterns
• Policy diff/comparison (is_stricter_than)
• Event hooks for violations
• 700+ tests

Happy to contribute a spec section, validation schema, and reference parser.

Ask

Would the maintainers be open to adding a governance section to the AGENT.md specification? This would make AGENT.md the single source of truth for both how an agent should work and what constraints it must operate within.

[imran-siddique]

Closing - project moved to microsoft/agent-governance-toolkit. Will re-submit fresh proposals from the Microsoft repo. Thank you!