task-orchestrator

タスクオーケストレーター

自己修復型の監視機能を備えた、tmux + Codex によるマルチエージェントビルドの自律的なオーケストレーションです。

エンジニアリングの原則については、このスキルと併せて senior-engineering スキルを読み込んでください。

安全上の境界

• 依存関係が解決するまでは、書き込み範囲が重複するタスクに対して並列ワーカーを起動しないでください。
• 人間によるレビューが必要な場合、ブランチのプッシュや作業のマージを行ったり、推測に基づいて自己修復したりしないでください。
• マニフェスト、ログ、プロンプト、tmux のペインキャプチャにシークレットを保存しないでください。
• 失敗するタスクの再試行を無期限に続けないでください。上限回数まで再試行したら停止し、ブロッカーを報告してください。

主な概念

1. タスクマニフェスト

すべてのタスク、その依存関係、変更対象ファイル、ステータスを定義する JSON ファイルです。

{
  "project": "project-name",
  "repo": "owner/repo",
  "workdir": "/path/to/worktrees",
  "created": "2026-01-17T00:00:00Z",
  "model": "gpt-5.2-codex",
  "modelTier": "high",
  "phases": [
    {
      "name": "Phase 1: Critical",
      "tasks": [
        {
          "id": "t1",
          "issue": 1,
          "title": "Fix X",
          "files": ["src/foo.js"],
          "dependsOn": [],
          "status": "pending",
          "worktree": null,
          "tmuxSession": null,
          "startedAt": null,
          "lastProgress": null,
          "completedAt": null,
          "prNumber": null
        }
      ]
    }
  ]
}

2. 依存関係のルール

• 同じファイル = 順次実行 — 同じファイルを変更するタスクは、順番に実行するか、まとめてマージする必要があります
• 異なるファイル = 並列実行 — 独立したタスクは同時に実行できます
• 明示的な依存関係 = 待機 — dependsOn 配列によって実行順序が強制されます
• フェーズゲート — 次のフェーズは、現在のフェーズが完了するまで待機します

3. 実行モデル

• 各タスクには専用の git worktree（分離されたブランチ）が割り当てられます
• 各タスクは専用の tmux セッションで実行されます
• 自律実行には Codex with --yolo を使用します
• モデル：GPT-5.2-codex high（設定可能）

---

セットアップコマンド

オーケストレーションを初期化する

# 1. Create working directory
WORKDIR="${TMPDIR:-/tmp}/orchestrator-$(date +%s)"
mkdir -p "$WORKDIR"

# 2. Clone repo for worktrees
git clone https://github.com/OWNER/REPO.git "$WORKDIR/repo"
cd "$WORKDIR/repo"

# 3. Create tmux socket
SOCKET="$WORKDIR/orchestrator.sock"

# 4. Initialize manifest
cat > "$WORKDIR/manifest.json" << 'EOF'
{
  "project": "PROJECT_NAME",
  "repo": "OWNER/REPO",
  "workdir": "WORKDIR_PATH",
  "socket": "SOCKET_PATH",
  "created": "TIMESTAMP",
  "model": "gpt-5.2-codex",
  "modelTier": "high",
  "phases": []
}
EOF

GitHub Issue を分析して依存関係を確認する

# Fetch all open issues
gh issue list --repo OWNER/REPO --state open --json number,title,body,labels > issues.json

# Group by files mentioned in issue body
# Tasks touching same files should serialize

Worktree を作成する

# For each task, create isolated worktree
cd "$WORKDIR/repo"
git worktree add -b fix/issue-N "$WORKDIR/task-tN" main

Tmux セッションを起動する

SOCKET="$WORKDIR/orchestrator.sock"

# Create session for task
tmux -S "$SOCKET" new-session -d -s "task-tN"

# Launch Codex (uses gpt-5.2-codex with reasoning_effort=high from ~/.codex/config.toml)
# Note: Model config is in ~/.codex/config.toml, not CLI flag
tmux -S "$SOCKET" send-keys -t "task-tN" \
  "cd $WORKDIR/task-tN && codex --yolo 'Fix issue #N: DESCRIPTION. Run tests, commit with good message, push to origin.'" Enter

---

監視と自己修復

進捗確認スクリプト

#!/bin/bash
# check_progress.sh - Run via heartbeat

WORKDIR="$1"
SOCKET="$WORKDIR/orchestrator.sock"
MANIFEST="$WORKDIR/manifest.json"
STALL_THRESHOLD_MINS=20

