autonomous-orchestration

自律的なオーケストレーション

概要

Task tool を使って並行ワーカーエージェントを起動し、TaskOutput を使って進行状況を監視することで、複数のイシューにまたがる長時間の自律的な作業をオーケストレーションします。

基本原則： 真実の情報源は GitHub です。ワーカーは使い捨てです。状態は再起動後も保持されます。

開始時に宣言： 「autonomous-orchestration を使用して、[SCOPE] に取り組みます。これから自律的な操作を開始します。」

前提条件

• Task tool でワーカーを起動するための worker-dispatch スキル
• ワーカーの動作に関する worker-protocol スキル
• CI／WAKE の処理に関する ci-monitoring スキル
• 認証済みの GitHub CLI（gh）
• 設定済みの GitHub Project Board

並列実行モデル

Task tool を使って、ワーカーをバックグラウンドエージェントとして起動します。

Orchestrator
    │
    ├── Task(run_in_background: true) → Worker Agent #1 (task_id: aa93f22)
    ├── Task(run_in_background: true) → Worker Agent #2 (task_id: b51e54b)
    └── Task(run_in_background: true) → Worker Agent #3 (task_id: c72f3d1)

TaskOutput で進行状況を監視します。

TaskOutput(task_id: "aa93f22", block: false) → "Task is still running..."
TaskOutput(task_id: "b51e54b", block: false) → Completed with result
TaskOutput(task_id: "c72f3d1", block: false) → "Task is still running..."

重要： 真の並行実行を実現するには、すべてのワーカーを同じメッセージ内で起動してください。

状態管理

重要： 永続状態はすべて GitHub に保存されます。Task ID は一時的なセッション状態です。

状態ストア	目的	用途
Project Board のステータス	唯一の真実の情報源	Ready、In Progress、In Review、Blocked、Done
イシューのコメント	アクティビティログ	ワーカーの割り当て、進捗、逸脱
ラベル	系譜のみ	spawned-from:#N、depth:N、epic-*
MCP Memory	アクティブマーカーとタスク追跡	アクティブなオーケストレーションの検出、アクティブな task_ids
オーケストレーターのメモリ	一時的なセッション状態	監視用の issue# → task_id のマップ

参照： 状態の詳細な照会と更新については、reference/state-management.md を参照してください。

コンテキスト圧縮への対応

重要： オーケストレーションはループの途中でコンテキストが圧縮されても継続できなければなりません。

開始時：アクティブマーカーを書き込む

# Write to MCP Memory when orchestration starts
mcp__memory__create_entities([{
  "name": "ActiveOrchestration",
  "entityType": "Orchestration",
  "observations": [
    "Status: ACTIVE",
    "Scope: [MILESTONE/EPIC/unbounded]",
    "Tracking Issue: #[NUMBER]",
    "Started: [ISO_TIMESTAMP]",
    "Repository: [owner/repo]",
    "Phase: BOOTSTRAP|MAIN_LOOP",
    "Last Loop: [ISO_TIMESTAMP]"
  ]
}])

各ループ反復時：マーカーを更新する

mcp__memory__add_observations({
  "observations": [{
    "entityName": "ActiveOrchestration",
    "contents": ["Last Loop: [ISO_TIMESTAMP]", "Phase: MAIN_LOOP"]
  }]
})

完了時：マーカーを削除する

mcp__memory__delete_entities({
  "entityNames": ["ActiveOrchestration"]
})

セッション再開時（圧縮後）

セッション開始スキルが、アクティブなオーケストレーションを確認します。

# Check MCP Memory for active orchestration
ACTIVE=$(mcp__memory__open_nodes({"names": ["ActiveOrchestration"]}))

if [ -n "$ACTIVE" ]; then
  echo "⚠️ ACTIVE ORCHESTRATION DETECTED"
  echo "Scope: [from ACTIVE]"
  echo "Tracking: [from ACTIVE]"
  echo ""
  echo "Resuming orchestration loop..."
  # Invoke autonomous-orchestration skill to resume
fi

これにより： ループの途中でコンテキストが圧縮されても、次のセッションでアクティブなオーケストレーションが検出され、再開されます。

即時開始（ユーザーの同意があるものとします）

ユーザーからの自律的な操作の依頼は、同意を意味します。 追加の確認は不要です。

ユーザーが自律的な作業を依頼した場合：

