sync-horizon

Horizon の同期

eve-horizon リポジトリの最新の状態に合わせて、eve-skillpacks を同期します。

中核となる考え方

システムのドキュメントは、実装より遅れることがよくあります。機能は、計画に「Implemented」と記された feat コミットによってリリースされますが、docs/system/ は数週間更新されないことがあります。この同期では、情報源に直接あたります。実際にリリースされた内容を示すのは、計画、コードの変更、コミットメッセージです。システムのドキュメントは複数ある判断材料の一つであり、主な判断基準ではありません。

前提条件

• eve-horizon リポジトリが ../eve-horizon（兄弟ディレクトリ）にあること
• リポジトリのルートに .sync-state.json があること（なければテンプレートから作成）
• リポジトリのルートに .sync-map.json があること

アーキテクチャ：オーケストレーター + 並列ワーカー

オーケストレーターとして、リリース内容を調査し、対象を絞ったワーカーに作業を割り当てます。各ワーカーは独自のコンテキスト予算を使い、個別に一つの更新を処理します。

オーケストレーターは軽量な情報（コミットログ、計画のヘッダー、ファイル統計、CLI モジュール一覧）を読み取ります。ワーカーは詳細な内容（計画本文、コード差分、ソースドキュメント、対象ファイル）を読み取ります。

出力基準

• リリース済みのプラットフォーム動作のみを抽出します。「Implemented」または「Complete」と記された計画は、リリース済みの機能を示します。
• ロードマップの内容をスキルパックに含めないでください。「Proposed」または「Draft」と記された計画、および Planned (Not Implemented)、What's next、「current vs planned」のような枠組みのセクションは無視します。
• eve-work/eve-read-eve-docs/SKILL.md はタスクを起点とし、意図に応じて参照先を案内し、必要最小限の参照ファイルのみを読み込む構成にします。
• 参照ドキュメントは対象を絞り、実用的な内容にします。コピーではなく、要点を厳選してまとめてください。

ワークフロー

フェーズ 1：詳細な調査（オーケストレーター）

複数の観点から軽量な情報を読み取り、実際にリリースされた内容を把握します。

1a. コミットログ

cd ../eve-horizon && git log --oneline <last_synced_commit>..HEAD

コミットを分類します。

• feat: — 新しい機能（主な関心対象）
• fix: — ドキュメントに記載された動作に影響する可能性があるバグ修正
• docs: — ドキュメントの変更（すでにリリースされた機能について説明しているか確認）
• chore: / refactor: — 通常、スキルパックへの影響はありませんが、削除には注意してください

1b. 計画の分析

これは最も豊富な情報源です。計画には、リリースされた内容、その理由、実現方法が記されています。

cd ../eve-horizon && git diff --stat <last_synced_commit>..HEAD -- docs/plans/

変更された計画ごとに、ヘッダーのみ（最初の 15～20 行）を読み、ステータスを抽出します。

cd ../eve-horizon && head -20 docs/plans/<plan-file>.md

分類します。

• リリース済み：ステータスに Implemented、Complete、または Done が含まれる — 新しい機能の主な一次情報源です
• 進行中：ステータスに In Progress または Partially Implemented が含まれる — 把握しておきますが、未完成の作業は抽出しません
• 提案／ドラフト：ステータスに Proposed、Plan、Draft、Ready to build が含まれる — 完全にスキップします
• 削除済み：この期間に計画ファイルが削除された — 非推奨化または放棄された機能です

重要：計画の本文全体は読まないでください。ヘッダーのみを確認します。ワーカーが必要な計画を読みます。

1c. コードからの情報

新しい CLI コマンド、DB マイグレーション、パッケージの変更は、リリース内容を裏付け、計画だけでは十分に説明されていない機能を明らかにします。

# New/changed/removed CLI commands
cd ../eve-horizon && git diff --stat <last_synced_commit>..HEAD -- packages/cli/src/commands/

# New DB migrations (table/column names reveal capability shape)
cd ../eve-horizon && git diff --stat <last_synced_commit>..HEAD -- packages/db/migrations/

# Key package changes (new modules, removed modules)
cd ../eve-horizon && git diff --stat <last_synced_commit>..HEAD -- packages/shared/src/ packages/api/src/ packages/worker/src/ packages/gateway/src/ --stat-name-width=120 | head -50

1d. システムドキュメントの変更

引き続き有用な情報源です。特に削除や修正の確認に役立ちます。

