Claude-Code-Workflow/.codex/skills/codex-issue-plan-execute/phases/orchestrator.md

Orchestrator - Dual-Agent Pipeline Architecture

主流程编排器：创建两个持久化 agent（规划和执行），流水线式处理所有 issue。

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│        Main Orchestrator (Claude Code)                  │
│        流水线式分配任务给两个持久化 agent               │
└──────┬────────────────────────────────────────┬────────┘
       │ send_input                             │ send_input
       │ (逐个 issue)                           │ (逐个 solution)
       ▼                                        ▼
┌──────────────────┐                    ┌──────────────────┐
│ Planning Agent   │                    │ Execution Agent  │
│ (持久化)         │                    │ (持久化)         │
│                  │                    │                  │
│ • 接收 issue    │                    │ • 接收 solution │
│ • 设计方案      │                    │ • 执行 tasks   │
│ • 返回 solution │                    │ • 返回执行结果 │
└──────────────────┘                    └──────────────────┘
       ▲                                        ▲
       └────────────────┬─────────────────────┘
              wait for completion

Main Orchestrator Pseudocode

async function mainOrchestrator(workDir, issues) {
  const planningResults = { results: [] };  // 统一存储
  const executionResults = { results: [] }; // 统一存储

  // 1. Create persistent agents (never close until done)
  const planningAgentId = spawn_agent({
    message: Read('prompts/planning-agent-system.md')
  });

  const executionAgentId = spawn_agent({
    message: Read('prompts/execution-agent-system.md')
  });

  try {
    // Phase 1: Planning Pipeline
    for (const issue of issues) {
      // Send issue to planning agent (不新建 agent，用 send_input)
      send_input({
        id: planningAgentId,
        message: buildPlanningRequest(issue)
      });

      // Wait for solution
      const result = wait({ ids: [planningAgentId], timeout_ms: 300000 });
      const solution = parseResponse(result);

      // Store in unified results
      planningResults.results.push({
        issue_id: issue.id,
        solution: solution,
        status: solution ? "completed" : "failed"
      });
    }

    // Save planning results once
    Write(`${workDir}/planning-results.json`, JSON.stringify(planningResults, null, 2));

    // Phase 2: Execution Pipeline
    for (const planning of planningResults.results) {
      if (planning.status !== "completed") continue;

      // Send solution to execution agent (不新建 agent，用 send_input)
      send_input({
        id: executionAgentId,
        message: buildExecutionRequest(planning.solution)
      });

      // Wait for execution result
      const result = wait({ ids: [executionAgentId], timeout_ms: 600000 });
      const execResult = parseResponse(result);

      // Store in unified results
      executionResults.results.push({
        issue_id: planning.issue_id,
        status: execResult?.status || "failed",
        commit_hash: execResult?.commit_hash
      });
    }

    // Save execution results once
    Write(`${workDir}/execution-results.json`, JSON.stringify(executionResults, null, 2));

  } finally {
    // Close agents after ALL issues processed
    close_agent({ id: planningAgentId });
    close_agent({ id: executionAgentId });
  }

  generateFinalReport(workDir, planningResults, executionResults);
}

Key Design Principles

1. Agent Persistence

• Creating: Each agent created once at the beginning
• Running: Agents continue running, receiving multiple send_input calls
• Closing: Agents closed only after all issues processed
• Benefit: Agent maintains context across multiple issues

2. Unified Results Storage

// planning-results.json
{
  "phase": "planning",
  "created_at": "2025-01-29T12:00:00Z",
  "results": [
    {
      "issue_id": "ISS-001",
      "solution_id": "SOL-ISS-001-1",
      "status": "completed",
      "solution": { "id": "...", "tasks": [...] },
      "planned_at": "2025-01-29T12:05:00Z"
    },
    {
      "issue_id": "ISS-002",
      "solution_id": "SOL-ISS-002-1",
      "status": "completed",
      "solution": { "id": "...", "tasks": [...] },
      "planned_at": "2025-01-29T12:10:00Z"
    }
  ]
}

// execution-results.json
{
  "phase": "execution",
  "created_at": "2025-01-29T12:15:00Z",
  "results": [
    {
      "issue_id": "ISS-001",
      "solution_id": "SOL-ISS-001-1",
      "status": "completed",
      "commit_hash": "abc123def",
      "files_modified": ["src/auth.ts"],
      "executed_at": "2025-01-29T12:20:00Z"
    }
  ]
}

优点:

• 单一 JSON 文件，易于查询和分析
• 完整的处理历史
• 减少文件 I/O 次数

3. Pipeline Flow

Issue 1 → Planning Agent → Wait → Solution 1 (save)
Issue 2 → Planning Agent → Wait → Solution 2 (save)
Issue 3 → Planning Agent → Wait → Solution 3 (save)
[All saved to planning-results.json]

Solution 1 → Execution Agent → Wait → Result 1 (save)
Solution 2 → Execution Agent → Wait → Result 2 (save)
Solution 3 → Execution Agent → Wait → Result 3 (save)
[All saved to execution-results.json]

4. Agent Communication via send_input

Instead of creating new agents, reuse persistent ones:

// ❌ OLD: Create new agent per issue
for (const issue of issues) {
  const agentId = spawn_agent({ message: prompt });
  const result = wait({ ids: [agentId] });
  close_agent({ id: agentId });  // ← Expensive!
}

// ✅ NEW: Persistent agent with send_input
const agentId = spawn_agent({ message: initialPrompt });
for (const issue of issues) {
  send_input({ id: agentId, message: taskPrompt });  // ← Reuse!
  const result = wait({ ids: [agentId] });
}
close_agent({ id: agentId });  // ← Single cleanup

5. Path Resolution for Global Installation

When this skill is installed globally:

• Skill-internal paths: Use relative paths from skill root (e.g., prompts/planning-agent-system.md)
• Project paths: Use project-relative paths starting with . (e.g., .workflow/project-tech.json)
• User-home paths: Use ~ prefix (e.g., ~/.codex/agents/...)
• Working directory: Always relative to the project root when skill executes

Benefits of This Architecture

方面	优势
性能	Agent 创建/销毁开销仅一次（而非 N 次）
上下文	Agent 在多个任务间保持上下文
存储	统一的 JSON 文件，易于追踪和查询
通信	通过 send_input 实现 agent 间的数据传递
可维护性	流水线结构清晰，易于调试