On this page
  1. Findings
  2. kitty
  3. pi, by Earendil
  4. Earendil RFCs
  5. MCP
  6. ACP
  7. Matrix
  8. From general knowledge
  9. What this means for cotty
  10. Sources
  11. Not covered

How do projects that publish protocols and proposals keep their documents usable? The ones that stay readable keep a living specification and fold accepted proposals into it. The depth is in the living documents. Proposals are short, or frozen once accepted.

Findings

Every claim below is [official] unless marked otherwise: it was read on the project’s own site or in its repository on 2026-11-22.

kitty

  • The site is a user manual (quickstart, overview, FAQ, changelog and more) plus a section called “Terminal protocol extensions”. That section has 14 pages. Each page specifies one protocol and is written for authors of other terminals and programs.
  • The keyboard protocol page opens with the problems of the status quo. Then come a quickstart, an overview, progressive enhancement, detection of support, and the legacy encoding. It lists the terminals, libraries and programs that implement the protocol.
  • Requirements are written with lowercase “must” and “should”. The page carries a note “Added in version 0.20.0” and no revision history.
  • The site is built with Sphinx and the Furo theme.
  • No proposal process is visible. The pages appear to be edited directly (not verified).

pi, by Earendil

  • The pi-durable package has three layers of documents:
    • A README that works as a guide: a list of concepts, explicit rules, and more than forty runnable examples.
    • docs/spec.md, the specification. It has 7303 lines and begins “This document is normative”. Its first chapter is terms and invariants, and its last is non-goals.
    • Separate design documents.
  • packages/agent/docs/harness-v2.md is a design document of 1655 lines. It was rewritten as a whole, and the commit message says that it supersedes the earlier document and what changed. Its structure:
    • a compatibility policy at the top;
    • goals and non-goals;
    • concepts and invariants;
    • records, and traces that mark where a crash can happen;
    • recovery;
    • the API and the implementation;
    • open questions, testing strategy, implementation sequence;
    • required reading: an ordered list of files “for a fresh implementation session”.

Earendil RFCs

  • Earendil publishes RFCs at rfc.earendil.com with four-digit numbers. Its RFC 0001 defines the states draft, discussion, published, accepted and abandoned. A superseded RFC names its replacement.
  • The RFCs are short. Eight of them measured about 300 to 1900 words each, and they share no fixed set of sections.
  • The series holds company principles and investigations as well as technical decisions.

MCP

  • Proposals are called SEPs. The template has an abstract, motivation, specification, rationale, backward compatibility, security implications and a reference implementation.
  • When a SEP is accepted, the same pull request must add the specification text, the schema changes and a changelog entry. To become final, a SEP also needs a reference implementation and a conformance test that maps each requirement to a check.
  • A final SEP is frozen. Where the specification has since diverged, the specification governs.
  • A script renders the SEP files into the documentation, and the automated checks fail when the rendering is out of date.
  • The site is hosted on Mintlify, a commercial service.

ACP

  • Proposals are called RFDs. They move through Draft, Preview and Completed. Only Completed carries a stability commitment.
  • Experimental work goes behind a feature gate named after the RFD.
  • The site is hosted on Mintlify.

Matrix

  • Proposals are called MSCs. After the final comment period, a proposal waits in a state called “spec PR missing” until the change is written into the specification. That change must link to a working implementation.
  • Before a feature is in a released version of the specification, implementations use unstable prefixes.
  • The specification has released versions, v1.1 to v1.19, each with a changelog.

From general knowledge

These were not checked this time.

  • Rust keeps RFCs and, separately, the Reference.
  • TC39 proposals carry specification text and are merged into ECMA-262.
  • The IETF only appends. The definition of TCP ended up spread over many RFCs, and RFC 9293 was written to consolidate it.

What this means for cotty

  • Keep living documents and fold accepted proposals into them. This is the fold rule in Documentation system.
  • Put the depth in specifications and architecture pages. The bar for a specification page is a kitty protocol page. The bar for an architecture page is pi’s harness design.
  • Keep RFCs thin: the decision and the reasoning.
  • Take three practices from the others: only parts marked stable carry a compatibility commitment; the specification governs over the proposal; and, once there is code, each requirement maps to a test.
  • Write for implementers and for coding agents. A list of required reading tells a new session where to start.

Sources

Not covered

  • The processes of Rust, TC39 and the IETF in detail.
  • Python PEPs, Kubernetes KEPs, Wayland protocols and Tor proposals.