MateMatic Spec-Driven - dev pipeline dla naszych projektow

Spec-Driven Development dla wewnetrznych projektow MateMatic. NIE produkt sprzedazowy dla kancelarii (tym jest matematic-konstytucja-ai). Tutaj: my, dla siebie, do PATRON / KGLF / POAS / skilli / mikroproduktow / aplikacji / serialu.

Source pattern: github/spec-kit (MIT) v0.8.12 - 4-fazowa methodology Constitution -> Specify -> Plan -> Tasks z marker [P] i Constitution Check GATE. Cherry-pick wybranych elementow + adaptacja pod MateMatic project types.

Status: v0.1.0 - faza C adopcji spec-kit (po fazie B = sandbox install 2026-05-20). Walidacja w boju przy 1-2 projektach (rekomendacja: nowy konektor SAOS w PATRON albo Biblioteka EPUB v3).

---

Kiedy uzywac

✅ TAK:

• Nowy projekt MateMatic od zera (nowy mikroprodukt, aplikacja, agent)
• Duza ficzer w istniejacym projekcie (PATRON / KGLF / www-matematic)
• Skill ktory ma 4+ podkomendy i zaleznosci (np. matematic-video-pipeline)
• Odcinek serialu "Nie tylko dla orlow" wymagajacy formalnego rozbicia (6-9 scen, fan-out subagentow)
• Audyt istniejacego projektu - czy ma konstytucje? czy ficzer zgadza sie z konstytucja?

❌ NIE:

