Read the target .md file.
Read skills/request-plan-review/assets/template.html as the HTML shell.
Read skills/request-plan-review/assets/style.css and skills/request-plan-review/assets/runtime.js — these will be inlined into the HTML.
Run automated markdown review:
- Import buildReviewPrompt from skills/request-plan-review/scripts/review-utils.mjs.
- Read skills/request-plan-review/references/review-template.md.
- Discover available reviewer CLIs directly in the main agent with command -v for claude, gemini, codex, opencode, and qwen.
- Build one prompt with buildReviewPrompt({ sourcePath, markdown, reviewTemplate }), where sourcePath is the target .md plan/spec address and markdown is the full target file contents.
- Dispatch one subagent per detected reviewer, in parallel. Give each subagent the reviewer id, CLI path, source path, and full review prompt.
- Each subagent runs only its assigned reviewer CLI, asks it to review the source markdown, and returns only the finding markdown in the exact template format.
- Do not use a short fixed timeout such as 120 seconds. Let reviewers complete a full review. If the host environment requires a timeout, use a long soft limit and record timeout as a reviewer failure.
- After all subagents finish, the main agent writes docs/request-plan-review/<filename>.reviews.md.
- If no reviewer CLI is detected, still write a .reviews.md file that records automated reviews were not run.
- If a reviewer fails, times out, or returns invalid output, record the failure in .reviews.md and continue rendering.
- The main agent parses valid findings from the completed .reviews.md file and builds automated comment data for the HTML page.
Convert the markdown content to HTML manually (see MD→HTML rules below).
Generate a TOC sidebar from all h2/h3 headings.
Fill the template slots:
-  — page title and topbar (use first h1 text or filename)
-  — relative path of the source .md file (e.g. docs/plans/my-plan.md)
-  — paste the full contents of style.css (replaces the entire line including the /* SLOT:STYLE */ comment)
-  — the converted HTML content
-  — the generated TOC sidebar HTML
- /* SLOT:REVIEW_DATA */ — paste a window.__AUTOMATED_REVIEW_COMMENTS__ = [...] assignment built from the aggregated reviewer findings
- /* SLOT:SCRIPT */ — paste the full contents of runtime.js (replaces the entire line including the /* SLOT:SCRIPT */ comment)
Write the result to docs/request-plan-review/<filename>.html (same basename as source).
Run open docs/request-plan-review/<filename>.html.

Output is a single self-contained HTML file — CSS and JS are inlined, no external assets needed. This ensures the file works with open on file:// protocol without CORS issues.

MD → HTML Conversion Rules

Headings

All h2 and h3 elements MUST have an id attribute. Generate the id by slugifying the heading text: lowercase, replace spaces with hyphens, remove non-alphanumeric characters except hyphens, strip leading/trailing hyphens. If duplicate ids exist, append -2, -3, etc.

<h1>Title</h1>
<h2 id="section-name">Section Name</h2>
<h3 id="subsection-name">Subsection Name</h3>

Code Blocks

Wrap in <pre> with a language label and copy button. The <code> element gets class="language-xxx".

<pre><code class="language-typescript">const x = 1;</code><span class="code-lang">typescript</span><button class="copy-btn">Copy</button></pre>

For unknown language, omit the class: <pre><code>...</code></pre>.

For Mermaid blocks, use <pre class="mermaid"> without a <code> wrapper:

<pre class="mermaid">graph TD
  A --> B</pre>

Inline Code

<code>variable_name</code>

Bold and Italic

<strong>bold text</strong>
<em>italic text</em>

Links

<a href="url">link text</a>

Images

<img src="url" alt="alt text">

Lists

<ul>
  <li>Item</li>
</ul>
<ol>
  <li>Item</li>
</ol>

Task Lists

<ul class="task-list">
  <li><input type="checkbox"> <span>Unchecked task</span></li>
  <li><input type="checkbox" checked disabled> <span>Completed task</span></li>
</ul>

Tables

<table>
  <thead>
    <tr><th>Header 1</th><th>Header 2</th></tr>
  </thead>
  <tbody>
    <tr><td>Cell 1</td><td>Cell 2</td></tr>
  </tbody>
</table>

Blockquotes

<blockquote>
  <p>Quoted text</p>
</blockquote>

Admonitions

Parse GitHub-style admonitions from blockquotes:

<div class="admonition admonition-note">
  <div class="admonition-title">NOTE</div>
  <p>Note content</p>
</div>

Supported types: NOTE (blue), WARNING (yellow), TIP (green), CAUTION (orange). The type maps to the CSS class suffix.

Horizontal Rules

<hr>

TOC Sidebar Generation

After converting all markdown to HTML, scan the converted content for all h2 and h3 elements. Build the sidebar HTML:

<aside class="toc-sidebar">
  <nav>
    <div class="toc-sidebar-title">On this page</div>
    <ul>
      <li><a href="#section-id">Section Title</a></li>
      <li class="toc-h3"><a href="#subsection-id">Subsection Title</a></li>
    </ul>
  </nav>
</aside>

Rules:

h2 entries are top-level <li> elements
h3 entries get class="toc-h3" for indentation
Each <a href> uses the heading's id as the anchor
The link text is the heading text (trimmed)
h4 and below are NOT included in the TOC

HTML Entity Escaping

Inside code blocks (<pre><code>), escape these characters:

< → <
> → >
& → &

Do NOT escape these in regular content — only inside code contexts.

Source Line Annotation

During MD→HTML conversion, track the source line number for each block-level element. Add a data-source-line="<N>" attribute where <N> is the 1-indexed line number from the source .md file where the element starts.

Elements to annotate

Element	Annotate?
`<p>`	Yes
`<h1>`–`<h4>`	Yes
`<pre>`	Yes
`<blockquote>`	Yes
`<table>`	Yes
`<div class="admonition">`	Yes
`<hr>`	Yes
`<li>`	Yes
`<ul>`, `<ol>`	No (children are annotated)
`<thead>`, `<tbody>`	No (parent `<table>` is annotated)

Rules

Nested structures (e.g. <p> inside <blockquote>) annotate independently — each gets its own starting line number.
The line number corresponds to where the markdown construct begins in the source file, not where it ends.
Example: a fenced code block starting at line 42 gets data-source-line="42" on the <pre> element, even though the closing fence is on line 48.

Example

Source markdown (lines 10-13):

Some paragraph text.
## Section Name

Generated HTML:

<p data-source-line="10">Some paragraph text.</p>
<h2 data-source-line="12" id="section-name">Section Name</h2>

Automated Review Comments

During generation, create a sidecar reviews file:

docs/request-plan-review/<filename>.reviews.md

Reviewer findings use this parseable markdown format:

## Reviewer: claude

### Finding: Missing failure path
Severity: high
Location: docs/superpowers/plans/example.md:42-48
Quote:
> original markdown snippet

Comment:
This step assumes the command succeeds but does not define what to do if the
generated HTML has no source-line annotations.

Allowed severity values are critical, high, medium, low, and note.

Injected automated comments use this shape:

window.__AUTOMATED_REVIEW_COMMENTS__ = [
  {
    id: 'A1',
    source: 'automated',
    reviewer: 'claude',
    severity: 'high',
    title: 'Missing failure path',
    startLine: 42,
    endLine: 48,
    selectedText: 'original markdown snippet',
    comment: 'This step assumes the command succeeds...',
    unanchored: false
  }
];

Automated comments reuse the existing comments panel. They get A1, A2, and A3 IDs so manual comments can continue using numeric IDs.

Verification

After generating the HTML file:

test -s docs/request-plan-review/<filename>.html
open docs/request-plan-review/<filename>.html

Check in browser:

Dark theme renders correctly
Theme toggle switches to light and back
Code blocks show shiki syntax highlighting
TOC sidebar highlights active section on scroll
Tables, admonitions, task lists render properly
docs/request-plan-review/<filename>.reviews.md exists.
If no reviewer CLI is available, the reviews file says automated reviews were not run.
If reviewer findings exist, automated comments appear in the comments panel.
Rough Notation underlines appear when the CDN is available and CSS highlights remain when it is not.

Debugging

If the page looks wrong:

Check the browser DevTools console for errors
Verify the HTML file contains inlined <style> and <script> (not external links)
Verify all heading ids are unique and match TOC links
Verify code blocks have class="language-xxx" for shiki to detect
Verify mermaid blocks use <pre class="mermaid"> not <pre><code class="language-mermaid">
If shiki/mermaid CDN fails (no network), content still renders as plain HTML

request-plan-review

Request Plan Review

Workflow