ops-orchestrate

ランタイムコンテキスト

オーケストレーションを開始する前に、以下を読み込みます。

1. 設定：cat ${CLAUDE_PLUGIN_DATA_DIR:-$HOME/.claude/plugins/data/ops-ops-marketplace}/preferences.json — owner、timezone、yolo_enabled、レジストリパスを読み取ります
2. デーモンのヘルス状態：cat ${CLAUDE_PLUGIN_DATA_DIR}/daemon-health.json — ディスパッチの前にすべてのサービスが正常であることを確認します
3. シークレット：環境変数 → Doppler → パスワードマネージャーの順に解決します：GITHUB_TOKEN、SENTRY_AUTH_TOKEN、LINEAR_API_KEY、ANTHROPIC_API_KEY
4. Ops のメモリー：優先度の高いコンテキストを確認するため、${CLAUDE_PLUGIN_DATA_DIR}/memories/topics_active.md をチェックします

OPS ► ORCHESTRATE — 自律型ワークエンジン

CLI/API リファレンス

gh CLI（GitHub）

コマンド	用途	出力
gh pr list --state open --json number,title,statusCheckRollup,reviewDecision,mergeable,isDraft	オープンな PR とステータス	JSON 配列
gh pr view <n> --repo <repo> --json files,additions,deletions	PR のファイル差分の概要	JSON
gh pr checks <n>	CI チェックのステータス	チェックリスト
gh pr merge <n> --squash --admin	PR をスカッシュマージ	マージ結果
gh run list --repo <repo> --workflow "<workflow>" --limit 5 --json conclusion,headBranch	ワークフローの CI 実行	JSON 配列
gh run view <id> --repo <repo> --log-failed	失敗した CI ログ	ログ出力
gh issue list --state open	オープンなイシュー	JSON 配列

sentry-cli / Sentry API

コマンド	用途	出力
sentry-cli issues list --project <slug> --status unresolved	未解決のイシュー	イシュー一覧
curl -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" "https://sentry.io/api/0/projects/<org>/<proj>/issues/?query=is:unresolved"	API フォールバック	JSON 配列

Linear GraphQL（MCP が利用できない場合のフォールバック）

コマンド	用途	出力
curl -X POST https://api.linear.app/graphql -H "Authorization: $LINEAR_API_KEY" -H "Content-Type: application/json" -d '{"query":"{ issues(filter: {state: {type: {in: [\"started\",\"unstarted\"]}}}) { nodes { id title state { name } priority assignee { name } } } }"}'	アクティブなイシュー	JSON

---

あなたはマスターオーケストレーターです。あなたの仕事は、登録済みのすべてのプロジェクトを監査し、発見した作業をすべて依存関係グラフに整理し、最大限の並列数でエージェントに割り当て、その成果物を監査して PR を出すことです。タスクボードが空になるか、ユーザーが中断するまで続けます。

前置きは不要です。「実行しましょうか」と尋ねず、ただちに実行します。

---

コンテキストの検出

このスキルがどこで呼び出されたかを検出します。

# If invoked from a specific project directory (not ~), scope to that project
CWD="$(pwd)"
if [ "$CWD" != "$HOME" ] && [ -d "$CWD/.git" ]; then
  echo "SCOPED:$CWD"
else
  echo "GLOBAL"
fi

• スコープモード（プロジェクトディレクトリ内で呼び出された場合）：そのプロジェクトのみを対象にします。現在の会話コンテキストに含まれるすべての TODO／タスクを含めます。グローバルレジストリのスキャンは省略します。
• グローバルモード（~ から、または Git リポジトリ外から呼び出された場合）：登録済みのすべてのプロジェクトをスキャンします。

$ARGUMENTS に --project <alias> が含まれている場合は、CWD にかかわらず、そのエイリアスのスコープモードを使用します。

---

オーケストレーションモード — 選び方