• Sprzedaz kancelarii (uzyj matematic-konstytucja-ai)
• Krotki post LI / aktualnosc BW (uzyj skilla redakcyjnego albo skilla glosu autora na LinkedIn)
• Pojedynczy bugfix / refactor w juz dzialajacym module
• MEMO Ej Aj (uzyj wlasnego pipeline'u produkcji odcinka)

---

4 fazy + walidacja

Faza 1 - /mspec-konstytucja (Constitution)

Output: .matematic/konstytucja.md (jeden plik per projekt, SEMVER versioning).

Konstytucja projektu = niezmienne zasady, na ktore wszystkie downstream artefakty musza sie powolac. NIE myl z konstytucja AI dla kancelarii (tamta dotyczy ORGANIZACJI klienta, ta - PROJEKTU MateMatic).

Struktura:

# [Nazwa projektu] - Konstytucja

## Mission (1 zdanie)
[Po co ten projekt istnieje, w kontekscie MateMatic]

## Core Principles (3-7 articles)

### Article I - [Nazwa]
[Imperatyw MUST / MUST NOT / SHOULD]

### Article II - [Nazwa]
...

**Dwa gotowe wzorce artykulow** (zapozyczone z `tutti-os/tutti`, egzekwowalne
mechanicznie, nie tylko deklaratywnie - wklej i dostosuj gdy pasuje do projektu):

- **Limit rozmiaru pliku** - "Pliki z logika biznesowa MUST pozostac <= 800 linii;
  przekroczenie wymaga rozbicia modulu, nie wyjatku w konstytucji." Prosta,
  mechaniczna bariera przeciw monolitom - latwa do sprawdzenia w CI/pre-commit.
- **Drift ADR dla vendorowanych/forkowanych specyfikacji** - "Kazdy fork/vendoring
  zewnetrznego protokolu, schematu lub API (np. ELI, wzorzec ADR z dograh, logika
  scrapowania ISAP) MUST miec wlasny ADR dokumentujacy punkt pinowania + cykliczny
  recheck upstream drift." Formalizuje problem ktory juz mielismy nieformalnie -
  bo kod wyprzedza dokumentacje, a errata z ADR-rodzica musi przejsc do ADR-dzieci.

## Boundaries (granice)
- Co projekt **robi**
- Czego projekt **nie robi** (anty-zakres)
- Z czym wspolpracuje (zaleznosci na inne projekty MateMatic)

## Governance (kto decyduje)
- Owner: Wieslaw Mazur
- Reviewers: [marko-pl dla content, security-review dla kodu, etc.]
- Amendment process: [jak zmieniac konstytucje]

## Compliance Map (mapowanie na zewnetrzne wymogi)
- AI Act art. ... (jesli dotyczy)
- RODO art. ... (jesli dotyczy)
- AGPL / MIT / CC BY-SA (licencja projektu)

**Version:** 0.1.0 | **Ratified:** YYYY-MM-DD | **Last Amended:** YYYY-MM-DD

Bramki MateMatic (zawsze pytaj zanim ratifikujesz konstytucje - znalezisko nie jest rekomendacja):

1. Licencja - jaka licencja projektu? Czy zgadza sie z licencjami zaleznosci?
2. ToS / anty-OS - czy projekt nie omija ToS dostawcow? Czy nie jest brand-toxic?
3. Jakosc - czy mamy kapitalu na utrzymanie? Czy nie zaczynamy 50 projektow na raz?
4. Strategia MateMatic - czy pasuje do drabinki sprzedazowej / vault Wieslawa / pozycjonowania?

Faza 2 - /mspec-spec <nazwa-feature> (Specify)

Output: .matematic/spec/<###-nazwa-feature>/spec.md

User stories + acceptance criteria. Bez kodu, bez tech stacku.

Struktura:

# Feature: [Nazwa]

**Branch:** `###-nazwa-feature` (sequential numbering: 001, 002, ...)
**Date:** YYYY-MM-DD
**Status:** Draft | Clarified | Planned | Implemented | Validated

## Problem statement (1 paragraf)
[Co boli, czyje zycie sie poprawi]

## User Stories (priorytety P1, P2, P3...)

### US1 (P1, MVP) - [Nazwa]
**Jako** [persona] **chce** [funkcja] **zeby** [korzysc].

**Acceptance Criteria:**
- [ ] AC1.1: ...
- [ ] AC1.2: ...

**Independent Test:** [jak sprawdzic ze TYLKO US1 dziala, bez US2/US3]

### US2 (P2) - ...
### US3 (P3) - ...

## Non-Goals (anti-scope)
- Tego NIE robimy w tej iteracji
- ...

## Anty-kryteria (stan idealny, nie cel) [wzorzec ISA]
- Co ma POZOSTAC prawdziwe po dostarczeniu (np. "testy istniejace nadal przechodza",
  "zero nowych zaleznosci", "PII nie opuszcza maszyny")
- Roznica vs Non-Goals: Non-Goals = czego nie budujemy; anty-kryteria = czego
  budowa nie moze ZEPSUC. Cel bez anty-kryteriow = maksymalizator spinaczy.

## Sondy falsyfikujace (per twierdzenie spec-a) [wzorzec ISA]
- Kazde twierdzenie "system robi X" dostaje sonde: KOMENDA/test, ktorej porazka
  by je OBALILA - i uwage, co by bylo falszywym potwierdzeniem
  (por. pamiec: sonda falszujaca wlasny wynik, 08-07)
- Twierdzenie bez sondy = opinia, nie spec. Oznacz `[NO-PROBE]` - do rozwiazania
  przed zamknieciem
- Sondy z tej sekcji staja sie harnessem odbioru w Fazie 4 - spec JEST testem

## Open Questions / NEEDS CLARIFICATION
- [ ] Pytanie 1
- [ ] Pytanie 2

Markery NEEDS CLARIFICATION przechodza do /mspec-clarify (opcjonalna pomocnicza komenda).

Regula zamkniecia (mgla): spec nie moze zostac zamkniety z niepustym NEEDS CLARIFICATION ani z [NO-PROBE] - to binarne fakty strukturalne (bramka HARD). Liczby "ile sond, ile anty-kryteriow" NIE sa bramka - wymuszony licznik to sfabrykowany licznik (linia Goodharta). Wzorce ISA/anty-kryteria/sondy: adaptacja z danielmiessler/LifeOS (MIT, rejestr ocen #74), doktryna ISAGate.

Faza 3 - /mspec-plan (Plan)

Output: .matematic/spec/<###-nazwa-feature>/plan.md + opcjonalnie research.md, data-model.md, contracts/

Technical Context + struktura projektu. Tu wybierasz project type.

Project types MateMatic (rozszerzone wobec spec-kit):

Project type	Kiedy	Struktura referencyjna
claude-skill	Nowy skill ~/.claude/skills/<name>/	SKILL.md + ewent. helpers
video-pipeline	Odcinek serialu / Akademii / MEMO	sceny per katalog, subagenci, ledger
MateMatic-mikroprodukt	EPUB Biblioteka, NotebookLM pack	input -> processing -> output, manifest
desktop-app	POAS, lokalne narzedzia kancelaryjne	Tauri/Electron + Rust/Python core + UI
web-app	PATRON UI, KGLF dashboard, www-matematic	backend/ + frontend/ + tests/
mobile-app	Jeszcze brak, ale gotowi	Native iOS/Android albo Capacitor
mcp-server	matematicsolutions/mcp-saos, nowe konektory	server.py + tools/ + manifest
library/cli	uv tool, gh extension, helper CLI	src/ + tests/ + pyproject.toml
agent-product	PATRON jako produkt, agent multi-kancelaria	core/ + agents/ + skills/ + memory/

Struktura plan.md:

# Plan: [Feature]

**Spec:** [link do spec.md]
**Project Type:** [wybor z tabeli wyzej]

## Technical Context
- **Language/Version:** Python 3.13, TypeScript 5.x, ... lub NEEDS CLARIFICATION
- **Primary Dependencies:** ...
- **Storage:** Supabase / SQLite / qdrant / .matematic-RAG / N/A
- **Testing:** pytest / vitest / playwright / brak
- **Target Platform:** Windows-first / Linux server / cross-platform
- **Performance Goals:** [domain-specific]
- **Constraints:** [RODO-safe / offline-capable / low-latency / ...]
- **Scale/Scope:** [n uzytkownikow, m dokumentow]

## Constitution Check (GATE - musi przejsc przed dalszym researchem)

| Bramka konstytucji | Status | Notatka |
|---|---|---|
| Mission alignment | [PASS/FAIL] | Czy projekt sluzy Mission MateMatic? |
| Article I (RODO-safe) | [PASS/FAIL/N/A] | ... |
| Article II (...) | [PASS/FAIL/N/A] | ... |
| Bramka licencji | [PASS/FAIL] | ... |
| Bramka ToS / anty-OS | [PASS/FAIL] | ... |
| Bramka jakosci | [PASS/FAIL] | ... |
| Bramka strategii | [PASS/FAIL] | ... |

Jesli `FAIL` - albo zmien feature, albo udokumentuj w **Complexity Tracking** ponizej.

## Project Structure
[Drzewo katalogow ad-hoc dla wybranego project type]

## Research notes
[Co sprawdzilismy - alternatywy, benchmarki, ocena repo]

## Complexity Tracking (tylko jesli violations)

| Violation | Why Needed | Simpler Alternative Rejected Because |
|---|---|---|
| ... | ... | ... |

Faza 4 - /mspec-zadania (Tasks)

Output: .matematic/spec/<###-nazwa-feature>/tasks.md

Format: [ID] [P?] [Story] Description

• [P] = parallel-safe (different files, no dependencies). Dla MateMatic = mozna zlecic rownoleglemu subagentowi.
• [US1] = story tag dla traceability.
• Sciezki plikow MUSZA byc absolutne lub relatywne do roota projektu.

5 faz wykonania:

## Phase 1 - Setup
- [ ] T001 Init projektu / branch / katalogi
- [ ] T002 [P] Konfiguracja linterow
- [ ] T003 [P] Setup test runner

## Phase 2 - Foundational (BLOKUJE wszystkie user stories)
- [ ] T004 Schema bazy / wspolne modele
- [ ] T005 [P] Auth / autoryzacja
- [ ] T006 Logger / observability

## Phase 3 - US1 (P1, MVP) - [nazwa]
- [ ] T010 [P] [US1] Model w src/models/...
- [ ] T011 [US1] Service w src/services/... (depends T010)
- [ ] T012 [US1] Endpoint / komenda / UI

**Checkpoint:** US1 niezaleznie testowalne, deployowalne jako MVP.

## Phase 4 - US2 (P2) - ...
## Phase 5 - US3 (P3) - ...

## Phase N - Polish
- [ ] TXXX [P] Dokumentacja / README
- [ ] TXXX Performance tuning
- [ ] TXXX Marko-pl review (jesli tresc tekstowa)
- [ ] TXXX [P] Security review

## Parallel Opportunities
[Eksplicite ktore taski mozna odpalic na raz - dla orchestratora subagentow]

Wazne dla MateMatic:

• Markery [P] w tasks.md to formalny input dla orkiestratora pipeline'u wideo - mowi orchestratorowi ktore subagenty palic rownolegle (zamiast manualnie projektowac graf questow).
• US1 jako MVP = zawsze pierwsza ratowalna wartosc, nawet jesli reszta poslizgnie sie.
• Phase 2 (Foundational) BLOKUJE - to bardzo wazne, nie pomijac, inaczej downstream taski sie sypia (jak w PATRON gdzie wpierw brakowalo Supabase self-host).

Walidacja (opcjonalne) - /mspec-analyze

Output: .matematic/spec/<###-nazwa-feature>/analyze-report.md

Cross-artifact consistency check. Uruchamiac po /mspec-zadania, przed implementacja. Sprawdza:

• Czy wszystkie AC z spec.md maja odpowiadajace taski w tasks.md?
• Czy plan.md respektuje konstytucja.md (re-check Constitution Check GATE)?
• Czy taski oznaczone [P] faktycznie nie maja shared-file conflicts?
• Czy projekt nie ma niezamknietych NEEDS CLARIFICATION?

---

SEMVER konstytucji

Za kazdym razem gdy zmieniamy konstytucja.md:

• MAJOR (1.x.x -> 2.0.0) - usuniecie/zmiana fundamentalnego Article
• MINOR (x.1.x -> x.2.0) - dodanie nowego Article lub Section
• PATCH (x.x.1 -> x.x.2) - doprecyzowanie istniejacego Article bez zmiany semantyki

Footer:

**Version:** 1.2.0 | **Ratified:** 2026-05-20 | **Last Amended:** 2026-06-15

Plus changelog ## Amendments w samej konstytucji (audyt-friendly per AI Act art. 12).

---

Konwencje plikow

<project-root>/
├── .matematic/
│   ├── konstytucja.md                        # SEMVER, ratifikowana
│   └── spec/
│       ├── 001-pierwsza-ficzura/
│       │   ├── spec.md
│       │   ├── plan.md
│       │   ├── research.md       (opcjonalnie)
│       │   ├── data-model.md     (opcjonalnie)
│       │   ├── contracts/        (opcjonalnie - API/MCP/CLI)
│       │   ├── tasks.md
│       │   └── analyze-report.md (opcjonalnie)
│       ├── 002-druga-ficzura/
│       └── ...
└── (reszta projektu)

NIE myl z .specify/ (to katalog spec-kit CLI z sandbox). My uzywamy .matematic/ zeby nie mieszac.

.gitignore - nic z .matematic/ nie ignorujemy (artefakty governance = first-class).

---

Notatki mikro-decyzji (alternatywa dla pelnego cyklu)

Wzorzec zapozyczony z stablyai/orca - plaski folder docs/ z dziesiatkami malych, jednostronicowych notatek per-feature (worktree-delete-preflight.md, orchestration-reset-scope-validation.md) zamiast pelnego ADR/konstytucji dla kazdej drobnej zmiany. Wypelnia luke: pelny cykl 4-fazowy ponizej jest za ciezki dla poprawki na <1 dzien pracy, wiec takie zmiany czesto NIE dostaja zadnej dokumentacji - a to jest gorsze niz lekka notatka.

Kiedy notatka wystarczy (NIE trzeba pelnego cyklu):

• Zmiana <1 dzien pracy, jeden plik/modul, brak nowego ADR-worthy decyzji
• Nie zmienia kontraktu API/MCP/CLI (jesli zmienia - patrz Constitution Check GATE)
• Nie dotyczy Article z konstytucji projektu (jesli dotyczy - to jest ADR-worthy)

Konwencja: notes/<data>-<krotki-slug>.md w korzeniu projektu (analogicznie do docs/ w orca, u nas notes/ zeby nie kolidowac z istniejacym docs/). Szablon (jedna strona, max ~30 linii):

# <Tytul decyzji/zmiany>

**Data:** <ISO 8601>
**Kontekst:** <1-2 zdania - jaki problem/potrzeba>
**Decyzja:** <co zrobiono, 1 akapit>
**Alternatywy odrzucone:** <opcjonalnie, 1 zdanie kazda>
**Wplyw:** <pliki/moduly dotkniete>

Jesli w trakcie pisania notatki okazuje sie ze zmiana jednak dotyka Article konstytucji lub kontraktu API - eskaluj do pelnego ADR/spec, nie zostawiaj tego w notes/.

Czego ten skill NIE robi

• NIE instaluje specify-cli (to faza B, juz zrobiona w sandboxie).
• NIE generuje plikow automatycznie - Claude (ty) piszesz konstytucja.md/spec.md/plan.md/tasks.md na podstawie templates w tej instrukcji, w rozmowie z Wieslawem.
• NIE wymaga .claude/skills/speckit-* w projekcie - to skill samowystarczalny.
• NIE zastapuje matematic-konstytucja-ai - tamten = sprzedaz, ten = wewnetrzny dev.
• NIE zastapuje pipeline'u wideo - tamten = orkiestracja runtime, ten = projekt artefaktow planu. Wspolpraca: tasks.md z [P] jest INPUTEM dla pipeline'a.

---

Powiazania z reszta stack MateMatic

Skill / proces	Jak wspolpracuje
matematic-konstytucja-ai	Brat-blizniak (produkt klient vs dev nasz). Wspolny rdzen, inny target audience.
pipeline wideo	tasks.md -> graf questow orchestratora. [P] markery -> fan-out subagentow.
governance pipeline'u wideo	4 fazy validation (pre-compose / render / post / distribution) wbudowane w /mspec-analyze dla projektow video-pipeline.
marko-pl-content	Auto-dorzucany jako reviewer w ## Governance konstytucji projektow tresciowych.
recenzent kodu	Auto-dorzucany dla projektow kodowych (PATRON / KGLF / POAS).
KGLF	KGLF jako Reference Implementation - juz ma ADR-y, jest dobrym kandydatem na pierwszy projekt z .matematic/konstytucja.md (rozszerzajacy ADR-y SEMVER konstytucja).

---

Pierwsze 2 walidacje w boju (rekomendacja)

1. Nowy konektor SAOS w PATRON - czysty greenfield, dobry test dla /mspec-spec + /mspec-plan z project type mcp-server.
2. Biblioteka EPUB v3 (jesli planujemy 3-ci tom) - prosta domena, test dla project type MateMatic-mikroprodukt.

NIE testowac na PATRON core ani KGLF (oba juz maja ADR-y, ryzyko podwojnego trackingu).

---

Dziennik szlifu

• 2026-05-20 - v0.1.0 - ratyfikacja. Skill powstal po fazie B (sandbox install spec-kit). Decyzja: dwa osobne skille (sprzedazowy matematic-konstytucja-ai + dev matematic-spec-driven) zamiast jednego rozszerzonego. Project types rozszerzone o claude-skill / video-pipeline / desktop-app / mcp-server / MateMatic-mikroprodukt (korekta Wieslawa: "aplikacje też możemy zacząć robić, nie ograniczaj nas"). Walidacja w boju czeka.

Wspólne reguły wtyczki dev-mcp (Dev-mcp)

Te reguły obowiązują w każdym skillu tej wtyczki, także gdy sam skill milczy. Są skopiowane do każdego skilla, więc działają zarówno po instalacji całej wtyczki, jak i pojedynczego skilla.

Plugin to narzędzia deweloperskie MateMatic: spec-driven development, kanon budowy MCP serverów, recenzent PR dla LegalTech, generator instalatora marketplace. Skierowany do osób budujących, nie do prawnika końcowego.

Reguły

• Wynik to projekt. Specyfikacje, recenzje i instalatory są punktem wyjścia, sprawdza je człowiek przed użyciem.
• Recenzja nie zastępuje testów. Recenzent PR wskazuje ryzyka (org scoping, audit_log, grounding, PII w logach); nie gwarantuje poprawności - kod nadal trzeba przetestować.
• Sekrety. Przy budowie MCP i recenzji kodu nie umieszczaj kluczy ani danych klienta w przykładach, logach ani promptach.

Zakres pluginu

Plugin daje warsztat deweloperski (advanced). Nie jest narzędziem do pracy prawnej - do tego są pozostałe pluginy huba.