Worktree Manager — 並行エージェント オーケストレーション

並行AI エージェント開発のための git worktree を管理します。決定論的なポート割り当てとファイルスコープ割り当てを備えた分離された worktree を作成し、最小差分優先の順序でマージを調整し、完了した作業を安全に破棄します。

merge を除くすべてのコマンドは自律的に完了まで実行されます。merge はコンフリクトが予測される場合にユーザーに確認します。

ランタイム: ai-skills/wt-cli/ の wt CLI (TypeScript/Node.js) 設定: .claude/skills/project.toml — プロジェクト固有のパス、コマンド、モジュール

コマンド

コマンド	使用方法	目的
spawn	/worktree-manager spawn <name> [--scope <path>]	worktree + ブランチ + ブートストラップを作成
list	/worktree-manager または /worktree-manager list	すべての worktree をステータス付きで表示
merge	/worktree-manager merge <name> または merge --all	ブランチをマージ、最小差分優先
teardown	/worktree-manager teardown <name> または teardown --all	チェック付きで安全に削除
scope	/worktree-manager scope <name> <path>	worktree にファイルスコープを割り当て
ports	/worktree-manager ports	ポート割り当てテーブルを表示
diff	/worktree-manager diff <name>	マージベースに対する diff 統計を表示

コマンドが指定されない場合は list がデフォルトです。

---

セットアップ: ランタイムの確認

コマンド実行前に、wt CLI が利用可能であることを確認します:

1. wt が PATH にあるか確認します:

   wt --version
   

2. 見つからない場合はローカルインストールを確認します:

   node ai-skills/wt-cli/dist/cli.js --version
   

3. どちらも機能しない場合はインストールします:

   cd ai-skills/wt-cli && npm install && npx tsup && cd -
   

動作する呼び出し方法 (wt または node <path>/dist/cli.js) をすべての後続コマンドで使用します。

---

コマンド: spawn — Worktree を作成

ブランチ、ブートストラップ、メタデータを含む新しい worktree を作成します。

使用方法:

• /worktree-manager spawn auth — 基本的な spawn
• /worktree-manager spawn auth --scope src/auth — ファイルスコープ付き
• /worktree-manager spawn payments --port 3100 — ポート明示指定
• /worktree-manager spawn api --skip-install — 依存関係インストールをスキップ

手順:

1. リポジトリが git リポジトリであることを確認します:

   git rev-parse --show-toplevel
   

2. 既存の worktree をチェック してコンフリクトを回避します:

   wt list --json
   

3. worktree を spawn します:

   wt spawn <name> --scope <path>
   

   CLI は以下を処理します:

   • ../wt-<repo>-<slug>/ サイドカーディレクトリを作成
   • HEAD から agent/<slug> ブランチを作成
   • 決定論的なポート (3000-3999 範囲) を割り当て
   • 依存関係をインストール (pnpm > yarn > npm、uv > pip)
   • .env.example を .env にコピー
   • .worktree/local.json メタデータを書き込み
   • extensions.worktreeConfig を有効化して worktree ごとの git 設定を許可

4. 作成された worktree のパス、ブランチ、ポート、スコープをレポート します。

ルール:

• スコープが明らかに異なる場合を除き、2-3 個のアクティブなエージェント worktree で開始
• worktree で作業を開始する前に、必ずスコープを割り当て
• 共有ホットスポット (ロックファイル、ルートマニフェスト、ルートレジストリ、バレルエクスポート、マイグレーション、スキーマスナップショット、生成されたクライアント) は1つの所有者のみに予約

---

コマンド: list — Worktree を表示

すべての worktree をステータス付きで表示します。

手順:

1. worktree をリストします:

   wt list --all
   

2. 各 worktree の名前、ブランチ、ポート、スコープ、ロック状態、ダーティ/クリーン状態を表示するテーブルをレポート します。

JSON 出力の場合 (プログラム的なチェックに便利):

wt list --all --json

---

コマンド: merge — 調整されたマージ

worktree ブランチをターゲットブランチにマージします (最小差分優先の順序)。

使用方法:

• /worktree-manager merge auth — 1 つの worktree をマージ
• /worktree-manager merge --all — すべての worktree ブランチをマージ
• /worktree-manager merge --all --dry-run — マージ順序をプレビュー