check_session() {
  local session="$1"
  local task_id="$2"
  
  # Capture recent output
  local output=$(tmux -S "$SOCKET" capture-pane -p -t "$session" -S -50 2>/dev/null)
  
  # Check for completion indicators
  if echo "$output" | grep -qE "(All tests passed|Successfully pushed|❯ $)"; then
    echo "DONE:$task_id"
    return 0
  fi
  
  # Check for errors
  if echo "$output" | grep -qiE "(error:|failed:|FATAL|panic)"; then
    echo "ERROR:$task_id"
    return 1
  fi
  
  # Check for stall (prompt waiting for input)
  if echo "$output" | grep -qE "(\? |Continue\?|y/n|Press any key)"; then
    echo "STUCK:$task_id:waiting_for_input"
    return 2
  fi
  
  echo "RUNNING:$task_id"
  return 0
}

# Check all active sessions
for session in $(tmux -S "$SOCKET" list-sessions -F "#{session_name}" 2>/dev/null); do
  check_session "$session" "$session"
done

自己修復アクション

タスクが停止している場合、オーケストレーターは次の対応を行います。

1. 入力待ち → 適切な応答を送信する

   tmux -S "$SOCKET" send-keys -t "$session" "y" Enter
   

2. エラー／失敗 → ログを取得して分析し、修正を加えて再試行する

   # Capture error context
   tmux -S "$SOCKET" capture-pane -p -t "$session" -S -100 > "$WORKDIR/logs/$task_id-error.log"
   
   # Kill and restart with error context
   tmux -S "$SOCKET" kill-session -t "$session"
   tmux -S "$SOCKET" new-session -d -s "$session"
   tmux -S "$SOCKET" send-keys -t "$session" \
     "cd $WORKDIR/$task_id && codex --model gpt-5.2-codex-high --yolo 'Previous attempt failed with: $(cat error.log | tail -20). Fix the issue and retry.'" Enter
   

3. 20 分以上進捗がない → 促すか、再起動する

   # Check git log for recent commits
   cd "$WORKDIR/$task_id"
   LAST_COMMIT=$(git log -1 --format="%ar" 2>/dev/null)
   
   # If no commits in threshold, restart
   

ハートビート Cron の設定

# Add to cron (every 15 minutes)
cron action:add job:{
  "label": "orchestrator-heartbeat",
  "schedule": "*/15 * * * *",
  "prompt": "Check orchestration progress at WORKDIR. Read manifest, check all tmux sessions, self-heal any stuck tasks, advance to next phase if current is complete. Do NOT ping human - fix issues yourself."
}

---

ワークフロー：オーケストレーションの全工程

ステップ 1：分析と計画

# 1. Fetch issues
gh issue list --repo OWNER/REPO --state open --json number,title,body > /tmp/issues.json

# 2. Analyze for dependencies (files mentioned, explicit deps)
# Group into phases:
# - Phase 1: Critical/blocking issues (no deps)
# - Phase 2: High priority (may depend on Phase 1)
# - Phase 3: Medium/low (depends on earlier phases)

# 3. Within each phase, identify:
# - Parallel batch: Different files, no deps → run simultaneously
# - Serial batch: Same files or explicit deps → run in order

ステップ 2：マニフェストを作成する

すべてのタスク、依存関係、ファイルの対応関係を記載した manifest.json を作成します。

ステップ 3：フェーズ 1 を起動する

# Create worktrees for Phase 1 tasks
for task in phase1_tasks; do
  git worktree add -b "fix/issue-$issue" "$WORKDIR/task-$id" main
done

# Launch tmux sessions
for task in phase1_parallel_batch; do
  tmux -S "$SOCKET" new-session -d -s "task-$id"
  tmux -S "$SOCKET" send-keys -t "task-$id" \
    "cd $WORKDIR/task-$id && codex --model gpt-5.2-codex-high --yolo '$PROMPT'" Enter
done

ステップ 4：監視と自己修復

ハートビートは 15 分ごとに次を確認します。

1. すべてのセッションをポーリングする
2. 進捗に合わせてマニフェストを更新する
3. 停止しているタスクを自己修復する
4. フェーズ N のタスクがすべて完了したら、フェーズ N+1 を起動する

ステップ 5：PR を作成する

# When task completes successfully
cd "$WORKDIR/task-$id"
git push -u origin "fix/issue-$issue"
gh pr create --repo OWNER/REPO \
  --head "fix/issue-$issue" \
  --title "fix: Issue #$issue - $TITLE" \
  --body "Closes #$issue

## Changes
[Auto-generated by Codex orchestrator]

## Testing
- [ ] Unit tests pass
- [ ] Manual verification"

ステップ 6：クリーンアップする

