Claude-Code-Workflow/.codex/prompts/collaborative-plan-with-file.md

description, argument-hint

description	argument-hint
Parallel collaborative planning with Plan Note - Multi-agent parallel task generation, unified plan-note.md, conflict detection. Codex subagent-optimized.	TASK="<description>" [--max-agents=5]

Codex Collaborative-Plan-With-File Workflow

Quick Start

Parallel collaborative planning workflow using Plan Note architecture. Spawns parallel subagents for each sub-domain, generates task plans concurrently, and detects conflicts across domains.

Core workflow: Understand → Template → Parallel Subagent Planning → Conflict Detection → Completion

Key features:

• plan-note.md: Shared collaborative document with pre-allocated sections
• Parallel subagent planning: Each sub-domain planned by its own subagent concurrently
• Conflict detection: Automatic file, dependency, and strategy conflict scanning
• No merge needed: Pre-allocated sections eliminate merge conflicts

Codex-Specific Features:

• Parallel subagent execution via spawn_agent + batch wait({ ids: [...] })
• Role loading via path (agent reads ~/.codex/agents/*.md itself)
• Pre-allocated sections per agent = no write conflicts
• Explicit lifecycle management with close_agent

Overview

This workflow enables structured planning through parallel-capable phases:

1. Understanding & Template - Analyze requirements, identify sub-domains, create plan-note.md template
2. Parallel Planning - Spawn subagent per sub-domain, batch wait for all results
3. Conflict Detection - Scan plan-note.md for conflicts across all domains
4. Completion - Generate human-readable plan.md summary

The key innovation is the Plan Note architecture - a shared collaborative document with pre-allocated sections per sub-domain, eliminating merge conflicts. Combined with Codex's true parallel subagent execution, all domains are planned simultaneously.

Output Structure

.workflow/.planning/CPLAN-{slug}-{date}/
├── plan-note.md                  # ⭐ Core: Requirements + Tasks + Conflicts
├── requirement-analysis.json     # Phase 1: Sub-domain assignments
├── agents/                       # Phase 2: Per-domain plans (serial)
│   ├── {domain-1}/
│   │   └── plan.json            # Detailed plan
│   ├── {domain-2}/
│   │   └── plan.json
│   └── ...
├── conflicts.json                # Phase 3: Conflict report
└── plan.md                       # Phase 4: Human-readable summary

Output Artifacts

Phase 1: Understanding & Template

Artifact	Purpose
plan-note.md	Collaborative template with pre-allocated task pool and evidence sections per domain
requirement-analysis.json	Sub-domain assignments, TASK ID ranges, complexity assessment

Phase 2: Parallel Planning

Artifact	Purpose
agents/{domain}/plan.json	Detailed implementation plan per domain (from parallel subagent)
Updated plan-note.md	Task pool and evidence sections filled by each subagent

Phase 3: Conflict Detection

Artifact	Purpose
conflicts.json	Detected conflicts with types, severity, and resolutions
Updated plan-note.md	Conflict markers section populated

Phase 4: Completion

Artifact	Purpose
plan.md	Human-readable summary with requirements, tasks, and conflicts

---

Implementation Details

Session Initialization

The workflow automatically generates a unique session identifier and directory structure.

Session ID Format: CPLAN-{slug}-{date}

• slug: Lowercase alphanumeric, max 30 chars
• date: YYYY-MM-DD format (UTC+8)

Session Directory: .workflow/.planning/{sessionId}/

Auto-Detection: If session folder exists with plan-note.md, automatically enters continue mode.

Session Variables:

• sessionId: Unique session identifier
• sessionFolder: Base directory for all artifacts
• maxDomains: Maximum number of sub-domains (default: 5)

---

Phase 1: Understanding & Template Creation

Objective: Analyze task requirements, identify parallelizable sub-domains, and create the plan-note.md template with pre-allocated sections.

Step 1.1: Analyze Task Description

Use built-in tools to understand the task scope and identify sub-domains.

Analysis Activities:

1. Extract task keywords - Identify key terms and concepts from the task description
2. Identify sub-domains - Split into 2-5 parallelizable focus areas based on task complexity
3. Assess complexity - Evaluate overall task complexity (Low/Medium/High)
4. Search for references - Find related documentation, README files, and architecture guides

Sub-Domain Identification Patterns:

Pattern	Keywords
Backend API	服务, 后端, API, 接口
Frontend	界面, 前端, UI, 视图
Database	数据, 存储, 数据库, 持久化
Testing	测试, 验证, QA
Infrastructure	部署, 基础, 运维, 配置

Ambiguity Handling: When the task description is unclear or has multiple interpretations, gather user clarification before proceeding.

Step 1.2: Create plan-note.md Template

Generate a structured template with pre-allocated sections for each sub-domain.

plan-note.md Structure:

• YAML Frontmatter: session_id, original_requirement, created_at, complexity, sub_domains, status
• Section: 需求理解: Core objectives, key points, constraints, split strategy
• Section: 任务池 - {Domain N}: Pre-allocated task section per domain (TASK-{range})
• Section: 依赖关系: Auto-generated after all domains complete
• Section: 冲突标记: Populated in Phase 3
• Section: 上下文证据 - {Domain N}: Evidence section per domain

TASK ID Range Allocation: Each domain receives a non-overlapping range of 100 IDs (e.g., Domain 1: TASK-001100, Domain 2: TASK-101200).

Step 1.3: Generate requirement-analysis.json

Create the sub-domain configuration document.

requirement-analysis.json Structure:

Field	Purpose
session_id	Session identifier
original_requirement	Task description
complexity	Low / Medium / High
sub_domains[]	Array of focus areas with descriptions
sub_domains[].focus_area	Domain name
sub_domains[].description	Domain scope description
sub_domains[].task_id_range	Non-overlapping TASK ID range
sub_domains[].estimated_effort	Effort estimate
sub_domains[].dependencies	Cross-domain dependencies
total_domains	Number of domains identified

Success Criteria:

• 2-5 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 domain)
• Requirements understanding is comprehensive

---

Phase 2: Parallel Sub-Domain Planning

Objective: Spawn parallel subagents for each sub-domain, generating detailed plans and updating plan-note.md concurrently.

Execution Model: Parallel subagent execution - all domains planned simultaneously via spawn_agent + batch wait.

Key API Pattern:

spawn_agent × N → wait({ ids: [...] }) → verify outputs → close_agent × N

Step 2.1: User Confirmation (unless autoMode)

Display identified sub-domains and confirm before spawning agents.

// User confirmation
if (!autoMode) {
  // Display sub-domains for user approval
  // Options: "开始规划" / "调整拆分" / "取消"
}

Step 2.2: Parallel Subagent Planning

⚠️ IMPORTANT: Role files are NOT read by main process. Pass path in message, agent reads itself.

Spawn All Domain Agents in Parallel:

// Create agent directories first
subDomains.forEach(sub => {
  // mkdir: ${sessionFolder}/agents/${sub.focus_area}/
})

// Parallel spawn - all agents start immediately
const agentIds = subDomains.map(sub => {
  return spawn_agent({
    message: `
## TASK ASSIGNMENT

### MANDATORY FIRST STEPS (Agent Execute)
1. **Read role definition**: ~/.codex/agents/cli-lite-planning-agent.md (MUST read first)
2. Read: .workflow/project-tech.json
3. Read: .workflow/project-guidelines.json
4. Read: ${sessionFolder}/plan-note.md (understand template structure)
5. Read: ${sessionFolder}/requirement-analysis.json (understand full context)

---

## Sub-Domain 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

Include:
- Task breakdown with IDs from assigned range (${sub.task_id_range[0]}-${sub.task_id_range[1]})
- Dependencies within and across domains
- Files to modify with specific locations
- Effort and complexity estimates per task
- Conflict risk assessment for each task

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

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

**Task Summary Format**:
### TASK-{ID}: {Title} [${sub.focus_area}]
- **状态**: pending
- **复杂度**: Low/Medium/High
- **依赖**: TASK-xxx (if any)
- **范围**: Brief scope description
- **修改点**: file:line - change summary
- **冲突风险**: Low/Medium/High

**Evidence Format**:
- 相关文件: File list with relevance
- 现有模式: Patterns identified
- 约束: Constraints discovered

## Execution Steps
1. Explore codebase for domain-relevant files
2. Generate complete plan.json
3. Extract task summaries from plan.json
4. Read ${sessionFolder}/plan-note.md
5. Locate and fill your pre-allocated task pool section
6. Locate and fill your pre-allocated evidence section
7. Write back plan-note.md

## Important Rules
- ONLY modify your pre-allocated sections (do NOT touch other domains)
- Use assigned TASK ID range exclusively: ${sub.task_id_range[0]}-${sub.task_id_range[1]}
- Include conflict_risk assessment for each task

## Success Criteria
- [ ] Role definition read
- [ ] plan.json generated with detailed tasks
- [ ] plan-note.md updated with task pool and evidence
- [ ] All tasks within assigned ID range
`
  })
})

// Batch wait - TRUE PARALLELISM (key Codex advantage)
const results = wait({
  ids: agentIds,
  timeout_ms: 900000  // 15 minutes for all planning agents
})

// Handle timeout
if (results.timed_out) {
  const completed = agentIds.filter(id => results.status[id].completed)
  const pending = agentIds.filter(id => !results.status[id].completed)

  // Option: Continue waiting or use partial results
  // If most agents completed, proceed with partial results
}

// Verify outputs exist
subDomains.forEach((sub, index) => {
  const agentId = agentIds[index]
  if (results.status[agentId].completed) {
    // Verify: agents/${sub.focus_area}/plan.json exists
    // Verify: plan-note.md sections populated
  }
})

// Batch cleanup
agentIds.forEach(id => close_agent({ id }))

Step 2.3: Verify plan-note.md Consistency

After all agents complete, verify the shared document.

Verification Activities:

1. Read final plan-note.md
2. Verify all task pool sections are populated
3. Verify all evidence sections are populated
4. Check for any accidental cross-section modifications
5. Validate TASK ID uniqueness across all domains

Success Criteria:

• All subagents spawned and completed (or timeout handled)
• agents/{domain}/plan.json created for each domain
• plan-note.md updated with all task pools and evidence sections
• Task summaries follow consistent format
• No TASK ID overlaps across domains
• All agents closed properly

---

Phase 3: Conflict Detection

Objective: Analyze plan-note.md for conflicts across all domain contributions.

Step 3.1: Parse plan-note.md

Extract all tasks from all "任务池" sections.

Extraction Activities:

1. Read plan-note.md content
2. Parse YAML frontmatter for session metadata
3. Identify all "任务池" sections by heading pattern
4. Extract tasks matching pattern: ### TASK-{ID}: {Title} [{domain}]
5. Parse task details: status, complexity, dependencies, modification points, conflict risk
6. Consolidate into unified task list

Step 3.2: Detect Conflicts

Scan all tasks for three categories of conflicts.

Conflict Types:

Type	Severity	Detection Logic	Resolution
file_conflict	high	Same file:location modified by multiple domains	Coordinate modification order or merge changes
dependency_cycle	critical	Circular dependencies in task graph (DFS detection)	Remove or reorganize dependencies
strategy_conflict	medium	Multiple high-risk tasks in same file from different domains	Review approaches and align on single strategy

Detection Activities:

1. File Conflicts: Group modification points by file:location, identify locations modified by multiple domains
2. Dependency Cycles: Build dependency graph from task dependencies, detect cycles using depth-first search
3. Strategy Conflicts: Group tasks by files they modify, identify files with high-risk tasks from multiple domains

Step 3.3: Generate Conflict Artifacts

Write conflict results and update plan-note.md.

conflicts.json Structure:

• detected_at: Detection timestamp
• total_conflicts: Number of conflicts found
• conflicts[]: Array of conflict objects with type, severity, tasks involved, description, suggested resolution

plan-note.md Update: Locate "冲突标记" section and populate with conflict summary markdown. If no conflicts found, mark as "✅ 无冲突检测到".

Success Criteria:

• All tasks extracted and analyzed
• conflicts.json written with detection results
• plan-note.md updated with conflict markers
• All conflict types checked (file, dependency, strategy)

---

Phase 4: Completion

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

Step 4.1: Generate plan.md

Create a human-readable summary from plan-note.md content.

plan.md Structure:

Section	Content
Header	Session ID, task description, creation time
需求 (Requirements)	Copied from plan-note.md "需求理解" section
子领域拆分 (Sub-Domains)	Each domain with description, task range, estimated effort
任务概览 (Task Overview)	All tasks with complexity, dependencies, and target files
冲突报告 (Conflict Report)	Summary of detected conflicts or "无冲突"
执行指令 (Execution)	Command to execute the plan

Step 4.2: Display Completion Summary

Present session statistics and next steps.

Summary Content:

• Session ID and directory path
• Total domains planned
• Total tasks generated
• Conflict status
• Execution command for next step

Success Criteria:

• plan.md generated with complete summary
• All artifacts present in session directory
• User informed of completion and next steps

---

Configuration

Parameter	Default	Description
--max-domains	5	Maximum sub-domains to identify

---

Error Handling & Recovery

Situation	Action	Recovery
Subagent timeout	Check results.timed_out, continue wait() or use partial results	Reduce scope, plan remaining domains with new agent
Agent closed prematurely	Cannot recover closed agent	Spawn new agent with domain context
Parallel agent partial failure	Some domains complete, some fail	Use completed results, re-spawn for failed domains
plan-note.md write conflict	Multiple agents write simultaneously	Pre-allocated sections prevent this; if detected, re-read and verify
Section not found in plan-note	Agent creates section defensively	Continue with new section
No tasks generated	Review domain description	Retry with refined description via new agent
Conflict detection fails	Continue with empty conflicts	Note in completion summary
Session folder conflict	Append timestamp suffix	Create unique folder

Codex-Specific Error Patterns

// Safe parallel planning with error handling
try {
  const agentIds = subDomains.map(sub => spawn_agent({ message: buildPlanPrompt(sub) }))

  const results = wait({ ids: agentIds, timeout_ms: 900000 })

  if (results.timed_out) {
    const completed = agentIds.filter(id => results.status[id].completed)
    const pending = agentIds.filter(id => !results.status[id].completed)

    // Re-spawn for timed-out domains
    const retryIds = pending.map((id, i) => {
      const sub = subDomains[agentIds.indexOf(id)]
      return spawn_agent({ message: buildPlanPrompt(sub) })
    })

    const retryResults = wait({ ids: retryIds, timeout_ms: 600000 })
    retryIds.forEach(id => { try { close_agent({ id }) } catch(e) {} })
  }

} finally {
  // ALWAYS cleanup
  agentIds.forEach(id => {
    try { close_agent({ id }) } catch (e) { /* ignore */ }
  })
}

