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
edit-article albo linkedin-voice-wieslaw-mazur)
- Pojedynczy bugfix / refactor w juz dzialajacym module
- MEMO Ej Aj (uzyj
memo-production-pipeline)
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]
...
## 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: [wewnetrzny senior review 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, per regule "discovery to nie rekomendacja" - 4 bramki kanonu):
- Licencja - jaka licencja projektu? Czy zgadza sie z licencjami zaleznosci?
- ToS / anty-OS - czy projekt nie omija ToS dostawcow? Czy nie jest brand-toxic?
- Jakosc - czy mamy kapitalu na utrzymanie? Czy nie zaczynamy 50 projektow na raz?
- 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
- ...
## Open Questions / NEEDS CLARIFICATION
- [ ] Pytanie 1
- [ ] Pytanie 2
Markery NEEDS CLARIFICATION przechodza do /mspec-clarify (opcjonalna pomocnicza komenda).
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 w .claude/skills/ (podkatalog o nazwie skilla) | 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 Wewnetrzny senior 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 wewnetrznego orchestratora pipeline'a wideo MateMatic - 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:** 2025-05-20 | **Last Amended:** 2025-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).
Czego ten skill NIE robi
- NIE instaluje specify-cli (to wczesniejsza faza B - sandbox install).
- 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 wewnetrznego pipeline'a wideo MateMatic - 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. |
| matematic video pipeline (internal) | tasks.md -> graf questow orchestratora. [P] markery -> fan-out subagentow. |
matematic-video-governance | 4 fazy validation (pre-compose / render / post / distribution) wbudowane w /mspec-analyze dla projektow video-pipeline. |
| wewnetrzny senior review MateMatic | Auto-dorzucany jako reviewer w ## Governance konstytucji projektow tresciowych. |
anthropic-skills:matematic-reviewer | Auto-dorzucany dla projektow kodowych (PATRON / KGLF / POAS). |
| KGLF (Knowledge Graph for Law Firms) | 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)
- Nowy konektor SAOS w PATRON (planowany od 2026-05-19) - czysty greenfield, dobry test dla
/mspec-spec + /mspec-plan z project type mcp-server.
- 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.
