loom-skill-enhancement

/loom-skill-enhancement

公開されている Loom Skill Orchestrator（so）のワークフローを通じて、改善対象のスキルをアップグレードまたは作成します。改善対象のスキルを納品することがビジネス上の成果であり、ランタイムチェックは補足的な証拠です。

必読資料

• 実行契約：ランタイムの取得、ファイルとペイロードのルール、ワークフローの識別、コンパイル／実行／再開、バージョンセマンティクスのプローブ、ランタイムモード。

• ランタイムセマンティクスの移行：検証済みの 0.3.282 エミッターマトリクス、プロデューサーのルール、gov4 の到達可能性、移行手順、再開時の形式、Windows のツールに関する制約。 現在の段階に必要な資料のみを参照してください：

• 実行契約：ランタイムの取得、ファイルとペイロードのルール、ワークフローの識別、コンパイル／実行／再開、バージョンセマンティクスのプローブ、ランタイムモード。

• レビューと証拠に関する契約：ガイドアセット、ワークフロー設計、一括レビュー／修正、必須の成果物、監査用の納品物、完了の証拠。

• 平易な言葉でのフィードバック：ユーザー向けの必須表現、用語の対応関係、例。

• SO スキルリファレンス：特定のランタイムに対応するガイド／スキーマ／デモのリファレンスパックと、パッケージの動作。

• Mermaid アーティファクトの納品：検証済みの Mermaid および HTML 出力の取り扱い。

• 用語の共通基準：ワークフロー用語。

ランタイムバインディング

公開されている AO および SO のランタイムでは、自己完結型の製品名＋RID パッケージのみを使用します。ホストエージェントは現在の OS、アーキテクチャ、Linux の libc を判定し、サポート対象の RID を 1 つだけ選択します。リゾルバー実行ファイル、起動記述子、インストール済みの dotnet ホストは必要ありません。

MCP は任意であり、パッケージの起動、ガイドの取得、公式 CLI の実行を妨げることはありません。最新のガイドを取得する手順より前に、MCP を登録または調査しないでください。後続のワークフロー手順では、利用可能な場合に MCP を使用できます。そのバインディング元は、記述子ファイルではなく、実行中の自己完結型 apphost の識別情報です。ディスパッチ後に発生した MCP アプリケーション／ツールのエラーは失敗として扱い、別のトランスポートで再試行して隠蔽してはいけません。

• 現在公開されている SO パッケージのランタイムバージョン：0.4.0。

• このブロックは、SO パッケージのバージョンが変更されるたびに公開ワークフローによって更新されるため、スキルの契約は最新の公開済み安定版パッケージセットに沿った状態に保たれます。

• assets/so-workflow/so-package-lock.json は、正確なバージョンの根拠であり、チェックイン済みのロック参照先です。そのバージョンからチャネルを導出してください。ユーザーにチャネルを選ばせてはいけません。

• バインドされたバージョンと検出された RID に対して、Techne.Loom.SkillOrchestrator.Runtime.<rid> のみを使用してください。DLL/FDD モードを調査または選択せず、マシンの RID や apphost のパスをスキルのチェックイン済み状態に保存してはいけません。

• リリース版およびベータ版のパッケージインデックスは、それぞれ reference/packages.released.md と reference/packages.beta.md です。

• 移行スクリプトの手順書：パスセーフな移行エントリポイント、生成元の境界、ドライランの動作、繰り返し実行可能なフィクスチャチェックについて説明しています。

すべての機能強化パスで、次のブートストラップを実行してください。

1. 外部ワークフローの新しいコピーを作成し、caseId／runId の系譜を維持します。
2. ロックファイルから正確なパッケージバージョンを読み取り、チャネルを導出して、ホストの RID を検出します。
3. 標準の NuGet キャッシュにある、検証済みの正確なパッケージのみを再利用します。それ以外の場合は、正確な NuGet パッケージを取得し、その SHA-512 を正確な登録メタデータと照合します。同じバージョンの GitHub フォールバックには .sha512 サイドカーが必要です。
4. 安全に apphost とドキュメントを展開する前に、パッケージ ID、バージョン、nuspec、RID、マニフェスト、エントリポイント、アーカイブサイズ、パスを検証します。固定のチェックイン済みブートストラップスクリプト、Loom 専用のランタイムキャッシュ、記述子ファイルを追加してはいけません。ホストで必須の検証を実行できない場合は、具体的な機能エラーを返して停止します。
5. Windows では so.exe --guide を、Unix では so --guide を直接実行します。JSON のバージョン、絶対パスであるドキュメントとガイドの各パス、パスの包含関係、読み取り可能性を検証します。この最新のガイドを使って、同じ apphost 上で計画、作成、検証、コンパイル、実行、または再開に進みます。

