AGENTS.md Governance

Inkog supports AGENTS.md - an emerging community convention for declaring AI agent capabilities and limitations. Inkog parses these manifests and cross-validates them against actual code behavior, enabling Governance Mismatch Detection.

What is AGENTS.md?

AGENTS.md is a markdown file (similar to README.md) that declares:

Capabilities: What the agent can do
Limitations: What the agent should NOT do
Tools: Available tools and their permissions
Security Rules: Audit, approval, and logging requirements

This convention is used by AI coding assistants like Aider and Cursor to understand project-specific agent rules.

Governance Mismatch Detection

Inkog’s unique feature: cross-validation of declared behavior vs actual code.


┌─────────────────────┐     ┌─────────────────────┐
│     AGENTS.md       │     │    Actual Code      │
│  "No write access"  │ vs  │  db.write(data)     │
│  "Read-only"        │     │  file.delete(path)  │
└─────────────────────┘     └─────────────────────┘
              │                      │
              └──────────┬───────────┘
                         ▼
              ┌─────────────────────┐
              │  GOVERNANCE MISMATCH │
              │  CRITICAL Finding    │
              └─────────────────────┘

Quick Start

Create an AGENTS.md file in your project root:


# Customer Support Agent
 
## Capabilities
- Read customer records
- Search knowledge base
- Create support tickets
 
## Limitations
- Read-only database access (no writes)
- No external API calls
- Cannot delete records
 
## Tools
- database_query (read-only)
- knowledge_search
- ticket_create
 
## Security
- All actions logged
- Human approval for refunds over $100

Scan your project:


inkog scan .

Inkog will flag mismatches:


CRITICAL: Governance Mismatch
  AGENTS.md declares "Read-only database access"
  but code contains 'db.write' at agent.py:45

Supported Sections

Inkog uses semantic section extraction - it recognizes various header phrasings:

Intent	Recognized Headers
Capabilities	`## Capabilities`, `## Features`, `## What this agent can do`
Limitations	`## Limitations`, `## Constraints`, `## Restrictions`
Tools	`## Tools`, `## Available Tools`, `## Functions`
Security	`## Security`, `## Safety`, `## Rules`
Permissions	`## Permissions`, `## Access`

Constraint Detection

Inkog extracts constraints from limitation text using natural language patterns:

Text Pattern	Extracted Constraint
”Read-only access”	`read_only`, `no_write`
”No writes”	`no_write`
”Cannot delete”	`no_delete`
”No external API calls”	`no_external_api`
”No shell/command execution”	`no_exec`, `no_shell`
”No network access”	`no_network`
”No file access”	`no_file_access`
”Requires human approval”	`require_human_approval`
”Requires audit logging”	`require_audit`

Example: Full AGENTS.md


# Financial Advisor Agent
 
## Description
An AI agent that provides financial advice to customers.
 
## Capabilities
- Query customer portfolio data
- Calculate investment projections
- Search market data
- Generate reports
 
## Limitations
- Read-only access to customer data (no modifications)
- Cannot execute trades without human approval
- No access to external financial APIs
- Cannot delete any records
 
## Tools
- portfolio_query (read-only)
- market_search
- projection_calculator
- report_generator
 
## Security
- All interactions logged for compliance
- Human approval required for any trade recommendations
- PII must be masked in logs
 
## Permissions
| Resource | Access Level |
|----------|-------------|
| Customer Data | Read |
| Market Data | Read |
| Trade Execution | None |
| External APIs | None |

Mismatch Finding Types

Mismatch Type	Description	Triggered By
`write_violation`	Code writes when read-only declared	`db.write()`, `insert()`, `update()`
`delete_violation`	Code deletes when no-delete declared	`delete()`, `remove()`, `drop()`
`external_api_violation`	Code calls external APIs when forbidden	`http_request()`, `fetch()`, `curl`
`execute_violation`	Code executes commands when forbidden	`exec()`, `eval()`, `subprocess`
`network_violation`	Code accesses network when forbidden	`socket`, `connect()`, `ssh`
`file_violation`	Code accesses files when forbidden	`file_write()`, `file_delete()`

CLI Examples


# Scan project with AGENTS.md
inkog scan .
 
# Check only governance mismatches
inkog scan . -pattern governance-mismatch
 
# Output governance findings as JSON
inkog scan . -output json | jq '.findings | map(select(.governance_category))'

Compliance Mapping

AGENTS.md findings map to regulatory frameworks:

Finding	EU AI Act	NIST AI RMF	OWASP LLM
Governance Mismatch	Article 14 (Human Oversight)	MAP 1.3 (Reliability)	LLM08 (Excessive Agency)
Missing Audit	Article 12 (Logging)	MEASURE 2.2	-
Missing Approval	Article 14.1	GOVERN 1.4	LLM08

Best Practices

Keep AGENTS.md in project root - Inkog auto-detects it
Use clear limitation language - “No writes”, “Read-only”, “Cannot delete”
List all tools explicitly - Helps track tool sprawl
Declare security requirements - Audit, approval, logging
Update when code changes - Treat as living documentation
Run in CI/CD - Catch mismatches before deployment

Integration with IR

Under the hood, Inkog:

Parses AGENTS.md into DeclaredCapabilityNode IR nodes
Parses code into ToolCallNode IR nodes
Cross-validates constraints vs actual tool calls
Generates governance-mismatch-* findings

This enables framework-agnostic detection across Python, TypeScript, n8n, Flowise, Copilot Studio, and more.

Human Oversight - Article 14 compliance
Audit Logging - Logging requirements
Missing Human Oversight