Skip to content

AGENTS_MD_ENTERPRISE_EVIDENCE_CHECKLIST.md

Latest commit

 

History

History
253 lines (175 loc) · 10.7 KB

AGENTS_MD_ENTERPRISE_EVIDENCE_CHECKLIST.md

File metadata and controls

253 lines (175 loc) · 10.7 KB
Raw

AGENTS.md Enterprise Evidence Checklist

Purpose

This checklist helps maintainers turn AGENTS.md from a basic instruction file into a reviewable evidence entry point for agentic repositories.

It is an independent educational contribution by Karunanidhi Mishra. It is not an Agentic AI Foundation project, not a Linux Foundation project, and not endorsed by either organization.

The goal is practical developer activation: in about 20 minutes, a maintainer should be able to add clearer agent instructions, human approval gates, validation commands, secret boundaries, and review evidence without claiming production readiness.

Source Anchors

Who Should Use This

Use this checklist if your repository includes AI coding agents, agentic workflows, MCP-style tools, automated actions, generated code, or maintainer-assistive automation.

It is useful when:

  • contributors need exact setup, test, and validation commands
  • agent instructions need clearer boundaries than a README can provide
  • maintainers want to document what an agent may inspect, edit, run, or publish
  • a repository uses paid providers but should offer OSS or local alternatives
  • reviewers ask how tool side effects, approvals, and audit evidence are handled

Do not use it to claim certification, AAIF status, Linux Foundation status, external adoption, or production readiness.

20-Minute Implementation Path

Minute Action Evidence created
0-3 Add or open AGENTS.md at the repository root Predictable agent instruction entry point
3-6 Add setup, test, lint, build, and smoke commands Reproducible contributor path
6-9 Define allowed and disallowed agent actions Tool/action boundary
9-12 Add human approval gates for secrets, billing, deployment, destructive data, and legal changes Human-in-the-loop evidence
12-15 Link security, governance, contribution, and roadmap docs Review packet spine
15-18 Add OSS fallback notes for paid APIs, hosted databases, model providers, queues, and storage Fork-friendly provider posture
18-20 Run validation and record the result in the PR or release note Live proof instead of intent

Minimum AGENTS.md Sections

Every agentic repository should answer these questions:

Section Question it answers Minimum evidence
Purpose What is this repository trying to do? One paragraph, no marketing claims
Setup commands How does a contributor start safely? Exact install and environment steps
Validation commands What must pass before a change is credible? Test, lint, typecheck, build, smoke, or documented reason unavailable
Editable surfaces Which files can an agent change without special approval? Scoped paths or module boundaries
Restricted surfaces Which files require human approval? Secrets, infra, billing, auth, legal, data migration, release config
Tool boundaries Which commands, network actions, and external services are allowed? Allowed, ask-first, and never-run categories
Human approval gates When must a human decide? Deployment, public posting, upstream comment, credential, cost, legal, destructive data
Evidence expectations What proof must accompany a change? Commands run, checks passed or failed, screenshots only when UI was inspected
Anti-claims What must not be inferred? No endorsement, no certification, no production-readiness claim without proof

Copy-Ready Starter Block

Use this as a starting point and then replace the bracketed values with repository-specific details.

# AGENTS.md

## Purpose

This repository provides [short product or library purpose]. Keep changes evidence-based, contributor-friendly, and free of endorsement or production-readiness claims unless public proof exists.

## Setup Commands

- Install dependencies: `[package manager install command]`
- Start local runtime: `[dev command or documented not applicable]`
- Run validation: `[test/lint/typecheck/build command]`
- Optional smoke: `[local smoke command or documented not applicable]`

## Editable Surfaces

Agents may edit:

- `[source path]`
- `[docs path]`
- `[tests path]`

Agents must ask before editing:

- secrets, `.env`, credentials, tokens, or private keys
- billing, payment, deployment, DNS, or cloud infrastructure
- database migrations, destructive scripts, or retention policy
- legal, license, CLA, trademark, or public affiliation language
- upstream comments, public forum posts, or maintainer tagging

## Tool And Command Boundaries

Allowed without approval:

- read-only repository inspection
- local validation commands listed above
- formatting commands that affect only the current change set

Ask first:

- dependency installation that changes lockfiles
- network calls, package publishing, release creation, or deployment
- comments on external issues, pull requests, forums, or social platforms

Never do:

- expose secrets
- claim foundation, employer, maintainer, or external endorsement without public evidence
- run destructive cleanup, reset, prune, or data deletion commands without explicit approval

## Evidence Expectations

For meaningful changes, record:

- what changed
- what was not touched
- commands run
- checks passed, failed, or blocked
- whether proof is live runtime evidence or static inspection

## Related Review Artifacts

- Readiness profile: `[agentic-readiness.json path if present]`
- Boundary model: `[AGENTIC_BOUNDARY_MODEL.md path if present]`
- Security policy: `[SECURITY.md path]`
- Contribution guide: `[CONTRIBUTING.md path]`
- Roadmap: `[ROADMAP.md path]`

Before And After Model

Weak AGENTS.md:

# AGENTS.md

Run npm install and npm test. Follow existing style.

Enterprise evidence AGENTS.md:

# AGENTS.md

Run `npm test` before claiming validation. Do not edit `.env`, billing, deployment, database migrations, public release notes, or upstream comments without human approval. When a change touches agent actions, update `docs/AGENTIC_BOUNDARY_MODEL.md` and record commands run in the PR.

The stronger version does not become long for its own sake. It names the work boundary, the proof boundary, and the human approval boundary.

Tool Boundary Checklist

Record each tool or command family as one of three states:

State Meaning Examples
Allowed Safe for routine contributor work npm test, npm run lint, rg, read-only local inspection
Ask first May change cost, public state, data, or ownership dependency upgrades, release creation, cloud deployment, public comments
Never without explicit approval High-risk or legal/credential action secret exposure, destructive deletion, legal agreement, foundation affiliation claim

For MCP-style tools, connector actions, browser automation, or generated-code publishing, add side-effect notes:

  • reads local files
  • writes local files
  • calls external API
  • changes persistent data
  • sends user-visible communication
  • starts a cost-bearing resource
  • publishes a public artifact

Human Approval Gates

Require a human decision when a change affects:

  • credentials or secret storage
  • paid providers or billing configuration
  • deployment, release, DNS, package publishing, or GitHub visibility
  • identity, RBAC, tenant isolation, audit retention, or policy enforcement
  • destructive database, storage, or filesystem operations
  • public statements about affiliation, endorsement, contributor status, adoption, or certification
  • upstream OSS comments, maintainer tagging, or foundation/forum posts

These gates protect maintainers from accidental public claims and hidden operational cost.

OSS Fallback Notes

If the repository uses a paid or hosted provider, AGENTS.md should point contributors to the local or OSS alternative when one exists.

Provider class Examples Fallback note to include
LLM provider hosted model APIs local model, OpenAI-compatible endpoint, mock provider, or no-network test mode
Database hosted Postgres, serverless SQL local Postgres, SQLite test mode, containerized dev database, or migration-only validation
Object storage S3-compatible storage MinIO, local filesystem adapter, or dry-run mode
Queue/events hosted queue, workflow service local queue, in-memory adapter, or replay fixture
Auth hosted auth service local dev issuer, mock sessions, or documented manual test account
Payments hosted billing sandbox mode, mock checkout, or disabled billing path for contributors

Do not include real keys, private URLs, customer examples, or privileged setup instructions.

Review Evidence Checklist

Before opening a PR or publishing a release, attach evidence:

  • AGENTS.md updated when agent behavior or contributor flow changed
  • docs/AGENTIC_BOUNDARY_MODEL.md updated when tool actions, approvals, or side effects changed
  • validation command run locally or in CI
  • failed checks recorded with reason and next action
  • no secret values committed
  • no public endorsement or affiliation claim added
  • no upstream maintainer tagged without direct relevance
  • no production-readiness claim added without runtime proof

One-Comment Reviewer Ask

Use this when asking for feedback:

I am looking for technical correction, not endorsement.

This AGENTS.md evidence checklist tries to make agent instructions easier to review by naming setup commands, allowed actions, human approval gates, tool side effects, OSS fallbacks, and anti-claims.

Which one part would make a real repository safer or easier to contribute to, and which one part is too heavy?

AAIF Ambassador-Style Contribution Boundary

This artifact can support an AAIF Ambassador-style monthly contribution because it is public, project-based, and tied to AGENTS.md developer activation.

It does not claim:

  • AAIF Ambassador acceptance
  • AAIF endorsement
  • Linux Foundation endorsement
  • AGENTS.md project approval
  • maintainer review
  • external adoption

The next valid recognition signal is a public external review, accepted upstream PR, public routing comment, opt-in adoption trial, or official AAIF acceptance.

Maintainer Outcome

After applying this checklist, a maintainer should have:

  • one predictable agent instruction entry point
  • one clear validation path
  • one human approval boundary
  • one provider-fallback path for developers
  • one honest review ask that invites correction without implying endorsement