artifact-integrator

Artifact Integrator

目的

新たに作成または変更されたアーティファクトを分析して統合上の不足を特定し、エコシステムへの完全な統合を確実にするためのフォローアップタスクを提案します。

使用するタイミング

• アーティファクト作成スキルの完了後
• Router Step 0.5で未処理の統合キューエントリが検出されたとき
• 統合の健全性を手動で確認するとき
• アーティファクトの完全性をレビューするとき

プロトコル

Step 1: 統合キューを読み込む

.claude/context/runtime/integration-queue.jsonlを読み込みます "processed": falseのエントリを絞り込みます 未処理のエントリがない場合は、直接分析用のartifactId引数が指定されているか確認します。

Step 2: 各アーティファクトを分析する

未処理の各エントリ（または直接指定されたアーティファクト）について：

1. アーティファクトグラフを読み込みます：require('.claude/lib/workflow/artifact-graph.cjs')
2. 影響分析ツールを読み込みます：require('.claude/lib/workflow/integration-impact.cjs')
3. analyzeImpact({ artifactId, changeType, graphPath })を呼び出します
4. missingIntegrationsとproposedTasksを確認します

Step 3: 統合計画を作成する

統合の不足がある各アーティファクトについて：

必須（P1）— すぐにタスクを作成します：

• カタログエントリがない → TaskCreate：「{name}を{catalog}に追加」
• エージェントの割り当てがない → TaskCreate：「{name}を関連するエージェントに割り当てる」
• ルーティングエントリがない → TaskCreate：「{name}のルーティングを更新」
• フックの登録がない → TaskCreate：「{name}をsettings.jsonに登録」

推奨（P2）— 優先度を下げてタスクを作成します：

• ドキュメントがない → TaskCreate：「{name}を{doc}に記載」
• 適用を強制するフックがない → TaskCreate：「{name}の適用を強制するフックを作成」
• テストがない → TaskCreate：「{name}のテストを作成」

あると望ましいもの — 記録しますが、タスクは作成しません：

• テンプレートや任意のドキュメントがない

Step 3.1: コンパニオンマトリックス分析（連携した作成者エコシステム）

分析対象の各アーティファクトについて、コンパニオンマトリックスの検証を実行し、エコシステム内で不足しているコンパニオンを特定します：

分析：

1. .claude/lib/creators/companion-check.cjsのcompanion-check.cjsを使用します
2. checkCompanions(artifactType, artifactName)を呼び出してコンパニオンマトリックスを取得します
3. コンパニオンチェックリストを次のカテゴリに分類します：
   • 必須のコンパニオン（アーティファクトの完全性に必須）
   • 推奨されるコンパニオン（ベストプラクティスのために推奨）
   • 任意のコンパニオン（完全な統合のためにあると望ましい）

タスクの作成：

• 必須のコンパニオンが不足している場合 → P1タスクを作成：「{artifact-name}用の{companion-type}:{companion-name}を作成」
• 推奨されるコンパニオンが不足している場合 → P2タスクを作成：「{artifact-name}用の{companion-type}:{companion-name}の作成を検討」
• 任意のコンパニオンが不足している場合 → レポートに記録しますが、タスクは作成しません

安全制限（SEC-ICE-002）：

• アーティファクトあたりの自動生成タスクの最大数：3（連鎖的な作成を防止）
• 1回の統合実行あたりのコンパニオンタスクの合計最大数：10（一括作成の急増を防止）
• 制限を超えた場合、残りのコンパニオンはレポートに警告を記載して手動レビュー用にキューに追加します

例：

### Companion Matrix Analysis: skill:rate-limiter

**Required Companions (MISSING):**

- [ ] hook:rate-limit-validator (validates rate limit headers) — **TASK CREATED** (P1)
- [ ] schema:rate-limit-config (validates configuration) — **TASK CREATED** (P1)

**Recommended Companions (MISSING):**

- [ ] template:rate-limit-pattern (template for rate limiting implementations) — **TASK CREATED** (P2)

**Optional Companions (MISSING):**

- [ ] workflow:rate-limit-setup (onboarding workflow) — noted for future consideration

**Safety Check:**

- Auto-spawned tasks: 3 (within limit of 3 per artifact)
- Total companion tasks this run: 8 (within limit of 10)

Companion Checkとの統合：

