goal-loop

Skill do Claude Code, który zamienia zadanie w gotowy do wklejenia prompt /goal (albo /loop) — z weryfikowalnym warunkiem końca, twardym capem na liczbę tur i escape hatchem, żeby pętla sama się zatrzymała, gdy utknie. Zamiast za każdym razem wyprowadzać teorię pętli od zera, skill trzyma całą mechanikę u siebie i za jednym strzałem produkuje dobry warunek.

Skill nie odpala pętli — pisze prompt i oddaje ci go do zatwierdzenia. Wynik wklejasz sam.

Czym są /goal i /loop

/goal <warunek> (Claude Code ≥ 2.1.139) ustawia warunek ukończenia. Claude sam zaczyna kolejne tury i pracuje do skutku — bez tego, żebyś podpowiadał mu każdy krok. Po każdej turze mały, szybki model (domyślnie Haiku) czyta warunek plus rozmowę i zwraca „tak/nie" z uzasadnieniem: „nie" staje się wskazówką do następnej tury, „tak" kończy pętlę.

Kluczowe: ten ewaluator nie uruchamia komend ani nie czyta plików — ocenia tylko to, co Claude już pokazał w transkrypcie. Dlatego warunek musi być czymś, co własny output Claude'a potrafi udowodnić („npm test wypisuje 0 failed"), a nie czymś nieweryfikowalnym („architektura jest dobra", „aż będzie zadowalająco"). To pojedyncza reguła, na której stoi lub wywraca się cała pętla.