cd ../eve-horizon && git diff --stat <last_synced_commit>..HEAD -- docs/system/ AGENTS.md

1e. 現在の CLI サーフェス

現在の CLI コマンドモジュールをスナップショットします。これは、エージェントが呼び出せる機能の確定情報です。

cd ../eve-horizon && ls packages/cli/src/commands/*.ts

フェーズ 2：機能の統合（オーケストレーター）

ここで一旦止まり、考えてください。 これは重要なステップです。すべての情報を相互に照合し、機能マップを作成します。

リリース済みの計画（Implemented／Complete）ごとに、機能エントリーを作成します。

Capability: <name>
  Plan: docs/plans/<file>.md (status: Implemented)
  Feat commits: <matching commit hashes>
  Code signal: <new CLI commands, new migrations, new/removed modules>
  System doc: <updated/created/unchanged>
  Scope: <which platform areas this touches>
  One-line summary: <what this capability does, from the plan header>

対応する計画がない feat コミットで確認できる機能についても、エントリーを作成します。これらは、小規模な機能や修正が直接リリースされたものです。

また、削除にも注意します。計画の削除、CLI コマンドの削除、モジュールの削除などです。これらはスキルからも削除する必要があります。

フェーズ 3：影響範囲の分析（オーケストレーター）

マップ内の各機能について、eve-read-eve-docs への影響を判断します。

3a. リファレンスドキュメントへの影響

各機能について、次の点を確認します。

1. 既存のリファレンスですでにこの領域が扱われていますか？ → ワーカーが更新します
2. 独自のリファレンスが必要な新しいプリミティブですか？ → ワーカーが作成します
3. 削除されたものがありますか？ → ワーカーが該当するリファレンスから古い内容を削除します

eve-work/eve-read-eve-docs/SKILL.md の現在のリファレンスインデックスと、.sync-map.json の reference_docs セクションを照合します。

3b. SKILL.md のルーティングへの影響

eve-work/eve-read-eve-docs/SKILL.md について、次の更新が必要か確認します。

• Task Router への項目の追加
• Index への項目の追加
• Intent Coverage Matrix への行の追加
• frontmatter へのトリガーキーワードの追加
• 非推奨になった機能の古い項目の削除

3c. その他のスキルへの影響

.sync-map.json の skill_triggers と composite_triggers を確認し、影響を受ける他のスキルを特定します。次の点も検討してください。

• eve-se/eve-manifest-authoring — マニフェストの形式が変更された場合
• eve-se/eve-deploy-debugging — デプロイ／インフラの動作が変更された場合
• eve-se/eve-auth-and-secrets — 認証モデルが変更された場合
• eve-work/eve-agent-memory — ストレージプリミティブが変更された場合
• eve-design/eve-fullstack-app-design — アプリのパターンが変更された場合

Phase 4: 作業項目を計画する（オーケストレーター）

Phase 3 で特定した更新ごとに、作業項目を作成します。

• タイトル: Update <target-file>: <capability name>
• 説明 — ワーカーが単独で作業を進めるために必要な情報をすべて記載します。
  • eve-horizon リポジトリのパス（../eve-horizon）
  • コミット範囲：<last_synced_commit>..HEAD
  • 参照する計画書（この更新に関連するリリース済みの計画書）
  • 差分の確認または読み取りが必要なソースファイル（コード、システムドキュメント）
  • 更新または作成する対象ファイルのパス
  • リファレンスドキュメントの更新、スキルの更新、新規リファレンスの作成、削除のいずれに該当するか
  • 以下から選んだ適切なワーカー向け手順

最後に、Update sync state and produce report という作業項目を追加します。これは、すべての更新が完了するまでブロックします。

いずれかの作業項目が eve-work/eve-read-eve-docs に関係する場合は、次も追加します。

• Run state-today compliance scan for eve-read-eve-docs
• Validate progressive-access routing in eve-read-eve-docs/SKILL.md
• Update .sync-map.json with any new reference doc mappings

Phase 5: ワーカーを起動する（並列）

作業項目ごとにバックグラウンドワーカーを1つ起動します。すべてのワーカーを一度に起動してください。

各ワーカーへのプロンプトは、単独で完結している必要があります。 ワーカーはオーケストレーターとの会話にアクセスできません。次の情報を含めてください。

1. 読み込む計画書ファイル（最優先の情報源です）
2. 関連するコード／ドキュメントの変更を確認するための git diff コマンド
3. 読み取りおよび変更の対象ファイル
4. Phase 2 でまとめた機能の概要
5. 以下から選んだ適切なワーカー向け手順

ワーカー向け手順：リファレンスドキュメントの更新

最優先の情報源は、リリース済みの計画書（Implemented／Complete と記されたもの）とコードの変更です。 システムドキュメントは二次的な情報源です。内容が古くなっていたり、存在しなかったりする場合があります。

1. タスクに記載された計画書を読み、リリースされた内容とその理由を把握します。
2. 更新対象の現在のリファレンスドキュメントを読みます。
3. 関連するソースファイル（コード、システムドキュメント）の git diff を実行します。
4. リリースされた機能をリファレンスドキュメントにまとめます。
   • その機能が何をするか（計画書とコードに基づく）
   • 使い方（CLI コマンド、マニフェスト設定、API 呼び出し）
   • 主な制約または要件
5. ロードマップの内容は含めないでください。実装済みの内容だけを記載します。
6. 既存ファイルを編集し、一から書き直さないでください。
7. 既存の構成、文体、書式を維持してください。

作業者への指示：新しいリファレンスドキュメント

1. この機能について説明している計画を読みます。
2. システムドキュメントに記載があるか確認します：cd ../eve-horizon && cat docs/system/<name>.md（存在しない場合もあります）。
3. 該当する場合は、CLI コマンドのソースを読みます：cd ../eve-horizon && cat packages/cli/src/commands/<name>.ts
4. eve-work/eve-read-eve-docs/references/ にある既存のリファレンスの規約に従って、リファレンスドキュメントを作成します。
5. 以下を含めます：目的、CLI コマンド／フラグ、関連する場合はマニフェスト設定、主な動作、制約事項。
6. 簡潔で、エージェントが実行に移せる内容にします。説明のコピーではなく、要点をまとめます。
7. 現時点の内容だけを記載します。計画中／ロードマップの内容は含めません。

作業者への指示：スキルの更新

主な情報源は、提供済みの計画とコード変更です。

1. タスクに記載された計画を読みます。
2. 更新対象の現在の SKILL.md を読みます。
3. 新しいコマンド、変更されたワークフロー、新機能を反映して更新します。
4. 廃止された機能に言及する古い内容を削除します。
5. 現時点の内容だけを記載します。段階的な情報開示を徹底します。
6. 簡潔な命令形を維持します。
7. 既存のファイルを編集し、一から書き直さないでください。

作業者への指示：SKILL.md のルーティング更新

この作業者は、eve-read-eve-docs の SKILL.md のルーティング、インデックス、対応表を更新します。

1. 現在の eve-work/eve-read-eve-docs/SKILL.md を読みます。
2. 他の作業者が作成した新しいリファレンスドキュメントごとに、以下を追加します：
   • 読み込むタイミングを説明するタスクルーターの項目
   • ファイルパスと簡潔な説明を記載したインデックスの項目
   • 独自のユーザー意図に対応する場合は、意図対応表の行
3. 削除された機能に関する古いルーティング項目を整理します。
4. YAML フロントマターに新しいトリガーキーワードを追加します。
5. 各セクション内では、アルファベット順または論理的な順序を維持します。

作業者への指示：陳腐化の確認

これは複数のプラットフォームプリミティブにまたがるスキルです。 このスキルの記述が、現在のプラットフォームの実態と一致しているか検証してください。

1. SKILL.md と、その references/ ディレクトリ内のすべてのファイルを読みます。
2. 変更の背景を把握するため、タスクに記載された提供済みの計画を読みます。
3. 現在の CLI コマンドモジュールを一覧表示します：

   cd ../eve-horizon && ls packages/cli/src/commands/*.ts
   

4. スキルに古い記述がないか確認します：
   • 「X 専用のものはない」／「X は利用できない」／「まだサポートされていない」などの記述。X が現在存在するか確認します。
   • 「現在の不足点」や「回避策」のセクション。それぞれの不足点が現在も該当するか確認します。
   • 判断表や比較表。抜けている行がないか確認します。
   • 削除された機能（例：inference／ollama／managed-models）への言及。
5. 古い記述が見つかった場合は、スキルを更新します。新しいプリミティブを追加し、誤った不足点を削除します。
6. 現時点の内容だけを記載します。簡潔な命令形を維持します。
7. 何が古く、何を修正したか報告します。

作業者への指示：同期マップの更新

.sync-map.json を更新し、この同期で見つかった新しいマッピングを反映します。

1. 現在の .sync-map.json を読みます。
2. 新しく作成された各リファレンスドキュメントについて、ソースファイルと対象を対応付ける reference_docs 項目を追加します。
3. 新しく見つかったスキルトリガーの関連付けごとに、skill_triggers 項目を追加します。
4. 削除されたソースドキュメントについて、古いマッピングを削除します。
5. 監視対象にすべき新しいディレクトリがあれば、watch_paths に含めます。

作業者プロンプトの例

You are updating a reference doc in the eve-skillpacks repository.

## Your Task
Update the file: eve-work/eve-read-eve-docs/references/agents-teams.md
Add coverage for agent aliases (short names for chat addressing).

## Capability Summary
Agent aliases let users declare short names for agents instead of using full
project-slug-agent-name. Declared in manifest under `agents[].alias`. Resolved
at chat dispatch time. Status: Implemented.

## Primary Source
Read the plan: cd ../eve-horizon && cat docs/plans/agent-aliases-plan.md

## Code Confirmation
The agents CLI was updated: cd ../eve-horizon && git diff <commit>..HEAD -- packages/cli/src/commands/agents.ts
New migration: packages/db/migrations/00076_add_agent_alias.sql

## Target
Read and edit: eve-work/eve-read-eve-docs/references/agents-teams.md

## Rules
- Distill only shipped behavior from the plan and code
- Edit the existing file; do not rewrite from scratch
- These are curated distillations for agents, not copies
- Keep it concise and actionable

フェーズ 6：結果を収集して最終処理する（オーケストレーター）

すべての作業者が完了するまで待ちます。

すべての更新作業項目が完了したら：

1. 現在の HEAD を取得します：

   cd ../eve-horizon && git rev-parse HEAD
   

2. 現時点の内容と段階的アクセスのチェックを実行します：

   ./private-skills/sync-horizon/scripts/check-state-today.sh
   

3. .sync-state.json を更新します：
   • last_synced_commit を HEAD のハッシュに設定します
   • last_synced_at を現在の ISO タイムスタンプに設定します
   • sync_log に追記します（直近 10 件を保持します）

フェーズ 7：報告する（オーケストレーター）

## Sync Report: <old_commit_short>..<new_commit_short>

### Commits
- <count> commits synced (<feat count> features, <fix count> fixes)

### Shipped Capabilities (from plans)
- <capability>: <one-line summary> (plan status, feat commits)

### Capability Cascade
For each shipped capability:
- <capability> → updated <reference/skill>, because <reason>

### Removals
- <what was removed/deprecated and cleaned from skills>

### Updated Reference Docs
- <file>: <what changed and why>

### New Reference Docs
- <file>: <what it covers>

### Updated Skills
- <skill>: <what changed>

### SKILL.md Routing Changes
- <new routes, index entries, or coverage matrix rows>

### Sync Map Changes
- <new mappings added>

### State-Today Compliance
- <pass/fail + scan results>

### Coverage Gaps
- <shipped capabilities with no reference doc yet>
- <plan files with no sync-map entry>
- <CLI commands with no documentation coverage>

### Next Steps
- <manual follow-up needed>

主な制約事項

• 実装内容を把握する際は、計画を最も信頼できる情報源として扱います。 システムドキュメントは二次資料です。コードの変更は確認材料です。
• オーケストレーターが参照するのは軽量な情報のみです：コミットログ、計画の見出し（冒頭15～20行）、ファイル統計、CLI モジュール一覧です。計画全文、差分全体、ソースドキュメントは決して参照しません。
• 作業者は詳細な情報を読みます：計画全文、コード差分、ソースドキュメント、対象ファイルです。
• 作業者の独立性：各作業者へのプロンプトは、計画のパス、コードのパス、対象パス、機能の概要、更新ルールを含む自己完結した内容にする必要があります。
• 並列実行：すべての作業者を同時に起動します（参照ドキュメントの作業者が完了してから起動するルーティング更新作業者を除きます）。
• 書き直すのではなく編集します：作業者は既存ファイルを段階的に変更します。
• 現時点の状態に忠実にします：実装済みで、リリースされている動作のみを記載します。
• 段階的に情報へアクセスできるようにします：エントリースキルではタスクを起点とするルーティングを維持し、詳細情報はリファレンスに残します。