docs: add AGENTS.md scaffolding and cross-tool agent instructions

[Alberto-Codes]

Summary

Create an AGENTS.md file for the docvet repository and update docvet init (#150) to scaffold AGENTS.md alongside CLAUDE.md, .cursorrules, and .github/copilot-instructions.md.

Background

AGENTS.md is a new universal standard for project-level AI agent instructions, donated to the Agentic AI Foundation (Linux Foundation) by OpenAI. It is supported by:

• OpenAI Codex CLI
• Cursor
• Windsurf
• Kilo Code
• GitHub Copilot (reads it alongside .github/copilot-instructions.md)

It uses plain Markdown with hierarchical placement (root + per-package). The spec lives at agents.md.

Scope

1. Create AGENTS.md for docvet itself

An AGENTS.md at the repo root documenting:

• How to run docvet checks
• Development conventions (Google-style docstrings, from future import annotations, etc.)
• Test commands and patterns
• Key architecture notes

2. Update docvet init (#150) to scaffold AGENTS.md

When docvet init runs on a user's project, it should offer to create/update:

• AGENTS.md — universal agent instructions
• CLAUDE.md — Claude Code specific
• .cursorrules — Cursor specific
• .github/copilot-instructions.md — Copilot specific
• .windsurfrules — Windsurf specific

Each file gets a docvet-specific snippet: "After modifying Python functions, run docvet check --files <changed_files> and fix all findings before committing."

References

• AGENTS.md Specification
• AGENTS.md GitHub Repository
• GitHub Blog: How to Write a Great agents.md
• OpenAI Codex AGENTS.md Guide

Related

• feat: add docvet init command for agent-ready project scaffolding #150 (docvet init — this issue adds AGENTS.md to its scope)
• docs: add AI Agent Integration section to README #153 (README AI section — complementary, different surface)
• chore: audit and expand GitHub/PyPI discoverability metadata #156 (Discoverability — AGENTS.md is a discovery mechanism)

[Alberto-Codes]

Research Findings: Agent Instruction Delivery Mechanisms (2026-02-26)

Before implementing this issue, we researched the AGENTS.md ecosystem, security landscape, and alternative delivery mechanisms. Key findings:

1. No Python package ships AGENTS.md in pip distributions

Zero established packages (ruff, black, mypy, pytest, pylint) include agent instruction files in their built artifacts. Ruff has a contributor-facing CLAUDE.md in its source repo — not shipped with the package. The pattern today is repo-level contributor docs, not package-level user docs.

2. No established linter/formatter scaffolds agent instructions into user projects

Only agent-specific tools do this (agentmd CLI, Claude Code /init). No traditional dev tool generates AGENTS.md/CLAUDE.md into user projects.

3. AGENTS.md files are confirmed prompt injection vectors

Multiple CVEs assigned for agent instruction file attacks:

• CVE-2025-54135 (Cursor CurXecute, CVSS 8.6)
• CVE-2025-53773 (GitHub Copilot RCE, CVSS 7.8)
• CVE-2025-59536 (Claude Code, CVSS 8.7)

The "Your AI, My Shell" paper (arXiv:2509.22040) tested 314 attack payloads and achieved 41-84% success rates. Snyk's ToxicSkills audit found 13.4% of agent skills contained malicious payloads.

A tool that scaffolds "always run me" instructions into user projects creates a supply chain trust escalation — indistinguishable from an attack vector to the agent reading the file.

4. MCP is the tool-native approach

SonarQube and ESLint (eslint --mcp) provide agent guidance through MCP tool descriptions and the instructions field in InitializeResult, not by injecting files. The MCP approach is scoped, dynamic, and doesn't masquerade as project-authored content.

Decision: Option B — AGENTS.md + publishable snippets

Based on this research, we're splitting the scope:

In scope for this issue (Story 22.3):

• Create AGENTS.md at docvet's repo root, focused on helping agents use docvet (not contribute to docvet's codebase)
• Publish copy-paste agent integration snippets on the docs site that users manually add to their own projects
• Template snippets for AGENTS.md, CLAUDE.md, .cursorrules, .github/copilot-instructions.md

Deferred / reconsidered:

• docvet init scaffolding agent files into user projects (feat: add docvet init command for agent-ready project scaffolding #150) — needs security-conscious redesign. Should print snippets to stdout or show them interactively rather than silently writing files. The trust boundary implications are significant.
• MCP server (feat: MCP server for agentic AI integration #149) is the preferred long-term mechanism for tool-native agent instructions

Research sources

• AGENTS.md Specification
• GitHub Blog: How to Write a Great agents.md
• OpenAI Codex AGENTS.md Guide
• arXiv:2509.22040 — "Your AI, My Shell"
• Snyk ToxicSkills Study
• OWASP Top 10 for Agentic Applications 2026
• SonarQube MCP Blog Post