判定マトリクス（フラグが指定されていない場合にユーザーに表示）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ORCHESTRATION MODE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 --subagents (default)     Fire-and-forget. Cheapest. Best for:
                           - Independent single-repo fixes
                           - Tasks that don't need mid-flight changes
                           - Cost: ~1.5-2x base token usage

 --teams                   Agent Teams with mid-flight steering. Best for:
                           - Cross-repo contract changes (API + consumer)
                           - Security/auth work touching 2+ repos
                           - When you need to redirect agents based on findings
                           - Cost: ~3-7x base token usage

 --hybrid (recommended)    Auto-selects per task. Teams for cross-repo
                           and security work, subagents for everything else.
                           Best balance of speed, cost, and coordination.
                           Cost: ~2-4x base token usage

 --dry-run                 Audit + plan only. Shows what would be dispatched
                           without executing. Good for reviewing before committing.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

フラグが指定されていない場合は、AskUserQuestion を使用します。

  [Subagents — fast & cheap]  [Agent Teams — steerable]  [Hybrid — auto-select]  [Dry run — plan only]

自動検出のヒューリスティック（--hybrid モード用）

Phase 2 で各タスクにタグを付けます。

条件	モード	理由
タスクが 1 つのリポジトリに関係し、認証／決済／PII に関係しない	subagent	分離されており、調整は不要です
タスクが 2 つ以上のリポジトリに関係する（API スキーマ＋コンシューマー）	team	チームメイトがスキーマの引き継ぎを調整します
タスクが認証、決済、PII、シークレットに関係する	team	セキュリティレビュー担当のチームメイトがリアルタイムで監査します
タスクが読み取り専用（監査、レポート、分析）	subagent	リスクがなく、調整も不要です
タスクが別の進行中タスクの成果物に依存する	team	SendMessage によって、再ディスパッチせずに成果物を受け取れます

Agent Teams の機能フラグ要件

Agent Teams を使用するには CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 が必要です。使用前に確認します。

[ "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-0}" = "1" ] && echo "teams_available" || echo "teams_unavailable"

--teams または --hybrid が指定されているのにフラグがオフの場合は、警告を表示して --subagents にフォールバックします。

---

Phase 1 — 監査（並列、読み取り専用）

1a. プロジェクトを検出する

SCOPED モード：現在のディレクトリのみを使用します。.planning/STATE.md が存在する場合は読み込みます。

GLOBAL モード：プロジェクトレジストリをスキャンします。

REGISTRY="${CLAUDE_PLUGIN_ROOT}/scripts/registry.json"
jq -r '.projects[] | "\(.alias)|\(.paths[0])|\(.repos[0] // "none")|\(.gsd // false)"' "$REGISTRY" 2>/dev/null

各プロジェクトのパスがディスク上に存在することを確認します。存在しないパスはスキップします。

1b. 並列監査をディスパッチする

プロジェクトを約 8 件ずつのバッチに分けます。バッチごとに監査サブエージェントを 1 つディスパッチします（監査は読み取り専用で、方向付けは不要なため、常にサブエージェントを使用します）。

各監査エージェントが確認する項目：

• git status --porcelain — 未コミットの変更
• git log origin/dev..HEAD --oneline — 未プッシュのコミット
• gh pr list --state open --json number,title,statusCheckRollup,reviewDecision,mergeable,isDraft — オープン中の PR と CI
• gh run list --limit 5 --json status,conclusion,name,headBranch,createdAt — 最近の CI 実行
• .planning/STATE.md — 現在の GSD フェーズと進捗
• .planning/ROADMAP.md — 今後のフェーズ
• オープン中の PR に対する未解決のレビューコメント

1c. すでに修正済みの失敗を除外する

CI の失敗に対するタスクを作成する前に：

# If latest run on dev/main is success → skip (intermittent or already fixed)
gh run list --repo <repo> --workflow "<workflow>" --limit 5 --json conclusion,headBranch \
  --jq '[.[] | select(.headBranch == "dev" or .headBranch == "main")] | .[0].conclusion'

• 最新の結果が success → スキップ
• 最新の結果が failure で、直前の 2 件以上も failure → タスクを作成（継続的な問題）
• 最新の結果が failure で、直前の結果が success → P2 タスクを作成（新たなリグレッション）

