# OpenSpec w tej bazie wiedzy *Read this in: [English](OPENSPEC.md) | **Polski*** Jak dodać [OpenSpec](https://openspec.dev) do Cascade KB, które dokumentuje tworzone przez Ciebie oprogramowanie, i jak to współgra z wiki. To przewodnik dla człowieka. Zasady dla samego agenta są w module `software` — [.agents/modules/software/](../.agents/modules/software/README.md) — który musi być zainstalowany, zanim cokolwiek z poniższych zacznie obowiązywać. Powiedz: **„zainstaluj moduł software”**. --- ## Spis treści 1. [Po co tu OpenSpec](#1-po-co-tu-openspec) 2. [Przeczytaj to, zanim uruchomisz `openspec init`](#2-przeczytaj-to-zanim-uruchomisz-openspec-init) 3. [Instalacja](#3-instalacja) 4. [Dwa poziomy specyfikacji](#4-dwa-poziomy-specyfikacji) 5. [Codzienna praca](#5-codzienna-praca) 6. [Jak specyfikacje trafiają do wiki](#6-jak-specyfikacje-trafiają-do-wiki) 7. [Pilnowanie spójności poziomów](#7-pilnowanie-spójności-poziomów) 8. [Szybki przegląd](#8-szybki-przegląd) --- ## 1. Po co tu OpenSpec Wiki zapisuje o oprogramowaniu trzy różne rzeczy. Trzymaj je osobno: | Pytanie | Gdzie mieszka | Kto zapisuje | |---|---|---| | Czym *jest* kod? | `wiki/entities/` — strony `repository` i `component` | `ckb-code-map` | | Co *powinien* robić? | `openspec/specs/` | `ckb-spec` + OpenSpec | | Co *wybraliśmy* i dlaczego? | `wiki/decisions/` | `ckb-decide` | OpenSpec odpowiada za środkowy wiersz: specyfikacja opisuje obowiązujący kontrakt, a propozycja zmiany — co ma stać się prawdą w następnym kroku. Piszesz specyfikację przed kodem, agent implementuje pod nią, a zarchiwizowana zmiana staje się częścią trwałego zapisu. Jeśli coś nie ogranicza przyszłego zachowania, to nie jest specyfikacja, tylko decyzja. Powiedz wtedy „zapisz decyzję”. ## 2. Przeczytaj to, zanim uruchomisz `openspec init` **Nigdy nie uruchamiaj `openspec init` w katalogu głównym bazy wiedzy.** Uruchamiaj go w `src//`. To nie jest ostrożność na wszelki wypadek. `openspec init` zapisuje pliki integracji z narzędziami w `.claude/skills/` oraz dodaje bloki znacznikowe do `AGENTS.md` / `CLAUDE.md`. W tym repozytorium oba te miejsca są nośne: - `.claude/skills` to **dowiązanie symboliczne** do `.agents/skills`. Cokolwiek OpenSpec tam zapisze, ląduje w zestawie skilli Twojej bazy wiedzy. - `CLAUDE.md` to **dowiązanie symboliczne** do `AGENTS.md` — systemowego prompta bazy. To jeden i ten sam plik, więc blok zapisany „do obu” zapisuje się dwukrotnie w to samo miejsce. Uruchomienie w katalogu głównym wmiesza instrukcje OpenSpec dla pojedynczego repozytorium w reguły rządzące całą bazą wiedzy. Uruchomienie w `src//` zostawia wszystko na swoim miejscu: repozytorium dostaje własne `.claude/`, własny `AGENTS.md`, a jego specyfikacje podróżują razem z kodem. Katalog `openspec/` w korzeniu bazy **nie jest** instalacją OpenSpec (§4), więc nigdy nie wymaga `init`. ## 3. Instalacja Wymaga **Node.js 20.19.0 lub nowszego**. ```bash npm install -g @fission-ai/openspec@latest # albo pnpm / yarn / bun openspec --version ``` Następnie, dla każdego repozytorium: ```bash cd src/ openspec init ``` Po późniejszej aktualizacji CLI uruchom w każdym repozytorium `openspec update`, żeby odświeżyć wygenerowane pliki instrukcji. **Odinstalowanie z repozytorium** oznacza ręczne usunięcie katalogu `openspec/`, wygenerowanych plików narzędziowych oraz bloków znacznikowych OpenSpec z `AGENTS.md` / `CLAUDE.md` tego repozytorium — CLI tego za Ciebie nie cofa. ## 4. Dwa poziomy specyfikacji Specyfikacje celowo mieszkają w dwóch miejscach. **Korzeń bazy — `openspec/`** — przekrojowe zdolności obejmujące kilka repozytoriów w `src/`. To *co* i *dlaczego*, którego nie posiada żadne pojedyncze repozytorium. Tą warstwą zarządza skill `ckb-spec`, a **nie** CLI OpenSpec. Nie ma pod nią kodu ani repozytorium, którym miałaby rządzić, więc workflow OpenSpec, skrojony pod repozytorium, tu nie pasuje. Historię tej warstwy, jak każdej innej wiedzy, śledzi git bazy. **Per repozytorium — `src//openspec/`** — jak to repozytorium realizuje te zdolności. To *jak*. Rodzimy przypadek OpenSpec: zarządzany przez CLI i jego własne instrukcje, podróżujący z kodem i biorący udział w pull requestach tego repozytorium. Agent oddaje tu pole OpenSpec i nie podstawia własnego workflow. Jeśli CLI nie jest zainstalowane, powie to wprost, zamiast improwizować. ## 5. Codzienna praca W zainicjalizowanym repozytorium pętla wygląda tak: **propose → apply → archive**. | Krok | Powiedz / uruchom | Co się dzieje | |---|---|---| | Propozycja | `/opsx:propose ` | Propozycja, delta specyfikacji, projekt i zadania zapisane jako Markdown w `openspec/changes//` | | Przegląd | `openspec show `, `openspec validate ` | Czytasz deltę; walidacja sprawdza strukturę oraz zmodyfikowane wymagania wobec specyfikacji, które mają zastąpić | | Wdrożenie | `/opsx:apply` | Agent implementuje pod specyfikację | | Archiwizacja | `/opsx:archive` lub `openspec archive ` | Zmiana scala się z główną specyfikacją i trafia do `changes/archive/` | Przydatne obok: `openspec list`, `openspec status`, `openspec view` (interaktywny pulpit). Dla warstwy w korzeniu bazy nie ma CLI — po prostu powiedz **„napisz przekrojową specyfikację dla X”**, a zajmie się tym `ckb-spec`. ## 6. Jak specyfikacje trafiają do wiki Trzy mostki, wszystkie obsługiwane przez `ckb-spec`. To one sprawiają, że OpenSpec nie staje się równoległym światem obok bazy wiedzy. **Zarchiwizowana zmiana → rekord decyzji.** Wdrożona i zarchiwizowana zmiana to decyzja, którą podjęto i wykonano. Agent *proponuje* zapisanie jej w `wiki/decisions/` — uzasadnienie z propozycji staje się Kontekstem i Uzasadnieniem, delta staje się Decyzją, a odrzucone opcje — Rozważanymi alternatywami. Celowo tylko proponuje. Nie każda rutynowa zmiana zasługuje na trwały, numerowany rekord, a dziennik decyzji zapchany nimi przestaje być wart czytania. **Specyfikacja → strona encji.** Aktualne specyfikacje z korzenia bazy pojawiają się w `wiki/entities/` jako cienkie strony `type: spec`, dzięki czemu na pytania w rodzaju „co to ma robić?” da się odpowiedzieć z indeksu, bez otwierania drzewa specyfikacji. Źródłem prawdy pozostaje plik specyfikacji — strona wiki jest wskaźnikiem, nie kopią. **Poziom → poziom.** Specyfikacje z korzenia i z repozytoriów linkują się nawzajem (§7). ## 7. Pilnowanie spójności poziomów Dwa poziomy specyfikacji to dwa miejsca, w których może mieszkać to samo stwierdzenie — a więc i dwa, w których może się po cichu rozjechać. Zapobiega temu jedna zasada: > Specyfikacja z korzenia wymienia każdą implementującą ją specyfikację > repozytorium w `implemented_by:`. > Specyfikacja repozytorium wskazuje rodzica w `implements:`. > **Zawsze ustawiaj obie strony.** Te odnośniki stają się krawędziami grafu, co zamienia rozjazd w widoczne znalezisko, zamiast w cichy drugi ośrodek prawdy. Powiedz **„zsynchronizuj specyfikacje”** (albo uruchom `lint`), a dostaniesz cztery kontrole: 1. Specyfikacje z korzenia bez implementacji — *opisane, ale nikt tego nie buduje.* 2. Specyfikacje repozytorium, których rodzic zniknął lub trafił do archiwum — *budujesz pod coś, co przestało obowiązywać.* 3. Jednostronne odnośniki, w dowolnym kierunku. 4. Specyfikacje z korzenia starsze niż zmapowany commit każdego repozytorium, które je implementuje — *możliwy rozjazd, wart sprawdzenia.* Agent nie naprawia żadnej z nich automatycznie. Każda jest stwierdzeniem o intencji, a tylko Ty wiesz, która strona ma rację. ## 8. Szybki przegląd | Chcesz | Powiedz / uruchom | |---|---| | Włączyć to wszystko | „zainstaluj moduł software” | | Dodać OpenSpec do repozytorium | `cd src/ && openspec init` | | Zmapować repozytorium do wiki | „zmapuj `src/`” | | Napisać przekrojową specyfikację | „napisz przekrojową specyfikację dla X” | | Zaproponować zmianę w repozytorium | `/opsx:propose ` | | Sprawdzić stan specyfikacji | „zsynchronizuj specyfikacje” | | Zamienić zarchiwizowaną zmianę w decyzję | „zapisz tę zmianę jako decyzję” | **Nigdy:** nie uruchamiaj `openspec init` w korzeniu bazy · nie rób `git add` niczego w `src/` · nie przerabiaj plików OpenSpec repozytorium pod konwencje tej bazy. --- ## Źródła - [Dokumentacja OpenSpec](https://openspec.dev/docs/installation) · [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) · [@fission-ai/openspec na npm](https://www.npmjs.com/package/@fission-ai/openspec) - Rekordy projektowe: [D-0001](decisions/0001-opt-in-file-based-kb-modules.md), [D-0002](decisions/0002-software-module-design.md) --- *Udostępniane na licencji Apache License 2.0 — zobacz [LICENSE](../LICENSE).*