Matematic Spec Driven

---
name: matematic-spec-driven
description: Spec-Driven Development dla wewnetrznych projektow MateMatic (PATRON, KGLF, POAS, skille, mikroprodukty, aplikacje). Cherry-pick + adaptacja patternu github/spec-kit (MIT) - 4 fazy (Konstytucja -> Specyfikacja -> Plan -> Zadania) plus opcjonalna walidacja. Wbudowany Constitution Check GATE z 4 bramkami MateMatic (licencja / ToS-antyOS / jakosc / strategia). Marker `[P]` dla zadan parallel-safe (fan-out subagentow). Uzywaj gdy zaczynasz nowy projekt MateMatic, dodajesz duza ficzer do PATRON/KGLF, planujesz odcinek serialu wymagajacy formalnego rozbicia zadan, projektujesz nowy mikroprodukt, lub gdy chcesz audytowac istniejacy projekt pod katem zgodnosci z konstytucja MateMatic. Trigger - "spec-driven", "konstytucja projektu", "rozplanuj projekt", "rozbij na zadania", "zaplanuj ficzer", "spec dla projektu", "plan implementacji", "tasks z markerem P", "audyt projektu MateMatic", "Constitution Check". NIE uzywaj dla sprzedazy klientom kancelaria (do tego jest `matematic-konstytucja-ai` - produkt 15-40k PLN).
license: Apache-2.0
allowed-tools: [Read, Write, Glob]
data-residency: local
requires-human-approval: false
pii-egress: none
attribution:
  source: github/spec-kit
  url: https://github.com/github/spec-kit
  license: MIT
  relationship: adaptation
  note: >
    Wersja v0.8.12.dev0: 4-fazowa metodyka Konstytucja -> Specyfikacja -> Plan ->
    Zadania, marker [P] dla zadan parallel-safe oraz Constitution Check GATE.
    Adaptacja: ton polski, project-types MateMatic (claude-skill, video-pipeline,
    desktop-app, mcp-server, mikroprodukt) i 4 wlasne bramki
    (licencja / ToS-antyOS / jakosc / strategia).
metadata:
  author: Wieslaw Mazur / MateMatic
  version: 0.1.0
  ratified: 2026-05-20
  project: MateMatic Internal Dev Pipeline
  related_skill: matematic-konstytucja-ai (sprzedazowy produkt dla kancelarii, NIE myl)
  delivery_format: pliki markdown w katalogu projektu (.matematic/spec/<feature>/)
---

# 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:

```markdown
# [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:

```markdown
# 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`:

```markdown
# 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:

```markdown
## 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:

```markdown
**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):

```md
# <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.