feat: Add unified-execute-parallel, unified-execute-with-file, and worktree-merge workflows

- Implemented unified-execute-parallel for executing tasks in isolated Git worktrees with parallel execution capabilities. - Developed unified-execute-with-file for universal task execution from various planning outputs with progress tracking. - Created worktree-merge to handle merging of completed worktrees back to the main branch, including dependency management and conflict detection. - Enhanced documentation for each workflow, detailing core functionalities, implementation phases, and configuration options.
2026-02-11 02:33:51 +08:00 · 2026-02-05 18:44:00 +08:00
parent 1480873008
commit eac1bb81c8
17 changed files with 16 additions and 0 deletions
--- a/.codex/skills/collaborative-plan-with-file/SKILL.md
+++ b/.codex/skills/collaborative-plan-with-file/SKILL.md
@@ -0,0 +1,560 @@
+---
+name: collaborative-plan-with-file
+description: Parallel collaborative planning with Plan Note - Multi-agent parallel task generation, unified plan-note.md, conflict detection. Codex subagent-optimized.
+argument-hint: "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-001~100, Domain 2: TASK-101~200).
+
+### 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.
+
+```javascript
+// 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**:
+
+```javascript
+// 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
+
+```javascript
+// 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