parallel-worktree

parallel-worktree

大量のサブエージェント起動・worktree 生成・push という外部影響の大きい操作を含むため、disable-model-invocation: true とし /parallel-worktree の明示実行時のみ動作する。

起動引数

/parallel-worktree resume — クラッシュ復旧モード（下記セクション参照）。第一引数が resume のときはこちらに分岐し、Phase 0 以降の通常オーケストレーションには進まない。

/parallel-worktree [計画ファイルのパス] [--remote-control] [--model <model>] [--permission-mode <mode>] [--effort <level>] — 通常のオーケストレーション起動。

• 計画ファイルのパス: 事前に作成済みの計画ファイル（無ければ所在をユーザーに確認）。
• --remote-control（任意・オプトイン）: 起動引数にこのトークンが含まれていたら、Phase 1 の plan_orchestration.py 実行にそのまま --remote-control を渡す。各 worktree の claude が --remote-control <ブランチ名> で起動し、detached tmux に入ったままでも claude.ai 等からリモート接続できる（この親セッションと同じ Remote Control 接続方式）。Remote Control 名は tmux セッション名（sanitize 済みブランチ名）に揃うので、tmux ls / wt list / リモート一覧で同じ識別子で対応が取れる。無指定なら従来通りローカル tmux のみ（リモート登録しない）。
• --model <model> / --permission-mode <mode> / --effort <level>（任意）: 各 worktree の claude の起動既定。起動引数にあれば Phase 1 の plan_orchestration.py 実行へそのまま渡す（値ごと pass-through）。
  • --model: alias（opus/sonnet/fable 等）またはフルネーム
  • --permission-mode: acceptEdits / auto / bypassPermissions / manual / dontAsk / plan
  • --effort: low / medium / high / xhigh / max
  • 適用は task 個別指定（spec の model/permission_mode/effort）> グローバル既定（このフラグ）> 未指定（claude 自身のデフォルト＝settings.json 等） の優先順。タスクごとに変えたい場合は spec 側に書く。

クラッシュ復旧モード（/parallel-worktree resume）

PC の強制終了・クラッシュ等でセッションが不意に中断されたときのための read-only モード。並列・stacked で複数 worktree（レーン）を動かしている最中に落ちると、レーンの数だけ「どこまで終わっていたか」を手動で説明し直す必要が出るため、wt list を土台に全レーンの状態を一度に機械的に集計する。

新しい worktree・tmux・エージェントは一切起動しない（Phase 2 には進まない）。能動的な引き継ぎ用の handoff スキル（一部プロジェクトに導入済み）とは補完関係: handoff はセッションを意図的に終える前に自分で書く前提のドキュメントで、不意打ちのクラッシュには使えない。resume は逆に、事前準備が無い不意の中断からの受け身の状況復元に使う。

手順:

1. UV_PROJECT_ENVIRONMENT="$HOME/.cache/uv-venvs/parallel-worktree" uv run --project "<SKILL>" python "<SKILL>/scripts/resume_check.py" を実行する（-C <path> で対象リポジトリを指定可、既定は cwd）。内部で wt list --format json を呼び、レーンごとの branch / path / 未コミット変更（dirty） / 未push件数（ahead）/ 未pull件数（behind）を集計し、ブランチ名から ~/.claude/plans/（既定。--plans-dir で変更可）内の対応しそうな計画ファイルも突き合わせる。
2. 出力の NEEDS ACTION に挙がったレーン（dirty=True または ahead>0）を優先して、レーンごとに次アクション（git status/git diff で中身を確認 → 必要なら /gh-push や /pr-create [base]、または実装の続行）をユーザーに提示する。plan_candidates が見つかったレーンはその計画ファイルを読み、残タスクの位置を特定する材料にする。
3. 複数レーンにまたがる作業がある場合、憶測でまとめて処理せず、レーンごとにユーザーへ状況を要約してから次の対応を確認する（各レーンの文脈は独立しているため）。

前提と本質的な制約

着手前にこの 3 点を頭に入れる。設計判断の根拠になる。

