Claude-Code-Workflow/.claude/commands/workflow/collaborative-plan-with-file.md

---
name: workflow:collaborative-plan-with-file
description: Collaborative planning with Plan Note - Understanding agent creates shared plan-note.md template, parallel agents fill pre-allocated sections, conflict detection without merge. Outputs executable plan-note.md.
argument-hint: "[-y|--yes] <task description> [--max-agents=5]"
allowed-tools: TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Bash(*), Write(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*)
---

## Auto Mode

When `--yes` or `-y`: Auto-approve splits, skip confirmations.

# Collaborative Planning Command

## Quick Start

```bash
# Basic usage
/workflow:collaborative-plan-with-file "Implement real-time notification system"

# With options
/workflow:collaborative-plan-with-file "Refactor authentication module" --max-agents=4
/workflow:collaborative-plan-with-file "Add payment gateway support" -y
```

**Context Source**: Understanding-Agent + Per-agent exploration
**Output Directory**: `.workflow/.planning/{session-id}/`
**Default Max Agents**: 5 (actual count based on requirement complexity)
**Core Innovation**: Plan Note - shared collaborative document, no merge needed

## Output Artifacts

### Phase 1: Understanding Agent

| Artifact | Description |
|----------|-------------|
| `plan-note.md` | Shared collaborative document with pre-allocated sections |
| `requirement-analysis.json` | Sub-domain assignments and TASK ID ranges |

### Phase 2: Per Sub-Agent

| Artifact | Description |
|----------|-------------|
| `planning-context.md` | Evidence paths + synthesized understanding |
| `plan.json` | Complete agent plan (detailed implementation) |
| Updates to `plan-note.md` | Agent fills pre-allocated sections |

### Phase 3: Final Output

| Artifact | Description |
|----------|-------------|
| `plan-note.md` | ⭐ Executable plan with conflict markers |
| `conflicts.json` | Detected conflicts with resolution options |
| `plan.md` | Human-readable summary |

## Overview

Unified collaborative planning workflow using **Plan Note** architecture:

1. **Understanding**: Agent analyzes requirements and creates plan-note.md template with pre-allocated sections
2. **Parallel Planning**: Each agent generates plan.json + fills their pre-allocated section in plan-note.md
3. **Conflict Detection**: Scan plan-note.md for conflicts (no merge needed)
4. **Completion**: Generate plan.md summary, ready for execution

```
┌─────────────────────────────────────────────────────────────────────────┐
│                    PLAN NOTE COLLABORATIVE PLANNING                      │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Phase 1: Understanding & Template Creation                              │
│     ├─ Understanding-Agent analyzes requirements                         │
│     ├─ Identify 2-5 sub-domains (focus areas)                            │
│     ├─ Create plan-note.md with pre-allocated sections                   │
│     └─ Assign TASK ID ranges (no conflicts)                              │
│                                                                          │
│  Phase 2: Parallel Agent Execution (No Locks Needed)                     │
│     ┌──────────────┬──────────────┬──────────────┐                       │
│     │   Agent 1    │   Agent 2    │   Agent N    │                       │
│     ├──────────────┼──────────────┼──────────────┤                       │
│     │ Own Section  │ Own Section  │ Own Section  │  ← Pre-allocated      │
│     │ plan.json    │ plan.json    │ plan.json    │  ← Detailed plans     │
│     └──────────────┴──────────────┴──────────────┘                       │
│                                                                          │
│  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)                                          │
│     ├─ Generate plan.md (human-readable)                                 │
│     └─ Ready for execution                                               │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘
```

## Output Structure

```
.workflow/.planning/{CPLAN-slug-YYYY-MM-DD}/
├── plan-note.md                  # ⭐ Core: Requirements + Tasks + Conflicts
├── requirement-analysis.json     # Phase 1: Sub-domain assignments
├── agents/                       # Phase 2: Per-agent detailed plans
│   ├── {focus-area-1}/
│   │   ├── planning-context.md  # Evidence + understanding
│   │   └── plan.json            # Complete agent plan
│   ├── {focus-area-2}/
│   │   └── ...
│   └── {focus-area-N}/
│       └── ...
├── conflicts.json                # Phase 3: Conflict details
└── plan.md                       # Phase 4: Human-readable summary
```

## Implementation

### Session Initialization

**Objective**: Create session context and directory structure for collaborative planning.

