需求级渐进式路线图规划Skill req-plan-with-file

---

name: req-plan-with-file description: 需求级渐进式路线图规划，带JSONL输出。将需求分解为收敛层（MVP→迭代）或拓扑排序的任务序列，每个都有可测试的完成标准。 argument-hint: “[-y|–yes] [-c|–continue] [-m|–mode progressive|direct|auto] "需求描述"”

Codex Req-Plan-With-File 提示

概述

需求级路线图规划，带JSONL输出和收敛标准。将需求分解为自包含的层或任务，每个都有可测试的完成标准，可以通过 lite-plan 独立执行。

核心工作流: 需求理解 → 策略选择 → 上下文收集（可选） → 分解 → 验证 → 质量检查 → 输出

双模式:

• 渐进式: 分层MVP→迭代，适用于高不确定性需求（先验证，后细化）
• 直接式: 拓扑排序的任务序列，适用于低不确定性需求（清晰任务，直接排序）
• 自动: 基于不确定性评估自动选择

自动模式

当 --yes 或 -y: 自动确认策略选择，使用推荐模式，跳过交互式验证轮次。

快速开始

# 基本用法
/codex:req-plan-with-file "实现带有OAuth和2FA的用户认证系统"

# 带模式选择
/codex:req-plan-with-file -m progressive "构建实时通知系统"
/codex:req-plan-with-file -m direct "重构支付模块"
/codex:req-plan-with-file -m auto "添加数据导出功能"

# 继续现有会话
/codex:req-plan-with-file --continue "用户认证系统"

# 自动模式（跳过所有确认）
/codex:req-plan-with-file -y "实现缓存层"

目标需求

$ARGUMENTS

执行过程

步骤0: 会话设置
   ├─ 解析标志（-y, -c, -m）和需求文本
   ├─ 生成会话ID: RPLAN-{slug}-{date}
   └─ 创建会话文件夹（或检测现有 → 继续模式）

步骤1: 解析需求 & 选择策略
   ├─ 提取目标、约束、利益相关者、领域关键词
   ├─ 评估不确定性（5个维度）
   ├─ 选择模式: 渐进式 / 直接式
   ├─ 写入 strategy-assessment.json
   └─ 初始化 roadmap.md 骨架

步骤2: 探索代码库（可选）
   ├─ 检测项目标记（package.json, go.mod 等）
   ├─ 有代码库 → 搜索相关模块、模式、集成点
   │   ├─ 读取 project-tech.json / project-guidelines.json（如果存在）
   │   ├─ 搜索与需求相关的模块/组件
   │   └─ 写入 exploration-codebase.json
   └─ 无代码库 → 跳过

步骤3: 分解需求 → roadmap.jsonl
   ├─ 步骤3.1: 构建分解（需求 + 策略 + 上下文）
   │   ├─ 生成带收敛标准的JSONL记录
   │   └─ 应用收敛质量要求
   ├─ 步骤3.2: 验证记录
   │   ├─ 模式合规、范围完整性
   │   ├─ 无循环依赖（拓扑排序）
   │   ├─ 收敛质量（可测试标准、可执行验证、业务DoD）
   │   └─ 写入 roadmap.jsonl
   └─ 步骤3.3: 质量检查（强制）
       ├─ 需求覆盖、收敛质量、范围完整性
       ├─ 依赖正确性、工作负载平衡
       └─ 自动修复或报告问题

步骤4: 验证 & 完成 → roadmap.md
   ├─ 显示分解（表格 + 收敛详情）
   ├─ 用户反馈循环（最多5轮，如果 -y 则跳过）
   ├─ 写入最终 roadmap.md
   └─ 下一步选项: lite-plan / issue / export / done

配置

标志	默认值	描述
-y, --yes	false	自动确认所有决策
-c, --continue	false	继续现有会话
-m, --mode	auto	分解策略: progressive / direct / auto

会话ID格式: RPLAN-{slug}-{YYYY-MM-DD}

• slug: 小写，字母数字 + CJK字符，最大40字符
• date: YYYY-MM-DD（UTC+8）
• 自动检测继续: 会话文件夹 + roadmap.jsonl 存在 → 继续模式

实现详情

会话设置

步骤0: 初始化会话

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

// 解析标志
const autoYes = $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'

// 清理需求文本
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 = `RPLAN-${slug}-${dateStr}`
const sessionFolder = `.workflow/.req-plan/${sessionId}`

