mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
rename: collaborative-plan → collaborative-plan-with-file
This commit is contained in:
catlog22
761
.claude/commands/workflow/collaborative-plan-with-file.md
Normal file
761
.claude/commands/workflow/collaborative-plan-with-file.md
Normal file
@@ -0,0 +1,761 @@
|
||||
---
|
||||
name: workflow:collaborative-plan-with-file
|
||||
description: Unified collaborative planning with dynamic requirement splitting, parallel sub-agent exploration/understanding/planning, and automatic merge. Each agent maintains process files for full traceability.
|
||||
argument-hint: "[-y|--yes] <task description> [--max-agents=5] [--depth=normal|deep] [--merge-rule=consensus|priority]"
|
||||
allowed-tools: TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Bash(*), Write(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-approve splits, use default merge rule, 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" --depth=deep
|
||||
/workflow:collaborative-plan-with-file "Migrate to microservices" --merge-rule=priority
|
||||
```
|
||||
|
||||
**Context Source**: ACE semantic search + Per-agent CLI exploration
|
||||
**Output Directory**: `.workflow/.planning/{session-id}/`
|
||||
**Default Max Agents**: 5 (actual count based on requirement complexity)
|
||||
**CLI Tools**: cli-lite-planning-agent (internally calls ccw cli with gemini/codex/qwen)
|
||||
**Schema**: plan-json-schema.json (sub-plans & final plan share same base schema)
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
### Per Sub-Agent (Phase 2)
|
||||
|
||||
| Artifact | Description |
|
||||
|----------|-------------|
|
||||
| `planning-context.md` | Evidence paths + synthesized understanding |
|
||||
| `sub-plan.json` | Sub-plan following plan-json-schema.json |
|
||||
|
||||
### Final Output (Phase 4)
|
||||
|
||||
| Artifact | Description |
|
||||
|----------|-------------|
|
||||
| `requirement-analysis.json` | Requirement breakdown and sub-agent assignments |
|
||||
| `conflicts.json` | Detected conflicts between sub-plans |
|
||||
| `plan.json` | Merged plan (plan-json-schema + merge_metadata) |
|
||||
| `plan.md` | Human-readable plan summary |
|
||||
|
||||
**Agent**: `cli-lite-planning-agent` with `process_docs: true` for sub-agents
|
||||
|
||||
## Overview
|
||||
|
||||
Unified collaborative planning workflow that:
|
||||
|
||||
1. **Analyzes** complex requirements and splits into sub-requirements
|
||||
2. **Spawns** parallel sub-agents, each responsible for one sub-requirement
|
||||
3. **Each agent** maintains process files: planning-refs.md + sub-plan.json
|
||||
4. **Merges** all sub-plans into unified plan.json with conflict resolution
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ COLLABORATIVE PLANNING │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Phase 1: Requirement Analysis & Splitting │
|
||||
│ ├─ Analyze requirement complexity │
|
||||
│ ├─ Identify 2-5 sub-requirements (focus areas) │
|
||||
│ └─ Write requirement-analysis.json │
|
||||
│ │
|
||||
│ Phase 2: Parallel Sub-Agent Execution │
|
||||
│ ┌──────────────┬──────────────┬──────────────┐ │
|
||||
│ │ Agent 1 │ Agent 2 │ Agent N │ │
|
||||
├──────────────┼──────────────┼──────────────┤ │
|
||||
│ │ planning │ planning │ planning │ → planning-context.md│
|
||||
│ │ + sub-plan │ + sub-plan │ + sub-plan │ → sub-plan.json │
|
||||
│ └──────────────┴──────────────┴──────────────┘ │
|
||||
│ │
|
||||
│ Phase 3: Cross-Verification & Conflict Detection │
|
||||
│ ├─ Load all sub-plan.json files │
|
||||
│ ├─ Detect conflicts (effort, approach, dependencies) │
|
||||
│ └─ Write conflicts.json │
|
||||
│ │
|
||||
│ Phase 4: Merge & Synthesis │
|
||||
│ ├─ Resolve conflicts using merge-rule │
|
||||
│ ├─ Merge all sub-plans into unified plan │
|
||||
│ └─ Write plan.json + plan.md │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Output Structure
|
||||
|
||||
```
|
||||
.workflow/.planning/{CPLAN-slug-YYYY-MM-DD}/
|
||||
├── requirement-analysis.json # Phase 1: Requirement breakdown
|
||||
├── agents/ # Phase 2: Per-agent process files
|
||||
│ ├── {focus-area-1}/
|
||||
│ │ ├── planning-context.md # Evidence + understanding
|
||||
│ │ └── sub-plan.json # Agent's plan for this focus area
|
||||
│ ├── {focus-area-2}/
|
||||
│ │ └── ...
|
||||
│ └── {focus-area-N}/
|
||||
│ └── ...
|
||||
├── conflicts.json # Phase 3: Detected conflicts
|
||||
├── plan.json # Phase 4: Unified merged plan
|
||||
└── plan.md # Phase 4: Human-readable plan
|
||||
```
|
||||
|
||||
## Implementation
|
||||
|
||||
### Session Initialization
|
||||
|
||||
```javascript
|
||||
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
|
||||
|
||||
const taskDescription = "$ARGUMENTS"
|
||||
const taskSlug = taskDescription.toLowerCase()
|
||||
.replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-')
|
||||
.substring(0, 30)
|
||||
|
||||
const sessionId = `CPLAN-${taskSlug}-${getUtc8ISOString().substring(0, 10)}`
|
||||
const sessionFolder = `.workflow/.planning/${sessionId}`
|
||||
|
||||
// Parse options
|
||||
const maxAgents = parseInt($ARGUMENTS.match(/--max-agents=(\d+)/)?.[1] || '5')
|
||||
const depth = $ARGUMENTS.match(/--depth=(normal|deep)/)?.[1] || 'normal'
|
||||
const mergeRule = $ARGUMENTS.match(/--merge-rule=(consensus|priority)/)?.[1] || 'consensus'
|
||||
const autoMode = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
|
||||
Bash(`mkdir -p ${sessionFolder}/agents`)
|
||||
```
|
||||
|
||||
### Phase 1: Requirement Analysis & Splitting
|
||||
|
||||
Use CLI to analyze and split requirements:
|
||||
|
||||
```javascript
|
||||
TodoWrite({ todos: [
|
||||
{ content: "Phase 1: Requirement Analysis", status: "in_progress", activeForm: "Analyzing requirements" },
|
||||
{ content: "Phase 2: Parallel Agent Execution", status: "pending", activeForm: "Running agents" },
|
||||
{ content: "Phase 3: Conflict Detection", status: "pending", activeForm: "Detecting conflicts" },
|
||||
{ content: "Phase 4: Merge & Synthesis", status: "pending", activeForm: "Merging plans" }
|
||||
]})
|
||||
|
||||
// Step 1.1: Use CLI to analyze requirement and propose splits
|
||||
Bash({
|
||||
command: `ccw cli -p "
|
||||
PURPOSE: Analyze requirement and identify distinct sub-requirements/focus areas
|
||||
Success: 2-${maxAgents} clearly separated sub-requirements that can be planned independently
|
||||
|
||||
TASK:
|
||||
• Understand the overall requirement: '${taskDescription}'
|
||||
• Identify major components, features, or concerns
|
||||
• Split into 2-${maxAgents} independent sub-requirements
|
||||
• Each sub-requirement should be:
|
||||
- Self-contained (can be planned independently)
|
||||
- Non-overlapping (minimal dependency on other sub-requirements)
|
||||
- Roughly equal in complexity
|
||||
• For each sub-requirement, provide:
|
||||
- focus_area: Short identifier (e.g., 'auth-backend', 'ui-components')
|
||||
- description: What this sub-requirement covers
|
||||
- key_concerns: Main challenges or considerations
|
||||
- suggested_cli_tool: Which CLI tool is best suited (gemini/codex/qwen)
|
||||
|
||||
MODE: analysis
|
||||
|
||||
CONTEXT: @**/*
|
||||
|
||||
EXPECTED: JSON output with structure:
|
||||
{
|
||||
\"original_requirement\": \"...\",
|
||||
\"complexity\": \"low|medium|high\",
|
||||
\"sub_requirements\": [
|
||||
{
|
||||
\"index\": 1,
|
||||
\"focus_area\": \"...\",
|
||||
\"description\": \"...\",
|
||||
\"key_concerns\": [\"...\"],
|
||||
\"suggested_cli_tool\": \"gemini|codex|qwen\",
|
||||
\"estimated_effort\": \"low|medium|high\"
|
||||
}
|
||||
],
|
||||
\"dependencies_between_subs\": [
|
||||
{ \"from\": 1, \"to\": 2, \"reason\": \"...\" }
|
||||
],
|
||||
\"rationale\": \"Why this split was chosen\"
|
||||
}
|
||||
|
||||
CONSTRAINTS: Maximum ${maxAgents} sub-requirements | Ensure clear boundaries
|
||||
" --tool gemini --mode analysis`,
|
||||
run_in_background: true
|
||||
})
|
||||
|
||||
// Wait for CLI completion and parse result
|
||||
// ... (hook callback will provide result)
|
||||
```
|
||||
|
||||
**After CLI completes**:
|
||||
|
||||
```javascript
|
||||
// Parse CLI output to extract sub-requirements
|
||||
const analysisResult = parseCLIOutput(cliOutput)
|
||||
const subRequirements = analysisResult.sub_requirements
|
||||
|
||||
// Write requirement-analysis.json
|
||||
Write(`${sessionFolder}/requirement-analysis.json`, JSON.stringify({
|
||||
session_id: sessionId,
|
||||
original_requirement: taskDescription,
|
||||
analysis_timestamp: getUtc8ISOString(),
|
||||
complexity: analysisResult.complexity,
|
||||
sub_requirements: subRequirements,
|
||||
dependencies_between_subs: analysisResult.dependencies_between_subs,
|
||||
rationale: analysisResult.rationale,
|
||||
options: { maxAgents, depth, mergeRule }
|
||||
}, null, 2))
|
||||
|
||||
// Create agent folders
|
||||
subRequirements.forEach(sub => {
|
||||
Bash(`mkdir -p ${sessionFolder}/agents/${sub.focus_area}`)
|
||||
})
|
||||
|
||||
// User confirmation (unless auto mode)
|
||||
if (!autoMode) {
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: `已识别 ${subRequirements.length} 个子需求:\n${subRequirements.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: "退出规划" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 2: Parallel Sub-Agent Execution
|
||||
|
||||
Launch one agent per sub-requirement, each maintaining its own process files:
|
||||
|
||||
```javascript
|
||||
TodoWrite({ todos: [
|
||||
{ content: "Phase 1: Requirement Analysis", status: "completed", activeForm: "Analyzing requirements" },
|
||||
{ content: "Phase 2: Parallel Agent Execution", status: "in_progress", activeForm: "Running agents" },
|
||||
...subRequirements.map((sub, i) => ({
|
||||
content: ` → Agent ${i+1}: ${sub.focus_area}`,
|
||||
status: "pending",
|
||||
activeForm: `Planning ${sub.focus_area}`
|
||||
})),
|
||||
{ content: "Phase 3: Conflict Detection", status: "pending", activeForm: "Detecting conflicts" },
|
||||
{ content: "Phase 4: Merge & Synthesis", status: "pending", activeForm: "Merging plans" }
|
||||
]})
|
||||
|
||||
// Launch all sub-agents in parallel
|
||||
const agentPromises = subRequirements.map((sub, index) => {
|
||||
return Task({
|
||||
subagent_type: "cli-lite-planning-agent",
|
||||
run_in_background: false,
|
||||
description: `Plan: ${sub.focus_area}`,
|
||||
prompt: `
|
||||
## Sub-Agent Context
|
||||
|
||||
You are planning ONE sub-requirement. Generate process docs + sub-plan.
|
||||
|
||||
**Focus Area**: ${sub.focus_area}
|
||||
**Description**: ${sub.description}
|
||||
**Key Concerns**: ${sub.key_concerns.join(', ')}
|
||||
**CLI Tool**: ${sub.suggested_cli_tool}
|
||||
**Depth**: ${depth}
|
||||
|
||||
## Input Context
|
||||
|
||||
\`\`\`json
|
||||
{
|
||||
"task_description": "${sub.description}",
|
||||
"schema_path": "~/.claude/workflows/cli-templates/schemas/plan-json-schema.json",
|
||||
"session": { "id": "${sessionId}", "folder": "${sessionFolder}" },
|
||||
"process_docs": true,
|
||||
"focus_area": "${sub.focus_area}",
|
||||
"output_folder": "${sessionFolder}/agents/${sub.focus_area}",
|
||||
"cli_config": { "tool": "${sub.suggested_cli_tool}" },
|
||||
"parent_requirement": "${taskDescription}"
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
## Output Requirements
|
||||
|
||||
Write 2 files to \`${sessionFolder}/agents/${sub.focus_area}/\`:
|
||||
1. **planning-context.md** - Evidence paths + synthesized understanding
|
||||
2. **sub-plan.json** - Plan with \`_metadata.source_agent: "${sub.focus_area}"\`
|
||||
|
||||
See cli-lite-planning-agent documentation for file formats.
|
||||
`
|
||||
})
|
||||
})
|
||||
|
||||
// Wait for all agents to complete
|
||||
const agentResults = await Promise.all(agentPromises)
|
||||
```
|
||||
|
||||
### Phase 3: Cross-Verification & Conflict Detection
|
||||
|
||||
Load all sub-plans and detect conflicts:
|
||||
|
||||
```javascript
|
||||
TodoWrite({ todos: [
|
||||
{ content: "Phase 1: Requirement Analysis", status: "completed", activeForm: "Analyzing requirements" },
|
||||
{ content: "Phase 2: Parallel Agent Execution", status: "completed", activeForm: "Running agents" },
|
||||
{ content: "Phase 3: Conflict Detection", status: "in_progress", activeForm: "Detecting conflicts" },
|
||||
{ content: "Phase 4: Merge & Synthesis", status: "pending", activeForm: "Merging plans" }
|
||||
]})
|
||||
|
||||
// Load all sub-plans
|
||||
const subPlans = subRequirements.map(sub => {
|
||||
const planPath = `${sessionFolder}/agents/${sub.focus_area}/sub-plan.json`
|
||||
const content = Read(planPath)
|
||||
return {
|
||||
focus_area: sub.focus_area,
|
||||
index: sub.index,
|
||||
plan: JSON.parse(content)
|
||||
}
|
||||
})
|
||||
|
||||
// Detect conflicts
|
||||
const conflicts = {
|
||||
detected_at: getUtc8ISOString(),
|
||||
total_sub_plans: subPlans.length,
|
||||
conflicts: []
|
||||
}
|
||||
|
||||
// 1. Effort conflicts (same task estimated differently)
|
||||
const effortConflicts = detectEffortConflicts(subPlans)
|
||||
conflicts.conflicts.push(...effortConflicts)
|
||||
|
||||
// 2. File conflicts (multiple agents modifying same file)
|
||||
const fileConflicts = detectFileConflicts(subPlans)
|
||||
conflicts.conflicts.push(...fileConflicts)
|
||||
|
||||
// 3. Approach conflicts (different approaches to same problem)
|
||||
const approachConflicts = detectApproachConflicts(subPlans)
|
||||
conflicts.conflicts.push(...approachConflicts)
|
||||
|
||||
// 4. Dependency conflicts (circular or missing dependencies)
|
||||
const dependencyConflicts = detectDependencyConflicts(subPlans)
|
||||
conflicts.conflicts.push(...dependencyConflicts)
|
||||
|
||||
// Write conflicts.json
|
||||
Write(`${sessionFolder}/conflicts.json`, JSON.stringify(conflicts, null, 2))
|
||||
|
||||
console.log(`
|
||||
## Conflict Detection Complete
|
||||
|
||||
**Total Sub-Plans**: ${subPlans.length}
|
||||
**Conflicts Found**: ${conflicts.conflicts.length}
|
||||
|
||||
${conflicts.conflicts.length > 0 ? `
|
||||
### Conflicts:
|
||||
${conflicts.conflicts.map((c, i) => `
|
||||
${i+1}. **${c.type}** (${c.severity})
|
||||
- Agents: ${c.agents_involved.join(' vs ')}
|
||||
- Issue: ${c.description}
|
||||
- Suggested Resolution: ${c.suggested_resolution}
|
||||
`).join('\n')}
|
||||
` : '✅ No conflicts detected - sub-plans are compatible'}
|
||||
`)
|
||||
```
|
||||
|
||||
**Conflict Detection Functions**:
|
||||
|
||||
```javascript
|
||||
function detectFileConflicts(subPlans) {
|
||||
const fileModifications = {}
|
||||
const conflicts = []
|
||||
|
||||
subPlans.forEach(sp => {
|
||||
sp.plan.tasks.forEach(task => {
|
||||
task.modification_points?.forEach(mp => {
|
||||
if (!fileModifications[mp.file]) {
|
||||
fileModifications[mp.file] = []
|
||||
}
|
||||
fileModifications[mp.file].push({
|
||||
focus_area: sp.focus_area,
|
||||
task_id: task.id,
|
||||
target: mp.target,
|
||||
change: mp.change
|
||||
})
|
||||
})
|
||||
})
|
||||
})
|
||||
|
||||
Object.entries(fileModifications).forEach(([file, mods]) => {
|
||||
if (mods.length > 1) {
|
||||
const agents = [...new Set(mods.map(m => m.focus_area))]
|
||||
if (agents.length > 1) {
|
||||
conflicts.push({
|
||||
type: "file_conflict",
|
||||
severity: "high",
|
||||
file: file,
|
||||
agents_involved: agents,
|
||||
modifications: mods,
|
||||
description: `Multiple agents modifying ${file}`,
|
||||
suggested_resolution: "Sequence modifications or consolidate"
|
||||
})
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
return conflicts
|
||||
}
|
||||
|
||||
function detectEffortConflicts(subPlans) {
|
||||
// Compare effort estimates across similar tasks
|
||||
// Return conflicts where estimates differ by >50%
|
||||
return []
|
||||
}
|
||||
|
||||
function detectApproachConflicts(subPlans) {
|
||||
// Analyze approaches for contradictions
|
||||
// Return conflicts where approaches are incompatible
|
||||
return []
|
||||
}
|
||||
|
||||
function detectDependencyConflicts(subPlans) {
|
||||
// Check for circular dependencies
|
||||
// Check for missing dependencies
|
||||
return []
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 4: Merge & Synthesis
|
||||
|
||||
Use cli-lite-planning-agent to merge all sub-plans:
|
||||
|
||||
```javascript
|
||||
TodoWrite({ todos: [
|
||||
{ content: "Phase 1: Requirement Analysis", status: "completed", activeForm: "Analyzing requirements" },
|
||||
{ content: "Phase 2: Parallel Agent Execution", status: "completed", activeForm: "Running agents" },
|
||||
{ content: "Phase 3: Conflict Detection", status: "completed", activeForm: "Detecting conflicts" },
|
||||
{ content: "Phase 4: Merge & Synthesis", status: "in_progress", activeForm: "Merging plans" }
|
||||
]})
|
||||
|
||||
// Collect all planning context documents for context
|
||||
const contextDocs = subRequirements.map(sub => {
|
||||
const path = `${sessionFolder}/agents/${sub.focus_area}/planning-context.md`
|
||||
return {
|
||||
focus_area: sub.focus_area,
|
||||
content: Read(path)
|
||||
}
|
||||
})
|
||||
|
||||
// Invoke planning agent to merge
|
||||
Task({
|
||||
subagent_type: "cli-lite-planning-agent",
|
||||
run_in_background: false,
|
||||
description: "Merge sub-plans into unified plan",
|
||||
prompt: `
|
||||
## Mission: Merge Multiple Sub-Plans
|
||||
|
||||
Merge ${subPlans.length} sub-plans into a single unified plan.
|
||||
|
||||
## Schema Reference
|
||||
|
||||
Execute: cat ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json
|
||||
|
||||
The merged plan follows the SAME schema as lite-plan, with ONE additional field:
|
||||
- \`merge_metadata\`: Object containing merge-specific information
|
||||
|
||||
## Project Context
|
||||
|
||||
1. Read: .workflow/project-tech.json
|
||||
2. Read: .workflow/project-guidelines.json
|
||||
|
||||
## Original Requirement
|
||||
|
||||
${taskDescription}
|
||||
|
||||
## Sub-Plans to Merge
|
||||
|
||||
${subPlans.map(sp => `
|
||||
### Sub-Plan: ${sp.focus_area}
|
||||
\`\`\`json
|
||||
${JSON.stringify(sp.plan, null, 2)}
|
||||
\`\`\`
|
||||
`).join('\n')}
|
||||
|
||||
## Planning Context Documents
|
||||
|
||||
${contextDocs.map(cd => `
|
||||
### Context: ${cd.focus_area}
|
||||
${cd.content}
|
||||
`).join('\n')}
|
||||
|
||||
## Detected Conflicts
|
||||
|
||||
\`\`\`json
|
||||
${JSON.stringify(conflicts, null, 2)}
|
||||
\`\`\`
|
||||
|
||||
## Merge Rules
|
||||
|
||||
**Rule**: ${mergeRule}
|
||||
${mergeRule === 'consensus' ? `
|
||||
- Equal weight to all sub-plans
|
||||
- Conflicts resolved by finding middle ground
|
||||
- Combine overlapping tasks
|
||||
` : `
|
||||
- Priority based on sub-requirement index
|
||||
- Earlier agents' decisions take precedence
|
||||
- Later agents adapt to earlier decisions
|
||||
`}
|
||||
|
||||
## Requirements
|
||||
|
||||
1. **Task Consolidation**:
|
||||
- Combine tasks that modify same files
|
||||
- Preserve unique tasks from each sub-plan
|
||||
- Ensure no task duplication
|
||||
- Maintain clear task boundaries
|
||||
|
||||
2. **Dependency Resolution**:
|
||||
- Cross-reference dependencies between sub-plans
|
||||
- Create global task ordering
|
||||
- Handle inter-sub-plan dependencies
|
||||
|
||||
3. **Conflict Resolution**:
|
||||
- Apply ${mergeRule} rule to resolve conflicts
|
||||
- Document resolution rationale
|
||||
- Ensure no contradictions in final plan
|
||||
|
||||
4. **Metadata Preservation**:
|
||||
- Track which sub-plan each task originated from (source_agent field)
|
||||
- Include merge_metadata with:
|
||||
- merged_from: list of sub-plan focus areas
|
||||
- conflicts_resolved: count
|
||||
- merge_rule: ${mergeRule}
|
||||
|
||||
## Output
|
||||
|
||||
Write to ${sessionFolder}/plan.json following plan-json-schema.json.
|
||||
|
||||
Add ONE extension field for merge tracking:
|
||||
|
||||
\`\`\`json
|
||||
{
|
||||
// ... all standard plan-json-schema fields ...
|
||||
|
||||
"merge_metadata": {
|
||||
"source_session": "${sessionId}",
|
||||
"merged_from": ["focus-area-1", "focus-area-2"],
|
||||
"sub_plan_count": N,
|
||||
"conflicts_detected": N,
|
||||
"conflicts_resolved": N,
|
||||
"merge_rule": "${mergeRule}",
|
||||
"merged_at": "ISO-timestamp"
|
||||
}
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
Each task should include \`source_agent\` field indicating which sub-plan it originated from.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] All sub-plan tasks included (or explicitly merged)
|
||||
- [ ] Conflicts resolved per ${mergeRule} rule
|
||||
- [ ] Dependencies form valid DAG (no cycles)
|
||||
- [ ] merge_metadata present
|
||||
- [ ] Schema compliance verified
|
||||
- [ ] plan.json written to ${sessionFolder}/plan.json
|
||||
`
|
||||
})
|
||||
|
||||
// Generate human-readable plan.md
|
||||
const plan = JSON.parse(Read(`${sessionFolder}/plan.json`))
|
||||
const planMd = generatePlanMarkdown(plan, subRequirements, conflicts)
|
||||
Write(`${sessionFolder}/plan.md`, planMd)
|
||||
```
|
||||
|
||||
**Markdown Generation**:
|
||||
|
||||
```javascript
|
||||
function generatePlanMarkdown(plan, subRequirements, conflicts) {
|
||||
return `# Collaborative Planning Session
|
||||
|
||||
**Session ID**: ${plan._metadata?.session_id || sessionId}
|
||||
**Original Requirement**: ${taskDescription}
|
||||
**Created**: ${getUtc8ISOString()}
|
||||
|
||||
---
|
||||
|
||||
## Sub-Requirements Analyzed
|
||||
|
||||
${subRequirements.map((sub, i) => `
|
||||
### ${i+1}. ${sub.focus_area}
|
||||
${sub.description}
|
||||
- **Key Concerns**: ${sub.key_concerns.join(', ')}
|
||||
- **Estimated Effort**: ${sub.estimated_effort}
|
||||
`).join('\n')}
|
||||
|
||||
---
|
||||
|
||||
## Conflict Resolution
|
||||
|
||||
${conflicts.conflicts.length > 0 ? `
|
||||
**Conflicts Detected**: ${conflicts.conflicts.length}
|
||||
**Merge Rule**: ${mergeRule}
|
||||
|
||||
${conflicts.conflicts.map((c, i) => `
|
||||
${i+1}. **${c.type}** - ${c.description}
|
||||
- Resolution: ${c.suggested_resolution}
|
||||
`).join('\n')}
|
||||
` : '✅ No conflicts detected'}
|
||||
|
||||
---
|
||||
|
||||
## Merged Plan
|
||||
|
||||
### Summary
|
||||
${plan.summary}
|
||||
|
||||
### Approach
|
||||
${plan.approach}
|
||||
|
||||
---
|
||||
|
||||
## Tasks
|
||||
|
||||
${plan.tasks.map((task, i) => `
|
||||
### ${task.id}: ${task.title}
|
||||
|
||||
**Source**: ${task.source_agent || 'merged'}
|
||||
**Scope**: ${task.scope}
|
||||
**Action**: ${task.action}
|
||||
**Complexity**: ${task.effort?.complexity || 'medium'}
|
||||
|
||||
${task.description}
|
||||
|
||||
**Modification Points**:
|
||||
${task.modification_points?.map(mp => `- \`${mp.file}\` → ${mp.target}: ${mp.change}`).join('\n') || 'N/A'}
|
||||
|
||||
**Implementation**:
|
||||
${task.implementation?.map((step, idx) => `${idx+1}. ${step}`).join('\n') || 'N/A'}
|
||||
|
||||
**Acceptance Criteria**:
|
||||
${task.acceptance?.map(ac => `- ${ac}`).join('\n') || 'N/A'}
|
||||
|
||||
**Dependencies**: ${task.depends_on?.join(', ') || 'None'}
|
||||
|
||||
---
|
||||
`).join('\n')}
|
||||
|
||||
## Execution
|
||||
|
||||
\`\`\`bash
|
||||
# Execute this plan
|
||||
/workflow:unified-execute-with-file -p ${sessionFolder}/plan.json
|
||||
|
||||
# Or with auto-confirmation
|
||||
/workflow:unified-execute-with-file -y -p ${sessionFolder}/plan.json
|
||||
\`\`\`
|
||||
|
||||
---
|
||||
|
||||
## Agent Process Files
|
||||
|
||||
${subRequirements.map(sub => `
|
||||
### ${sub.focus_area}
|
||||
- Context: \`${sessionFolder}/agents/${sub.focus_area}/planning-context.md\`
|
||||
- Sub-Plan: \`${sessionFolder}/agents/${sub.focus_area}/sub-plan.json\`
|
||||
`).join('\n')}
|
||||
|
||||
---
|
||||
|
||||
**Generated by**: /workflow:collaborative-plan-with-file
|
||||
**Merge Rule**: ${mergeRule}
|
||||
`
|
||||
}
|
||||
```
|
||||
|
||||
### Completion
|
||||
|
||||
```javascript
|
||||
TodoWrite({ todos: [
|
||||
{ content: "Phase 1: Requirement Analysis", status: "completed", activeForm: "Analyzing requirements" },
|
||||
{ content: "Phase 2: Parallel Agent Execution", status: "completed", activeForm: "Running agents" },
|
||||
{ content: "Phase 3: Conflict Detection", status: "completed", activeForm: "Detecting conflicts" },
|
||||
{ content: "Phase 4: Merge & Synthesis", status: "completed", activeForm: "Merging plans" }
|
||||
]})
|
||||
|
||||
console.log(`
|
||||
✅ Collaborative Planning Complete
|
||||
|
||||
**Session**: ${sessionId}
|
||||
**Sub-Agents**: ${subRequirements.length}
|
||||
**Conflicts Resolved**: ${conflicts.conflicts.length}
|
||||
|
||||
## Output Files
|
||||
|
||||
📁 ${sessionFolder}/
|
||||
├── requirement-analysis.json # Requirement breakdown
|
||||
├── agents/ # Per-agent process files
|
||||
${subRequirements.map(sub => `│ ├── ${sub.focus_area}/
|
||||
│ │ ├── planning-context.md
|
||||
│ │ └── sub-plan.json`).join('\n')}
|
||||
├── conflicts.json # Detected conflicts
|
||||
├── plan.json # Unified plan (execution-ready)
|
||||
└── plan.md # Human-readable plan
|
||||
|
||||
## Next Steps
|
||||
|
||||
Execute the plan:
|
||||
\`\`\`bash
|
||||
/workflow:unified-execute-with-file -p ${sessionFolder}/plan.json
|
||||
\`\`\`
|
||||
|
||||
Review a specific agent's work:
|
||||
\`\`\`bash
|
||||
cat ${sessionFolder}/agents/{focus-area}/planning-context.md
|
||||
\`\`\`
|
||||
`)
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
| Flag | Default | Description |
|
||||
|------|---------|-------------|
|
||||
| `--max-agents` | 5 | Maximum sub-agents to spawn |
|
||||
| `--depth` | normal | Exploration depth: normal or deep |
|
||||
| `--merge-rule` | consensus | Conflict resolution: consensus or priority |
|
||||
| `-y, --yes` | false | Auto-confirm all decisions |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
| Requirement too simple | Use single-agent lite-plan instead |
|
||||
| Agent fails | Retry once, then continue with partial results |
|
||||
| Merge conflicts unresolvable | Ask user for manual resolution |
|
||||
| CLI timeout | Use fallback CLI tool |
|
||||
| File write fails | Retry with alternative path |
|
||||
|
||||
## vs Other Planning Commands
|
||||
|
||||
| Command | Use Case |
|
||||
|---------|----------|
|
||||
| **collaborative-plan-with-file** | Complex multi-aspect requirements needing parallel exploration |
|
||||
| lite-plan | Simple single-focus tasks |
|
||||
| multi-cli-plan | Iterative cross-verification with convergence |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Be Specific**: Detailed requirements lead to better splits
|
||||
2. **Review Process Files**: Check planning-context.md for insights
|
||||
3. **Trust the Merge**: Conflict resolution follows defined rules
|
||||
4. **Iterate if Needed**: Re-run with different --merge-rule if results unsatisfactory
|
||||
|
||||
---
|
||||
|
||||
**Now execute collaborative-plan-with-file for**: $ARGUMENTS
|
||||
Reference in New Issue
Block a user