**Required Actions**:
1. Extract task description from `$ARGUMENTS`
2. Generate session ID with format: `CPLAN-{slug}-{date}`
   - slug: lowercase, alphanumeric, max 30 chars
   - date: YYYY-MM-DD (UTC+8)
3. Define session folder: `.workflow/.planning/{session-id}`
4. Parse command options:
   - `--max-agents=N` (default: 5)
   - `-y` or `--yes` for auto-approval mode
5. Create directory structure: `{session-folder}/agents/`

**Session Variables**:
- `sessionId`: Unique session identifier
- `sessionFolder`: Base directory for all artifacts
- `maxAgents`: Maximum number of parallel agents
- `autoMode`: Boolean for auto-confirmation

### Phase 1: Understanding & Template Creation

**Objective**: Analyze requirements and create the plan-note.md template with pre-allocated sections for parallel agents.

**Prerequisites**:
- Session initialized with valid sessionId and sessionFolder
- Task description available from $ARGUMENTS

**Workflow Steps**:

1. **Initialize Progress Tracking**
   - Create 4 todo items for workflow phases
   - Set Phase 1 status to `in_progress`

2. **Launch Understanding Agent**
   - Agent type: `cli-lite-planning-agent`
   - Execution mode: synchronous (run_in_background: false)

3. **Agent Tasks**:
   - **Understand Requirements**: Extract core objective, key points, constraints from task description
   - **Form Checklist**: Identify critical questions needing clarification
   - **Split Sub-Domains**: Identify 2-{maxAgents} parallelizable focus areas
   - **Create Plan Note**: Generate plan-note.md with pre-allocated sections

**Output Files**:

| File | Purpose |
|------|---------|
| `{sessionFolder}/plan-note.md` | Collaborative template with pre-allocated sections per agent |
| `{sessionFolder}/requirement-analysis.json` | Sub-domain assignments and TASK ID ranges |

**requirement-analysis.json Schema**:
- `session_id`: Session identifier
- `original_requirement`: Task description
- `complexity`: Low | Medium | High
- `sub_domains[]`: Array of focus areas with task_id_range and estimated_effort
- `total_agents`: Number of agents to spawn

**Success Criteria**:
- 2-{maxAgents} clear sub-domains identified
- Each sub-domain can be planned independently
- Plan Note template includes all pre-allocated sections
- TASK ID ranges have no overlap (100 IDs per agent)
- Requirements understanding is comprehensive

**Completion**:
- Log created artifacts
- Update Phase 1 todo status to `completed`

**Agent Call**:
```javascript
Task(
  subagent_type="cli-lite-planning-agent",
  run_in_background=false,
  description="Understand requirements and create plan template",
  prompt=`
## Mission: Create Plan Note Template

### Input Requirements
${taskDescription}

### Tasks
1. **Understand Requirements**: Extract core objective, key points, constraints
2. **Form Checklist**: Identify critical questions needing clarification
3. **Split Sub-Domains**: Identify 2-${maxAgents} parallelizable focus areas
4. **Create Plan Note**: Generate plan-note.md with pre-allocated sections

### Output Files

**File 1**: ${sessionFolder}/plan-note.md

Structure Requirements:
- YAML frontmatter: session_id, original_requirement, created_at, contributors, sub_domains, agent_sections, agent_task_id_ranges, status
- Section: ## 需求理解 (Core objectives, key points, constraints, split strategy)
- Section: ## 任务池 - {Focus Area 1} (Pre-allocated task section for agent 1, TASK-001 ~ TASK-100)
- Section: ## 任务池 - {Focus Area 2} (Pre-allocated task section for agent 2, TASK-101 ~ TASK-200)
- ... (One task pool section per sub-domain)
- Section: ## 依赖关系 (Auto-generated after all agents complete)
- Section: ## 冲突标记 (Populated in Phase 3)
- Section: ## 上下文证据 - {Focus Area 1} (Evidence for agent 1)
- Section: ## 上下文证据 - {Focus Area 2} (Evidence for agent 2)
- ... (One evidence section per sub-domain)

**File 2**: ${sessionFolder}/requirement-analysis.json
- session_id, original_requirement, complexity, sub_domains[], total_agents

### Success Criteria
- [ ] 2-${maxAgents} clear sub-domains identified
- [ ] Each sub-domain can be planned independently
- [ ] Plan Note template includes all pre-allocated sections
- [ ] TASK ID ranges have no overlap (100 IDs per agent)
`
)
```

