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>
--- a/.paul/phases/65-paul-delegated-apply/65-01-SUMMARY.md
+++ b/.paul/phases/65-paul-delegated-apply/65-01-SUMMARY.md
@@ -0,0 +1,124 @@
+---
+phase: 65-paul-delegated-apply
+plan: 01
+subsystem: infra
+tags: [paul-framework, subagents, delegation, context-management]
+
+requires:
+  - phase: none
+    provides: standalone enhancement
+
+provides:
+  - Delegated-apply execution mode for /paul:apply
+  - Micro-prompt template for sub-agent task delegation
+  - Evaluation protocol (accept/retry/escalate)
+  - delegation field in PLAN.md frontmatter
+
+affects: [all future phases using /paul:apply]
+
+tech-stack:
+  added: []
+  patterns: [orchestrator-subagent delegation, micro-prompt composition, evaluation protocol]
+
+key-files:
+  created:
+    - ~/.claude/paul-framework/references/delegated-apply.md
+  modified:
+    - ~/.claude/paul-framework/workflows/apply-phase.md
+    - ~/.claude/paul-framework/templates/PLAN.md
+    - ~/.claude/paul-framework/references/subagent-criteria.md
+
+key-decisions:
+  - "delegation: auto as default for all new plans"
+  - "Max 3 retries before escalation to user"
+  - "Checkpoints always inline, never delegated"
+
+patterns-established:
+  - "Orchestrator builds micro-prompt from PLAN.md task fields, delegates via Agent tool"
+  - "Evaluation: git diff + done criteria + boundary check → accept/retry/escalate"
+
+duration: ~15min
+started: 2026-04-03T20:10:00Z
+completed: 2026-04-03T20:25:00Z
+---
+
+# Phase 65 Plan 01: PAUL Delegated Apply Summary
+
+**Rozszerzenie /paul:apply o tryb delegowany — orkiestrator w głównym kontekście zleca mikro-zadania sub-agentom, ocenia wyniki i decyduje accept/retry/escalate. Szacowana oszczędność: ~80% kontekstu per faza.**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~15min |
+| Started | 2026-04-03T20:10:00Z |
+| Completed | 2026-04-03T20:25:00Z |
+| Tasks | 3 auto + 1 checkpoint completed |
+| Files modified | 4 |
+| Execution mode | Delegated (parallel) — 3 sub-agents |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: Tryb delegowany aktywuje się automatycznie | Pass | Pole `delegation: auto` (domyślne), workflow sprawdza frontmatter |
+| AC-2: Mikro-prompt zawiera pełny kontekst | Pass | Template w delegated-apply.md: cel, pliki, instrukcje, granice, weryfikacja, kontekst |
+| AC-3: Orkiestrator ocenia wynik | Pass | Evaluation protocol: git diff + done criteria + boundary check → accept/retry/escalate |
+| AC-4: Fallback do trybu inline | Pass | `delegation: off` = inline bez zmian; brak pola = auto (zmiana z oryginalnego planu) |
+| AC-5: Równoległe wykonywanie tasków | Pass | `delegation: parallel` mode zdefiniowany w workflow i reference |
+
+## Accomplishments
+
+- Utworzono kompletny reference `delegated-apply.md` z architekturą, mikro-prompt template, evaluation protocol, trybami i ograniczeniami
+- Rozszerzono `apply-phase.md` o krok `determine_execution_mode` i alternatywną ścieżkę delegowaną (inline path bez zmian)
+- Zaktualizowano template PLAN.md o pole `delegation` (domyślnie `auto`) i sekcję Delegation Mode
+- Rozszerzono `subagent-criteria.md` o kontekst PAUL delegated-apply
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `~/.claude/paul-framework/references/delegated-apply.md` | Created | Pełna specyfikacja wzorca delegated-apply |
+| `~/.claude/paul-framework/workflows/apply-phase.md` | Modified | Nowy krok determine_execution_mode + delegated path + delegation summary w finalize |
+| `~/.claude/paul-framework/templates/PLAN.md` | Modified | Pole delegation w frontmatter (default: auto) + sekcja Delegation Mode |
+| `~/.claude/paul-framework/references/subagent-criteria.md` | Modified | Sekcja PAUL Delegated Apply Context |
+
+## Decisions Made
+
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| `delegation: auto` jako default | Użytkownik chce delegacji jako standardowego zachowania, nie opt-in | Wszystkie nowe plany automatycznie delegują taski |
+| Max 3 retries (zmiana z 2) | Użytkownik poprosił o zwiększenie — daje więcej szans na sukces | Mniej escalacji do użytkownika |
+| Checkpointy zawsze inline | Wymagają interakcji z użytkownikiem — nie da się delegować | Bezpieczeństwo workflow |
+
+## Deviations from Plan
+
+### Summary
+
+| Type | Count | Impact |
+|------|-------|--------|
+| Scope additions | 1 | Zmiana default z `off` na `auto` — poproszona przez użytkownika |
+
+**Total impact:** Pozytywna zmiana — lepsze UX, delegacja out-of-the-box.
+
+## Issues Encountered
+
+None
+
+## Next Phase Readiness
+
+**Ready:**
+- Framework PAUL wspiera tryb delegated-apply we wszystkich projektach
+- Każdy nowy plan domyślnie używa `delegation: auto`
+- Gotowe do przetestowania na następnej fazie orderPRO
+
+**Concerns:**
+- Wymaga przetestowania w praktyce — pierwszy real-world test na następnej fazie orderPRO pokaże czy mikro-prompty są wystarczająco dobre
+- Sub-agenty mogą potrzebować dostrojenia kontekstu projektu (stack + konwencje)
+
+**Blockers:**
+- None
+
+---
+*Phase: 65-paul-delegated-apply, Plan: 01*
+*Completed: 2026-04-03*