1. 並列と stacked は相反する。 並列＝タスク間が独立（同時に走らせられる）。stacked＝後段が前段のコードに依存する連鎖（前段がコミットされて初めて後段を切れる）。だから「全部まとめて並列 background」は stacked では成立しない。独立タスク群は並列、依存連鎖は逐次 に振り分けるのがこのスキルの肝。

2. worktree は必ず wt で作る。 Claude の isolation: "worktree" は使わない。wt switch --create で作れば post-start hook が走り、gitignored の symlink 化・direnv allow まで済んでビルド可能な実環境になる。hook の走らない worktree でエージェントを動かすと、direnv/依存が無くビルド・テストが通らない事故になる。

3. wt は PR を作らない／stacked branch もネイティブ非対応。 stacked は「wt switch --create <child> --base <parent> でブランチを積む」＋「PR は gh（/pr-create スキル）で --base <parent> 指定」の合わせ技で実現する。

決定論ツール（scripts/）と AI の責務分担

このスキルは「意味理解が要る部分（AI）」と「機械的に確定できる部分（スクリプト）」を分ける。AI の責務は計画ファイルから「タスクと依存辺」を読み取り JSON spec を組むところまで。そこから先の環境前提収集・スケジュール算出・コマンド生成は決定論スクリプトに委譲し、再発明と順序ミスを防ぐ。

スクリプトは Python プロジェクト（pyproject.toml + uv.lock）として梱包され、uv が requires-python に沿った venv を構築して実行する。venv は skill 配下ではなく UV_PROJECT_ENVIRONMENT="$HOME/.cache/uv-venvs/parallel-worktree" に必ず逃がす（skill ディレクトリは read-only の nix store / plugin cache に配置され得るため）。cwd 非依存なので、プラグインとして任意の環境へ配置しても動く。以下、skill 本体のパスを <SKILL> と表記する（プラグイン実行時は ${CLAUDE_PLUGIN_ROOT}/parallel-worktree、個人 skill 実行時はこの SKILL.md があるディレクトリ）。

• scripts/preflight.sh（read-only）: wt/gh/tmux 有無・既定ブランチ・未コミット変更・既存 worktree/ブランチ名衝突を収集。bash <SKILL>/scripts/preflight.sh を実行し、WARNING を解消してから起動に進む。

• scripts/plan_orchestration.py: AI が組んだ JSON spec を入力に、循環検出・base 解決・並列ウェーブ算出・wt/tmux//pr-create コマンド列生成を行う。実行は必ず .venv 経由:

  UV_PROJECT_ENVIRONMENT="$HOME/.cache/uv-venvs/parallel-worktree" uv run --project "<SKILL>" python "<SKILL>/scripts/plan_orchestration.py" <spec.json>
  # 起動引数のオプションはそのまま前に付ける（--remote-control / --model / --permission-mode / --effort）:
  UV_PROJECT_ENVIRONMENT="$HOME/.cache/uv-venvs/parallel-worktree" uv run --project "<SKILL>" python "<SKILL>/scripts/plan_orchestration.py" --remote-control --model opus --permission-mode acceptEdits --effort high <spec.json>
  

  spec の形（scripts/example-spec.json 参照）:

  {
    "default_base": "main",
    "tasks": [
      {"id": "A",  "branch": "refactor-logger",  "depends_on": [],     "prompt": "...",
       "boundary": ["pkg/logger/**"]},
      {"id": "B2", "branch": "feat-client-retry", "depends_on": ["B1"], "prompt": "...",
       "boundary": ["internal/client/**", "docs/dev/<対象>/**"],
       "model": "opus", "permission_mode": "plan", "effort": "high"}
    ]
  }
  

  depends_on 空＝独立（並列・base はデフォルト）、親 1 つ＝その親ブランチを base にした stacked 段。task の model/permission_mode/effort は任意で、その task の claude だけ起動設定を上書きする（CLI のグローバル既定より優先。どちらも無ければ claude 自身のデフォルト）。boundary（触ってよいパスの glob 配列）は任意で、書くと境界ファイル生成が有効になる（下記「タスク境界の宣言」）。出力の SCHEDULE（起動ウェーブ）・BOUNDARY（境界宣言の一覧）・COMMANDS（実行コマンド列）をそのまま plan と実行に使う。スクリプトのロジック（順序・base・クォート・ワーカー指示の標準セクション）は SKILL.md 上で再現しない。

