Writing for planpage

Writing documents

For agents and the people who prompt them. Document types, the block syntax, and how to write a plan a person can review quickly.

For agents: this page as markdown · llms.txt

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.

Kind Shown as Use it for
plan Plan Work you intend to do. The default.
report Report Research, investigations, and the completion report for a plan.
review Code review Code or security reviews, one finding per issue.
adr Decision record Architecture decision records.
brief Brief Work queued for an agent. People usually write these.

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. Notice where the decision and the question sit: each one right under the facts it's about, not gathered at the end.

# Migrate auth to Better Auth

Short summary: what, why, and the outcome.


### 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`. Titles and details can use inline markdown (code, bold, italic, links), which reviewers see formatted. Give the decision a short `name`. Reviewers see it when approval is blocked, and agents see it in feedback. Reviewers can always choose **Other** and write their own answer, so don't add an "Other" option. Their answer comes back in `get_feedback` as `picked` with `pickedOther: true`, and as `other="..."` on the `:::decision` in the markdown.
- **Questions.** The first line is the question. Any further lines before the answer list explain why it matters. The question and its suggested answers can use inline markdown too.
- **Diagrams.** A fenced code block with the language `mermaid` renders as a diagram, and the editor draws it under the code as you type. Shared pages show it as an image. When an agent publishes, a diagram that doesn't parse is refused with mermaid's error, so it never reaches a reviewer broken.
- **Images.** An image on a line of its own, `![description](url)`, shows inline when the URL is a planpage image link. Paste or drop an image into the editor, use **Image** in the toolbar, or have an agent call `upload_image`. Images from other sites stay as links, so a document never loads anything from a third party. See [Images](/docs/images).
- **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. On a long document an agent can read one section at a time: `read_document` with `outline: true` lists the headings, and `read_document`, `read_document_blocks` and `get_feedback` take a `section` (a heading's text or block id) so the agent gets only that part and its comments.

## 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.

**Ask beside the evidence.** Put each decision and question right under the section, finding or step it's about, so the facts needed to answer it are on screen when the reviewer gets to it. Don't gather them at the end or in an "Open questions" section: the reviewer then has to scroll back and rebuild the context. Only a choice about the whole document, such as its scope, belongs near the top, after the summary.

**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 team 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 move a document to Trash with `trash_document`, but only one their own connection published, that was never approved, in a workspace where the person they act for could delete it. It then waits in Trash like any other, and the agent can bring it back with `restore_document`. See [Agents and access](/docs/agents-and-access#cleaning-up-after-themselves).

## 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.