roadmap-with-file

自动模式

使用 --yes 或 -y 时：自动确认策略选择，使用推荐模式，跳过交互式细化轮次。此技能仅用于规划——绝不会执行代码或修改源文件。输出路线图和问题，供用户审核。

带文件的路线图技能

用法

$roadmap-with-file "Implement user authentication system with OAuth and 2FA"
$roadmap-with-file -m progressive "Build real-time notification system"
$roadmap-with-file -m direct "Refactor payment module"
$roadmap-with-file -m auto "Add data export feature"
$roadmap-with-file --continue "auth system"
$roadmap-with-file -y "Implement caching layer"

标志：

• -y, --yes：跳过所有确认（自动模式）
• -c, --continue：继续现有会话
• -m, --mode：策略选择（progressive / direct / auto）

上下文来源：cli-explore-agent（可选）+ 需求分析 输出目录：.workflow/.roadmap/{session-id}/ 核心输出：roadmap.md（单一来源，便于人类阅读）+ issues.jsonl（全局、可供机器执行）

---

子 Agent API 参考

spawn_agent

创建新的子 Agent 并分配任务。

const agentId = spawn_agent({
  agent_type: "{agent_type}",
  message: `
## TASK ASSIGNMENT

### MANDATORY FIRST STEPS (Agent Execute)
1. Read: .workflow/project-tech.json
2. Read: .workflow/project-guidelines.json

## TASK CONTEXT
${taskContext}

## DELIVERABLES
${deliverables}
`
})

wait_agent

获取子 Agent 的结果（获取结果的唯一方式）。

const result = wait_agent({
  timeout_ms: 1800000  // 30 minutes
})

if (result.timed_out) {
  // Handle timeout via 4-step cascade: status probe → force finalize → close
}

followup_task

为活动子 Agent 分配新任务（用于澄清或后续跟进）。

followup_task({
  target: agentId,
  message: `
## CLARIFICATION ANSWERS
${answers}

## NEXT STEP
Continue with plan generation.
`
})

close_agent

清理子 Agent 资源（不可逆）。

close_agent({ target: agentId })

---

输出产物

单一事实来源

产物	用途	使用方
roadmap.md	⭐ 包含所有上下文、便于人类阅读的战略路线图	人工审核、移交给 csv-wave-pipeline
.workflow/issues/issues.jsonl	全局问题存储（追加写入）	csv-wave-pipeline、问题命令

为什么不使用单独的 JSON 文件？

原始文件	移除原因	内容存放位置
strategy-assessment.json	与 roadmap.md 内容重复	嵌入 roadmap.md 的策略评估部分
exploration-codebase.json	仅使用一次的中间文件	嵌入 roadmap.md 的代码库上下文附录

---

概述

通过迭代式分解制定战略需求路线图。创建单个 roadmap.md，在讨论中不断完善，并将问题保存到全局 issues.jsonl，以供执行。

核心工作流：理解 → 分解 → 迭代 → 验证 → 移交

主要功能：

• roadmap.md：单一事实来源，包含策略、路线图、收敛情况和迭代历史
• 双模式分解：渐进式（MVP→优化）或直接式（拓扑任务）
• 外部调研：通过 web.run 搜索架构模式和最佳实践
• 创建问题：将问题保存到全局 issues.jsonl，以供执行流水线使用
• 进度跟踪：使用 functions.update_plan 实时查看各阶段进度
• 决策记录：记录包含上下文和理由的结构化决策轨迹
• 结构化移交：在终端关卡中进行执行规划、查看问题或完成流程