### Phase 2: Parallel Sub-Agent Execution

**Objective**: Launch parallel planning agents to fill their pre-allocated sections in plan-note.md.

**Prerequisites**:
- Phase 1 completed successfully
- `{sessionFolder}/requirement-analysis.json` exists with sub-domain definitions
- `{sessionFolder}/plan-note.md` template created

**Workflow Steps**:

1. **Load Sub-Domain Configuration**
   - Read `{sessionFolder}/requirement-analysis.json`
   - Extract sub-domains array with focus_area, description, task_id_range

2. **Update Progress Tracking**
   - Set Phase 2 status to `in_progress`
   - Add sub-todo for each agent

3. **User Confirmation** (unless autoMode)
   - Display identified sub-domains with descriptions
   - Options: "开始规划" / "调整拆分" / "取消"
   - Skip if autoMode enabled

4. **Create Agent Directories**
   - For each sub-domain: `{sessionFolder}/agents/{focus-area}/`

5. **Launch Parallel Agents**
   - Agent type: `cli-lite-planning-agent`
   - Execution mode: synchronous (run_in_background: false)
   - Launch ALL agents in parallel (single message with multiple Task calls)

**Per-Agent Context**:
- Focus area name and description
- Assigned TASK ID range (no overlap with other agents)
- Session ID and folder path

**Per-Agent Tasks**:

| Task | Output | Description |
|------|--------|-------------|
| Generate plan.json | `{sessionFolder}/agents/{focus-area}/plan.json` | Complete detailed plan following schema |
| Update plan-note.md | Sync to shared file | Fill pre-allocated "任务池" and "上下文证据" sections |

**Task Summary Format** (for plan-note.md):
- Task header: `### TASK-{ID}: {Title} [{focus-area}]`
- Status, Complexity, Dependencies
- Scope description
- Modification points with file:line references
- Conflict risk assessment

**Evidence Format** (for plan-note.md):
- Related files with relevance scores
- Existing patterns identified
- Constraints discovered

**Agent Execution Rules**:
- Each agent modifies ONLY its pre-allocated sections
- Use assigned TASK ID range exclusively
- No locking needed (exclusive sections)
- Include conflict_risk assessment for each task

**Completion**:
- Wait for all agents to complete
- Log generated artifacts for each agent
- Update Phase 2 todo status to `completed`

**User Confirmation** (unless autoMode):
```javascript
if (!autoMode) {
  AskUserQuestion({
    questions: [{
      question: `已识别 ${subDomains.length} 个子领域:\n${subDomains.map((s, i) => `${i+1}. ${s.focus_area}: ${s.description}`).join('\n')}\n\n确认开始并行规划?`,
      header: "Confirm Split",
      multiSelect: false,
      options: [
        { label: "开始规划", description: "启动并行sub-agent" },
        { label: "调整拆分", description: "修改子领域划分" },
        { label: "取消", description: "退出规划" }
      ]
    }]
  })
}
```

**Launch Parallel Agents** (single message, multiple Task calls):
```javascript
// Create agent directories
subDomains.forEach(sub => {
  Bash(`mkdir -p ${sessionFolder}/agents/${sub.focus_area}`)
})

// Launch all agents in parallel
subDomains.map(sub =>
  Task(
    subagent_type="cli-lite-planning-agent",
    run_in_background=false,
    description=`Plan: ${sub.focus_area}`,
    prompt=`
## Sub-Agent Context

**Focus Area**: ${sub.focus_area}
**Description**: ${sub.description}
**TASK ID Range**: ${sub.task_id_range[0]}-${sub.task_id_range[1]}
**Session**: ${sessionId}

## Dual Output Tasks

### Task 1: Generate Complete plan.json
Output: ${sessionFolder}/agents/${sub.focus_area}/plan.json
Schema: ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json

### Task 2: Sync Summary to plan-note.md

**Locate Your Sections**:
- Task Pool: "## 任务池 - ${toTitleCase(sub.focus_area)}"
- Evidence: "## 上下文证据 - ${toTitleCase(sub.focus_area)}"

**Task Summary Format**:
- Task header: ### TASK-${sub.task_id_range[0]}: Task Title [${sub.focus_area}]
- Fields: 状态, 复杂度, 依赖, 范围, 修改点, 冲突风险

