fdk

スキル：fdk — Framework Dev Kit（セルフ完結型）

オンデマンド：セッション開始時に自動で読み込まないでください（ほとんどのセッションは別のプロジェクトの開発です）。このスキルには、どのプロジェクトでも使えるガイダンスが十分に含まれています。末尾の「完全版」の項目は、フレームワークリポジトリ内にいる場合にのみ適用されます。

WHAT

目的と背景

• 目的： オンデマンドで使える、自己完結型の入口です。フレームワーク自体の修正や、どのプロジェクトでもスキルを抽出・作成する際に使います。あらゆる変更前の事前確認、出荷と HTML のルール、下流への影響範囲の把握、問題ツリーの管理を行います。
• 利用する場面：
  • フレームワーク自体を修正する場合（スキル／ルール／バリデーター／フック／Wiki）、または
  • 任意のプロジェクトのセッションでスキルを抽出・作成する場合。
• 対象外： 通常のプロジェクト機能開発には使いません（セッションの大半はこれに該当します。ADR-004 を参照）。セッション開始時に自動実行もしません。

デフォルトの考え方 — Donella Meadows：症状ではなく、システムを修正する

フレームワークに関するすべての作業で、システム思考とフィードバックループ（Thinking in Systems）の視点を用います。

• エラーや問題に遭遇したら、「どの構造がこれを生み出したのか？」とまず問いかけます。 痛い箇所をいきなり塞がないでください。繰り返す症状は、フィードバックループの欠如や誤りを示すシグナルです。同じ種類のエラーに対して2度目の手動修正を行うのは、プロセス上の誤りです。正しくは、そのエラーが再発しないよう構造（ルールのハーネス、スキル、テンプレート、フック）を変更します（これは failure-flywheel と problem-tree が担っていることです）。
• 最小のコストで最大のレバレッジポイントを選びます。 Meadows の段階に沿うと、パラメーターの修正 ＜ フィードバックループの追加 ＜ 情報フローの変更 ＜ ルールの変更 ＜ 目標／パラダイムの変更、となります。コードを書く前に、次のように自問してください。この修正はどの段階に当たるか？ より高い段階を、低コストで実現できないか？（例：エージェントに覚えるよう言うのは低い段階です。それよりも、自動で検出するバリデーターを追加し、ルールを変更します。）
• 一度きりの対応ではなく、フィードバックループを育てます。 変更ごとに、システムがずれを自ら検知できるよう、シグナルが戻る経路（決定論的な検証、台帳、ログ、評価）を設けます。フィードバックループのない変更は、盲目的な変更です。
• 遅延を尊重します。 新しいルールやスキルの効果が表れるまでには、複数のセッションがかかります。早まって結論を出さないでください。前の修正が効く前に、さらに修正を重ねないでください。測定できるよう、台帳に日付を記録します。

2つ目の指針 — Hub とプレゼンテーション（ユーザー体験、2026-07-03 のフィードバック）

Meadows の考え方に加え、フレームワークのあらゆるツール／スキル／Hub は、ユーザーにとって使いやすく安全であるという原則に従います。

• 名前は1つの Hub にまとめ、説明は範囲で指定できるようにします。多くのサブコマンドを覚えさせないでください。 関連する作業をすべて1つの Hub で行い、ユーザーはサブコマンドを覚えるのではなく、範囲（全体、1つ以上の部分、同等の部分／規模）を説明するだけで済むようにします。コマンド名は短く、手が覚えるほど入力しやすいものにします（ユーザーは curl に慣れています。覚えにくい名前は呼ばれず、役に立ちません。例：長い名前の代わりに、総合的なヘルスチェックの入口として medic を使います）。
• TL;DR — ユーザー向けの要約は簡潔に、要点はすべて含めます。 ユーザーには「長すぎて読まない」という習慣があります。短くても不十分な内容や、説明を惜しむ内容にしないでください。
• 思考モデルを透明にします。 ユーザーは think の部分を読んで、進め方が正しいか確認します。推論を隠さないでください。
• 出力の最後に要約を加え、使い方を自然に伝えます。 このツールの役割を簡潔に振り返り、代表的なユースケースと、意外なユースケース（ユーザーが想定していなくても使える場面）を示します。そうすることで、ユーザーは質問せずに使い方を学べます。
• 透明性は安全につながります。パフォーマンスより使いやすさを優先します。 クエリの最適化だけでなく、ディレクトリ構造や内部の仕組みもユーザーが読めるようにします。表示されたものが透明であれば、ユーザーはシステムを安心して使えます。内部での最適化より、使いやすさを優先します。

