--- name: prepare-openspec-goal description: "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// 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 i chce sformułować warunek zakończenia dla autonomicznej pętli /goal implementującej openspec change." license: Apache-2.0 --- # /prepare-openspec-goal — completion condition dla implementacji OpenSpec change Produkuje gotowy tekst do wklejenia po `/goal ...`, sformatowany pod implementację konkretnego OpenSpec change (`openspec/changes//`). 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 /prepare-openspec-goal → poproś usera o nazwę changu (lista z openspec/changes/) ``` ## Co to jest /goal (kontekst, skrót z docs) `/goal ` — 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//`, żeby ewaluator widział o czym mowa i Claude miał konkretny scope. 2. **End state** — wszystkie taski w `tasks.md` mają `- [x]`, `openspec validate --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//tasks.md` pokazujący `0` - output `openspec validate --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//` 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//` 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//tasks.md` i `grep -c "^- \[ \]" openspec/changes//tasks.md` → liczba tasków - Czy istnieje `openspec/changes//design.md` → sygnał complexity - Czy istnieje `openspec/changes//specs/` z deltami → ile spec capabilities ruszamy - `head -20 proposal.md` → jakiego rzędu zmiana (UI refactor / DB migration / new feature) - **`grep "^## " openspec/changes//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 to drive the implementation, then continue until: `. 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//: ...`. Zob. „Edge case: finishing leftovers" niżej. Format wyjścia (zawsze ten sam): ```` ``` /goal ``` **Change:** openspec/changes// ( tasków, design.md: yes/no) **Co ewaluator sprawdza w transkrypcie:** <2-3 zdania konkretnie jakie outputy muszą wpaść> **Bound:** **Sugerowana sekwencja (jeśli stosowne):** ```` ### 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 ` 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//` 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.