311 lines
11 KiB
Markdown
311 lines
11 KiB
Markdown
---
|
|
phase: 67-paul-codex-executor
|
|
plan: 01
|
|
type: execute
|
|
wave: 1
|
|
depends_on: ["65-01"]
|
|
files_modified:
|
|
- ~/.claude/paul-framework/references/delegated-apply.md
|
|
- ~/.claude/paul-framework/workflows/apply-phase.md
|
|
- ~/.claude/paul-framework/templates/PLAN.md
|
|
autonomous: true
|
|
delegation: auto
|
|
---
|
|
|
|
<objective>
|
|
## Goal
|
|
Dodać Codex CLI (`codex exec`) jako alternatywny executor w PAUL delegated-apply. Reguła: jeśli plan ma >3 tasków auto, 1/3 z nich MUSI iść przez Codex. Plus: auto-fallback na Codex przy quota error Claude.
|
|
|
|
## 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.md` z sekcją Codex executor
|
|
- Zaktualizowany `apply-phase.md` z logiką wyboru executor (Claude vs Codex)
|
|
- Zaktualizowany `PLAN.md` template z nowym trybem delegation
|
|
</objective>
|
|
|
|
<context>
|
|
## Prior Work
|
|
@.paul/phases/65-paul-delegated-apply/65-01-SUMMARY.md
|
|
|
|
## 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ć
|
|
</context>
|
|
|
|
<acceptance_criteria>
|
|
|
|
## AC-1: Reguła 1/3 Codex przy >3 taskach
|
|
```gherkin
|
|
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
|
|
```gherkin
|
|
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
|
|
```gherkin
|
|
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
|
|
```gherkin
|
|
Given plan z delegation: off lub delegation: auto z <=3 taskami
|
|
When orkiestrator wykonuje plan
|
|
Then zachowanie identyczne jak dotychczas (bez Codex)
|
|
```
|
|
|
|
</acceptance_criteria>
|
|
|
|
<tasks>
|
|
|
|
<task type="auto">
|
|
<name>Task 1: Rozszerzenie delegated-apply.md o Codex executor</name>
|
|
<files>~/.claude/paul-framework/references/delegated-apply.md</files>
|
|
<action>
|
|
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
|
|
```
|
|
</action>
|
|
<verify>Plik zawiera sekcję "Codex Executor" z regułą 1/3, auto-fallback, micro-prompt guard. Tabela Delegation Modes zawiera tryb codex.</verify>
|
|
<done>AC-1 spec: reguła 1/3 zdefiniowana. AC-2 spec: auto-fallback zdefiniowany. AC-3 spec: UTF-8 guard zdefiniowany.</done>
|
|
</task>
|
|
|
|
<task type="auto">
|
|
<name>Task 2: Logika executor selection w apply-phase.md</name>
|
|
<files>~/.claude/paul-framework/workflows/apply-phase.md</files>
|
|
<action>
|
|
Przeczytaj plik, potem zmodyfikuj.
|
|
|
|
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.
|
|
</action>
|
|
<verify>apply-phase.md zawiera: executor assignment w determine_execution_mode, rozgałęzienie Claude/Codex w execute_tasks, auto-fallback, Codex w finalize summary, Codex error handling.</verify>
|
|
<done>AC-1: logika 1/3 w orkiestratorze. AC-2: auto-fallback zaimplementowany. AC-4: <=3 tasków = bez Codex.</done>
|
|
</task>
|
|
|
|
<task type="auto">
|
|
<name>Task 3: Aktualizacja PLAN.md template</name>
|
|
<files>~/.claude/paul-framework/templates/PLAN.md</files>
|
|
<action>
|
|
Przeczytaj plik, potem zmodyfikuj.
|
|
|
|
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.
|
|
</action>
|
|
<verify>PLAN.md template zawiera tryb codex w frontmatter komentarzu, tabeli i sekcji Delegation Mode.</verify>
|
|
<done>AC-4 partially: template zaktualizowany o nowy tryb.</done>
|
|
</task>
|
|
|
|
</tasks>
|
|
|
|
<boundaries>
|
|
|
|
## 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
|
|
|
|
</boundaries>
|
|
|
|
<verification>
|
|
- [ ] delegated-apply.md zawiera sekcję Codex Executor z regułą 1/3
|
|
- [ ] apply-phase.md zawiera executor assignment + rozgałęzienie Claude/Codex
|
|
- [ ] apply-phase.md zawiera auto-fallback Claude → Codex
|
|
- [ ] PLAN.md template zawiera tryb codex
|
|
- [ ] Reguła 1/3 dotyczy tylko planów >3 tasków auto
|
|
- [ ] UTF-8 guard jest w każdym Codex mikro-prompcie
|
|
</verification>
|
|
|
|
<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>
|
|
|
|
<output>
|
|
After completion, create `.paul/phases/67-paul-codex-executor/67-01-SUMMARY.md`
|
|
</output>
|