# 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 i warto trzymać 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ępnej kolejności.
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/<repo>/`.

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/<repo>/`
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/<repo>
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 mieszkają w dwóch miejscach i jest to zamierzone.

**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. Warstwa ta jest śledzona w historii gita bazy,
tak jak każda inna wiedza.

**Per repozytorium — `src/<repo>/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 <co chcesz zbudować>` | Propozycja, delta specyfikacji, projekt i zadania zapisane jako Markdown w `openspec/changes/<id>/` |
| Przegląd | `openspec show <id>`, `openspec validate <id>` | 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 <id>` | 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.

Proponuje, a nie robi tego automatycznie, i jest to celowe. 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 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.*

Żadna z tych rzeczy nie jest naprawiana 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/<repo> && openspec init` |
| Zmapować repozytorium do wiki | „zmapuj `src/<repo>`” |
| Napisać przekrojową specyfikację | „napisz przekrojową specyfikację dla X” |
| Zaproponować zmianę w repozytorium | `/opsx:propose <co>` |
| 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](wiki/decisions/0001-opt-in-file-based-kb-modules.md),
  [D-0002](wiki/decisions/0002-software-module-design.md)

---

*Udostępniane na licencji Apache License 2.0 — zobacz [LICENSE](LICENSE).*