メンタルモデル

事前確認（pull → ルール → grep／影響範囲 → 提案して STOP → 対象を絞って実施・検証 → 下流の構成を確認）→ 修正 → ［スキルを抽出・作成 · 別プロジェクトから kit を取り込む · リポジトリ内の完全版］→ 出荷前に ci-local + fdk-uat → 終了前に problem-tree を更新

Input và output contract

	Field	Required?	Ý nghĩa
In	việc framework hoặc skill cần distill	có	mô tả của user
In	repo hiện tại (framework hay dự án khác)	có	quyết định dùng bản đầy đủ hay kit
Out	draft propose chờ duyệt, rồi thay đổi surgical đã verify	có	không code thẳng
Out	llmwiki/html/fdk-problem-tree.html đã rà/cập nhật	có mỗi lần gọi	trước khi kết thúc turn
Out	PR qua kit	khi dev từ dự án khác	fdk-kit.sh submit

ルールと機能

• RULE-01 (MUST): push／PR を出す前に必ず python3 fdk/tools/ci-local.py を実行してください（すべての GitHub ワークフローの run: ステップをローカルで一通り実行します。L4）。L2（pre-commit／medic）は L4（CI fresh-clone）と同じではありません。CI でしか実行されないゲートや、Stop-hook で自動修正されるものがあるため、commit してすぐ push すると L2 を通過しても CI が失敗することがあります（実際の事故：R3 index-sync 2026-07、search-index + skill-provenance 2026-09-08）。すべて成功してから push し、その後 /fdk-uat（canary + main-URL smoke）を実行してから完了を報告してください。[[harness-enforcement-floor]] を参照してください。
• RULE-02 (MUST): AI のクレジットを記載しないこと — commit message／PR／コード／wiki に Co-Authored-By: Claude…、Generated with Claude Code、🤖、その他 AI へのクレジットや帰属を示す記載を挿入してはいけません。Author と committer はユーザーの身元のみとしてください。テンプレートやツールがクレジットのトレーラーを自動生成した場合は、commit 前に削除してください。
• RULE-03 (MUST): オンデマンドのみ — セッション開始時に自動実行される hook を登録してはいけません（ADR-004）。
• RULE-04 (MUST): 自己完結型 — 上記（pre-flight + distill + inventory）は別のプロジェクトでも実行できるようにしてください。「完全版」の項目は、該当ファイルが存在する場合にのみ適用されます。リポジトリ内のファイルが存在すると決めつけてはいけません。
• RULE-05 (MUST): 件数は常に LIVE で数えてください（ドリフト防止）。
• RULE-06 (MUST): 人が読む HTML では用語を説明すること — レポート／可視化の表示内容（タイトル、ノードの説明、注釈など）は通常のベトナム語で記述してください。専門用語には、初出時に必ず直後の括弧内で簡潔な説明を添えてください（例：「flush（終了前に記録を反映すること）」、「untracked（Git で追跡されていないファイル）」）。閲覧者向けに説明のない専門用語を使ってはいけません。説明のない専門用語を使用できるのは、機械可読ファイルのみです。
• RULE-07 (MUST): 閲覧者向け HTML には明／暗の切り替え機能を必ず付けること（2026-07-06 のフィードバック — 2 回目の指摘、再発厳禁） — 閲覧者向けに生成するすべての HTML ファイル（レポート、ツリー、ダッシュボード、ドキュメント、レンダリングされた提案書など）に、ダーク／ライト切り替えボタンを付けてください。prefers-color-scheme は初期設定にのみ使用し、ユーザーが切り替えボタンを押した場合は html[data-theme] で上書きし、localStorage に保存してください（head に FOUC 対策スクリプトも含めます）。モードを固定してはいけません。必須の形式は、ラベル付きトグルスイッチで、サイドバー／ナビゲーションの最下部に固定することです — 隅にアイコンチップを散らしてはいけません。標準スニペット：skill docs-site-macos §「明／暗テーマの切り替え」。ジェネレーターの参考として _DARK_RULES を確認してください（fdk/tools/build-overstack-docs.py 内。1 つのソースから 2 つのブロックを出力し、ドリフトを防止します）。
• RULE-08 (MUST): モード切り替えには即時の反転ではなく、必ず circle-reveal を使うこと（160926 のフィードバック、タスク T-260916-01） — トグルボタンを押すと、移行先モードの背景色を使った円形オーバーレイがボタンの正確な座標から広がり、ゆっくり始まってから素早く確実にビューポート全体を覆います。その時点で初めて data-theme／localStorage の値を変更し、その後オーバーレイをフェードアウトします。prefers-reduced-motion: reduce を尊重し、（動きなしではなく）150ms 以下のクロスフェードにフォールバックしてください。標準スニペット：skill docs-site-macos §「明／暗テーマの切り替え」項目 4。node skills/docs-site-macos/scripts/verify-theme-motion.mjs <file.html> で検収してください（実際の Playwright を使用します。モデルが自分で保証したと言うだけでは不十分です）。
• RULE-09 (MUST): 閲覧者向け HTML は 13″ 画面に合わせたコンパクトな文字サイズにすること（2026-07-06 のフィードバック） — サイズは大きくせず、小さくしてください。本文は約 13.5px、ナビゲーションは 12px、リスト／表は 12.5px、ラベルは 10〜10.5px を目安にします。文字を大きくすると 13″ 画面では表示できる内容が減り、折り返しが窮屈になるため、見づらくなります。読みやすさは行間とコントラストで確保し、フォントサイズを大きくして解決しないでください。詳細は docs-site-macos § Best Practices を参照してください。
• RULE-10 (MUST): HTML レポート／可視化ではフルパスを表示すること — 閲覧用に生成するすべての HTML ファイル（レポート、ツリー、ダッシュボード、レンダリングされた提案書など）に、そのファイル自身の絶対パスをページ上（フッターまたはタイトルバー）に表示してください。コピー可能な <code> 形式にしてください。閲覧者がファイルの場所を把握し、再度開いたり編集したりできるようにします。ファイル生成後、プレースホルダーではなく実際のパスを設定してください。
• 機能：リポジトリのフレームワークまたは sandbox kit の読み書き、ゲート／テストのローカル実行、認証済み CLI による PR の作成。

