multitask

マルチタスクスキル

目的

複数の独立した開発タスクを並行して実行します。各ワークストリームは、コードで強制されるワークフローの手順に従い、分離された /tmp クローン内で専用の Recipe Runner プロセスを実行します。

主な利点：プロンプトベースの Markdown ワークフローではなく、Recipe Runner の YAML レシピを使用します。Python が手順の実行を制御するため、手順を飛ばすことはできません。

クイックスタート

インラインタスク

/multitask
- #123 (feat/add-auth): Implement user authentication
- #124 (feat/add-logging): Add structured logging
- #125 (feat/update-api): Update API endpoints

JSON 設定

workstreams.json を作成します。

[
  {
    "issue": 123,
    "branch": "feat/add-auth",
    "description": "User authentication",
    "task": "Implement JWT-based authentication with login/logout endpoints",
    "recipe": "default-workflow"
  },
  {
    "issue": 124,
    "branch": "feat/add-logging",
    "description": "Structured logging",
    "task": "Add structured JSON logging across all API endpoints"
  }
]

次に、/multitask workstreams.json を実行します。

仕組み

User provides task list
        |
        v
For each task:
  1. Clone branch to /tmp/amplihack-workstreams/ws-{issue}/
  2. Write launcher.py (Recipe Runner with CLISubprocessAdapter)
  3. Write run.sh (sets session tree vars, runs launcher.py)
  4. Launch subprocess via Popen
        |
        v
Monitor all workstreams (60s intervals)
        |
        v
Report: PR numbers, success/failure, runtime

Recipe Runner を使う理由

項目	従来方式（Markdown）	Recipe Runner（YAML）
手順の順序	プロンプトベース（スキップ可能）	コードで強制（Python ループ）
テンプレート変数	なし	{{task_description}}、{{repo_path}}
エラー処理	暗黙的	手順ごとに即時停止
進捗状況の追跡	不透明	手順ごとのステータス

重要な実装の詳細

1. /tmp クローン（ワークツリーではありません）：ワークツリーのシンボリックリンクは、ネストされた Claude セッションを混乱させます。クリーンなクローンを使えば、これを回避できます。
2. --subprocess-safe：従来モードでは、このフラグを渡してステージングと環境変数の更新をスキップし、~/.amplihack/.claude/ への同時書き込みによる競合を防ぎます（issue #2567）。
3. Recipe Runner アダプター：CLISubprocessAdapter は、レシピ内の各エージェント手順で claude -p を呼び出します（amplihack ラッパーを使わないため、ステージング競合は発生しません）。
4. 子プロセスの環境クリーンアップ：共通の build_child_env() ユーティリティは、ブロックする環境変数を除去し、セッションツリーのコンテキストを引き継ぎます。

実行モード

レシピモード（デフォルト）

各ワークストリームは Python ランチャーを介して run_recipe_by_name() を実行します。

from amplihack.recipes import run_recipe_by_name

result = run_recipe_by_name("default-workflow",
    user_context={"task_description": task, "repo_path": "."})

従来モード

同時ステージング競合（issue #2567 を参照）を避けるため、--subprocess-safe を使った単一セッションのプロンプトベース実行に切り替えます。

amplihack claude --subprocess-safe -- -p "@TASK.md Execute autonomously following DEFAULT_WORKFLOW.md."

--subprocess-safe フラグは、ステージングと環境変数の更新をすべてスキップするため、並行するワークストリームが ~/.amplihack/.claude/ で競合することはありません。親の amplihack プロセスは、すでにフレームワークファイルをステージングしています。

Recipe Runner を利用できない場合や、完全なセッションコンテキストが有益なタスクでは、--mode classic を使用してください。

利用可能なレシピ

amplifier-bundle/recipes/ 内の任意のレシピを、ワークストリームごとに使用できます。

レシピ	手順数	最適な用途
default-workflow	52	機能、バグ、リファクタリング（デフォルト）
investigation-workflow	23	調査、コードベース分析
verification-workflow	5	軽微な変更、設定の更新
auto-workflow	9	完了するまで自律的に反復

タスクごとに、JSON 設定で "recipe": "investigation-workflow" のように指定します。

モニタリング

# Watch all logs
tail -f /tmp/amplihack-workstreams/log-*.txt

# Check specific workstream
tail -f /tmp/amplihack-workstreams/log-123.txt

