ckb/.agents/modules/software/README.pl.md
Michał Kopeć bbfda5a65d Sync: local changes as of 2026-10-29T13:50:12Z
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-29 14:50:12 +01:00

83 lines
4.2 KiB
Markdown

# 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/<repo>/` 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/<repo>` 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/<repo>/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).*