失敗境界

• Draft の承認がまだない → pre-flight #4 で blocked、コードを書きません。
• ci-local.py が赤 → push しません（RULE-01）。
• リポジトリ内のファイルが存在しない（別のプロジェクトにいる）→「完全版」の項目を省略し、あると仮定しません（RULE-04）。
• fdk-kit.sh check の15ステップが完了していない → submit しません。

方法

メインワークフロー

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	効果	base remote	修正前に Pull	最新版	—
W02	決定的	harness	ルールを確認する（rule-registry / policy.yaml）	ルール一覧	harness がない → 汎用ルール
W03	決定的	モジュール名	名前を Grep する；共有コードを使う場合 → impact-check の後に safe-change	重複なし	重複あり → 既存モジュールを修正
W04	判断	変更	draft を提案し、承認を待って STOP	承認	未承認 → blocked
W05	効果	承認済み draft	Surgical → verify → 記録（作業の種類に応じて B01–B03）	変更 + テスト成功	失敗 → 修正して繰り返す
W06	決定的	変更対象の path	hook/engine/installer/CI の path に触れる前に、下流マップを確認する	path が overstack_paths.py を通過	bare_path_lint が赤 → 修正
W07	効果	セッション中の問題	turn を終える前に problem-tree を確認・更新する	更新済みツリー	まだない → template から作成

