---
phase: 65-paul-delegated-apply
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - ~/.claude/paul-framework/workflows/apply-phase.md
  - ~/.claude/paul-framework/references/delegated-apply.md
  - ~/.claude/paul-framework/references/subagent-criteria.md
  - ~/.claude/paul-framework/templates/PLAN.md
autonomous: false
---

<objective>
## Goal
Rozszerzyć workflow `/paul:apply` o tryb delegowany (delegated-apply), w którym orkiestrator w głównym kontekście rozbija taski z PLAN.md na mikro-zadania i zleca je sub-agentom przez Agent tool. Orkiestrator ocenia wyniki i decyduje: accept / retry / escalate.

## Purpose
Główny kontekst zapełnia się zbyt szybko podczas APPLY — czytanie plików, implementacja, weryfikacja zużywają 60-80% okna kontekstowego na jedną fazę. Delegacja do sub-agentów pozwoli:
- Zachować główny kontekst na poziomie ~15-25% zużycia (orkiestracja + ocena)
- Wykonywać więcej faz w jednej sesji bez handoff
- Poprawić jakość — mniejsze, fokusowe zadania dla sub-agentów
- Umożliwić równoległe wykonywanie niezależnych tasków

## Output
1. Zmodyfikowany `apply-phase.md` z trybem delegowanym
2. Nowy reference `delegated-apply.md` z pełną specyfikacją wzorca
3. Zaktualizowany `subagent-criteria.md` o kontekst PAUL delegacji
4. Zaktualizowany template `PLAN.md` o pole `delegation`
</objective>

<context>
## Project Context
@.paul/PROJECT.md
@.paul/STATE.md

## Source Files (do edycji)
@~/.claude/paul-framework/workflows/apply-phase.md
@~/.claude/paul-framework/references/subagent-criteria.md
@~/.claude/paul-framework/references/delegated-apply.md (nowy)
@~/.claude/paul-framework/templates/PLAN.md
</context>

<acceptance_criteria>

## AC-1: Tryb delegowany aktywuje się automatycznie lub ręcznie
```gherkin
Given plan z polem `delegation: auto` w frontmatter
When /paul:apply wykonuje plan
Then orkiestrator rozbija każdy task type="auto" na mikro-prompt i zleca Agent tool
And checkpointy (human-verify, decision) pozostają w głównym kontekście
```

## AC-2: Mikro-prompt zawiera pełny kontekst dla sub-agenta
```gherkin
Given task z PLAN.md z polami files, action, verify, done, boundaries
When orkiestrator buduje mikro-prompt
Then prompt zawiera: cel zadania, ścieżki plików, dokładne instrukcje, co NIE zmieniać, jak zweryfikować
And sub-agent nie musi czytać PLAN.md ani STATE.md (zero dodatkowego kontekstu)
```

## AC-3: Orkiestrator ocenia wynik i podejmuje decyzję
```gherkin
Given sub-agent zwrócił wynik mikro-zadania
When orkiestrator analizuje zwrócony summary
Then podejmuje jedną z decyzji: accept (kontynuuj) / retry (ponów z feedbackiem) / escalate (poproś użytkownika)
And loguje decyzję do progress trackera
```

## AC-4: Fallback do trybu inline
```gherkin
Given plan z polem `delegation: off` lub brak pola delegation
When /paul:apply wykonuje plan
Then workflow działa identycznie jak dotychczas (bez zmian w zachowaniu)
```

## AC-5: Równoległe wykonywanie niezależnych tasków
```gherkin
Given plan z 2+ taskami type="auto" które nie mają zależności między sobą
When orkiestrator jest w trybie delegowanym
Then może zlecić niezależne taski równolegle (multiple Agent calls w jednym kroku)
```

</acceptance_criteria>

<tasks>

