Planpage

Skill YosefHayim/planpage/skills/planpage

Render a skill's plan, review gate, quiz, poll, or report as a beautiful, self-contained INTERACTIVE HTML page via the open-source planpage package (Preact → static HTML + local post-back so the user can Approve / Adjust / flip decisions in the browser and the choice comes back to the agent). Use whenever a skill needs an approval gate, decision review, preference poll, teach/coach surface, storyboard/image grid, or shareable before/after report — author with planpage instead of hand-rolling HTML.From its SKILL.md

Install

npx -y skills add YosefHayim/planpage --skill planpage

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
runs commandsInstructs the agent to run 5 commands, including `npx planpage render plan-brief --sample --open` and 4 more.

SKILL.md

4.7 KB, ~1.1k tokens by cl100k_base, as published. Nobody here has run it

planpage — interactive HTML plans for agents

Thin consumer of planpage on npm (npm i planpage or zero-install npx planpage). Components, render engine, gallery, and post-back live there as SSOT. Do not hand-roll HTML — author with the package.

When to use

Need	Template / approach
Multi-step plan + risks + Approve/Adjust	`plan-brief`
Diff / deslop / migration report	`before-after`
Code-style picks + canonical example	`code-style-plan`
Preference interview / grill	`question-poll`
Graded teach/coach quiz	`quiz`
Flip-card learn deck	`flashcards`
Scored audit findings	`audit-report`
Browse every component live	`library` or `npx planpage library --open`
Custom page	Compose components + `render()` / `renderHighlighted()`

Quick start (CLI)

# sample page in the browser
npx planpage render plan-brief --sample --open

# plan gate: render + serve + one decision back
npx planpage render plan-brief --data plan.json --serve --decision decision.json

# preference poll
npx planpage render question-poll --data questions.json --serve --decision decision.json

# browse components
npx planpage library --open

# wire this package into local agents (Claude / Cursor / Codex / …)
npx planpage init

Quick start (library)

import { render, renderHighlighted, PlanBrief, serve } from "planpage";

const html = await renderHighlighted(
  <PlanBrief title="…" summary={/* … */} steps={/* … */} risks={/* … */} />,
);
// write html → $TMPDIR/plan-<ts>.html, then:
// await serve({ htmlPath, outPath: "decision.json", timeoutSec: 600 })
// or: npx planpage serve <html> decision.json --timeout 600

Prefer renderHighlighted() (or CLI render) for VS Code syntax colour (Shiki, baked into the HTML). Bare render() is sync and monochrome-safe.

Decision contract

The page posts one JSON object; serve writes it verbatim:

{
  "approved": true,
  "flips": ["rule.function-form"],
  "revisit": ["rule.error-shape"],
  "notes": "keep classes only in the DB layer"
}

Field	Meaning
`approved`	Approve (`true`) vs Adjust (`false`)
`flips`	`data-id`s of `PickBlock`s the user flipped — re-open these
`revisit`	`data-id`s marked revisit without a firm decision
`notes`	free text from the notes box

Interactive pieces carry a stable data-id (or id / dataId). Name them meaningfully (rule.error-shape, move.orders-dir) so a bare id tells you what to re-open.

Never hang. serve has an idle timeout; Copy decision is the clipboard/file:// fallback for headless / no-port callers.

Plan-gate workflow (default)

Shape plan JSON for plan-brief (title · summary · steps · options · risks · code).
npx planpage render plan-brief --data plan.json --serve --decision decision.json
Read decision.json → if approved:false, re-open picks in flips / revisit and fold in notes.

Question-poll workflow

Shape { title, layout?, questions: [{ id, text, group?, diagram?, options: [{ id, label, description?, code?, recommended? }] }] }
npx planpage render question-poll --data questions.json --serve --decision decision.json
Each answer includes questionId, picked, questionText, chosenText.

Layouts: stack · grid-2 · grid-3 · grid-4 · grid-5. Optional Mermaid diagram per question.

Rules

Package owns HTML; skill owns content. Plug content into planpage — don't re-derive the shell. New widgets go into the package (+ gallery entry).
Self-contained. No repo assets at render time; Tailwind + Mermaid from CDN; Shiki colour baked in by renderHighlighted.
Always render at the gate when this skill is available — never dump a long plan as plain terminal text for approval.
Installing the package does not install skills. Ship this skill (or run npx planpage init) so agents know to call the kit.

More detail

Component catalog + props: COMPONENTS.md
Live gallery: npx planpage library --open
Package docs: https://github.com/YosefHayim/planpage

What ships with it: 1 file

3.3 KB alongside SKILL.md

COMPONENTS.md3.3 KB