---

Iteration Patterns

New Planning Session (Parallel Mode)

User initiates: TASK="task description"
   ├─ No session exists → New session mode
   ├─ Analyze task and identify sub-domains
   ├─ Create plan-note.md template
   ├─ Generate requirement-analysis.json
   │
   ├─ Execute parallel planning:
   │   ├─ spawn_agent × N (one per sub-domain)
   │   ├─ wait({ ids: [...] })  ← TRUE PARALLELISM
   │   └─ close_agent × N
   │
   ├─ Verify plan-note.md consistency
   ├─ Detect conflicts
   ├─ Generate plan.md summary
   └─ Report completion

Continue Existing Session

User resumes: TASK="same task"
   ├─ Session exists → Continue mode
   ├─ Load plan-note.md and requirement-analysis.json
   ├─ Identify incomplete domains (empty task pool sections)
   ├─ Spawn agents for incomplete domains only
   └─ Continue with conflict detection

Agent Lifecycle Management

Subagent lifecycle:
   ├─ spawn_agent({ message }) → Create with role path + task
   ├─ wait({ ids, timeout_ms }) → Get results (ONLY way to get output)
   └─ close_agent({ id }) → Cleanup (MUST do, cannot recover)

Key rules:
   ├─ Pre-allocated sections = no write conflicts
   ├─ ALWAYS use wait() to get results, NOT close_agent()
   ├─ Batch wait for all domain agents: wait({ ids: [a, b, c, ...] })
   └─ Verify plan-note.md after batch completion