各ステップの詳細（W01–W06、Pre-flight の正規情報源）：

1. 修正前に Pull — base を同期し、古い版で作業しないでください。
2. ルールを確認する — リポジトリに harness がある場合は、rule-registry / policy.yaml を確認します。汎用ルールは常に適用されます：wiki ファイルには ## Origin が必要です；raw/ に記録しないでください；wiki ファイルは正しいサブフォルダー（concepts/entities/sources/draft/…）に配置します；proposal には .md と .html の両方が必要です。
3. 既存モジュールと重複させない — 新しい skill/validator/script/hook を作成する前に、名前を grep して既存のものがないか確認します；共有コードを修正する場合は、先に呼び出し元を特定（impact-check）してから safe-change します。
4. 先に提案する — すべての変更について、計画 draft を作成し、承認を待って STOP します；直接コードを書かないでください。
5. Surgical → verify → 記録 — 必要なものだけに触れます；test/drift-test を実行し、registry/log を更新します。 Commit する場合は、明示的な pathspec を stage し、git add -A/./commit -a は使わないでください：複数のセッションが同じツリーを共有しているため、一括 stage すると別のセッションの未完了作業まで含まれてしまいます（framework リポジトリでは rule P1 no-bulk-stage がこれをブロックします）。
6. クライアントのレイアウト ≠ リポジトリのレイアウト — hook/engine/installer/CI の path に触れる前に、以下の「下流マップ」を確認します；llmwiki/ harness/ の裸のパスが正しいのはこのリポジトリ内だけです。

分岐

ID	Kind	Guard	行動	Skip / failure	Rejoin
B01	条件付き必須	skill の蒸留／作成が作業内容	「skill を蒸留／作成する」の項目に従う	—	W06
B02	条件付き必須	別のプロジェクトで開発中で、fdk/tools がない	kit：pull → kit 内で蒸留 → check → PR を submit	overstack リポジトリ内にいる → pull の手順を省略	W07
B03	任意の機能	framework リポジトリ内にいる（完全版ファイルがある）	完全版を読む；SKILL.md の修正後に → sync-skill.sh	ファイルがない → 省略	W06
B04	条件付き必須	push/PR を ship する直前	ci-local.py の後に /fdk-uat（RULE-01）	失敗 → push しない	W07

検証と停止

決定的なチェック：test/drift-test、skill 用の swh-lint.py、ci-local.py、fdk-kit.sh check、HTML 用の verify-theme-motion。人による承認が必要：W04 で draft を提案します。problem-tree の確認（W07）が済んだ後にのみ、turn を終了します。

例

• 成功例： framework リポジトリ内で「/fdk medic 用の新しい probe を追加」と依頼された場合 → pull、medic.py を grep（単独の tool を新しく作らない）、承認待ちの draft を作成 → Surgical に修正 + test → push 前に ci-local.py が成功 → problem-tree に status: solved、scope: ["harness"] のノードを追加すると、「solved 1/3 trụ」がオレンジ色で表示されます。
• 境界／失敗例： 別のプロジェクトにいて、蒸留したばかりの skill を overstack に push しようとして python3 fdk/tools/new-skill.py を実行する → ファイルが存在しない（ADR-004）→ B02 に切り替える：kit を .overstack-kit/ に pull し、kit 内で蒸留し、fdk-kit.sh check を実行してから submit します。

参照 — downstream マップ — 表示されているものは、クライアントマシンで実行されるものではありません

