/prepare-openspec-goal — completion condition dla implementacji OpenSpec change

Produkuje gotowy tekst do wklejenia po /goal ..., sformatowany pod implementację konkretnego OpenSpec change (openspec/changes/<name>/). Ewaluator (mały model) nie uruchamia narzędzi — ocenia tylko to, co Claude wkleił do rozmowy, więc condition musi wymuszać pokazywanie weryfikowalnych dowodów w wiadomościach.

Invocation

/prepare-openspec-goal <change-name>
/prepare-openspec-goal                 → poproś usera o nazwę changu (lista z openspec/changes/)

Co to jest /goal (kontekst, skrót z docs)

/goal <condition> — autonomiczna pętla: po każdej turze Haiku sprawdza condition vs transkrypt. Brak spełnienia → kolejna tura. Spełnione → goal clear. Limit 4000 znaków. Działa w trybie headless: claude -p "/goal ...".

Pełna dokumentacja: https://code.claude.com/docs/en/goal

Anatomia goalu dla OpenSpec change (5 elementów)

1. Identyfikacja changu — pełna ścieżka openspec/changes/<name>/, żeby ewaluator widział o czym mowa i Claude miał konkretny scope.
2. End state — wszystkie taski w tasks.md mają - [x], openspec validate <name> --strict exit 0, pnpm typecheck + pnpm lint exit 0. Liczbowo: 0 unchecked items.
3. Proof in transcript — Claude w ostatniej wiadomości wkleja:
   • output grep -c "^- \[ \]" openspec/changes/<name>/tasks.md pokazujący 0
   • output openspec validate <name> --strict z valid / exit 0
   • output pnpm typecheck z exit 0
   • listę zmienionych plików (git diff --name-only main...HEAD) i potwierdzenie że wszystkie mieszczą się w scope changu (nie ruszone obce featury)
4. Constraints — nie ruszamy plików spoza scope changu (poza openspec/changes/<name>/ i plików wymienionych w tasks.md / specs/ deltas); inne testy w repo nadal przechodzą; nie modyfikujemy archived changes ani innych aktywnych changes.
5. Turn/time bound — or stop after N turns. Default:
   • small change (≤10 tasków, brak design.md): 20 tur
   • medium (10–25 tasków, jest design.md): 40 tur
   • large (>25 tasków, wiele plików): 60 tur + zasugeruj rozbicie na sekwencję

Workflow

Krok 1: Sparsuj nazwę changu

Sprawdź czy openspec/changes/<name>/ istnieje. Jeśli nie — zaproponuj ls openspec/changes/ i poproś o wybór. Jeśli user nie podał nazwy — zrób listing i zapytaj.

Krok 2: Quick audit changu (decyduje o bound i rozbiciu)

Sprawdź:

• wc -l openspec/changes/<name>/tasks.md i grep -c "^- \[ \]" openspec/changes/<name>/tasks.md → liczba tasków
• Czy istnieje openspec/changes/<name>/design.md → sygnał complexity
• Czy istnieje openspec/changes/<name>/specs/ z deltami → ile spec capabilities ruszamy
• head -20 proposal.md → jakiego rzędu zmiana (UI refactor / DB migration / new feature)
• grep "^## " openspec/changes/<name>/tasks.md → lista sekcji H2 (potrzebne do kroku 2a)

Sygnały do rozbicia na sekwencję /goal A → /goal B:

• 40 unchecked tasków

• design.md wymienia wiele etapów (np. "Phase 1 / Phase 2")
• tasks.md ma top-level sekcje, które dało się robić niezależnie (refactor + migracja + testy)

W razie wątpliwości — zaproponuj rozbicie sekwencyjne po sekcjach H2 w tasks.md.

Krok 2a: Wykryj sekcje nieweryfikowalne z transkryptu (OBOWIĄZKOWE)

Z listy sekcji H2 oznacz jako nieweryfikowalne każdą zawierającą (case-insensitive) któreś ze słów-kluczy:

manual, manualny, manualnie, devtools, wizualnie, visual, QA, smoke test, smoke audyt, weryfikacja przed mergem, merge, pre-merge, changelog, release notes, screenshot, responsywność (gdy w kontekście otwierania w przeglądarce)

Reguła: wyklucz te sekcje z goala. Ewaluator (Haiku) nie umie ocenić z transkryptu „wygląda dobrze na 768×600", „PR description napisane", „smoke test na devie zielony" — Claude może to tylko gołosłownie zadeklarować, co psuje całą pętlę.