---

Best Practices

Before Starting Planning

1. Clear Task Description: Detailed requirements lead to better sub-domain splitting
2. Reference Documentation: Ensure latest README and design docs are identified
3. Clarify Ambiguities: Resolve unclear requirements before committing to sub-domains

During Planning

1. Review Plan Note: Check plan-note.md between phases to verify progress
2. Verify Domains: Ensure sub-domains are truly independent and parallelizable
3. Check Dependencies: Cross-domain dependencies should be documented explicitly
4. Inspect Details: Review agents/{domain}/plan.json for specifics when needed

Codex Subagent Best Practices

1. Role Path, Not Content: Pass ~/.codex/agents/*.md path in message, let agent read itself
2. Pre-allocated Sections: Each agent only writes to its own sections - no write conflicts
3. Batch wait: Use wait({ ids: [a, b, c] }) for all domain agents, not sequential waits
4. Handle Timeouts: Check results.timed_out, re-spawn for failed domains
5. Explicit Cleanup: Always close_agent when done, even on errors (use try/finally)
6. Verify After Batch: Read plan-note.md after all agents complete to verify consistency
7. TASK ID Isolation: Pre-assigned non-overlapping ranges prevent ID conflicts

After Planning

1. Resolve Conflicts: Address high/critical conflicts before execution
2. Review Summary: Check plan.md for completeness and accuracy
3. Validate Tasks: Ensure all tasks have clear scope and modification targets

---

Now execute collaborative-plan-with-file for: $TASK