レクチャー資料や導入ガイドの handout を作りたいとき、題材のヒアリングから外部依存ゼロの単一 HTML 資料と同梱物一式を生成したいときに使う。
インストールする前に、エージェントに与えられる指示の中身を確認できます。
Purpose & Output Contractの最小の実成果物をmain contextで作成する。effect別のparse/open・secret・irreversible・corrupt guardだけを実行し、現物path・digest・開き方を提示してからaccept-as-is/light/standard/detailedを記録する。accept-as-isはその場でhandoff完了とし、後続sectionを実行しない。
以下の既存workflow・goal-seek・評価・修正sectionはlight/standard/detailedが記録されてsemantic_evaluator_startedへ遷移した場合だけ実行する。release/exhaustiveは別の明示eventを必要とする。
handout.html (writer C11) / handout-config.json と assets/ (writer C19) / README.md (writer 本 skill) であり、writer 割り当ての正本は C19 の bundle_writers。/handout-verify が返した summary.json の verdict と gates をそのまま載せる。build_stage)。第1稿 (draft) = ゲート集約の verdict が pass で、同梱物が既定の命名規則の出力ディレクトリに揃った状態。ここで利用者へ現物を渡して止まる。仕上げ (release) = 利用者の指摘を反映し、意味レビューと挿絵まで回した状態。HTML の組み立て自体は決定論 script へ委譲し LLM で書かない。読みやすさの最終判定は assign-handout-readability-evaluator (C03) へ委譲し、本 skill は返った verdict を受けて資料を直す側に回る。release の visual-fit は alt 文ではなく埋め込み画像の実画素を全件開き、節内容と画像計画への一致を確認して初めて PASS にできる。
frontmatter の hearing_required_items_r21 が plugin 全体で唯一の項目定義である。ここに宣言した項目を確定してから設計へ進み、確定していない項目は聞き直す。項目の形式と必須性を最終的に落とすのは validate-handout-config.py であって本文の散文ではない。
提示順 (demo_first / explain_first) は質問しない。既に取得している prior_knowledge_level から C12 の CR-PRESENTATION-ORDER が決定論導出する。利用者が自発的に述べたときだけ、その値を明示上書きとして構成データへ書く。
粒度の項目は frontmatter の hearing_required_items_r22 にある。既定値は resolve-handout-preset.py の granularity_defaults から doc_type を鍵に引き、既定を提示して上書きの要否だけを 1 問で聞く。無回答なら既定を採用して進み、停止しない。
検証済みの構成データを直接渡された場合はヒアリングを省き、非対話経路として設計以降へ進む。逆抽出 (C08) からの再生成と自動実行をこの経路で塞がない。
用途プリセットは resolve-handout-preset.py で解決し、用途語彙とプリセット内容を本 skill が持たない。解決した preset とヒアリング結果と素材の論理名を handout-content-architect (C05) へ渡して構成データ設計を委譲する。C05 が status=blocked を返したら、欠落項目をヒアリングへ差し戻してから再委譲する。
資料全体に効く 3 つの指定は C05 へ渡す前にここで確定させる (節ごとの設計では決まらないため)。(a) 文章量は detail_level で選ぶ — 「もっと詳しく / 要点だけでいい」は書き足しや削りではなく水準の選択で、節あたりの予算は assets/tokens/<theme>.json#text_limits.section_body_chars_by_detail_level が正本 (NAR-09 が上下双方を検査する)。(b) 一覧で最初に目に入る 1 枚を thumbnail_asset_id に指定する (素材があるなら未指定にしない — 検査は W-THUMBNAIL-ABSENT・G1。既定で先頭節の挿絵を流用せず、どれを表紙にするかは必ず選ぶ)。(c) 本編の最後に section_kind: "closing-summary" を 1 節置く — 各節を要点へ絞るほど、節をまたいで残るものが本文中のどこにも書かれなくなるためで、冒頭の goal は予告であって総括ではない。
節の中の並びも C05 へ渡す前に決めておく。本編の節は 見出し → 絵 1 枚 → 目的と言いたいこと → 要点を並べる部品 → 補足 の順で、構成データ側では blocks[0] を image (要請があれば diagram) にする (config/handout-visual-policy.json#opening.section_opening.order・検査は W-SECTION-VISUAL-NOT-FIRST)。前へ出すのは先頭の 1 枚だけで、その 1 枚は「具体部品」に数えない (節の中身が絵だけなら LANG-06)。情報量が多いときは 1 節を厚くせず節を増やしてよい — 増えた分は目次が 2 行まで折り返して受ける (nav.max_rows) ので、heading は nav.max_chars に収める。絵の粒度は冊子で 1 つに揃える (画風系統・密度・視点は全節同値。混在は C21 の E-IMG-GRANULARITY-DRIFT で停止する)。
C05 が書いた構成データは validate-handout-config.py で検証し、--normalize の出力を以後の唯一の入力にする。正規化済み構成データには読み手・前提知識・用途が入っている必要がある。C03 が委譲入力の reader_profile をこれらから組み立てるため、欠けたままでは意味レビューへ進めない。
素材の data URI 化 (embed-assets.py)、概念図解の inline SVG 生成 (render-diagram-svg.py)、使用アイコンだけの symbol 生成 (build-icon-sprite.py)、挿絵の生成委譲 (srg-image-bridge.py)、単一 HTML のレンダリング (render-handout.py) を決定論 script 列として実行する。本 skill はこれらの引数を組み立てるだけで、HTML の断片を自分で書かない。
共有時のサムネイル (OGP)・帯の一番上の題・紙面に出さない日付 (root 属性 data-hb-date が唯一の運び手)・節番号と題の区切り・2 行まで折り返す常時表示の目次・常駐する操作帯 (メモを埋め込んだ HTML の保存) は、すべて C11 が構成データから決定論に組み立てる面である。指摘を受けても HTML を手で足さず、出ていなければ C11 か構成データ側の欠落として扱う。
挿絵の委譲は exit 0 が「生成した」と「skip した」の両方を含むため、exit code でなく stdout の status を読む。status=skipped のときは skip_reason (srg-absent = 委譲先の SRG 実体が解決できない / runtime-absent = node か codex が無い) をそのまま生成レポートの warning へ転記し、画像なしで先へ進む。skip を黙って成功へ畳まない — 挿絵が無いまま出来上がったことが読み手に見えなくなるためである。
利用者が画風の参照画像または参照フォルダを示した場合は、選んだ実在画像を画像計画トップレベルの style_reference_paths として C21 へ渡す。説明文へ「漫画調」「青基調」と書くだけで代替しない。C21 は参照画素を SRG 作業域へ無加工で配置し、全節の styleReference へ同じ anchor として結線する。指定済み参照が欠落していれば fail-closed とし、参照なしの生成を成功扱いしない。
検証ゲートは /handout-verify (C09) を --json-report つきで起動して実行し、返った summary.json の verdict と各ゲート面の状態をそのまま受け取る。状態分類と全体 verdict の判定規則は C09 の CR-GATE-AGG が単一正本であり、本 skill では再実装も再解釈もしない。verdict が pass 以外なら該当箇所を直して再実行する。not-run を「通った」と読み替える判断を本 skill 側に持たない。
出力先ルーティングは route-handout-output.py (C19) へ --place-config と --assets-src を渡して実行する。構成データと素材原本の複製は C19 に行わせ、ディレクトリ名の組み立ても C19 の責務である。C19 が返した出力ディレクトリ直下へ README.md を書くのは本 skill の責務で、節は原題・目的・適用プリセット・同梱物一覧・各同梱物の使い方とする。
委譲するのは release 段だけである (draft_first.skipped_in_draft.readability_review)。第1稿は利用者本人が現物を読むため、レビュアーを挟むより速くて正確な判定が既に得られている。ここを draft へ前倒しすると、利用者が一度も見ていない資料の読みやすさを推測で詰める周回に時間を使うことになる。
release 段でゲートの verdict が pass になった資料について assign-handout-readability-evaluator (C03) へ 1 回委譲する。C03 は verdict を無加工で返し、再レビューの起動と打ち切りは本 skill のゴールシークだけが持つ。
初回の委譲は scope を渡さず全体を読ませる。2 回目以降は、直前の周回で実際に手を入れた節の id だけを scope として渡す。 触っていない節を毎周読み直しても、同じ HTML から同じ判定が返るだけで待ち時間と読み込みだけが増える。節をまたぐ軸 (goal-chain / opening-order / nav-scannability) はレビュアー側が scope に関わらず全体で見るので、絞ったことで全体の筋の断裂を見落とすことはない。
scope に載せるのは直した節であって、指摘が出ていた節ではない。指摘に対して別の節を直したなら渡すのは直したほうである。また scope へ添えてよいのは節 id だけで、何周目か・前回何を指摘されたか・どこをどう直したかは渡さない。渡した時点で独立 context が壊れ、レビュアーの verdict に「もう十分だろう」が入る。
scope を絞ったときの verdict=PASS は、それだけでは release の完了根拠にならない。 verdict はレビュアーが読んだ範囲の findings から計算されるので、severity=high の指摘を受けた節を直さないまま scope から外せば、その節は読まれず findings に現れず PASS が返る。これを塞ぐため、本 skill は受け取った severity=high の指摘を解消するまで自分の側に残す。解消とは資料を直したうえで、その節を次の scope に載せて再度レビューを受け、その周の findings に現れないことである。同じ形で、最後に手を入れて以降まだ一度も読まれていない節も未解消として扱う。初回の全件レビューで読み終えた無改修の節は既読なので消え、直した節は次周の scope に載せて読ませれば消える。「そのレビューで読まれなかった節」を数えてはならない — 2 周目以降は scope を絞る以上つねに未読の節があり、それを未解消と数えると release へ永久に到達しない。
not_reviewed を一括で未解消にしてはならない。この配列は性質の異なる 2 群を運んでいる — (a) scope により読まなかった節・軸 と、(b) machine_gate_overlap により除外した面である。(b) は決定論ゲートが既に見ている面を二重に指摘しないための除外であり、C06 は全件レビューでも必ず理由付きで残す。したがって not_reviewed は非空が正常形であり、(a) についても上のとおり「未読のまま残っているか」で見る。
これは verdict の再判定ではない。severity を決めるのも PASS/FAIL を決めるのも C06 のままで、本 skill が持つのは「受け取った指摘がまだ残っているか」だけである。
status=blocked は verdict を伴わない。pass とも fail とも読まず、ゲート修復へ戻してから委譲し直す。suggestion は提案であって適用指示ではなく、どう直すかは本 skill が決める。題材のヒアリングから構成データを確定し、外部依存ゼロの単一 HTML 資料 1 個と同梱物一式が既定の命名規則で出力され、自己完結性・a11y・印刷・言語規約・日付表記の全ゲートが exit0 になった状態。
初心者・非エンジニア向けの資料は毎回ゼロから手書きされ、部品もデザイン言語も資産として残らない。構成データ駆動へ移せば反復配布できるテンプレートになる。
判定は 3 つしかない。構成が確定したか (G1) / 資料が読める形で成立したか (G2) / 渡せる形で開示したか (G3) である。段 (draft / release) が変えるのは判定の数ではなく、各判定を満たしたと言える中身である。
分類の基準は「利用者が現物を見るまでに要るか」の一点であり、重要度ではない。release 側へ回した中身は品質を捨てたのではなく、現物が出てから効くものを第1稿の待ち時間から外しただけである。
0 件を求めるのは次の 13 コードであって、C12 が出す warning の全件ではない。図解密度と文字量 (W-VISUAL-ABSENT / W-DIAGRAM-FEW / W-TEXT-HEAVY / W-TEXT-RUN / W-COPY-LONG)、層の切り分け (W-DETAIL-ABSENT / W-LAYER-ORDER / W-DETAIL-FLOWLESS)、冒頭の置き方 (W-HERO-LONG / W-OPENS-PROSE)、節の入口と共有面 (W-SECTION-VISUAL-NOT-FIRST / W-THUMBNAIL-ABSENT)、用語の言い換え (W-GLOSSARY-EMPTY)。最後の 1 つを外せない理由は criteria:IN1 が「用語言い換え宣言の欠落 0 件」を要求する一方、欠落を見る診断がこれしか無いためである (error 側の E-GLOSSARY-DUP は重複を見るので代わりにならない)。いずれも同じ 1 回の出力に並んでいるので、種別ごとに項目を立てても検査は 1 つも増えず、同じ出力の読み直しだけが増える — だから 13 項目ではなく 1 項目で受ける。
残りの warning は利用者が選んだ結果を報告するものであり、完了を阻まない。とりわけ W-SECTIONS-MANY は本文が明示的に許可した行為 (情報量が多いときは 1 節を厚くせず節を増やしてよい・nav.max_rows) に対して出る。これを欠陥として数えると、許可した行為を選んだ資料が draft を完了できなくなる。「warning 全件 0」を完了条件にしないのはこのためで、0 件を求める対象を上の 13 コードに固定してあるのはその境界そのものである。
それでも種別を挙げるのは、0 件でない資料が具体的にどう読まれないか (図が無く文章が長い / 要点より先に手順が来る / 冒頭が段落で始まる / 節の入口に絵が無い = 読み手が読まない状態そのもの) を設計時に思い出すためである。速さのためにこれらを外さない — C12 は数百ミリ秒で終わるので待ち時間の原因ではない。
ヒアリング必須項目 (hearing_required_items_r21 / _r22) の確定もここで落ちる。never_inferred_fields (doc_type / out_dir) 以外は 1 ラウンドで聞くか素材から推定で埋めてよく (回答を待たずに進む。非対話経路では検証済み構成データがその代わりを満たす)、埋まったかどうかは C12 の必須検査が判定する。項目ごとの検査コードは frontmatter の checked_by が持つので、散文で二重に数えない。
criteria:IN1 はこの判定の別名である。
/handout-verify の集約 verdict が pass で、同梱構成データからの再生成がバイト一致するdraft_first.skipped_in_draft の可読性レビュー) から回収した verdict が PASS で、未解消の severity=high 指摘が 0 件であり、最後に手を入れて以降まだ一度も読まれていない節が 0 件であるゲート面を面ごとに数え直さない。集約は C09 の CR-GATE-AGG が単一正本であり、本 skill が受け取るのは verdict 1 個である。第1稿の粒度 (draft_first.first_draft_detail_level — 全体を詳細で作ってから削らない) が守られているかもここで落ちる。実態との一致を見るのは C22 の NAR-09 / NAR-10 であって散文の自己申告ではない。
release の visual-fit は alt 文でなく全 illustration の実画素を開き、(a) 節の人物/役割主体・行為・場所・主役の具体物、(b) 読み順、(c) 指定された画風・配色・俯瞰角度、(d) 冊子内の統一と節ごとの場面差、を確認して初めて PASS にできる。
criteria:OUT1 のゲート面と criteria:OUT2 はこの判定の別名である。
README.md を書き、生成レポート (適用部品・埋め込みサイズ・warning・ゲート結果・仮置き項目・載せなかった項目・第1稿で回さなかった工程) を返して停止したfirst_draft_detail_level のままであるdraft でこの判定を満たすことは completed ではない。第1稿は速い完了ではなく、未完了だが読める状態である。 開示そのものを判定に入れてあるのは、回さなかった工程が黙って消えるのを防ぐためであり、criteria:OUT3 はこの開示が実走で起きたことを見る。
criteria:OUT1 の同梱物面はこの判定の別名である。
検査は 1 つも減っていない。3 判定は同じ検査を、それを返す機械の単位で束ね直したものである。
| 旧 | 現 | 旧 | 現 |
|---|---|---|---|
| D1 ヒアリング必須項目 | G1 | D8 集約 verdict | G2 |
| D2 第1稿の粒度 | G2 | D9 同梱物・README・生成レポート | G3 |
| D3 C12 exit0 | G1 | D10 節の入口・共有面の警告 | G1 |
| D4 図解密度・文字量の警告 | G1 | F1 仮置き項目の確認と反映 | G3 |
| D5 層の切り分けの警告 | G1 | F2 可読性レビューを回した | G2 |
| D6 冒頭の置き方の警告 | G1 | F3 C03 verdict PASS・visual-fit | G2 |
| D7 決定論 script 列での生成 | G2 | F4 粒度を上げた範囲 | G3 |
frontmatter の goal_seek.engine: inline / fork: subagent を実行契約とする。固定手順は使わず、未達 checklist と担当 prompts/*.md からその周回の操作を都度生成する。周回上限は goal_seek.max_loops の一本値だけであり、段ごとの上限も criteria ごとの反復上限も置かない。段が変えるのは回数ではなく、何を未達として拾い何のために回してよいかである。
skipped_in_draft により回さなかった工程、(4) 指摘の受け取り先が R5-refine であること、を提示する。第1稿は速い完了ではなく、未完了だが読める状態である。各周回で inner criterion (IN1) を検証し、その周回の修復が終わった時点で outer criterion (OUT1 / OUT2) を 1 回評価する。評価のための追加の周回予算は持たない — 資料を直さずに再評価しても決定論検証の結果は変わらないため、fail なら次の 1 周として修復へ戻るだけである。IN1 / OUT1 / OUT2 はいずれも決定論検証であり draft でも省かない (省くと開けない HTML を渡すことになる)。
eval-log/guide-doc-generator/run-handout-build-goal-spec.json へ、各 checklist の status と evidence を eval-log/guide-doc-generator/run-handout-build-progress.json へ記録する。prompts/<R-id>.md を読み、Agent で分離 context に fork する。ユーザー判断が必要な境界だけ AskUserQuestion を使う。eval-log/guide-doc-generator/run-handout-build-intermediate.jsonl へ 1 行 append-only で記録する。正本 plugins/harness-creator/skills/run-build-skill/schemas/goal-seek-loop.schema.json の intermediate_artifacts[] が必須とするのは iteration、original_goal、current_goal_snapshot、delta_from_original、merged_directive_for_next、drift_signal の 6 キーであり、本文はこの 6 キーの意味を再定義しない。次周回は直前の merged_directive_for_next を必須入力にする。original_goal_hash を各行へ足す。これは正本には無い local 拡張である。 正本では original_goal_hash は progress.json のトップレベルに 1 つ置かれ、照合相手は intermediate_artifacts[0].original_goal である。本 skill は照合相手を第三のファイル run-handout-build-goal-spec.json の original_goal に取るので、行ごとに持たせている。正本由来と local 拡張の境界はここにあり、後者を正本準拠と呼ばない。drift_signal には正本の値域外を書かない。差分ゼロは aligned、前周回が無い初回は initial である。この 1 語だけが周回ごとに変わり次の周回の判断に使われるので、none のような値域外の語を置くと「差が出ていない」のか「判定していない」のかが区別できなくなる。下の検証はこの値域だけを正本から写して実行時に照合する — 意味は正本にあり、写しているのは 6 語の集合だけである。正本の enum が将来変わっても写しは自動追随しないが、劣化方向は「通すべき新値を止める」側なので fail-closed を崩さない。feedback_contract.criteria が全て PASS のときだけである。draft 段の停止は完了ではなく引き渡しであり、progress には未達として各判定の release 行を残す。build_stage を記録する。draft の停止を「全項目 PASS」と書かない — 記録が完了に見えると、繰り越した release 行が回収されないまま積み上がる。各周回後に次を実行し、中間成果物の欠落と goal drift と hash 不一致を fail-closed にする。
python3 - "eval-log/guide-doc-generator/run-handout-build-goal-spec.json" "eval-log/guide-doc-generator/run-handout-build-intermediate.jsonl" <<'PY'
import hashlib, json, sys
goal = json.load(open(sys.argv[1], encoding='utf-8'))
rows = [json.loads(line) for line in open(sys.argv[2], encoding='utf-8') if line.strip()]
canon_keys = {'iteration','original_goal','current_goal_snapshot','delta_from_original','merged_directive_for_next','drift_signal'}
required_keys = canon_keys | {'original_goal_hash'}
drift_values = {'initial','aligned','compressing','stagnant','widening','oscillating'}
expected = hashlib.sha256(goal['original_goal'].encode('utf-8')).hexdigest()
assert rows, 'intermediate.jsonl is empty'
for row in rows:
assert required_keys <= row.keys(), required_keys - row.keys()
assert row['original_goal'] == goal['original_goal']
assert row['original_goal_hash'] == expected
assert row['drift_signal'] in drift_values, row['drift_signal']
assert len(rows) == rows[-1]['iteration'] + 1, (len(rows), rows[-1]['iteration'])
PY
criteria:IN1: validate-handout-config.py が exit0 で、lead-line と判断軸の一文・日付フィールド・用語言い換え宣言の欠落が 0 件である。criteria:OUT1: 生成した単一 HTML が外部依存ゼロで開き、検証ゲートが全て exit0 になり、出力先に資料 HTML と構成データと素材と README が揃うことを受入テストが確認する。criteria:OUT2: 同梱された構成データからの再生成で出力 HTML がバイト一致することを受入テストが確認する。criteria:OUT3: 題材と素材だけを与えた実起動で、質問ラウンドが draft_first.max_question_rounds_before_first_draft 回以内に収まり、G1-G3 の draft 行が揃った時点で completed を宣言せず停止して成果物のパス・仮置き項目・回さなかった工程を提示し、C03 委譲が draft 段で起動しておらず、挿絵生成 (C21) は R25 (goal-spec C69) により draft 段でも起動していることを実走の痕跡で確認する。config/handout-visual-policy.json#content_selection)。載せなかった項目は生成レポートで明示し、黙って落とさない。config/handout-visual-policy.json#layering)。config/handout-visual-policy.json#opening)。lead_line が 1 行で担い、その直後は形 (図解・カード・表)、TEXT はその後の補足 1 本。location の逐語引用を落とすと修正箇所が当て推量になる。draft_first.skipped_in_draft に挙がった工程だけである。まだレビューはありません。使ってみた感想をお寄せください。
概要と使いどころ
アプリ・Webサービス・業務ツールの制作を、証拠分析→確定的な初稿→要件定義→体験設計→機能分解→実装→品質ゲート→リリース判定の手順ゲート制で進めるスキル。質問で要件を埋めるのではなく、依頼文・既存コード・資料・ログから最有力案を選び、動く成果物を先に出して差分で改善する。ユーザーが「アプリを作りたい」「ツールを作って」「〜を自動化したい」「システム化したい」「要件定義」「仕様を決めたい」「UI/UXを設計して」「体験を良くしたい」「機能を洗い出して」「MVPを決めたい」「品質チェック」「リリースしていいか判断して」などと言ったら必ず使用する。外部データの取込・マスタ・締め処理を伴う業務システムでは references/data-lifecycle.md も併用する。新規・既存を問わずアプリの制作・改善・リニューアルで使用する。
Webアプリの準備→要件定義→設計→実装→公開→品質ゲートを実行する内部オーケストレーター。Claude Codeの /build-app /improve-app、Codexの $build-app / $improve-app から明示的に委譲された場合、custom agent起動時、または利用者が $app-orchestrator を明示した場合だけ使用する。一般のアプリ相談から暗黙起動しない。
run-extract-blueprint が生成した章別ブループリントの忠実性を独立 context で評価したいとき、事実/推測区別と粒度と被覆を検証し draft_hash に束縛した PASS/FAIL verdict をローカル品質ゲート (C01 の周回内の受入判定・差し戻し) へ渡したいときに使う。
確認点で利用者が見る深さを選んだあと打ち合わせ資料を作り手とは別の目で確かめたいとき、正確さ・言葉・見た目・シンプルさの指摘を資料の編集なしで受け取りたいときに使う。
生成した handout 資料が初心者に伝わるか読みやすさレビューを依頼したいとき、独立 context のレビュアーから指摘と根拠つきの verdict を回収したいときに使う。
Notion ページを描画する直前に粒度を検証したいとき、info-collector-agent ページと同等の section 充足度を section_canonical_map 基準で機械検証したいときに使う。