1. スコープを特定する - ユーザーの依頼から、マイルストーン、エピック、特定のイシュー、または「すべて」を読み取ります
2. 実行の意図を伝える - これから行うことを簡潔に伝えます
3. 直ちに開始する - 追加の入力を待たずにオーケストレーションを開始します

## Starting Autonomous Operation

**Scope:** [MILESTONE/EPIC/ISSUES or "all open issues"]
**Workers:** Up to 5 parallel
**Mode:** Continuous until complete

Beginning work now...

「PROCEED」やその他の確認を求めてはいけません。 ユーザーは自律的な操作を依頼しており、それが確認にあたります。

スコープの自動検出

ユーザーがスコープを指定せずに自律的な操作を依頼した場合：

優先順位

1. ユーザーが指定したスコープ - ユーザーが特定のイシュー、エピック、またはマイルストーンに言及している場合
2. 緊急度／優先度の高い単独イシュー - priority:urgent または priority:high ラベルが付いており、エピックに属していないイシュー
3. エピック単位の順次作業 - エピックを順番に進め、各エピック内のすべてのイシューを完了する
4. 残りの単独イシュー - エピックに属していないその他のイシュー

detect_work_scope() {
  # 1. Check for urgent/high priority standalone issues first
  PRIORITY_ISSUES=$(gh issue list --state open \
    --label "priority:urgent,priority:high" \
    --json number,labels \
    --jq '[.[] | select(.labels | map(.name) | any(startswith("epic-")) | not)] | .[].number')

  if [ -n "$PRIORITY_ISSUES" ]; then
    echo "priority_standalone"
    echo "$PRIORITY_ISSUES"
    return
  fi

  # 2. Get epics in order (by creation date)
  EPICS=$(gh issue list --state open --label "type:epic" \
    --json number,title,createdAt \
    --jq 'sort_by(.createdAt) | .[].number')

  if [ -n "$EPICS" ]; then
    echo "epics"
    echo "$EPICS"
    return
  fi

  # 3. Fall back to all open issues
  ALL_ISSUES=$(gh issue list --state open --json number --jq '.[].number')
  echo "all_issues"
  echo "$ALL_ISSUES"
}

完了まで継続して実行

自律的な操作は、次の条件がすべて満たされるまで継続します。

• スコープ内に未解決のイシューが残っていない
• マージ待ちの未解決 PR が残っていない
• 「In Progress」または「In Review」ステータスのイシューが残っていない

次の場合も、操作は一時停止しません。

• 進捗の更新
• イシュー間の確認
• エピック間の切り替え
• ユーザーからの入力（致命的なエラーでブロックされた場合を除く）

PR 解決のブートストラップフェーズ

重要： 新しいワーカーを起動する前に、既存の未解決 PR をすべて解決してください。

