/visual-html-renderer

name: visual-html-renderer
description: |
  HTMLを最終成果物として生成・検証・プレビューしたい時に使う共通レンダラー。Use this shared renderer when the user wants content turned into a final, validated, previewable HTML artifact. 現行rendererの表現能力を前提にagentが文書モデルを直接設計し、表・リスト・コード・注記・図・生成画像を選んだHTML bundleとセッション限定のプレビューURLを提示する。Triggers: html出力して, HTMLにして, HTMLで出して, この内容をHTMLで出して, HTMLでプレビューして, HTMLレンダラー, HTML出力を共通化, 図示つきHTML, visual HTML renderer, render this as HTML, turn this into HTML, create an HTML preview, generate a visual HTML report, make this a reviewable HTML document, diagrammed HTML report。使用しない場面: Plan Mode 中の計画確認プレビュー、設計内容そのものの作成、Notion投稿だけ、既存HTMLの軽微な見た目修正だけ。Do not use for: Plan Mode proposal previews, creating the design content itself, Notion-only publishing, or minor visual tweaks to existing HTML.
argument-hint: "[document-model.json] [--output output/<date>_<slug>] [--preview auto|tailscale|local|off]"
strict_procedure: true

visual-html-renderer

役割

HTML出力系skillの共通レンダラーとして、個別HTML生成ロジックを置き換える。

重い処理は `scripts/html_review_workbench/` のPython実装に委譲し、このskillは入力確認、呼び出し順、ガード、検証を担当する。

Role

Use this skill as the shared renderer for HTML-output workflows. It replaces one-off HTML generation logic with a fixed flow: understand the requested content, design the document model, run the shared CLI, validate the bundle, and return a preview URL. Heavy implementation stays in `scripts/html_review_workbench/`; this skill owns input handling, workflow order, gates, and verification.

Plan Mode 中の計画確認プレビューには、このskillを使わない。その場合は `plan-preview` を使い、一時HTML previewとして扱う。`visual-html-renderer` は通常の最終HTML成果物、レポート、レビュー可能な文書のbundle生成だけを担当する。

Do not use this skill for Plan Mode proposal previews. Route those requests to `plan-preview`; this skill is only for final HTML artifacts, reports, and reviewable document bundles.

Strict procedure profile

• Strictness: strict-procedure。HTML表現設計、文書モデルread-back、render、validate、preview URL提示までがこのskillの成果。
• Hard gates: 外部サービス送信、画像生成、外部アップロード、shared state変更は該当する承認ゲートに従う。
• Forcing function: rendererブロック対応表、render前自己レビュー、`check-model` CLI、Completion receipt。
• Completion receipt: HTML表現設計、生成物、検証、preview、未実施層を最終応答に必ず含める。

言語方針 / Language behavior

Follow the language of the latest user request for progress updates, final responses, preview handoff text, and user-facing summaries. 日本語の依頼には日本語で、英語の依頼には英語で返す。入力本文や引用内容は、ユーザーが翻訳を求めない限り勝手に翻訳しない。HTML内の見出しや本文は、元資料の言語、ユーザーの指定、レビュー対象読者に合わせる。

基本手順

0. Plan Mode 中の計画確認プレビュー、`<proposed_plan>` の視覚確認、計画URLの追加が目的なら、このskillではなく `plan-preview` を使う。 1. 文書モデルとレンダリングオプションを確認する。 2. 文書モデルが未指定の場合は、直前の成果物またはユーザー指定内容を読み、HTML表現設計フェーズで構成を決める。 3. 現行rendererのブロック型に合わせて、agentが `document-model.json` を直接作る。 4. 一時的な入力退避が必要な場合だけ `build-model` で source-capture draft を作ってよい。ただし draft は最終モデルではないため、そのまま `render` へ渡さない。 5. render前に `document-model.json` を読み返し、未再構成テキストの流し込みやrenderer非対応型の使用がないことを確認する。 6. `image.generation_status=requested` のブロックがある場合は、`imagegen` skillで画像を生成し、`attach-image` CLIで文書モデルへ添付する。 7. `check-model` CLIで最終render前の文書モデル品質を検査する。 8. `render` CLIでHTML bundleを生成する。 9. `validate` CLIでHTML、asset、comment schema、図・画像の非空を検証する。 10. ユーザー向け最終HTMLでは既定で `preview` CLIを `--mode auto` で起動し、返却JSONの `url` と `stop_command` を最終応答に必ず書く。 11. preview 起動直後に、Monitor ツールで `watch-comments` を開始する。これによりブラウザからのコメントを自動検知できるようになる。Monitor 起動コマンド: `python3 -m scripts.html_review_workbench.cli watch-comments --root <output-dir>`。自前の polling スクリプトではなく、この CLI を使うこと。イベント受信後の処理は `reviewable-design-doc` skill の「コメント自動回答と解決待ちゲート」セクションに従う。