// 自动检测继续: 会话文件夹 + roadmap.jsonl 存在 → 继续模式
// 如果继续 → 跳至步骤4（加载现有 roadmap.jsonl，显示，收集反馈）
Bash(`mkdir -p ${sessionFolder}`)

阶段1: 解析需求 & 选择策略

目标: 解析需求，评估不确定性，选择分解策略。

步骤1.1: 分析需求 & 选择策略

解析需求，跨5个维度评估不确定性，并在一步中选择分解策略：

// 1. 从需求文本中提取
const goal = extractCoreGoal(requirement)       // 实现什么
const constraints = extractConstraints(requirement) // 技术栈、时间线、兼容性
const stakeholders = extractStakeholders(requirement) // 用户、管理员、开发者
const domainKeywords = extractDomainKeywords(requirement) // 领域特定术语

// 2. 评估不确定性（每个: low | medium | high）
const uncertaintyFactors = {
  scope_clarity: '...',       // 范围是否明确？
  technical_risk: '...',      // 已知技术 vs 实验性？
  dependency_unknown: '...',  // 依赖是否清晰？
  domain_familiarity: '...',  // 团队熟悉此领域？
  requirement_stability: '...' // 需求会变化？
}
// >=3 high → 渐进式， >=3 low → 直接式，否则 → 询问

// 3. 选择策略
let selectedMode
if (requestedMode !== 'auto') {
  selectedMode = requestedMode
} else if (autoYes) {
  selectedMode = recommendedMode
} else {
  AskUserQuestion({
    questions: [{
      question: `分解策略选择:

不确定性评估: ${uncertaintyLevel}
推荐策略: ${recommendedMode}

选择分解策略:`,
      header: "策略",
      multiSelect: false,
      options: [
        {
          label: recommendedMode === 'progressive' ? "渐进式（推荐）" : "渐进式",
          description: "分层MVP→迭代，先验证核心后逐步细化。适用于高不确定性需求，需要快速验证"
        },
        {
          label: recommendedMode === 'direct' ? "直接式（推荐）" : "直接式",
          description: "拓扑排序的任务序列，带明确依赖。适用于清晰需求，技术方法已确认"
        }
      ]
    }]
  })
}

// 4. 写入策略评估
Write(`${sessionFolder}/strategy-assessment.json`, JSON.stringify({
  session_id: sessionId,
  requirement, timestamp: getUtc8ISOString(),
  uncertainty_factors: uncertaintyFactors,
  uncertainty_level: uncertaintyLevel,
  recommended_mode: recommendedMode,
  selected_mode: selectedMode,
  goal, constraints, stakeholders,
  domain_keywords: domainKeywords
}, null, 2))

// 5. 初始化 roadmap.md 骨架
const roadmapMdSkeleton = `# 需求路线图

**会话**: ${sessionId}
**需求**: ${requirement}
**策略**: ${selectedMode}
**状态**: 规划中
**创建时间**: ${getUtc8ISOString()}

## 策略评估
- 不确定性级别: ${uncertaintyLevel}
- 分解模式: ${selectedMode}
- 评估基础: ${Object.entries(uncertaintyFactors).map(([k,v]) => `${k}=${v}`).join(', ')}

## 路线图
> 在阶段3分解后填充

## 收敛标准详情
> 在阶段3分解后填充

## 风险项
> 在阶段3分解后填充

## 下一步
> 在阶段4验证后填充
`
Write(`${sessionFolder}/roadmap.md`, roadmapMdSkeleton)

成功标准:

• 需求目标、约束、利益相关者、领域关键词已识别
• 跨5个维度评估不确定性级别
• 策略已选择（渐进式或直接式）
• strategy-assessment.json 已生成
• roadmap.md 骨架已初始化

阶段2: 探索代码库（可选）

目标: 如果代码库存在，收集相关上下文以增强分解质量。

步骤2.1: 检测 & 探索

如果代码库存在，直接搜索相关上下文。无代理委托 — 使用内联搜索工具。

const hasCodebase = Bash(`
  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 -f pom.xml && echo "java" ||
  test -d src && echo "generic" ||
  echo "none"
`).trim()