<task type="auto">
  <name>Task 1: Utworzenie reference delegated-apply.md</name>
  <files>~/.claude/paul-framework/references/delegated-apply.md</files>
  <action>
    Utwórz nowy plik referencyjny opisujący wzorzec delegated-apply:

    1. **Architektura orkiestratora:**
       - Główny kontekst = lekki koordynator (czyta plan, buduje prompty, ocenia wyniki)
       - Sub-agent = wykonawca jednego mikro-zadania (czyta pliki, implementuje, weryfikuje)
       - Przepływ: parse plan → dla każdego taska → build micro-prompt → spawn Agent → evaluate result → accept/retry/escalate

    2. **Budowanie mikro-promptu:**
       Każdy mikro-prompt dla sub-agenta MUSI zawierać:
       ```
       ## Cel
       [task name z PLAN.md]

       ## Pliki do modyfikacji
       [files z PLAN.md]

       ## Instrukcje
       [action z PLAN.md — pełna treść, nie skrócona]

       ## Granice — NIE ZMIENIAJ
       [boundaries z PLAN.md]

       ## Weryfikacja
       [verify z PLAN.md]

       ## Kryteria ukończenia
       [done z PLAN.md]

       ## Kontekst projektu (minimum)
       - Stack: [z PROJECT.md — 1-2 linijki]
       - Konwencje: [kluczowe konwencje z CONVENTIONS/CLAUDE.md — max 5 linijek]
       ```

    3. **Ocena wyników (evaluation protocol):**
       - Sub-agent zwraca summary ~100-300 słów
       - Orkiestrator sprawdza:
         a) Czy pliki zostały zmodyfikowane (git diff --stat)
         b) Czy done criteria z PLAN.md są spełnione
         c) Czy boundaries nie zostały naruszone (git diff na chronionych plikach)
       - Decyzja:
         - **accept**: wynik OK → przejdź do następnego taska
         - **retry** (max 3x): wynik niekompletny → spawn Agent z feedbackiem co poprawić
         - **escalate**: 3 retry failed lub problem wymaga decyzji → pytaj użytkownika

    4. **Tryby delegacji:**
       - `delegation: auto` — orkiestrator automatycznie deleguje taski type="auto"
       - `delegation: parallel` — jak auto, ale niezależne taski lecą równolegle
       - `delegation: off` — klasyczny inline (domyślne, backward compatible)

    5. **Ograniczenia:**
       - Checkpointy (human-verify, decision, human-action) ZAWSZE w głównym kontekście
       - Sub-agent NIE aktualizuje STATE.md ani PLAN.md — to robi orkiestrator
       - Max 1 task per sub-agent (atomowość)
       - Sub-agent type: `general-purpose` (domyślny)

    6. **Szacunek oszczędności kontekstu:**
       | Element | Inline (teraz) | Delegated |
       |---------|----------------|-----------|
       | Czytanie plików źródłowych | ~3-5k tokens/plik | 0 (w sub-agencie) |
       | Implementacja kodu | ~10-20k tokens | 0 (w sub-agencie) |
       | Wynik weryfikacji | ~2-5k tokens | ~0.5k (summary) |
       | Orkiestracja per task | 0 | ~1-2k tokens |
       | **Total per task** | **~15-30k** | **~2-3k** |

  </action>
  <verify>Plik istnieje w ~/.claude/paul-framework/references/delegated-apply.md i zawiera sekcje: Architektura, Mikro-prompt, Evaluation Protocol, Tryby, Ograniczenia</verify>
  <done>AC-2 satisfied: specyfikacja mikro-promptu zdefiniowana. AC-3 satisfied: evaluation protocol zdefiniowany.</done>
</task>

<task type="auto">
  <name>Task 2: Modyfikacja apply-phase.md — dodanie trybu delegowanego</name>
  <files>~/.claude/paul-framework/workflows/apply-phase.md</files>
  <action>
    Dodaj nowy krok `determine_execution_mode` PRZED `execute_tasks` oraz zmodyfikuj `execute_tasks`:

    1. **Nowy krok `determine_execution_mode`** (po `verify_required_skills`):
       ```
       1. Sprawdź frontmatter pola `delegation`:
          - `auto` lub `parallel` → tryb delegowany
          - `off` lub brak pola → tryb inline (bez zmian)
       2. Jeśli tryb delegowany:
          - Załaduj @references/delegated-apply.md
          - Przygotuj kontekst projektu dla mikro-promptów (stack, konwencje — max 10 linijek)
          - Zidentyfikuj taski niezależne (do równoległego wykonania jeśli `parallel`)
       3. Log: "Execution mode: delegated|inline"
       ```

    2. **Rozszerzenie `execute_tasks`** — dodaj alternatywną ścieżkę dla trybu delegowanego:

       **Jeśli tryb delegowany i task type="auto":**
       ```
       1. Zbuduj mikro-prompt wg szablonu z delegated-apply.md
       2. Wywołaj Agent tool:
          - subagent_type: "general-purpose"
          - prompt: [mikro-prompt]
          - description: "PAUL task: [task name]" (3-5 słów)
       3. Odbierz wynik (summary od sub-agenta)
       4. Oceń wg evaluation protocol:
          - Sprawdź git diff --stat
          - Sprawdź done criteria
          - Sprawdź boundaries
       5. Decyzja: accept / retry / escalate
       6. Przy retry: spawn ponownie z feedbackiem (max 3 razy)
       ```

       **Jeśli `delegation: parallel` i multiple niezależne taski:**
       ```
       1. Zidentyfikuj klastry niezależnych tasków
       2. Wywołaj multiple Agent tool w jednym kroku
       3. Oceń wyniki każdego
       4. Kontynuuj sekwencyjnie z taskami zależnymi
       ```

       **Checkpointy — BEZ ZMIAN:**
       Taski checkpoint:* zawsze wykonywane inline w głównym kontekście.

    3. **Rozszerzenie `finalize`** — dodaj podsumowanie trybu:
       ```
       Delegated execution summary:
       - Tasks delegated: N
       - Accepted on first try: N
       - Retried: N
       - Escalated: N
       ```

    WAŻNE: Nie usuwaj i nie modyfikuj istniejącego zachowania inline. Tryb delegowany to DODATKOWA ścieżka.
  </action>
  <verify>apply-phase.md zawiera kroki: determine_execution_mode, execute_tasks z alternatywną ścieżką delegowaną, finalize z podsumowaniem delegacji</verify>
  <done>AC-1 satisfied: tryb delegowany aktywuje się na podstawie pola delegation. AC-4 satisfied: brak pola = inline bez zmian.</done>
