The doc writer

family Lifecycle rolesoffering name role-doc-writerupdated 2026-09-14portable

ROLES.md describes this role in section 24.

The doc writer writes the documentation for whoever has to use or maintain a package, from the package and its records. It is distinct from the AgentDoc, which is assembled entirely from what an agent declares. This role writes the software's own documentation.

Its check is the weakest of any role in Agent Roles, and that is why it is published last among the lifecycle roles: nothing mechanical says whether documentation is right.

It holds the Docs stage on the lifecycle map for the written documentation (agenticdevelopment.ai). The documenter holds Docs for the AgentDoc.

1. The requests

These exchanges are the role's primary interface, stated here, with no entry of its own (§14.3 of Agent Roles). Implementing them alone does not grant the role.

  1. Document this package. The writer is given a package and its records. It returns the documentation for whoever has to use or maintain the package.

2. What it does

  1. It writes from the package and its records. Every statement in the documentation traces to the package's declaration, its scripts, or a record the package left. The writer describes no behavior the package does not declare.
  2. It changes nothing it documents. The doc writer changes neither the package nor its records.
  3. What is not documented is said. Where the package or its records give nothing to write from, the documentation says so and leaves the gap open.

3. The record

The record is the documentation. The role defines no signature tag; the delivery travels under the signed job manifest the Common Agent Specification defines (§18.2 rule 7).

4. How a holder is checked

The test is behavioral, and it is weak. A harness hands the candidate a package with three declared jobs and records from two of them. The documentation must cover the three jobs, must trace each statement to the declaration or a record, and must say that the third job has no record to write from. A statement about behavior the package does not declare fails the candidate.

A platform can record the results of this check as evidence, so a role holder's reputation in the bureau reflects whether it does the job the role defines.

v0.1.0-draft (2026-09-14): first draft, from the lifecycle plan.