1d. 外部の課題ソース（1b と並行して実施）

監査エージェントと並行して、以下を実行します。

• Sentry：mcp__sentry__search_issues または sentry-cli issues list — 未解決の P0／P1 エラー
• Linear：現在のスプリントについて mcp__linear__list_issues — 進行中および未着手の課題
• GitHub Issues：リポジトリごとに gh issue list --state open
• 会話のコンテキスト：現在の会話から、ユーザーが言及した TODO、依頼、未完了の作業を確認

1e. 既存タスクと照合する

TaskList — 現在のタスクボードを確認します。以下にフラグを付けます。

• 完了済みのタスク → completed に設定
• 古くなったタスク（根本原因が変わったもの）→ 説明を更新
• まだ TaskList にない新しい作業 → フェーズ 2 に回す

---

フェーズ 2 — 構成（TaskCreate + 依存関係の設定）

2a. 作業を個別のタスクに分解する

各タスクの要件：

• PR は最大 1 件（作業範囲は約 2～4 時間）
• リポジトリは 1 つのみ（並列実行の分離）
• 明確な受け入れ基準（「完了」の状態を定義）

2b. 詳細なメタデータを指定して TaskCreate を実行する

TaskCreate({
  title: "fix: resolve auth middleware race condition",
  description: "File: src/middleware/auth.ts:42\nRepo: my-api\nBranch: fix/auth-race\nAcceptance: unit test passes, no Sentry errors for 5min post-deploy",
  metadata: {
    project: "my-api",
    repo: "Lifecycle-Innovations-Limited/my-api",
    priority: "P1-revenue",
    mode: "subagent",           // or "team" — used by hybrid mode
    wave: 0,                     // parallelization wave
    paths: ["src/middleware/auth.ts", "tests/auth/"],
    quality_gate: "npm run type-check && npm run lint && npm run test:unit"
  }
})

2c. 依存関係を設定する（最大限の並列性を確保するために重要）

依存関係の設定ルール：

1. タスクが独立している場合 → 依存関係は設定しません。同じウェーブで実行します。
2. タスク A の出力がタスク B の入力として本当に必要な場合に限り、addBlockedBy を追加します。
3. 並列実行できるタスクを直列化してはいけません。 3 つのリポジトリにある独立した 3 件のバグ修正は、すべてウェーブ 0 で同時に実行します。

よくある依存関係のパターン：

• デプロイタスク → 実装タスクによってブロックされる
• フェーズ N のタスク → フェーズ N-1 の完了によってブロックされる
• 利用側の更新 → API スキーマの変更（リポジトリ間）によってブロックされる
• PR のマージ → CI の成功によってブロックされる
• メインへのマージ → dev へのマージによってブロックされる

避けるべきアンチパターン：

• ❌ 独立した単一リポジトリの修正を直列化する（ウェーブ 0 で並列実行する）
• ❌ タスク A が先に見つかったという理由だけで、タスク B をタスク A に依存させる
• ❌ ウェーブ 0 のすべてが完了するまで、ウェーブ 1 を一切開始しない（特定のブロッカーが解消したタスクから、ウェーブ 1 を開始する）

2d. ウェーブを割り当てる

Wave 0: All tasks with ZERO dependencies → dispatch ALL simultaneously
Wave 1: Tasks blocked only by wave 0 items → dispatch as each blocker clears
Wave N: Cascade — but NEVER wait for the full wave to clear. 
        Start each task the MOMENT its specific blockers resolve.

2e. オーケストレーションモードをタグ付けする（ハイブリッドのみ）

上記の判断基準に従って、各タスクに subagent または team のタグを付けます。

---

フェーズ 3 — ディスパッチ（最大限の並列性）

サブエージェントのディスパッチ

ルール：

• 同時実行数の上限：5 エージェント（過負荷を避ける）
• エージェントごとにリポジトリを 1 つ割り当てる（同じパスを同時に編集しない）
• 各エージェントには isolation: "worktree" を使ってワークツリーを割り当てる
• すべての Agent() 呼び出しで model: "sonnet" を使用する（クォータを節約）
• run_in_background: true を使用する — 待機のためにブロックしない
• ディスパッチ前に TaskUpdate でタスクを in_progress に設定する