• コンパニオンマトリックスのデータはecosystem-impact-graph.jsonから取得されます
• 作成者スキルがStep 0.5で呼び出すものと同じcompanion-check.cjsライブラリを使用します
• 作成者が作成時にコンパニオンを確認し、インテグレーターが作成後にコンパニオンを検証することで、双方向の整合性を確保します

ステップ 3.5：逆伝播の処理（ADR-100 フェーズ 3.1～3.3）

code-reviewer または architect からの逆伝播シグナルを処理する場合：

検出：

• changeType: "backward-propagation" を含むキューエントリ
• BACKWARD_PROPAGATION セクションを含むレビュー指摘事項
• システム全体にわたる重複を示すパターンレポート

検証：

1. パターンが存在することを確認する（記載されたファイル／コンポーネントを確認）

   • 影響を受ける各ファイルを読み、パターンの重複を確認する
   • 実際のインスタンス数を数える（申告された数だけを信頼しない）
   • パターンの類似性を検証する（表面的に似ているだけではないことを確認する）

2. 新しいアーティファクトが妥当か評価する

   • しきい値：同一またはほぼ同一のパターンが 3 件以上
   • 影響：アーティファクトによって重複する LOC を 50％以上削減できるか
   • 保守性：一元化によって保守性が向上するか

3. 妥当であれば、作成用にキューに登録する：

   • changeType: "backward-propagation" を指定して integration-queue.jsonl にエントリを書き込む
   • proposedArtifact フィールドに、タイプと推奨名を設定する
   • 影響に基づいて優先度を設定する：
     • P1（3～5 件、セキュリティ／重要なパターン）
     • P2（6 件以上、品質／一貫性に関するパターン）
   • 検証の根拠（ファイルパス、LOC 数、パターンの抜粋）を含める

4. 統合分析レポートに報告する：

## Backward Propagation Analysis

**Pattern**: <validated pattern description>
**Instances Found**: <actual count> (claimed: <original count>)
**Proposed Artifact**: <type>:<name>
**Justification**: <why centralization is beneficial>
**Priority**: P1 | P2
**Next Steps**: Queued for creator skill invocation

キューエントリの例：

{
  "artifactId": "hook:jwt-validation",
  "changeType": "backward-propagation",
  "timestamp": "2026-02-08T10:30:00Z",
  "processed": false,
  "source": "code-reviewer",
  "pattern": "Manual JWT validation logic duplicated in 4 route handlers",
  "affectedFiles": [
    "routes/auth.ts",
    "routes/api.ts",
    "routes/admin.ts",
    "routes/user.ts"
  ],
  "validatedInstances": 4,
  "estimatedLOCReduction": 120,
  "priority": "P1",
  "proposedArtifact": {
    "type": "hook",
    "name": "jwt-validation",
    "rationale": "Centralize JWT validation for consistent security enforcement"
  }
}

却下基準：

• パターンが 3 ファイル未満で見つかった（重複が不十分）
• パターンのバリエーションが大きく異なる（実際には重複していない）
• 既存のアーティファクトがすでにこのパターンに対応している（孤立している／十分に活用されていない）
• LOC の削減が 30 行未満（効果が不十分）

Creator Skills との統合：

• 検証済みの逆伝播エントリを受けて、creator skill の呼び出しがトリガーされる
• creator skill（skill-creator、hook-creator、template-creator、schema-creator）がキューエントリを処理する
• 作成後、artifact-integrator が新たに作成されたアーティファクトを処理し、標準的な統合を行う

ステップ 4：グラフを更新する

統合タスクの作成後：

• 新たに発見された関係のエッジを追加する
• 現在の状態に基づいてノードの integrationStatus を更新する
• グラフを保存する

ステップ 5：キューエントリを処理済みにする

処理した各エントリについて、JSONL を更新し、processed: true にする

ステップ 6：レポートする

概要を出力します：

## Integration Analysis Report

Processed: {count} artifacts
Tasks created: {count}
Must-have gaps: {count}
Should-have gaps: {count}

### Details
[artifact-by-artifact breakdown]

引数

• artifactId（任意）— キューの代わりに特定のアーティファクトを分析します
• mode（任意）— 'queue'（デフォルト）| 'single' | 'health-check'

アーティファクトタイプ別の統合ルール

タイプ	必須項目	推奨項目
スキル	カタログ + エージェントの割り当て	Hook、ワークフロー参照
エージェント	レジストリ + ルーティング用キーワード	スキル、モデル設定
Hook	settings.json への登録	ドキュメント項目
ワークフロー	レジストリ + エージェントのマッピング	ドキュメント項目
テンプレート	カタログ項目	利用側の参照
スキーマ	カタログ項目	利用側の接続

