11 KiB
11 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous, delegation
| phase | plan | type | wave | depends_on | files_modified | autonomous | delegation | ||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 67-paul-codex-executor | 01 | execute | 1 |
|
|
true | auto |
Purpose
- Oszczędność 5h limitu Claude Code — Codex jest osobno opłacany
- Rotacja executorów — wymuszenie użycia Codex przy większych planach
- Fallback — gdy Claude limit się kończy, praca nie staje
Output
- Zaktualizowany
delegated-apply.mdz sekcją Codex executor - Zaktualizowany
apply-phase.mdz logiką wyboru executor (Claude vs Codex) - Zaktualizowany
PLAN.mdtemplate z nowym trybem delegation
Research: Codex CLI
- Komenda:
codex exec -c 'approval_mode="full-auto"' "prompt" - Model: gpt-5.3-codex
- Synchroniczny, non-interactive, zwraca diff + summary
- Timeout: ~30s na proste zadanie, max ~5min na złożone
- Uwagi: pilnować UTF-8 bez BOM, polskie znaki w prompcie
- Skill warnings (niekrytyczne): ignorować
<acceptance_criteria>
AC-1: Reguła 1/3 Codex przy >3 taskach
Given plan z 6 taskami type="auto" i delegation: auto
When orkiestrator przydziela executory
Then minimum 2 taski (ceil(6/3)) idą przez Codex
And pozostałe 4 przez Claude sub-agent
And wybór tasków dla Codex to te najprostsze (najmniej plików)
AC-2: Auto-fallback Claude → Codex
Given task delegowany do Claude sub-agent
When Agent tool zwróci błąd quota/rate-limit
Then orkiestrator automatycznie ponawia ten sam task przez codex exec
And loguje: "Task N: Claude quota → fallback Codex"
AC-3: Codex micro-prompt zawiera guard UTF-8
Given task przydzielony do Codex
When orkiestrator buduje mikro-prompt
Then prompt zawiera instrukcje: "IMPORTANT: All files must remain UTF-8 without BOM. Preserve Polish characters (ą,ć,ę,ł,ń,ó,ś,ź,ż)."
AC-4: Backward compatible
Given plan z delegation: off lub delegation: auto z <=3 taskami
When orkiestrator wykonuje plan
Then zachowanie identyczne jak dotychczas (bez Codex)
</acceptance_criteria>
Task 1: Rozszerzenie delegated-apply.md o Codex executor ~/.claude/paul-framework/references/delegated-apply.md Przeczytaj plik, potem dodaj nowe sekcje.1. Dodaj nową sekcję "## Codex Executor" PO sekcji "## Evaluation Protocol" a PRZED "## Delegation Modes":
```markdown
## Codex Executor
Codex CLI (`codex exec`) służy jako alternatywny executor dla tasków z PLAN.md.
### Wywołanie
```bash
codex exec -c 'approval_mode="full-auto"' "MICRO_PROMPT"
```
- Synchroniczny, non-interactive
- Timeout Bash: 300000ms (5 min)
- Output zawiera diff + summary — parsowany przez orkiestratora
### Reguła 1/3
Jeśli plan ma **>3 tasków type="auto"**, minimum `ceil(count/3)` tasków MUSI iść przez Codex:
| Tasków auto | Min Codex | Min Claude |
|-------------|-----------|------------|
| 1-3 | 0 | all |
| 4-6 | 2 | reszta |
| 7-9 | 3 | reszta |
| 10+ | ceil(N/3) | reszta |
**Wybór tasków dla Codex:** Orkiestrator przydziela Codexowi taski o najmniejszej liczbie plików w `<files>` (najprostsze). Jeśli równe — pierwsze w kolejności.
**KRYTYCZNE: Brak współdzielenia plików.** Codex i Claude sub-agenty NIE MOGĄ edytować tych samych plików — działają na tym samym working directory. Orkiestrator MUSI sprawdzić `<files>` każdego taska i zapewnić że:
- Żaden plik z tasków Codex nie pokrywa się z plikami tasków Claude
- Jeśli jest konflikt plików → oba taski idą do tego samego executora
- Przy parallel mode: taski z tymi samymi plikami NIE lecą równolegle
### Auto-fallback
Jeśli Claude Agent tool zwróci błąd (quota, rate-limit, timeout):
1. Orkiestrator loguje: "Task N: Claude error → fallback Codex"
2. Ponawia TEN SAM mikro-prompt przez `codex exec`
3. Evaluation protocol identyczny jak dla Claude
### Micro-prompt guard
Każdy mikro-prompt wysyłany do Codex MUSI zawierać na końcu:
```
## IMPORTANT
- All files must remain UTF-8 without BOM encoding
- Preserve all Polish characters: ą,ć,ę,ł,ń,ó,ś,ź,ż,Ą,Ć,Ę,Ł,Ń,Ó,Ś,Ź,Ż
- Do NOT convert file encoding
- Do NOT add BOM markers
```
### Evaluation po Codex
Identyczny jak po Claude sub-agent:
1. git diff --stat
2. Sprawdź done criteria
3. Sprawdź boundaries
4. **Dodatkowe:** `file` command na zmodyfikowanych plikach — potwierdź UTF-8
5. Decyzja: accept / retry / escalate
```
2. W sekcji "## Delegation Modes", zaktualizuj tabelę:
Dodaj wiersz:
```
| codex | `delegation: codex` | Wszystkie taski auto przez Codex exec |
```
W "Kiedy użyć jakiego" dodaj:
```
- **`codex`** — wymuszone użycie Codex dla wszystkich tasków (np. przy niskim limicie Claude)
```
3. W sekcji "## Constraints", dodaj:
```
- Codex exec timeout: 300s (5 min) per task — jeśli task jest większy, rozbij
- Codex nie ma dostępu do MCP servers ani Agent tool — tylko filesystem + shell
```
1. W kroku `determine_execution_mode`, ROZSZERZ punkt 2 ("If delegated mode"):
Dodaj pod-punkt po identyfikacji task clusters:
```
- Determine executor assignment per task:
a. Count auto tasks in plan
b. If count > 3: assign ceil(count/3) tasks to Codex executor
- Select tasks with fewest files in <files> for Codex
- Remaining tasks go to Claude Agent tool
- CRITICAL: Verify no file overlap between Codex and Claude tasks
If overlap detected → move conflicting task to same executor as its peer
c. If delegation: codex → all auto tasks to Codex
d. If delegation: auto/parallel with <=3 tasks → all to Claude Agent tool
e. Log: "Executor assignment: N Claude, M Codex (no file conflicts)"
```
2. W kroku `execute_tasks`, w bloku "If delegated mode and task type=auto":
Dodaj rozgałęzienie na executor:
```
**If task assigned to Claude Agent tool:**
[existing Agent tool delegation — no changes]
**If task assigned to Codex executor:**
1. Build micro-prompt (same template as Claude)
2. Append UTF-8 guard block to prompt
3. Execute via Bash:
codex exec -c 'approval_mode="full-auto"' "MICRO_PROMPT"
Timeout: 300000ms
4. Parse output for diff and summary
5. Evaluate: git diff + done criteria + boundaries + UTF-8 check
6. Decision: accept / retry (max 3) / escalate
**Auto-fallback (Claude → Codex):**
If Agent tool returns error (quota/rate-limit/connection):
1. Log: "Task N: [name] → Claude error: [reason] → fallback Codex"
2. Re-execute same micro-prompt via codex exec
3. Continue evaluation as normal
```
3. W kroku `finalize`, rozszerz "Delegated execution summary":
```
- Tasks via Claude: N
- Tasks via Codex: N
- Tasks via Codex (fallback): N
```
4. W sekcji `error_handling`, dodaj:
```
**Codex exec timeout:**
- If codex exec exceeds 300s timeout: mark as failed
- Offer retry via Claude Agent tool (reverse fallback)
**Codex encoding issue:**
- If file check shows non-UTF-8 after Codex: auto-fix encoding
- Log warning and continue
```
WAŻNE: Nie usuwaj istniejącej logiki — rozszerzaj.
1. W frontmatter YAML, zaktualizuj komentarz przy delegation:
Zmień:
```yaml
delegation: auto # auto (default) | parallel | off — execution mode for /paul:apply
```
na:
```yaml
delegation: auto # auto (default) | parallel | codex | off — execution mode for /paul:apply
```
2. W tabeli Frontmatter Fields, zaktualizuj opis delegation:
Zmień na:
```
| `delegation` | No | Execution mode: `auto` (delegated, 1/3 Codex if >3 tasks, default), `parallel` (delegated + parallel), `codex` (all tasks via Codex), `off` (inline, legacy) |
```
3. W sekcji "## Delegation Mode", dodaj `codex` do tabeli:
```
| `codex` | When Claude limit is low or you want to force Codex for all tasks |
```
WAŻNE: Nie zmieniaj nic innego.
DO NOT CHANGE
- ~/.claude/paul-framework/workflows/plan-phase.md
- ~/.claude/paul-framework/workflows/unify-phase.md
- ~/.claude/paul-framework/rules/*
- ~/.claude/paul-framework/references/subagent-criteria.md
- .paul/PROJECT.md, .paul/ROADMAP.md
SCOPE LIMITS
- Nie tworzymy wrapper script dla codex — wywołanie bezpośrednio z Bash
- Nie modyfikujemy Codex config (~/.codex/) — używamy -c flag
- Nie implementujemy monitoring limitu Claude — reaktywny fallback wystarczy
<success_criteria>
- Wszystkie 3 taski completed
- PAUL apply wspiera Codex jako executor
- Reguła 1/3 wymusza rotację przy większych planach
- Auto-fallback chroni przed przestojem przy quota error
- Backward compatible </success_criteria>