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

description, argument-hint

description	argument-hint
Serial collaborative planning with Plan Note - Single-agent sequential task generation, unified plan-note.md, conflict detection. Codex-optimized.	TASK="<description>" [--max-domains=5] [--focus=<domain>]

Codex Collaborative-Plan-With-File Workflow

Quick Start

Serial collaborative planning workflow using Plan Note architecture. Processes sub-domains sequentially, generates task plans, and detects conflicts across domains.

Core workflow: Understand → Template → Sequential Planning → Conflict Detection → Completion

Key features:

• plan-note.md: Shared collaborative document with pre-allocated sections
• Serial domain processing: Each sub-domain planned sequentially via CLI
• Conflict detection: Automatic file, dependency, and strategy conflict scanning
• No merge needed: Pre-allocated sections eliminate merge conflicts

Note: Codex does not support parallel agent execution. All domains are processed serially.

Overview

This workflow enables structured planning through sequential phases:

1. Understanding & Template - Analyze requirements, identify sub-domains, create plan-note.md template
2. Sequential Planning - Process each sub-domain serially via CLI analysis
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.

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: Sequential Planning

Artifact	Purpose
agents/{domain}/plan.json	Detailed implementation plan per domain
Updated plan-note.md	Task pool and evidence sections filled for each domain

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: Sequential Sub-Domain Planning

Objective: Process each sub-domain serially via CLI analysis, generating detailed plans and updating plan-note.md.

Execution Model: Serial processing - plan each domain completely before moving to the next. Later domains can reference earlier planning results.

Step 2.1: Domain Planning Loop

For each sub-domain in sequence:

1. Execute Gemini CLI analysis for the current domain
2. Parse CLI output into structured plan
3. Save detailed plan as agents/{domain}/plan.json
4. Update plan-note.md with task summaries and evidence

Planning Guideline: Wait for each domain's CLI analysis to complete before proceeding to the next.

Step 2.2: CLI Planning for Each Domain

Execute synchronous CLI analysis to generate a detailed implementation plan.

CLI Analysis Scope:

• PURPOSE: Generate detailed implementation plan for the specific domain
• CONTEXT: Domain description, related codebase files, prior domain results
• TASK: Analyze domain, identify all necessary tasks, define dependencies, estimate effort
• EXPECTED: JSON output with tasks, summaries, interdependencies, total effort

Analysis Output Should Include:

• Task breakdown with IDs from the assigned range
• Dependencies within and across domains
• Files to modify with specific locations
• Effort and complexity estimates per task
• Conflict risk assessment for each task

Step 2.3: Update plan-note.md After Each Domain

Parse CLI output and update the plan-note.md sections for the current domain.

Task Summary Format (for "任务池" section):

• Task header: ### TASK-{ID}: {Title} [{domain}]
• Fields: 状态 (status), 复杂度 (complexity), 依赖 (dependencies), 范围 (scope)
• Modification points: File paths with line ranges and change summaries
• Conflict risk assessment: Low/Medium/High

Evidence Format (for "上下文证据" section):

• Related files with relevance descriptions
• Existing patterns identified in codebase
• Constraints discovered during analysis

Success Criteria:

• All domains processed sequentially
• agents/{domain}/plan.json created for each domain
• plan-note.md updated with all task pools and evidence sections
• Task summaries follow consistent format

---

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
--focus	None	Focus specific domain (optional)

---

Error Handling & Recovery

Situation	Action	Recovery
CLI timeout	Retry with shorter, focused prompt	Skip domain or reduce scope
No tasks generated	Review domain description	Retry with refined description
Section not found in plan-note	Recreate section defensively	Continue with new section
Conflict detection fails	Continue with empty conflicts	Note in completion summary
Session folder conflict	Append timestamp suffix	Create unique folder

---

Iteration Patterns

New Planning Session

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
   ├─ Process each domain serially:
   │   ├─ CLI analysis → plan.json
   │   └─ Update plan-note.md sections
   ├─ 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
   ├─ Resume from first incomplete domain
   └─ Continue sequential processing

---

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

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

---

When to Use This Workflow

Use collaborative-plan-with-file when:

• Complex tasks requiring multi-domain decomposition
• Need structured planning with conflict detection
• Tasks spanning multiple modules or systems
• Want documented planning process for team review
• Preparing for multi-step execution workflows

Use direct execution when:

• Simple, single-domain tasks
• Clear implementation path without ambiguity
• Quick follow-up to existing planning session

Consider alternatives when:

• Exploring ideas without clear direction → use workflow:brainstorm-with-file
• Analyzing existing code/system → use workflow:analyze-with-file
• Lightweight planning for simple features → use workflow:lite-plan
• Ready to execute existing plan → use workflow:unified-execute-with-file

---

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