# Check running processes
ps aux | grep launcher.py

# Final report
cat /tmp/amplihack-workstreams/REPORT.md

補助ファイルを読むタイミング

必要な情報	ファイル
API 全体、設定オプション、アーキテクチャ	reference.md
実際の使用例	examples.md
Python オーケストレーターのソース	orchestrator.py

ディスク管理とクリーンアップ

ディスク使用量について

各ワークストリームは完全な Git クローン（約 1.5GB）を作成します。10 個のワークストリームを並行して実行すると、一時的なディスク使用量は約 15GB になります。

場所：

• /tmp/amplihack-workstreams/ws-{issue}/ - 各ワークストリームの作業ディレクトリ
• /tmp/amplihack-workstreams/log-{issue}.txt - ログファイル（別の場所に保持）
• /tmp/amplihack-workstreams/REPORT.md - 最終実行レポート

クリーンアップするタイミング

✅ 削除しても安全です：

• PR が main にマージされている
• ワークストリームのデバッグや調査が完了している
• 新しいワークストリーム用のディスク容量が必要である
• マルチタスクセッションの PR がすべて完了している

❌ 削除しても安全ではありません：

• PR がまだレビュー中である
• PR に手動で解決する必要のあるマージコンフリクトがある
• デバッグのために作業ディレクトリを確認する必要が生じる可能性がある
• ワークストリームが失敗しており、問題の原因をまだ特定していない

手動クリーンアップコマンド

# Check disk usage first
du -sh /tmp/amplihack-workstreams/*

# Clean up specific workstream (after PR merged)
rm -rf /tmp/amplihack-workstreams/ws-123

# Clean up all workstreams (after all PRs merged)
rm -rf /tmp/amplihack-workstreams/ws-*

# Keep log files, delete only working directories
find /tmp/amplihack-workstreams -type d -name "ws-*" -exec rm -rf {} +

# Check available disk space
df -h /tmp

自動クリーンアップ（ヘルパーコマンド）

PR をマージした後、クリーンアップヘルパーを使うと、マージ済みのワークストリームを自動的に削除できます。

# Clean up all workstreams with merged PRs
python .claude/skills/multitask/orchestrator.py --cleanup workstreams.json

# Dry run (show what would be deleted)
python .claude/skills/multitask/orchestrator.py --cleanup --dry-run workstreams.json

クリーンアップヘルパーは、次の処理を行います。

• gh CLI を使って各ワークストリームの PR ステータスを確認します
• MERGED ステータスのワークストリームのみを削除します
• 過去の参照用にログファイルを保持します
• 解放されたディスク容量を報告します

ディスク容量の監視

オーケストレーターは、ワークストリームを起動する前にディスク容量を自動的に確認します。

⚠️  WARNING: Only 8.2GB free in /tmp
Each workstream requires ~1.5GB. Consider cleaning up:
  rm -rf /tmp/amplihack-workstreams/ws-*
Continue anyway? (y/N):

目安： 複数のワークストリームを使った開発を快適に行うため、少なくとも 20GB の空き容量を確保してください。

ディスクの問題を防ぐ

1. 大規模なマルチタスク実行の前（ワークストリームが 10 個以上の場合）：

   df -h /tmp  # Check available space
   rm -rf /tmp/amplihack-workstreams/ws-*  # Clean old workstreams
   

2. PR のマージ後：

   python orchestrator.py --cleanup workstreams.json
   

3. 実行中の監視：

   watch -n 60 'du -sh /tmp/amplihack-workstreams && df -h /tmp'
   

トラブルシューティング

ログファイルが空の場合：プロセスは起動しましたが、すぐに終了しています。クローンの環境で amplihack パッケージをインポートできるか確認してください。

レシピが見つからない場合：クローンしたブランチに amplifier-bundle/recipes/ が存在することを確認してください。レシピの検出では、最初にこのディレクトリを確認します。

フォールバック：レシピモードが失敗した場合は、--mode classic を指定して再試行し、プロンプトベースの方法を使用してください。

実行中にディスク容量が不足した場合：空き容量が 10GB 未満になると、オーケストレーターが警告します。実行中にディスク容量がいっぱいになった場合は、実行中のワークストリームを停止してから、手動でクリーンアップしてください：rm -rf /tmp/amplihack-workstreams/ws-*