Writing documents

planpage documents are markdown. A few ::: blocks turn into things the reviewer can act on: steps they can follow, decisions they pick, questions they answer. Everything else renders as ordinary markdown, including headings, lists, tables, links, code blocks and checklists.

#Document types

Set the type with the kind argument when publishing.

A report or review that belongs to a plan can name it as its parent, so the two are linked.

#Block syntax

Plain markdown plus blocks that become interactive widgets for the reviewer:

# Migrate auth to Better Auth

Short summary: what, why, and the outcome.

:::step{id="s1" title="Add the migration"}
What changes, where, and how it's verified.
:::

:::decision{id="d1" name="Session storage"}
- **D1** (recommended): simple, close to the Worker
- **KV**: faster reads, eventual consistency
:::

:::question{id="q1" required}
Should existing API tokens keep working after the cutover?

- Keep them
- Revoke and reissue
:::

:::risk
Rollback needs a manual step.
:::

:::note
Context the reviewer should know.
:::

:::finding{severity="high" file="src/auth.ts" line="42" title="Token logged"}
For reviews: one block per finding.
:::

- [ ] Checklist items the reviewer can tick

Guidelines:

• One :::step per unit of work you'll claim; stable ids let feedback and progress attach to them across versions.
• Put real choices in :::decision and mark your pick with (recommended) after the bold title. It is labelled "Agent recommends" but never pre-selected: the human chooses.
• Open questions go in :::question; add {required} when you can't proceed without the answer. Suggested answers as a list become one-click chips.
• Approval is blocked until every decision has a pick and every required question has an answer (the reviewer can override, and get_feedback tells you if they did). Ask only what you genuinely need decided.
• To ask specific people, pass reviewers (emails or names) to submit_for_review.
• Lead with the summary; keep prose tight; link files and PRs.

#More detail

• Callouts. Besides :::risk and :::note, there are :::info and :::warning.
• Findings. severity is one of critical, high, medium, low or info (medium if omitted). file and line are optional. A finding can also carry a status of open, fixed, wontfix or duplicate.
• Steps. Steps can hold any markdown, including lists and code. Their status is set by planpage as work runs, so leave it out when writing.
• Decisions. Write each option as - **Title**: detail. Give the decision a short name. Reviewers see it when approval is blocked, and agents see it in feedback.
• Questions. The first line is the question. Any further lines before the answer list explain why it matters.
• Diagrams. A fenced code block with the language mermaid renders as a diagram.
• Block ids. The id on a block keeps comments, picks and progress attached to it across versions. planpage adds ids to blocks that don't have one. read_document_blocks lists every block's id for targeted edits.

#Good practice

Lead with the summary. Start with a title and two or three sentences: what changes, why, and what the result will be. The reviewer should know whether to read on from the first paragraph.

One step per unit of work you'll claim. A step is what you mark in progress and done. Say what changes, where, and how you'll check it. Keep ids stable when you revise.

Recommend, don't pre-select. Put real choices in a decision and mark your preference with (recommended). The reviewer sees "Agent recommends" but still has to choose. Don't write a decision whose answer you've already acted on.

Mark only truly blocking questions required. Every decision and every required question blocks approval until it's answered. If you can proceed on a sensible default, say what you'll assume in a note instead, or ask a question without {required}. A plan with six required questions is a plan nobody approves quickly.

Offer answers. A list under a question turns into one-click answers. Two to four short options work best.

Name risks. A :::risk block for anything that could go wrong, with the rollback, saves a round of comments.

Link, don't paste. Link files, issues and pull requests rather than pasting long code.

Search first. Earlier plans and decision records in the same project often answer questions you were about to ask. Agents should call search before planning.

#Delete a document

Open the document and choose ⋯ → Move to Trash…. Owners and admins can do this in organization workspaces, and you can in your personal workspace.

The document disappears for everyone straight away: from lists, search and the Inbox, and its share links, guest access and agent access stop working. Anyone editing it is disconnected.

It waits in Workspace settings → Projects → Trash for 30 days, where you can Restore it or Delete now. After 30 days it's deleted for good with its versions, comments, reviews and activity. If you only want it out of the way, Archive… keeps it readable instead. Agents can archive documents but can't delete them.

#Revising after review

Read everything with get_feedback first. Keep the reviewer's edits, picks and answers. For small fixes use edit_blocks, which changes single blocks and leaves the rest, including concurrent edits by people, untouched. Republish the whole document with publish only for larger rewrites. Reply to each comment with what you did, resolve the ones you handled, then submit again with a summary of what changed.