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.

mkdir -p .ccw/worktree

Step 2.2: Create Git Worktree

Create worktree with group's branch.

If worktree doesn't exist:

# Create branch and worktree
git worktree add -b {branch-name} .ccw/worktree/{group-id} main

If worktree exists:

# 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.

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.

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.

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/):

{
  "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:

# 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