feat(codex): convert team-planex skill to Codex-native format

Add Codex skill package with spawn_agent/wait/send_input/close_agent patterns, replacing Claude Task/TeamCreate/SendMessage primitives.
2026-02-28 09:23:08 +08:00 · 2026-02-23 23:19:19 +08:00
parent 07b9d06cad
commit 9e8d6af9f1
3 changed files with 1023 additions and 0 deletions
--- a/.codex/skills/team-planex/agents/planex-executor.md
+++ b/.codex/skills/team-planex/agents/planex-executor.md
@@ -0,0 +1,316 @@
+---
+name: planex-executor
+description: |
+  Execution agent for PlanEx pipeline. Loads solutions, routes to
+  configurable backends (agent/codex/gemini CLI), runs tests, commits.
+  Processes all tasks within a single wave assignment.
+color: green
+skill: team-planex
+---
+
+# PlanEx Executor
+
+加载 solution → 根据 execution_method 路由到对应后端（Agent/Codex/Gemini）→ 测试验证 → 提交。每次被 spawn 时处理一个 wave 的所有 exec tasks，按依赖顺序执行。
+
+## Core Capabilities
+
+1. **Solution Loading**: 从 issue system 加载 bound solution plan
+2. **Multi-Backend Routing**: 根据 execution_method 选择 agent/codex/gemini 后端
+3. **Test Verification**: 实现后运行测试验证
+4. **Commit Management**: 每个 solution 完成后 git commit
+5. **Result Reporting**: 输出结构化 IMPL_COMPLETE / WAVE_DONE 数据
+
+## Execution Process
+
+### Step 1: Context Loading
+
+**MANDATORY**: Execute these steps FIRST before any other action.
+
+1. Read this role definition file (already done if you're reading this)
+2. Read: `.workflow/project-tech.json` — understand project technology stack
+3. Read: `.workflow/project-guidelines.json` — understand project conventions
+4. Parse the TASK ASSIGNMENT from the spawn message for:
+   - **Goal**: Which wave to implement
+   - **Wave Tasks**: Array of exec_tasks with issue_id, solution_id, depends_on
+   - **Execution Config**: execution_method + code_review settings
+   - **Deliverables**: IMPL_COMPLETE + WAVE_DONE structured output
+
+### Step 2: Implementation (Sequential by Dependency)
+
+Process each task in the wave, respecting dependency order.
+
+```javascript
+const tasks = taskAssignment.exec_tasks
+const executionMethod = taskAssignment.execution_config.execution_method
+const codeReview = taskAssignment.execution_config.code_review
+const waveNum = taskAssignment.wave_number
+
+let completed = 0
+let failed = 0
+
+// Sort by dependencies (topological order — tasks with no deps first)
+const sorted = topologicalSort(tasks)
+
+for (const task of sorted) {
+  const issueId = task.issue_id
+
+  // --- Load solution ---
+  const solJson = shell(`ccw issue solution ${issueId} --json`)
+  const solution = JSON.parse(solJson)
+
+  if (!solution.bound) {
+    console.log(`IMPL_COMPLETE:\n${JSON.stringify({
+      issue_id: issueId,
+      status: "failed",
+      reason: "No bound solution",
+      test_result: "N/A",
+      commit: "N/A"
+    }, null, 2)}`)
+    failed++
+    continue
+  }
+
+  // --- Update issue status ---
+  shell(`ccw issue update ${issueId} --status executing`)
+
+  // --- Resolve executor backend ---
+  const taskCount = solution.bound.task_count || solution.bound.tasks?.length || 0
+  const executor = resolveExecutor(executionMethod, taskCount)
+
+  // --- Build execution prompt ---
+  const prompt = buildExecutionPrompt(issueId, solution)
+
+  // --- Route to backend ---
+  let implSuccess = false
+
+  if (executor === 'agent') {
+    // Spawn code-developer subagent (synchronous)
+    const devAgent = spawn_agent({
+      message: `
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS (Agent Execute)
+1. **Read role definition**: ~/.codex/agents/code-developer.md (MUST read first)
+2. Read: .workflow/project-tech.json
+3. Read: .workflow/project-guidelines.json
+
+---
+
+${prompt}
+`
+    })
+
+    const devResult = wait({ ids: [devAgent], timeout_ms: 900000 })
+
+    if (devResult.timed_out) {
+      send_input({ id: devAgent, message: "Please finalize implementation and output results." })
+      wait({ ids: [devAgent], timeout_ms: 120000 })
+    }
+
+    close_agent({ id: devAgent })
+    implSuccess = true // will verify with tests below
+
+  } else if (executor === 'codex') {
+    // Codex CLI execution
+    const fixedId = `planex-${issueId}`
+    shell(`ccw cli -p "${prompt}" --tool codex --mode write --id ${fixedId}`)
+    // Wait for CLI completion (synchronous in agent context)
+    implSuccess = true
+
+  } else if (executor === 'gemini') {
+    // Gemini CLI execution
+    const fixedId = `planex-${issueId}`
+    shell(`ccw cli -p "${prompt}" --tool gemini --mode write --id ${fixedId}`)
+    implSuccess = true
+  }
+
+  // --- Test verification ---
+  let testCmd = 'npm test'
+  try {
+    const pkgJson = JSON.parse(read_file('package.json'))
+    if (pkgJson.scripts?.test) testCmd = 'npm test'
+    else if (pkgJson.scripts?.['test:unit']) testCmd = 'npm run test:unit'
+  } catch { /* use default */ }
+
+  const testResult = shell(`${testCmd} 2>&1 || echo "TEST_FAILED"`)
+  const testPassed = !testResult.includes('TEST_FAILED') && !testResult.includes('FAIL')
+
+  if (!testPassed) {
+    console.log(`IMPL_COMPLETE:\n${JSON.stringify({
+      issue_id: issueId,
+      status: "failed",
+      reason: "Tests failing after implementation",
+      executor: executor,
+      test_result: "fail",
+      test_output: testResult.slice(0, 500),
+      commit: "N/A",
+      resume_hint: executor !== 'agent'
+        ? `ccw cli -p "Fix failing tests" --resume planex-${issueId} --tool ${executor} --mode write`
+        : "Re-spawn code-developer with fix instructions"
+    }, null, 2)}`)
+    failed++
+    continue
+  }
+
+  // --- Optional code review ---
+  if (codeReview && codeReview !== 'Skip') {
+    executeCodeReview(codeReview, issueId)
+  }
+
+  // --- Git commit ---
+  shell(`git add -A && git commit -m "feat(${issueId}): implement solution ${task.solution_id}"`)
+  const commitHash = shell('git rev-parse --short HEAD').trim()
+
+  // --- Update issue status ---
+  shell(`ccw issue update ${issueId} --status completed`)
+
+  // --- Report completion ---
+  console.log(`IMPL_COMPLETE:\n${JSON.stringify({
+    issue_id: issueId,
+    status: "success",
+    executor: executor,
+    test_result: "pass",
+    commit: commitHash
+  }, null, 2)}`)
+
+  completed++
+}
+```
+
+### Step 3: Wave Completion Report
+
+```javascript
+console.log(`WAVE_DONE:\n${JSON.stringify({
+  wave_number: waveNum,
+  completed: completed,
+  failed: failed
+}, null, 2)}`)
+```
+
+## Execution Method Resolution
+
+```javascript
+function resolveExecutor(method, taskCount) {
+  if (method.toLowerCase() === 'auto') {
+    return taskCount <= 3 ? 'agent' : 'codex'
+  }
+  return method.toLowerCase() // 'agent' | 'codex' | 'gemini'
+}
+```
+
+## Execution Prompt Builder
+
+```javascript
+function buildExecutionPrompt(issueId, solution) {
+  return `
+## Issue
+ID: ${issueId}
+Title: ${solution.bound.title || 'N/A'}
+
+## Solution Plan
+${JSON.stringify(solution.bound, null, 2)}
+
+## Implementation Requirements
+1. Follow the solution plan tasks in order
+2. Write clean, minimal code following existing patterns
+3. Run tests after each significant change
+4. Ensure all existing tests still pass
+5. Do NOT over-engineer — implement exactly what the solution specifies
+
+## Quality Checklist
+- [ ] All solution tasks implemented
+- [ ] No TypeScript/linting errors
+- [ ] Existing tests pass
+- [ ] New tests added where appropriate
+- [ ] No security vulnerabilities introduced
+`
+}
+```
+
+## Code Review (Optional)
+
+```javascript
+function executeCodeReview(reviewTool, issueId) {
+  if (reviewTool === 'Gemini Review') {
+    shell(`ccw cli -p "PURPOSE: Code review for ${issueId} implementation
+TASK: Verify solution convergence, check test coverage, analyze quality
+MODE: analysis
+CONTEXT: @**/*
+EXPECTED: Quality assessment with issue identification
+CONSTRAINTS: Focus on solution adherence" --tool gemini --mode analysis`)
+  } else if (reviewTool === 'Codex Review') {
+    shell(`ccw cli --tool codex --mode review --uncommitted`)
+  }
+  // Agent Review: perform inline review (read diff, analyze)
+}
+```
+
+## Role Boundaries
+
+### MUST
+
+- 仅处理被分配的 wave 中的 exec tasks
+- 按依赖顺序（topological sort）执行任务
+- 每个 task 完成后输出 IMPL_COMPLETE
+- 所有 tasks 完成后输出 WAVE_DONE
+- 通过 spawn_agent 调用 code-developer（agent 后端）
+- 运行测试验证实现
+
+### MUST NOT
+
+- ❌ 创建 issue（planner 职责）
+- ❌ 修改 solution 或 queue（planner 职责）
+- ❌ Spawn issue-plan-agent 或 issue-queue-agent
+- ❌ 处理非当前 wave 的任务
+- ❌ 跳过测试验证直接 commit
+
+## Topological Sort
+
+```javascript
+function topologicalSort(tasks) {
+  const taskMap = new Map(tasks.map(t => [t.issue_id, t]))
+  const visited = new Set()
+  const result = []
+
+  function visit(id) {
+    if (visited.has(id)) return
+    visited.add(id)
+    const task = taskMap.get(id)
+    if (task?.depends_on) {
+      task.depends_on.forEach(dep => visit(dep))
+    }
+    result.push(task)
+  }
+
+  tasks.forEach(t => visit(t.issue_id))
+  return result.filter(Boolean)
+}
+```
+
+## Key Reminders
+
+**ALWAYS**:
+- Read role definition file as FIRST action (Step 1)
+- Follow structured output template (IMPL_COMPLETE / WAVE_DONE)
+- Verify tests pass before committing
+- Respect dependency ordering within the wave
+- Include executor backend info and commit hash in reports
+
+**NEVER**:
+- Skip test verification before commit
+- Modify files outside of the assigned solution scope
+- Produce unstructured output
+- Continue to next task if current has unresolved blockers
+- Create new issues or modify planning artifacts
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| Solution not found | Report IMPL_COMPLETE with status=failed, reason |
+| code-developer timeout | Urge convergence via send_input, close and report |
+| CLI execution failure | Include resume_hint in IMPL_COMPLETE output |
+| Tests failing | Report with test_output excerpt and resume_hint |
+| Git commit failure | Retry once, then report in IMPL_COMPLETE |
+| Unknown execution_method | Fallback to 'agent' with warning |
+| Dependency task failed | Skip dependent tasks, report as failed with reason |
--- a/.codex/skills/team-planex/agents/planex-planner.md
+++ b/.codex/skills/team-planex/agents/planex-planner.md
@@ -0,0 +1,291 @@
+---
+name: planex-planner
+description: |
+  Planning lead for PlanEx pipeline. Decomposes requirements into issues,
+  generates solutions via issue-plan-agent, forms execution queues via
+  issue-queue-agent, outputs wave-structured data for orchestrator dispatch.
+color: blue
+skill: team-planex
+---
+
+# PlanEx Planner
+
+需求拆解 → issue 创建 → 方案设计 → 队列编排 → 输出 wave 数据。内部 spawn issue-plan-agent 和 issue-queue-agent 子代理，通过 Wave Pipeline 持续推进。每完成一个 wave 立即输出 WAVE_READY，等待 orchestrator send_input 继续下一 wave。
+
+## Core Capabilities
+
+1. **Requirement Decomposition**: 将需求文本/plan 文件拆解为独立 issues
+2. **Solution Planning**: 通过 issue-plan-agent 为每个 issue 生成 solution
+3. **Queue Formation**: 通过 issue-queue-agent 排序 solutions 并检测冲突
+4. **Wave Output**: 每个 wave 完成后输出结构化 WAVE_READY 数据
+
+## Execution Process
+
+### Step 1: Context Loading
+
+**MANDATORY**: Execute these steps FIRST before any other action.
+
+1. Read this role definition file (already done if you're reading this)
+2. Read: `.workflow/project-tech.json` — understand project technology stack
+3. Read: `.workflow/project-guidelines.json` — understand project conventions
+4. Parse the TASK ASSIGNMENT from the spawn message for:
+   - **Goal**: What to achieve
+   - **Input**: Issue IDs / text / plan file
+   - **Execution Config**: execution_method + code_review settings
+   - **Deliverables**: WAVE_READY + ALL_PLANNED structured output
+
+### Step 2: Input Parsing & Issue Creation
+
+Parse the input from TASK ASSIGNMENT and create issues as needed.
+
+```javascript
+const input = taskAssignment.input
+
+// 1) 已有 Issue IDs
+const issueIds = input.match(/ISS-\d{8}-\d{6}/g) || []
+
+// 2) 文本输入 → 创建 issue
+const textMatch = input.match(/text:\s*(.+)/)
+if (textMatch && issueIds.length === 0) {
+  // Use ccw issue create CLI to create issue from text
+  const result = shell(`ccw issue create --data '{"title":"${textMatch[1]}","description":"${textMatch[1]}"}' --json`)
+  const newIssue = JSON.parse(result)
+  issueIds.push(newIssue.id)
+}
+
+// 3) Plan 文件 → 解析并批量创建 issues
+const planMatch = input.match(/plan_file:\s*(\S+)/)
+if (planMatch && issueIds.length === 0) {
+  const planContent = read_file(planMatch[1])
+
+  // Check if execution-plan.json from req-plan-with-file
+  try {
+    const content = JSON.parse(planContent)
+    if (content.waves && content.issue_ids) {
+      // execution-plan format: use wave structure directly
+      executionPlan = content
+      issueIds = content.issue_ids
+    }
+  } catch {
+    // Regular plan file: parse phases and create issues
+    const phases = parsePlanPhases(planContent)
+    for (const phase of phases) {
+      const result = shell(`ccw issue create --data '{"title":"${phase.title}","description":"${phase.description}"}' --json`)
+      issueIds.push(JSON.parse(result).id)
+    }
+  }
+}
+```
+
+### Step 3: Wave-Based Solution Planning
+
+Group issues into waves, spawn sub-agents for each wave.
+
+```javascript
+const projectRoot = shell('cd . && pwd').trim()
+
+// Group into waves (max 5 per wave, or use execution-plan wave structure)
+const WAVE_SIZE = 5
+let waves
+if (executionPlan) {
+  waves = executionPlan.waves.map(w => w.issue_ids)
+} else {
+  waves = []
+  for (let i = 0; i < issueIds.length; i += WAVE_SIZE) {
+    waves.push(issueIds.slice(i, i + WAVE_SIZE))
+  }
+}
+
+let waveNum = 0
+for (const waveIssues of waves) {
+  waveNum++
+
+  // --- Step 3a: Spawn issue-plan-agent for solutions ---
+  const planAgent = spawn_agent({
+    message: `
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS (Agent Execute)
+1. **Read role definition**: ~/.codex/agents/issue-plan-agent.md (MUST read first)
+2. Read: .workflow/project-tech.json
+3. Read: .workflow/project-guidelines.json
+
+---
+
+Goal: Generate solutions for Wave ${waveNum} issues
+
+issue_ids: ${JSON.stringify(waveIssues)}
+project_root: "${projectRoot}"
+
+## Requirements
+- Generate solutions for each issue
+- Auto-bind single solutions
+- For multiple solutions, select the most pragmatic one
+
+## Deliverables
+Structured output with solution bindings per issue.
+`
+  })
+
+  const planResult = wait({ ids: [planAgent], timeout_ms: 600000 })
+
+  if (planResult.timed_out) {
+    send_input({ id: planAgent, message: "Please finalize solutions and output current results." })
+    wait({ ids: [planAgent], timeout_ms: 120000 })
+  }
+
+  close_agent({ id: planAgent })
+
+  // --- Step 3b: Spawn issue-queue-agent for ordering ---
+  const queueAgent = spawn_agent({
+    message: `
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS (Agent Execute)
+1. **Read role definition**: ~/.codex/agents/issue-queue-agent.md (MUST read first)
+2. Read: .workflow/project-tech.json
+
+---
+
+Goal: Form execution queue for Wave ${waveNum}
+
+issue_ids: ${JSON.stringify(waveIssues)}
+project_root: "${projectRoot}"
+
+## Requirements
+- Order solutions by dependency (DAG)
+- Detect conflicts between solutions
+- Output execution queue to .workflow/issues/queue/execution-queue.json
+
+## Deliverables
+Structured execution queue with dependency ordering.
+`
+  })
+
+  const queueResult = wait({ ids: [queueAgent], timeout_ms: 300000 })
+
+  if (queueResult.timed_out) {
+    send_input({ id: queueAgent, message: "Please finalize queue and output results." })
+    wait({ ids: [queueAgent], timeout_ms: 60000 })
+  }
+
+  close_agent({ id: queueAgent })
+
+  // --- Step 3c: Read queue and output WAVE_READY ---
+  const queuePath = `.workflow/issues/queue/execution-queue.json`
+  const queue = JSON.parse(read_file(queuePath))
+
+  const execTasks = queue.queue.map(entry => ({
+    issue_id: entry.issue_id,
+    solution_id: entry.solution_id,
+    title: entry.title || entry.issue_id,
+    priority: entry.priority || "normal",
+    depends_on: entry.depends_on || []
+  }))
+
+  // Output structured wave data for orchestrator
+  console.log(`
+WAVE_READY:
+${JSON.stringify({
+  wave_number: waveNum,
+  issue_ids: waveIssues,
+  queue_path: queuePath,
+  exec_tasks: execTasks
+}, null, 2)}
+`)
+
+  // Wait for orchestrator send_input before continuing to next wave
+  // (orchestrator will send: "Wave N dispatched. Continue to Wave N+1.")
+}
+```
+
+### Step 4: Finalization
+
+After all waves are planned, output ALL_PLANNED signal.
+
+```javascript
+console.log(`
+ALL_PLANNED:
+${JSON.stringify({
+  total_waves: waveNum,
+  total_issues: issueIds.length
+}, null, 2)}
+`)
+```
+
+## Role Boundaries
+
+### MUST
+
+- 仅执行规划和拆解工作
+- 每个 wave 完成后输出 WAVE_READY 结构化数据
+- 所有 wave 完成后输出 ALL_PLANNED
+- 通过 spawn_agent 调用 issue-plan-agent 和 issue-queue-agent
+- 等待 orchestrator send_input 才继续下一 wave
+
+### MUST NOT
+
+- ❌ 直接编写/修改业务代码（executor 职责）
+- ❌ Spawn code-developer agent（executor 职责）
+- ❌ 运行项目测试
+- ❌ git commit 代码变更
+- ❌ 直接修改 solution 内容（issue-plan-agent 负责）
+
+## Plan File Parsing
+
+```javascript
+function parsePlanPhases(planContent) {
+  const phases = []
+  const phaseRegex = /^#{2,3}\s+(?:Phase|Step|阶段)\s*\d*[:.：]\s*(.+?)$/gm
+  let match, lastIndex = 0, lastTitle = null
+
+  while ((match = phaseRegex.exec(planContent)) !== null) {
+    if (lastTitle !== null) {
+      phases.push({ title: lastTitle, description: planContent.slice(lastIndex, match.index).trim() })
+    }
+    lastTitle = match[1].trim()
+    lastIndex = match.index + match[0].length
+  }
+
+  if (lastTitle !== null) {
+    phases.push({ title: lastTitle, description: planContent.slice(lastIndex).trim() })
+  }
+
+  if (phases.length === 0) {
+    const titleMatch = planContent.match(/^#\s+(.+)$/m)
+    phases.push({
+      title: titleMatch ? titleMatch[1] : 'Plan Implementation',
+      description: planContent.slice(0, 500)
+    })
+  }
+
+  return phases
+}
+```
+
+## Key Reminders
+
+**ALWAYS**:
+- Read role definition file as FIRST action (Step 1)
+- Follow structured output template (WAVE_READY / ALL_PLANNED)
+- Stay within planning boundaries (no code implementation)
+- Spawn issue-plan-agent and issue-queue-agent for each wave
+- Include all issue IDs and solution references in wave data
+
+**NEVER**:
+- Modify source code files
+- Skip context loading (Step 1)
+- Produce unstructured or free-form output
+- Continue to next wave without outputting WAVE_READY
+- Close without outputting ALL_PLANNED
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| Issue creation failure | Retry once with simplified text, report in output |
+| issue-plan-agent timeout | Urge convergence via send_input, close and report partial |
+| issue-queue-agent failure | Create exec tasks without DAG ordering |
+| Plan file not found | Report error in output with CLARIFICATION_NEEDED |
+| Empty input (no issues, no text) | Output CLARIFICATION_NEEDED asking for requirements |
+| Sub-agent produces invalid output | Report error, continue with available data |
--- a/.codex/skills/team-planex/orchestrator.md
+++ b/.codex/skills/team-planex/orchestrator.md
@@ -0,0 +1,416 @@
+---
+name: team-planex
+description: |
+  2-member plan-and-execute pipeline with Wave Pipeline for concurrent planning and execution.
+  Planner decomposes requirements into issues, generates solutions, forms execution queues.
+  Executor implements solutions via configurable backends (agent/codex/gemini).
+agents: 2
+phases: 4
+---
+
+# Team PlanEx
+
+2 成员边规划边执行团队。通过 Wave Pipeline（波次流水线）实现 planner 和 executor 并行工作：planner 完成一个 wave 的 queue 后，orchestrator 立即 spawn executor agent 处理该 wave，同时 send_input 让 planner 继续下一 wave。
+
+## Architecture Overview
+
+```
+┌──────────────────────────────────────────────┐
+│  Orchestrator (this file)                     │
+│  → Parse input → Spawn planner → Spawn exec  │
+└────────────────┬─────────────────────────────┘
+                 │ Wave Pipeline
+         ┌───────┴───────┐
+         ↓               ↓
+    ┌─────────┐    ┌──────────┐
+    │ planner │    │ executor │
+    │ (plan)  │    │ (impl)   │
+    └─────────┘    └──────────┘
+         │               │
+    issue-plan-agent  code-developer
+    issue-queue-agent (or codex/gemini CLI)
+```
+
+## Agent Registry
+
+| Agent | Role File | Responsibility | New/Existing |
+|-------|-----------|----------------|--------------|
+| `planex-planner` | `.codex/skills/team-planex/agents/planex-planner.md` | 需求拆解 → issue 创建 → 方案设计 → 队列编排 | New (skill-specific) |
+| `planex-executor` | `.codex/skills/team-planex/agents/planex-executor.md` | 加载 solution → 代码实现 → 测试 → 提交 | New (skill-specific) |
+| `issue-plan-agent` | `~/.codex/agents/issue-plan-agent.md` | ACE exploration + solution generation + binding | Existing |
+| `issue-queue-agent` | `~/.codex/agents/issue-queue-agent.md` | Solution ordering + conflict detection | Existing |
+| `code-developer` | `~/.codex/agents/code-developer.md` | Code implementation (agent backend) | Existing |
+
+## Input Types
+
+支持 3 种输入方式（通过 orchestrator message 传入）：
+
+| 输入类型 | 格式 | 示例 |
+|----------|------|------|
+| Issue IDs | 直接传入 ID | `ISS-20260215-001 ISS-20260215-002` |
+| 需求文本 | `--text '...'` | `--text '实现用户认证模块'` |
+| Plan 文件 | `--plan path` | `--plan plan/2026-02-15-auth.md` |
+
+## Execution Method Selection
+
+支持 3 种执行后端：
+
+| Executor | 后端 | 适用场景 |
+|----------|------|----------|
+| `agent` | code-developer subagent | 简单任务、同步执行 |
+| `codex` | `ccw cli --tool codex --mode write` | 复杂任务、后台执行 |
+| `gemini` | `ccw cli --tool gemini --mode write` | 分析类任务、后台执行 |
+
+## Phase Execution
+
+### Phase 1: Input Parsing & Preference Collection
+
+Parse user arguments and determine execution configuration.
+
+```javascript
+// Parse input from orchestrator message
+const args = orchestratorMessage
+const issueIds = args.match(/ISS-\d{8}-\d{6}/g) || []
+const textMatch = args.match(/--text\s+['"]([^'"]+)['"]/)
+const planMatch = args.match(/--plan\s+(\S+)/)
+const autoYes = /\b(-y|--yes)\b/.test(args)
+const explicitExec = args.match(/--exec[=\s]+(agent|codex|gemini|auto)/i)?.[1]
+
+let executionConfig
+
+if (explicitExec) {
+  executionConfig = {
+    executionMethod: explicitExec.charAt(0).toUpperCase() + explicitExec.slice(1),
+    codeReviewTool: "Skip"
+  }
+} else if (autoYes) {
+  executionConfig = { executionMethod: "Auto", codeReviewTool: "Skip" }
+} else {
+  // Interactive: ask user for preferences
+  // (orchestrator handles user interaction directly)
+}
+```
+
+### Phase 2: Planning (Planner Agent — Deep Interaction)
+
+Spawn planner agent for wave-based planning. Uses send_input for multi-wave progression.
+
+```javascript
+// Build planner input context
+let plannerInput = ""
+if (issueIds.length > 0) plannerInput = `issue_ids: ${JSON.stringify(issueIds)}`
+else if (textMatch) plannerInput = `text: ${textMatch[1]}`
+else if (planMatch) plannerInput = `plan_file: ${planMatch[1]}`
+
+const planner = spawn_agent({
+  message: `
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS (Agent Execute)
+1. **Read role definition**: .codex/skills/team-planex/agents/planex-planner.md (MUST read first)
+2. Read: .workflow/project-tech.json
+3. Read: .workflow/project-guidelines.json
+
+---
+
+Goal: Decompose requirements into waves of executable solutions
+
+## Input
+${plannerInput}
+
+## Execution Config
+execution_method: ${executionConfig.executionMethod}
+code_review: ${executionConfig.codeReviewTool}
+
+## Deliverables
+For EACH wave, output structured wave data:
+
+\`\`\`
+WAVE_READY:
+wave_number: N
+issue_ids: [ISS-xxx, ...]
+queue_path: .workflow/issues/queue/execution-queue.json
+exec_tasks: [
+  { issue_id: "ISS-xxx", solution_id: "SOL-xxx", title: "...", priority: "normal", depends_on: [] },
+  ...
+]
+\`\`\`
+
+After ALL waves planned, output:
+\`\`\`
+ALL_PLANNED:
+total_waves: N
+total_issues: N
+\`\`\`
+
+## Quality bar
+- Every issue has a bound solution
+- Queue respects dependency DAG
+- Wave boundaries are logical groupings
+`
+})
+
+// Wait for Wave 1
+const wave1 = wait({ ids: [planner], timeout_ms: 600000 })
+
+if (wave1.timed_out) {
+  send_input({ id: planner, message: "Please finalize current wave and output WAVE_READY." })
+  const retry = wait({ ids: [planner], timeout_ms: 120000 })
+}
+
+// Parse wave data from planner output
+const wave1Data = parseWaveReady(wave1.status[planner].completed)
+```
+
+### Phase 3: Wave Pipeline (Planning + Execution Interleaved)
+
+Pipeline: spawn executor for current wave while planner continues next wave.
+
+```javascript
+const allAgentIds = [planner]
+const executorAgents = []
+let waveNum = 1
+let allPlanned = false
+
+while (!allPlanned) {
+  // --- Spawn executor for current wave ---
+  const waveData = parseWaveReady(currentWaveOutput)
+
+  if (waveData && waveData.exec_tasks.length > 0) {
+    const executor = spawn_agent({
+      message: `
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS (Agent Execute)
+1. **Read role definition**: .codex/skills/team-planex/agents/planex-executor.md (MUST read first)
+2. Read: .workflow/project-tech.json
+3. Read: .workflow/project-guidelines.json
+
+---
+
+Goal: Implement all solutions in Wave ${waveNum}
+
+## Wave ${waveNum} Tasks
+${JSON.stringify(waveData.exec_tasks, null, 2)}
+
+## Execution Config
+execution_method: ${executionConfig.executionMethod}
+code_review: ${executionConfig.codeReviewTool}
+
+## Deliverables
+For each task, output:
+\`\`\`
+IMPL_COMPLETE:
+issue_id: ISS-xxx
+status: success|failed
+test_result: pass|fail
+commit: <hash or N/A>
+\`\`\`
+
+After all wave tasks done:
+\`\`\`
+WAVE_DONE:
+wave_number: ${waveNum}
+completed: N
+failed: N
+\`\`\`
+
+## Quality bar
+- All existing tests pass after each implementation
+- Code follows project conventions
+- One commit per solution
+`
+    })
+    allAgentIds.push(executor)
+    executorAgents.push({ id: executor, wave: waveNum })
+  }
+
+  // --- Tell planner to continue next wave ---
+  if (!allPlanned) {
+    send_input({ id: planner, message: `Wave ${waveNum} dispatched to executor. Continue to Wave ${waveNum + 1}.` })
+
+    // Wait for both: planner (next wave) + current executor
+    const activeIds = [planner]
+    if (executorAgents.length > 0) {
+      activeIds.push(executorAgents[executorAgents.length - 1].id)
+    }
+
+    const results = wait({ ids: activeIds, timeout_ms: 600000 })
+
+    // Check planner output
+    const plannerOutput = results.status[planner]?.completed || ""
+    if (plannerOutput.includes("ALL_PLANNED")) {
+      allPlanned = true
+    } else if (plannerOutput.includes("WAVE_READY")) {
+      waveNum++
+      currentWaveOutput = plannerOutput
+    }
+  }
+}
+
+// Wait for remaining executor agents
+const pendingExecutors = executorAgents
+  .map(e => e.id)
+  .filter(id => !completedIds.includes(id))
+
+if (pendingExecutors.length > 0) {
+  const finalResults = wait({ ids: pendingExecutors, timeout_ms: 900000 })
+
+  // Handle timeout
+  if (finalResults.timed_out) {
+    const pending = pendingExecutors.filter(id => !finalResults.status[id]?.completed)
+    pending.forEach(id => {
+      send_input({ id, message: "Please finalize current task and output results." })
+    })
+    wait({ ids: pending, timeout_ms: 120000 })
+  }
+}
+```
+
+### Phase 4: Result Aggregation & Cleanup
+
+```javascript
+// Collect results from all executors
+const pipelineResults = {
+  waves: [],
+  totalCompleted: 0,
+  totalFailed: 0
+}
+
+executorAgents.forEach(({ id, wave }) => {
+  const output = results.status[id]?.completed || ""
+  const waveDone = parseWaveDone(output)
+  pipelineResults.waves.push({
+    wave,
+    completed: waveDone?.completed || 0,
+    failed: waveDone?.failed || 0
+  })
+  pipelineResults.totalCompleted += waveDone?.completed || 0
+  pipelineResults.totalFailed += waveDone?.failed || 0
+})
+
+// Output final summary
+console.log(`
+## PlanEx Pipeline Complete
+
+### Summary
+- Total Waves: ${waveNum}
+- Total Completed: ${pipelineResults.totalCompleted}
+- Total Failed: ${pipelineResults.totalFailed}
+
+### Wave Details
+${pipelineResults.waves.map(w =>
+  `- Wave ${w.wave}: ${w.completed} completed, ${w.failed} failed`
+).join('\n')}
+`)
+
+// Cleanup ALL agents
+allAgentIds.forEach(id => {
+  try { close_agent({ id }) } catch { /* already closed */ }
+})
+```
+
+## Coordination Protocol
+
+### File-Based Communication
+
+Since Codex agents have isolated contexts, use file-based coordination:
+
+| File | Purpose | Writer | Reader |
+|------|---------|--------|--------|
+| `.workflow/.team/PEX-{slug}-{date}/wave-{N}.json` | Wave plan data | planner | orchestrator |
+| `.workflow/.team/PEX-{slug}-{date}/exec-{issueId}.json` | Execution result | executor | orchestrator |
+| `.workflow/.team/PEX-{slug}-{date}/pipeline-log.ndjson` | Event log | both | orchestrator |
+| `.workflow/issues/queue/execution-queue.json` | Execution queue | planner (via issue-queue-agent) | executor |
+
+### Wave Data Format
+
+```json
+{
+  "wave_number": 1,
+  "issue_ids": ["ISS-20260215-001", "ISS-20260215-002"],
+  "queue_path": ".workflow/issues/queue/execution-queue.json",
+  "exec_tasks": [
+    {
+      "issue_id": "ISS-20260215-001",
+      "solution_id": "SOL-001",
+      "title": "Implement auth module",
+      "priority": "high",
+      "depends_on": []
+    }
+  ]
+}
+```
+
+### Execution Result Format
+
+```json
+{
+  "issue_id": "ISS-20260215-001",
+  "status": "success",
+  "executor": "agent",
+  "test_result": "pass",
+  "commit": "abc123",
+  "files_changed": ["src/auth/login.ts", "src/auth/login.test.ts"]
+}
+```
+
+## Lifecycle Management
+
+### Timeout Handling
+
+| Timeout Scenario | Action |
+|-----------------|--------|
+| Planner wave timeout | send_input to urge convergence, retry wait |
+| Executor impl timeout | send_input to finalize, record partial result |
+| All agents timeout | Log error, abort with partial state |
+
+### Cleanup Protocol
+
+```javascript
+// Track all agents created during execution
+const allAgentIds = []
+
+// ... (agents added during phase execution) ...
+
+// Final cleanup (end of orchestrator or on error)
+allAgentIds.forEach(id => {
+  try { close_agent({ id }) } catch { /* already closed */ }
+})
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Planner wave failure | Retry once via send_input, then abort pipeline |
+| Executor impl failure | Record failure, continue with next wave tasks |
+| No issues created from text | Report to user, abort |
+| Solution generation failure | Skip issue, continue with remaining |
+| Queue formation failure | Create exec tasks without DAG ordering |
+| Pipeline stall (no progress) | Timeout handling → urge convergence → abort |
+| Missing role file | Log error, use inline fallback instructions |
+
+## Helper Functions
+
+```javascript
+function parseWaveReady(output) {
+  const match = output.match(/WAVE_READY:\s*\n([\s\S]*?)(?=\n```|$)/)
+  if (!match) return null
+  // Parse structured wave data
+  return JSON.parse(match[1])
+}
+
+function parseWaveDone(output) {
+  const match = output.match(/WAVE_DONE:\s*\n([\s\S]*?)(?=\n```|$)/)
+  if (!match) return null
+  return JSON.parse(match[1])
+}
+
+function resolveExecutor(method, taskCount) {
+  if (method.toLowerCase() === 'auto') {
+    return taskCount <= 3 ? 'agent' : 'codex'
+  }
+  return method.toLowerCase()
+}
+```