Basic Workflow

0. If the request is a Plan Mode proposal preview, `<proposed_plan>` visual check, or plan preview URL request, use `plan-preview` instead of this skill. 1. Check the document model and rendering options. 2. If no `document-model.json` is provided, inspect the user's content or the latest artifact and design the HTML structure yourself. 3. Create the final `document-model.json` directly using the renderer-supported block types. 4. Use `build-model` only as a source-capture draft when temporary input storage is needed; never pass that draft straight to `render`. 5. Read back the model before rendering and confirm that raw or unsupported content was not dumped into the model. 6. If image blocks request generation, use the `imagegen` skill and attach images with `attach-image`. 7. Run `check-model`, then `render`, then `validate`, then `preview`. 8. For user-facing artifacts, use `preview --mode auto` by default and include the returned `url` and `stop_command` in the final response. 9. Start `watch-comments` immediately after preview startup so browser comments can be detected.

HTML情報設計の規約

HTML出力はテキスト変換ではなく、最終HTML bundleの情報設計として扱う。

• 入力本文の記号や行構造をそのまま表示へ流し込まない。
• まず内容の意味、用途、読者、比較軸、時系列、依存関係、操作手順、注意点を読み取り、HTML上の表現を選ぶ。
• 比較は表、手順は番号付きリスト、並列項目はリスト、注意・決定・前提はcallout、処理や依存関係はdiagramブロック、画面イメージや説明画像が有効な箇所はimageブロック、コマンドやログはコードブロックにする。
• diagramブロックはMermaid sourceを構造保存用に残し、既定では生成画像を主表示にする。生成画像が未添付の場合、全diagram kindを同梱 mermaid.js でブラウザ描画する。Mermaid v11系の記法に準拠してsourceを書く。CDNは使わず、standalone publishでは mermaid.js と図の拡大用scriptをHTMLへinline化する。
• Mermaidで描画される図は、図右上の拡大ボタンから全画面表示に切り替え、pan / zoom で詳細を確認できる。
• 現行rendererのブロック型で表現が足りない場合、未再構成テキストへ戻さず、必要なブロック型やレンダリング拡張を検討する。

<!-- BEGIN SHARED: md-file-prohibition -->

• 一時入力ファイルが必要な場合も `.md` は使わない。`source.txt`, `input.txt`, `source-content.txt` のようなプレーンテキスト名を使う。
• ユーザーへの進捗・最終報告では、`.md` やMarkdownという語をHTML出力の前提として扱わない。

<!-- END SHARED: md-file-prohibition -->

rendererブロック対応表

現行rendererで最終HTMLに使う表現は、実装上の描画挙動に合わせて選ぶ。

| block type | rendererの扱い | contentに書くもの | |---|---|---| | `html` | HTML片をそのまま挿入する | agentが設計した `<p>`, `<table>`, `<ul>`, `<ol>`, `<pre><code>` 等の構造化HTML | | `callout` | HTML escapeしてcallout表示する | 決定、注意、前提などの短いプレーンテキスト。HTMLタグは書かない | | `diagram` | Mermaid sourceを保存し、同梱 mermaid.js のブラウザ描画、または生成画像を表示する | `diagram_source` または `diagram.source` にMermaid v11系のsource。sourceに無い関係を画像側で追加しない | | `image` | 添付済み生成画像を表示する | `image.prompt`, `image.alt`, `image.caption`, `image.source_path` | | `se