关于 collaborative-plan-with-file
Collaborative-Plan-With-File 是一种串行规划工作流，可将需求拆分为子领域，依次制定计划并检查冲突。共享的 `plan-note.md` 预先分配各领域的区段，汇总计划而无需合并编辑。
主要功能
- 01分析需求并拆分为多个子领域
- 02依次规划各个领域
- 03在共享 `plan-note.md` 区段中记录计划
- 04检测文件、依赖和策略冲突
- 05生成任务文件和易读计划
适用场景
- 01规划涉及多个子领域的功能
- 02协调可能修改重叠文件的工作
- 03为 unified-execute 准备任务产物
MCP 相关
工作流列出 `mcp__ace-tool__search_context`，用于查找相关代码和文档。
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/collaborative-plan-with-file确认已加载。
详细介绍
Collaborative-Plan-With-File 工作流
快速开始
采用 Plan Note 架构的串行协作规划工作流。分析需求，识别子领域，为每个领域依次生成详细计划，并检测不同领域之间的冲突。
# Basic usage
/codex:collaborative-plan-with-file "Implement real-time notification system"
# With options
/codex:collaborative-plan-with-file "Refactor authentication module" --max-domains=4
/codex:collaborative-plan-with-file "Add payment gateway support" -y
核心工作流：理解 → 模板 → 串行领域规划 → 冲突检测 → 完成
主要功能：
- plan-note.md：协作文档，为每个领域预分配专属章节
- 串行领域规划：依次规划每个子领域，并提供完整的代码库上下文
- 冲突检测：自动扫描文件、依赖项和策略冲突
- 无需合并：预分配的章节可避免合并冲突
自动模式
使用 --yes 或 -y 时：自动批准拆分，跳过确认。
概述
此工作流通过一系列阶段实现结构化规划：
- 理解与模板 — 分析需求，识别子领域，创建 plan-note.md 模板
- 串行领域规划 — 使用直接搜索和分析，依次规划每个子领域
- 冲突检测 — 扫描 plan-note.md，检测所有领域之间的冲突
- 完成 — 生成便于阅读的 plan.md 摘要
关键创新是 Plan Note 架构 — 一份协作文档，为每个子领域预分配专属章节，即使采用串行执行，也能避免合并冲突。
┌─────────────────────────────────────────────────────────────────────────┐
│ PLAN NOTE COLLABORATIVE PLANNING │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Phase 1: Understanding & Template Creation │
│ ├─ Analyze requirements (inline search & analysis) │
│ ├─ Identify 2-5 sub-domains (focus areas) │
│ ├─ Create plan-note.md with pre-allocated sections │
│ └─ Assign TASK ID ranges (no conflicts) │
│ │
│ Phase 2: Serial Domain Planning │
│ ┌──────────────┐ │
│ │ Domain 1 │→ Explore codebase → Generate .task/TASK-*.json │
│ │ Section 1 │→ Fill task pool + evidence in plan-note.md │
│ └──────┬───────┘ │
│ ┌──────▼───────┐ │
│ │ Domain 2 │→ Explore codebase → Generate .task/TASK-*.json │
│ │ Section 2 │→ Fill task pool + evidence in plan-note.md │
│ └──────┬───────┘ │
│ ┌──────▼───────┐ │
│ │ Domain N │→ ... │
│ └──────────────┘ │
│ │
│ Phase 3: Conflict Detection (Single Source) │
│ ├─ Parse plan-note.md (all sections) │
│ ├─ Detect file/dependency/strategy conflicts │
│ └─ Update plan-note.md conflict section │
│ │
│ Phase 4: Completion (No Merge) │
│ ├─ Collect domain .task/*.json → session .task/*.json │
│ ├─ Generate plan.md (human-readable) │
│ └─ Ready for execution │
│ │
└─────────────────────────────────────────────────────────────────────────┘
输出结构
架构：
cat ~/.ccw/workflows/cli-templates/schemas/task-schema.json
{projectRoot}/.workflow/.planning/CPLAN-{slug}-{date}/
├── plan-note.md # ⭐ Core: Requirements + Tasks + Conflicts
├── requirement-analysis.json # Phase 1: Sub-domain assignments
├── domains/ # Phase 2: Per-domain plans
│ ├── {domain-1}/
│ │ └── .task/ # Per-domain task JSON files
│ │ ├── TASK-001.json
│ │ └── ...
│ ├── {domain-2}/
│ │ └── .task/
│ │ ├── TASK-101.json
│ │ └── ...
│ └── ...
├── plan.json # Plan overview (plan-overview-base-schema.json)
├── .task/ # ⭐ Merged task JSON files (all domains)
│ ├── TASK-001.json
│ ├── TASK-101.json
│ └── ...
├── conflicts.json # Phase 3: Conflict report
└── plan.md # Phase 4: Human-readable summary
输出产物
阶段 1：理解与模板
| 产物 | 用途 |
|---|---|
plan-note.md | 协作模板，为每个领域预分配任务池和证据章节 |
requirement-analysis.json | 子领域分配、TASK ID 范围、复杂度评估 |
阶段 2：串行领域规划
| 产物 | 用途 |
|---|---|
domains/{domain}/.task/TASK-*.json | 各领域的任务 JSON 文件（每个任务一个文件，并附带收敛信息） |
更新后的 plan-note.md | 填写各领域的任务池和证据章节 |
阶段 3：冲突检测
| 产物 | 用途 |
|---|---|
conflicts.json | 检测到的冲突，包括类型、严重程度和解决方案 |
更新后的 plan-note.md | 填写冲突标记章节 |
阶段 4：完成
| 产物 | 用途 |
|---|---|
.task/TASK-*.json | 合并所有领域的任务 JSON 文件（可供 unified-execute 使用） |
plan.json | 遵循 plan-overview-base-schema.json 的计划概览 |
plan.md | 便于阅读的摘要，包含需求、任务和冲突 |
实现详情
会话初始化
步骤 0：初始化会话
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
// Detect project root
const projectRoot = Bash(`git rev-parse --show-toplevel 2>/dev/null || pwd`).trim()
// Parse arguments
const autoMode = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
const maxDomainsMatch = $ARGUMENTS.match(/--max-domains=(\d+)/)
const maxDomains = maxDomainsMatch ? parseInt(maxDomainsMatch[1]) : 5
// Clean task description
const taskDescription = $ARGUMENTS
.replace(/--yes|-y|--max-domains=\d+/g, '')
.trim()
const slug = taskDescription.toLowerCase()
.replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-')
.substring(0, 30)
const dateStr = getUtc8ISOString().substring(0, 10)
const sessionId = `CPLAN-${slug}-${dateStr}`
const sessionFolder = `${projectRoot}/.workflow/.planning/${sessionId}`
// Auto-detect continue: session folder + plan-note.md exists → continue mode
// If continue → load existing state and resume from incomplete phase
Bash(`mkdir -p ${sessionFolder}/domains`)
会话变量：
sessionId：唯一会话标识符sessionFolder：所有产物的根目录maxDomains：子领域的最大数量（默认值：5）autoMode：用于自动确认的布尔值
自动检测：如果会话文件夹中存在 plan-note.md，则自动进入继续模式。
阶段 1：理解与模板创建
目标：分析任务需求，识别可并行处理的子领域，并创建包含预分配章节的 plan-note.md 模板。
步骤 1.1：分析任务描述
直接使用内置工具了解任务范围并识别子领域。
分析活动：
- 搜索参考资料 — 查找相关文档、README 文件和架构指南
- 使用：
mcp__ace-tool__search_context、Grep、Glob、Read - 运行：
ccw spec load --category planning（如果有规范系统）
- 使用：
- 提取任务关键词 — 识别任务描述中的关键术语和概念
- 识别歧义 — 列出不明确之处或多种可能的解释
- 向用户澄清 — 如果发现歧义，使用 request_user_input 进行澄清
- 识别子领域 — 根据任务复杂度拆分为 2-{maxDomains} 个可并行处理的重点领域
- 评估复杂度 — 评估整体任务复杂度（低/中/高）
子领域识别模式：
| 模式 | 关键词 |
|---|---|
| 后端 API | 服务、后端、API、接口 |
| 前端 | 界面、前端、UI、视图 |
| 数据库 | 数据、存储、数据库、持久化 |
| 测试 | 测试、验证、QA |
| 基础设施 | 部署、基础、运维、配置 |
指南：优先查找最新文档（README、设计文档、架构指南）。存在歧义时，应向用户澄清，而不是自行假设。
步骤 1.2：创建 plan-note.md 模板
生成一个结构化模板，为每个子领域预先分配对应章节。
plan-note.md 结构：
---
session_id: CPLAN-{slug}-{date}
original_requirement: "{task description}"
created_at: "{ISO timestamp}"
complexity: Low | Medium | High
sub_domains: ["{domain-1}", "{domain-2}", ...]
domain_task_id_ranges:
"{domain-1}": [1, 100]
"{domain-2}": [101, 200]
status: planning
---
章节：
## 需求理解— 核心目标、关键要点、约束、拆分策略## 任务池 - {Domain N}— 为每个领域预先分配的任务章节（TASK-{range}）## 依赖关系— 所有领域完成后自动生成## 冲突标记— 在阶段 3 中填写## 上下文证据 - {Domain N}— 每个领域对应的证据章节
TASK ID 范围分配：每个领域分配一个不重叠的 100 个 ID 的范围（例如，领域 1：TASK-001100，领域 2：TASK-101200）。
步骤 1.3：生成 requirement-analysis.json
Write(`${sessionFolder}/requirement-analysis.json`, JSON.stringify({
session_id: sessionId,
original_requirement: taskDescription,
complexity: complexity, // Low | Medium | High
sub_domains: subDomains.map(sub => ({
focus_area: sub.focus_area,
description: sub.description,
task_id_range: sub.task_id_range,
estimated_effort: sub.estimated_effort,
dependencies: sub.dependencies // cross-domain dependencies
})),
total_domains: subDomains.length
}, null, 2))
成功标准：
- 已识别并引用最新文档（如有）
- 已通过用户澄清解决歧义（如有发现）
- 已识别出 2-{maxDomains} 个明确的子领域
- 每个子领域都可以独立规划
- 计划说明模板包含所有预分配章节
- TASK ID 范围互不重叠（每个领域 100 个 ID）
- 需求理解全面
阶段 2：串行子领域规划
目标：依次规划每个子领域，生成详细计划并更新 plan-note.md。
执行模式：串行内联执行——每次使用搜索工具直接探索并规划一个领域。
步骤 2.1：用户确认（除非启用 autoMode）
展示已识别的子领域，并在开始前进行确认。
if (!autoMode) {
request_user_input({
questions: [{
header: "确认规划",
id: "confirm",
question: `已识别 ${subDomains.length} 个子领域:\n${subDomains.map((s, i) =>
`${i+1}. ${s.focus_area}: ${s.description}`).join('\n')}\n\n确认开始规划?`,
options: [
{ label: "开始规划(Recommended)", description: "逐域进行规划" },
{ label: "调整拆分", description: "修改子领域划分" },
{ label: "取消", description: "退出规划" }
]
}]
})
}
步骤 2.2：串行领域规划
对每个子领域，直接内联执行完整的规划流程：
for (const sub of subDomains) {
// 1. Create domain directory with .task/ subfolder
Bash(`mkdir -p ${sessionFolder}/domains/${sub.focus_area}/.task`)
// 2. Explore codebase for domain-relevant context
// Use: mcp__ace-tool__search_context, Grep, Glob, Read
// Focus on:
// - Modules/components related to this domain
// - Existing patterns to follow
// - Integration points with other domains
// - Architecture constraints
// 3. Generate task JSON records (following task-schema.json)
const domainTasks = [
// For each task within the assigned ID range:
{
id: `TASK-${String(sub.task_id_range[0]).padStart(3, '0')}`,
title: "...",
description: "...", // scope/goal of this task
type: "feature", // infrastructure|feature|enhancement|fix|refactor|testing
priority: "medium", // high|medium|low
effort: "medium", // small|medium|large
scope: "...", // Brief scope description
depends_on: [], // TASK-xxx references
convergence: {
criteria: ["... (testable)"], // Testable conditions
verification: "... (executable)", // Command or steps
definition_of_done: "... (business language)"
},
files: [ // Files to modify
{
path: "...",
action: "modify", // modify|create|delete
changes: ["..."], // Change descriptions
conflict_risk: "low" // low|medium|high
}
],
source: {
tool: "collaborative-plan-with-file",
session_id: sessionId,
original_id: `TASK-${String(sub.task_id_range[0]).padStart(3, '0')}`
}
}
// ... more tasks
]
// 4. Write individual task JSON files (one per task)
domainTasks.forEach(task => {
Write(`${sessionFolder}/domains/${sub.focus_area}/.task/${task.id}.json`,
JSON.stringify(task, null, 2))
})
// 5. Sync summary to plan-note.md
// Read current plan-note.md
// Locate pre-allocated sections:
// - Task Pool: "## 任务池 - ${toTitleCase(sub.focus_area)}"
// - Evidence: "## 上下文证据 - ${toTitleCase(sub.focus_area)}"
// Fill with task summaries and evidence
// Write back plan-note.md
}
任务摘要格式（用于 plan-note.md 任务池章节）：
### TASK-{ID}: {Title} [{focus-area}]
- **状态**: pending
- **类型**: feature/fix/refactor/enhancement/testing/infrastructure
- **优先级**: high/medium/low
- **工作量**: small/medium/large
- **依赖**: TASK-xxx (if any)
- **范围**: Brief scope description
- **修改文件**: `file-path` (action): change summary
- **收敛标准**:
- criteria 1
- criteria 2
- **验证方式**: executable command or steps
- **完成定义**: business language definition
证据格式（用于 plan-note.md 证据章节）：
- **相关文件**: file list with relevance
- **现有模式**: patterns identified
- **约束**: constraints discovered
领域规划规则：
- 每个领域只能修改 plan-note.md 中预先分配给自己的章节
- 只能使用分配的 TASK ID 范围
- 为每项任务包含收敛标准（criteria + verification + definition_of_done）
- 包含
files[]，并针对每个文件评估 conflict_risk - 明确引用跨领域依赖关系
- 每条任务记录都必须自包含（可由 unified-execute 独立使用）
步骤 2.3：验证 plan-note.md 一致性
规划完所有领域后，验证共享文档。
验证活动：
- 阅读最终的 plan-note.md
- 验证所有任务池章节均已填写
- 验证所有证据章节均已填写
- 检查所有领域间的 TASK ID 是否唯一
- 检查是否存在章节格式不一致的情况
成功标准：
- 为每个领域创建
domains/{domain}/.task/TASK-*.json（每个任务一个文件） - 每个任务均有收敛信息（criteria + verification + definition_of_done）
plan-note.md已更新，包含所有任务池和证据章节- 任务摘要格式一致
- 各领域间没有 TASK ID 重复
阶段 3：冲突检测
目标：分析 plan-note.md，检测各领域贡献之间的冲突。
步骤 3.1：解析 plan-note.md
从所有“任务池”章节和各领域的 .task/*.json 文件中提取所有任务。
// parsePlanNote(markdown)
// - Extract YAML frontmatter between `---` markers
// - Scan for heading patterns: /^(#{2,})\s+(.+)$/
// - Build sections array: { level, heading, start, content }
// - Return: { frontmatter, sections }
// Also load all domain .task/*.json for detailed data
// loadDomainTasks(sessionFolder, subDomains):
// const allTasks = []
// for (const sub of subDomains) {
// const taskDir = `${sessionFolder}/domains/${sub.focus_area}/.task`
// const taskFiles = Glob(`${taskDir}/TASK-*.json`)
// taskFiles.forEach(file => {
// allTasks.push(JSON.parse(Read(file)))
// })
// }
// return allTasks
// extractTasksFromSection(content, sectionHeading)
// - Match: /### (TASK-\d+):\s+(.+?)\s+\[(.+?)\]/
// - For each: extract taskId, title, author
// - Parse details: status, type, priority, effort, depends_on, files, convergence
// - Return: array of task objects
// parseTaskDetails(content)
// - Extract via regex:
// - /\*\*状态\*\*:\s*(.+)/ → status
// - /\*\*类型\*\*:\s*(.+)/ → type
// - /\*\*优先级\*\*:\s*(.+)/ → priority
// - /\*\*工作量\*\*:\s*(.+)/ → effort
// - /\*\*依赖\*\*:\s*(.+)/ → depends_on (extract TASK-\d+ references)
// - Extract files: /- `([^`]+)` \((\w+)\):\s*(.+)/ → path, action, change
// - Return: { status, type, priority, effort, depends_on[], files[], convergence }
步骤 3.2：检测冲突
扫描所有任务，检查以下三类冲突。
冲突类型：
| 类型 | 严重程度 | 检测逻辑 | 解决方法 |
|---|---|---|---|
| file_conflict | 高 | 多个领域修改了同一个文件的同一位置 | 协调修改顺序或合并更改 |
| dependency_cycle | 严重 | 任务图中存在循环依赖（通过 DFS 检测） | 移除或重新组织依赖关系 |
| strategy_conflict | 中 | 不同领域在同一个文件中有多个高风险任务 | 审查方案并统一策略 |
检测函数：
// detectFileConflicts(tasks)
// Build fileMap: { "file-path": [{ task_id, task_title, source_domain, changes }] }
// For each file with modifications from multiple domains:
// → conflict: type='file_conflict', severity='high'
// → include: file, tasks_involved, domains_involved, changes
// → resolution: 'Coordinate modification order or merge changes'
// detectDependencyCycles(tasks)
// Build dependency graph: { taskId: [dependsOn_taskIds] }
// DFS with recursion stack to detect cycles:
function detectCycles(tasks) {
const graph = new Map(tasks.map(t => [t.id, t.depends_on || []]))
const visited = new Set(), inStack = new Set(), cycles = []
function dfs(node, path) {
if (inStack.has(node)) { cycles.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)
}
tasks.forEach(t => { if (!visited.has(t.id)) dfs(t.id, []) })
return cycles
}
// detectStrategyConflicts(tasks)
// Group tasks by files they modify (from task.files[].path)
// For each file with tasks from multiple domains:
// Filter for tasks with files[].conflict_risk === 'high' or 'medium'
// If >1 high-risk from different domains:
// → conflict: type='strategy_conflict', severity='medium'
// → resolution: 'Review approaches and align on single strategy'
步骤 3.3：生成冲突产物
写入冲突结果并更新 plan-note.md。
// 1. Write conflicts.json
Write(`${sessionFolder}/conflicts.json`, JSON.stringify({
detected_at: getUtc8ISOString(),
total_tasks: allTasks.length,
total_domains: subDomains.length,
total_conflicts: allConflicts.length,
conflicts: allConflicts // { type, severity, tasks_involved, description, suggested_resolution }
}, null, 2))
// 2. Update plan-note.md "## 冲突标记" section
// generateConflictMarkdown(conflicts):
// If empty: return '✅ 无冲突检测到'
// For each conflict:
// ### CONFLICT-{padded_index}: {description}
// - **严重程度**: critical | high | medium
// - **涉及任务**: TASK-xxx, TASK-yyy
// - **涉及领域**: domain-a, domain-b
// - **问题详情**: (based on conflict type)
// - **建议解决方案**: ...
// - **决策状态**: [ ] 待解决
// replaceSectionContent(markdown, sectionHeading, newContent):
// Find section heading position via regex
// Find next heading of same or higher level
// Replace content between heading and next section
// If section not found: append at end
成功标准：
- 已提取并分析所有任务
- 已写入包含检测结果的
conflicts.json plan-note.md已更新，包含冲突标记- 已检查所有冲突类型（文件、依赖、策略）
阶段 4：完成
目标：生成人类可读的计划摘要并完成工作流。
步骤 4.1：将领域 .task/*.json 收集到会话 .task/
将各领域的所有任务 JSON 文件复制到同一个会话级 .task/ 目录中。
// Create session-level .task/ directory
Bash(`mkdir -p ${sessionFolder}/.task`)
// Collect all domain task files
for (const sub of subDomains) {
const taskDir = `${sessionFolder}/domains/${sub.focus_area}/.task`
const taskFiles = Glob(`${taskDir}/TASK-*.json`)
taskFiles.forEach(file => {
const filename = path.basename(file)
// Copy domain task file to session .task/ directory
Bash(`cp ${file} ${sessionFolder}/.task/${filename}`)
})
}
步骤 4.2：生成 plan.json
按照 plan-overview-base-schema 生成计划概览。
// Generate plan.json (plan-overview-base-schema)
const allTaskFiles = Glob(`${sessionFolder}/.task/TASK-*.json`)
const taskIds = allTaskFiles.map(f => JSON.parse(Read(f)).id).sort()
// Guard: skip plan.json if no tasks generated
if (taskIds.length === 0) {
console.warn('No tasks generated; skipping plan.json')
} else {
const planOverview = {
summary: `Collaborative plan for: ${taskDescription}`,
approach: `Multi-domain planning across ${subDomains.length} sub-domains: ${subDomains.map(s => s.focus_area).join(', ')}`,
task_ids: taskIds,
task_count: taskIds.length,
complexity: complexity,
recommended_execution: "Agent",
_metadata: {
timestamp: getUtc8ISOString(),
source: "direct-planning",
planning_mode: "direct",
plan_type: "collaborative",
schema_version: "2.0"
}
}
Write(`${sessionFolder}/plan.json`, JSON.stringify(planOverview, null, 2))
} // end guard
步骤 4.3：生成 plan.md
根据 plan-note.md 的内容创建人类可读的摘要。
plan.md 结构：
| 章节 | 内容 |
|---|---|
| 标题 | 会话 ID、任务描述、创建时间 |
| 需求 | 从 plan-note.md 的“需求理解”章节复制 |
| 子领域拆分 | 每个领域的描述、任务范围、预估工作量 |
| 任务概览 | 所有任务及其复杂度、依赖关系和目标文件 |
| 冲突报告 | 检测到的冲突摘要，或“无冲突” |
| 执行指令 | 执行计划的命令 |
const planMd = `# Collaborative Plan
**Session**: ${sessionId}
**Requirement**: ${taskDescription}
**Created**: ${getUtc8ISOString()}
**Complexity**: ${complexity}
**Domains**: ${subDomains.length}
## 需求理解
${requirementSection}
## 子领域拆分
| # | Focus Area | Description | TASK Range | Effort |
|---|-----------|-------------|------------|--------|
${subDomains.map((s, i) => `| ${i+1} | ${s.focus_area} | ${s.description} | ${s.task_id_range[0]}-${s.task_id_range[1]} | ${s.estimated_effort} |`).join('\n')}
## 任务概览
${subDomains.map(sub => {
const domainTasks = allTasks.filter(t => t.source?.original_id?.startsWith('TASK') && t.source?.session_id === sessionId)
return `### ${sub.focus_area}\n\n` +
domainTasks.map(t => `- **${t.id}**: ${t.title} (${t.type}, ${t.effort}) ${t.depends_on.length ? '← ' + t.depends_on.join(', ') : ''}`).join('\n')
}).join('\n\n')}
## 冲突报告
${allConflicts.length === 0
? '✅ 无冲突检测到'
: allConflicts.map(c => `- **${c.type}** (${c.severity}): ${c.description}`).join('\n')}
## 执行
\`\`\`bash
/workflow:unified-execute-with-file PLAN="${sessionFolder}/.task/"
\`\`\`
**Session artifacts**: \`${sessionFolder}/\`
`
Write(`${sessionFolder}/plan.md`, planMd)
步骤 4.4：显示完成摘要
呈现会话统计信息和后续步骤。
// Display:
// - Session ID and directory path
// - Total domains planned
// - Total tasks generated
// - Conflict status (count and severity)
// - Execution command for next step
if (!autoMode) {
request_user_input({
questions: [{
header: "下一步",
id: "next_step",
question: `规划完成:\n- ${subDomains.length} 个子领域\n- ${allTasks.length} 个任务\n- ${allConflicts.length} 个冲突\n\n下一步:`,
options: [
{ label: "Execute Plan(Recommended)", description: "使用 unified-execute 执行计划" },
{ label: "Review Conflicts", description: "查看并解决冲突" },
{ label: "Done", description: "保存产物，稍后执行" }
]
}]
})
}
| 选项 | 操作 |
|---|---|
| 执行计划 | Skill(skill="workflow:unified-execute-with-file", args="PLAN=\"${sessionFolder}/.task/\"") |
| 查看冲突 | 显示 conflicts.json 内容以便手动解决 |
| 导出 | 将 plan.md + plan-note.md 复制到用户指定的位置 |
| 完成 | 显示产物路径，结束工作流 |
步骤 4.5：同步会话状态
$session-sync -y "Plan complete: {domains} domains, {tasks} tasks"
使用规划方面的经验更新 specs/*.md，并在 project-tech.json 中添加规划会话条目。
成功标准：
- 已生成包含完整摘要的
plan.md - 已在会话根目录收集
.task/TASK-*.json（可供 unified-execute 使用） - 会话目录中包含所有产物
- 已通过
$session-sync同步会话状态 - 已告知用户任务完成及后续步骤
配置
| 标志 | 默认值 | 描述 |
|---|---|---|
--max-domains | 5 | 可识别的子领域最大数量 |
-y, --yes | false | 自动确认所有决策 |
迭代模式
新建规划会话
User initiates: TASK="task description"
├─ No session exists → New session mode
├─ Analyze task with inline search tools
├─ Identify sub-domains
├─ Create plan-note.md template
├─ Generate requirement-analysis.json
│
├─ Serial domain planning:
│ ├─ Domain 1: explore → .task/TASK-*.json → fill plan-note.md
│ ├─ Domain 2: explore → .task/TASK-*.json → fill plan-note.md
│ └─ Domain N: ...
│
├─ Collect domain .task/*.json → session .task/
│
├─ Verify plan-note.md consistency
├─ Detect conflicts
├─ Generate plan.md summary
└─ Report completion
继续现有会话
User resumes: TASK="same task"
├─ Session exists → Continue mode
├─ Load plan-note.md and requirement-analysis.json
├─ Identify incomplete domains (empty task pool sections)
├─ Plan remaining domains serially
└─ Continue with conflict detection
错误处理与恢复
| 情况 | 操作 | 恢复方式 |
|---|---|---|
| 未检测到代码库 | 正常流程，仅进行需求规划 | 不使用代码库上下文继续 |
| 代码库搜索失败 | 使用现有上下文继续 | 在 plan-note.md 中注明限制 |
| 领域规划失败 | 记录错误，继续规划下一个领域 | 重试失败的领域，或手动规划 |
| 在计划备注中找不到章节 | 采取防御性措施创建章节 | 使用新章节继续 |
| 某个领域未生成任务 | 检查领域描述 | 优化范围并重试 |
| 冲突检测失败 | 使用空冲突列表继续 | 在完成摘要中注明 |
| 会话文件夹冲突 | 添加时间戳后缀 | 创建唯一文件夹 |
| plan-note.md 格式不一致 | 每个领域完成后验证并修复格式 | 重新读取并规范格式 |
最佳实践
开始规划之前
- 清晰的任务描述：详细的需求有助于更好地拆分子领域
- 参考文档：确保在第 1 阶段确定最新的 README 和设计文档
- 澄清歧义：在确定子领域之前解决不明确的需求
规划期间
- 检查计划备注：在各领域之间检查 plan-note.md，确认进度
- 验证独立性：确保子领域真正独立且重叠最少
- 检查依赖关系：应明确记录跨领域依赖关系
- 检查详情：必要时查看
domains/{domain}/.task/TASK-*.json了解具体信息 - 格式一致：严格遵循所有领域统一的任务摘要格式
- TASK ID 隔离：使用预分配且不重叠的范围，以避免 ID 冲突
规划之后
- 解决冲突：执行前处理高优先级或严重冲突
- 检查摘要：查看 plan.md，确保内容完整且准确
- 验证任务：确保所有任务都有明确的范围和修改目标
适用场景
在以下情况使用 collaborative-plan-with-file：
- 复杂任务涉及多个子领域（后端 + 前端 + 数据库等）
- 需要结构化的多领域任务拆分和冲突检测
- 规划涉及代码库多个部分的功能
- 需要预分配章节结构，以清晰划分领域
在以下情况使用 lite-plan：
- 单一领域，任务明确，无需拆分子领域
- 无需冲突检测的快速规划
在以下情况使用 req-plan-with-file：
- 需要按需求制定渐进式路线图（MVP → 多次迭代）
- 在详细规划之前进行更高层级的分解
在以下情况使用 analyze-with-file：
- 规划前需要深入分析
- 目标是理解和讨论，而非生成任务
现在执行 collaborative-plan-with-file，参数为：$ARGUMENTS
评论
支持 Markdown