if (hasCodebase !== 'none') {
  // 1. 读取项目元数据（如果存在）
  //    - .workflow/project-tech.json（技术栈信息）
  //    - .workflow/project-guidelines.json（项目约定）

  // 2. 搜索与需求相关的代码库模块
  //    使用: Grep, Glob, Read, 或 mcp__ace-tool__search_context
  //    关注:
  //      - 与需求相关的模块/组件
  //      - 要遵循的现有模式
  //      - 新功能的集成点
  //      - 架构约束

  // 3. 将发现写入 exploration-codebase.json:
  Write(`${sessionFolder}/exploration-codebase.json`, JSON.stringify({
    project_type: hasCodebase,
    relevant_modules: [...],      // [{name, path, relevance}]
    existing_patterns: [...],     // [{pattern, files, description}]
    integration_points: [...],    // [{location, description, risk}]
    architecture_constraints: [...],
    tech_stack: {languages, frameworks, tools},
    _metadata: {timestamp: getUtc8ISOString(), exploration_scope: '...'}
  }, null, 2))
}
// 无代码库 → 跳过，进行阶段3

成功标准:

• 代码库检测完成
• 当代码库存在时，exploration-codebase.json 已生成，带相关模块、模式、集成点
• 当无代码库时，跳过并进行阶段3

阶段3: 分解需求

目标: 执行需求分解，生成已验证的 roadmap.jsonl。

步骤3.1: 生成 JSONL 记录

直接根据所选模式将需求分解为JSONL记录。自行分析需求并生成记录，参考策略评估和代码库上下文（如果可用）。

// 加载上下文
const strategy = JSON.parse(Read(`${sessionFolder}/strategy-assessment.json`))
let explorationContext = null
if (file_exists(`${sessionFolder}/exploration-codebase.json`)) {
  explorationContext = JSON.parse(Read(`${sessionFolder}/exploration-codebase.json`))
}

渐进式模式 — 生成2-4层：

// 每层必须有:
// - id: L0, L1, L2, L3
// - title: "MVP" / "可用" / "细化" / "优化"
// - description: 该层实现的目标
// - type: feature（层的默认值）
// - priority: high（L0） | medium（L1） | low（L2-L3）
// - scope[]: 包含的功能
// - excludes[]: 明确推迟的功能
// - convergence: { criteria[], verification, definition_of_done }
// - risk_items[], effort（small|medium|large）, depends_on[]
// - source: { tool, session_id, original_id }
//
// 规则:
// - L0（MVP）= 自包含闭环，无依赖
// - 每个功能只在一层中（无重叠）
// - 总共2-4层
// - 收敛必须满足质量要求（见下文）

const layers = [
  {
    id: "L0", title: "MVP",
    description: "...",
    type: "feature", priority: "high",
    scope: ["..."], excludes: ["..."],
    convergence: {
      criteria: ["...（可测试）"],
      verification: "...（可执行命令或步骤）",
      definition_of_done: "...（业务语言）"
    },
    risk_items: [], effort: "medium", depends_on: [],
    source: { tool: "req-plan-with-file", session_id: sessionId, original_id: "L0" }
  },
  // L1, L2, ...
]

直接式模式 — 生成拓扑排序任务：

// 每个任务必须有:
// - id: T1, T2, ...
// - title, description, type（infrastructure|feature|enhancement|testing）
// - priority（high|medium|low）
// - scope, inputs[], outputs[]
// - convergence: { criteria[], verification, definition_of_done }
// - depends_on[], parallel_group
// - source: { tool, session_id, original_id }
//
// 规则:
// - 输入必须来自前置任务输出或现有资源
// - 相同 parallel_group = 真正独立
// - 无循环依赖
// - 收敛必须满足质量要求（见下文）

const tasks = [
  {
    id: "T1", title: "...", description: "...", type: "infrastructure",
    priority: "high",
    scope: "...", inputs: [], outputs: ["..."],
    convergence: {
      criteria: ["...（可测试）"],
      verification: "...（可执行）",
      definition_of_done: "...（业务语言）"
    },
    depends_on: [], parallel_group: 1,
    source: { tool: "req-plan-with-file", session_id: sessionId, original_id: "T1" }
  },
  // T2, T3, ...
]

步骤3.2: 验证记录

写入JSONL前验证所有记录。修复发现的任何问题。

const items = selectedMode === 'progressive' ? layers : tasks
const errors = []

// 1. 模式验证: 每个记录有收敛，带所有3个字段
items.forEach(item => {
  if (!item.convergence?.criteria?.length) errors.push(`${item.id}: 缺少 convergence.criteria`)
  if (!item.convergence?.verification) errors.push(`${item.id}: 缺少 convergence.verification`)
  if (!item.convergence?.definition_of_done) errors.push(`${item.id}: 缺少 convergence.definition_of_done`)
})

