---
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>