┌─────────────────────────────────────────────────────────────────────────┐
│                    ROADMAP ITERATIVE WORKFLOW                            │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Session Init                                                            │
│     ├─ Parse flags, generate session ID                                  │
│     ├─ functions.exec_command (mkdir session folder)                      │
│     └─ functions.update_plan (5 phases: Understand → Decompose →         │
│        Refine → Handoff → GATE)                                          │
│                                                                          │
│  Phase 1: Requirement Understanding & Strategy                           │
│     ├─ Parse requirement: goal / constraints / stakeholders              │
│     ├─ Assess uncertainty level → recommend mode                         │
│     ├─ User confirms strategy via functions.request_user_input           │
│     └─ Initialize roadmap.md with Strategy Assessment                    │
│                                                                          │
│  Phase 2: Decomposition & Issue Creation                                 │
│     ├─ Optional codebase exploration (functions.exec_command detection)   │
│     ├─ cli-roadmap-plan-agent executes decomposition                     │
│     ├─ Progressive: 2-4 layers (MVP→Optimized) with convergence          │
│     ├─ Direct: Topological task sequence with convergence                │
│     ├─ Create issues via ccw issue create → issues.jsonl                 │
│     └─ Update roadmap.md with Roadmap table + Issue references           │
│                                                                          │
│  Phase 3: Iterative Refinement (Multi-Round, Decision Recording)         │
│     ├─ Present roadmap to user (Cumulative Context)                      │
│     ├─ Feedback via functions.request_user_input:                        │
│     │   Approve | Adjust Scope | Refine Criteria | Research/Re-decompose │
│     ├─ External research via web.run (optional — patterns, practices)    │
│     ├─ Record decisions in Iteration History (Record-Before-Continue)     │
│     └─ Repeat until approved (max 5 rounds)                              │
│                                                                          │
│  Phase 4: Handoff (PLANNING ENDS HERE)                                   │
│     ├─ Final roadmap.md with Issue ID references                         │
│     └─ MANDATORY Terminal Gate: 执行计划 / 查看Issue / 完成              │
│         ├─ Execute Plan → display csv-wave-pipeline command               │
│         ├─ View Issues → ccw issue list                                  │
│         └─ Done → end workflow                                           │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

---

双模式

模式	策略	适用场景	分解方式
渐进式	MVP → 可用 → 精炼 → 优化	不确定性高，需要验证	2-4 层，每层都完整收敛
直接式	拓扑任务序列	需求明确，技术方案已确认	明确标注输入/输出的任务

自动选择逻辑：

• ≥3 个高不确定性因素 → 渐进式
• ≥3 个低不确定性因素 → 直接式
• 其他情况 → 询问用户偏好

---

输出结构

.workflow/.roadmap/RMAP-{date}-{slug}/
└── roadmap.md                  # ⭐ Single source of truth
                                #   - Strategy Assessment (embedded)
                                #   - Roadmap Table
                                #   - Convergence Criteria per Issue
                                #   - Codebase Context (appendix, if applicable)
                                #   - Iteration History

.workflow/issues/issues.jsonl   # Global issue store (appended)
                                #   - One JSON object per line
                                #   - Consumed by csv-wave-pipeline, issue commands

---

roadmap.md 模板

# Requirement Roadmap

**Session**: RMAP-{date}-{slug}
**Requirement**: {requirement}
**Strategy**: {progressive|direct}
**Status**: {Planning|Refining|Ready}
**Created**: {timestamp}

---

## Strategy Assessment

- **Uncertainty Level**: {high|medium|low}
- **Decomposition Mode**: {progressive|direct}
- **Assessment Basis**: {factors summary}
- **Goal**: {extracted goal}
- **Constraints**: {extracted constraints}
- **Stakeholders**: {extracted stakeholders}

---

## Roadmap

### Progressive Mode
| Wave | Issue ID | Layer | Goal | Priority | Dependencies |
|------|----------|-------|------|----------|--------------|
| 1 | ISS-xxx | MVP | ... | 2 | - |
| 2 | ISS-yyy | Usable | ... | 3 | ISS-xxx |

### Direct Mode
| Wave | Issue ID | Title | Type | Dependencies |
|------|----------|-------|------|--------------|
| 1 | ISS-xxx | ... | infrastructure | - |
| 2 | ISS-yyy | ... | feature | ISS-xxx |

---

## Convergence Criteria

### ISS-xxx: {Issue Title}
- **Criteria**: [testable conditions]
- **Verification**: [executable steps/commands]
- **Definition of Done**: [business language, non-technical]

