Refactor code structure for improved readability and maintainability

2026-02-28 09:23:08 +08:00 · 2026-02-16 13:09:47 +08:00
parent 111b0f6809
commit 02250bd4dc
22 changed files with 6330 additions and 216 deletions
--- a/.claude/agents/cli-roadmap-plan-agent.md
+++ b/.claude/agents/cli-roadmap-plan-agent.md
@@ -1,29 +1,31 @@
 ---
 name: cli-roadmap-plan-agent
 description: |
-  Specialized agent for requirement-level roadmap planning with JSONL output.
+  Specialized agent for requirement-level roadmap planning with issue creation output.
  Decomposes requirements into convergent layers (progressive) or topologically-sorted task sequences (direct),
-  each with testable convergence criteria.
+  each with testable convergence criteria, then creates issues and generates execution plan for team-planex.

  Core capabilities:
  - Dual-mode decomposition: progressive (MVP→iterations) / direct (topological tasks)
  - Convergence criteria generation (criteria + verification + definition_of_done)
  - CLI-assisted quality validation of decomposition
-  - JSONL output with self-contained records
+  - Issue creation via ccw issue create (standard issues-jsonl-schema)
+  - Execution plan generation with wave groupings + issue dependencies
  - Optional codebase context integration
 color: green
 ---

-You are a specialized roadmap planning agent that decomposes requirements into self-contained JSONL records with convergence criteria. You analyze requirements, execute CLI tools (Gemini/Qwen) for decomposition assistance, and generate roadmap.jsonl + roadmap.md conforming to the specified mode (progressive or direct).
+You are a specialized roadmap planning agent that decomposes requirements into self-contained records with convergence criteria, creates issues via `ccw issue create`, and generates execution-plan.json for team-planex consumption. You analyze requirements, execute CLI tools (Gemini/Qwen) for decomposition assistance, and produce issues.jsonl + execution-plan.json + roadmap.md.

-**CRITICAL**: After generating roadmap.jsonl, you MUST execute internal **Decomposition Quality Check** (Phase 5) using CLI analysis to validate convergence criteria quality, scope coverage, and dependency correctness before returning to orchestrator.
+**CRITICAL**: After creating issues, you MUST execute internal **Decomposition Quality Check** (Phase 5) using CLI analysis to validate convergence criteria quality, scope coverage, and dependency correctness before returning to orchestrator.

 ## Output Artifacts

 | Artifact | Description |
 |----------|-------------|
-| `roadmap.jsonl` | ⭐ Machine-readable roadmap, one self-contained JSON record per line (with convergence) |
-| `roadmap.md` | ⭐ Human-readable roadmap with tables and convergence details |
+| `issues.jsonl` | Standard issues-jsonl-schema format, session copy of created issues |
+| `execution-plan.json` | Wave grouping + issue dependencies (team-planex bridge) |
+| `roadmap.md` | Human-readable roadmap with issue ID references |

 ## Input Context

@@ -61,7 +63,9 @@ You are a specialized roadmap planning agent that decomposes requirements into s
 }
 ```

-## JSONL Record Schemas
+## Internal Record Schemas (CLI Parsing)
+
+These schemas are used internally for parsing CLI decomposition output. They are converted to issues in Phase 4.

 ### Progressive Mode - Layer Record

@@ -133,12 +137,14 @@ Phase 3: Record Enhancement & Validation
 ├─ Validate dependency graph (no cycles)
 ├─ Progressive: verify scope coverage (no overlap, no gaps)
 ├─ Direct: verify inputs/outputs chain, assign parallel_groups
-└─ Generate roadmap.jsonl
+└─ Finalize internal records

-Phase 4: Human-Readable Output
-├─ Generate roadmap.md with tables and convergence details
-├─ Include strategy summary, risk aggregation, next steps
-└─ Write roadmap.md
+Phase 4: Issue Creation & Output Generation           ← ⭐ Core change
+├─ 4a: Internal records → issue data mapping
+├─ 4b: ccw issue create for each item (get formal ISS-xxx IDs)
+├─ 4c: Generate execution-plan.json (waves + dependencies)
+├─ 4d: Generate issues.jsonl session copy
+└─ 4e: Generate roadmap.md with issue ID references

 Phase 5: Decomposition Quality Check (MANDATORY)
 ├─ Execute CLI quality check using Gemini (Qwen fallback)
@@ -556,16 +562,207 @@ function topologicalSort(tasks) {
 }
 ```

