Claude-Code-Workflow/.codex/prompts/UNIFIED_EXECUTE_COMPARISON.md

Unified-Execute-With-File: Claude vs Codex Versions

Overview

Two complementary implementations of the universal execution engine:

Aspect	Claude CLI Command	Codex Prompt
Location	.claude/commands/workflow/	.codex/prompts/
Format	YAML frontmatter + Markdown	Simple Markdown + Variables
Execution	/workflow:unified-execute-with-file	Direct Codex execution
Lines	807 (optimized)	722 (adapted)
Parameters	CLI flags (-y, -p, -m)	Substitution variables ($PLAN_PATH, etc)

---

Format Differences

Claude Version (CLI Command)

Header (YAML):

---
name: unified-execute-with-file
description: Universal execution engine...
argument-hint: "[-y|--yes] [-p|--plan <path>] [-m|--mode sequential|parallel]"
allowed-tools: TodoWrite(*), Task(*), ...
---

Parameters: CLI-style flags with short forms

/workflow:unified-execute-with-file -y -p PLAN_PATH -m parallel

Codex Version (Prompt)

Header (Simple):

---
description: Universal execution engine...
argument-hint: "PLAN_PATH=\"<path>\" [EXECUTION_MODE=\"sequential|parallel\"]"
---

Parameters: Variable substitution with named arguments

PLAN_PATH=".workflow/IMPL_PLAN.md"
EXECUTION_MODE="parallel"
AUTO_CONFIRM="yes"

---

Functional Equivalence

Core Features (Identical)

Both versions support:

• ✅ Format-agnostic plan parsing (IMPL_PLAN.md, synthesis.json, conclusions.json)
• ✅ Multi-agent orchestration (code-developer, test-fix-agent, doc-generator, etc)
• ✅ Automatic dependency resolution with topological sort
• ✅ Parallel execution with wave-based grouping (max 3 tasks/wave)
• ✅ Unified event logging (execution-events.md as SINGLE SOURCE OF TRUTH)
• ✅ Knowledge chain: agents read all previous executions
• ✅ Incremental execution with resume capability
• ✅ Error handling: retry/skip/abort logic
• ✅ Session management and folder organization

Session Structure (Identical)

Both create:

.workflow/.execution/{executionId}/
├── execution.md              # Execution plan and status
└── execution-events.md       # Unified execution log (SINGLE SOURCE OF TRUTH)

---

Key Adaptations

Claude CLI Version

Optimizations:

• Direct access to Claude Code tools (TodoWrite, Task, AskUserQuestion)
• CLI tool integration (ccw cli)
• Background agent execution with run_in_background flag
• Direct file system operations via Bash

Structure:

• Comprehensive Implementation Details section
• Explicit allowed-tools configuration
• Integration with workflow command system

Codex Version

Adaptations:

• Simplified execution context (no direct tool access)
• Variable substitution for parameter passing
• Streamlined phase explanations
• Focused on core logic and flow
• Self-contained event logging

Benefits:

• Works with Codex's execution model
• Simpler parameter interface
• 85 fewer lines while maintaining all core functionality

---

Parameter Mapping

Concept	Claude	Codex
Plan path	-p path/to/plan.md	PLAN_PATH="path/to/plan.md"
Execution mode	-m sequential|parallel	EXECUTION_MODE="sequential|parallel"
Auto-confirm	-y, --yes	AUTO_CONFIRM="yes"
Context focus	"execution context"	EXECUTION_CONTEXT="focus area"

---

Recommended Usage

Use Claude Version When:

• Using Claude Code CLI environment
• Need direct integration with workflow system
• Want full tool access (TodoWrite, Task, AskUserQuestion)
• Prefer CLI flag syntax
• Building multi-command workflows

Use Codex Version When:

• Executing within Codex directly
• Need simpler execution model
• Prefer variable substitution
• Want standalone execution
• Integrating with Codex command chains

---

Event Logging (Unified)

Both versions produce identical execution-events.md format:

## Task {id} - {STATUS} {emoji}

**Timestamp**: {ISO8601}
**Duration**: {ms}
**Agent**: {agent_type}

### Execution Summary
{summary}

### Generated Artifacts
- `path/to/file` (size)

### Notes for Next Agent
- Key decisions
- Issues identified
- Ready for: NEXT_TASK_ID

---

---

Migration Path

If switching between Claude and Codex versions:

1. Same session ID format: Both use .workflow/.execution/{executionId}/
2. Same event log structure: execution-events.md is 100% compatible
3. Same artifact locations: Files generated at project paths (e.g., src/types/auth.ts)
4. Same agent selection: Both use identical selectBestAgent() strategy
5. Same parallelization rules: Identical wave grouping and file conflict detection

You can:

• Start execution with Claude, resume with Codex
• Start with Codex, continue with Claude
• Mix both in multi-step workflows

---

Statistics

Metric	Claude	Codex
Lines	807	722
Size	25 KB	22 KB
Phases	4 full phases	4 phases (adapted)
Agent types	6+ supported	6+ supported
Parallelization	Max 3 tasks/wave	Max 3 tasks/wave
Error handling	retry/skip/abort	retry/skip/abort

---

Implementation Timeline

1. Initial Claude version: Full unified-execute-with-file.md (1094 lines)
2. Claude optimization: Consolidated duplicates (807 lines, -26%)
3. Codex adaptation: Format-adapted version (722 lines)

Both versions represent same core logic with format-specific optimizations.