### ISS-yyy: {Issue Title}
...

---

## Risks

| Risk | Severity | Mitigation |
|------|----------|------------|
| ... | ... | ... |

---

## Iteration History

### Round 1 - {timestamp}
**User Feedback**: {feedback summary}
**Changes Made**: {adjustments}
**Status**: {approved|continue iteration}

---

## Codebase Context (Optional)

*Included when codebase exploration was performed*

- **Relevant Modules**: [...]
- **Existing Patterns**: [...]
- **Integration Points**: [...]

---

Issues JSONL 规范

位置与格式

Path: .workflow/issues/issues.jsonl
Format: JSONL (one complete JSON object per line)
Encoding: UTF-8
Mode: Append-only (new issues appended to end)

记录架构

{
  "id": "ISS-YYYYMMDD-NNN",
  "title": "[LayerName] goal or [TaskType] title",
  "status": "pending",
  "priority": 2,
  "context": "Markdown with goal, scope, convergence, verification, DoD",
  "source": "text",
  "tags": ["roadmap", "progressive|direct", "wave-N", "layer-name"],
  "extended_context": {
    "notes": {
      "session": "RMAP-{date}-{slug}",
      "strategy": "progressive|direct",
      "wave": 1,
      "depends_on_issues": []
    }
  },
  "lifecycle_requirements": {
    "test_strategy": "unit",
    "regression_scope": "affected",
    "acceptance_type": "automated",
    "commit_strategy": "per-issue"
  }
}

查询接口

# By ID (detail view)
ccw issue list ISS-20260227-001

# List all with status filter
ccw issue list --status planned,queued
ccw issue list --brief  # JSON minimal output

# Queue operations (wave-based execution)
ccw issue queue list              # List all queues
ccw issue queue dag               # Get dependency graph (JSON)
ccw issue next --queue <queue-id> # Get next task

# Execute
ccw issue queue add <issue-id>    # Add to active queue
ccw issue done <item-id>          # Mark completed

注意：问题会在 tags[] 字段中标记为 wave-N，以便筛选。以编程方式解析时，请使用 --brief。

---

实现

会话初始化

const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()

// Parse flags
const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
const continueMode = $ARGUMENTS.includes('--continue') || $ARGUMENTS.includes('-c')
const modeMatch = $ARGUMENTS.match(/(?:--mode|-m)\s+(progressive|direct|auto)/)
const requestedMode = modeMatch ? modeMatch[1] : 'auto'

// Clean requirement text (remove flags)
const requirement = $ARGUMENTS
  .replace(/--yes|-y|--continue|-c|--mode\s+\w+|-m\s+\w+/g, '')
  .trim()

const slug = requirement.toLowerCase()
  .replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-')
  .substring(0, 40)
const dateStr = getUtc8ISOString().substring(0, 10)
const sessionId = `RMAP-${dateStr}-${slug}`
const sessionFolder = `.workflow/.roadmap/${sessionId}`

// Auto-detect continue mode
if (continueMode || file_exists(`${sessionFolder}/roadmap.md`)) {
  // Resume existing session
  const existingRoadmap = Read(`${sessionFolder}/roadmap.md`)
  // Extract current phase and continue from there
}

functions.exec_command(`mkdir -p ${sessionFolder}`)

// Initialize progress tracking (MANDATORY)
functions.update_plan([
  { id: "phase-1", title: "Phase 1: Requirement Understanding & Strategy", status: "in_progress" },
  { id: "phase-2", title: "Phase 2: Decomposition & Issue Creation", status: "pending" },
  { id: "phase-3", title: "Phase 3: Iterative Refinement", status: "pending" },
  { id: "phase-4", title: "Phase 4: Handoff", status: "pending" },
  { id: "next-step", title: "GATE: Post-Completion Next Step", status: "pending" }
])

---

阶段 1：需求理解与策略选择

目标：解析需求、评估不确定性、选择分解策略，并初始化 roadmap.md。

步骤：

