diff --git a/.codex/prompts/UNIFIED_EXECUTE_COMPARISON.md b/.codex/prompts/UNIFIED_EXECUTE_COMPARISON.md new file mode 100644 index 00000000..a672b847 --- /dev/null +++ b/.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 ] [-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=\"\" [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. +