mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-11 02:33:51 +08:00
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.
This commit is contained in:
catlog22
@@ -1,559 +0,0 @@
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user