From b6f7b841f480d7f0643fecc46aa1ce588585dcc7 Mon Sep 17 00:00:00 2001 From: Krzysztof Polak Date: Mon, 18 May 2026 09:49:32 +0200 Subject: [PATCH 1/3] chore: add module documentation standard specification --- ...026-05-18-module-documentation-standard.md | 328 ++++++++++++++++++ 1 file changed, 328 insertions(+) create mode 100644 .ai/specs/SPEC-005-2026-05-18-module-documentation-standard.md diff --git a/.ai/specs/SPEC-005-2026-05-18-module-documentation-standard.md b/.ai/specs/SPEC-005-2026-05-18-module-documentation-standard.md new file mode 100644 index 0000000..3f9f578 --- /dev/null +++ b/.ai/specs/SPEC-005-2026-05-18-module-documentation-standard.md @@ -0,0 +1,328 @@ +# SPEC-005: Module Documentation Standard + +## TLDR + +**Key Points:** +- Dokumentacja jest trójpoziomowa: repo root README (tabelka modułów) → `packages//README.md` (skrócona dokumentacja modułu) → `packages//docs/*.md` (rozszerzona dokumentacja podzielona na pliki). +- `packages//README.md` zawiera prawdziwą treść (nie tylko nawigację) — krótkie omówienie modułu, quick start, screenshoty, linki do rozszerzonej docs. +- Wzorcem jest `packages/pdf-generators` — jego `docs/README.md` zostanie rozbity na osobne pliki zgodnie z tym standardem. +- CI blokuje PR jeśli wymagane pliki nie istnieją. + +**Scope:** +- Trójpoziomowa hierarchia README: repo → pakiet → docs/ +- Standard treści `packages//README.md` (skrócona dokumentacja) +- Wymagane pliki w `docs/` (rozszerzona dokumentacja) +- GitHub Actions walidacja — blokuje merge gdy brak wymaganych plików + +**Concerns:** +- `carrier-inpost` nie ma żadnej dokumentacji — wymaga dopisania od zera +- Podwójny SPEC-004 w `.ai/specs/` — poza scope tej specyfikacji + +--- + +## Overview + +Każdy moduł w `offical-modules` jest zewnętrznym rozszerzeniem instalowanym przez deweloperów budujących aplikacje na Open Mercato. Jakość dokumentacji bezpośrednio przekłada się na adoption — moduł bez README to moduł, którego nikt nie zainstaluje bez zaglądania w kod. + +Specyfikacja definiuje **wymagany minimalny zestaw dokumentacji** dla każdego pakietu oraz **strukturę katalogową** tak, aby autorzy wiedzieli dokładnie co napisać, a recenzenci i CI wiedzieli co sprawdzić przed mergem. + +> **Market Reference**: Wzorowano się na podejściu stosowanym przez Shopify Polaris, Medusa.js i shadcn/ui — każdy z tych projektów posiada spójną strukturę per-pakiet z dokumentacją podzieloną na tematyczne pliki (installation, api, contributing). Odrzucono model monolitycznych wiki (Confluence, Notion) jako nietrwały i oderwany od kodu. Odrzucono też model jednego dużego README.md — przy modułach tej złożoności co pdf-generators szybko staje się nieczytelny. + +## Problem Statement + +Aktualny stan repozytorium: + +| Pakiet | Root README | docs/ | Stan | +|--------|-------------|-------|------| +| `pdf-generators` | brak | `docs/README.md` (monoplik) | Częściowy — brak root README, brak podziału na pliki | +| `carrier-inpost` | brak | brak | Brak dokumentacji | +| `test-package` | brak | brak | Placeholder — wyłączony ze scope | + +Brak standardu powoduje: +1. **npm pokazuje pustą stronę** pakietu — `packages//README.md` jest wymagany przez `npm publish` +2. **Autorzy nie wiedzą co pisać** — każdy wymyśla strukturę od nowa lub nie pisze nic +3. **Recenzenci nie mają checklisty** — PR może być merdżowany bez dokumentacji +4. **Zewnętrzni kontrybutorzy nie mogą się onboardować** — brak contributing guide + +## Proposed Solution + +Dokumentacja jest zorganizowana w trzech poziomach: + +**Poziom 1 — Repo root `README.md`** +Tabelka wszystkich dostępnych modułów z krótkim opisem i linkiem do `packages//README.md`. Zarządzana przez maintainerów repozytorium. + +**Poziom 2 — `packages//README.md`** +Główna dokumentacja modułu — skrócona, ale zawierająca prawdziwą treść: co robi, jak zainstalować, screenshoty, najważniejsze przykłady użycia. Zawiera sekcję z linkami do `docs/` dla tych którzy potrzebują więcej szczegółów. To jest to co użytkownik widzi na npmjs.com. + +**Poziom 3 — `packages//docs/*.md`** +Rozszerzona dokumentacja podzielona tematycznie na osobne pliki. Linkowana z poziomu 2. + +### Design Decisions + +| Decision | Rationale | +|----------|-----------| +| `packages//README.md` zawiera prawdziwą treść, nie tylko nawigację | npm renderuje root README — pusty plik z linkami to złe UX dla potencjalnego użytkownika pakietu | +| `docs/` z osobnymi plikami zamiast jednego `docs/README.md` | Każdy plik ma jednoznaczną odpowiedzialność; linkowanie z zewnątrz do konkretnej sekcji; łatwiejszy przegląd PR | +| Repo root README jako tabelka modułów | Jeden punkt wejścia do całego ekosystemu; GitHub renderuje go automatycznie | +| CI blokuje PR | Wymuszenie bez CI to tylko "sugestia" — dokumentacja zawsze odkładana jest na później | + + +## User Stories / Use Cases + +- **Deweloper instalujący moduł** chce zobaczyć na npmjs.com krótki opis i linki do dokumentacji, żeby ocenić moduł bez zaglądania do kodu. +- **Deweloper integrujący moduł** chce otworzyć `docs/api.md` i znaleźć kompletne API reference z przykładami bez szukania po całym repozytorium. +- **Kontrybutor** chce otworzyć `docs/contributing.md` i wiedzieć jak uruchomić moduł lokalnie i jak dodać nową funkcjonalność. +- **Recenzent PR** chce uruchomić CI i dostać czytelny błąd jeśli wymagana dokumentacja nie istnieje. + +## Architecture + +Dokumentacja jest statycznym artefaktem repozytorium. Nie wymaga nowych modułów Medusa, encji, ani endpointów. "Komponentami" są: struktura plików, standard treści, i skrypt CI. + +### Struktura katalogowa + +``` +README.md ← POZIOM 1 — repo root: tabelka wszystkich modułów + +packages// +├── README.md ← POZIOM 2 — główna docs modułu (skrócona, z treścią) +├── docs/ +│ ├── installation.md ← POZIOM 3 — krok po kroku: install, register, generate +│ ├── usage.md ← POZIOM 3 — integracja zewnętrzna, przykłady +│ ├── api.md ← POZIOM 3 — REST endpoints + TypeScript exports +│ ├── contributing.md ← POZIOM 3 — local setup, package structure +│ └── screenshots/ ← OPCJONALNE — PNG referencjonowane w README lub docs +└── skill/ + └── SKILL.md ← OPCJONALNE (WYMAGANE gdy moduł ma rozszerzalny API) +``` + +### Skill modułu (`skill/SKILL.md`) + +Każdy moduł który udostępnia **rozszerzalny API** — tzn. inny moduł może do niego dodawać własną zawartość (szablony, adaptery, handlery, providers) — powinien dostarczać skill który automatyzuje ten proces dla konsumenta. + +Skill jest plikiem Markdown instalowanym przez `yarn install-skills` do środowiska LLM dewelopera. Dzięki niemu deweloper może napisać np. `scaffold pdf templates for my module` zamiast ręcznie tworzyć pliki według dokumentacji. + +**Kiedy skill jest wymagany:** + +- Moduł eksportuje klasę bazową do rozszerzenia (np. `BaseDocumentService`) +- Moduł używa convention file pattern (np. `pdf-generators.ts`, `carrier-rates.ts`) +- Moduł ma precyzyjny schemat plików który konsument musi odtworzyć + +**Kiedy skill jest opcjonalny:** + +- Moduł nie ma publicznego API do rozszerzenia (działa samodzielnie) +- Integracja ogranicza się do konfiguracji w `src/modules.ts` + +**Wymagana zawartość `skill/SKILL.md`:** + +```markdown +--- +name: # kebab-case, np. scaffold-pdf-templates +description: # jednozdaniowy opis + słowa kluczowe wyzwalające skill +--- + +# + +Co robi skill i kiedy go używać. + +## Inputs +Jakie zmienne pyta użytkownika przed generowaniem plików. + +## Kroki +Jakie pliki generuje i w jakiej kolejności — z pełnymi szablonami kodu. +``` + +Wzorzec: `packages/pdf-generators` na branchu `feat/pdf-generators` dostarcza skill `scaffold-pdf-templates` który generuje `DocumentService`, komponent React-PDF i convention file w jednym kroku. + +### Poziom 1 — repo root `README.md` + +Istniejąca sekcja z tabelką modułów (już jest w repo). Wymaga aktualizacji gdy dodawany jest nowy moduł: + +```markdown +## Available modules + +| Module | Description | Docs | +|--------|-------------|------| +| [`@open-mercato/pdf-generators`](packages/pdf-generators/README.md) | PDF generation framework | [Docs](packages/pdf-generators/README.md) | +| [`@open-mercato/carrier-inpost`](packages/carrier-inpost/README.md) | InPost carrier integration | [Docs](packages/carrier-inpost/README.md) | +``` + +### Poziom 2 — `packages//README.md` — szablon + +Zawiera prawdziwą, skróconą treść. Standardowe sekcje: + +```markdown +# @open-mercato/ + +<2-3 zdania: co robi moduł, dla kogo, co dostarcza out-of-the-box.> + +--- + +## Screenshots + + + +--- + +## Quick start + +\`\`\`bash +yarn mercato module add @open-mercato/ +\`\`\` + + + +--- + +## Documentation + +- [Installation](docs/installation.md) +- [Usage & Integration](docs/usage.md) +- [API Reference](docs/api.md) +- [Contributing](docs/contributing.md) + +--- + +## License + +MIT +``` + +Rozmiar: **orientacyjnie 50–150 linii**. Jeśli sekcja "Quick start" rozrasta się ponad 1 przykład — przenieś do `docs/usage.md` i zostaw tylko link. + +--- + +## Wymagana zawartość plików + +### `docs/installation.md` + +Obowiązkowe elementy: + +1. **Wymagania** — wersja Open Mercato, peer dependencies (jeśli nieoczywiste) +2. **Instalacja krok po kroku** — `mercato module add`, rejestracja w `src/modules.ts`, `yarn generate`, migracje, weryfikacja +3. **Uprawnienia** — jeśli moduł dodaje nowe ACL features, jak je zsynchronizować z rolami +4. **Weryfikacja** — co sprawdzić żeby potwierdzić że moduł działa + +### `docs/usage.md` + +Obowiązkowe elementy: + +1. **Overview** — co robi moduł z perspektywy użytkownika +2. **Podstawowe przypadki użycia** — z przykładami kodu lub screenshotami +3. **Integracja zewnętrzna** — jak moduł rozszerzać z innego modułu (convention files, extension points) + +Opcjonalne: + +- **Built-in defaults** — gdy moduł dostarcza gotowe szablony / konfiguracje do nadpisania +- **Configuration** — env vars, ustawienia runtime + +### `docs/api.md` + +Obowiązkowe elementy (jeśli moduł udostępnia API): + +1. **REST Endpoints** — dla każdego endpointu: metoda + ścieżka, opis, request body, response shape, kody błędów +2. **TypeScript exports** — publiczne klasy, funkcje, typy eksportowane z pakietu z opisem + +Sekcja może być pusta (z notatką) jeśli moduł nie udostępnia żadnego API. + +### `docs/contributing.md` + +Obowiązkowe elementy: + +1. **Local setup** — jak uruchomić moduł w trybie watch + sandbox +2. **Package structure** — drzewo katalogów `src/` z opisem każdego pliku/folderu +3. **Jak dodać nową funkcjonalność** — przepływ pracy dla najczęstszego przypadku rozszerzenia (np. nowy template, nowy carrier) + +--- + +## Implementation Plan + +### Phase 1: Standard i infrastruktura + +1. Sfinalizować tę specyfikację (done) +2. Zaktualizować root `AGENTS.md` — dodać sekcję "Documentation Requirements" z linkiem do tej specyfikacji +3. Zaktualizować skill `scaffold-module` — generuje puste szablony wymaganych plików docs podczas scaffoldowania nowej paczki +4. Dodać GitHub Actions workflow `.github/workflows/docs-check.yml` — przy każdym PR sprawdza czy wszystkie wymagane pliki (`README.md`, `docs/installation.md`, `docs/usage.md`, `docs/api.md`, `docs/contributing.md`) istnieją w zmienionych paczkach; blokuje merge jeśli brakuje + +### Phase 2: Dokumentacja istniejących pakietów + +Każdy istniejący pakiet w `packages/` musi zostać uzupełniony o wymaganą strukturę docs. Każdy pakiet to osobny PR. + +Dla `carrier-inpost`: +1. Dodać `packages/carrier-inpost/README.md` (skrócona dokumentacja) +2. Stworzyć `packages/carrier-inpost/docs/installation.md` +3. Stworzyć `packages/carrier-inpost/docs/usage.md` +4. Stworzyć `packages/carrier-inpost/docs/api.md` +5. Stworzyć `packages/carrier-inpost/docs/contributing.md` +6. Zaktualizować repo root `README.md` — dodać link do `carrier-inpost` w tabelce modułów + +### File Manifest + +| Plik | Akcja | Cel | +|------|-------|-----| +| `AGENTS.md` | Modify | Dodać sekcję Documentation Requirements | +| `.github/workflows/docs-check.yml` | Create | CI walidacja wymaganych plików | +| `packages/carrier-inpost/README.md` | Create | Skrócona dokumentacja modułu (poziom 2) | +| `packages/carrier-inpost/docs/installation.md` | Create | — | +| `packages/carrier-inpost/docs/usage.md` | Create | — | +| `packages/carrier-inpost/docs/api.md` | Create | — | +| `packages/carrier-inpost/docs/contributing.md` | Create | — | +| `README.md` | Modify | Zaktualizować tabelkę modułów z linkiem do carrier-inpost docs | + +--- + +## Risks & Impact Review + +### Dług techniczny — carrier-inpost + +#### Brak wiedzy o module carrier-inpost +- **Scenario**: Wymagana dokumentacja musi zostać napisana przez kogoś kto rozumie moduł — jeśli oryginalny autor jest niedostępny, maintainer musi zapoznać się z kodem od zera +- **Severity**: Medium +- **Affected area**: `packages/carrier-inpost` +- **Mitigation**: Phase 1 wprost przypisuje stworzenie docs dla carrier-inpost; scaffold-module generuje szablony z placeholder content jako punkt startowy +- **Residual risk**: Jakość dokumentacji carrier-inpost zależy od dostępności autora + +### Rozjazd szablonu CI ze strukturą plików + +#### Zmiana wymaganej struktury bez aktualizacji CI +- **Scenario**: Ktoś decyduje że `docs/api.md` nie jest wymagany dla prostych modułów bez API, ale CI nadal go wymaga i blokuje PR +- **Severity**: Low +- **Affected area**: Wszystkie nowe PR dodające moduły +- **Mitigation**: Lista wymaganych plików w CI jest zarządzana jako tablica w jednym miejscu w workflow YAML — prosta do edycji +- **Residual risk**: Akceptowalny — prosta zmiana w jednym pliku + +--- + +## Final Compliance Report — 2026-05-18 + +### AGENTS.md Files Reviewed +- `AGENTS.md` (root) + +### Compliance Matrix + +| Rule Source | Rule | Status | Notes | +|-------------|------|--------|-------| +| root AGENTS.md | Pakiety w `packages//` | Compliant | Dotyczy wyłącznie plików docs — nie dodaje kodu poza packages/ | +| root AGENTS.md | Nie modyfikuje core packages | Compliant | Spec nie ingeruje w żaden core package | +| root AGENTS.md | Check `.ai/specs/` before starting | Compliant | Sprawdzono — brak istniejącej spec o dokumentacji | + +### Internal Consistency Check + +| Check | Status | Notes | +|-------|--------|-------| +| File Manifest pokrywa wszystkie pakiety z Problem Statement | Pass | pdf-generators i carrier-inpost | +| Implementation Phases są wykonywalne bez blokowania się | Pass | Phase 1 i 2 są niezależne | +| CI scope odpowiada wymaganym plikom z Architecture | Pass | Sprawdza dokładnie 5 plików z listy | + +### Verdict + +**Fully compliant** — Approved, ready for implementation. + +--- + +## Changelog + +### 2026-05-18 +- Pełna specyfikacja po rozstrzygnięciu Open Questions +- Zmiana architektury na trójpoziomową: repo root → `packages//README.md` (skrócona treść) → `docs/*.md` (rozszerzona) +- `packages//README.md` zawiera prawdziwą treść, nie tylko nawigację +- CI blokuje PR jeśli brakuje wymaganych plików From e273440de1269d5a67bd5e2cbc19d1c7a9560387 Mon Sep 17 00:00:00 2001 From: Krzysztof Polak Date: Mon, 18 May 2026 09:51:56 +0200 Subject: [PATCH 2/3] chore: add module documentation standard specification (SPEC-005) --- ...026-05-18-module-documentation-standard.md | 276 +++++++++--------- 1 file changed, 138 insertions(+), 138 deletions(-) diff --git a/.ai/specs/SPEC-005-2026-05-18-module-documentation-standard.md b/.ai/specs/SPEC-005-2026-05-18-module-documentation-standard.md index 3f9f578..fc07ea8 100644 --- a/.ai/specs/SPEC-005-2026-05-18-module-documentation-standard.md +++ b/.ai/specs/SPEC-005-2026-05-18-module-documentation-standard.md @@ -3,139 +3,138 @@ ## TLDR **Key Points:** -- Dokumentacja jest trójpoziomowa: repo root README (tabelka modułów) → `packages//README.md` (skrócona dokumentacja modułu) → `packages//docs/*.md` (rozszerzona dokumentacja podzielona na pliki). -- `packages//README.md` zawiera prawdziwą treść (nie tylko nawigację) — krótkie omówienie modułu, quick start, screenshoty, linki do rozszerzonej docs. -- Wzorcem jest `packages/pdf-generators` — jego `docs/README.md` zostanie rozbity na osobne pliki zgodnie z tym standardem. -- CI blokuje PR jeśli wymagane pliki nie istnieją. +- Documentation follows a three-level hierarchy: repo root README (module table) → `packages//README.md` (shortened module docs) → `packages//docs/*.md` (extended documentation split into files). +- `packages//README.md` contains real content (not just navigation) — a short module overview, quick start, screenshots, and links to extended docs. +- The reference implementation is `packages/pdf-generators` on the `feat/pdf-generators` branch — its `docs/README.md` should be split into separate files following this standard. +- CI blocks PRs if required files are missing. **Scope:** -- Trójpoziomowa hierarchia README: repo → pakiet → docs/ -- Standard treści `packages//README.md` (skrócona dokumentacja) -- Wymagane pliki w `docs/` (rozszerzona dokumentacja) -- GitHub Actions walidacja — blokuje merge gdy brak wymaganych plików +- Three-level README hierarchy: repo → package → docs/ +- Content standard for `packages//README.md` (shortened docs) +- Required files in `docs/` (extended documentation) +- GitHub Actions validation — blocks merge when required files are missing **Concerns:** -- `carrier-inpost` nie ma żadnej dokumentacji — wymaga dopisania od zera -- Podwójny SPEC-004 w `.ai/specs/` — poza scope tej specyfikacji +- `carrier-inpost` has no documentation at all — needs to be written from scratch +- Duplicate SPEC-004 in `.ai/specs/` — out of scope for this specification --- ## Overview -Każdy moduł w `offical-modules` jest zewnętrznym rozszerzeniem instalowanym przez deweloperów budujących aplikacje na Open Mercato. Jakość dokumentacji bezpośrednio przekłada się na adoption — moduł bez README to moduł, którego nikt nie zainstaluje bez zaglądania w kod. +Every module in `offical-modules` is an external extension installed by developers building applications on Open Mercato. Documentation quality directly impacts adoption — a module without a README is a module nobody will install without reading the source. -Specyfikacja definiuje **wymagany minimalny zestaw dokumentacji** dla każdego pakietu oraz **strukturę katalogową** tak, aby autorzy wiedzieli dokładnie co napisać, a recenzenci i CI wiedzieli co sprawdzić przed mergem. +This specification defines the **required minimum documentation set** for each package and the **directory structure**, so authors know exactly what to write and reviewers and CI know what to check before merging. -> **Market Reference**: Wzorowano się na podejściu stosowanym przez Shopify Polaris, Medusa.js i shadcn/ui — każdy z tych projektów posiada spójną strukturę per-pakiet z dokumentacją podzieloną na tematyczne pliki (installation, api, contributing). Odrzucono model monolitycznych wiki (Confluence, Notion) jako nietrwały i oderwany od kodu. Odrzucono też model jednego dużego README.md — przy modułach tej złożoności co pdf-generators szybko staje się nieczytelny. +> **Market Reference**: Modeled on the approach used by Shopify Polaris, Medusa.js, and shadcn/ui — each project has a consistent per-package structure with documentation split into thematic files (installation, api, contributing). Monolithic wiki models (Confluence, Notion) were rejected as fragile and disconnected from the code. A single large README.md was also rejected — for modules as complex as pdf-generators it quickly becomes unreadable. ## Problem Statement -Aktualny stan repozytorium: +Current state of the repository: -| Pakiet | Root README | docs/ | Stan | -|--------|-------------|-------|------| -| `pdf-generators` | brak | `docs/README.md` (monoplik) | Częściowy — brak root README, brak podziału na pliki | -| `carrier-inpost` | brak | brak | Brak dokumentacji | -| `test-package` | brak | brak | Placeholder — wyłączony ze scope | +| Package | Root README | docs/ | Status | +|---------|-------------|-------|--------| +| `pdf-generators` | missing | `docs/README.md` (monolithic) | Partial — no root README, no file split | +| `carrier-inpost` | missing | missing | No documentation | +| `test-package` | missing | missing | Placeholder — excluded from scope | -Brak standardu powoduje: -1. **npm pokazuje pustą stronę** pakietu — `packages//README.md` jest wymagany przez `npm publish` -2. **Autorzy nie wiedzą co pisać** — każdy wymyśla strukturę od nowa lub nie pisze nic -3. **Recenzenci nie mają checklisty** — PR może być merdżowany bez dokumentacji -4. **Zewnętrzni kontrybutorzy nie mogą się onboardować** — brak contributing guide +The lack of a standard causes: +1. **npm shows an empty page** for the package — `packages//README.md` is required by `npm publish` +2. **Authors don't know what to write** — everyone invents their own structure or writes nothing +3. **Reviewers have no checklist** — PRs can be merged without documentation +4. **External contributors cannot onboard** — no contributing guide ## Proposed Solution -Dokumentacja jest zorganizowana w trzech poziomach: +Documentation is organized in three levels: -**Poziom 1 — Repo root `README.md`** -Tabelka wszystkich dostępnych modułów z krótkim opisem i linkiem do `packages//README.md`. Zarządzana przez maintainerów repozytorium. +**Level 1 — Repo root `README.md`** +A table of all available modules with a short description and a link to `packages//README.md`. Maintained by repository maintainers. -**Poziom 2 — `packages//README.md`** -Główna dokumentacja modułu — skrócona, ale zawierająca prawdziwą treść: co robi, jak zainstalować, screenshoty, najważniejsze przykłady użycia. Zawiera sekcję z linkami do `docs/` dla tych którzy potrzebują więcej szczegółów. To jest to co użytkownik widzi na npmjs.com. +**Level 2 — `packages//README.md`** +The main module documentation — shortened but containing real content: what it does, how to install it, screenshots, the most important usage examples. Includes a section with links to `docs/` for those who need more detail. This is what users see on npmjs.com. -**Poziom 3 — `packages//docs/*.md`** -Rozszerzona dokumentacja podzielona tematycznie na osobne pliki. Linkowana z poziomu 2. +**Level 3 — `packages//docs/*.md`** +Extended documentation split into thematic files. Linked from Level 2. ### Design Decisions | Decision | Rationale | |----------|-----------| -| `packages//README.md` zawiera prawdziwą treść, nie tylko nawigację | npm renderuje root README — pusty plik z linkami to złe UX dla potencjalnego użytkownika pakietu | -| `docs/` z osobnymi plikami zamiast jednego `docs/README.md` | Każdy plik ma jednoznaczną odpowiedzialność; linkowanie z zewnątrz do konkretnej sekcji; łatwiejszy przegląd PR | -| Repo root README jako tabelka modułów | Jeden punkt wejścia do całego ekosystemu; GitHub renderuje go automatycznie | -| CI blokuje PR | Wymuszenie bez CI to tylko "sugestia" — dokumentacja zawsze odkładana jest na później | - +| `packages//README.md` contains real content, not just navigation | npm renders the root README — an empty file with only links is poor UX for potential package users | +| `docs/` with separate files instead of a single `docs/README.md` | Each file has a single responsibility; enables deep-linking to specific sections; easier PR review | +| Repo root README as a module table | Single entry point to the entire ecosystem; GitHub renders it automatically | +| CI blocks PRs | Enforcement without CI is just a "suggestion" — documentation is always pushed off until later | ## User Stories / Use Cases -- **Deweloper instalujący moduł** chce zobaczyć na npmjs.com krótki opis i linki do dokumentacji, żeby ocenić moduł bez zaglądania do kodu. -- **Deweloper integrujący moduł** chce otworzyć `docs/api.md` i znaleźć kompletne API reference z przykładami bez szukania po całym repozytorium. -- **Kontrybutor** chce otworzyć `docs/contributing.md` i wiedzieć jak uruchomić moduł lokalnie i jak dodać nową funkcjonalność. -- **Recenzent PR** chce uruchomić CI i dostać czytelny błąd jeśli wymagana dokumentacja nie istnieje. +- **A developer evaluating a module** wants to see a short description and links to documentation on npmjs.com so they can assess the module without reading the source. +- **A developer integrating a module** wants to open `docs/api.md` and find a complete API reference with examples without searching the entire repository. +- **A contributor** wants to open `docs/contributing.md` and know how to run the module locally and how to add new functionality. +- **A PR reviewer** wants CI to fail with a clear error if required documentation is missing. ## Architecture -Dokumentacja jest statycznym artefaktem repozytorium. Nie wymaga nowych modułów Medusa, encji, ani endpointów. "Komponentami" są: struktura plików, standard treści, i skrypt CI. +Documentation is a static repository artifact. It requires no new Medusa modules, entities, or endpoints. The "components" are: the file structure, the content standard, and the CI script. -### Struktura katalogowa +### Directory Structure ``` -README.md ← POZIOM 1 — repo root: tabelka wszystkich modułów +README.md ← LEVEL 1 — repo root: table of all modules packages// -├── README.md ← POZIOM 2 — główna docs modułu (skrócona, z treścią) +├── README.md ← LEVEL 2 — main module docs (shortened, with content) ├── docs/ -│ ├── installation.md ← POZIOM 3 — krok po kroku: install, register, generate -│ ├── usage.md ← POZIOM 3 — integracja zewnętrzna, przykłady -│ ├── api.md ← POZIOM 3 — REST endpoints + TypeScript exports -│ ├── contributing.md ← POZIOM 3 — local setup, package structure -│ └── screenshots/ ← OPCJONALNE — PNG referencjonowane w README lub docs +│ ├── installation.md ← LEVEL 3 — step by step: install, register, generate +│ ├── usage.md ← LEVEL 3 — external integration, examples +│ ├── api.md ← LEVEL 3 — REST endpoints + TypeScript exports +│ ├── contributing.md ← LEVEL 3 — local setup, package structure +│ └── screenshots/ ← OPTIONAL — PNGs referenced in README or docs └── skill/ - └── SKILL.md ← OPCJONALNE (WYMAGANE gdy moduł ma rozszerzalny API) + └── SKILL.md ← OPTIONAL (REQUIRED when the module has an extensible API) ``` -### Skill modułu (`skill/SKILL.md`) +### Module Skill (`skill/SKILL.md`) -Każdy moduł który udostępnia **rozszerzalny API** — tzn. inny moduł może do niego dodawać własną zawartość (szablony, adaptery, handlery, providers) — powinien dostarczać skill który automatyzuje ten proces dla konsumenta. +Any module that exposes an **extensible API** — meaning another module can add its own content to it (templates, adapters, handlers, providers) — should ship a skill that automates that process for consumers. -Skill jest plikiem Markdown instalowanym przez `yarn install-skills` do środowiska LLM dewelopera. Dzięki niemu deweloper może napisać np. `scaffold pdf templates for my module` zamiast ręcznie tworzyć pliki według dokumentacji. +A skill is a Markdown file installed by `yarn install-skills` into the developer's LLM environment. It lets a developer type e.g. `scaffold pdf templates for my module` instead of manually creating files by following the documentation. -**Kiedy skill jest wymagany:** +**When a skill is required:** -- Moduł eksportuje klasę bazową do rozszerzenia (np. `BaseDocumentService`) -- Moduł używa convention file pattern (np. `pdf-generators.ts`, `carrier-rates.ts`) -- Moduł ma precyzyjny schemat plików który konsument musi odtworzyć +- The module exports a base class to extend (e.g. `BaseDocumentService`) +- The module uses a convention file pattern (e.g. `pdf-generators.ts`, `carrier-rates.ts`) +- The module has a precise file schema that consumers must replicate -**Kiedy skill jest opcjonalny:** +**When a skill is optional:** -- Moduł nie ma publicznego API do rozszerzenia (działa samodzielnie) -- Integracja ogranicza się do konfiguracji w `src/modules.ts` +- The module has no public extensible API (works standalone) +- Integration is limited to configuration in `src/modules.ts` -**Wymagana zawartość `skill/SKILL.md`:** +**Required content of `skill/SKILL.md`:** ```markdown --- -name: # kebab-case, np. scaffold-pdf-templates -description: # jednozdaniowy opis + słowa kluczowe wyzwalające skill +name: # kebab-case, e.g. scaffold-pdf-templates +description: # one-sentence description + trigger keywords --- # -Co robi skill i kiedy go używać. +What the skill does and when to use it. ## Inputs -Jakie zmienne pyta użytkownika przed generowaniem plików. +What variables to ask the user before generating files. -## Kroki -Jakie pliki generuje i w jakiej kolejności — z pełnymi szablonami kodu. +## Steps +What files to generate and in what order — with full code templates. ``` -Wzorzec: `packages/pdf-generators` na branchu `feat/pdf-generators` dostarcza skill `scaffold-pdf-templates` który generuje `DocumentService`, komponent React-PDF i convention file w jednym kroku. +Reference: `packages/pdf-generators` on the `feat/pdf-generators` branch ships the `scaffold-pdf-templates` skill, which generates a `DocumentService`, a React-PDF component, and a convention file in one step. -### Poziom 1 — repo root `README.md` +### Level 1 — Repo root `README.md` -Istniejąca sekcja z tabelką modułów (już jest w repo). Wymaga aktualizacji gdy dodawany jest nowy moduł: +The existing module table (already in the repo). Must be updated when a new module is added: ```markdown ## Available modules @@ -146,20 +145,20 @@ Istniejąca sekcja z tabelką modułów (już jest w repo). Wymaga aktualizacji | [`@open-mercato/carrier-inpost`](packages/carrier-inpost/README.md) | InPost carrier integration | [Docs](packages/carrier-inpost/README.md) | ``` -### Poziom 2 — `packages//README.md` — szablon +### Level 2 — `packages//README.md` — template -Zawiera prawdziwą, skróconą treść. Standardowe sekcje: +Contains real, shortened content. Standard sections: ```markdown # @open-mercato/ -<2-3 zdania: co robi moduł, dla kogo, co dostarcza out-of-the-box.> +<2-3 sentences: what the module does, for whom, what it provides out-of-the-box.> --- ## Screenshots - + --- @@ -169,7 +168,7 @@ Zawiera prawdziwą, skróconą treść. Standardowe sekcje: yarn mercato module add @open-mercato/ \`\`\` - + --- @@ -187,108 +186,108 @@ yarn mercato module add @open-mercato/ MIT ``` -Rozmiar: **orientacyjnie 50–150 linii**. Jeśli sekcja "Quick start" rozrasta się ponad 1 przykład — przenieś do `docs/usage.md` i zostaw tylko link. +Target size: **roughly 50–150 lines**. If the "Quick start" section grows beyond one example — move it to `docs/usage.md` and leave only a link. --- -## Wymagana zawartość plików +## Required File Contents ### `docs/installation.md` -Obowiązkowe elementy: +Required elements: -1. **Wymagania** — wersja Open Mercato, peer dependencies (jeśli nieoczywiste) -2. **Instalacja krok po kroku** — `mercato module add`, rejestracja w `src/modules.ts`, `yarn generate`, migracje, weryfikacja -3. **Uprawnienia** — jeśli moduł dodaje nowe ACL features, jak je zsynchronizować z rolami -4. **Weryfikacja** — co sprawdzić żeby potwierdzić że moduł działa +1. **Requirements** — Open Mercato version, peer dependencies (if non-obvious) +2. **Step-by-step installation** — `mercato module add`, registration in `src/modules.ts`, `yarn generate`, migrations, verification +3. **Permissions** — if the module adds new ACL features, how to sync them with roles +4. **Verification** — what to check to confirm the module is working ### `docs/usage.md` -Obowiązkowe elementy: +Required elements: -1. **Overview** — co robi moduł z perspektywy użytkownika -2. **Podstawowe przypadki użycia** — z przykładami kodu lub screenshotami -3. **Integracja zewnętrzna** — jak moduł rozszerzać z innego modułu (convention files, extension points) +1. **Overview** — what the module does from the user's perspective +2. **Core use cases** — with code examples or screenshots +3. **External integration** — how to extend the module from another module (convention files, extension points) -Opcjonalne: +Optional: -- **Built-in defaults** — gdy moduł dostarcza gotowe szablony / konfiguracje do nadpisania -- **Configuration** — env vars, ustawienia runtime +- **Built-in defaults** — when the module ships ready-made templates / configurations to override +- **Configuration** — env vars, runtime settings ### `docs/api.md` -Obowiązkowe elementy (jeśli moduł udostępnia API): +Required elements (if the module exposes an API): -1. **REST Endpoints** — dla każdego endpointu: metoda + ścieżka, opis, request body, response shape, kody błędów -2. **TypeScript exports** — publiczne klasy, funkcje, typy eksportowane z pakietu z opisem +1. **REST Endpoints** — for each endpoint: method + path, description, request body, response shape, error codes +2. **TypeScript exports** — public classes, functions, and types exported from the package with descriptions -Sekcja może być pusta (z notatką) jeśli moduł nie udostępnia żadnego API. +The section may be empty (with a note) if the module exposes no API. ### `docs/contributing.md` -Obowiązkowe elementy: +Required elements: -1. **Local setup** — jak uruchomić moduł w trybie watch + sandbox -2. **Package structure** — drzewo katalogów `src/` z opisem każdego pliku/folderu -3. **Jak dodać nową funkcjonalność** — przepływ pracy dla najczęstszego przypadku rozszerzenia (np. nowy template, nowy carrier) +1. **Local setup** — how to run the module in watch mode + sandbox +2. **Package structure** — `src/` directory tree with a description of each file/folder +3. **How to add new functionality** — workflow for the most common extension case (e.g. a new template, a new carrier) --- ## Implementation Plan -### Phase 1: Standard i infrastruktura +### Phase 1: Standard and infrastructure -1. Sfinalizować tę specyfikację (done) -2. Zaktualizować root `AGENTS.md` — dodać sekcję "Documentation Requirements" z linkiem do tej specyfikacji -3. Zaktualizować skill `scaffold-module` — generuje puste szablony wymaganych plików docs podczas scaffoldowania nowej paczki -4. Dodać GitHub Actions workflow `.github/workflows/docs-check.yml` — przy każdym PR sprawdza czy wszystkie wymagane pliki (`README.md`, `docs/installation.md`, `docs/usage.md`, `docs/api.md`, `docs/contributing.md`) istnieją w zmienionych paczkach; blokuje merge jeśli brakuje +1. Finalize this specification (done) +2. Update root `AGENTS.md` — add a "Documentation Requirements" section with a link to this specification +3. Update the `scaffold-module` skill — generate empty templates for required docs files when scaffolding a new package +4. Add a GitHub Actions workflow `.github/workflows/docs-check.yml` — on every PR, checks whether all required files (`README.md`, `docs/installation.md`, `docs/usage.md`, `docs/api.md`, `docs/contributing.md`) exist in changed packages; blocks merge if any are missing -### Phase 2: Dokumentacja istniejących pakietów +### Phase 2: Documentation for existing packages -Każdy istniejący pakiet w `packages/` musi zostać uzupełniony o wymaganą strukturę docs. Każdy pakiet to osobny PR. +Every existing package in `packages/` must be brought up to the required docs structure. Each package is a separate PR. -Dla `carrier-inpost`: -1. Dodać `packages/carrier-inpost/README.md` (skrócona dokumentacja) -2. Stworzyć `packages/carrier-inpost/docs/installation.md` -3. Stworzyć `packages/carrier-inpost/docs/usage.md` -4. Stworzyć `packages/carrier-inpost/docs/api.md` -5. Stworzyć `packages/carrier-inpost/docs/contributing.md` -6. Zaktualizować repo root `README.md` — dodać link do `carrier-inpost` w tabelce modułów +For `carrier-inpost`: +1. Add `packages/carrier-inpost/README.md` (shortened docs) +2. Create `packages/carrier-inpost/docs/installation.md` +3. Create `packages/carrier-inpost/docs/usage.md` +4. Create `packages/carrier-inpost/docs/api.md` +5. Create `packages/carrier-inpost/docs/contributing.md` +6. Update repo root `README.md` — add a link to `carrier-inpost` in the module table ### File Manifest -| Plik | Akcja | Cel | -|------|-------|-----| -| `AGENTS.md` | Modify | Dodać sekcję Documentation Requirements | -| `.github/workflows/docs-check.yml` | Create | CI walidacja wymaganych plików | -| `packages/carrier-inpost/README.md` | Create | Skrócona dokumentacja modułu (poziom 2) | +| File | Action | Purpose | +|------|--------|---------| +| `AGENTS.md` | Modify | Add Documentation Requirements section | +| `.github/workflows/docs-check.yml` | Create | CI validation of required files | +| `packages/carrier-inpost/README.md` | Create | Shortened module docs (level 2) | | `packages/carrier-inpost/docs/installation.md` | Create | — | | `packages/carrier-inpost/docs/usage.md` | Create | — | | `packages/carrier-inpost/docs/api.md` | Create | — | | `packages/carrier-inpost/docs/contributing.md` | Create | — | -| `README.md` | Modify | Zaktualizować tabelkę modułów z linkiem do carrier-inpost docs | +| `README.md` | Modify | Update module table with link to carrier-inpost docs | --- ## Risks & Impact Review -### Dług techniczny — carrier-inpost +### Technical debt — carrier-inpost -#### Brak wiedzy o module carrier-inpost -- **Scenario**: Wymagana dokumentacja musi zostać napisana przez kogoś kto rozumie moduł — jeśli oryginalny autor jest niedostępny, maintainer musi zapoznać się z kodem od zera +#### No knowledge of the carrier-inpost module +- **Scenario**: The required documentation must be written by someone who understands the module — if the original author is unavailable, the maintainer must read the source from scratch - **Severity**: Medium - **Affected area**: `packages/carrier-inpost` -- **Mitigation**: Phase 1 wprost przypisuje stworzenie docs dla carrier-inpost; scaffold-module generuje szablony z placeholder content jako punkt startowy -- **Residual risk**: Jakość dokumentacji carrier-inpost zależy od dostępności autora +- **Mitigation**: Phase 2 explicitly assigns creating docs for carrier-inpost; scaffold-module generates templates with placeholder content as a starting point +- **Residual risk**: Quality of carrier-inpost documentation depends on author availability -### Rozjazd szablonu CI ze strukturą plików +### CI template drift -#### Zmiana wymaganej struktury bez aktualizacji CI -- **Scenario**: Ktoś decyduje że `docs/api.md` nie jest wymagany dla prostych modułów bez API, ale CI nadal go wymaga i blokuje PR +#### Required structure changes without updating CI +- **Scenario**: Someone decides `docs/api.md` is not required for simple modules with no API, but CI still requires it and blocks PRs - **Severity**: Low -- **Affected area**: Wszystkie nowe PR dodające moduły -- **Mitigation**: Lista wymaganych plików w CI jest zarządzana jako tablica w jednym miejscu w workflow YAML — prosta do edycji -- **Residual risk**: Akceptowalny — prosta zmiana w jednym pliku +- **Affected area**: All new PRs adding modules +- **Mitigation**: The list of required files in CI is managed as an array in a single place in the workflow YAML — trivial to edit +- **Residual risk**: Acceptable — a simple change in one file --- @@ -301,17 +300,17 @@ Dla `carrier-inpost`: | Rule Source | Rule | Status | Notes | |-------------|------|--------|-------| -| root AGENTS.md | Pakiety w `packages//` | Compliant | Dotyczy wyłącznie plików docs — nie dodaje kodu poza packages/ | -| root AGENTS.md | Nie modyfikuje core packages | Compliant | Spec nie ingeruje w żaden core package | -| root AGENTS.md | Check `.ai/specs/` before starting | Compliant | Sprawdzono — brak istniejącej spec o dokumentacji | +| root AGENTS.md | Packages in `packages//` | Compliant | Applies only to docs files — no code added outside packages/ | +| root AGENTS.md | Must not modify core packages | Compliant | Spec does not touch any core package | +| root AGENTS.md | Check `.ai/specs/` before starting | Compliant | Checked — no existing spec on documentation | ### Internal Consistency Check | Check | Status | Notes | |-------|--------|-------| -| File Manifest pokrywa wszystkie pakiety z Problem Statement | Pass | pdf-generators i carrier-inpost | -| Implementation Phases są wykonywalne bez blokowania się | Pass | Phase 1 i 2 są niezależne | -| CI scope odpowiada wymaganym plikom z Architecture | Pass | Sprawdza dokładnie 5 plików z listy | +| File Manifest covers all packages from Problem Statement | Pass | carrier-inpost | +| Implementation Phases are executable without blocking each other | Pass | Phase 1 and 2 are independent | +| CI scope matches required files from Architecture | Pass | Checks exactly the 5 files from the list | ### Verdict @@ -322,7 +321,8 @@ Dla `carrier-inpost`: ## Changelog ### 2026-05-18 -- Pełna specyfikacja po rozstrzygnięciu Open Questions -- Zmiana architektury na trójpoziomową: repo root → `packages//README.md` (skrócona treść) → `docs/*.md` (rozszerzona) -- `packages//README.md` zawiera prawdziwą treść, nie tylko nawigację -- CI blokuje PR jeśli brakuje wymaganych plików +- Full specification after resolving Open Questions +- Architecture changed to three-level: repo root → `packages//README.md` (shortened content) → `docs/*.md` (extended) +- `packages//README.md` contains real content, not just navigation +- Added `skill/SKILL.md` requirement for modules with extensible APIs +- CI blocks PRs when required files are missing From 33460f82aebd6e01af9709c16f30cdecfcbe1b3e Mon Sep 17 00:00:00 2001 From: Krzysztof Polak Date: Mon, 18 May 2026 10:03:59 +0200 Subject: [PATCH 3/3] chore: update SPEC-005 with Requirements section and peerDependencies rule --- ...026-05-18-module-documentation-standard.md | 22 +++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/.ai/specs/SPEC-005-2026-05-18-module-documentation-standard.md b/.ai/specs/SPEC-005-2026-05-18-module-documentation-standard.md index fc07ea8..d81dbff 100644 --- a/.ai/specs/SPEC-005-2026-05-18-module-documentation-standard.md +++ b/.ai/specs/SPEC-005-2026-05-18-module-documentation-standard.md @@ -156,6 +156,15 @@ Contains real, shortened content. Standard sections: --- +## Requirements + +| Dependency | Version | +|------------|---------| +| Open Mercato | `^` | +| `react` | `^19.0.0` | + +--- + ## Screenshots @@ -188,6 +197,8 @@ MIT Target size: **roughly 50–150 lines**. If the "Quick start" section grows beyond one example — move it to `docs/usage.md` and leave only a link. +The Open Mercato version in Requirements must match the stable range declared in `peerDependencies` in `package.json` — never a develop pin (e.g. `^0.6.2`, not `0.6.2-develop.3330.xxx`). + --- ## Required File Contents @@ -196,10 +207,11 @@ Target size: **roughly 50–150 lines**. If the "Quick start" section grows beyo Required elements: -1. **Requirements** — Open Mercato version, peer dependencies (if non-obvious) -2. **Step-by-step installation** — `mercato module add`, registration in `src/modules.ts`, `yarn generate`, migrations, verification -3. **Permissions** — if the module adds new ACL features, how to sync them with roles -4. **Verification** — what to check to confirm the module is working +1. **Step-by-step installation** — `mercato module add`, registration in `src/modules.ts`, `yarn generate`, migrations, verification +2. **Permissions** — if the module adds new ACL features, how to sync them with roles +3. **Verification** — what to check to confirm the module is working + +> Requirements (Open Mercato version, `react`) live in the `## Requirements` section of the root `README.md` — do not repeat them here. ### `docs/usage.md` @@ -326,3 +338,5 @@ For `carrier-inpost`: - `packages//README.md` contains real content, not just navigation - Added `skill/SKILL.md` requirement for modules with extensible APIs - CI blocks PRs when required files are missing +- Added `## Requirements` section to `README.md` template (Open Mercato version + react) — derived from stable `peerDependencies` range, not a develop pin +- Removed requirements from `docs/installation.md` — single source of truth is the root README