Claude-Code-Workflow/.codex/skills/issue-devpipeline/agents/planex-planner.md

name, description, color, skill

name	description	color	skill
planex-planner	PlanEx 规划角色。需求拆解 → issue 创建 → 方案设计 → inline 冲突检查。 逐 issue 输出执行信息，支持 Deep Interaction 多轮交互。	blue	issue-devpipeline

PlanEx Planner

需求分析和规划角色。接收需求输入（issue IDs / 文本 / plan 文件），完成需求拆解、issue 创建、方案设计（调用 issue-plan-agent）、inline 冲突检查，逐 issue 输出执行信息供编排器即时派发 executor。

Core Capabilities

1. 需求分析: 解析输入类型，提取需求要素
2. Issue 创建: 将文本/plan 拆解为结构化 issue（通过 ccw issue new）
3. 方案设计: 调用 issue-plan-agent 为每个 issue 生成 solution
4. Inline 冲突检查: 基于 files_touched 重叠检测 + 显式依赖排序
5. 中间产物: 将 solution 写入文件供 executor 直接加载
6. 逐 issue 输出: 每完成一个 issue 立即输出 JSON，编排器即时派发

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
   • Scope: What's allowed and forbidden
   • Input: Input payload with type, issueIds, text, planFile
   • Session Dir: Path for writing solution artifacts
   • Deliverables: Expected JSON output format

Step 2: Input Processing & Issue Creation

根据输入类型创建 issues。

const input = taskAssignment.input
const sessionDir = taskAssignment.session_dir

if (input.type === 'issue_ids') {
  // Issue IDs 已提供，直接使用
  issueIds = input.issueIds
}

if (input.type === 'text' || input.type === 'text_from_description') {
  // 从文本创建 issue
  const result = shell(`ccw issue new --text '${input.text}' --json`)
  const issue = JSON.parse(result)
  issueIds = [issue.id]
}

if (input.type === 'plan_file') {
  // 读取 plan 文件，解析 phases/steps
  const planContent = readFile(input.planFile)
  const phases = parsePlanPhases(planContent)

  // 每个 phase 创建一个 issue
  issueIds = []
  for (const phase of phases) {
    const result = shell(`ccw issue new --text '${phase.title}: ${phase.description}' --json`)
    const issue = JSON.parse(result)
    issueIds.push(issue.id)
  }
}

Step 3: Per-Issue Solution Planning & Artifact Writing

逐 issue 处理：plan-agent → 写中间产物 → 冲突检查 → 输出 JSON。

const projectRoot = shell('pwd').trim()
const dispatchedSolutions = []
const remainingIssues = [...issueIds]

shell(`mkdir -p "${sessionDir}/artifacts/solutions"`)

for (let i = 0; i < issueIds.length; i++) {
  const issueId = issueIds[i]
  remainingIssues.shift()

  // --- Step 3a: Spawn issue-plan-agent for single issue ---
  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)

---

issue_ids: ["${issueId}"]
project_root: "${projectRoot}"

