# agentproto

> Open numbered standards (AIPs) for the markdown files AI agents read, write, and run from, plus a reference TypeScript runtime any agent framework can consume.

agentproto publishes open, numbered specifications — called AIPs (Agentproto Improvement Proposals) — for the markdown files that AI agents read, write, and operate from. The project is hosted on GitHub under CC-BY-4.0 for specs and MIT for code, and currently sits at version 0.1.0-alpha with 47 proposals in the registry.

## What It Is

agentproto is a community standards registry for the AI-agent ecosystem, modeled after ERC (Ethereum), BIP (Bitcoin), and PEP (Python) improvement proposal processes. Each AIP is a numbered markdown specification that defines a single primitive — a skill manifest, a tool contract, a governance policy, an operator profile — so that any agent runtime can consume the same file without rewriting it. The project's README frames the motivation as: every serious agent system is converging on a folder of markdown files the agent reads, writes, and runs from, but without a shared vocabulary there is zero interoperability — "Is it `skill.title` or `skill.name`? Does `AGENTS.md` mean Codex's flavour, Cursor's flavour, or yours?"

## The AIP Registry Structure

The 47 proposals in the registry are organized into 8 semantic layers, each answering a distinct question about agents:

- **Process** — how the standard itself evolves (AIP-1, AIP-2)
- **Primitives** — shared building blocks like IO, RUNNER, COLLECTION, SECRETS, REF
- **Identity** — who acts: OPERATOR, IDENTITY, PERSONA
- **Memory** — what the agent remembers: KNOWLEDGE, LESSON, PLAYBOOK
- **Work, Org & Governance** — COMPANY, GOVERNANCE, AGENCY, WORK, OFFICE, ASSEMBLY
- **Capabilities** — SKILL, TOOL, WORKFLOW, INTENT
- **Drivers** — how capabilities are implemented: DRIVER, CLI, HTTP, MCP, SDK
- **Surfaces** — what the agent produces or reads: DESIGN, CANVAKIT, CODE

Final-status specs are considered stable; Draft and Review specs may change before promotion.

## Why Markdown, Not YAML or JSON

The README explains the design choice directly: agents read the file every turn, so prose in a SKILL.md can carry behavioral semantics — "if the document isn't an invoice, return `{ error: 'not_an_invoice' }` — don't hallucinate fields" — and the model acts on that instruction each run. YAML frontmatter holds the typed fields machines need; the prose body holds the behavioral contract the model reads. The same intent in JSON is described as "dead data"; in a compiled function it is "locked into a release."

## Relationship to MCP and A2A

The project's FAQ explicitly positions AIPs as complementary to, not competing with, existing protocols. MCP solves tool transport; AIPs specify the layer above transport and below frameworks — where context lives, roles are defined, and memory is structured. A TOOL.md contract (AIP-14) can be served over MCP, HTTP, CLI, or in-process via the DRIVER layer (AIP-30 through AIP-33). A2A solves agent-to-agent communication; AIPs address how a single agent's components are structured on disk.

## Self-Modifying Agents and the Runtime

The reference TypeScript runtime lives in the separate `agentproto/ts` repository and exposes packages including `@agentproto/tool`, `@agentproto/driver`, `@agentproto/agencies`, `@agentproto/governance`, and `@agentproto/ref`, with framework adapters for Mastra and ai-sdk. Because every component — memory, runtime, governance, work backlog — is a file with a declared contract, the README argues that self-modification "stops being a research problem and becomes a `write_file` call": an agent can add a new tool by writing a TOOL.md and DRIVER.md to disk, swap an OpenAI call for a Replicate one by adding a second DRIVER and updating policy, or deploy itself by running its own CLI driver against its own files.

## Current Status: 0.1.0-alpha

The GitHub repository was created in April 2026 and last pushed in May 2026. The project self-describes as "0.1.0-alpha" with specs stabilizing and minor breaking changes expected between alpha releases. The registry currently holds 47 AIPs, with AIP-1 through AIP-6 at Final status and AIP-7 onward at Draft or Review.

## Features
- 47 numbered AIP specifications organized into 8 semantic layers
- Markdown-based specs with YAML frontmatter for typed fields and prose for behavioral semantics
- Final, Draft, and Review status tiers for spec stability
- Reference TypeScript runtime with packages for tool, driver, agencies, governance, and ref
- Framework adapters for Mastra and ai-sdk
- MCP driver specialization (AIP-32) alongside HTTP, CLI, and SDK drivers
- Governance primitives: audit, approval, and policy as files (AIP-7)
- Memory primitives: KNOWLEDGE, LESSON, PLAYBOOK (AIP-10, 11, 12)
- Multi-agent collective workspace with council, voting, peer, and hierarchy modes (AIP-24)
- LLM-friendly /llms.txt and /llms-full.txt endpoints
- CC-BY-4.0 specs license with MIT code license
- Contribution workflow via GitHub PRs using AIP-2 template

## Integrations
Mastra, ai-sdk, OpenAI Codex, Anthropic Claude, MCP (Model Context Protocol), HTTP, CLI, Replicate

## Platforms
WEB, API, CLI, DEVELOPER_SDK

## Pricing
Open Source

## Version
0.1.0-alpha

## Links
- Website: https://agentproto.sh
- Documentation: https://agentproto.sh/docs
- Repository: https://github.com/agentproto/agentproto
- EveryDev.ai: https://www.everydev.ai/tools/agentproto