README conventions

Overview

A protocol’s README.md is user-facing documentation, exposed directly on the platform.

Guidelines

  • The version at the top of README.md must match manifest.json.

  • Unlike a task script, a protocol needs no separate README-internal.md for its README.md to be shown on TDP.

  • If a protocol update only bumps which task-script version it uses, absorb that task script’s changelog entries into the protocol’s own changelog — users typically read only the protocol’s README, not the task script’s:

### <protocol version>

- Update to use task script `<namespace>/<slug>:<version>`
  - <task script changelog item A>
  - <task script changelog item B>

  • Scan for spelling errors before publishing.

  • If you insert images, add them to the images/ folder (see Repo structure).

Deprecation banners

Put the warning immediately below the title, so it’s the first thing a reader sees.

Superseded by another artifact:

> ⚠️ WARNING
>
> This protocol is superseded by **`<protocol namespace>/<protocol slug>`**

Compatibility limit (not limited to agent versions — adapt the wording to whatever the compatibility constraint actually is):

> ⚠️ WARNING
>
> This version of the protocol only supports <Agent Name> vX and older. For <Agent Name> vY and newer, please use a newer version of the protocol.

Deprecated version:

> ⚠️ WARNING
>
> This version of the protocol is deprecated. Please use a newer version.