ブートストラップの流れ： 未解決 PR を取得する（release/*、release-placeholder、do-not-merge を除外）→ 各 PR について、CI を確認する → レビューを確認する → 準備が整っていればマージする → その後、メインループを開始する

ブートストラップの実装

resolve_existing_prs() {
  echo "=== PR RESOLUTION BOOTSTRAP ==="

  # Get all open PRs, excluding release placeholders
  OPEN_PRS=$(gh pr list --json number,headRefName,labels \
    --jq '[.[] | select(
      (.headRefName | startswith("release/") | not) and
      (.labels | map(.name) | index("release-placeholder") | not)
    )] | .[].number')

  if [ -z "$OPEN_PRS" ]; then
    echo "No actionable PRs to resolve. Proceeding to main loop."
    return 0
  fi

  echo "Found PRs to resolve: $OPEN_PRS"

  for pr in $OPEN_PRS; do
    echo "Processing PR #$pr..."

    # Get CI status
    ci_status=$(gh pr checks "$pr" --json state --jq '.[].state' 2>/dev/null | sort -u)

    # Get linked issue
    ISSUE=$(gh pr view "$pr" --json body --jq '.body' | grep -oE 'Closes #[0-9]+' | grep -oE '[0-9]+' | head -1)

    if [ -z "$ISSUE" ]; then
      echo "  ⚠ No linked issue found, skipping"
      continue
    fi

    # Check if CI passed
    if echo "$ci_status" | grep -q "FAILURE"; then
      echo "  ❌ CI failing - triggering ci-monitoring for PR #$pr"
      # Invoke ci-monitoring skill to fix
      handle_ci_failure "$pr"
      continue
    fi

    if echo "$ci_status" | grep -q "PENDING"; then
      echo "  ⏳ CI pending for PR #$pr, will check in main loop"
      continue
    fi

    if echo "$ci_status" | grep -q "SUCCESS"; then
      # Verify review artifact
      REVIEW_EXISTS=$(gh api "/repos/$OWNER/$REPO/issues/$ISSUE/comments" \
        --jq '[.[] | select(.body | contains(""))] | length' 2>/dev/null || echo "0")

      if [ "$REVIEW_EXISTS" = "0" ]; then
        echo "  ⚠ No review artifact - requesting review for #$ISSUE"
        gh issue comment "$ISSUE" --body "## Review Required

PR #$pr has passing CI but no review artifact.

**Action needed:** Complete comprehensive-review and post artifact to this issue.

---
*Bootstrap phase - Orchestrator*"
        continue
      fi

      # All checks pass - merge
      echo "  ✅ Merging PR #$pr"
      gh pr merge "$pr" --squash --delete-branch
      mark_issue_done "$ISSUE"
    fi
  done

  echo "=== BOOTSTRAP COMPLETE ==="
}

リリースプレースホルダーの検出

次の PR は、ブートストラップの解決対象から除外されます。

条件	例
ブランチ名が release/ で始まる	release/v2.0.0、release/2025-01
release-placeholder ラベルが付いている	手動での除外
do-not-merge ラベルが付いている	明示的な保留

オーケストレーションループ

メインループの流れ： ワーカーを監視（TaskOutput）＋ CI／PR を確認＋ワーカーを起動（Task）→ 状態を評価（完了／スリープ／継続）

ループの手順

1. アクティブなワーカーを監視 - アクティブな各 task_id に対して TaskOutput(block: false) を使用します
2. 完了したワーカーに対応 - GitHub で PR／完了状況を確認します
3. CI／PR を確認 - マージ可能かを監視し、レビュー成果物を検証します
4. グリーンの PR をマージ - CI が通過した PR は、すべて直ちにマージします
5. ワーカーを起動 - Task(run_in_background: true) を使用して、最大 5 つのワーカーを並行して起動します
6. 状態を評価 - 次のアクション（継続、スリープ、完了）を判断します
7. 短く一時停止 - 反復の間隔を 30 秒空けます

TaskOutput によるワーカーの監視

各ループの反復で、すべてのアクティブなワーカーを確認します。

## Monitor Active Workers

For each task_id in active_workers:
  TaskOutput(task_id: "[ID]", block: false, timeout: 1000)

Interpret results:
- "Task is still running..." → Continue monitoring
- Completed → Check GitHub for PR, update project board, remove from active list
- Error → Handle failure, potentially spawn replacement

並列ワーカーの起動

複数のワーカーを 1 つのメッセージで起動し、並行して実行します。

## Dispatch Workers

1. Count available slots: 5 - len(active_workers)
2. Get Ready issues from project board
3. For each issue to dispatch:

Task(
  description: "Issue #123 worker",
  prompt: [WORKER_PROMPT],
  subagent_type: "general-purpose",
  run_in_background: true
)

4. Store returned task_id → issue mapping

重要：グリーンの PR は直ちにマージする

ループの反復ごとに、CI を通過した PR を確認してマージする必要があります。

# In each loop iteration
for pr in $(gh pr list --json number,statusCheckRollup --jq '.[] | select(.statusCheckRollup | all(.conclusion == "SUCCESS")) | .number'); do
  # Check for do-not-merge label
  if ! gh pr view "$pr" --json labels --jq '.labels[].name' | grep -q "do-not-merge"; then
    echo "Merging PR #$pr (CI passed)"
    gh pr merge "$pr" --squash --delete-branch

    # Get linked issue and mark done
    ISSUE=$(gh pr view "$pr" --json body --jq '.body' | grep -oE 'Closes #[0-9]+' | grep -oE '[0-9]+' | head -1)
    if [ -n "$ISSUE" ]; then
      # Update project board status to Done
      mark_issue_done "$ISSUE"
    fi
  fi
done

次のことはしないでください。

• 「PR のマージ準備ができています」と報告して停止する
• ユーザーがマージを依頼するまで待つ
• 完了した作業を要約して次のステップを尋ねる

スコープが完了するまでループを継続します。グリーンの PR は直ちにマージします。

スコープの種類

マイルストーン

gh issue list --milestone "v1.0.0" --state open --json number --jq '.[].number'

エピック

gh issue list --label "epic-dark-mode" --state open --json number --jq '.[].number'

制限なし（すべてのオープンな Issue）

gh issue list --state open --json number --jq '.[].number'

「UNBOUNDED」の確認を求めないでください。 ユーザーの依頼は同意を意味します。

失敗への対応

失敗したワーカーが、ただちにブロック扱いになることはありません。

Attempt 1 → Research → Attempt 2 → Research → Attempt 3 → Research → Attempt 4 → BLOCKED

Issue がブロック扱いになるのは、調査サイクルを 3 回以上実施した後だけです。

参照： 調査サイクルの実装については reference/failure-recovery.md を参照してください。

ブロックの判定

Issue がブロック扱いになるのは、次の条件を満たす場合に限られます。

• 複数回（3 回以上）の調査サイクルを完了している
• 調査の結果、「外部からの入力なしでは不可能」と結論づけられている
• 例：認証情報の不足、人間による判断が必要、外部サービスの停止

スリープ／復帰

スリープへの移行

次の場合、オーケストレーションはスリープします。

• すべての Issue がブロック中またはレビュー中である
• 外部イベントなしでは進められる作業がない

状態は GitHub の追跡用 Issue に投稿されます（クラッシュ後も保持されます）。

復帰の仕組み

• SessionStart フック - 新しい Claude セッションで CI の状態を確認します
• 手動 - claude --resume [SESSION_ID]

チェックリスト

オーケストレーションを開始する前に：

• スコープを特定済み（明示的または自動検出）
• GitHub CLI の認証済み（gh auth status）
• orchestration-tracking ラベル付きの追跡用 Issue が存在する
• Status フィールドを含むプロジェクトボードが設定済み
• アクティブマーカーが MCP Memory に書き込まれている

ブートストラップフェーズ：

• 既存のオープンな PR を検出済み
• リリースプレースホルダーを除外済み（release/*、release-placeholder、do-not-merge ラベル）
• 各 PR の CI 状態を確認済み
• マージ前にレビュー成果物を検証済み
• PR をマージ済み、または要対応としてマーク済み
• ワーカーの起動前にブートストラップを完了済み

オーケストレーション中：

• Task(run_in_background: true) を使用してワーカーを起動済み
• 各ワーカーのタスク ID を保存済み（issue# → task_id の対応付け）
• TaskOutput(block: false) でワーカーの状態を監視済み
• 完了したワーカーを検出し、対応済み
• プロジェクトボードの状態を更新済み（In Progress、In Review、Done）
• オープンな PR の CI 状態を監視済み
• グリーンの PR を直ちにマージ済み
• PR のマージ前にレビュー成果物を検証済み
• 失敗したワーカーに対して調査サイクルを開始済み
• 引き継ぎ時に代替ワーカーを起動済み
• CI の待機のみになった場合、スリープに移行済み
• 各ループで逸脱の解決状況を確認済み
• 追跡用 Issue に状態を投稿済み

レビューの徹底

重大： オーケストレーターはレビューの遵守状況を検証します。

1. PR のマージ前：

   • レビュー成果物が Issue のコメントに存在する
   • レビューのステータスが COMPLETE である
   • 未対応の指摘が 0 件である

2. 子 Issue（後回しにした指摘から作成）：

   • 完全な issue-driven-development プロセスに従う
   • 独自のコードレビューを受ける
   • spawned-from:#N ラベルで追跡する

3. 逸脱への対応：

   • プロジェクトボードで親のステータスを Blocked に設定する
   • すべての子 Issue がクローズされた場合にのみ再開する

統合

このスキルは以下と連携します。

スキル	目的
worker-dispatch	ワーカーの起動
worker-protocol	ワーカーの動作
worker-handover	コンテキストの受け渡し
ci-monitoring	CI と WAKE の処理
research-after-failure	調査サイクル
issue-driven-development	ワーカーが従うプロセス
comprehensive-review	PR の前にワーカーが完了する必要があるレビュー
project-board-enforcement	すべての状態の照会と更新

参照ファイル

• reference/state-management.md - 状態の照会、更新、逸脱への対応
• reference/loop-implementation.md - ループの完全なコードとヘルパー
• reference/failure-recovery.md - 調査サイクル、ブロック時の処理、SLEEP/WAKE