mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
docs: Add comparison guide between Claude and Codex unified-execute versions
This commit is contained in:
catlog22
205
.codex/prompts/UNIFIED_EXECUTE_COMPARISON.md
Normal file
205
.codex/prompts/UNIFIED_EXECUTE_COMPARISON.md
Normal file
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user