13 KiB
13 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous
| phase | plan | type | wave | depends_on | files_modified | autonomous | ||||
|---|---|---|---|---|---|---|---|---|---|---|
| 65-paul-delegated-apply | 01 | execute | 1 |
|
false |
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
- Zmodyfikowany
apply-phase.mdz trybem delegowanym - Nowy reference
delegated-apply.mdz pełną specyfikacją wzorca - Zaktualizowany
subagent-criteria.mdo kontekst PAUL delegacji - Zaktualizowany template
PLAN.mdo poledelegation
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
<acceptance_criteria>
AC-1: Tryb delegowany aktywuje się automatycznie lub ręcznie
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
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ę
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
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
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>
Task 1: Utworzenie reference delegated-apply.md ~/.claude/paul-framework/references/delegated-apply.md 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** |
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.
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)"
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)
<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>