すべての機能強化パスで、ロックファイルに記載された正確な公開済み SO パッケージの apphost が、後続の作業前に実行可能であることを確認してください。

ワークフローの手順

1. 対象が新規か、すでに Loom Skill Orchestrator の管理下にあるかを分類し、強化するスキルの成果物を確定します。
2. 強化するスキルの成果物を編集する前に、プランモードに入ります。範囲を限定した参照資料一式と実行ごとの計画を <execution-output-root>/plan/ に作成します。
3. 入力、出力、ノード、分岐、ループ、所有権の境界、ゲート、具体的な証拠の生成元を分析します。すべてのコンテキストパスを、所有するコントラクトの context_fields カタログと照合し、型付き読み取りと出力プロジェクションをその JSON 型に一致させます。
4. assets/agents/loom-skill-enhancement-workflow-designer.agent.md を通じてワークフロー JSON を生成または改訂します。JSON を正式な情報源とし、Mermaid は表現用とします。 デザイナーへのディスパッチコンテキストに、英語版および中国語版の実行モデル、JSON コントラクト、SO の動作、SO ツール、CLI の使用方法の各ページへの完全なクリック可能リンクを含めます。
5. 独立したチェックでは、範囲を限定した共有コンテキストを構築し、完全な外部 whenAllPass バッチを実行して、1 回だけ集約し、1 回だけ修復してから、レビューコントラクトの説明に従って再検証します。
6. 正確なランタイムでコンパイルを実行します。コンパイルは構造上の証拠としてのみ扱います。
7. 公開 run を通じて、正確な外部ワークフローのコピーを実行し、最終的な Done に至るまで、必要なすべての resume を実行します。コンパイル、ブロックされたペイロード、ローカルオーケストレーション、または別のワークフローコピーをもって完了と主張してはいけません。
8. 対象成果物の変更、イベント／監査レコード、出力ファミリーの値、Mermaid／HTML のパス、完了マニフェストを検証します。

セマンティックドリフトゲート

ランタイムのバージョン変更は、コントラクトの変更であると同時に、実行セマンティクスの変更でもあります。

• 対象を編集したりバッチを実行したりする前に、選択した正確なランタイム上で、最小限の 3 ノードフィクスチャの継承版と置換版を実行します。置換版は、期待される空でないコンテキスト値を伴って、最終的な Done に到達する必要があります。
• リリース済みの 0.3.282 のマトリックスはエミッター固有です。通常の ToolCall／noop 上のリテラル updates は無効です。StateUpdate／MemoryWrite は宣言された更新を書き込みます。実際の echo／write-file の結果、および実証済みの外部 resume プロジェクションでは、プローブ後に $result を使用できます。宣言された outputPath や、同一遷移での $context バインディングを自己証明に使用してはいけません。
• プロデューサーより前の分岐／サイクルのコンシューマーには、gov4 プローブを実行します。最初のパスでは DFS の後退辺を無視し、片方の分岐にしかプロデューサーがない結合を拒否し、管理下と管理外のデータフロールールを分けて扱います。不明な動作は推測せずに記録します。
• 対象パターンが繰り返される場合は、移行前に冪等なドライスキャンを実行します。曖昧さのない ToolCall／noop のリテラル書き込み形式のみを StateUpdate／state.update に自動変換します。曖昧なバインディングや不明なエミッターは報告し、架空の $context プロデューサーを作り出してはいけません。
• 正式な resume を行う前に毎回、ブロックされた遷移の requiredInputs を確認します。必須の兄弟フィールドはペイロードのトップレベルに置き、宣言された resumeOutputKey のみをペイロードからプロジェクションします。
• 最終検証では、空でない runtime_semantic_probe_evidence、batch_migration_evidence、decision_evidence_manifest を返す必要があります。

フィクスチャ、ペイロード、マニフェスト、証拠に関する詳細な要件は、実行コントラクトおよびランタイムのセマンティック移行リファレンスに記載されています。

名前付きエージェントの解決

このスキルで指定されている各 .agent.md は、そのロールの正確な動作契約です。ホストへの登録はディスパッチ手段にすぎず、機能の利用可否を制限するものではありません。