1. 解析需求

   • 提取：目标、约束、利益相关方、关键词

2. 评估不确定性

   const uncertaintyFactors = {
     scope_clarity: 'low|medium|high',
     technical_risk: 'low|medium|high',
     dependency_unknown: 'low|medium|high',
     domain_familiarity: 'low|medium|high',
     requirement_stability: 'low|medium|high'
   }
   
   // Calculate recommendation
   const highCount = Object.values(uncertaintyFactors).filter(v => v === 'high').length
   const lowCount = Object.values(uncertaintyFactors).filter(v => v === 'low').length
   
   let recommendedMode
   if (highCount >= 3) recommendedMode = 'progressive'
   else if (lowCount >= 3) recommendedMode = 'direct'
   else recommendedMode = 'progressive'  // default safer choice
   

3. 选择策略（如果指定了 -m 或 AUTO_YES，则跳过）

   let selectedMode
   
   if (requestedMode !== 'auto') {
     selectedMode = requestedMode
   } else if (AUTO_YES) {
     selectedMode = recommendedMode
   } else {
     const answer = functions.request_user_input({
       questions: [{
         header: "Strategy",   // max 12 chars
         question: `Decomposition strategy: Uncertainty=${uncertaintyLevel}, Recommended=${recommendedMode}`,
         multiSelect: false,
         options: [
           { label: recommendedMode === 'progressive' ? "Progressive (Recommended)" : "Progressive", description: "MVP → Usable → Refined → Optimized layers" },
           { label: recommendedMode === 'direct' ? "Direct (Recommended)" : "Direct", description: "Topological task sequence" }
         ]
       }]
     })
   
     selectedMode = answer // parsed from user selection
   }
   

4. 初始化 roadmap.md

   const roadmapContent = `# Requirement Roadmap
   

Session: ${sessionId} Requirement: ${requirement} Strategy: ${selectedMode} Status: Planning Created: ${getUtc8ISOString()}

---

Strategy Assessment

• Uncertainty Level: ${uncertaintyLevel}
• Decomposition Mode: ${selectedMode}
• Assessment Basis: ${factorsSummary}
• Goal: ${extractedGoal}
• Constraints: ${extractedConstraints}
• Stakeholders: ${extractedStakeholders}

---

Roadmap

To be populated after Phase 2 decomposition

---

Convergence Criteria Details

To be populated after Phase 2 decomposition

---

Risks

To be populated after Phase 2 decomposition

---

Iteration History

To be populated during Phase 3 refinement

---

Codebase Context (Optional)

To be populated if codebase exploration was performed `

Write(${sessionFolder}/roadmap.md, roadmapContent)

**成功标准**：
- 已创建包含策略评估的 roadmap.md
- 已选择策略（渐进式或直接式）
- 已记录不确定性因素

---

### 阶段 2：分解与创建 Issue

**目标**：通过 `cli-roadmap-plan-agent` 执行分解、创建 Issue 并更新 roadmap.md。

**步骤**：

1. **可选的代码库探索**（如果检测到代码库）
```javascript
// Update progress
functions.update_plan([{ id: "phase-2", title: "Phase 2: Decomposition & Issue Creation", status: "in_progress" }])

const hasCodebase = functions.exec_command(`
  test -f package.json && echo "nodejs" ||
  test -f go.mod && echo "golang" ||
  test -f Cargo.toml && echo "rust" ||
  test -f pyproject.toml && echo "python" ||
  test -d src && echo "generic" ||
  echo "none"
`).trim()

let codebaseContext = null

if (hasCodebase !== 'none') {
  const exploreAgentId = spawn_agent({
    agent_type: "cli_explore_agent",
    message: `
## TASK ASSIGNMENT

### MANDATORY FIRST STEPS (Agent Execute)
1. Read: .workflow/project-tech.json
2. Read: .workflow/project-guidelines.json

---

## Exploration Context
- **Requirement**: ${requirement}
- **Strategy**: ${selectedMode}
- **Project Type**: ${hasCodebase}
- **Session**: ${sessionFolder}