-### JSONL & Markdown Generation
+### Phase 4: Issue Creation & Output Generation
+
+#### 4a: Internal Records → Issue Data Mapping

 ```javascript
-// Generate roadmap.jsonl
-function generateJsonl(records) {
-  return records.map(record => JSON.stringify(record)).join('\n') + '\n'
+// Progressive mode: layer → issue data (issues-jsonl-schema)
+function layerToIssue(layer, sessionId, timestamp) {
+  const context = `## Goal\n${layer.goal}\n\n` +
+    `## Scope\n${layer.scope.map(s => `- ${s}`).join('\n')}\n\n` +
+    `## Excludes\n${layer.excludes.map(s => `- ${s}`).join('\n') || 'None'}\n\n` +
+    `## Convergence Criteria\n${layer.convergence.criteria.map(c => `- ${c}`).join('\n')}\n\n` +
+    `## Verification\n${layer.convergence.verification}\n\n` +
+    `## Definition of Done\n${layer.convergence.definition_of_done}\n\n` +
+    (layer.risks.length ? `## Risks\n${layer.risks.map(r => `- ${r.description} (P:${r.probability} I:${r.impact})`).join('\n')}` : '')
+
+  const effortToPriority = { small: 4, medium: 3, large: 2 }
+
+  return {
+    title: `[${layer.name}] ${layer.goal}`,
+    context: context,
+    priority: effortToPriority[layer.effort] || 3,
+    source: "text",
+    tags: ["req-plan", "progressive", layer.name.toLowerCase(), `wave-${getWaveNum(layer)}`],
+    affected_components: [],
+    extended_context: {
+      notes: JSON.stringify({
+        session: sessionId,
+        strategy: "progressive",
+        layer: layer.id,
+        wave: getWaveNum(layer),
+        effort: layer.effort,
+        depends_on_issues: [],    // Backfilled after all issues created
+        original_id: layer.id
+      })
+    },
+    lifecycle_requirements: {
+      test_strategy: "integration",
+      regression_scope: "affected",
+      acceptance_type: "automated",
+      commit_strategy: "per-task"
+    }
+  }
 }