タスク境界の宣言（スコープドリフト防止）

並列レーンでワーカーが当初タスクの境界から逸脱するスコープドリフトを、指示 + 機械ブロックの二層で止める。

• spec の task に boundary（glob 配列）を書くと、plan_orchestration.py がその worktree ルートへ境界ファイル .claude/task-boundary.json（task_id / branch / allow の公開契約書式）を生成する起動コマンドを組む。worktree ローカル・gitignored（git rev-parse --git-path info/exclude へ追記）・wt remove で worktree ごと消える
• 境界ファイルがあると task-boundary hook（hooks/task-boundary-plugin。併用推奨） が境界外への Edit/Write/NotebookEdit を PreToolUse で deny する。スキルと hook は互いを呼ばず、境界ファイルという契約だけで結合する（hook 未 install でも指示層は機能する）
• boundary を書かない task は境界ファイルを生成しない（従来動作）。境界ファイルが無ければ hook は即 exit 0 で沈黙するので、境界宣言はオプトイン
• 境界の決め方は依存解析と同じ材料（触るファイルが重ならない範囲）。テスト実装も含むので実装・テスト両ディレクトリを宣言に入れる（TDD 順序を指示しながらテストが境界外だと詰む）

生成方式・gitignore 方式の選定理由は references/orchestration.md の「タスク境界の宣言」を参照。

ワーカー指示の標準セクション（常設）

ワーカーへ渡す指示は手書きしない。plan_orchestration.py が spec の prompt（タスク本文）の後ろへ下記を必ず連結する。

1. 実装範囲の境界 — boundary の glob と一致（境界ファイルの allow と同じ値を使うのでコードで整合が担保される）
2. TDD 順序 — テスト実装 → アプリケーション実装
3. コミット粒度 — commit-flow 準拠（Conventional Commits、論理的に独立した修正は都度）
4. push ポリシー — 自分の feature ブランチのみ
5. PR 作成前ゲート — /review-converge で収束させてから /pr-create [base]

spec の prompt にはタスク固有の内容と完了条件だけを書く（境界・TDD・PR 手順を重複して書かない）。雛形の全文は references/orchestration.md の「タスクプロンプト雛形」。

全体フロー

Phase 0: 計画ファイルを読み、spec を組む

入口は事前に作成済みの計画ファイル（引数のパス。無ければ所在をユーザーに確認）を読むこと。計画は別途 grill-me 方式（対話的な問い詰め）で固めてファイル化されている前提。

読み込んだら、各タスクの 依存辺（A→B） と 境界（boundary: 触ってよいパスの glob） を意味的に判定し、上記 JSON spec に落とす。判定基準（同一ファイル/モジュールに触る、前段の型・関数・API・スキーマに依存する 等）は references/orchestration.md の「依存解析」を参照。計画ファイルに依存関係やタスク境界が欠けている／曖昧なときは、憶測で埋めず grill-me 方式で確認する（依存の読み違えは並列化を破綻させる。境界の読み違えは hook による誤 deny か、逆にドリフトの取り逃がしになる）。

ワーカー指示の標準セクション（境界・TDD 順序・PR 前ゲート・コミット粒度）はスクリプトが自動付与するので、prompt にはタスク固有の内容と完了条件だけを書く。

Phase 1: 事前確認・スケジュール算出 → plan 承認

