update

2026-04-03 22:35:49 +02:00
parent 0e7ee957cb
commit e95c4967d2
52 changed files with 7430 additions and 631 deletions
--- a/.paul/phases/65-paul-delegated-apply/65-01-PLAN.md
+++ b/.paul/phases/65-paul-delegated-apply/65-01-PLAN.md
@@ -0,0 +1,302 @@
+---
+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>