The Agent-First Project Standard (AFPS) defines how repositories, APIs, SDKs, CLIs, and services expose capabilities, schemas, workflows, and validation rules so independent AI agents can discover, execute, and verify them — without relying on undocumented assumptions or chat history.
README
→ docs site
→ scattered runbooks
→ source code
→ tribal knowledge
→ Slack historymanifest
→ capabilities
→ schemas
→ examples
→ executable tests
→ validation resultsThe gap is not documentation quality. The gap is conformance. A project is agent-first when an independent agent can discover its capabilities, parse contracts, execute workflows, validate outcomes, recover from known errors, and verify that documentation matches implementation.
Agent-facing docs are versioned, validated, linted, and reviewed with the same rigor as production code.
Prose may explain a capability. Structured files — OpenAPI, AsyncAPI, JSON Schema, YAML — define the contract.
Agents should not scrape and guess. A stable entry point exposes the project's manifest, capabilities, and artifacts.
Every request, command, workflow, and error case is a conformance fixture validated in CI.
Agents must know whether an action reads, writes, deletes, spends money, or triggers irreversible behavior.
Standards proposals are the highest-leverage AFPS target because they define the contracts every later implementation will copy. If a proposal is only a narrative document, an agent has to guess which paragraphs are normative, which examples are current, which schemas are authoritative, and which tests prove compatibility.
An AFPS-compliant proposal is different. It exposes the draft, conformance model, schemas, examples, vectors, open decisions, implementation packs, and verification commands as one linked artifact graph. A coding agent can then update the proposal with the same discipline expected of production code: scoped inputs, declared side effects, executable checks, and reviewable outputs.
{
"id": "standard.propose-change",
"inputs": {
"schema": "agent/schemas/change-request.schema.json",
"valid_examples": ["agent/examples/change.valid.json"],
"invalid_examples": ["agent/examples/change.invalid.json"]
},
"outputs": {
"artifacts": [
"specification/draft/*.md",
"schemas/*.schema.json",
"examples/*.json",
"test_vectors/",
"agent/implementation-packs/*.json"
]
},
"commands": [
"afps validate --target AFPS-3",
"project-specific conformance checks"
]
}Most projects should still start with manifest, capabilities, schemas, examples, non-interactive commands, and CI checks. That remains AFPS's broad adoption path.
Standards repositories add typed normative requirements, conformance targets, checkability, validation strategy, test coverage, and traceability.
At the highest maturity, prose is generated from a machine-readable standards model rather than being the primary source of truth.
The source of MUST, SHOULD, MAY, role, artifact, and verification semantics.
The claim surface: levels, required behavior, negative cases, and test identifiers.
Machine-readable contracts for every artifact agents and implementers must preserve.
Executable fixtures that keep the proposal grounded in concrete behavior.
Reviewable handoff bundles with prompts, scope, smoke tests, done criteria, and rollback.
The index that tells agents which artifacts are authoritative and how to verify them.
Implementation packs are the natural extension of AFPS for standards work. A draft says what should be interoperable. A pack says how an agent should apply that draft in one repository: files in scope, files out of scope, prompts, smoke tests, negative tests, completion criteria, and rollback steps. That makes the standards proposal operational before the ecosystem is fully standardized.
| Gate | Required behavior |
|---|---|
| Proposal gate | A change starts with problem, scope, non-goals, and affected artifacts. |
| Artifact gate | Normative text, schemas, examples, vectors, and packs move together. |
| Agent gate | Every capability has input schemas, valid and invalid examples, side effects, and commands. |
| Verification gate | A non-interactive check proves the artifact graph is complete before release. |
| Publication gate | Landing-page copy links back to source artifacts instead of becoming the source of truth. |
AFSC is the conformance profile for agent-first standards. It does not replace AFPS; it adds checks that only make sense when the project being evaluated is a standard, protocol, or specification package.
| Check | Requirement | Why it matters |
|---|---|---|
| AFSC-STD-001 | Every normative requirement has a stable ID. | Agents can cite, update, test, and report against exact obligations. |
| AFSC-STD-002 | Every normative requirement declares a conformance target. | Document, issuer, verifier, gateway, SDK, and profile obligations stop being mixed together. |
| AFSC-STD-003 | Every normative requirement declares checkability. | Machine-checkable, test-checkable, observable, policy-judgment, and human-review rules are separated. |
| AFSC-STD-004 | Every MUST has a validation strategy. | Untestable mandates are surfaced before they become conformance debt. |
| AFSC-STD-005 | Every test vector maps back to requirement IDs. | Coverage can be measured and gaps are reviewable. |
| AFSC-STD-006 | Every requirement has traceability to generated prose or a source anchor. | Human readers and agents can reconcile rendered text with the machine-readable model. |
AFSL should be treated as a higher maturity path: a standards intermediate representation that can generate human prose, schemas, tests, conformance matrices, reports, and agent instructions. A project can be AFPS-compliant before it is AFSL-native, but a standards project should become AFSL-native when ambiguity, interoperability risk, or conformance cost justifies the heavier source model.
The standard publishes requirement objects with IDs, modalities, subjects, targets, checkability, and source anchors.
Requirement objects link to schemas, examples, vectors, negative tests, conformance reports, and implementation packs.
A machine-readable standards language becomes the source of truth and generates prose, schemas, tests, reports, and agent instructions.
Documentation exists only as prose. No manifest, no schemas. Agents must infer behavior from source code.
Local manifest, structured capabilities, machine-readable I/O schemas, owners, versions, and an error model.
Adds a deployed discovery endpoint at /.well-known/agent-first.json and validated examples.
Executable examples, non-interactive CLIs, dry-run mutations, idempotency, and CI-validated behavior.
Drift detection, coverage reports, changelog enforcement, deprecation validation, security checks, and optional AFSC / AFSL maturity for standards projects.
At minimum, projects include agent/manifest.json. Deployed services additionally expose a manifest at /.well-known/agent-first.json following RFC 8615.
The manifest declares the project, its owners, the artifacts that define its contracts, and the capabilities an agent may invoke. Each capability points to a structured definition with schemas, side effects, auth scopes, errors, and examples.
{
"schema_version": "0.2",
"standard": "AFPS",
"conformance_target": "AFPS-3",
"project": {
"id": "example.crm-api",
"name": "Example CRM API",
"version": "1.8.0"
},
"owners": [
{ "team": "Platform API", "contact": "platform-api@example.com" }
],
"capabilities": [
{
"id": "customers.create",
"type": "api_action",
"path": "agent/capabilities/customers.create.yaml",
"side_effects": true,
"supports_dry_run": true,
"auth_scopes": ["customers:write"]
}
],
"last_updated": "2026-05-07"
}| ID | Requirement | Level |
|---|---|---|
| AFPS-DISC-001 | Project must include an agent manifest. | AFPS-1 |
| AFPS-CAP-003 | Every capability must define input and output schemas. | AFPS-1 |
| AFPS-CAP-004 | Every state-changing capability must declare side effects. | AFPS-1 |
| AFPS-API-001 | HTTP APIs must provide OpenAPI. | AFPS-1 |
| AFPS-CAP-007 | Capabilities must include valid and invalid examples. | AFPS-2 |
| AFPS-ERR-002 | Errors must declare retryability. | AFPS-2 |
| AFPS-CAP-008 | Examples must validate against declared schemas. | AFPS-3 |
| AFPS-CLI-001 | Agent-usable CLI commands must be non-interactive. | AFPS-3 |
| AFPS-SEC-004 | Destructive actions must declare approval requirements. | AFPS-3 |
| AFPS-TRACE-005 | Changelog entries must exist for changed capabilities. | AFPS-4 |
Selected from §9.1–9.7. The full standard defines 40+ normative requirements with explicit MUST / SHOULD / MAY semantics.
A guideline says: write better docs for agents.
A standard says: a project claiming AFPS-3 must pass tests AFPS-T001 through AFPS-T406, and failures block release unless waived.
The reference runner afps-conformance executes static, schema, API, discovery, execution, and drift tests, and emits machine-readable reports for CI.
name: Agent-First Compliance
on: [pull_request, push]
jobs:
afps:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm install -g afps-conformance
- run: afps validate --project . \
--target AFPS-3 \
--format json \
--output afps-report.json
- uses: actions/upload-artifact@v4
with:
name: afps-report
path: afps-report.jsonAFPS tests whether a project conforms to a standard. But most standards today — including W3C Recommendations — are still authored as prose, leaving agents to extract normative meaning from paragraphs.
The companion proposal AFSL — Agent-First Standards Language defines a typed source language for standards. Each normative statement becomes a structured requirement object. Human prose, JSON Schemas, SHACL shapes, conformance tests, and agent manifests are generated outputs.
AFSL → how to express a standard AFSC → how to test the standard AFPS → how to test a project against it
Concepts, manifest format, capability format, initial checklist.
JSON Schemas, conformance levels, test IDs, example projects, CI examples.
Build afps validate, publish fixtures, validate 3–5 real repositories.
MCP and A2A mappings, llms.txt guidance, AsyncAPI examples, pre-commit hooks.
Freeze schemas and required tests. Publish compatibility matrix.
AFPS compliance means a project exposes enough versioned, structured, tested, and discoverable information for an AI agent to safely operate it — without guessing from prose, source code, or chat history.