## Exploration Focus
- Identify modules/components related to the requirement
- Find existing patterns that should be followed
- Locate integration points for new functionality
- Assess current architecture constraints

## Output
Return findings as JSON with schema:
{
"project_type": "${hasCodebase}",
"relevant_modules": [{name, path, relevance}],
"existing_patterns": [{pattern, files, description}],
"integration_points": [{location, description, risk}],
"architecture_constraints": [string],
"tech_stack": {languages, frameworks, tools}
}
`
  })

  const exploreResult = wait_agent({
    timeout_ms: 1800000  // 30 minutes
  })

  close_agent({ target: exploreAgentId })

  if (exploreResult.status[exploreAgentId].completed) {
    codebaseContext = exploreResult.status[exploreAgentId].completed
  }
}

2. 执行分解 Agent

   const decompositionAgentId = spawn_agent({
     agent_type: "cli_roadmap_plan_agent",
     message: `
   

TASK ASSIGNMENT

MANDATORY FIRST STEPS (Agent Execute)

1. Read: .workflow/project-tech.json
2. Read: .workflow/project-guidelines.json

---

Roadmap Decomposition Task

Input Context

• Requirement: ${requirement}
• Selected Mode: ${selectedMode}
• Session ID: ${sessionId}
• Session Folder: ${sessionFolder}

Strategy Assessment

${JSON.stringify(strategyAssessment, null, 2)}

Codebase Context

${codebaseContext ? JSON.stringify(codebaseContext, null, 2) : 'No codebase detected - pure requirement decomposition'}

---

Mode-Specific Requirements

${selectedMode === 'progressive' ? `Progressive Mode:

• 2-4 layers from MVP to full implementation
• Each layer: id (L0-L3), name, goal, scope, excludes, convergence, risks, effort, depends_on
• L0 (MVP) must be a self-contained closed loop with no dependencies
• Scope: each feature belongs to exactly ONE layer (no overlap)
• Layer names: MVP / Usable / Refined / Optimized` :

`Direct Mode:

• Topologically-sorted task sequence
• Each task: id (T1-Tn), title, type, scope, inputs, outputs, convergence, depends_on, parallel_group
• Inputs must come from preceding task outputs or existing resources
• Tasks in same parallel_group must be truly independent`}

---

Convergence Quality Requirements

• criteria[]: MUST be testable (can write assertions or manual verification steps)
• verification: MUST be executable (command, script, or explicit steps)
• definition_of_done: MUST use business language (non-technical person can judge)

---

Expected Output

1. Update ${sessionFolder}/roadmap.md with Roadmap table + Convergence sections
2. Create issues via ccw issue create - append to .workflow/issues/issues.jsonl

Issue Format (for ccw issue create)

• id: ISS-YYYYMMDD-NNN (auto-generated)
• title: [LayerName] goal or [TaskType] title
• context: Markdown with goal, scope, convergence criteria, verification, DoD
• priority: small→4, medium→3, large→2
• tags: ["roadmap", mode, wave-N, layer-name]
• extended_context.notes: {session, strategy, wave, depends_on_issues}

Execution Steps

1. Analyze requirement and build decomposition context

2. Execute decomposition (internal reasoning)

3. Validate records, check convergence quality

4. For each decomposed item:

   • Run: ccw issue create --title "..." --context "..." --tags "..." --priority N
   • Record returned Issue ID

5. Update roadmap.md with Issue ID references