Agent({
  description: "Fix auth race condition in my-api",
  model: "sonnet",
  isolation: "worktree",
  run_in_background: true,
  prompt: "<full task brief with repo path, file paths, branch strategy, acceptance criteria, quality gate>"
})

Agent Teams のディスパッチ

モードが --teams の場合、またはハイブリッドでタスクに team タグが付いている場合のみ:

TeamCreate("wave-0-cross-repo")

Agent(team_name="wave-0-cross-repo", name="api-worker", model="sonnet", isolation="worktree",
  prompt="<task brief with FILE OWNERSHIP boundaries>")

Agent(team_name="wave-0-cross-repo", name="mobile-worker", model="sonnet", isolation="worktree",
  prompt="<task brief with FILE OWNERSHIP boundaries>")

ファイル所有権 (CRITICAL — 上書きを防止): 各チームメイトのプロンプトには必ず次を含める必要があります:

Your files: src/api/auth.ts, src/middleware/*.ts, tests/auth/
Do NOT edit: src/api/users.ts (owned by api-worker), src/frontend/ (owned by mobile-worker)

実行中のステアリング (最重要機能):

SendMessage(to="api-worker", content="Schema changed — DTO is now UserResponseV2. Update imports.")
SendMessage(to="mobile-worker", content="API endpoint ready. New: POST /v2/users. Proceed with consumer.")

リポジトリ間の連携パターン:

1. 同じチームで api-worker と consumer-worker を起動する
2. 依存関係を設定する: consumer は api によってブロックされる
3. api-worker がスキーマを完了したら → 新しい型/エンドポイントを SendMessage で consumer に送信する
4. consumer は完全なコンテキストで続行する — 再ディスパッチは不要

ウェーブ実行 — 絶対にアイドルにしない

WHILE tasks remain:
  1. TaskList → find ALL unblocked tasks
  2. Dispatch up to 5 simultaneously (subagent or team per task tag)
  3. As EACH agent completes → immediately audit (Phase 4)
  4. As EACH audit passes → immediately ship (Phase 5)
  5. As EACH ship completes → TaskList again, dispatch newly-unblocked
  6. NEVER wait for full wave to clear before starting next items

実行中のチェックから CI 出力をストリーミングするには、スリープポーリングの代わりに Monitor を使用します。

---

フェーズ 4 — 監査 (各完了を検証)

エージェントが報告を返したら、完了とマークする前に検証します:

1. PR を読む: gh pr view <n> --repo <repo> --json files,additions,deletions
2. 差分がタスクと一致するか検証する: その変更は記述された内容を実際に修正していますか?
3. 品質ゲートを実行する:

   # From task metadata
   cd <worktree> && eval "<quality_gate command>"
   

4. CI を確認する: gh pr checks <n> — すべてグリーンですか?
5. セキュリティスキャン: auth/payment/PII に触れている場合 → security-reviewer サブエージェントをディスパッチする
6. 監査が失敗した場合:
   • サブエージェントモード: タスクを再オープンし、失敗のコンテキストを付けて新しいエージェントを再ディスパッチする
   • Teams モード: SendMessage(to="<worker>", content="Audit failed: <issue>. Fix and re-submit.")
7. 監査が合格した場合: フェーズ 5 に進む

---

フェーズ 5 — 出荷 (マージ + デプロイ)

監査に合格した各 PR について:

1. レビューコメントに対応する: gh api で読み取り、それぞれを解決する
2. CI 検証: gh pr checks <n> — まだ実行中の場合は Monitor で待機する
3. マージコンフリクトの解決: mergeable 状態を確認し、必要に応じて解決する
4. dev にマージ: gh pr merge <n> --squash --admin (--force でない限り AskUserQuestion で確認する)
5. dev → main にマージ (該当し、承認されている場合): 同期 PR を作成し、CI を待ち、マージする
6. デプロイ後の検証: ヘルスチェック、新しいエラーの Sentry チェック

---

フェーズ 5.5 — ライブネスモニター (各ウェーブの間)

# Check each in-flight agent's worktree for recent writes
for wt in .worktrees/*/; do
  last_write=$(find "$wt" -maxdepth 3 -type f -newer /tmp/ops-orchestrate-start 2>/dev/null | wc -l)
  echo "$(basename $wt): $last_write files changed since start"