**Evidence Format**:
- 相关文件, 现有模式, 约束

## Execution Steps
1. Generate complete plan.json
2. Extract summary from plan.json
3. Read ${sessionFolder}/plan-note.md
4. Locate and replace your task pool section
5. Locate and replace your evidence section
6. Write back plan-note.md

## Important
- Only modify your pre-allocated sections
- Use assigned TASK ID range: ${sub.task_id_range[0]}-${sub.task_id_range[1]}
`
  )
)
```

### Phase 3: Conflict Detection

**Objective**: Analyze plan-note.md for conflicts across all agent contributions without merging files.

**Prerequisites**:
- Phase 2 completed successfully
- All agents have updated plan-note.md with their sections
- `{sessionFolder}/plan-note.md` contains all task and evidence sections

**Workflow Steps**:

1. **Update Progress Tracking**
   - Set Phase 3 status to `in_progress`

2. **Parse Plan Note**
   - Read `{sessionFolder}/plan-note.md`
   - Extract YAML frontmatter (session metadata)
   - Parse markdown sections by heading levels
   - Identify all "任务池" sections

3. **Extract All Tasks**
   - For each "任务池" section:
     - Extract tasks matching pattern: `### TASK-{ID}: {Title} [{author}]`
     - Parse task details: status, complexity, dependencies, modification points, conflict risk
   - Consolidate into single task list

4. **Detect Conflicts**

   **File Conflicts**:
   - Group modification points by file:location
   - Identify locations modified by multiple agents
   - Record: severity=high, tasks involved, agents involved, suggested resolution

   **Dependency Cycles**:
   - Build dependency graph from task dependencies
   - Detect cycles using depth-first search
   - Record: severity=critical, cycle path, suggested resolution

   **Strategy Conflicts**:
   - Group tasks by files they modify
   - Identify files with high/medium conflict risk from multiple agents
   - Record: severity=medium, tasks involved, agents involved, suggested resolution

5. **Generate Conflict Artifacts**

   **conflicts.json**:
   - Write to `{sessionFolder}/conflicts.json`
   - Include: detected_at, total_tasks, total_agents, conflicts array
   - Each conflict: type, severity, tasks_involved, description, suggested_resolution

   **Update plan-note.md**:
   - Locate "## 冲突标记" section
   - Generate markdown summary of conflicts
   - Replace section content with conflict markdown

6. **Completion**
   - Log conflict detection summary
   - Display conflict details if any found
   - Update Phase 3 todo status to `completed`

**Conflict Types**:

| Type | Severity | Detection Logic |
|------|----------|-----------------|
| file_conflict | high | Same file:location modified by multiple agents |
| dependency_cycle | critical | Circular dependencies in task graph |
| strategy_conflict | medium | Multiple high-risk tasks in same file from different agents |

**Conflict Detection Functions**:

**parsePlanNote(markdown)**:
- Input: Raw markdown content of plan-note.md
- Process:
  - Extract YAML frontmatter between `---` markers
  - Parse frontmatter as YAML to get session metadata
  - Scan for heading patterns `^(#{2,})\s+(.+)$`
  - Build sections array with: level, heading, start position, content
- Output: `{ frontmatter: object, sections: array }`

**extractTasksFromSection(content, sectionHeading)**:
- Input: Section content text, section heading for attribution
- Process:
  - Match task pattern: `### (TASK-\d+):\s+(.+?)\s+\[(.+?)\]`
  - For each match: extract taskId, title, author
  - Call parseTaskDetails for additional fields
- Output: Array of task objects with id, title, author, source_section, ...details

