planning-doc

Planning Doc

Produce a single self-contained HTML file that renders a plan or design as an interactive document: tabbed pages, mermaid diagrams, a file-change tree, a clickable phase stepper, and inline review threads. The goal is a doc a human can absorb in minutes instead of reading pages of text — while the raw HTML stays lean and semantic enough for an agent to re-read and edit cheaply.

The doc uses the pd-* web component library, loaded from a CDN. You do not write any CSS or JavaScript — you write semantic markup; the components do the rendering.

Step 1: Fetch the component reference

The component library is versioned with this skill. Fetch the reference for the exact release this skill targets — an immutable tag, so it never drifts or serves a stale cache:

curl -fsSL https://cdn.jsdelivr.net/gh/mistakenot/[email protected]/pd-components/dist/llms.txt

It contains the page boilerplate, the release tag to pin, every component with attributes and examples, the authoring rules, and the comment-merge protocol. Follow it exactly — in particular, import the bundle pinned to the release tag it names (pd-v0.6.0), never @main. To move to a newer component release, update this skill (npx skills install …) — the new tag rides along.

If the fetch fails (offline/sandboxed): inside the skills repo itself, read pd-components/dist/llms.txt; elsewhere, fall back to the cheat sheet at the bottom of this skill and flag to the user that the reference may be stale.

Step 2: Author the doc

1. Gather the content: the conversation, files the user points at, or existing planning docs (requirements/solution/plan markdown) being rendered richly.
2. Choose the structure. Multi-topic docs get one <pd-tab> per concern (e.g. Overview / Solution / Plan / Wireframe); small docs skip tabs and put sections directly in <pd-doc>. Mind the tab roles: Solution is the end state (human-reviewed — file tree, API outlines, final snippets live here); Plan is the recipe (agent-consumed — keep it self-sufficient).
3. Prefer the rich components over prose. A plan with phases belongs in a <pd-stepper> (set each phase's files so the file tree highlights); file changes belong in <pd-files>; flows and architectures belong in <pd-mermaid>; acceptance criteria in <pd-ac> with traceability chips. Use only the mermaid diagram types llms.txt lists as supported.
4. Save as <topic>.html where the user keeps planning artifacts (for task workflows: the task folder's artifacts/; otherwise ask or use docs/). Tell the user to open it in a browser; it works from file:// directly.

Authoring rules that matter most (full set in llms.txt):

• The HTML source is the canonical document. Keep it semantic — structure lives in pd-* elements and stable kebab-case section ids, not in styled divs. Tailwind utility classes are welcome ONLY inside wireframe/freeform content.
• Content is edited in place; review threads are append-only. This mirrors the markdown workflow: the artifact stays current and readable, while every decision survives in its thread (and surfaces automatically in <pd-decisions>).
• Record an architectural decision you made yourself — one not dictated by the requirements or an existing repo pattern — as a <pd-decision> (rationale + alternatives + consequences), not buried in prose. It feeds <pd-decisions> alongside resolved threads.
• Preserve <script type="application/json" id="pd-meta"> blocks when editing existing docs. Never modify, move, or delete the pd-meta block — it tracks task lifecycle state managed by the planning workflow.

Step 3: Iterate

When the user asks for changes, edit the HTML in place — do not regenerate the whole file (that would orphan threads and churn the diff). Keep section ids stable so existing threads and deep links keep pointing at the right content.

Merging reviewer comments

Reviewers comment in the browser and paste back an export block delimited by === DOC COMMENTS / === END DOC COMMENTS ===. When you receive one:

• REPLY to thread "X" → append <pd-comment by="review"> with the text to that thread. If you can address it, do so, append your <pd-comment by="author"> explaining what changed, and set the thread's status="resolved" (or "rejected" with reasoning).
• NEW <priority> comment on "X" (anchor: id) → insert a new <pd-thread anchor="<id>" priority="<priority>" title="<short summary you write>"> directly after the anchored element, containing the comment.
• Never edit or delete existing comments — threads are the decision log.
• Report what you merged and resolved; the user clears their pending copy with the doc's Clear button.

Emergency cheat sheet (prefer llms.txt — this may be stale)

Classic scripts in head (never type="module"): https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4 and https://cdn.jsdelivr.net/gh/mistakenot/[email protected]/pd-components/dist/pd.min.js (defer).

• <pd-doc title status pr generated> shell · <pd-tab name> page pr: "pending" → placeholder; a URL → clickable badge. Update when PR opens.
• <pd-section id title> titled/anchorable section, freeform body
• <pd-thread anchor status{unresolved|resolved|rejected} priority{p1|p2|p3} title> with <pd-comment by{review|author|name}> children — append-only
• <pd-files> + <pd-file path change{add|edit|delete}>note</pd-file>
• <pd-stepper> + <pd-phase n title files status{done|active|todo}>
• <pd-mermaid caption> source as text content; flowchart/graph, sequence, state, class, ER, xychart only
• <pd-code lang path lines highlight caption> highlighted snippet (code as text content; use a nested <script type="text/plain"> if it contains <>&)
• <pd-api kind name lang path> + <pd-member kind sig>note</pd-member> — API/outline: signatures + comments only, generic kind badges
• <pd-ac id title phases tests> acceptance-criteria card
• <pd-decision id title status{accepted|proposed|superseded} by summary> authored ADR block
• <pd-decisions> auto decision log · <pd-wire label h> / <pd-note> wireframes