Docs that keep up with the API

Take an example API for asynchronous exports (not a Rhizome endpoint). A client creates an export, polls the job, and downloads the result when it’s ready.

Claude Code is implementing it in the API repository. The user asks Codex, working in the documentation repository, to write the guide while the implementation is still in progress. Both sessions already run on their own; neither launched the other.

The guide has to describe a contract that isn’t finished yet:

• → The contract moves. The first description is “returns a job ID, then poll”. Later, creation returns 202 Accepted with a statusUrl, and downloadUrl only appears once the job is ready.
• → Edge cases aren’t decided yet. What a client should do when an export expires isn’t in the code when the guide is drafted.
• → Two repos, two agents. Codex can read the API branch if it has access. It can’t see what the implementing session is deciding, or when.
• → Release timing. The API and its docs should be reviewed and published together, not weeks apart.

The usual options all leave someone carrying the contract between two sessions by hand:

• → Write the docs after merge. Someone reconstructs why creation returns 202 and when downloadUrl appears. Late changes get lost between code review and the guide.
• → Write them early, once. The guide documents “returns a job ID” and is wrong by the time the API is reviewed. Nothing tells the docs session the contract changed.
• → Relay by hand. The user copies each change from Claude Code into Codex, and asks about expiry over Slack. Every relay is a chance to drop a detail.
• → Guess the edge case. The docs agent fills the gap with plausible behavior, like “retry the download”, that the API doesn’t support.

1. 01 Find and follow the exact session. Codex calls list_sessions and checks agent type, project and session name against the export work. Once it’s sure, it calls subscribe with that session’s exact ID. A repository name alone isn’t enough.
2. 02 Draft from the first contract. An update arrives: “The export endpoint will return a job ID. Clients will poll the job endpoint until the download is ready.” Codex outlines create → poll → download, opens a draft docs PR, and marks status codes, fields and errors as open instead of inventing them.
3. 03 Catch the late change. Another update: “Creation now returns 202 Accepted with a status URL. The download URL only appears once the job is ready.” Codex checks the API branch diff and schema, then revises the guide on the same docs PR.
4. 04 Ask instead of guessing. The guide needs expiry behavior, so Codex uses send to ask that exact session: “What should clients do when an export expires?” Until a reply arrives, expiry stays an open item.
5. 05 Turn the answer into guidance. The reply: “An expired export returns 410. Start a new export; retrying the expired download will not renew it.” Codex checks it against the implementation and adds a recovery section.
6. 06 Align at ready-for-review. When the API session reports it’s ready for review, Codex re-checks the guide against the branch and schema, runs the docs build, link and example checks, and lists what it validated and what still needs review on the PR.

• → One docs PR, revised in place. Draft, then the 202 and statusUrl change, then 410 recovery. The commits show how the contract evolved.
• → No guessed behavior. Expiry is documented from the implementer’s answer, checked against the code.
• → Reviewed together. The API PR and the docs PR stay separate, so reviewers can read the code and its explanation side by side and agree on release timing. Rhizome doesn’t merge either one.

POST /exports
→ 202 Accepted
{ "jobId": "{job_id}", "statusUrl": "/exports/{job_id}" }

GET /exports/{job_id}
→ 200 OK
{ "status": "pending" }

GET /exports/{job_id}
→ 200 OK
{ "status": "ready", "downloadUrl": "/exports/{job_id}/download" }

GET /exports/{job_id}/download  (after expiration)
→ 410 Gone

Recovery: POST /exports, then poll the new statusUrl.

• → Updates aren’t diffs. A subscription carries selected assistant activity and activity markers, not transcripts, reasoning or file contents. Codex still has to read the API branch and schema; if it can’t, verification stays open.
• → Following can have gaps. A new subscription starts from now. Reconnects, bounded queues and restarts can drop events. When updates go quiet, check the subscription state and the branch, and ask rather than fill the gap.
• → Sent isn’t answered. A successful send means the message was queued, not that it was read or answered.
• → Ready isn’t tested. A “ready for review” update doesn’t mean tests pass or the feature shipped. Validation is a step Codex runs, not something it receives.

1. 01 Pick a feature whose API contract is still changing, with docs in a separate repo or session.
2. 02 Start the docs session and have it find and subscribe to the implementing session by exact ID.
3. 03 Open a draft docs PR early, with unknowns marked as open.
4. 04 Ask the implementing session directly for anything the guide can’t safely infer. Review and release both PRs together.

Write the guide for <feature> in this repo. Find the session implementing it,
confirm it's the right one, and subscribe. Keep unknowns open in a draft PR,
check each contract change against the API branch before editing, and ask
that session directly instead of guessing.