フレームワークリポジトリ（現在開いているもの）	curl bootstrap.sh の後のクライアントマシン	備考
llmwiki/	.llmwiki/	wiki · raw · html · .harness-stamp
harness/	.harness/	poc-vendor-neutral/ + foundation.yaml + metrics/ のみ。scripts/ validators/ はありません
harness/scripts · harness/validators · fdk/tools · llmwiki/.claude/hooks	~/.claude/harness/（グローバル）	共通エンジン。フックは ~/.claude/settings.json から起動します
fdk/wiki/	なし	framework_only
skills/*/SKILL.md	~/.claude/skills/	npx 経由で、プロジェクトリポジトリ内にはありません
なし	CAPABILITIES.md · .overstack.yaml · ルートの .claude/settings.json	downstream にのみ存在

機械可読な情報源：harness/downstream-contract.yaml → layout_map。ルール：downstream に触れるパスは、harness/scripts/overstack_paths.py（エンジン）または hooklib.overstack_dir/harness_dir/stamp_path（フック）を経由します。ハードコードされたパスがあると bare_path_lint がエラーになります。実際の挙動テスト：bash harness/tests/dot-layout-runtime-test.sh .（dot を使った fixture、分離された HOME）。注意：rg／Grep はドットで始まるディレクトリを無視します。downstream プロジェクトを調べるときは --hidden を使ってください。

スキルの蒸留・作成（任意のプロジェクトで使用）

• solid-what-how/1 (SWH) に準拠したネイティブスキル：frontmatter に name + description + metadata.design-standard: "solid-what-how/1" を記述し、続けて ## WHAT（目的／トリガー／対象外・メンタルモデル・入出力の契約・ID 付きルール・失敗時の境界）と ## HOW（exit／next を含むメインワークフロー W01… の表・分岐、または「副分岐なし」と明記・検証／停止・成功例と境界の例）を記述します。完全なテンプレートは solid-what-how コンセプト（フレームワークリポジトリ内）を参照するか、new-skill.py で生成してください。
• description はトリガーを十分に網羅する必要があります。いつ呼び出すか（キーワードや状況）を明確に記述してください。これはルーターがスキルを選ぶ際に使います。
• カタログがある場合は、作成前にサンプルを検索してください（Reuse Layer SWH v1.1）：python3 fdk/tools/skill-reuse.py search --desc "<việc>" → 契約に合致する場合は new-skill.py <tên> --from <asset_id> --params p.json を実行します（型付きテンプレートをレンダリングし、sha256 を固定します）。合致するものがなければ、--reason を付けて scratch から作成します。スキルを作成するたびに reuse_decision が残ります。再利用しても、どのゲートも免除されません。
• ツールがある場合は形式を確認します：python3 fdk/tools/swh-lint.py --skills <tên> --ci（構造のみ。挙動はサンプル文で引き続き試す必要があります）。upstream から取得したスキルは skills/external/ に置き、SWH に合わせて書き直さないでください。
• 自己完結型を保ってください。1 つのリポジトリにしかないファイルを参照しないでください。必要な場合は「ファイル X が存在する場合は…」と記述してください。
• 作成後、サンプル文を 1～2 個使って、スキルが正しくトリガーされるか試してください。

参照 — インベントリ — 記憶している数を信用せず、LIVE を数えてください（パスはリポジトリのレイアウトによって異なります）

ls -d skills/*/ 2>/dev/null | wc -l                                   # số skill
ls harness/validators/*.py 2>/dev/null | wc -l                        # số validator
grep -cE 'id: R' harness/poc-vendor-neutral/policy.yaml 2>/dev/null   # số rule

リファレンス — Problem-tree — フレームワーク全体の共通問題台帳（/fdk 専用ではありません）

llmwiki/html/fdk-problem-tree.html は、フレームワークに関するあらゆる問題の唯一の台帳です。フレームワーク関連の作業（propose、harness-update、orca-workflow など）に触れるスキルやセッションが問題を発見したり解決したりした場合は、必ずこの台帳を更新してください。/fdk は管理役です。/fdk が呼び出されるたびに、ターンを終了する前に必ずツリーを確認して更新してください（まだなければテンプレートから作成します。フレームワークのリポジトリ内にいなくても、プロジェクトに llmwiki/ がある場合は、同じ名前のプロジェクトローカルパスを使用してください）。

• 形式：/docs-site-macos スタイル（liquid-glass）の単一ファイル HTML。内容は問題ツリーです。各ノードはセッションで遭遇した問題を表し、ノードは SVG コネクターで親→子の関係としてつながります。コネクターは JS が自動描画し（getBoundingClientRect で測定し、サイズ変更時に再描画）、座標をハードコードしません。
• データとマークアップの分離：すべてのノードは <script type="application/json" id="tree-data"> ブロック内に置きます。更新のたびに変更するのは JSON の追加・編集だけで、マークアップには触れません。各ノード：{id, parent, title, desc, status: solved|partial|open, scope: "full" | ["harness"|"skills"|"llmwiki"...], date, solvedBy?, session?}。
• Scope は 3 つの柱に基づく固定値です："full" は 3 つの柱（harness + skills + llmwiki）すべてを完全に解決したことを意味します。それ以外の場合は、対応した柱のリストを指定します（例：["skills"] = スキル層でのみ解決）。status: solved でも scope が full でない場合、ツリーには「solved x/3 trụ」と明示し、完全に解決したと誤解されないようにしてください。
• 履歴は追記のみ：古いノードは削除しません。問題が解決したら status を変更し、solvedBy（解決に使ったスキル／ルール／コミット）を記録します。
• 色はステータスではなく対応範囲に応じて決めます：緑にするのは 3/3 の柱すべてを完全に解決した場合のみです。深刻度の高い順に、0/3（何も対応していない — 最も深刻）= 赤 #ef4444 → 1/3 = オレンジ #f97316 → 2/3 = 黄 #eab308 → 3/3 = 緑 #22c55e。バッジには x/3 を併記します。一部だけ解決したものを緑にすることは決してありません。

overstack remote への適用 — 別のプロジェクトから開発している場合

別のプロジェクトで作業中にスキルを抽出して overstack に追加したい場合、fdk-gate と fdk/tools はそのプロジェクトにはありません（意図的な設計です — ADR-004）。そのため、kit をサンドボックスに取得して PR で提出してください。手作業で適当に変更しないでください。

1. kit を取得（初回 — リモートから直接実行でき、ローカルファイルは不要です）：

   bash <(curl -fsSL https://raw.githubusercontent.com/Rheinmir/setup/orca/fdk/tools/fdk-kit.sh) pull
   

   → overstack を .overstack-kit/ に clone します（自動で .gitignore に追加され、プロジェクトには触れません）。
2. kit 内でスキルを抽出：cd .overstack-kit && python3 fdk/tools/new-skill.py <tên> → SKILL.md を記述 → 登録（mirror + LOOP_MAP + AGENT/CLAUDE 表 + CAPABILITIES — pre-flight #3 + checklist）。
3. 確認：bash .overstack-kit/fdk/tools/fdk-kit.sh check — fdk-gate の 15 ステップをすべて通過して初めて有効です。
4. 提出（PR を自動で作成）：bash .overstack-kit/fdk/tools/fdk-kit.sh submit skill/<tên> "<mô tả>" → gate が緑になったら branch を push → gh pr create で orca に PR を作成します。

overstack リポジトリ内で作業している場合は、pull の手順を省略し、リポジトリ上で fdk-kit check / submit を直接実行してください。

フレームワークのリポジトリ（Rheinmir/setup）内にいる場合 — 完全版

以下のファイルはフレームワークのリポジトリにのみ存在し、他のプロジェクトには配布されません（意図的な設計です — ADR-004）。ファイルがある場合は、詳細版を確認してください。

• fdk/wiki/concepts/fdk.md — 完全版 front-door（pre-flight + 種類別モジュールマップ）。
• fdk/docs/CONTRIBUTING.md — rule harness（content-check / hook-event / process-gate）の追加・編集手順書（次の番号は R13）。
• fdk/README.md + fdk/tools/ — kit フォルダー（例：build-cheatsheet.py）。
• SKILL.md の編集後は → bash fdk/tools/sync-skill.sh <tên> — canonical から llmwiki の mirror と ~/.claude のインストール済みコピーへ、1 コマンドで同期し、parity を自動検証します。コピーを手作業で個別に行わないでください（ソースの drift の原因になります — eval 020726）。
• llmwiki/html/*-fdk-docs.html — HTML で読める版。