303 lines
13 KiB
Markdown
303 lines
13 KiB
Markdown
---
|
|
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>
|