docs: Add comparison guide between Claude and Codex unified-execute versions

.codex/prompts/UNIFIED_EXECUTE_COMPARISON.md

@@ -0,0 +1,205 @@
+# 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)**:
+```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
+```bash
+/workflow:unified-execute-with-file -y -p PLAN_PATH -m parallel
+```
+
+### Codex Version (Prompt)
+
+**Header (Simple)**:
+```yaml
+---
+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:
+
+```markdown
+## 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.
+