// 2. 收敛质量检查
const vaguePatterns = /正常|正确|好|可以|没问题|works|fine|good|correct/i
items.forEach(item => {
  item.convergence.criteria.forEach((criterion, i) => {
    if (vaguePatterns.test(criterion) && criterion.length < 15) {
      errors.push(`${item.id} criteria[${i}]: 太模糊 - "${criterion}"`)
    }
  })
  if (item.convergence.verification.length < 10) {
    errors.push(`${item.id} verification: 太短，需要可执行步骤`)
  }
  const technicalPatterns = /compile|build|lint|npm|npx|jest|tsc|eslint/i
  if (technicalPatterns.test(item.convergence.definition_of_done)) {
    errors.push(`${item.id} definition_of_done: 应是业务语言，而非技术命令`)
  }
})

// 3. 循环依赖检测
function detectCycles(records, prefix) {
  const graph = new Map(records.map(r => [r.id, r.depends_on]))
  const visited = new Set(), inStack = new Set(), cycleErrors = []
  function dfs(node, path) {
    if (inStack.has(node)) { cycleErrors.push(`循环: ${[...path, node].join(' → ')}`); return }
    if (visited.has(node)) return
    visited.add(node); inStack.add(node)
    ;(graph.get(node) || []).forEach(dep => dfs(dep, [...path, node]))
    inStack.delete(node)
  }
  records.forEach(r => { if (!visited.has(r.id)) dfs(r.id, []) })
  return cycleErrors
}
errors.push(...detectCycles(items, selectedMode === 'progressive' ? 'L' : 'T'))

// 4. 模式特定验证
if (selectedMode === 'progressive') {
  // 检查2-4层
  if (items.length < 2 || items.length > 4) errors.push(`预期2-4层，得到 ${items.length}`)

  // 检查L0自包含（无 depends_on）
  const l0 = items.find(l => l.id === 'L0')
  if (l0 && l0.depends_on.length > 0) errors.push("L0（MVP）不应有依赖")

  // 检查范围重叠
  const allScopes = new Map()
  items.forEach(layer => {
    layer.scope.forEach(feature => {
      if (allScopes.has(feature)) {
        errors.push(`范围重叠: "${feature}" 同时存在于 ${allScopes.get(feature)} 和 ${layer.id}`)
      }
      allScopes.set(feature, layer.id)
    })
  })
} else {
  // 检查输入/输出链
  const availableOutputs = new Set()
  items.forEach(task => {
    task.inputs.forEach(input => {
      if (!availableOutputs.has(input)) {
        // 仅对非现有资源警告 — 现有文件是有效输入
      }
    })
    task.outputs.forEach(output => availableOutputs.add(output))
  })

  // 检查 parallel_group 一致性（相同组任务不应相互依赖）
  const groups = new Map()
  items.forEach(task => {
    if (!groups.has(task.parallel_group)) groups.set(task.parallel_group, [])
    groups.get(task.parallel_group).push(task)
  })
  groups.forEach((groupTasks, groupId) => {
    if (groupTasks.length > 1) {
      const ids = new Set(groupTasks.map(t => t.id))
      groupTasks.forEach(task => {
        task.depends_on.forEach(dep => {
          if (ids.has(dep)) {
            errors.push(`并行组 ${groupId}: ${task.id} 依赖 ${dep} 但两者在同一组`)
          }
        })
      })
    }
  })
}