# After all PRs merged or work complete
tmux -S "$SOCKET" kill-server
cd "$WORKDIR/repo"
for task in all_tasks; do
  git worktree remove "$WORKDIR/task-$id" --force
done
rm -rf "$WORKDIR"

---

マニフェストのステータス値

ステータス	意味
pending	まだ開始していません
blocked	依存タスクの完了待ちです
running	Codex セッションが実行中です
stuck	介入が必要です（自動修復）
error	失敗しました。再試行が必要です
complete	完了し、PR を作成できます
pr_open	PR が作成されています
merged	PR がマージされています

---

例：セキュリティフレームワークのオーケストレーション

{
  "project": "nuri-security-framework",
  "repo": "jdrhyne/nuri-security-framework",
  "phases": [
    {
      "name": "Phase 1: Critical",
      "tasks": [
        {"id": "t1", "issue": 1, "files": ["ceo_root_manager.js"], "dependsOn": []},
        {"id": "t2", "issue": 2, "files": ["ceo_root_manager.js"], "dependsOn": ["t1"]},
        {"id": "t3", "issue": 3, "files": ["workspace_validator.js"], "dependsOn": []}
      ]
    },
    {
      "name": "Phase 2: High",
      "tasks": [
        {"id": "t4", "issue": 4, "files": ["kill_switch.js", "container_executor.js"], "dependsOn": []},
        {"id": "t5", "issue": 5, "files": ["kill_switch.js"], "dependsOn": ["t4"]},
        {"id": "t6", "issue": 6, "files": ["ceo_root_manager.js"], "dependsOn": ["t2"]},
        {"id": "t7", "issue": 7, "files": ["container_executor.js"], "dependsOn": []},
        {"id": "t8", "issue": 8, "files": ["container_executor.js", "egress_proxy.js"], "dependsOn": ["t7"]}
      ]
    }
  ]
}

フェーズ 1 の並列実行：

• t1 と t3 は異なるファイルを扱うため、並列実行されます
• t2 は t1 の完了を待ちます（同じファイル）

フェーズ 2 の並列実行：

• t4、t6、t7 は同時に開始できます
• t5 は t4 の完了を待ち、t8 は t7 の完了を待ちます

---

ヒント

1. 複雑な作業には 常に GPT-5.2-codex high を使用してください：--model gpt-5.2-codex-high
2. 明確なプロンプト — Issue 番号、説明、期待する結果、テスト手順を含めてください
3. アトミックなコミット — 論理的な変更ごとにコミットするよう Codex に指示してください
4. 早めにプッシュする — セッションが終了しても進捗を失わないよう、リモートブランチにプッシュしてください
5. ログをチェックポイントとして保存する — tmux の出力を定期的にファイルに取得してください
6. フェーズゲート — フェーズ N が 100% 完了するまで、フェーズ N+1 を開始しないでください
7. 積極的に自己修復する — 10 分以上停止していたら、自動的に介入してください
8. ブラウザーリレーの制限 — CDP による自動化がブロックされた場合は、iframe の一括スクレイピングか、ブラウザーを手動で操作してください

---

他のスキルとの連携

• senior-engineering：ビルドの原則と品質ゲートのために読み込みます
• coding-agent：Codex CLI の使用パターンを参照します
• github：PR の作成と Issue の管理に使用します

---

学んだ教訓（2026-01-17）

Codex サンドボックスの制限

codex exec --full-auto を使用する場合、サンドボックスには次の制限があります。

• ネットワークアクセス不可 — git push は「Could not resolve host」エラーで失敗します
• ファイルシステムの制限 — ~/nuri_workspace などのパスには書き込めません

ハートビート検出の改善

ハートビートでは、次の項目を確認する必要があります。

1. シェルプロンプトのアイドル状態 — tmux ペインに username@hostname path % が表示されていれば、ワーカーは完了しています
2. 未プッシュのコミット — git log @{u}.. --oneline にリモートにないコミットが表示されます
3. プッシュの失敗 — 出力に「Could not resolve host」がないか確認します

検出した場合、オーケストレーター（ワーカーではありません）は次の操作を行います。

1. サンドボックスの外からコミットをプッシュします
2. gh pr create で PR を作成します
3. マニフェストを更新して通知します

推奨パターン

# In heartbeat, for each task:
cd /tmp/orchestrator-*/task-tN
if tmux capture-pane shows shell prompt; then
  # Worker finished, check for unpushed work
  if git log @{u}.. --oneline | grep -q .; then
    git push -u origin HEAD
    gh pr create --title "$(git log --format=%s -1)" --body "Closes #N" --base main
  fi
fi