/loop <interwał> <prompt> to inne narzędzie: powtarza prompt co zadany czas (polling/patrol — np. „sprawdzaj CI co 5 minut"). Zatrzymuje się, gdy ty je zatrzymasz albo Claude uzna, że praca skończona. /goal i /loop to alternatywy — wybierasz po tym, co ma zacząć następną turę: poprzednia tura skończona → /goal; tyknięcie zegara → /loop. Oba żrą tokeny autonomicznie, więc skill zawsze dokłada twardy cap i escape hatch. Pełna dokumentacja: https://code.claude.com/docs/en/goal

Dwa warianty: goal-loop i goal-loop-herdr

W repo są dwa skille. Różnią się tym, kto wykonuje pracę.

goal-loop (domyślny, lean) pisze kontrakt dla tej samej sesji Claude'a. Wklejasz wynik jako /goal i Claude sam pracuje do skutku, a wbudowany ewaluator po każdej turze sprawdza warunek w transkrypcie.

goal-loop-herdr (wariant koordynatora) zakłada, że wykonawcą jest zewnętrzny worker — Codex albo opencode — działający w pane Herdr obok. Claude nie pisze wtedy kodu, tylko koordynuje w trzech rolach naraz: dyspozytor (wysyła goal i dopycha frontier), walidator (zatwierdza permission prompty mieszczące się w kontrakcie, resztę eskaluje do ciebie) i monitor (co 5 minut, przez /loop 5m, czyta statusy ticketów i git log).

Kluczowa różnica techniczna: worker nie ma komendy /goal — to funkcja Claude Code. Kontrakt nie może więc żyć w ewaluatorze i mieszka w plikach: goal file z regułami plus tickety z polami Status: i Blocked by: (frontier = najniższy numer bez nierozwiązanych blokerów). Tickety są jednocześnie pamięcią między iteracjami.

Kiedy który:

• małe albo średnie zadanie, jedna sesja, chcesz mieć to z głowy → lean;
• duży nocny drain na kilkanaście ticketów, chcesz oddzielić wykonawcę od nadzoru, chcesz żeby ktoś klikał permission prompty i pilnował zakresu → koordynator;
• nie masz Herdr albo nie siedzisz w jego sesji → lean (skill koordynatora sam to sprawdza i odsyła cię do wariantu lean).

Wymagania wariantu koordynatora (ponad wymagania lean, niżej):

• zainstalowany Herdr, a ta sesja Claude'a działa wewnątrz jego pane (HERDR_ENV=1),
• worker w PATH (codex, opencode, …),
• skill herdr zainstalowany osobno, z projektu Herdr — goal-loop-herdr celowo nie powiela składni komend Herdr, bo autorytetem jest zainstalowana binarka (herdr --help) i składnia zmienia się między wersjami.

Instalacja

Skille to katalogi skills/goal-loop/ i skills/goal-loop-herdr/. Skopiuj ten, którego chcesz używać (albo oba), tam gdzie twój agent szuka skilli:

• Claude Code, globalnie (wszystkie projekty): skopiuj skills/goal-loop/ (i/lub skills/goal-loop-herdr/) do ~/.claude/skills/
• Claude Code, per projekt (jedno repo): skopiuj skills/goal-loop/ (i/lub skills/goal-loop-herdr/) do .claude/skills/ w repozytorium
• Codex (opcjonalnie): skopiuj do .agents/skills/. Uwaga: komendy /goal i /loop istnieją tylko w Claude Code. W Codexie skill nadal napisze ci prompt (jest wyłącznie jego autorem), ale sam wygenerowany blok /goal wklejasz w Claude Code (≥ 2.1.139). W samym Codexie stosuj wzorzec backlog-drain jako pętlę ręczną (plik-backlog + odhaczanie zadań po kolei).

Po skopiowaniu sprawdź, że frontmatter (name + description) jest na miejscu — po tym agent rozpoznaje skill.

Użycie

Wywołaj skill jako /goal-loop albo poproś naturalnie: „napisz mi goal na X", „zrób loop, żeby…". Skill dopyta o brakujące rzeczy (komenda testów, warunek końca), a potem odda ci gotowy blok do wklejenia.

Nazwa — ważne. Skill wywołujesz jako /goal-loop. /goal to wbudowana komenda Claude Code, w którą wklejasz WYNIK skilla. Nie myl ich: /goal-loop pisze prompt, /goal go uruchamia.

Przykład 1 — zadanie jednopętlowe

Ty:

/goal-loop rozbij src/lib/foo.ts na moduły, każdy poniżej 200 linii

Skill oddaje:

/goal Refactor src/lib/foo.ts into focused modules, each under 200 lines. Done
when: `npm test` shows 0 failed AND `wc -l src/lib/foo*.ts` shows every file
≤ 200 lines, both printed in the transcript, with no other test file modified.
Run the test + wc and show output every turn. Stop after 15 turns, or if the
same failure repeats 3 turns in a row — then report and stop.

…plus jedna linijka: co dokładnie ewaluator przeczyta, żeby potwierdzić „done".

Przykład 2 — duże zadanie (backlog + drain-goal)

Ty:

/goal-loop dowieź cały feature „batch export" — mam trzy PRD-y w notes/

Skill najpierw ocenia rozmiar (wiele slice'ów / wiele PRD-ów → zadanie duże), więc zamiast jednego mega-warunku najpierw zakłada plik-backlog jako pamięć między iteracjami:

# Backlog: batch-export   (PRD = źródło prawdy; każde zadanie zostawia repo zielone)
- [ ] L1-S1 CSV writer — PRD notes/batch-export-io.md slice 1 — done: `npm test -- io` = 0 failed
- [ ] L1-S2 ZIP bundling — PRD notes/batch-export-io.md slice 2 — done: `npm test -- zip` = 0 failed
- [ ] L2-S1 Export UI button — PRD notes/batch-export-ui.md slice 1 — done: `npm run build` exit 0

…a potem pisze jeden „chudy" drain-goal, który go opróżnia:

/goal Work through notes/batch-export-backlog.md top to bottom. For each `[ ]`:
read the named PRD, implement test-first, check it off as `[x]` with proof (the
`done` command's output in the transcript), commit per task. One-line report
after each; stop at the L1→L2 boundary and ask. DONE when all `[x]` AND
`npm test` = 0 failed AND `npm run build` exits 0, all shown in the transcript.
No paid calls; no push; commit per task on the feature branch. Stop after 20
turns or if the same task blocks 3 turns in a row.

Gdyby któregoś PRD brakowało, skill NIE zgaduje architektury — mówi ci, żebyś najpierw spisał PRD (backlog jest tak dobry, jak PRD-y, które go karmią) i podpowiada, co powinno się w nim znaleźć.

Koszt — przeczytaj, zanim odpalisz

Pętle pracują autonomicznie i żrą tokeny aż do osiągnięcia celu — od kilkunastu minut do godzin (a bez capa nawet dni). Dlatego skill zawsze dokłada twardy cap (stop after N turns) i escape hatch. Sweet spot to ~35 minut do ~2 godzin; dłuższe przebiegi rzadko się opłacają. Zawsze pilnuj budżetu.

Wymagania

• Claude Code ≥ 2.1.139 (komenda /goal)
• Zaakceptowany trust dialog w workspace (ewaluator działa jako hook)
• Bez disableAllHooks (ani allowManagedHooksOnly w managed settings) — inaczej /goal jest niedostępny
• dla goal-loop-herdr dodatkowo: Herdr + sesja uruchomiona w jego pane (HERDR_ENV=1), worker (codex / opencode) w PATH i osobno zainstalowany skill herdr

Licencja

MIT — patrz LICENSE.