// 5. 修复错误（如果有），然后写入
// 如果发现错误 → 修复记录并重新验证
// 写入 roadmap.jsonl（每行一个JSON记录）
const jsonlContent = items.map(item => JSON.stringify(item)).join('
')
Write(`${sessionFolder}/roadmap.jsonl`, jsonlContent)

步骤3.3: 质量检查（强制）

生成 roadmap.jsonl 后，在继续前跨5个质量维度执行自检。

const roadmapJsonlContent = Read(`${sessionFolder}/roadmap.jsonl`)

// 要验证的质量维度:
//
// | 维度                | 检查标准                                                  | 关键？ |
// |---------------------|----------------------------------------------------------|--------|
// | 需求覆盖           | 原始需求的所有方面在层/任务中已处理                       | 是     |
// | 收敛质量           | 标准可测试、验证可执行、DoD业务可读                       | 是     |
// | 范围完整性         | 渐进式: 无重叠/间隙; 直接式: 输入/输出链有效             | 是     |
// | 依赖正确性         | 无循环依赖、正确排序                                     | 是     |
// | 工作负载平衡       | 无单个层/任务不成比例地大                                 | 否     |
//
// 检查后决定:
// - 通过 → 进行阶段4
// - 自动修复 → 修复收敛措辞、重新平衡范围、更新 roadmap.jsonl
// - 需要审核 → 在阶段4反馈中向用户报告问题

// 自动修复策略:
// | 问题类型          | 自动修复动作                                 |
// |-------------------|---------------------------------------------|
// | 模糊标准          | 替换为具体、可测试的条件                     |
// | 技术性DoD        | 用业务语言重写                               |
// | 缺少范围          | 添加到适当层/任务                           |
// | 工作负载不平衡    | 拆分过大的层/任务                           |

// 自动修复后，更新 roadmap.jsonl

成功标准:

• roadmap.jsonl 已生成，每行独立 JSON.parse-able
• 每条记录包含收敛（标准 + 验证 + definition_of_done）
• 质量检查通过（所有关键维度）
• 无循环依赖
• 渐进式: 2-4层，无范围重叠，L0自包含
• 直接式: 任务有明确输入/输出，parallel_group 正确分配

阶段4: 验证 & 完成

目标: 显示分解结果，收集用户反馈，生成最终工件。

步骤4.1: 显示结果 & 收集反馈

以表格形式显示分解结果，带收敛标准，然后运行反馈循环。

渐进式模式显示格式:

## 路线图概述

| 层 | 标题 | 描述 | 工作负载 | 依赖 |
|----|------|------|----------|------|
| L0 | MVP | ... | medium | - |
| L1 | 可用 | ... | medium | L0 |

### 收敛标准
**L0 - MVP**:
- 标准: [标准列表]
- 验证: [验证]
- 完成定义: [definition_of_done]

直接式模式显示格式:

## 任务序列

| 组 | ID | 标题 | 类型 | 描述 | 依赖 |
|----|----|------|------|------|------|
| 1 | T1 | ... | infrastructure | ... | - |
| 2 | T2 | ... | feature | ... | T1 |

### 收敛标准
**T1 - 建立数据模型**:
- 标准: [标准列表]
- 验证: [验证]
- 完成定义: [definition_of_done]

反馈循环:

const items = Read(`${sessionFolder}/roadmap.jsonl`)
  .split('
').filter(l => l.trim()).map(l => JSON.parse(l))

// 显示表格结果 + 每条收敛（使用上述格式）

if (!autoYes) {
  let round = 0, continueLoop = true
  while (continueLoop && round < 5) {
    round++
    const feedback = AskUserQuestion({
      questions: [{
        question: `路线图验证（轮次 ${round}）:
对当前分解有任何反馈吗？`,
        header: "反馈",
        multiSelect: false,
        options: [
          { label: "批准", description: "分解合理，生成最终工件" },
          { label: "调整范围", description: "某些层/任务范围需要调整" },
          { label: "修改收敛", description: "收敛标准不够具体" },
          { label: "重新分解", description: "整体策略或分层需要更改" }
        ]
      }]
    })
    if (feedback === 'Approve') continueLoop = false
    // 否则: 应用调整，重写 roadmap.jsonl，重新显示，循环
  }
}

步骤4.2: 写入 roadmap.md & 下一步

使用以下生成模板生成最终 roadmap.md，然后提供完成后选项。

渐进式模式 roadmap.md 生成:

const roadmapMd = `# 需求路线图

**会话**: ${sessionId}
**需求**: ${requirement}
**策略**: 渐进式
**不确定性**: ${strategy.uncertainty_level}
**生成时间**: ${getUtc8ISOString()}

## 策略评估
- 不确定性级别: ${strategy.uncertainty_level}
- 分解模式: 渐进式
- 评估基础: ${Object.entries(strategy.uncertainty_factors).map(([k,v]) => `${k}=${v}`).join(', ')}
- 目标: ${strategy.goal}
- 约束: ${strategy.constraints.join(', ') || '无'}
- 利益相关者: ${strategy.stakeholders.join(', ') || '无'}

## 路线图概述

| 层 | 标题 | 描述 | 工作负载 | 依赖 |
|----|------|------|----------|------|
${items.map(l => `| ${l.id} | ${l.title} | ${l.description} | ${l.effort} | ${l.depends_on.length ? l.depends_on.join(', ') : '-'} |`).join('
')}

## 层详情

${items.map(l => `### ${l.id}: ${l.title}

**描述**: ${l.description}

**范围**: ${l.scope.join(', ')}

**排除**: ${l.excludes.join(', ') || '无'}

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

**风险项**: ${l.risk_items.length ? l.risk_items.map(r => \`
- ${r}\`).join('') : '无'}

**工作负载**: ${l.effort}
`).join('
---

')}

## 风险总结

${items.flatMap(l => l.risk_items.map(r => \`- **${l.id}**: ${r}\`)).join('
') || '未识别风险'}

## 下一步

每层可独立执行:
\\\`\\\`\\\`bash
/workflow:lite-plan "${items[0]?.title}: ${items[0]?.scope.join(', ')}"
\\\`\\\`\\\`

路线图 JSONL 文件: \\\`${sessionFolder}/roadmap.jsonl\\\`
`

直接式模式 roadmap.md 生成:

const roadmapMd = `# 需求路线图

**会话**: ${sessionId}
**需求**: ${requirement}
**策略**: 直接式
**生成时间**: ${getUtc8ISOString()}

## 策略评估
- 目标: ${strategy.goal}
- 约束: ${strategy.constraints.join(', ') || '无'}
- 评估基础: ${Object.entries(strategy.uncertainty_factors).map(([k,v]) => `${k}=${v}`).join(', ')}

## 任务序列

| 组 | ID | 标题 | 类型 | 描述 | 依赖 |
|----|----|------|------|------|------|
${items.map(t => `| ${t.parallel_group} | ${t.id} | ${t.title} | ${t.type} | ${t.description} | ${t.depends_on.length ? t.depends_on.join(', ') : '-'} |`).join('
')}

## 任务详情

${items.map(t => `### ${t.id}: ${t.title}

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

**描述**: ${t.description}

**范围**: ${t.scope}

**输入**: ${t.inputs.length ? t.inputs.join(', ') : '无（起始任务）'}
**输出**: ${t.outputs.join(', ')}

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

')}

## 下一步

每任务可独立执行:
\\\`\\\`\\\`bash
/workflow:lite-plan "${items[0]?.title}: ${items[0]?.scope}"
\\\`\\\`\\\`

路线图 JSONL 文件: \\\`${sessionFolder}/roadmap.jsonl\\\`
`

写入并提供完成后选项:

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

// 完成后选项
if (!autoYes) {
  AskUserQuestion({
    questions: [{
      question: "路线图已生成。下一步：",
      header: "下一步",
      multiSelect: false,
      options: [
        { label: "执行第一层", description: `启动 lite-plan 执行 ${items[0].id}` },
        { label: "创建问题", description: "基于路线图创建 GitHub Issue" },
        { label: "导出报告", description: "生成独立可共享路线图报告" },
        { label: "完成", description: "仅保存路线图，稍后执行" }
      ]
    }]
  })
}

选择	动作
执行第一层	Skill(skill="workflow:lite-plan", args="${firstItem.scope}")
创建问题	Skill(skill="issue:new", args="...")
导出报告	复制 roadmap.md + roadmap.jsonl 到用户指定位置
完成	显示路线图文件路径，结束

成功标准:

• 用户反馈已处理（或通过 autoYes 跳过）
• roadmap.md 已最终化，带完整表格和收敛详情
• roadmap.jsonl 最终版本已更新
• 完成后选项已提供

会话文件夹结构

.workflow/.req-plan/RPLAN-{slug}-{YYYY-MM-DD}/
├── roadmap.md                    # 人类可读路线图
├── roadmap.jsonl                 # 机器可读，每行自包含记录
├── strategy-assessment.json      # 策略评估结果
└── exploration-codebase.json     # 代码库上下文（可选）

文件	阶段	描述
strategy-assessment.json	1	不确定性分析 + 模式推荐 + 提取的目标/约束/利益相关者/领域关键词
roadmap.md（骨架）	1	带占位符的初始骨架，在阶段4最终化
exploration-codebase.json	2	代码库上下文: 相关模块、模式、集成点（仅当代码库存在时）
roadmap.jsonl	3	每行一个自包含 JSON 记录，带收敛标准和来源证明
roadmap.md（最终）	4	人类可读路线图，带表格显示 + 收敛详情，按用户反馈修订

JSONL 模式

收敛标准

每条记录的 convergence 对象:

字段	目的	要求
criteria[]	可检查的具体条件列表	可测试 — 可写为断言或手动步骤
verification	如何验证这些条件	可执行 — 命令、脚本或明确步骤
definition_of_done	一句完成定义	业务语言 — 非技术人员可判断

渐进式模式（每行一层）

层	标题	典型描述
L0	MVP	最小可行闭环，核心路径端到端
L1	可用	关键用户路径细化，基本错误处理
L2	细化	边缘情况、性能、安全加固
L3	优化	高级功能、可观测性、运维

模式: id, title, description, type, priority, scope[], excludes[], convergence{}, risk_items[], effort, depends_on[], source{}

{"id":"L0","title":"MVP","description":"最小可行闭环","type":"feature","priority":"high","scope":["用户注册和登录","基本CRUD"],"excludes":["OAuth","2FA"],"convergence":{"criteria":["端到端注册→登录→操作流工作","核心API返回正确响应"],"verification":"curl/Postman手动测试或冒烟测试脚本","definition_of_done":"新用户可完成注册→登录→执行一个核心操作"},"risk_items":["JWT库选择需要验证"],"effort":"medium","depends_on":[],"source":{"tool":"req-plan-with-file","session_id":"RPLAN-xxx","original_id":"L0"}}
{"id":"L1","title":"可用","description":"完成关键用户路径","type":"feature","priority":"medium","scope":["密码重置","输入验证","错误消息"],"excludes":["审计日志","速率限制"],"convergence":{"criteria":["所有表单字段有前端+后端验证","密码重置邮件可发送且重置完成","错误场景显示用户友好消息"],"verification":"单元测试覆盖验证逻辑 + 重置流手动测试","definition_of_done":"用户遇到输入错误或忘记密码时有清晰恢复路径"},"risk_items":[],"effort":"medium","depends_on":["L0"],"source":{"tool":"req-plan-with-file","session_id":"RPLAN-xxx","original_id":"L1"}}

约束: 2-4层，L0必须是自包含闭环且无依赖，每个功能只属于一层（无范围重叠）。

直接式模式（每行一任务）

类型	用例
infrastructure	数据模型、配置、脚手架
feature	API、UI、业务逻辑实现
enhancement	验证、错误处理、边缘情况
testing	单元测试、集成测试、端到端测试

模式: id, title, description, type, scope, inputs[], outputs[], convergence{}, depends_on[], parallel_group, source{}

{"id":"T1","title":"建立数据模型","description":"为所有业务实体创建数据库模式和TypeScript类型定义","type":"infrastructure","scope":"DB模式 + TypeScript类型","inputs":[],"outputs":["schema.prisma","types/user.ts"],"convergence":{"criteria":["迁移执行无错误","TypeScript类型编译成功","字段覆盖所有业务实体"],"verification":"npx prisma migrate dev && npx tsc --noEmit","definition_of_done":"数据库模式正确迁移，类型定义可被其他模块引用"},"depends_on":[],"parallel_group":1,"source":{"tool":"req-plan-with-file","session_id":"RPLAN-xxx","original_id":"T1"}}
{"id":"T2","title":"实现核心API","description":"为User实体构建带适当验证和错误处理的CRUD端点","type":"feature","scope":"User的CRUD端点","inputs":["schema.prisma","types/user.ts"],"outputs":["routes/user.ts","controllers/user.ts"],"convergence":{"criteria":["GET/POST/PUT/DELETE返回正确状态码","请求/响应符合模式","无N+1查询"],"verification":"jest --testPathPattern=user.test.ts","definition_of_done":"所有User CRUD端点通过集成测试"},"depends_on":["T1"],"parallel_group":2,"source":{"tool":"req-plan-with-file","session_id":"RPLAN-xxx","original_id":"T2"}}

约束: 输入必须来自前置任务输出或现有资源，相同 parallel_group 的任务必须真正独立，无循环依赖。

收敛质量要求

每个 convergence 字段必须满足这些质量标准:

字段	要求	坏例子	好例子
criteria[]	可测试 — 可写断言或手动步骤	"系统正确工作"	"API返回200且响应体包含user_id字段"
verification	可执行 — 命令、脚本或清晰步骤	"检查它"	"jest --testPathPattern=auth && curl -s localhost:3000/health"
definition_of_done	业务语言 — 非技术人员可判断	"代码编译"	"新用户可完成注册→登录→执行核心操作流"

绝不输出模糊收敛标准（“正确工作”、“系统正常”）。始终确保:

• 标准可测试（可写为断言或手动验证步骤）
• 验证可执行（命令或明确步骤）
• 完成定义使用业务语言（非技术利益相关者可判断）

后备分解

当正常分解失败或产生空结果时，使用后备模板:

渐进式后备:

[
  {
    id: "L0", title: "MVP", description: "最小可行闭环",
    type: "feature", priority: "high",
    scope: ["核心功能"], excludes: ["高级功能", "优化"],
    convergence: {
      criteria: ["核心路径端到端工作"],
      verification: "核心流手动测试",
      definition_of_done: "用户可完成一个完整核心操作"
    },
    risk_items: ["技术选择需要验证"], effort: "medium", depends_on: [],
    source: { tool: "req-plan-with-file", session_id: sessionId, original_id: "L0" }
  },
  {
    id: "L1", title: "可用", description: "细化关键用户路径",
    type: "feature", priority: "medium",
    scope: ["错误处理", "输入验证"], excludes: ["性能优化", "监控"],
    convergence: {
      criteria: ["所有用户输入已验证", "错误场景显示消息"],
      verification: "单元测试 + 手动错误场景测试",
      definition_of_done: "用户遇到问题时有清晰指导和恢复路径"
    },
    risk_items: [], effort: "medium", depends_on: ["L0"],
    source: { tool: "req-plan-with-file", session_id: sessionId, original_id: "L1" }
  }
]

直接式后备:

[
  {
    id: "T1", title: "基础设施设置", description: "项目脚手架和基础配置",
    type: "infrastructure", priority: "high",
    scope: "项目脚手架和基础配置",
    inputs: [], outputs: ["project-structure"],
    convergence: {
      criteria: ["项目构建无错误", "基础配置完成"],
      verification: "npm run build（或等效构建命令）",
      definition_of_done: "项目基础准备好进行功能开发"
    },
    depends_on: [], parallel_group: 1,
    source: { tool: "req-plan-with-file", session_id: sessionId, original_id: "T1" }
  },
  {
    id: "T2", title: "核心功能实现", description: "实现核心业务逻辑",
    type: "feature", priority: "high",
    scope: "核心业务逻辑",
    inputs: ["project-structure"], outputs: ["core-module"],
    convergence: {
      criteria: ["核心API/功能可调用", "返回预期结果"],
      verification: "运行核心功能测试",
      definition_of_done: "核心业务功能按预期工作"
    },
    depends_on: ["T1"], parallel_group: 2,
    source: { tool: "req-plan-with-file", session_id: sessionId, original_id: "T2" }
  }
]

错误处理

情况	动作
无代码库检测到	正常流，跳过阶段2
代码库搜索失败	进行纯需求分解
记录中循环依赖	写入JSONL前修复依赖图
用户反馈超时	保存当前状态，显示 --continue 恢复命令
最大反馈轮次（5）	使用当前版本生成最终工件
会话文件夹冲突	添加时间戳后缀
JSONL格式错误	逐行验证，报告问题行并修复
质量检查失败	可能时自动修复，否则在反馈循环中报告给用户
分解产生空结果	使用后备分解模板

最佳实践

1. 清晰需求描述: 详细描述导致更准确不确定性评估和分解
2. 先验证MVP: 在渐进式模式中，L0应是最小可验证闭环
3. 可测试收敛: 标准必须可写为断言或手动步骤；完成定义应是非技术利益相关者可判断的
4. 增量验证: 使用 --continue 迭代现有路线图
5. 独立可执行: 每条JSONL记录应可独立传递给 lite-plan 执行

何时使用

使用 req-plan-with-file 当:

• 您需要将大需求分解为渐进式可执行路线图
• 不确定从何开始，需要MVP策略
• 需要为团队生成可跟踪任务序列
• 需求涉及多阶段或迭代

使用 lite-plan 当:

• 您有清晰单任务要执行
• 需求已是路线图中的层/任务
• 无需分层规划

使用 collaborative-plan-with-file 当:

• 单个复杂任务需要多代理并行规划
• 需要从多领域视角分析同一任务

使用 analyze-with-file 当:

• 需要深入分析技术问题
• 不关于规划执行，而是理解和讨论

---

现在为以下需求执行 req-plan-with-file 工作流: $ARGUMENTS