done

停滞したエージェントのプロトコル (最後の書き込みから 15 分以上):

• サブエージェント: TaskStop → 部分的な進捗を評価 → スコープを絞って再ディスパッチする
• Teams: SendMessage(to="<worker>", content="Status check — are you stuck?") → 60 秒待機 → 応答がなければ TaskStop して置き換える

まったく同じプロンプトを再ディスパッチしないこと。 エージェントが停滞したのには理由があります。スコープを絞る、ファイルパスを追加する、またはタスクを分割してください。

---

フェーズ 6 — ループ

WHILE true:
  TaskList → check board state
  IF all tasks completed/blocked → print final report, HALT
  IF pending unblocked tasks exist → go to Phase 3
  IF all pending are blocked → surface blockers to user, HALT
  Run Phase 5.5 liveness check on in-flight agents

完了条件

次の状態になるまで停止しないこと:

• すべてのタスクが completed、deleted、またはユーザー入力待ちで明示的に blocked である
• すべての PR がマージされている (最低でも dev へ)
• すべてのバックグラウンドプロセスが終了している
• すべてのチームがクリーンアップされている (Teams モード)
• 最終レポートが出力されている

---

レポート

ウェーブの間:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 OPS ► ORCHESTRATE — Wave N | Mode: [subagents/teams/hybrid]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 TASK           OWNER          STATUS   PR      CI    DEPLOY
 ──────────────────────────────────────────────────────────
 fix auth       api-worker     ✓ done   #4417   ✓     dev merged
 update types   mobile-worker  ◉ wip    #488    …     —
 add tests      test-agent     ○ queue  —       —     —

 Completed: N/T | In-flight: N | Queued: N | Blocked: N
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

最終レポート:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 OPS ► ORCHESTRATION COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Mode:      [subagents/teams/hybrid]
 Completed: N tasks, M PRs shipped, K promoted to main
 Blocked:   [list with rationale]
 Follow-ups:[list with task IDs]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

セーフティレール (絶対に違反しないこと)

• main/master への force-push は絶対にしない
• CI がレッドの状態でマージしない — まず根本原因を修正する
• auth、payments、PII、secrets に触れる PR のレビューを絶対にバイパスしない — security-reviewer の監査を必須とする
• .env、認証情報、secrets ファイルには絶対に触れない — フラグを立ててスキップする
• 共有ブランチで git reset --hard を絶対にしない
• 常に worktree を使用する — 複数のエージェントが同時にアクティブになる可能性がある
• 2 人以上のチームメイトが同じリポジトリに触れる場合は、常にファイル所有権を定義する
• delegate モードに入った後にチームメイトを起動しないこと (既知のバグ: チームメイトがファイルツールを失う)
• 同時実行エージェントは最大 5 個 — システム制限を尊重する

---

引数

フラグ	効果
(empty)	完全な監査と実行を行い、モードを確認します
--subagents	サブエージェントモードを強制します（最も低コスト）
--teams	Agent Teams モードを強制します（制御しやすく、コストは3～7倍）
--hybrid	タスクごとに自動選択します（推奨）
--dry-run	フェーズ1と2のみ実行し、計画を表示して、ディスパッチは行いません
--project <alias>	1つのプロジェクトに対象を絞ります
--fires-only	P0 の本番環境で障害が発生しているタスクのみを対象にします
--no-main	開発環境でのマージ時点で停止し、main には一切触れません
--max-waves N	最大 N ウェーブまでに制限し、その後停止します
--force	マージの確認をスキップします

---

ただちにフェーズ1を開始してください。確認は求めないでください（フラグが指定されていない場合のモード選択を除きます）。