手順:

1. マージプランをプレビューします:

   wt merge --all --dry-run
   

   各ブランチの差分サイズ、順序、コンフリクト予測を表示します。

2. コンフリクトが予測される場合は 、ユーザーに進めるか競合するブランチをスキップするか確認します。

3. マージを最小差分優先の順序で実行します:

   wt merge <name> --delete-branch
   

   または全体の場合:

   wt merge --all --delete-branch
   

4. すべてのマージ後、結果を確認します:

   git log --oneline -10
   git status --short
   

マージポリシー:

• 常に順序立てて最小差分優先でマージ
• 予測されるコンフリクトを持つブランチはスキップ — 手動解決のためレポート
• --no-ff マージを使用してブランチ履歴を保持
• 成功後にソースブランチを削除 (--delete-branch)

---

コマンド: teardown — 安全な削除

セーフティチェック付きで worktree を削除します。

使用方法:

• /worktree-manager teardown auth — 1 つの worktree を削除
• /worktree-manager teardown auth --delete-branch — ブランチも削除
• /worktree-manager teardown --all — プライマリ以外のすべての worktree を削除

手順:

1. コミットされていない変更をチェックします:

   wt diff <name>
   

2. コミットされていない変更がある場合は ユーザーに警告して確認を求めます。明示的な許可なく --force を使用しません。

3. worktree を削除します:

   wt teardown <name> --delete-branch
   

4. 削除を確認します:

   wt list --all
   

セーフティルール:

• プライマリ worktree を決して削除しない
• ユーザー確認なく --force を使用しない
• 削除前に常にコミットされていない変更を表示
• 削除後に常に worktree メタデータをプルーン

---

コマンド: scope — ファイルスコープを割り当て

worktree のファイル/ディレクトリスコープを設定または更新します。

手順:

1. スコープを設定します:

   wt scope <name> <path>
   

2. 確認します:

   wt list --all
   

スコープルール:

• すべての worktree は作業開始前にスコープを割り当てるべき
• スコープは並行 worktree 間で重複しないこと
• 広いスコープにはディレクトリパスを使用 (src/auth/)
• 狭いスコープにはファイルパターンを使用 (src/auth/middleware.ts)

---

コマンド: ports — ポート割り当てテーブル

どの worktree にどのポートが割り当てられているかを表示します。

wt ports

ポートは worktree パスの SHA256 ハッシュを使用して 3000-3999 範囲から決定論的に割り当てられます。これにより同じ worktree が常に同じポートを取得し、並行開発サーバー間のコンフリクトを回避します。

---

コマンド: diff — Diff 統計

worktree ブランチのマージベースに対する diff 統計を表示します。

wt diff <name>

ファイルごとの変更、合計挿入数、削除数、変更されたファイル数を表示します。マージ調整前にマージの複雑さを評価するのに便利です。

JSON 出力の場合:

wt diff <name> --json

---

ワークフロー: マルチエージェント キャンペーン

マルチエージェント キャンペーンの典型的なワークフロー:

1. 計画: 2-3 個の独立したタスクスコープを特定
2. Spawn: 重複しないスコープで worktree を作成

   wt spawn auth --scope src/auth
   wt spawn payments --scope src/payments
   wt spawn notifications --scope src/notifications
   

3. 作業: 各エージェントが独自の worktree で作業
4. レビュー: diff サイズとコンフリクト可能性をチェック

   wt merge --all --dry-run
   

5. マージ: 最小差分優先でマージ

   wt merge --all --delete-branch
   

6. クリーンアップ: 残りの worktree を削除

   wt teardown --all
   

---

慣例

• Worktree パスは ../wt-<repo>-<slug> サイドカーディレクトリ慣例に従う
• ブランチ名は agent/<slug> 慣例に従う
• メタデータは .worktree/local.json に存在 (.git/info/exclude 経由で git から除外)
• ポート範囲: 3000-3999 (決定論的、SHA256 ベース)
• JavaScript プロジェクトには pnpm を使用することが望ましい (ハードリンクで 80% のディスク節約)
• Windows 上: core.longpaths を有効化、worktree 名を短く保つ
• 規約ファイル (project.toml の [project].conventions) を読んでプロジェクトスタイルを確認