From bb4cd0529eb3bf68c46f5613c7e01f101492b3d9 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Tue, 3 Feb 2026 21:17:45 +0800 Subject: [PATCH] feat(codex): add parallel execution workflows with worktree support MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add three new workflow commands for parallel development: - collaborative-plan-parallel.md: Planning with execution group assignment - Supports automatic/balanced/manual group assignment strategies - Assigns codex instances and branch names per group - Detects cross-group conflicts and dependencies - unified-execute-parallel.md: Worktree-based group execution - Executes tasks in isolated Git worktrees (.ccw/worktree/{group-id}/) - Enables true parallel execution across multiple codex instances - Simplified focus on execution only - worktree-merge.md: Dependency-aware worktree merging - Merges completed worktrees in dependency order - Handles cross-group file conflicts - Optional worktree cleanup after merge Key improvements: - True parallel development via Git worktrees (vs branch switching) - Clear separation of concerns (plan → execute → merge) - Support for multi-codex coordination --- .codex/prompts/collaborative-plan-parallel.md | 742 ++++++++++++++++++ .codex/prompts/unified-execute-parallel.md | 271 +++++++ .codex/prompts/worktree-merge.md | 556 +++++++++++++ 3 files changed, 1569 insertions(+) create mode 100644 .codex/prompts/collaborative-plan-parallel.md create mode 100644 .codex/prompts/unified-execute-parallel.md create mode 100644 .codex/prompts/worktree-merge.md diff --git a/.codex/prompts/collaborative-plan-parallel.md b/.codex/prompts/collaborative-plan-parallel.md new file mode 100644 index 00000000..82bfe59f --- /dev/null +++ b/.codex/prompts/collaborative-plan-parallel.md @@ -0,0 +1,742 @@ +--- +description: Parallel collaborative planning with Execution Groups - Multi-codex parallel task generation, execution group assignment, multi-branch strategy. Codex-optimized. +argument-hint: "TASK=\"\" [--max-groups=3] [--group-strategy=automatic|balanced|manual] [--focus=]" +--- + +# Codex Collaborative-Plan-Parallel Workflow + +## Quick Start + +Parallel collaborative planning workflow using **Execution Groups** architecture. Splits task into sub-domains, assigns them to execution groups, and prepares for multi-branch parallel development. + +**Core workflow**: Understand → Group Assignment → Sequential Planning → Conflict Detection → Execution Strategy + +**Key features**: +- **Execution Groups**: Sub-domains grouped for parallel execution by different codex instances +- **Multi-branch strategy**: Each execution group works on independent Git branch +- **Codex instance assignment**: Each group assigned to specific codex worker +- **Dependency-aware grouping**: Automatic or manual group assignment based on dependencies +- **plan-note.md**: Shared document with execution group sections + +**Note**: Planning is still serial (Codex limitation), but output is structured for parallel execution. + +## Overview + +This workflow enables structured planning for parallel execution: + +1. **Understanding & Group Assignment** - Analyze requirements, identify sub-domains, assign to execution groups +2. **Sequential Planning** - Process each sub-domain serially via CLI analysis (planning phase only) +3. **Conflict Detection** - Scan for conflicts across execution groups +4. **Execution Strategy** - Generate branch strategy and codex assignment for parallel execution + +The key innovation is **Execution Groups** - sub-domains are grouped by dependencies and complexity, enabling true parallel development with multiple codex instances. + +## Output Structure + +``` +.workflow/.planning/CPLAN-{slug}-{date}/ +├── plan-note.md # ⭐ Core: Requirements + Groups + Tasks +├── requirement-analysis.json # Phase 1: Sub-domain + group assignments +├── execution-groups.json # ⭐ Phase 1: Group metadata + codex assignment +├── agents/ # Phase 2: Per-domain plans (serial planning) +│ ├── {domain-1}/ +│ │ └── plan.json +│ ├── {domain-2}/ +│ │ └── plan.json +│ └── ... +├── conflicts.json # Phase 3: Conflict report +├── execution-strategy.md # ⭐ Phase 4: Branch strategy + codex commands +└── plan.md # Phase 4: Human-readable summary +``` + +## Output Artifacts + +### Phase 1: Understanding & Group Assignment + +| Artifact | Purpose | +|----------|---------| +| `plan-note.md` | Collaborative template with execution group sections | +| `requirement-analysis.json` | Sub-domain assignments with group IDs | +| `execution-groups.json` | ⭐ Group metadata, codex assignment, branch names, dependencies | + +### Phase 2: Sequential Planning (per Phase 1 in original) + +| Artifact | Purpose | +|----------|---------| +| `agents/{domain}/plan.json` | Detailed implementation plan per domain | +| Updated `plan-note.md` | Task pool and evidence sections filled per domain | + +### Phase 3: Conflict Detection (same as original) + +| Artifact | Purpose | +|----------|---------| +| `conflicts.json` | Detected conflicts with types, severity, resolutions | +| Updated `plan-note.md` | Conflict markers section populated | + +### Phase 4: Execution Strategy Generation + +| Artifact | Purpose | +|----------|---------| +| `execution-strategy.md` | ⭐ Branch creation commands, codex execution commands per group, merge strategy | +| `plan.md` | Human-readable summary with execution groups | + +--- + +## 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 +- `maxGroups`: Maximum execution groups (default: 3) +- `groupStrategy`: automatic | balanced | manual (default: automatic) + +--- + +## Phase 1: Understanding & Group Assignment + +**Objective**: Analyze task requirements, identify sub-domains, assign to execution groups, and create the plan-note.md template. + +### 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 +2. **Identify sub-domains** - Split into 2-8 parallelizable focus areas +3. **Analyze dependencies** - Map cross-domain dependencies +4. **Assess complexity** - Evaluate task complexity per domain (Low/Medium/High) +5. **Search for references** - Find related documentation, README, architecture guides + +**Sub-Domain Identification Patterns**: + +| Pattern | Keywords | Typical Group Assignment | +|---------|----------|--------------------------| +| Backend API | 服务, 后端, API, 接口 | Group with database if dependent | +| Frontend | 界面, 前端, UI, 视图 | Separate group (UI-focused) | +| Database | 数据, 存储, 数据库, 持久化 | Group with backend if tightly coupled | +| Testing | 测试, 验证, QA | Can be separate or split across groups | +| Infrastructure | 部署, 基础, 运维, 配置 | Usually separate group | + +### Step 1.2: Assign Execution Groups + +Assign sub-domains to execution groups based on strategy. + +**Group Assignment Strategies**: + +#### 1. Automatic Strategy (default) +- **Logic**: Group domains by dependency relationships +- **Rule**: Domains with direct dependencies → same group +- **Rule**: Independent domains → separate groups (up to maxGroups) +- **Example**: + - Group 1: backend-api + database (dependent) + - Group 2: frontend + ui-components (dependent) + - Group 3: testing + documentation (independent) + +#### 2. Balanced Strategy +- **Logic**: Distribute domains evenly across groups by estimated effort +- **Rule**: Balance total complexity across groups +- **Example**: + - Group 1: frontend (high) + testing (low) + - Group 2: backend (high) + documentation (low) + - Group 3: database (medium) + infrastructure (medium) + +#### 3. Manual Strategy +- **Logic**: Prompt user to manually assign domains to groups +- **UI**: Present domains with dependencies, ask for group assignments +- **Validation**: Check that dependencies are within same group or properly ordered + +**Codex Instance Assignment**: +- Each group assigned to `codex-{N}` (e.g., codex-1, codex-2, codex-3) +- Instance names are logical identifiers for parallel execution +- Actual parallel execution happens in unified-execute-parallel workflow + +### Step 1.3: Generate execution-groups.json + +Create the execution group metadata document. + +**execution-groups.json Structure**: + +```json +{ + "session_id": "CPLAN-auth-2025-02-03", + "total_groups": 3, + "group_strategy": "automatic", + "groups": [ + { + "group_id": "EG-001", + "codex_instance": "codex-1", + "domains": ["frontend", "ui-components"], + "branch_name": "feature/cplan-auth-eg-001-frontend", + "estimated_effort": "high", + "task_id_range": "TASK-001~200", + "dependencies_on_groups": [], + "cross_group_files": [] + }, + { + "group_id": "EG-002", + "codex_instance": "codex-2", + "domains": ["backend-api", "database"], + "branch_name": "feature/cplan-auth-eg-002-backend", + "estimated_effort": "medium", + "task_id_range": "TASK-201~400", + "dependencies_on_groups": [], + "cross_group_files": [] + }, + { + "group_id": "EG-003", + "codex_instance": "codex-3", + "domains": ["testing"], + "branch_name": "feature/cplan-auth-eg-003-testing", + "estimated_effort": "low", + "task_id_range": "TASK-401~500", + "dependencies_on_groups": ["EG-001", "EG-002"], + "cross_group_files": [] + } + ], + "inter_group_dependencies": [ + { + "from_group": "EG-003", + "to_group": "EG-001", + "dependency_type": "requires_completion", + "description": "Testing requires frontend implementation" + }, + { + "from_group": "EG-003", + "to_group": "EG-002", + "dependency_type": "requires_completion", + "description": "Testing requires backend API" + } + ] +} +``` + +**Field Descriptions**: + +| Field | Purpose | +|-------|---------| +| `group_id` | Unique execution group identifier (EG-001, EG-002, ...) | +| `codex_instance` | Logical codex worker name for parallel execution | +| `domains[]` | Sub-domains assigned to this group | +| `branch_name` | Git branch name for this group's work | +| `estimated_effort` | Complexity: low/medium/high | +| `task_id_range` | Non-overlapping TASK ID range (200 IDs per group) | +| `dependencies_on_groups[]` | Groups that must complete before this group starts | +| `cross_group_files[]` | Files modified by multiple groups (conflict risk) | +| `inter_group_dependencies[]` | Explicit cross-group dependency relationships | + +### Step 1.4: Create plan-note.md Template with Groups + +Generate structured template with execution group sections. + +**plan-note.md Structure**: +- **YAML Frontmatter**: session_id, original_requirement, total_groups, group_strategy, status +- **Section: 需求理解**: Core objectives, key points, constraints, group strategy +- **Section: 执行组划分**: Table of groups with domains, branches, codex assignments +- **Section: 任务池 - {Group ID} - {Domains}**: Pre-allocated task section per execution group +- **Section: 依赖关系**: Cross-group dependencies +- **Section: 冲突标记**: Populated in Phase 3 +- **Section: 上下文证据 - {Group ID}**: Evidence section per execution group + +**TASK ID Range Allocation**: Each group receives 200 non-overlapping IDs (e.g., Group 1: TASK-001~200, Group 2: TASK-201~400). + +### Step 1.5: Update requirement-analysis.json with Groups + +Extend requirement-analysis.json to include execution group assignments. + +**requirement-analysis.json Structure** (extended): + +```json +{ + "session_id": "CPLAN-auth-2025-02-03", + "original_requirement": "...", + "complexity": "high", + "total_groups": 3, + "group_strategy": "automatic", + "sub_domains": [ + { + "focus_area": "frontend", + "description": "...", + "execution_group": "EG-001", + "task_id_range": "TASK-001~100", + "estimated_effort": "high", + "dependencies": [] + }, + { + "focus_area": "ui-components", + "description": "...", + "execution_group": "EG-001", + "task_id_range": "TASK-101~200", + "estimated_effort": "medium", + "dependencies": ["frontend"] + } + ], + "execution_groups_summary": [ + { + "group_id": "EG-001", + "domains": ["frontend", "ui-components"], + "total_estimated_effort": "high" + } + ] +} +``` + +**Success Criteria**: +- 2-3 execution groups identified (up to maxGroups) +- Each group has 1-4 sub-domains +- Dependencies mapped (intra-group and inter-group) +- execution-groups.json created with complete metadata +- plan-note.md template includes group sections +- requirement-analysis.json extended with group assignments +- Branch names generated for each group +- Codex instance assigned to each group + +--- + +## Phase 2: Sequential Sub-Domain Planning + +**Objective**: Process each sub-domain serially via CLI analysis (same as original workflow, but with group awareness). + +**Note**: This phase is identical to original collaborative-plan-with-file Phase 2, with the following additions: +- CLI prompt includes execution group context +- Task IDs respect group's assigned range +- Cross-group dependencies explicitly documented + +### Step 2.1: Domain Planning Loop (Serial) + +For each sub-domain in sequence: +1. Execute Gemini/Codex CLI analysis for the current domain +2. Include execution group metadata in CLI context +3. Parse CLI output into structured plan +4. Save detailed plan as `agents/{domain}/plan.json` +5. Update plan-note.md group section with task summaries and evidence + +**Planning Guideline**: Wait for each domain's CLI analysis to complete before proceeding. + +### Step 2.2: CLI Planning with Group Context + +Execute synchronous CLI analysis with execution group awareness. + +**CLI Analysis Scope** (extended): +- **PURPOSE**: Generate detailed implementation plan for domain within execution group +- **CONTEXT**: + - Domain description + - Execution group ID and metadata + - Related codebase files + - Prior domain results within same group + - Cross-group dependencies (if any) +- **TASK**: Analyze domain, identify tasks within group's ID range, define dependencies +- **EXPECTED**: JSON output with tasks, summaries, group-aware dependencies, effort estimates +- **CONSTRAINTS**: + - Use only TASK IDs from assigned range + - Document any cross-group dependencies + - Flag files that might be modified by other groups + +**Cross-Group Dependency Handling**: +- If a task depends on another group's completion, document as `depends_on_group: "EG-XXX"` +- Mark files that are likely modified by multiple groups as `cross_group_risk: true` + +### Step 2.3: Update plan-note.md Group Sections + +Parse CLI output and update the plan-note.md sections for the current domain's group. + +**Task Summary Format** (extended with group info): +- Task header: `### TASK-{ID}: {Title} [{domain}] [Group: {group_id}]` +- Fields: 状态, 复杂度, 依赖, 范围, **执行组** (execution_group) +- Cross-group dependencies: `依赖执行组: EG-XXX` +- Modification points with conflict risk flag +- Conflict risk assessment + +**Evidence Format** (same as original) + +**Success Criteria**: +- All domains processed sequentially +- `agents/{domain}/plan.json` created for each domain +- `plan-note.md` updated with group-aware task pools +- Cross-group dependencies explicitly documented +- Task IDs respect group ranges + +--- + +## Phase 3: Conflict Detection + +**Objective**: Analyze plan-note.md for conflicts within and across execution groups. + +**Note**: This phase extends original conflict detection with group-aware analysis. + +### Step 3.1: Parse plan-note.md (same as original) + +Extract all tasks from all group sections. + +### Step 3.2: Detect Conflicts (Extended) + +Scan all tasks for four categories of conflicts (added cross-group conflicts). + +**Conflict Types** (extended): + +| Type | Severity | Detection Logic | Resolution | +|------|----------|-----------------|------------| +| file_conflict | high | Same file:location modified by multiple domains within same group | Coordinate modification order | +| cross_group_file_conflict | critical | Same file modified by multiple execution groups | Requires merge coordination or branch rebase strategy | +| dependency_cycle | critical | Circular dependencies in task graph (within or across groups) | Remove or reorganize dependencies | +| strategy_conflict | medium | Multiple high-risk tasks in same file from different domains/groups | Review approaches and align on strategy | + +**Detection Activities**: +1. **File Conflicts (Intra-Group)**: Group modification points by file:location within each group +2. **Cross-Group File Conflicts**: Identify files modified by multiple execution groups +3. **Dependency Cycles**: Build dependency graph including cross-group dependencies, detect cycles +4. **Strategy Conflicts**: Identify files with high-risk tasks from multiple groups + +**Cross-Group Conflict Detection**: +- Parse `cross_group_files[]` from execution-groups.json +- Scan all tasks for files modified by multiple groups +- Flag as critical conflict requiring merge strategy + +### Step 3.3: Update execution-groups.json with Conflicts + +Append detected cross-group conflicts to execution-groups.json. + +**Update Structure**: +```json +{ + "groups": [ + { + "group_id": "EG-001", + "cross_group_files": [ + { + "file": "src/shared/config.ts", + "conflicting_groups": ["EG-002"], + "conflict_type": "both modify shared configuration", + "resolution": "Coordinate changes or use merge strategy" + } + ] + } + ] +} +``` + +### Step 3.4: Generate Conflict Artifacts (Extended) + +Write conflict results with group context. + +**conflicts.json Structure** (extended): +- `detected_at`: Detection timestamp +- `total_conflicts`: Number of conflicts +- `intra_group_conflicts[]`: Conflicts within single group +- `cross_group_conflicts[]`: ⭐ Conflicts across execution groups +- `conflicts[]`: All conflict objects with group IDs + +**plan-note.md Update**: Populate "冲突标记" section with: +- Intra-group conflicts (can be resolved during group execution) +- Cross-group conflicts (require coordination or merge strategy) + +**Success Criteria**: +- All tasks analyzed for intra-group and cross-group conflicts +- `conflicts.json` written with group-aware detection results +- `execution-groups.json` updated with cross_group_files +- `plan-note.md` updated with conflict markers +- Cross-group conflicts flagged as critical + +--- + +## Phase 4: Execution Strategy Generation + +**Objective**: Generate branch strategy and codex execution commands for parallel development. + +### Step 4.1: Generate Branch Strategy + +Create Git branch strategy for multi-branch parallel development. + +**Branch Strategy Decisions**: + +1. **Independent Groups** (no cross-group conflicts): + - Each group works on independent branch from main + - Branches can be merged independently + - Parallel development fully supported + +2. **Dependent Groups** (cross-group dependencies but no file conflicts): + - Groups with dependencies must coordinate completion order + - Independent branches, but merge order matters + - Group A completes → merge to main → Group B starts/continues + +3. **Conflicting Groups** (cross-group file conflicts): + - Strategy 1: Sequential - Complete one group, merge, then start next + - Strategy 2: Feature branch + rebase - Each group rebases on main periodically + - Strategy 3: Shared integration branch - Both groups branch from shared base, coordinate merges + +**Default Strategy**: Independent branches with merge order based on dependencies + +### Step 4.2: Generate execution-strategy.md + +Create execution strategy document with concrete commands. + +**execution-strategy.md Structure**: + +```markdown +# Execution Strategy: {session_id} + +## Overview + +- **Total Execution Groups**: {N} +- **Group Strategy**: {automatic|balanced|manual} +- **Branch Strategy**: {independent|dependent|conflicting} +- **Estimated Total Effort**: {sum of all groups} + +## Execution Groups + +### EG-001: Frontend Development +- **Codex Instance**: codex-1 +- **Domains**: frontend, ui-components +- **Branch**: feature/cplan-auth-eg-001-frontend +- **Dependencies**: None (can start immediately) +- **Estimated Effort**: High + +### EG-002: Backend Development +- **Codex Instance**: codex-2 +- **Domains**: backend-api, database +- **Branch**: feature/cplan-auth-eg-002-backend +- **Dependencies**: None (can start immediately) +- **Estimated Effort**: Medium + +### EG-003: Testing +- **Codex Instance**: codex-3 +- **Domains**: testing +- **Branch**: feature/cplan-auth-eg-003-testing +- **Dependencies**: EG-001, EG-002 (must complete first) +- **Estimated Effort**: Low + +## Branch Creation Commands + +```bash +# Create branches for all execution groups +git checkout main +git pull + +# Group 1: Frontend +git checkout -b feature/cplan-auth-eg-001-frontend +git push -u origin feature/cplan-auth-eg-001-frontend + +# Group 2: Backend +git checkout main +git checkout -b feature/cplan-auth-eg-002-backend +git push -u origin feature/cplan-auth-eg-002-backend + +# Group 3: Testing +git checkout main +git checkout -b feature/cplan-auth-eg-003-testing +git push -u origin feature/cplan-auth-eg-003-testing +``` + +## Parallel Execution Commands + +Execute these commands in parallel (separate terminal sessions or background): + +```bash +# Terminal 1: Execute Group 1 (Frontend) +PLAN=".workflow/.planning/CPLAN-auth-2025-02-03/plan-note.md" \ + GROUP="EG-001" \ + /workflow:unified-execute-parallel + +# Terminal 2: Execute Group 2 (Backend) +PLAN=".workflow/.planning/CPLAN-auth-2025-02-03/plan-note.md" \ + GROUP="EG-002" \ + /workflow:unified-execute-parallel + +# Terminal 3: Execute Group 3 (Testing) - starts after EG-001 and EG-002 complete +PLAN=".workflow/.planning/CPLAN-auth-2025-02-03/plan-note.md" \ + GROUP="EG-003" \ + WAIT_FOR="EG-001,EG-002" \ + /workflow:unified-execute-parallel +``` + +## Cross-Group Conflicts + +### Critical Conflicts Detected + +1. **File: src/shared/config.ts** + - Modified by: EG-001 (frontend), EG-002 (backend) + - Resolution: Coordinate changes or use merge strategy + - Recommendation: EG-001 completes first, EG-002 rebases before continuing + +### Resolution Strategy + +- **Option 1**: Sequential execution (EG-001 → merge → EG-002 rebases) +- **Option 2**: Manual coordination (both groups align on config changes before execution) +- **Option 3**: Split file (refactor into separate configs if feasible) + +## Merge Strategy + +### Independent Groups (EG-001, EG-002) +```bash +# After EG-001 completes +git checkout main +git merge feature/cplan-auth-eg-001-frontend +git push + +# After EG-002 completes +git checkout main +git merge feature/cplan-auth-eg-002-backend +git push +``` + +### Dependent Group (EG-003) +```bash +# After EG-001 and EG-002 merged to main +git checkout feature/cplan-auth-eg-003-testing +git rebase main # Update with latest changes +# Continue execution... + +# After EG-003 completes +git checkout main +git merge feature/cplan-auth-eg-003-testing +git push +``` + +## Monitoring Progress + +Track execution progress: +```bash +# Check execution logs for each group +cat .workflow/.execution/EXEC-eg-001-*/execution-events.md +cat .workflow/.execution/EXEC-eg-002-*/execution-events.md +cat .workflow/.execution/EXEC-eg-003-*/execution-events.md +``` +``` + +### Step 4.3: Generate plan.md Summary (Extended) + +Create human-readable summary with execution group information. + +**plan.md Structure** (extended): + +| Section | Content | +|---------|---------| +| Header | Session ID, task description, creation time | +| 需求 (Requirements) | From plan-note.md "需求理解" | +| 执行组划分 (Execution Groups) | ⭐ Table of groups with domains, branches, codex assignments, dependencies | +| 任务概览 (Task Overview) | All tasks grouped by execution group | +| 冲突报告 (Conflict Report) | Intra-group and cross-group conflicts | +| 执行策略 (Execution Strategy) | Branch strategy, parallel execution commands, merge order | + +### Step 4.4: Display Completion Summary + +Present session statistics with execution group information. + +**Summary Content**: +- Session ID and directory path +- Total execution groups created +- Total domains planned +- Total tasks generated (per group and total) +- Conflict status (intra-group and cross-group) +- Execution strategy summary +- Next step: Use `workflow:unified-execute-parallel` with GROUP parameter + +**Success Criteria**: +- `execution-strategy.md` generated with complete branch and execution strategy +- `plan.md` includes execution group information +- All artifacts present in session directory +- User informed of parallel execution approach and commands +- Cross-group conflicts clearly documented with resolution strategies + +--- + +## Configuration + +| Parameter | Default | Description | +|-----------|---------|-------------| +| `--max-groups` | 3 | Maximum execution groups to create | +| `--group-strategy` | automatic | Group assignment: automatic / balanced / manual | +| `--focus` | None | Focus specific domain (optional) | + +**Group Strategy Details**: +- **automatic**: Group by dependency relationships (dependent domains in same group) +- **balanced**: Distribute evenly by estimated effort +- **manual**: Prompt user to assign domains to groups interactively + +--- + +## Error Handling & Recovery + +| Situation | Action | Recovery | +|-----------|--------|----------| +| Too many groups requested | Limit to maxGroups | Merge low-effort domains | +| Circular group dependencies | Stop execution, report error | Reorganize domain assignments | +| All domains in one group | Warning: No parallelization | Continue or prompt user to split | +| Cross-group file conflicts | Flag as critical | Suggest resolution strategies | +| Manual grouping timeout | Fall back to automatic | Continue with automatic strategy | + +--- + +## Best Practices + +### Before Starting Planning + +1. **Clear Task Description**: Detailed requirements for better grouping +2. **Understand Dependencies**: Know which modules depend on each other +3. **Choose Group Strategy**: + - Use `automatic` for dependency-heavy tasks + - Use `balanced` for independent features + - Use `manual` for complex architectures you understand well + +### During Planning + +1. **Review Group Assignments**: Check execution-groups.json makes sense +2. **Verify Dependencies**: Cross-group dependencies should be minimal +3. **Check Branch Names**: Ensure branch names follow project conventions +4. **Monitor Conflicts**: Review conflicts.json for cross-group file conflicts + +### After Planning + +1. **Review Execution Strategy**: Read execution-strategy.md carefully +2. **Resolve Critical Conflicts**: Address cross-group file conflicts before execution +3. **Prepare Environments**: Ensure multiple codex instances can run in parallel +4. **Plan Merge Order**: Understand which groups must merge first + +--- + +## When to Use This Workflow + +### Use collaborative-plan-parallel when: +- Complex tasks with multiple independent sub-systems +- Want true parallel development with multiple developers/codex instances +- Need structured multi-branch development strategy +- Tasks have clear domain boundaries with minimal cross-dependencies +- Large projects requiring faster completion through parallelization + +### Use collaborative-plan-with-file (original) when: +- Smaller tasks with high inter-domain dependencies +- Single developer/codex instance +- Prefer simpler linear execution +- Cross-domain coordination is critical + +### Consider alternatives when: +- Simple single-domain tasks → use `workflow:lite-plan` +- Exploring ideas → use `workflow:brainstorm-with-file` +- Analyzing code → use `workflow:analyze-with-file` +- Ready to execute existing plan → use `workflow:unified-execute-parallel` with GROUP parameter + +--- + +## Migration from Original Workflow + +Existing `collaborative-plan-with-file` sessions can be converted to parallel execution: + +1. Read existing `plan-note.md` and `requirement-analysis.json` +2. Assign sub-domains to execution groups (run Step 1.2 manually) +3. Generate `execution-groups.json` and `execution-strategy.md` +4. Use `workflow:unified-execute-parallel` for execution + +--- + +**Now execute collaborative-plan-parallel for**: $TASK diff --git a/.codex/prompts/unified-execute-parallel.md b/.codex/prompts/unified-execute-parallel.md new file mode 100644 index 00000000..e51ec4c4 --- /dev/null +++ b/.codex/prompts/unified-execute-parallel.md @@ -0,0 +1,271 @@ +--- +description: Worktree-based parallel execution engine. Execute group tasks in isolated Git worktree. Codex-optimized. +argument-hint: "PLAN=\"\" GROUP=\"\" [--auto-commit] [--dry-run]" +--- + +# Codex Unified-Execute-Parallel Workflow + +## Quick Start + +Execute tasks for a specific execution group in isolated Git worktree. + +**Core workflow**: Load Plan → Select Group → Create Worktree → Execute Tasks → Mark Complete + +**Key features**: +- **Worktree isolation**: Each group executes in `.ccw/worktree/{group-id}/` +- **Parallel execution**: Multiple codex instances can run different groups simultaneously +- **Simple focus**: Execute only, merge handled by separate command + +## Overview + +1. **Plan & Group Selection** - Load plan, select execution group +2. **Worktree Setup** - Create Git worktree for group's branch +3. **Task Execution** - Execute group tasks serially in worktree +4. **Mark Complete** - Record completion status + +**Note**: Merging is handled by `/workflow:worktree-merge` command. + +## Output Structure + +``` +.ccw/worktree/ +├── {group-id}/ # Git worktree for group +│ ├── (full project checkout) +│ └── .execution/ # Execution artifacts +│ ├── execution.md # Task overview +│ └── execution-events.md # Execution log + +.workflow/.execution/ +└── worktree-status.json # ⭐ All groups completion status +``` + +--- + +## Implementation Details + +### Session Variables + +- `planPath`: Path to plan file +- `groupId`: Selected execution group ID (required) +- `worktreePath`: `.ccw/worktree/{groupId}` +- `branchName`: From execution-groups.json +- `autoCommit`: Boolean for auto-commit mode +- `dryRun`: Boolean for dry-run mode + +--- + +## Phase 1: Plan & Group Selection + +**Objective**: Load plan, extract group metadata, filter tasks. + +### Step 1.1: Load Plan File + +Read plan file and execution-groups.json from same directory. + +**Required Files**: +- `plan-note.md` or `plan.json` - Task definitions +- `execution-groups.json` - Group metadata with branch names + +### Step 1.2: Select Group + +Validate GROUP parameter. + +**Validation**: +- Group exists in execution-groups.json +- Group has assigned tasks +- Branch name is defined + +### Step 1.3: Filter Group Tasks + +Extract only tasks belonging to selected group. + +**Task Filtering**: +- Match by `execution_group` field, OR +- Match by `domain` if domain in group.domains + +Build execution order from filtered tasks. + +--- + +## Phase 2: Worktree Setup + +**Objective**: Create Git worktree for isolated execution. + +### Step 2.1: Create Worktree Directory + +Ensure worktree base directory exists. + +```bash +mkdir -p .ccw/worktree +``` + +### Step 2.2: Create Git Worktree + +Create worktree with group's branch. + +**If worktree doesn't exist**: +```bash +# Create branch and worktree +git worktree add -b {branch-name} .ccw/worktree/{group-id} main +``` + +**If worktree exists**: +```bash +# Verify worktree is on correct branch +cd .ccw/worktree/{group-id} +git status +``` + +**Branch Naming**: From execution-groups.json `branch_name` field. + +### Step 2.3: Initialize Execution Folder + +Create execution tracking folder inside worktree. + +```bash +mkdir -p .ccw/worktree/{group-id}/.execution +``` + +Create initial `execution.md`: +- Group ID and branch name +- Task list for this group +- Start timestamp + +**Success Criteria**: +- Worktree created at `.ccw/worktree/{group-id}/` +- Working on correct branch +- Execution folder initialized + +--- + +## Phase 3: Task Execution + +**Objective**: Execute group tasks serially in worktree. + +### Step 3.1: Change to Worktree Directory + +All execution happens inside worktree. + +```bash +cd .ccw/worktree/{group-id} +``` + +### Step 3.2: Execute Tasks Sequentially + +For each task in group: +1. Execute via CLI in worktree directory +2. Record result in `.execution/execution-events.md` +3. Auto-commit if enabled +4. Continue to next task + +**CLI Execution**: +- `--cd .ccw/worktree/{group-id}` - Execute in worktree +- `--mode write` - Allow file modifications + +### Step 3.3: Record Progress + +Update `.execution/execution-events.md` after each task: +- Task ID and title +- Timestamp +- Status (completed/failed) +- Files modified + +### Step 3.4: Auto-Commit (if enabled) + +Commit task changes in worktree. + +```bash +cd .ccw/worktree/{group-id} +git add . +git commit -m "feat: {task-title} [TASK-{id}]" +``` + +--- + +## Phase 4: Mark Complete + +**Objective**: Record group completion status. + +### Step 4.1: Update worktree-status.json + +Write/update status file in main project. + +**worktree-status.json** (in `.workflow/.execution/`): +```json +{ + "plan_session": "CPLAN-auth-2025-02-03", + "groups": { + "EG-001": { + "worktree_path": ".ccw/worktree/EG-001", + "branch": "feature/cplan-auth-eg-001-frontend", + "status": "completed", + "tasks_total": 15, + "tasks_completed": 15, + "tasks_failed": 0, + "completed_at": "2025-02-03T14:30:00Z" + }, + "EG-002": { + "status": "in_progress", + "tasks_completed": 8, + "tasks_total": 12 + } + } +} +``` + +### Step 4.2: Display Summary + +Report group execution results: +- Group ID and worktree path +- Tasks completed/failed +- Next step: Use `/workflow:worktree-merge` to merge + +--- + +## Configuration + +| Parameter | Default | Description | +|-----------|---------|-------------| +| `PLAN` | Auto-detect | Path to plan file | +| `GROUP` | Required | Execution group ID (e.g., EG-001) | +| `--auto-commit` | false | Commit after each task | +| `--dry-run` | false | Simulate without changes | + +--- + +## Error Handling + +| Situation | Action | +|-----------|--------| +| GROUP missing | Error: Require GROUP parameter | +| Group not found | Error: Check execution-groups.json | +| Worktree exists with wrong branch | Warning: Clean or remove existing worktree | +| Task fails | Record failure, continue to next | + +--- + +## Parallel Execution Example + +**3 terminals, 3 groups**: + +```bash +# Terminal 1 +PLAN=".workflow/.planning/CPLAN-auth/plan-note.md" GROUP="EG-001" --auto-commit + +# Terminal 2 +PLAN=".workflow/.planning/CPLAN-auth/plan-note.md" GROUP="EG-002" --auto-commit + +# Terminal 3 +PLAN=".workflow/.planning/CPLAN-auth/plan-note.md" GROUP="EG-003" --auto-commit +``` + +Each executes in isolated worktree: +- `.ccw/worktree/EG-001/` +- `.ccw/worktree/EG-002/` +- `.ccw/worktree/EG-003/` + +After all complete, use `/workflow:worktree-merge` to merge. + +--- + +**Now execute unified-execute-parallel for**: $PLAN with GROUP=$GROUP diff --git a/.codex/prompts/worktree-merge.md b/.codex/prompts/worktree-merge.md new file mode 100644 index 00000000..b0e99b9d --- /dev/null +++ b/.codex/prompts/worktree-merge.md @@ -0,0 +1,556 @@ +--- +description: Merge completed worktrees back to main branch. Handle cross-group conflicts and dependency order. +argument-hint: "[--plan=] [--group=] [--all] [--cleanup]" +--- + +# Codex Worktree-Merge Workflow + +## Quick Start + +Merge completed execution group worktrees back to main branch. + +**Core workflow**: Load Status → Check Dependencies → Merge Groups → Cleanup Worktrees + +**Key features**: +- **Dependency-aware merge**: Merge groups in correct order +- **Conflict detection**: Check for cross-group file conflicts +- **Selective or bulk merge**: Merge single group or all completed groups +- **Cleanup option**: Remove worktrees after successful merge + +## Overview + +1. **Load Status** - Read worktree-status.json and execution-groups.json +2. **Validate Dependencies** - Check group dependencies are merged first +3. **Merge Worktree** - Merge group's branch to main +4. **Update Status** - Mark group as merged +5. **Cleanup** (optional) - Remove worktree after merge + +**Note**: This command only merges, execution is handled by `/workflow:unified-execute-parallel`. + +## Input Files + +``` +.workflow/.execution/ +└── worktree-status.json # Group completion status + +.workflow/.planning/{session}/ +├── execution-groups.json # Group metadata and dependencies +└── conflicts.json # Cross-group conflicts (if any) + +.ccw/worktree/ +├── {group-id}/ # Worktree to merge +│ ├── .execution/ # Execution logs +│ └── (modified files) +``` + +## Output + +``` +.workflow/.execution/ +├── worktree-status.json # Updated with merge status +└── merge-log.md # Merge history and details +``` + +--- + +## Implementation Details + +### Command Parameters + +- `--plan=`: Plan session ID (auto-detect if not provided) +- `--group=`: Merge specific group (e.g., EG-001) +- `--all`: Merge all completed groups in dependency order +- `--cleanup`: Remove worktree after successful merge + +**Examples**: +```bash +# Merge single group +--group=EG-001 + +# Merge all completed groups +--all + +# Merge and cleanup +--group=EG-001 --cleanup +``` + +--- + +## Phase 1: Load Status + +**Objective**: Read completion status and group metadata. + +### Step 1.1: Load worktree-status.json + +Read group completion status. + +**Status File Location**: `.workflow/.execution/worktree-status.json` + +**Required Fields**: +- `plan_session`: Planning session ID +- `groups[]`: Array of group status objects + - `status`: "completed" / "in_progress" / "failed" + - `worktree_path`: Path to worktree + - `branch`: Branch name + - `merge_status`: "not_merged" / "merged" + +### Step 1.2: Load execution-groups.json + +Read group dependencies. + +**Metadata File**: `.workflow/.planning/{session}/execution-groups.json` + +**Required Fields**: +- `groups[]`: Group metadata with dependencies + - `group_id`: Group identifier + - `dependencies_on_groups[]`: Groups that must merge first + - `cross_group_files[]`: Files modified by multiple groups + +### Step 1.3: Determine Merge Targets + +Select groups to merge based on parameters. + +**Selection Logic**: + +| Parameter | Behavior | +|-----------|----------| +| `--group=EG-001` | Merge only specified group | +| `--all` | Merge all groups with status="completed" | +| Neither | Prompt user to select from completed groups | + +**Validation**: +- Group must have status="completed" +- Group's worktree must exist +- Group must not already be merged + +--- + +## Phase 2: Validate Dependencies + +**Objective**: Ensure dependencies are merged before target group. + +### Step 2.1: Build Dependency Graph + +Create merge order based on inter-group dependencies. + +**Dependency Analysis**: +1. For target group, check `dependencies_on_groups[]` +2. For each dependency, verify merge status +3. Build topological order for merge sequence + +**Example**: +```json +EG-003 depends on [EG-001, EG-002] +→ Merge order: EG-001, EG-002, then EG-003 +``` + +### Step 2.2: Check Dependency Status + +Validate all dependencies are merged. + +**Check Logic**: +``` +For each dependency in target.dependencies_on_groups: + ├─ Check dependency.merge_status == "merged" + ├─ If not merged: Error or prompt to merge dependency first + └─ If merged: Continue +``` + +**Options on Dependency Not Met**: +1. **Error**: Refuse to merge until dependencies merged +2. **Cascade**: Automatically merge dependencies first (if --all) +3. **Force**: Allow merge anyway (dangerous, use --force) + +--- + +## Phase 3: Conflict Detection + +**Objective**: Check for cross-group file conflicts before merge. + +### Step 3.1: Load Cross-Group Files + +Read files modified by multiple groups. + +**Source**: `execution-groups.json` → `groups[].cross_group_files[]` + +**Example**: +```json +{ + "group_id": "EG-001", + "cross_group_files": [ + { + "file": "src/shared/config.ts", + "conflicting_groups": ["EG-002"] + } + ] +} +``` + +### Step 3.2: Check File Modifications + +Compare file state across groups and main. + +**Conflict Check**: +1. For each cross-group file: + - Get version on main branch + - Get version in target worktree + - Get version in conflicting group worktrees +2. If all different → conflict likely +3. If same → safe to merge + +### Step 3.3: Report Conflicts + +Display potential conflicts to user. + +**Conflict Report**: +```markdown +## Potential Merge Conflicts + +### File: src/shared/config.ts +- Modified by: EG-001 (target), EG-002 +- Status: EG-002 already merged to main +- Action: Manual review recommended + +### File: package.json +- Modified by: EG-001 (target), EG-003 +- Status: EG-003 not yet merged +- Action: Safe to merge (EG-003 will handle conflict) +``` + +**User Decision**: +- Proceed with merge (handle conflicts manually if occur) +- Abort and review files first +- Coordinate with other group maintainers + +--- + +## Phase 4: Merge Worktree + +**Objective**: Merge group's branch from worktree to main. + +### Step 4.1: Prepare Main Branch + +Ensure main branch is up to date. + +```bash +git checkout main +git pull origin main +``` + +### Step 4.2: Merge Group Branch + +Merge from worktree's branch. + +**Merge Command**: +```bash +# Strategy 1: Regular merge (creates merge commit) +git merge --no-ff {branch-name} -m "Merge {group-id}: {description}" + +# Strategy 2: Squash merge (single commit) +git merge --squash {branch-name} +git commit -m "feat: {group-id} - {description}" +``` + +**Default**: Use regular merge to preserve history. + +### Step 4.3: Handle Merge Conflicts + +If conflicts occur, provide resolution guidance. + +**Conflict Resolution**: +```bash +# List conflicting files +git status + +# For each conflict: +# 1. Open file and resolve markers +# 2. Stage resolved file +git add {file} + +# Complete merge +git commit +``` + +**Conflict Types**: +- **Cross-group file**: Expected, requires manual merge +- **Unexpected conflict**: Investigate cause + +### Step 4.4: Push to Remote + +Push merged changes. + +```bash +git push origin main +``` + +**Validation**: +- Check CI/tests pass after merge +- Verify no regressions + +--- + +## Phase 5: Update Status & Cleanup + +**Objective**: Mark group as merged, optionally remove worktree. + +### Step 5.1: Update worktree-status.json + +Mark group as merged. + +**Status Update**: +```json +{ + "groups": { + "EG-001": { + "merge_status": "merged", + "merged_at": "2025-02-03T15:00:00Z", + "merged_to": "main", + "merge_commit": "abc123def456" + } + } +} +``` + +### Step 5.2: Append to merge-log.md + +Record merge details. + +**Merge Log Entry**: +```markdown +## EG-001: Frontend Development + +- **Merged At**: 2025-02-03 15:00:00 +- **Branch**: feature/cplan-auth-eg-001-frontend +- **Commit**: abc123def456 +- **Tasks Completed**: 15/15 +- **Conflicts**: 1 file (src/shared/config.ts) - resolved +- **Status**: Successfully merged to main +``` + +### Step 5.3: Cleanup Worktree (optional) + +Remove worktree if --cleanup flag provided. + +**Cleanup Commands**: +```bash +# Remove worktree +git worktree remove .ccw/worktree/{group-id} + +# Delete branch (optional) +git branch -d {branch-name} +git push origin --delete {branch-name} +``` + +**When to Cleanup**: +- Group successfully merged +- No need to revisit worktree +- Disk space needed + +**When to Keep**: +- May need to reference execution logs +- Other groups may need to coordinate +- Debugging merge issues + +### Step 5.4: Display Summary + +Report merge results. + +**Summary Output**: +``` +✓ Merged EG-001 to main + - Branch: feature/cplan-auth-eg-001-frontend + - Commit: abc123def456 + - Tasks: 15/15 completed + - Conflicts: 1 resolved + - Worktree: Cleaned up + +Remaining groups: + - EG-002: completed, ready to merge + - EG-003: in progress, waiting for dependencies +``` + +--- + +## Configuration + +| Parameter | Default | Description | +|-----------|---------|-------------| +| `--plan` | Auto-detect | Plan session ID | +| `--group` | Interactive | Group to merge | +| `--all` | false | Merge all completed groups | +| `--cleanup` | false | Remove worktree after merge | +| `--force` | false | Ignore dependency checks | +| `--squash` | false | Use squash merge instead of regular | + +--- + +## Error Handling + +| Situation | Action | +|-----------|--------| +| Group not completed | Error: Complete execution first | +| Group already merged | Skip with warning | +| Dependencies not merged | Error or cascade merge (--all) | +| Merge conflict | Pause for manual resolution | +| Worktree not found | Error: Check worktree path | +| Push fails | Rollback merge, report error | + +--- + +## Merge Strategies + +### Strategy 1: Sequential Merge + +Merge groups one by one in dependency order. + +```bash +# Merge EG-001 +--group=EG-001 --cleanup + +# Merge EG-002 +--group=EG-002 --cleanup + +# Merge EG-003 (depends on EG-001, EG-002) +--group=EG-003 --cleanup +``` + +**Use When**: +- Want to review each merge carefully +- High risk of conflicts +- Testing between merges + +### Strategy 2: Bulk Merge + +Merge all completed groups at once. + +```bash +--all --cleanup +``` + +**Use When**: +- Groups are independent +- Low conflict risk +- Want fast integration + +### Strategy 3: Dependency-First + +Merge dependencies before dependent groups. + +```bash +# Automatically merges EG-001, EG-002 before EG-003 +--group=EG-003 --cascade +``` + +**Use When**: +- Complex dependency graph +- Want automatic ordering + +--- + +## Best Practices + +### Before Merge + +1. **Verify Completion**: Check all tasks in group completed +2. **Review Conflicts**: Read conflicts.json for cross-group files +3. **Test Worktree**: Run tests in worktree before merge +4. **Update Main**: Ensure main branch is current + +### During Merge + +1. **Follow Order**: Respect dependency order +2. **Review Conflicts**: Carefully resolve cross-group conflicts +3. **Test After Merge**: Run CI/tests after each merge +4. **Commit Often**: Keep merge history clean + +### After Merge + +1. **Update Status**: Ensure worktree-status.json reflects merge +2. **Keep Logs**: Archive merge-log.md for reference +3. **Cleanup Gradually**: Don't rush to delete worktrees +4. **Notify Team**: Inform others of merged groups + +--- + +## Rollback Strategy + +If merge causes issues: + +```bash +# Find merge commit +git log --oneline + +# Revert merge +git revert -m 1 {merge-commit} +git push origin main + +# Or reset (dangerous, loses history) +git reset --hard HEAD~1 +git push origin main --force + +# Update status +# Mark group as not_merged in worktree-status.json +``` + +--- + +## Example Workflow + +### Scenario: 3 Groups Complete + +**Status**: +- EG-001: Completed (no dependencies) +- EG-002: Completed (no dependencies) +- EG-003: Completed (depends on EG-001, EG-002) + +### Step 1: Merge Independent Groups + +```bash +# Merge EG-001 +--group=EG-001 + +# Test after merge +npm test + +# Merge EG-002 +--group=EG-002 + +# Test after merge +npm test +``` + +### Step 2: Merge Dependent Group + +```bash +# EG-003 depends on EG-001, EG-002 (already merged) +--group=EG-003 + +# Final test +npm test +``` + +### Step 3: Cleanup All Worktrees + +```bash +# Remove all merged worktrees +--cleanup-all +``` + +--- + +## When to Use This Workflow + +### Use worktree-merge when: +- Execution groups completed via unified-execute-parallel +- Ready to integrate changes to main branch +- Need dependency-aware merge order +- Want to handle cross-group conflicts systematically + +### Manual merge when: +- Single group with no dependencies +- Comfortable with Git merge commands +- No cross-group conflicts to handle + +--- + +**Now execute worktree-merge for completed execution groups**