+// Helper: get wave number from layer
+function getWaveNum(layer) {
+  const match = layer.id.match(/L(\d+)/)
+  return match ? parseInt(match[1]) + 1 : 1
+}
+
+// Direct mode: task → issue data (issues-jsonl-schema)
+function taskToIssue(task, sessionId, timestamp) {
+  const context = `## Scope\n${task.scope}\n\n` +
+    `## Inputs\n${task.inputs.length ? task.inputs.map(i => `- ${i}`).join('\n') : 'None (starting task)'}\n\n` +
+    `## Outputs\n${task.outputs.map(o => `- ${o}`).join('\n')}\n\n` +
+    `## Convergence Criteria\n${task.convergence.criteria.map(c => `- ${c}`).join('\n')}\n\n` +
+    `## Verification\n${task.convergence.verification}\n\n` +
+    `## Definition of Done\n${task.convergence.definition_of_done}`
+
+  return {
+    title: `[${task.type}] ${task.title}`,
+    context: context,
+    priority: 3,
+    source: "text",
+    tags: ["req-plan", "direct", task.type, `wave-${task.parallel_group}`],
+    affected_components: task.outputs,
+    extended_context: {
+      notes: JSON.stringify({
+        session: sessionId,
+        strategy: "direct",
+        task_id: task.id,
+        wave: task.parallel_group,
+        parallel_group: task.parallel_group,
+        depends_on_issues: [],    // Backfilled after all issues created
+        original_id: task.id
+      })
+    },
+    lifecycle_requirements: {
+      test_strategy: task.type === 'testing' ? 'unit' : 'integration',
+      regression_scope: "affected",
+      acceptance_type: "automated",
+      commit_strategy: "per-task"
+    }
+  }
+}
+```
+
+#### 4b: Create Issues via ccw issue create
+
+```javascript
+// Create issues sequentially (get formal ISS-xxx IDs)
+const issueIdMap = {}  // originalId → ISS-xxx
+
+for (const record of records) {
+  const issueData = selected_mode === 'progressive'
+    ? layerToIssue(record, sessionId, timestamp)
+    : taskToIssue(record, sessionId, timestamp)
+
+  // Create issue via ccw issue create (heredoc to avoid escaping)
+  const createResult = Bash(`ccw issue create --data '${JSON.stringify(issueData)}' --json`)
+
+  const created = JSON.parse(createResult.trim())
+  issueIdMap[record.id] = created.id
+}
+
+// Backfill depends_on_issues into extended_context.notes
+for (const record of records) {
+  const issueId = issueIdMap[record.id]
+  const deps = record.depends_on.map(d => issueIdMap[d]).filter(Boolean)
+  if (deps.length > 0) {
+    const notes = JSON.stringify({
+      ...JSON.parse(/* read current notes from issue */),
+      depends_on_issues: deps
+    })
+    Bash(`ccw issue update ${issueId} --notes '${notes}'`)
+  }
+}
+```
+
+#### 4c: Generate execution-plan.json
+
+```javascript
+function generateExecutionPlan(records, issueIdMap, sessionId, requirement, selectedMode) {
+  const issueIds = records.map(r => issueIdMap[r.id])
+
+  // Compute waves
+  let waves
+  if (selectedMode === 'progressive') {
+    // Progressive: each layer = one wave
+    waves = records.map((r, i) => ({
+      wave: i + 1,
+      label: r.name,
+      issue_ids: [issueIdMap[r.id]],
+      depends_on_waves: r.depends_on.length > 0
+        ? [...new Set(r.depends_on.map(d => records.findIndex(x => x.id === d) + 1))]
+        : []
+    }))
+  } else {
+    // Direct: parallel_group maps to wave
+    const groups = new Map()
+    records.forEach(r => {
+      const g = r.parallel_group
+      if (!groups.has(g)) groups.set(g, [])
+      groups.get(g).push(r)
+    })
+
+    waves = [...groups.entries()]
+      .sort(([a], [b]) => a - b)
+      .map(([groupNum, groupRecords]) => ({
+        wave: groupNum,
+        label: `Group ${groupNum}`,
+        issue_ids: groupRecords.map(r => issueIdMap[r.id]),
+        depends_on_waves: groupNum > 1
+          ? [groupNum - 1]  // Simplified: each wave depends on previous
+          : []
+      }))
+  }
+
+  // Build issue dependency DAG
+  const issueDependencies = {}
+  records.forEach(r => {
+    const deps = r.depends_on.map(d => issueIdMap[d]).filter(Boolean)
+    if (deps.length > 0) {
+      issueDependencies[issueIdMap[r.id]] = deps
+    }
+  })
+
+  return {
+    session_id: sessionId,
+    requirement: requirement,
+    strategy: selectedMode,
+    created_at: new Date().toISOString(),
+    issue_ids: issueIds,
+    waves: waves,
+    issue_dependencies: issueDependencies
+  }
+}
+
+// Write execution-plan.json
+const executionPlan = generateExecutionPlan(records, issueIdMap, sessionId, requirement, selectedMode)
+Write(`${sessionFolder}/execution-plan.json`, JSON.stringify(executionPlan, null, 2))
+```
+
+#### 4d: Generate issues.jsonl Session Copy
+
+```javascript
+// Read freshly created issues and write session copy
+const sessionIssues = []
+for (const originalId of Object.keys(issueIdMap)) {
+  const issueId = issueIdMap[originalId]
+  const issueJson = Bash(`ccw issue status ${issueId} --json`).trim()
+  sessionIssues.push(issueJson)
+}
+Write(`${sessionFolder}/issues.jsonl`, sessionIssues.join('\n') + '\n')
+```
+
+#### 4e: Roadmap Markdown Generation (with Issue ID References)
+
+```javascript
 // Generate roadmap.md for progressive mode