6. Return brief completion summary with Issue IDs ` })

   const decompositionResult = wait_agent({ timeout_ms: 1800000 // 30 minutes for complex decomposition })

   close_agent({ target: decompositionAgentId })

   if (!decompositionResult.status[decompositionAgentId].completed) { throw new Error('Decomposition agent failed to complete') }

   const issueIds = decompositionResult.status[decompositionAgentId].completed.issueIds || []

成功标准：

• 已在 .workflow/issues/issues.jsonl 中创建 Issue
• roadmap.md 已更新并包含 Issue 引用
• 不存在循环依赖
• 收敛标准可测试

---

阶段 3：迭代优化

目标：通过多轮用户反馈优化路线图。

累积上下文规则：每轮展示时必须包含此前所有反馈和更改。切勿单独展示某一轮的内容，始终显示累积后的状态。

决策记录：每项用户反馈选择及其产生的更改都必须按照决策记录格式记录在迭代历史中：

> **Decision**: [Description]
> - **Context**: [What triggered this]
> - **Options**: [What was considered]
> - **Chosen**: [Selected] — **Reason**: [Why]
> - **Impact**: [What changed in roadmap]

步骤：

1. 显示当前路线图

   • 阅读并显示路线图表格及关键收敛标准
   • 显示 Issue 数量和波次细分

2. 反馈循环（如果 AUTO_YES，则跳过）

   // Update progress
   functions.update_plan([{ id: "phase-3", title: "Phase 3: Iterative Refinement", status: "in_progress" }])
   
   let round = 0
   let approved = false
   
   while (!approved && round < 5) {
     round++
   
     // Dynamic options — include research if not yet done
     const baseOptions = [
       { label: "Approve", description: "Proceed to handoff" },
       { label: "Adjust Scope", description: "Modify issue scopes" },
       { label: "Refine Criteria", description: "Improve convergence criteria/verification" }
     ]
   
     // Add research option if architecture decisions need external validation
     if (!researchDone) {
       baseOptions.push({ label: "Research", description: "Search for architecture patterns and best practices" })
     } else {
       baseOptions.push({ label: "Re-decompose", description: "Change strategy/layering" })
     }
   
     const feedback = functions.request_user_input({
       questions: [{
         header: "Validate",    // max 12 chars
         question: `Roadmap round ${round}: ${issueIds.length} issues across ${waveCount} waves. Your decision:`,
         multiSelect: false,
         options: baseOptions
       }]
     })
   
     if (feedback === 'Approve') {
       approved = true
     } else if (feedback === 'Research') {
       // Execute web.run for architecture patterns and best practices
       const researchQueries = generateResearchQueries(requirement, selectedMode)
       researchQueries.forEach(query => {
         const results = web.run({ search_query: query })
         // Extract: architecture patterns, best practices, risk mitigations
       })
       researchDone = true
       // Record research findings in roadmap.md Iteration History
     } else {
       // For Adjust Scope, Refine Criteria, Re-decompose:
       // Collect details via functions.request_user_input or free text
       // CONSTRAINT: All modifications ONLY touch roadmap.md and issues.jsonl
       // NEVER modify source code or project files during interactive rounds
   
       // Record decision in Iteration History using Decision Record format
     }
   
     // Update Iteration History in roadmap.md (Record-Before-Continue)
     const iterationEntry = `
   

Round ${round} - ${getUtc8ISOString()}

User Feedback: ${feedback} Changes Made: ${changesMade} Decision: ${decisionRecord} Status: ${approved ? 'approved' : 'continue iteration'} ` // Append to Iteration History section in roadmap.md }

3. **完成迭代历史**
```javascript
// Update final status in roadmap.md
Edit({
  path: `${sessionFolder}/roadmap.md`,
  old_string: "**Status**: Planning",
  new_string: "**Status**: Ready"
})

成功标准：

• 用户已批准，或已达到最大轮数
• 所有更改均已记录在迭代历史中
• roadmap.md 反映最终状态

---

阶段 4：交接

目标：展示最终路线图，并执行下一步选择的强制终端关卡。

步骤：

1. 显示摘要

   ## Roadmap Complete
   
   - **Session**: RMAP-{date}-{slug}
   - **Strategy**: {progressive|direct}
   - **Issues Created**: {count} across {waves} waves
   - **Roadmap**: .workflow/.roadmap/RMAP-{date}-{slug}/roadmap.md
   
   | Wave | Issue Count | Layer/Type |
   |------|-------------|------------|
   | 1 | 2 | MVP / infrastructure |
   | 2 | 3 | Usable / feature |
   

