git-worktree-manager

Git Worktree Manager

Git worktree を使って、決定的な命名、自動ポート割り当て、環境ファイルの同期、依存関係のインストール、クリーンアップの自動化を備えた並行開発ワークフローを管理します。各エージェントまたはターミナルセッションが、それぞれのポート、環境、実行中のサービスを持つ独立した worktree を所有するマルチエージェントワークフローに最適化されています。

主な機能

• Worktree のライフサイクル — 新規または既存のブランチから、決定的な命名で worktree を作成し、.env ファイルをコピーし、ロックファイルの判定に基づいて依存関係をインストールします。クリーン／変更ありと ahead／behind の状態を含めて一覧表示し、未コミットの変更を検出して安全に削除できます。
• ポート割り当て — worktree ごとに決定的に割り当て（base + index * stride）、実行中のプロセスとの競合を検出し、.worktree-ports.json にマップを永続化して、Docker Compose のオーバーライドを生成します。
• マルチエージェントの分離 — worktree ごとにブランチを1つ、エージェントを1つ割り当て、共有状態をなくして競合のない並行実行を実現し、追跡できるようタスク ID を対応付けます。
• クリーンアップの自動化 — 経過時間による古い worktree の検出、安全に削除できるようマージ済みブランチを検出し、変更ありの状態を警告して、安全確認付きで一括クリーンアップします。

使用する場面

• 開発サーバーを起動したまま、2つ以上のブランチを同時に開く必要がある場合。
• 機能開発、緊急修正、PR のレビュー用に環境を分離したい場合。
• 複数の AI エージェントに、互いに干渉しない個別のワークスペースが必要な場合。
• 現在のブランチが作業できない一方、緊急修正が必要な場合。
• 手動の rm -rf 操作ではなく、クリーンアップを自動化したい場合。

先に確認すること

worktree を管理する前に、以下の入力内容を確定してください。項目が欠けている、または曖昧で結果が変わる場合は確認してください。結果に影響しない場合は、妥当な既定値を使用し、その値を明示してください。

• 操作： worktree の作成、一覧表示、削除、クリーンアップのいずれかを指定します（worktree_manager.py、port_allocator.py、worktree_validator.py のどのアクションを使用するかが決まります）。
• ブランチとベース： worktree が追跡するブランチと、その作成元となるベースを指定します（worktree の命名と分離方法が決まります）。
• ポート／サービスの要件： 開発サーバーや Docker に割り当て済みポートが必要かどうかを指定します（決定的なポート範囲と、生成する Docker Compose オーバーライドが決まります）。

リクエストで重要な入力を2、3項目確認し、全項目を一度に尋ねないでください。ユーザーがすぐに結果を求める場合は、結果を提示し、冒頭に前提を記載してください。

ツール

ツール	目的	コマンド
worktree_manager.py	worktree の一覧表示、作成、削除、クリーンアップ	python scripts/worktree_manager.py list
port_allocator.py	決定的なポート範囲の割り当て／確認／解放、レジストリの同期	python scripts/port_allocator.py status
worktree_validator.py	worktree の健全性を検証（古さ、ブランチの欠落、環境の同等性、ポートの競合、ロックファイル）	python scripts/worktree_validator.py --stale-days 14

リファレンス

タスクに合ったリファレンスを読み込み、このファイルは簡潔に保ち、必要に応じて詳細を参照してください。

• references/setup-and-ports.md — git worktree コマンドのクイックスタート、決定的なポート割り当て方式と .worktree-ports.json の形式、競合検出のスニペット、setup-worktree.sh スクリプト全体、worktree ごとの Docker Compose オーバーライドを説明します。worktree の作成時やポート／サービスの設定時に読んでください。
• references/cleanup-and-workflows.md — 安全なクリーンアップ用の cleanup-worktrees.sh スクリプト、マルチエージェントの割り当てパターンとルール、シナリオからアクションを選ぶ判断マトリクス、作成後の検証チェックリストを説明します。クリーンアップを自動化するときや、エージェントを連携させるときに読んでください。
• references/operations-playbook.md — よくある落とし穴、ベストプラクティス、トラブルシューティング表、成功基準を説明します。ワークフローをリリースする前や、問題の診断時に読んでください。

対象範囲と制限事項

このスキルの対象：

• Git worktree のライフサイクル：作成、一覧表示、ステータスの確認、削除
• 並列で実行する開発サーバー向けの決定論的なポート割り当てと競合の回避
• 環境ファイルの同期と Docker Compose のオーバーライドパターン
• マルチエージェントのワークスペース分離戦略とクリーンアップの自動化

このスキルの対象外：

• Git のブランチ戦略やマージコンフリクトの解決（pr-review-expert と release-manager を参照）
• シークレットのローテーション、Vault の統合、認証情報の管理（env-secrets-manager を参照）
• CI/CD パイプラインの設定や自動テストのオーケストレーション（ci-cd-pipeline-builder を参照）
• モノレポのパッケージ管理、ワークスペースのリンク、パッケージ間の依存関係の解決（monorepo-navigator を参照）

統合ポイント

スキル	統合内容	データフロー
env-secrets-manager	worktree のセットアップでは、このスキルが管理するシークレットを含む .env ファイルをコピーします	.env ファイルはメインリポジトリから各 worktree にコピーされ、シークレットの参照はすべてのコピーで一貫性が保たれます
ci-cd-pipeline-builder	CI パイプラインでは、並列テストマトリクスの実行に worktree を起動できます	パイプライン設定により、マトリクス内の各ジョブで setup-worktree.sh が実行され、ポート割り当てによってサービスの競合を防ぎます
release-manager	リリースブランチには安定化用の専用 worktree を用意し、その間も機能開発を継続できます	リリース worktree はリリースブランチから作成され、マージ状況に基づいてクリーンアップが自動化されます
monorepo-navigator	モノレポの構成では、worktree がパッケージの境界と共有依存関係を尊重する必要があります	worktree の作成時にモノレポのルートにあるロックファイルが引き継がれ、パッケージ単位の開発サーバーには割り当てられたポートブロックが使用されます
pr-review-expert	実行中のコードを使った手動検証のため、分離された worktree で PR をレビューできます	レビュアーは PR ブランチの worktree を作成し、割り当てられたポートで開発サーバーを起動して、レビュー後に worktree を削除します
tech-debt-tracker	古い worktree や放置されたブランチは、技術的負債を示す指標になります	クリーンアップスクリプトの出力は負債追跡に取り込まれ、worktree の経過期間とマージ状況が優先度スコアの判断に使われます