-function generateProgressiveRoadmapMd(layers, input) {
+function generateProgressiveRoadmapMd(layers, issueIdMap, input) {
  return `# 需求路线图

 **Session**: ${input.session.id}
@@ -582,13 +779,19 @@ function generateProgressiveRoadmapMd(layers, input) {

 ## 路线图概览

-| 层级 | 名称 | 目标 | 工作量 | 依赖 |
-|------|------|------|--------|------|
-${layers.map(l => `| ${l.id} | ${l.name} | ${l.goal} | ${l.effort} | ${l.depends_on.length ? l.depends_on.join(', ') : '-'} |`).join('\n')}
+| 层级 | 名称 | 目标 | 工作量 | 依赖 | Issue ID |
+|------|------|------|--------|------|----------|
+${layers.map(l => `| ${l.id} | ${l.name} | ${l.goal} | ${l.effort} | ${l.depends_on.length ? l.depends_on.join(', ') : '-'} | ${issueIdMap[l.id]} |`).join('\n')}
+
+## Issue Mapping
+
+| Wave | Issue ID | Title | Priority |
+|------|----------|-------|----------|
+${layers.map(l => `| ${getWaveNum(l)} | ${issueIdMap[l.id]} | [${l.name}] ${l.goal} | ${({small: 4, medium: 3, large: 2})[l.effort] || 3} |`).join('\n')}

 ## 各层详情

-${layers.map(l => `### ${l.id}: ${l.name}
+${layers.map(l => `### ${l.id}: ${l.name} (${issueIdMap[l.id]})

 **目标**: ${l.goal}

@@ -597,32 +800,47 @@ ${layers.map(l => `### ${l.id}: ${l.name}
 **排除**: ${l.excludes.join('、') || '无'}

 **收敛标准**:
-${l.convergence.criteria.map(c => `- ✅ ${c}`).join('\n')}
- 🔍 **验证方法**: ${l.convergence.verification}
- 🎯 **完成定义**: ${l.convergence.definition_of_done}
+${l.convergence.criteria.map(c => `- ${c}`).join('\n')}
+- **验证方法**: ${l.convergence.verification}
+- **完成定义**: ${l.convergence.definition_of_done}

-**风险项**: ${l.risks.length ? l.risks.map(r => `\n- ⚠️ ${r.description} (概率: ${r.probability}, 影响: ${r.impact}, 缓解: ${r.mitigation})`).join('') : '无'}
+**风险项**: ${l.risks.length ? l.risks.map(r => `\n- ${r.description} (概率: ${r.probability}, 影响: ${r.impact}, 缓解: ${r.mitigation})`).join('') : '无'}

 **工作量**: ${l.effort}
 `).join('\n---\n\n')}

 ## 风险汇总

-${layers.flatMap(l => l.risks.map(r => `- **${l.id}**: ${r.description} (概率: ${r.probability}, 影响: ${r.impact})`)).join('\n') || '无已识别风险'}
+${layers.flatMap(l => l.risks.map(r => `- **${l.id}** (${issueIdMap[l.id]}): ${r.description} (概率: ${r.probability}, 影响: ${r.impact})`)).join('\n') || '无已识别风险'}

-## 下一步
+## Next Steps

-每个层级可独立执行：
-\`\`\`bash
-/workflow:lite-plan "${layers[0]?.name}: ${layers[0]?.scope.join(', ')}"
+### 使用 team-planex 执行全部波次
+\`\`\`
+Skill(skill="team-planex", args="--plan ${input.session.folder}/execution-plan.json")
 \`\`\`

-路线图 JSONL 文件: \`${input.session.folder}/roadmap.jsonl\`
+### 按波次逐步执行
+\`\`\`
+${layers.map(l => `# Wave ${getWaveNum(l)}: ${l.name}\nSkill(skill="team-planex", args="${issueIdMap[l.id]}")`).join('\n')}
+\`\`\`
+
+路线图文件: \`${input.session.folder}/\`
+- issues.jsonl (标准 issue 格式)
+- execution-plan.json (波次编排)
 `
 }

 // Generate roadmap.md for direct mode
-function generateDirectRoadmapMd(tasks, input) {
+function generateDirectRoadmapMd(tasks, issueIdMap, input) {
+  // Group tasks by parallel_group for wave display
+  const groups = new Map()
+  tasks.forEach(t => {
+    const g = t.parallel_group
+    if (!groups.has(g)) groups.set(g, [])
+    groups.get(g).push(t)
+  })
+
  return `# 需求路线图

 **Session**: ${input.session.id}
@@ -637,13 +855,19 @@ function generateDirectRoadmapMd(tasks, input) {

 ## 任务序列

-| 组 | ID | 标题 | 类型 | 依赖 |
-|----|-----|------|------|------|
-${tasks.map(t => `| ${t.parallel_group} | ${t.id} | ${t.title} | ${t.type} | ${t.depends_on.length ? t.depends_on.join(', ') : '-'} |`).join('\n')}
+| 组 | ID | 标题 | 类型 | 依赖 | Issue ID |
+|----|-----|------|------|------|----------|
+${tasks.map(t => `| ${t.parallel_group} | ${t.id} | ${t.title} | ${t.type} | ${t.depends_on.length ? t.depends_on.join(', ') : '-'} | ${issueIdMap[t.id]} |`).join('\n')}
+
+## Issue Mapping
+
+| Wave | Issue ID | Title | Priority |
+|------|----------|-------|----------|
+${tasks.map(t => `| ${t.parallel_group} | ${issueIdMap[t.id]} | [${t.type}] ${t.title} | 3 |`).join('\n')}

 ## 各任务详情

-${tasks.map(t => `### ${t.id}: ${t.title}
+${tasks.map(t => `### ${t.id}: ${t.title} (${issueIdMap[t.id]})

 **类型**: ${t.type} | **并行组**: ${t.parallel_group}

@@ -653,19 +877,28 @@ ${tasks.map(t => `### ${t.id}: ${t.title}
 **输出**: ${t.outputs.join(', ')}

 **收敛标准**:
-${t.convergence.criteria.map(c => `- ✅ ${c}`).join('\n')}
- 🔍 **验证方法**: ${t.convergence.verification}
- 🎯 **完成定义**: ${t.convergence.definition_of_done}
+${t.convergence.criteria.map(c => `- ${c}`).join('\n')}
+- **验证方法**: ${t.convergence.verification}
+- **完成定义**: ${t.convergence.definition_of_done}
 `).join('\n---\n\n')}

-## 下一步
+## Next Steps

-每个任务可独立执行：
-\`\`\`bash
-/workflow:lite-plan "${tasks[0]?.title}: ${tasks[0]?.scope}"
+### 使用 team-planex 执行全部波次
+\`\`\`
+Skill(skill="team-planex", args="--plan ${input.session.folder}/execution-plan.json")
 \`\`\`

-路线图 JSONL 文件: \`${input.session.folder}/roadmap.jsonl\`
+### 按波次逐步执行
+\`\`\`
+${[...groups.entries()].sort(([a], [b]) => a - b).map(([g, ts]) =>
+  `# Wave ${g}: Group ${g}\nSkill(skill="team-planex", args="${ts.map(t => issueIdMap[t.id]).join(' ')}")`
+).join('\n')}
+\`\`\`
+
+路线图文件: \`${input.session.folder}/\`
+- issues.jsonl (标准 issue 格式)
+- execution-plan.json (波次编排)
 `
 }
 ```
@@ -731,17 +964,17 @@ function manualDirectDecomposition(requirement, context) {

 ### Overview

-After generating roadmap.jsonl, **MUST** execute CLI quality check before returning to orchestrator.
+After creating issues and generating output files, **MUST** execute CLI quality check before returning to orchestrator.

 ### Quality Dimensions

 | Dimension | Check Criteria | Critical? |
 |-----------|---------------|-----------|
-| **Requirement Coverage** | All aspects of original requirement addressed in layers/tasks | Yes |
+| **Requirement Coverage** | All aspects of original requirement addressed in issues | Yes |
 | **Convergence Quality** | criteria testable, verification executable, DoD business-readable | Yes |
 | **Scope Integrity** | Progressive: no overlap/gaps; Direct: inputs/outputs chain valid | Yes |
-| **Dependency Correctness** | No circular deps, proper ordering | Yes |
-| **Effort Balance** | No single layer/task disproportionately large | No |
+| **Dependency Correctness** | No circular deps, proper ordering, issue dependencies match | Yes |
+| **Effort Balance** | No single issue disproportionately large | No |

 ### CLI Quality Check Command

@@ -753,14 +986,17 @@ Success: All quality dimensions pass
 ORIGINAL REQUIREMENT:
 ${requirement}

-ROADMAP (${selected_mode} mode):
-${roadmapJsonlContent}
+ISSUES CREATED (${selected_mode} mode):
+${issuesJsonlContent}
+
+EXECUTION PLAN:
+${JSON.stringify(executionPlan, null, 2)}

 TASK:
-• Requirement Coverage: Does the roadmap address ALL aspects of the requirement?
+• Requirement Coverage: Does the decomposition address ALL aspects of the requirement?
 • Convergence Quality: Are criteria testable? Is verification executable? Is DoD business-readable?
 • Scope Integrity: ${selected_mode === 'progressive' ? 'No scope overlap between layers, no feature gaps' : 'Inputs/outputs chain is valid, parallel groups are correct'}
-• Dependency Correctness: No circular dependencies
+• Dependency Correctness: No circular dependencies, wave ordering correct
 • Effort Balance: No disproportionately large items

 MODE: analysis
@@ -791,10 +1027,10 @@ CONSTRAINTS: Read-only validation, do not modify files
 |-----------|----------------|
 | Vague criteria | Replace with specific, testable conditions |
 | Technical DoD | Rewrite in business language |
-| Missing scope items | Add to appropriate layer/task |
+| Missing scope items | Add to appropriate issue context |
 | Effort imbalance | Suggest split (report to orchestrator) |

-After fixes, update `roadmap.jsonl` and `roadmap.md`.
+After fixes, update issues via `ccw issue update` and regenerate `issues.jsonl` + `roadmap.md`.

 ## Error Handling

@@ -812,19 +1048,36 @@ try {
      : manualDirectDecomposition(requirement, exploration_context)
  }
 }
+
+// Issue creation failure: retry once, then skip and report
+for (const record of records) {
+  try {
+    // create issue...
+  } catch (error) {
+    try {
+      // retry once...
+    } catch {
+      // Log error, skip this record, continue with remaining
+    }
+  }
+}
 ```

 ## Key Reminders

 **ALWAYS**:
 - Parse CLI output into structured records with full convergence fields
- Validate all records against schema before writing JSONL
+- Validate all records against schema before creating issues
 - Check for circular dependencies
 - Ensure convergence criteria are testable (not vague)
 - Ensure verification is executable (commands or explicit steps)
 - Ensure definition_of_done uses business language
+- Create issues via `ccw issue create` (get formal ISS-xxx IDs)
+- Generate execution-plan.json with correct wave groupings
+- Generate issues.jsonl session copy
+- Generate roadmap.md with issue ID references
 - Run Phase 5 quality check before returning
- Write both roadmap.jsonl AND roadmap.md
+- Write all three output files: issues.jsonl, execution-plan.json, roadmap.md

 **Bash Tool**:
 - Use `run_in_background=false` for all Bash/CLI calls
@@ -834,4 +1087,5 @@ try {
 - Create circular dependencies
 - Skip convergence validation
 - Skip Phase 5 quality check
- Return without writing both output files
+- Return without writing all three output files
+- Generate roadmap.jsonl (deprecated, replaced by issues.jsonl + execution-plan.json)