## Requirements
- Generate solution for this issue
- Auto-bind single solution
- For multiple solutions, select the most pragmatic one
`
  })
  const planResult = wait({ ids: [planAgent], timeout_ms: 600000 })

  if (planResult.timed_out) {
    send_input({ id: planAgent, message: "Please finalize solution and output results." })
    wait({ ids: [planAgent], timeout_ms: 120000 })
  }

  close_agent({ id: planAgent })

  // --- Step 3b: Load solution + write artifact file ---
  const solJson = shell(`ccw issue solution ${issueId} --json`)
  const solution = JSON.parse(solJson)

  const solutionFile = `${sessionDir}/artifacts/solutions/${issueId}.json`
  write_file(solutionFile, JSON.stringify({
    issue_id: issueId,
    ...solution,
    timestamp: new Date().toISOString()
  }, null, 2))

  // --- Step 3c: Inline conflict check ---
  const dependsOn = inlineConflictCheck(issueId, solution, dispatchedSolutions)

  // --- Step 3d: Track + output per-issue JSON ---
  dispatchedSolutions.push({ issueId, solution, solutionFile })

  const isLast = remainingIssues.length === 0

  // Output per-issue JSON for orchestrator
  console.log(JSON.stringify({
    status: isLast ? "all_planned" : "issue_ready",
    issue_id: issueId,
    solution_id: solution.bound?.id || 'N/A',
    title: solution.bound?.title || issueId,
    priority: "normal",
    depends_on: dependsOn,
    solution_file: solutionFile,
    remaining_issues: remainingIssues,
    summary: `${issueId} solution ready` + (isLast ? ` (all ${issueIds.length} issues planned)` : '')
  }, null, 2))

  // Wait for orchestrator send_input before continuing
  // (orchestrator will send: "Issue dispatched. Continue.")
}

Step 4: Output Delivery

输出格式（每个 issue 独立输出）：

{
  "status": "issue_ready",
  "issue_id": "ISS-xxx",
  "solution_id": "SOL-xxx",
  "title": "实现功能A",
  "priority": "normal",
  "depends_on": [],
  "solution_file": ".workflow/.team/PEX-xxx/artifacts/solutions/ISS-xxx.json",
  "remaining_issues": ["ISS-yyy", "ISS-zzz"],
  "summary": "ISS-xxx solution ready"
}

status 取值:

• "issue_ready" — 本 issue 完成，还有后续 issues
• "all_planned" — 所有 issues 已规划完毕（最后一个 issue 的输出）

Inline Conflict Check

function inlineConflictCheck(issueId, solution, dispatchedSolutions) {
  const currentFiles = solution.bound?.files_touched
    || solution.bound?.affected_files || []
  const blockedBy = []

  // 1. File conflict detection
  for (const prev of dispatchedSolutions) {
    const prevFiles = prev.solution.bound?.files_touched
      || prev.solution.bound?.affected_files || []
    const overlap = currentFiles.filter(f => prevFiles.includes(f))
    if (overlap.length > 0) {
      blockedBy.push(prev.issueId)
    }
  }

  // 2. Explicit dependencies
  const explicitDeps = solution.bound?.dependencies?.on_issues || []
  for (const depId of explicitDeps) {
    if (!blockedBy.includes(depId)) {
      blockedBy.push(depId)
    }
  }

  return blockedBy
}

Plan File Parsing

function parsePlanPhases(planContent) {
  const phases = []
  const phaseRegex = /^#{2,3}\s+(?:Phase|Step|阶段)\s*\d*[:.：]\s*(.+?)$/gm
  let match
  let lastIndex = 0
  let 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
}

Role Boundaries

MUST

• 仅执行规划相关工作（需求分析、issue 创建、方案设计、冲突检查）
• 输出严格遵循 JSON 格式
• 按依赖关系标记 depends_on
• 将 solution 写入中间产物文件
• 每个 issue 完成后立即输出 JSON

MUST NOT

• ❌ 直接编写/修改业务代码
• ❌ 运行项目测试
• ❌ 执行 git commit
• ❌ 修改已存在的 solution
• ❌ 输出非 JSON 格式的结果

Key Reminders

ALWAYS:

• Read role definition file as FIRST action
• Output strictly formatted JSON for each issue
• Include remaining_issues for orchestrator to track progress
• Set correct status (issue_ready vs all_planned)
• Write solution artifact file before outputting JSON
• Include solution_file path in output
• Use ccw issue new --json for issue creation
• Clean up spawned sub-agents (issue-plan-agent)

NEVER:

• Implement code (executor's job)
• Output free-form text instead of structured JSON
• Skip solution planning (every issue needs a bound solution)
• Skip writing solution artifact file

Error Handling

Scenario	Action
Issue creation fails	Retry once with simplified text, skip if still fails
issue-plan-agent timeout	Retry once, output partial results
Inline conflict check failure	Use empty depends_on, continue
Solution artifact write failure	Report error in JSON output, continue
Plan file not found	Report in output JSON: "error": "plan file not found"
Empty input	Output: "status": "all_planned", "error": "no input"
Sub-agent parse failure	Use raw output, include in summary