Wymień te sekcje userowi jawnie pod blokiem /goal jako do-it-yourself po zakończeniu pętli. Jeśli wszystkie sekcje są nieweryfikowalne (np. change typu „manual QA round") — powiedz userowi że /goal nie jest właściwym narzędziem; lepszy /loop z manualnym potwierdzeniem albo zwykły review.

Krok 3: Wygeneruj output

Default: condition zawsze zaczyna się od start by invoking /opsx:apply <name> to drive the implementation, then continue until: <proof template>.

Powód: /goal standalone bez /opsx:apply na świeży OpenSpec change traci całą wiedzę domenową skilla /opsx:apply (konwencje update'u specs/ deltas, kolejność czytania artifacts, patterns zaznaczania tasków). Bez tego dostajesz gorszy /opsx:apply z narzutem pasting evidence w każdej turze.

Edge case bez /opsx:apply: TYLKO gdy user jawnie mówi „dokończ resztki" — wcześniej odpalał /opsx:apply interaktywnie, urwał na limicie kontekstu, część tasków zaznaczona. Wtedy condition zaczyna się od continue implementing remaining unchecked tasks of openspec/changes/<name>/: .... Zob. „Edge case: finishing leftovers" niżej.

Format wyjścia (zawsze ten sam):

```
/goal <condition tekst>
```

**Change:** openspec/changes/<name>/ (<N> tasków, design.md: yes/no)
**Co ewaluator sprawdza w transkrypcie:** <2-3 zdania konkretnie jakie outputy muszą wpaść>
**Bound:** <N tur — uzasadnienie z auditu>
**Sugerowana sekwencja (jeśli stosowne):** <opis rozbicia>

Krok 4: Wskaż jak odpalić

Po bloku komendy dorzuć jednolinijkową podpowiedź:

• interaktywnie: wklej do Claude Code w tym repo
• headless: claude -p "/goal ..." (przyda się przy długich tureach w tle)

Zalecenie: jeśli change jest świeży (tasks.md w pełni - [ ]), zasugeruj odpalić goal po uruchomieniu /opsx:apply <name> albo zaszyć invocation w samym condition (zob. przykład 2).

Przykład 1 — mały change UI

User: /prepare-openspec-goal fix-modal-responsiveness

Audit: 18 tasków, 4 niezaznaczone sekcje (Primitive / Refactor x2 / Audit), jest design.md, zasięg: packages/ui/src/shadcn/dialog.tsx + 4-6 plików w apps/web/.../photo-shoot/_components/.

Output:

/goal start by invoking /opsx:apply fix-modal-responsiveness to drive the implementation, then continue until: every checkbox in openspec/changes/fix-modal-responsiveness/tasks.md is marked [x] (you prove this by pasting the output of `grep -c "^- \[ \]" openspec/changes/fix-modal-responsiveness/tasks.md` showing 0 in your final message); `openspec validate fix-modal-responsiveness --strict` exits 0 and you paste the final lines of its output; `pnpm --filter web typecheck` exits 0 and you paste the last 5 lines; `pnpm --filter web lint` exits 0 and you paste the last 5 lines; the diff stays within scope — you paste `git diff --name-only main...HEAD` and the only paths touched are openspec/changes/fix-modal-responsiveness/**, packages/ui/src/shadcn/dialog.tsx, and files under apps/web/app/home/[account]/content-generation/photo-shoot/_components/ (no archived openspec changes, no other active changes, no unrelated features modified); or stop after 30 turns

Change: openspec/changes/fix-modal-responsiveness/ (18 tasków, design.md: yes) Co ewaluator sprawdza: ostatnia wiadomość Claude'a musi zawierać 4 outputy komend (grep tasków = 0, openspec validate, typecheck, lint) + listę zmienionych plików zawężoną do dialog primitive i photo-shoot components. Bound: 30 tur — medium change, design.md jest ale tasks są krótkie i mechaniczne.

Headless

claude -p "/goal implement openspec change at openspec/changes/fix-modal-responsiveness/: ..."

Przykład 2 — edge case: finishing leftovers (BEZ /opsx:apply)

Scenariusz: user wcześniej odpalił /opsx:apply add-failed-jobs-retry interaktywnie, zrobił ~70% tasków, urwał (limit kontekstu / koniec dnia). Teraz chce autonomiczne dokończenie reszty. Tu /opsx:apply w pierwszej turze nie ma sensu — zacząłby od początku.

/goal continue implementing remaining unchecked tasks of openspec/changes/add-failed-jobs-retry/ (tasks.md already has partial progress — pick up from first `- [ ]` and continue) until: every checkbox in openspec/changes/add-failed-jobs-retry/tasks.md is [x] (prove by pasting `grep -c "^- \[ \]" openspec/changes/add-failed-jobs-retry/tasks.md` = 0); `openspec validate add-failed-jobs-retry --strict` exits 0 (paste output); `pnpm --filter web typecheck` exits 0 (paste tail); diff stays within openspec/changes/add-failed-jobs-retry/** plus files listed in the change's tasks.md (paste `git diff --name-only main...HEAD`); or stop after 25 turns

Kiedy ten wariant: TYLKO gdy user jawnie powie „dokończ resztki" / „pick up where I left off" / „pozostałe taski". W każdym innym przypadku — default z /opsx:apply w pierwszej turze.

Przykład 2a — change z manual QA / merge ritual sekcjami

User: /prepare-openspec-goal fix-modal-responsiveness

Audit: 37 unchecked, 0 checked, 8 sekcji H2, design.md: yes. Sekcje: 1. Primitive / 2. Refactor Configure Photo Shoot / 3. Refactor uploader / 4. Audyt sąsiednich modali / 5. Smoke audyt poza content-generation / 6. Manualny test responsywności / 7. Docs i konwencja / 8. Weryfikacja przed mergem.

Krok 2a: sekcja 6 (słowo Manualny) i sekcja 8 (Weryfikacja przed mergem, merge) → nieweryfikowalne, wyłącz z goala. Sekcja 5 (Smoke audyt) — w tasks opisana jako otwarcie modali w devtools → też wyłącz.

Mechaniczne sekcje do pętli: 1, 2, 3, 4, 7.

Output:

/goal start by invoking /opsx:apply fix-modal-responsiveness to drive the implementation, focusing only on sections 1, 2, 3, 4, 7 of tasks.md (skip sections 5, 6, 8 — those are manual QA / merge ritual handled outside this loop), then continue until: every `- [ ]` under headings "## 1.", "## 2.", "## 3.", "## 4.", "## 7." in openspec/changes/fix-modal-responsiveness/tasks.md is now `- [x]` (prove this by pasting the output of `awk '/^## (1|2|3|4|7)\./{p=1} /^## (5|6|8)\./{p=0} p' openspec/changes/fix-modal-responsiveness/tasks.md | grep -c "^- \[ \]"` showing 0 in your final message); `openspec validate fix-modal-responsiveness --strict` exits 0 and you paste the final lines; `pnpm --filter web typecheck` exits 0 and you paste the last 5 lines; `pnpm --filter web lint` exits 0 and you paste the last 5 lines; you paste `git diff --name-only main...HEAD` and the only paths touched are openspec/changes/fix-modal-responsiveness/**, packages/ui/src/shadcn/dialog.tsx, and files under apps/web/app/home/[account]/content-generation/photo-shoot/_components/ (no archived openspec changes, no other active changes, no unrelated features modified); or stop after 40 turns

Change: openspec/changes/fix-modal-responsiveness/ (37 tasków, design.md: yes) Mechaniczne sekcje w pętli: 1, 2, 3, 4, 7 Nieweryfikowalne — zrób ręcznie po /goal: sekcja 5 (smoke audyt w devtools), sekcja 6 (manualny test responsywności w 4 rozdzielczościach), sekcja 8 (merge checklist + changelog entry — zob. CLAUDE.md Changelog Process). Co ewaluator sprawdza: awk-filtered grep tasków = 0 dla {1,2,3,4,7}, validate, typecheck, lint, git diff zawężony do dialog + photo-shoot. Bound: 40 tur — mechaniczne taski (zamiana klas), 5 sekcji × średnio 4 taski.

Awk pattern — filtrowanie tasks.md po sekcjach

Wybrane sekcje (include): awk '/^## (1|2|3|4|7)\./{p=1} /^## (5|6|8)\./{p=0} p' tasks.md

Wzór:

• /^## (A|B|C)\./{p=1} — przy nagłówku z numerów do włączenia podnieś flag
• /^## (X|Y|Z)\./{p=0} — przy nagłówku z numerów do wyłączenia opuść flag
• p — drukuj linie gdy flag = 1

Wszystkie numery sekcji (1–8) muszą wpaść do jednego z dwóch wzorców, inaczej awk przestanie filtrować na końcu zakresu.

Przykład 3 — large change → sekwencja

User: /prepare-openspec-goal e2e-test-expansion

Audit: 60+ tasków, sekcje H2 podzielone na: setup fixtures / billing flows / team flows / admin flows / CI integration. Każda sekcja > 10 tasków.

Output (zamiast jednego /goal):

# Sekwencja 4 goali — każda sekcja osobno

# 1) setup fixtures
/goal start by invoking /opsx:apply e2e-test-expansion focusing only on section "## 1." of tasks.md, then continue until: every `- [ ]` under heading "## 1." is now `- [x]` (paste `awk '/^## 1\./,/^## 2\./' openspec/changes/e2e-test-expansion/tasks.md | grep -c "^- \[ \]"` = 0); `pnpm --filter web-e2e exec playwright test --list` exits 0 (paste tail); diff touches only apps/e2e/** and openspec/changes/e2e-test-expansion/**; or stop after 25 turns

# 2) billing flows  (odpal po zaliczeniu #1)
/goal ... (analogicznie dla sekcji 2.)

# 3) team flows
/goal ...

# 4) finalize: validate + typecheck + lint full
/goal openspec validate e2e-test-expansion --strict exits 0 (paste output); pnpm typecheck exits 0 (paste tail); pnpm lint exits 0 (paste tail); `grep -c "^- \[ \]" openspec/changes/e2e-test-expansion/tasks.md` = 0 (paste output); or stop after 15 turns

Dlaczego sekwencja: 60 tasków w jednym goalu = wysoka szansa na zgubienie wątku przez evaluatora i przekroczenie bound. Mniejsze cele = krótsze konteksty + łatwiejsze sprawdzanie.

Anti-wzorce specyficzne dla OpenSpec

• ❌ /goal bez /opsx:apply w pierwszej turze na świeży change — tracisz domain knowledge skilla apply (konwencje update'u specs/, kolejność czytania artifacts). Wyjątek: scenariusz „finishing leftovers" (zob. Przykład 2).
• ❌ "all tasks done" bez wymuszenia grep -c "^- \[ \]" = 0 — ewaluator nie widzi tasks.md
• ❌ pominięcie openspec validate --strict — change z brakującymi spec deltami przejdzie "all checked" ale nie jest gotowy do archive
• ❌ brak git diff --name-only w proof — Claude może niechcący ruszyć inne pliki (typowo: apps/e2e/.env, package.json lockfile) i nikt tego nie wyłapie
• ❌ doklejanie do goala "and run /opsx:archive" — archive ma osobny ritual (changelog, commit message, walidacja), nie pakuj tego w pętlę autonomiczną
• ❌ Condition > 4000 znaków — przy dużych changes łatwo przekroczyć; wtedy sekwencja

Edge cases

• Change ma już część tasków zaznaczonych: condition zostaje ten sam (grep = 0), evaluator policzy tylko niezaznaczone. Wspomnij to userowi w wyjaśnieniu.
• Change tylko docs/spec (brak kodu): pomiń pnpm typecheck/lint z proof — zostaw openspec validate --strict + grep tasks = 0. Bound: 10 tur.
• Change wymaga migracji DB: dorzuć do proof pnpm --filter web supabase migrations up exit 0 i pnpm supabase:web:typegen exit 0 (paste tail).
• Change w worktree: w condition użyj ścieżki openspec/changes/<name>/ tak samo — worktree dzieli openspec/ z main checkoutem (sprawdź git status przed goalem).
• Brak design.md, ale tasks.md > 30: poproś usera o decyzję — sekwencja czy mimo wszystko jeden goal z bound 50 tur.

Format odpowiedzi (zawsze ten sam)

1. (Opcjonalnie) jedno pytanie jeśli nazwa changu nieznana / change nie istnieje
2. Quick audit changu (2-3 linijki: liczba tasków, design.md y/n, scope plików z proposal.md)
3. Lista sekcji H2 z oznaczeniem które są mechaniczne (w goalu) a które nieweryfikowalne (DIY)
4. Blok z gotową komendą /goal ... (z awk-filtrem jeśli wykluczamy sekcje)
5. 4 linijki: change ID + mechaniczne sekcje + DIY sekcje + co ewaluator sprawdza + bound
6. (Jeśli stosowne) propozycja rozbicia na sekwencję
7. Jednolinijkowa podpowiedź headless

Bez długich wstępów. Bez powtarzania proposal.md.

Routing text before the description was cut

The description in the front matter is capped at 250 characters, because the list of skills a model sees has a character budget. The full routing text it carried before — triggers, boundaries, what the skill is not for — is kept here:

Przygotowuje gotowy tekst completion condition dla komendy /goal w Claude Code (v2.1.139+), dostosowany do implementacji OpenSpec change. Bierze nazwę changu z openspec/changes/<name>/ i produkuje sformułowanie, które ewaluator (mały model, Haiku) potrafi sprawdzić z samego transkryptu rozmowy. Triggeruje WYŁĄCZNIE na komendę /prepare-openspec-goal — nie auto-triggeruj na keywords typu 'goal', 'openspec', 'change'. Używaj gdy user pisze /prepare-openspec-goal <change-name> i chce sformułować warunek zakończenia dla autonomicznej pętli /goal implementującej openspec change.