# Moduł `software` *Read this in: [English](README.md) | **Polski*** Opcjonalny. Instalacja: „install the software module”; usunięcie: „uninstall the software module”. Dopóki moduł nie jest zainstalowany, nic tutaj nie działa. Poniższe skille leżą w tym folderze, a nie w `.agents/skills/`, po to, żeby ich opisy nie zajmowały kontekstu w bazach, które nie dokumentują oprogramowania. ## Co zakłada Tworzysz oprogramowanie, a ta baza przechowuje wiedzę *o* nim. Sam kod leży w `src//` jako zwykłe klony: **ignorowane przez git**, każdy z własnym zdalnym repozytorium i własną historią. Jedna baza może ich mieć kilka. Kod nie jest częścią historii bazy i może go w ogóle nie być w świeżym klonie. To celowe i dlatego moduł zapisuje dla każdego repozytorium stronę encji `type: repository`: adres zdalnego repozytorium, domyślna gałąź, język, polecenie budowania, ścieżka, właściciel. **Trwałym zapisem jest ta strona; klon to tylko wygoda.** ## Co dodaje | Skill | Co robi | |---|---| | `ckb-code-map` | Czyta klon `src/` i zapisuje go w `wiki/entities/` jako stronę repozytorium oraz strony komponentów, oznaczone commitem, z którego powstały, żeby dało się wykryć ich nieaktualność. | | `ckb-spec` | Zarządza specyfikacjami na poziomie bazy, specyfikacje poszczególnych repozytoriów zostawia OpenSpec i łączy oba poziomy z `wiki/`: zarchiwizowane zmiany stają się rekordami decyzji, bieżące specyfikacje stronami `type: spec`. | Do tego: szkielet `src/` i `openspec/`, blok routingu w `AGENTS.md`, reguły `.gitignore` dla `src/*` oraz typy `repository`/`component`/`spec`. Te skille zapisują czasowniki grafu z bazowego słownika w `wiki/graph/index.md`: `ckb-code-map` zapisuje `part_of`, `depends_on` i `owns`, a `ckb-spec` — `implements`. Moduł nie wprowadza nowych czasowników. ## Dwa poziomy specyfikacji Specyfikacje istnieją na **obu** poziomach i właśnie o ten podział chodzi: - **`openspec/` w katalogu głównym bazy**: co i dlaczego, ponad repozytoriami. Kontrakty przekrojowe, których nie posiada żadne pojedyncze repozytorium. Obsługuje je bezpośrednio `ckb-spec`, bo `openspec/` w katalogu głównym nie jest zwykłą instalacją OpenSpec: nie ma pod nim kodu. - **`src//openspec/`**: jak to repozytorium to realizuje. Naturalny przypadek OpenSpec: podróżuje razem z kodem i trafia do PR-ów samego repozytorium. Obsługują go instrukcje samego OpenSpec; `ckb-spec` się im podporządkowuje i mówi wprost, gdy CLI nie jest zainstalowane, zamiast improwizować zastępstwo. Poziomy łączą pola frontmatter `implements:` / `implemented_by:`, które stają się krawędziami grafu. Dzięki temu dwa poziomy specyfikacji, które się rozjadą, dają **sygnał w lincie** zamiast dwóch po cichu rozbieżnych prawd. Specyfikacja na poziomie bazy bez implementacji albo specyfikacja repozytorium, której rodzic został zarchiwizowany, to znalezisko. ## Czego nie robi - **`src/` nie jest warstwą kaskady.** To materiał dowodowy, jak `raw/archive/`. `ckb-retrieve` może otworzyć kod i zacytować go, żeby zweryfikować twierdzenie; nigdy nie odpowiada nim na pytanie „czym jest encja X”, a `ckb-ingest` nie traktuje kodu jako materiału do skrzynki. Bez tej reguły każdy ingest zamieniałby twój kod w strony wiki. - **Nie commituje ani nie wypycha repozytoriów z `src/`.** To osobne repozytoria z osobnymi zdalnymi. `ckb-sync-changes` nigdy nie wykonuje `git add` w `src/`. ## Konfiguracja OpenSpec Zobacz [docs/OPENSPEC.pl.md](../../../docs/OPENSPEC.pl.md) ([English](../../../docs/OPENSPEC.md)): instalacja, codzienna pętla propose → apply → archive i powód, dla którego `openspec init` nigdy nie może być uruchomione w katalogu głównym bazy. ## Zapis decyzji projektowych - [D-0001](../../../docs/decisions/0001-opt-in-file-based-kb-modules.md): dlaczego moduły są plikami w repozytorium. - [D-0002](../../../docs/decisions/0002-software-module-design.md): dlaczego ignorowane klony, oba poziomy specyfikacji i hybrydowe vendorowanie. Rekordy decyzji są po angielsku. --- *Udostępniane na licencji Apache License 2.0 — zobacz [LICENSE](../../../LICENSE).*