Plans
feature product-plans v3.3.0 2026-05-17

Plan: Emit self-contained HTML artifact from plan-review-agents

Approve with revisions

Generated: 2026-05-17T00:00:00Z · Source: docs/plans/add-html-output-to-plan-review-agents.md

File add-html-output-to-plan-review-agents-review.html
Path docs/plans/add-html-output-to-plan-review-agents-review.html

Context

The product-plans:plan-review-agents skill currently produces two outputs: a 15-section markdown panel report (echoed in chat) and an in-place mutation of the source plan file (Pass 1 inline edits + Pass 2 appended ## Panel Review section). Sharing reviews outside a Claude Code session requires the reader to either render the plan file themselves or read the chat transcript.

The user wants a third, shareable, browser-openable artifact: a media-rich, self-contained HTML document combining the revised plan (section 15b) as the primary surface with the full 15-section panel review available as an appendix. The artifact must open in any browser with no external dependencies (no CDN CSS, no external fonts, no remote scripts) so it can be uploaded to any static file host or attached to a ticket.

Design decisions confirmed with the user:

  • Content scope: revised plan as primary, full review as appendix in the same file.
  • Output mode: additive — the existing in-place plan update continues to happen in all modes; the HTML sibling is always emitted (no new Step 2 prompt).
  • Render approach: a dedicated HTML layout spec bundled inside this skill (purpose-built for review-report shape — decision badge, six reviewer cards, conflicts table, reviewer-unavailable pills). No cross-plugin dependency on plan-interview:plan-to-html, though we mirror its self-contained-single-file pattern.

Sibling-file emission was explicitly removed from this skill in a prior cleanup (CHANGELOG 3.x). The HTML sibling re-introduces a sibling file deliberately, with a distinct extension (.html) so it cannot collide with markdown plan files in the same directory.

Objective

Add a self-contained HTML output mode to the product-plans:plan-review-agents skill that always emits <plan-stem>-review.html next to the source plan, containing the revised plan as the primary document and the full panel review as a collapsible/secondary appendix, rendered per a new bundled layout spec.

Files to Modify

  • kit/plugins/product-plans/skills/plan-review-agents/SKILL.md — add new step, update table of contents, update opening summary, update final announcement.
  • kit/plugins/product-plans/skills/plan-review-agents/references/html-spec.md — new file. The full HTML layout contract: head, themes, two-column layout, decision badge, reviewer cards, conflicts table, inline-edits table, reviewer-unavailable pills, print styles, inlined CSS/JS.
  • kit/plugins/product-plans/README.md — document the new HTML output.
  • kit/plugins/product-plans/CHANGELOG.md — new MINOR entry (3.3.0).
  • .claude-plugin/marketplace.json — bump product-plans version 3.2.1 → 3.3.0.

Reuse Notes

  • The HTML synthesis must draw from the same in-memory synthesized report produced in Step 6, not re-synthesize from reviewer outputs — keeps the chat report, the appended ## Panel Review section, and the new HTML file consistent.
  • Mirror the cache pattern from kit/plugins/plan-interview/skills/plan-to-html/reference/html-spec.md (long-form layout contract in a reference//references/ file, short SKILL.md step that walks parse → synthesize → write). Do not read or import that file — we build a tailored spec.
  • The skill already declares Write in allowed-tools, so no manifest changes are required for file emission.
  • The synthesized report from Step 6 must be retained as a named string synthesized_report available to Steps 7 and 8 without regeneration. Neither step re-synthesizes from reviewer outputs. Step 8 reads this retained string directly — do not regenerate.

Steps

  1. Create references/html-spec.md with the full HTML layout contract organized into nine required sections (themes, layout, decision badge, reviewer cards, tables, appendix toggle, print, no-external-deps, Security & Escaping Contract). Include a reference HTML skeleton with injection-point comments. Status: complete.
  2. Update SKILL.md opening summary and table of contents — add HTML artifact mention; add Step 8 to TOC; renumber old Step 8 (cleanup) to Step 9. Status: complete.
  3. Insert new Step 8 body in SKILL.md with mode clause (skip when review only), synthesis instruction, path derivation, escaping requirement, write failure-mode announcement, and success announcement. Status: complete.
  4. Renumber current “Clean up the team” step to Step 9 — update heading only; body unchanged. Status: complete.
  5. Update Step 0 todo-creation guidance — change “Steps 1–8” to “Steps 1–9”. Status: complete.
  6. Update Step 7 closing announcement — append brief mention that HTML artifact path will be announced in Step 8. Status: complete.
  7. Update kit/plugins/product-plans/README.md — add third output bullet for HTML artifact. Status: complete.
  8. Add CHANGELOG entry for version 3.3.0, dated 2026-05-17. Status: complete.
  9. Bump version in .claude-plugin/marketplace.json from 3.2.1 to 3.3.0. Status: complete.

Verification

  1. Spec exists and is referenced: ls kit/plugins/product-plans/skills/plan-review-agents/references/html-spec.md succeeds and grep -n "html-spec.md" ...SKILL.md returns at least one match. — Passed.
  2. Step structure is intact: grep -n "^### Step" ...SKILL.md lists Steps 0 through 9 in order. — Passed.
  3. TOC matches body: TOC anchors resolve to existing headings. — Passed.
  4. Version is bumped: jq -r '... | .version' .claude-plugin/marketplace.json outputs 3.3.0. — Passed.
  5. CHANGELOG is dated correctly: top ## header reads ## 3.3.0 — 2026-05-17. — Passed.
  6. Live smoke test (manual): invoke skill on fixture plan; confirm chat report, in-place update, and HTML sibling all appear; no console errors; decision badge readable; reviewer cards render; appendix collapsed by default.
  7. Keyboard accessibility (manual): tab through rendered HTML; all interactive elements receive visible focus; Space/Enter on appendix summary opens/closes it.
  8. XSS smoke test (manual): invoke skill on plan whose title is Test <script>alert(1)</script>; confirm no alert fires; view-source shows escaped entities.

Next Steps

  • Rename plan file before first implementation commit — use git mv to rename from random name to add-html-output-to-plan-review-agents.md. (Completed.)
  • Add theme selection — --theme=<default|developer|document|minimal> flag in Step 0, defaulting to default.
  • Cross-link HTML artifact from the appended ## Panel Review section in the source plan (relative link).
  • html-spec.md parity — compare with plan-interview/skills/plan-to-html/reference/html-spec.md for shared layout primitives.
  • Dark mode — @media (prefers-color-scheme: dark) block mapping to developer theme palette. Target v3.4.0.

Unresolved Questions

  1. Markdown rendering trust boundary — should the revised plan section be rendered from markdown to HTML, or shown as <pre> preformatted text? If rendered: which renderer, and how are security constraints enforced?
  2. Review-only mode HTML output — confirm “skip Step 8 entirely” is the desired behavior when output_mode = review only (section 15b absent), or specify a degraded alternative.
  3. Background-mode HTML path surfacing — should the final status message in /product-plans:product-plans-bg surface the HTML artifact path alongside the existing in-place update line?
Panel Review — full 15-section report

Reviewed by: PM · Lead Developer · UX Designer · Lead Frontend Engineer · Accessibility Expert · Security Expert — coordinated by Lead Coordinator

1. Executive Summary

High-quality, well-scoped plan with a clear user problem and additive design. The panel unanimously approves with revisions. The plan's core decisions — self-contained artifact, deterministic filename, in-memory synthesis reuse, additive emission — are sound. Three cross-cutting gaps require resolution before implementation: (1) no HTML-escaping or CSP contract for user-controlled content flowing into the artifact, creating a real stored-XSS vector when the artifact is shared to static hosts; (2) no WCAG accessibility baseline in the html-spec.md scope, despite this being a professionally shared document; (3) no explicit named-variable contract guaranteeing the Step 6 synthesis is preserved for Steps 7 and 8. All three are now addressed as inline edits applied to this plan. No reviewers rejected the plan.

2. Role-by-Role Review

Product Manager

Approval
Approve with revisions
Works well
Clear user problem statement; additive non-breaking design; self-contained constraint explicit and verifiable; deterministic filename convention; correct MINOR version bump.
Critical concerns
No fallback for Write failures. html-spec.md relied upon without content-quality gate. Both addressed.
Missing (addressed)
Accessibility baseline; reviewer-unavailable trigger definition; overwrite behavior.

Lead Developer

Approval
Approve with revisions
Works well
Scope touches exactly five files; in-memory reuse strategy correct; Write already in allowed-tools; cleanup-last invariant preserved.
Critical concerns
None. Implementation is technically sound.
Missing (addressed)
Named-variable synthesis contract; Write failure handling; no accessibility floor.

UX Designer

Approval
Approve with revisions
Works well
Additive-only design eliminates new prompts; self-contained removes render friction; sidebar TOC + collapsible appendix addresses information hierarchy.
Critical concerns
No error state for HTML Write failure. Smoke test path was machine-specific. Both addressed.
Missing (addressed)
Accessibility spec; charset declaration; <title> element spec.

Lead Frontend Engineer

Approval
Approve with revisions
Works well
Self-contained constraint explicit; single source-of-truth rendering sound; CSS-variable theme approach correct; filename pattern deterministic.
Critical concerns
No accessibility spec. No progressive-enhancement clause or CSP. No reference skeleton. All addressed.
Missing (addressed)
Charset; viewport meta; HTML escaping; dark mode policy (added as out-of-scope).

Accessibility Expert

Approval
Approve with revisions
Works well
Native <details>/<summary> is the right choice; no-external-deps eliminates third-party a11y regressions; reviewer-unavailable pills better than blank cells.
Critical concerns
No WCAG conformance target. Zero accessibility checks in Verification. No :focus-visible styles. All addressed.
Missing (addressed)
Keyboard nav contract; scroll-spy focus-management policy; TOC landmark spec; language attribute.

Security Expert

Approval
Approve with revisions — blocking on XSS/CSP (resolved)
Works well
Self-contained/no-external-deps eliminates supply-chain risks; deterministic scoped output location; distinct .html extension.
Critical concerns
XSS via unescaped user content (OWASP A03). No threat model for shareable attack surface. Both resolved by Security & Escaping Contract in html-spec.md.
Missing (addressed)
HTML escaping rule; CSP meta tag; filename normalization; write-safety contract; provenance metadata.

3. Highest-Risk Issues

  1. Stored XSS via unescaped user content — plan body and reviewer outputs flowed into HTML without escaping. OWASP A03 stored-XSS on static hosts. Resolved: Security & Escaping Contract added to Step 1.
  2. No WCAG accessibility baseline in html-spec.md — zero semantic HTML, landmark, contrast, focus, or language requirements. Resolved: nine-section spec now includes full WCAG AA requirements.
  3. In-memory synthesis continuity not guaranteed — Step 6 → 7 → 8 reuse was emergent behavior, not a runtime contract. Resolved: named-variable contract added to Reuse notes.
  4. Write failure left “always emitted” invariant undefined — disk-full or permissions error had no recovery path. Resolved: failure-mode clause added to Step 3.
  5. html-spec.md had no content-quality gate — “>200 lines” check did not verify required sections exist. Resolved: section-presence grep replacing line-count verify.

4. Blocking Issues

All blocking issues resolved by inline edits applied in Pass 1:

  1. HTML escaping and CSP contract — mandatory Security & Escaping Contract added to Step 1 and Step 3. (Resolved)
  2. Write failure mode — announce error and continue to Step 9. (Resolved)
  3. Named-variable synthesis contract — synthesized_report contract added to Reuse notes. (Resolved)

5. Important but Non-Blocking Improvements

Applied in Pass 1: default theme (theme-default); review only skip clause; appendix collapsed on load, expanded in print; smoke test fixture path; jq version check; section-presence grep; responsive breakpoint; <meta charset>, viewport, generator; provenance footer; rename note formalized; dark mode marked out-of-scope; Unresolved Questions section added.

6. UX Recommendations

  • Appendix <details> collapsed by default; expanded in @media print.
  • Default theme theme-default applied explicitly in Step 3.
  • Compact footer disclaimer included in spec requirements.
  • Regression check: source plan must still contain ## Panel Review after Step 8 runs.

7. Accessibility Requirements

  • <html lang="en"> (WCAG 3.1.1)
  • Landmark regions: <nav aria-label="Table of contents">, <main>, <aside> (WCAG 1.3.6, 2.4.1)
  • Heading hierarchy: h1/h2/h3 (WCAG 1.3.1, 2.4.6)
  • :focus-visible on all interactive elements (WCAG 2.4.11)
  • WCAG AA contrast for all four themes (WCAG 1.4.3, 1.4.11)
  • Non-color decision badge: full text label required (WCAG 1.4.1)
  • Native <details>/<summary> exclusively for collapsibles (WCAG 2.1.1)
  • Scroll-spy must not move keyboard focus (WCAG 2.4.3)

8. Frontend Implementation Considerations

  • Native <details>/<summary> exclusively; JS for scroll-spy only.
  • Progressive enhancement: content readable without JS.
  • Reference HTML skeleton required in spec (injection-point approach).
  • Responsive breakpoint at ≤768px.
  • Dark mode explicitly out-of-scope for v3.3.0.

9. Security Requirements

  • HTML escaping rule for all interpolated values (OWASP A03)
  • CSP <meta> tag in <head> (OWASP A05)
  • Self-containment verification grep (OWASP A06)
  • Filename normalization to [A-Za-z0-9._-] (OWASP A01, A03)
  • Sensitive content footer notice (GDPR Art. 5(1)(f))
  • XSS smoke test added to Verification item 8

10. Technical Feasibility Concerns

No critical technical blockers. Implementation is feasible with existing skill capabilities. Spec drift risk: two parallel html-spec.md files will diverge; consolidation recommended before v3.4.0.

11. Open Questions Before Development

Moved to formal ## Unresolved Questions section. Key decisions: appendix default state (collapsed, addressed); review only mode (skip Step 8, addressed); default theme (theme-default, addressed); markdown rendering (open); in-memory synthesis continuity (addressed); Write failure (addressed); background-mode HTML path surfacing (open).

12. Recommended Changes to the Plan

All 19 recommendations applied in Pass 1 inline edits. See verification plan verify-panel-review-html-output-integration.md for full cross-check table.

13. Conflicts or Tradeoffs Between Reviewer Recommendations

Topic Conflict Resolution
Collapsible appendix mechanism A11y required native <details>. Frontend said pick one (simultaneous JS + native causes interaction conflicts). Security noted event-handler XSS surface. Native <details>/<summary> exclusively; JS restricted to scroll-spy only (progressive enhancement).
Sensitive content warning level Security wanted visible printable banner. UX wanted minimal friction on primary surface. Compact footer disclaimer that prints — not a modal overlay or full-page banner.
html-spec.md generation approach Frontend, A11y, and Dev converged on scaffold-fill. PM implied freehand but had not committed. Reference HTML skeleton with injection-point comments required as part of Step 1 spec scope.

14. Final Decision

Final decision: Approve with revisions

The plan is technically sound, correctly scoped, and the additive design holds up under cross-functional scrutiny. All three blocking issues (XSS/escaping/CSP, Write failure mode, named-variable synthesis contract) have been resolved by the inline edits applied in Pass 1. The plan is ready to implement once the three open Unresolved Questions are decided before Step 1 authoring begins.

15a. Inline Edits Applied

# Section Action Content summary
1## Reuse notesappendNamed-variable contract for synthesized_report
2Step 1editNine-section spec scope with security, accessibility, head requirements, skeleton requirement, section-presence verify
3Step 3editReview-only skip, failure mode, default theme, progressive enhancement, path-safety clauses
4Verification item 4editjq command replacing fragile grep
5Verification item 6editFixture path, regression check, extended self-containment grep
6VerificationappendItems 7 (keyboard a11y) and 8 (XSS smoke test)
7Plan title blockquoteeditRemoved floating filename-rename blockquote
8## Next StepseditRename entry now formal with fenced prompt
9## Next StepsappendDark mode out-of-scope + Next Steps entry
10## Next Stepsinsert after## Unresolved Questions section with three open decisions

15b. Complete Revised Plan

The source plan file reflects all inline edits. This section is a reference view of the plan as it stands after Pass 1. Key additions from the panel:

  • ## Reuse notes: named-variable contract (synthesized_report retained through Steps 7 and 8)
  • Step 1: nine-section spec scope including Security & Escaping Contract and full WCAG AA accessibility requirements; reference skeleton required; section-presence verify
  • Step 3: review-only skip clause, Write failure mode, default theme, progressive enhancement, path-safety normalization
  • Verification: jq-based version check; fixture-based smoke test; items 7 (keyboard a11y) and 8 (XSS smoke test)
  • Next Steps: formal rename entry, dark mode out-of-scope entry
  • ## Unresolved Questions: markdown rendering trust boundary, review-only mode output, background-mode path surfacing