2. 强制终端关卡（关键——必须执行，工作流不得在此步骤之前结束）

   // Update progress
   functions.update_plan([
     { id: "phase-4", title: "Phase 4: Handoff", status: "completed" },
     { id: "next-step", title: "GATE: Post-Completion Next Step", status: "in_progress" }
   ])
   
   const nextStep = functions.request_user_input({
     questions: [{
       header: "Next Step",    // max 12 chars
       question: `${issueIds.length} issues ready in roadmap. What would you like to do next?`,
       multiSelect: false,
       options: [
         { label: "Execute Plan", description: "Hand off to execution pipeline (csv-wave-pipeline)" },
         { label: "View Issues", description: "Display issue details before deciding" },
         { label: "Done", description: "Planning complete, all artifacts saved" }
       ]
     }]
   })
   
   // Handle next step
   if (nextStep === "Execute Plan") {
     // Display execution command for user to run manually
     // "Run: $csv-wave-pipeline '${requirement}'" or "/issue:execute"
     // This skill is planning-only — NEVER auto-launch execution
   } else if (nextStep === "View Issues") {
     functions.exec_command(`ccw issue list --session ${sessionId}`)
     // After viewing, show execution commands
   }
   // "Done" → end workflow
   
   // Mark terminal gate complete
   functions.update_plan([
     { id: "next-step", title: "GATE: Post-Completion Next Step", status: "completed" }
   ])
   

成功标准：

• 已执行用户选择
• 会话已完成
• 所有产物均可访问

---

错误处理

错误	解决方法
cli-explore-agent 失败	跳过代码探索，继续纯需求分解
cli-roadmap-plan-agent 失败	重试一次，失败后回退到手动分解提示词
无代码库	按正常流程进行，跳过探索步骤
网络研究失败	不依赖外部发现继续进行，依靠内联分析
研究结果与计划冲突	将其作为相互竞争的证据展示，由用户决定方向
检测到循环依赖	提示用户并重新分解
用户在反馈循环中超时	保存 roadmap.md，并显示 --continue 命令
达到最大轮数	强制使用当前路线图继续
会话文件夹冲突	附加时间戳后缀

---

核心规则

1. 立即开始：首先初始化会话，然后执行阶段 1
2. 单一来源：所有上下文都嵌入在 roadmap.md 中，不使用单独的 JSON 文件
3. 迭代完善路线图：通过反馈轮次进行优化，而不是重新创建
4. 可测试的收敛标准：criteria = 断言，DoD = 业务语言
5. 明确的生命周期管理：等待完成后始终调用 close_agent，以释放资源
6. 仅用于规划的技能：此技能只生成路线图和问题，不会执行代码、创建源文件或运行实现。所有代码更改都通过单独的执行技能完成，且须由用户手动触发
7. 仅修改计划文件：交互式反馈（阶段 3）只能更新 roadmap.md 和 issues.jsonl。在任何阶段都不得修改源代码、配置文件或任何项目文件。交接后，只有用户手动运行 $csv-wave-pipeline 或其他执行技能时，才会进行代码更改
8. 强制确认关卡：阶段 2 分解完成后，必须向用户展示路线图并等待用户确认（阶段 3），然后才能继续交接。绝不能跳过阶段 3 的用户验证

---

最佳实践

1. 明确需求：描述越详细，分解效果越好
2. 迭代完善路线图：通过反馈轮次优化收敛标准
3. 可测试的收敛标准：criteria = 断言，DoD = 业务语言
4. 使用继续模式：恢复并迭代现有路线图
5. 分波执行：从 wave-1（MVP）开始，验证后再全面执行

---

使用建议

何时使用路线图或其他技能：

场景	推荐技能
战略规划，需要问题跟踪	$roadmap-with-file
快速拆分任务，立即执行	$lite-plan
协作式多 Agent 规划	$collaborative-plan-with-file
完整规格说明文档	$spec-generator
根据现有计划实现代码	$workflow-lite-plan

---

现在为以下内容规划路线图：$ARGUMENTS