</task>

<task type="auto">
  <name>Task 3: Aktualizacja PLAN.md template i subagent-criteria.md</name>
  <files>~/.claude/paul-framework/templates/PLAN.md, ~/.claude/paul-framework/references/subagent-criteria.md</files>
  <action>
    1. **PLAN.md template** — dodaj pole `delegation` do frontmatter:
       ```yaml
       delegation: off          # off | auto | parallel
       ```
       - Dodaj pole po `autonomous` z komentarzem
       - Dodaj do tabeli Frontmatter Fields: `delegation | No | Execution mode: off (inline, default), auto (delegated), parallel (delegated + parallel)`
       - Dodaj krótką sekcję "## Delegation Mode" w dokumencie opisującą kiedy użyć jakiego trybu

    2. **subagent-criteria.md** — dodaj sekcję o kontekście PAUL:
       - Nowa sekcja "## PAUL Delegated Apply Context"
       - Wyjaśnij że w kontekście /paul:apply, sub-agenty służą do:
         a) Wykonywania tasków z PLAN.md (well-defined, files+action+verify+done)
         b) Ochrony głównego kontekstu orkiestratora
         c) Umożliwienia wielu faz w jednej sesji
       - Podkreśl że kryteria z istniejącej sekcji nadal obowiązują
       - Dodaj notę: "W PAUL delegated-apply, każdy task z PLAN.md naturalnie spełnia kryteria: Task Independence (self-contained), Clear Scope (files+action+verify+done), Complexity Sweet Spot (2-3 taski per plan = 1 task per agent)"
  </action>
  <verify>PLAN.md template zawiera pole delegation w frontmatter i tabeli. subagent-criteria.md zawiera sekcję PAUL Delegated Apply Context.</verify>
  <done>AC-1 partially satisfied: template wspiera pole delegation. AC-5 satisfied: parallel mode zdefiniowany.</done>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <what-built>
    Kompletny wzorzec delegated-apply dla PAUL:
    1. Reference doc z architekturą, mikro-promptem, evaluation protocol
    2. Zmodyfikowany apply-phase.md z trybem delegowanym
    3. Zaktualizowany template i subagent-criteria
  </what-built>
  <how-to-verify>
    1. Przejrzyj ~/.claude/paul-framework/references/delegated-apply.md
    2. Przejrzyj zmiany w ~/.claude/paul-framework/workflows/apply-phase.md
    3. Sprawdź czy PLAN.md template ma pole delegation
    4. Przetestuj na następnej fazie orderPRO z `delegation: auto`
  </how-to-verify>
  <resume-signal>Type "approved" to continue, or describe issues to fix</resume-signal>
</task>

</tasks>

<boundaries>

## DO NOT CHANGE
- ~/.claude/paul-framework/workflows/plan-phase.md (planning workflow untouched)
- ~/.claude/paul-framework/workflows/unify-phase.md (unify workflow untouched)
- ~/.claude/paul-framework/rules/* (framework rules untouched)
- .paul/PROJECT.md, .paul/ROADMAP.md (project state untouched)

## SCOPE LIMITS
- Nie zmieniamy /paul:plan ani /paul:unify — tylko /paul:apply
- Nie tworzymy nowych komend — rozszerzamy istniejący workflow
- Nie przerabiamy istniejącego trybu inline — dodajemy alternatywną ścieżkę
- Nie implementujemy auto-detection rozmiaru (proste pole w frontmatter wystarczy)

</boundaries>

<verification>
Before declaring plan complete:
- [ ] delegated-apply.md istnieje i zawiera: architekturę, mikro-prompt template, evaluation protocol, tryby, ograniczenia
- [ ] apply-phase.md zawiera krok determine_execution_mode i alternatywną ścieżkę delegowaną
- [ ] PLAN.md template zawiera pole delegation w frontmatter
- [ ] subagent-criteria.md zawiera sekcję PAUL context
- [ ] Tryb inline (delegation: off / brak pola) działa bez zmian
- [ ] Wszystkie checkpointy nadal działają w głównym kontekście
</verification>

<success_criteria>
- Wszystkie 3 taski auto completed + checkpoint approved
- Framework PAUL wspiera tryb delegated-apply
- Backward compatible — istniejące plany bez pola delegation działają jak dotychczas
- Gotowy do przetestowania na następnej fazie orderPRO
</success_criteria>

<output>
After completion, create `.paul/phases/65-paul-delegated-apply/65-01-SUMMARY.md`
</output>