• ファイルのステムではなく、frontmatter に記載された正確な name でロールを特定してください。このスキルの assets/agents/ フォルダーからファイルを解決します。単独でインストールされている場合は、~/.agents/skills/<skill-folder>/ や ~/.claude/skills/<skill-folder>/ など、アクティブなスキルルート以下の同じ相対パスから解決してください。まず現在のリポジトリ／ワークスペースのコピーを使用し、次に対応するグローバルインストール済みスキルのコピーを使用してください。
• ディスパッチ前に事前確認してください。その正確な名前を、ホストがサブエージェント呼び出し用に公開しているエージェント一覧と照合します。スキル内の assets/agents/ ファイルは通常登録されていません（VS Code では登録されません）。そのため、名前が見つからない場合は、直接呼び出すと失敗すると予想される呼び出しを行わず、以下のドライバールートへ進んでください。
• 名前が登録されている場合は、直接呼び出してください。次のいずれかの結果になった場合は、未登録とみなし、同じ手順内でドライバールートに切り替えてください。agent not found、エージェントが不明、またはエージェント名が無効という結果、agentName（または同等の）パラメーターがないサブエージェントツール、宣言されたロールを確認せず、デフォルトエージェントが応答した呼び出し。
• ドライバールート：編集、コマンドの実行、検証ができる、登録済みの汎用エージェントを呼び出してください（VS Code では、agentName を省略したデフォルトエージェントを使用します）。契約上、設計、編集、または検証が必要な場合は、Explore のような読み取り専用エージェントを使用しないでください。また、名前が似ている別のロールで代用しないでください。契約は次のいずれかの方法で渡してください。
  • インライン：ファイルの全文を含めます。
  • パスのみ：ハッシュを含めず、解決したファイルパスを伝え、作業を始める前にドライバー自身がファイル全体を読むよう指示します。ドライバーは、最初に読み取った frontmatter の name をそのまま返し、ファイルを読めない場合は作業を中止しなければなりません。
• 名前を指定したエージェントの直接呼び出しも含め、すべてのサブエージェント呼び出しには、ファイルに宣言された正確な name と、同じ .agent.md へのクリック可能な Markdown リンクに加え、必要なすべての入力と参照コンテキストを含めてください。大きな入力はパスで渡してください。名前だけ、または契約の代わりに要約を渡すのでは不十分です。
• エージェントファイルと入力が大きい場合は、パスのみで渡す方法を優先してください。リクエストサイズエラー、HTTP 408、またはタイムアウトは転送上の失敗であり、エージェントが未登録という意味ではありません。パスのみの方法で入力もパスで渡して一度再試行し、それでも失敗した場合は転送上の障害を報告してください。
• ドライバーへのフォールバックにユーザーの承認は不要です。これは通常の運用です。専用の名前が登録されていないという理由だけで、ユーザーに確認するために処理を中断しないでください。
• 正確なファイルが存在しない、または特定できない場合、あるいは読み取り専用ではない、能力を備えたドライバーが存在しない場合に限り、処理を中止してください。その場合は失敗の証拠を保持し、具体的な障害を報告して、後続の確認には進まないでください。サブエージェントのドライバーを使わず、メインの会話でロールの作業を直接行うには、ユーザーの明示的な承認が必要です。
• すべてのディスパッチについて、frontmatter に記載された正確な名前、.agent.md へのリンク、ルート（direct または driver-fallback）、受け渡し方法（inline または path-only）、フォールバックのきっかけとなった証拠、ドライバーが返した名前を記録してください。

中核となるガバナンス

• ワークフローが所有するスキーマと制御メタデータは英語とし、ユーザー／ビジネスのペイロードとローカライズされた表示には、元の言語またはリクエストの言語を維持します。
• SO および拡張対象のすべてのスキルについて、ユーザー向けの進捗、ブロック中、エラー、完了のメッセージでは、現在のやり取りの言語で平易な言葉を使用します。説明に FPx、xxx_preflight_xxx、ノード ID、ゲート ID、内部フィールド名などのワークフロー専用ラベルを使用してはいけません。正確な識別子は技術的な詳細または証拠にのみ記載します。拡張対象の各スキルでは、実行後の更新に、ローカライズされた実行信頼度と推定全体進捗率の見出しをこの順で含め、それぞれに短い理由を1つ添えることも必須とします。信頼度は、リクエストされた作業が正常に完了する可能性を推定します。推定全体進捗率は、リクエスト全体のおおよその完了度を示します。どちらも検証済みの証拠に基づいて算出します。どちらの割合も、必須の成果物、証拠ゲート、最終的な Done の代わりにはなりません。拡張対象のスキルが AO/SO ワークフローの実行を報告する場合は、固定形式の Mermaid、HTML、Analysis、Dataflow のレポートをこの順で必ず記載するよう求めます。クライアントが対応している場合、各タイトルはネイティブな Markdown ファイルリンクにします。生の HTML <a> は使用しません。リンク先には、/ 形式に正規化された、検証済みファイルの完全な絶対パスを指定します。パスにスペースが含まれる場合は、スペースをそのまま保持したうえでリンク先を山括弧で囲みます。パスを引用符で囲んだり、スペースを %20 にエンコードしたりしてはいけません。リンクの直後には、スペースをそのまま保持し、引用符やパーセントエンコードを含まない、同一の絶対パスだけを記載した text フェンスを続けます。既存のすべてのラベル、フィールド、順序、レポート周辺の形式を維持します。ファイルが利用できない場合は、推測せず、配信失敗のガイダンスに従います。
• CLI のすべてのファイル入力には、内容が完結したパスのみのファイルを使用します。変更可能な計画、ランタイムコピー、イベント、監査出力、判断の証拠は、スキルバンドルの外部に保管します。
• 拡張実行の plan/skill-plan.md は、<execution-output-root> の下にある、一時的かつ実行スコープ限定のファイルとして扱います。その内容を拡張対象のスキルの assets/、パッケージ、リリース、成果物にコピー、移動、移行、または含めてはいけません。ランタイムが所有するコンテキストと完了証拠には、その内容ではなく、パスとハッシュのみを保持できます。
• AskUser は、ユーザーが所有する判断または値のみを要求します。ランタイムが所有する事実と成果物のパスには、ランタイム所有の継続処理を使用します。
• 次の各ステップは、同一の外部コピー上で境界チェックに合格する必要があります。所有者の境界をまたぐステップでは、明示的な承認または構造化された継続処理も必要です。
• 実行中のワークフローコピーへの直接編集は、ブロック状態でのみ許可され、明示的に承認された最小限の緊急回避策に限ります。その直後に通常の SO のコンパイル／実行／再開を行います。
• すべてのサブエージェント呼び出しには、名前付きエージェントの解決 に記載された、正確なファイルへのディスパッチと全内容へのフォールバック手順を適用します。正確なエージェント名を明記し、適用対象の .agent.md への Markdown リンクを含めます。拡張対象の各スキルには、このルールを SKILL.md に記載し、すべての呼び出しに適用するよう求めます。類似した役割で代用してはいけません。
• 前提、修正、判断、プローブ、events.jsonl、監査参照は <execution-output-root>/evidence/ に記録します。会話のテキストは実行証拠ではありません。