使用例

Skill({ skill: 'artifact-integrator' });
// Processes queue, creates tasks, updates graph

Skill({ skill: 'artifact-integrator', args: 'skill:rate-limiter' });
// Analyzes specific artifact

実装リファレンス

コアライブラリ：

• .claude/lib/workflow/integration-impact.cjs - 影響分析とタスク生成
• .claude/lib/workflow/artifact-graph.cjs - グラフの CRUD 操作

データソース：

• .claude/context/runtime/integration-queue.jsonl - 統合が必要なアーティファクトのキュー
• .claude/context/data/artifact-graph.json - アーティファクトの関係グラフ

統合キューの形式：

{"artifactId":"skill:rate-limiter","changeType":"created","timestamp":"2026-02-07T10:30:00Z","processed":false}
{"artifactId":"agent:security-architect","changeType":"updated","timestamp":"2026-02-07T10:35:00Z","processed":false}

ワークフローとの統合

このスキルは、次から呼び出されます：

• Router Step 0.5（キューエントリがある場合に自動実行）
• Creator Skills（アーティファクトの作成後）
• 手動のヘルスチェック

自動呼び出しのパターン：

// Router Step 0.5 pseudocode
if (integrationQueueHasUnprocessedEntries()) {
  Task({
    task_id: 'task-1',
    subagent_type: 'developer',
    prompt: 'Invoke Skill({ skill: "artifact-integrator" })',
  });
}

鉄則

1. 新しい成果物の作成を始める前に、必ず統合キューを確認してください — ステップ 0.5 は必須です。未処理のエントリは孤立した負債となり、気付かないうちに蓄積します。
2. 成果物ごとに、自動生成される関連タスクを 3 件より多く作成してはいけません — SEC-ICE-002 の厳格な上限です。これを超えるとエージェントのパイプラインに過大な負荷がかかるため、残りの関連タスクは手動レビュー用にキューに登録してください。
3. 後方伝播に関する主張は、必ず実際のコードに照らして検証してください — キューに登録するには、重複が 3 件以上確認され、かつ 30 LOC 以上削減できることが必要です。未検証の主張は絶対に登録しないでください。
4. 完了を報告する前に、必ずキューエントリを processed: true に設定してください — 未処理のエントリは無期限に残り、その後の実行のたびに再試行されます。
5. 成果物グラフを更新せずに、統合上の不足を報告してはいけません — グラフは成果物間の関係を記録する正式な情報源です。グラフを更新しない不足の報告は、以降の実行で参照されません。

アンチパターン

アンチパターン	問題が生じる理由	正しい方法
統合キューの確認を省略する	未処理のエントリが気付かないうちに蓄積する	ステップ 1 で必ず integration-queue.jsonl を読み込む
成果物ごとに 3 件を超える関連タスクを作成する	タスクが急増し、エージェントのパイプラインに過大な負荷がかかる	SEC-ICE-002 を適用する：成果物ごとに最大 3 件、合計 10 件
コードを検証せずに後方伝播をキューに登録する	偽陽性によって不要な成果物が作成される	重複が 3 件以上あり、かつ 30 LOC 以上削減できることを確認する
キューエントリを処理済みにしない	次回の実行でエントリが無期限に再試行される	完了を報告する前に processed: true を設定する
成果物グラフを更新せずに不足を報告する	グラフが古くなり、以降の分析で誤ったデータが使われる	不足の分析後は必ずグラフのエッジを更新する
未検証の成果物 ID を使って統合を実行する	無効な ID によって、気付かないうちに失敗する	分析の前に成果物ファイルが存在することを確認する

関連スキル

• research-synthesis - 成果物作成前の調査フェーズ
• agent-creator - エージェントを作成します（統合分析をトリガーします）
• skill-creator - スキルを作成します（統合分析をトリガーします）
• hook-creator - フックを作成します（統合分析をトリガーします）
• workflow-creator - ワークフローを作成します（統合分析をトリガーします）

メモリプロトコル（必須）

開始前： .claude/context/memory/learnings.md を読み込みます。

完了後：

• 新しい統合パターン → .claude/context/memory/learnings.md
• 問題の発見 → .claude/context/memory/issues.md
• 決定事項 → .claude/context/memory/decisions.md

中断されることを前提にしてください。メモリに記録されていなければ、実行されていないのと同じです。