1. bash <SKILL>/scripts/preflight.sh を実行。WARNING（未コミット変更・ツール欠落・名前衝突）があれば先に解消する。
2. UV_PROJECT_ENVIRONMENT="$HOME/.cache/uv-venvs/parallel-worktree" uv run --project "<SKILL>" python "<SKILL>/scripts/plan_orchestration.py" <spec.json> でスケジュール／コマンド列を算出。ERROR（循環・未定義参照・重複・不正な permission_mode/effort）が出たら spec を直して再実行。起動引数に --remote-control / --model / --permission-mode / --effort があればこのコマンドにもそのまま付ける（生成される tmux コマンドの claude にそのフラグが乗る）。
3. その出力を土台に plan を組み、ExitPlanMode で承認を取る。plan には必ず含める:
   • 振り分け表 / 起動ウェーブ（スクリプトの SCHEDULE）
   • コミット計画: commit-plan スキル準拠（plan 本文に必ず含める）
   • PR 戦略: 各ブランチの base（スクリプトの PR セクション）

承認なしで worktree 生成・エージェント起動に進まない。

Phase 2: worktree 作成・並列/stacked 起動

承認後、スクリプトの COMMANDS をウェーブ順に実行する。コマンドの意味は references/orchestration.md を参照。

• wave 0（独立）: まとめて並列起動してよい
• 後続 wave（stacked）: 前段のコミット完了を wt list で確認してから起動（後段が前段のコードを見られるように）

各エージェントへ渡す指示の標準セクション（実装範囲の境界・TDD 順序・コミット粒度・push ポリシー・/review-converge → /pr-create の PR 前ゲート）はスクリプトが自動付与するので、spec の prompt に手書きしない。boundary 宣言ありの task は、起動コマンドが -x bash の bootstrap 経由になり、worktree 生成後・claude 起動前に境界ファイルを置く（COMMANDS をそのまま実行すればよい）。worktree は必ず wt switch --create で作り、isolation: "worktree" は使わない。

Phase 3: PR 作成

各エージェントが実装・コミット完了後、まず /review-converge で指摘を収束させ、そのうえで自分で /pr-create [base] を実行して draft PR を作る（スクリプトの PR セクション通り）。この 2 段は標準セクションで全 task に指示される。

• PR 作成前ゲート: /review-converge の収束前に PR を作らない（レビュー往復を PR 上に持ち出さない）
• push ポリシー: エージェントは自分の feature ブランチに限り push 可。main 等の保護ブランチへは push しない
• stacked: /pr-create <parent-branch> で base を前段に向ける
• /pr-create はタイトル/本文をユーザー承認後に作成する対話ゲートを持つ。各 tmux pane で承認待ちになるので、ユーザーが pane を巡回して承認する。--remote-control 起動時は pane を巡回せず、claude.ai 等のリモート接続から各セッション（Remote Control 名＝ブランチ名）に入って承認できる

Phase 4: 監視・後始末

• 進捗確認: wt list（各 worktree の状態・diff・CI を一覧）
• マージ後: 単発なら wt remove（worktree 削除、マージ済みブランチも削除）。全レーンのマージが済んだら /post-merge-cleanup を案内する（worktree・ブランチ・tmux セッションをまとめて承認ゲート付きで片付け、未 push の残るレーンは保護される）
• stacked の再 rebase: 下段が変わったら上段を rebase。wt merge --rebase か手動 git rebase（この環境に wt sync/worktrunk-sync は無い）

連携スキル・参照

このスキルは下記を呼び出す側で、内容を重複させない。

• commit-plan: plan のコミット計画（Phase 1 の plan 本文に必ず含める）
• commit-flow: コミット粒度とコミットの実施（各エージェント）
• review-converge: PR 作成前ゲートの収束ループ（Phase 3 で各エージェントが /review-converge を実行）
• pr-create: PR 本文作成（Phase 3 で各エージェントが収束後に /pr-create を実行）
• worktrunk: wt の設定・hook の詳細が要るとき
• task-boundary hook（hooks/task-boundary-plugin。併用推奨・別プラグイン）: 境界ファイルを読んで境界外の Edit/Write を機械ブロックする。このスキルとは境界ファイル書式という契約だけで結合し、互いを呼ばない
• references/orchestration.md: 依存解析ヒューリスティック、wt/tmux/gh コマンドレシピ、stacked 構築手順、タスク境界の宣言（生成方式・gitignore 方式の選定理由）、タスクプロンプト雛形