安定アセット

• assets/so-workflow/so-template.json
• assets/so-workflow/so-package-lock.json
• assets/so-workflow/node-to-file-map.md
• assets/so-workflow/governance-notes.md
• assets/so-workflow/reference/document-copy-manifest.json
• ワークフローデザイナーのサブエージェント：assets/agents/loom-skill-enhancement-workflow-designer.agent.md
• ガイドの取得後に利用できる任意の MCP サポート：assets/agents/loom-skill-enhancement-mcp-startup.agent.md
• 再利用可能な織り込みとレビュー用サブエージェント：
  • assets/agents/loom-skill-enhancement-skill-markdown-gap-review.agent.md
  • assets/agents/loom-skill-enhancement-package-lock-gap-review.agent.md
  • assets/agents/loom-skill-enhancement-workflow-governance-gap-review.agent.md
  • 再強化戦略のレビュアー：assets/agents/loom-skill-enhancement-reenhancement-conflict-judgment.agent.md
  • assets/agents/loom-skill-enhancement-weave-out-subagent-fit-review.agent.md
  • assets/agents/loom-skill-enhancement-review-fix-loop.agent.md
  • assets/agents/loom-skill-enhancement-review-findings-aggregator.agent.md
  • assets/agents/loom-skill-enhancement-scope-input-output-analysis.agent.md
  • assets/agents/loom-skill-enhancement-route-gate-analysis.agent.md
  • assets/agents/loom-skill-enhancement-evidence-node-map-analysis.agent.md

完了

完了には、以下のすべてが必要です。

• 強化対象として依頼されたスキルのファイルが作成または変更されていること。
• ロックされた RID の正確なパッケージ ID／ハッシュ／アーカイブの確認、安全な展開、アプリホストの直接起動、および新規に取得した読み取り可能なガイドの証拠が検証済みであること。MCP は任意であり、ブートストラップの必須条件ではありません。
• 該当する場合、正確なランタイムでのセマンティックプローブと一括移行の証拠が検証済みであること。
• ワークフローのコピー系譜が、公開された run／resume を経由して最終的に Done に到達していること。
• レビュー、修復、修正後の検証、境界チェック、イベントログ、監査アーティファクト、永続的な判断の証拠が読み取り可能であること。
• ランタイム所有の完了マニフェストが、証明がない項目を自己認証するのではなく、既存の証拠を参照していること。

パッケージロックのメタデータは、チェックイン済みのロック参照先、解決済みの正確なパッケージバージョン／チャネルの証拠、およびチェックイン済みのロックアセットへのランタイム所有の完了マニフェスト参照に分かれています。チェックイン済みのスキルマークダウンのガバナンス結果にも、同様に、そのチェックイン済みソースアセットへのランタイム所有の完了マニフェスト参照が含まれます。

完全な出力チェックリストについてはレビューと証拠の契約を、ユーザー向けの完了または失敗メッセージについては平易な言葉での契約を参照してください。