Markdown review

Optionalplugin: markdown

The Markdown review plugin shows a document an agent wrote, such as a plan, a design document, a README or release notes, and lets you comment on it before the agent goes on. You read it rendered, with its Mermaid diagrams, or as its source with line numbers. Each comment asks for a change or asks the agent a question, and goes back as lines of the document, so the agent knows exactly what it is about.

Click to enlarge

A question on the diagram, and a change asked for on the Backoff section.

When to use it

• A plan the agent wants to follow, read and corrected before it starts.
• Design documents and specs, with their diagrams.
• READMEs, changelogs and release notes, checked before they are published.

Install

The plugin comes with the app. Install it in Settings › Plugins, or from the command line:

pinrail plugins install markdown

What you see

• The document, rendered with its tables, code and Mermaid diagrams, or as its raw source with line numbers.
• The outline of its headings beside it, with a count of the comments under each. The button at the start of the header hides it, and the choice is kept as a setting.
• The agent’s context above the document, when it sends some, such as what changed since the last round.
• Comments on a section, from its heading, on a diagram, or on a passage you select in either view. Each comment is a Change or a Question.
• The previous round’s comments, when the agent sends a new version.

There is no verdict to choose. Handing over with no comments approves the document. With any change, it asks for changes. With questions alone, it asks the agent to explain without changing the document.

To see it before any agent asks with it, send its sample: pinrail submit markdown --sample, or Send a sample in its details in Settings › Plugins.

Asking from your agent

AGENTS.md

## Before acting on a plan or a document

When you write a plan, a spec or a document I should read, submit it to
Pinrail with the `markdown` plugin and wait for my decision:

1. Run: `pinrail submit markdown --title "<what the document is>" --data review.json --attach <the file> --wait`,
   with `{"file": {"$attachment": "<the file's name>"}, "path": "<its path>"}` in review.json.
2. If the verdict is `approve`, go on.
3. If it is `request_changes`, apply each `change` comment, answer each
   `question`, and submit the next version with `--revises <id>`.
4. If it is `questions`, answer them without changing the document, and
   submit it again with `--revises <id>`.
5. If the command exits 5, stop.

What the agent sends

review.json

{
  "file": { "$attachment": "retries.md" },
  "path": "docs/retries.md",
  "context": "First draft. Mostly the **Design** section needs a look."
}

• The document is a file sent with --attach and named in file, or its text in markdown in place of file. One of the two is required.
• path is how the person knows the document, shown in the header.
• context is markdown, shown above the document.
• Diagrams are ```mermaid blocks. Raw HTML in the document is shown as text.

What comes back

{
  "verdict": "request_changes",
  "comments": [
    { "id": 1, "kind": "change", "body": "Show the delays up to the eighth try.",
      "target": { "kind": "section", "start_line": 25, "end_line": 39,
                  "section": "Retry policy for webhook deliveries › Design › Backoff" } },
    { "id": 2, "kind": "question", "body": "Where does Retry-After come in?",
      "target": { "kind": "diagram", "start_line": 16, "end_line": 23, "quote": "flowchart LR" } }
  ]
}

Field	What the agent does with it
verdict	approve: goes on. request_changes: applies the changes and answers the questions in a new version. questions: answers the questions and sends the same version again.
comments[].kind	change is something to change in the document. question is something to explain.
comments[].target	What the comment is about: a section, a diagram or a text passage, as lines of the document, with the headings it sits under and, for a passage, the text selected.

Reference

The plugin’s manifest, and the schemas a payload and a decision are checked against, read from the plugin’s own files.

Manifestmanifest.jsonPayloadwhat the agent sendsDecisionwhat comes backSettingsSettings › Plugins

FieldsJSON

name	markdown
version	1.0.0
title	Markdown review
description	A Markdown document, rendered with its diagrams and as its raw source, with its outline. Comment on a section, a diagram or a selected passage, and approve it or ask for changes.
use_when	You wrote or changed a Markdown document (a design document, a README, a spec, release notes) and need a person to read it and say what to change, section by section or on a passage, before you go on.
attachments	.md .markdown text/markdown text/plain · up to 2 MB each, 1 a review

• One of: markdown or file
• markdownstring

  The document, as its file holds it. Diagrams are ```mermaid fenced blocks. Raw HTML is shown as text. Give either this or file.

  1–2000000 chars

• filefile

  The document as a Markdown file sent with --attach, in place of markdown. Give either this or markdown.

• pathstring

  Where the file lives, as you would name it to the person, such as docs/design.md.

  at most 500 chars

• contextstring

  What you want the person to look at, or what changed since the last round. Shown above the document; Markdown.

  at most 4000 chars

• verdictenumrequired

  approve: the person made no comments, and the document can stand as it is. request_changes: at least one comment is a change. Apply the changes, answer the questions, and send the next version with --revises. questions: every comment is a question. Answer them without changing the document, and send it again with --revises.

  "approve" "request_changes" "questions"

• commentsobject[]required

  Each comment, in the order of the document.

  • idintegerrequired

    at least 1

  • kindenumrequired

    change: something to change in the document. question: something for you to explain.

    "change" "question"

  • bodystringrequired

    What the person said.

    1–4000 chars

  • targetobjectrequired

    What the comment is about, as lines of the payload's markdown.

    • kindenumrequired

      section: a heading and everything under it. diagram: a mermaid block. text: a passage the person selected.

      "section" "diagram" "text"

    • start_lineintegerrequired

      The first line, counted from 1.

      at least 1

    • end_lineintegerrequired

      The last line, inclusive.

      at least 1

    • sectionstring

      The headings the target sits under, outermost first, joined with ' › '.

      at most 1000 chars

    • quotestring

      For text: the passage selected, as the person saw it. For a diagram: its first line.

      at most 2000 chars

• outline_openbooleanOutline open

  Start with the document's outline beside it

  default true