**parseTaskDetails(content)**:
- Input: Task content block
- Process:
  - Extract fields via regex patterns:
    - `**状态**:\s*(.+)` → status
    - `**复杂度**:\s*(.+)` → complexity
    - `**依赖**:\s*(.+)` → depends_on (extract TASK-\d+ references)
    - `**冲突风险**:\s*(.+)` → conflict_risk
  - Extract modification points: `-\s+\`([^`]+):\s*([^`]+)\`:\s*(.+)` → file, location, summary
- Output: Details object with status, complexity, depends_on[], modification_points[], conflict_risk

**detectFileConflicts(tasks)**:
- Input: All tasks array
- Process:
  - Build fileMap: `{ "file:location": [{ task_id, task_title, source_agent, change }] }`
  - For each location with multiple modifications from different agents:
    - Create conflict with type='file_conflict', severity='high'
    - Include: location, tasks_involved, agents_involved, modifications
    - Suggested resolution: 'Coordinate modification order or merge changes'
- Output: Array of file conflict objects

**detectDependencyCycles(tasks)**:
- Input: All tasks array
- Process:
  - Build dependency graph: `{ taskId: [dependsOn_taskIds] }`
  - Use DFS with recursion stack to detect cycles
  - For each cycle found:
    - Create conflict with type='dependency_cycle', severity='critical'
    - Include: cycle path as tasks_involved
    - Suggested resolution: 'Remove or reorganize dependencies'
- Output: Array of dependency cycle conflict objects

**detectStrategyConflicts(tasks)**:
- Input: All tasks array
- Process:
  - Group tasks by files they modify
  - For each file with tasks from multiple agents:
    - Filter for high/medium conflict_risk tasks
    - If >1 high-risk tasks from different agents:
      - Create conflict with type='strategy_conflict', severity='medium'
      - Include: file, tasks_involved, agents_involved
      - Suggested resolution: 'Review approaches and align on single strategy'
- Output: Array of strategy conflict objects

**generateConflictMarkdown(conflicts)**:
- Input: Array of conflict objects
- Process:
  - If empty: return '✅ 无冲突检测到'
  - For each conflict:
    - Generate header: `### CONFLICT-{padded_index}: {description}`
    - Add fields: 严重程度, 涉及任务, 涉及Agent
    - Add 问题详情 based on conflict type
    - Add 建议解决方案
    - Add 决策状态: [ ] 待解决
- Output: Markdown string for plan-note.md "## 冲突标记" section

**replaceSectionContent(markdown, sectionHeading, newContent)**:
- Input: Original markdown, target section heading, new content
- Process:
  - 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
- Output: Updated markdown string

### Phase 4: Completion

**Objective**: Generate human-readable plan summary and finalize workflow.

**Prerequisites**:
- Phase 3 completed successfully
- Conflicts detected and documented in plan-note.md
- All artifacts generated

**Workflow Steps**:

1. **Update Progress Tracking**
   - Set Phase 4 status to `in_progress`

2. **Read Final State**
   - Read `{sessionFolder}/plan-note.md`
   - Extract frontmatter metadata
   - Load conflicts from Phase 3

3. **Generate plan.md**
   - Create human-readable summary including:
     - Session metadata
     - Requirements understanding
     - Sub-domain breakdown
     - Task overview by focus area
     - Conflict report
     - Execution instructions

4. **Write Summary File**
   - Write to `{sessionFolder}/plan.md`

5. **Display Completion Summary**
   - Session statistics
   - File structure
   - Execution command
   - Conflict status

6. **Update Todo**
   - Set Phase 4 status to `completed`

**plan.md Structure**:

| Section | Content |
|---------|---------|
| Header | Session ID, created time, original requirement |
| Requirements | Copy from plan-note.md "## 需求理解" section |
| Sub-Domain Split | List each focus area with description and task ID range |
| Task Overview | Tasks grouped by focus area with complexity and dependencies |
| Conflict Report | Summary of detected conflicts or "无冲突" |
| Execution | Command to execute the plan |

**Required Function** (semantic description):
- **generateHumanReadablePlan**: Extract sections from plan-note.md and format as readable plan.md with session info, requirements, tasks, and conflicts

## Configuration

| Flag | Default | Description |
|------|---------|-------------|
| `--max-agents` | 5 | Maximum sub-agents to spawn |
| `-y, --yes` | false | Auto-confirm all decisions |

## Error Handling

| Error | Resolution |
|-------|------------|
| Understanding agent fails | Retry once, provide more context |
| Planning agent fails | Skip failed agent, continue with others |
| Section not found in plan-note | Agent creates section (defensive) |
| Conflict detection fails | Continue with empty conflicts |


## Best Practices

1. **Clear Requirements**: Detailed requirements → better sub-domain splitting
2. **Review Plan Note**: Check plan-note.md before execution
3. **Resolve Conflicts**: Address high/critical conflicts before execution
4. **Inspect Details**: Use agents/{focus-area}/plan.json for deep dive

---

**Now execute collaborative-plan-with-file for**: $ARGUMENTS