Strona toolchain i /monolynx:setup: konfiguracja przed pierwszym ticketem

Po co agentowi strona toolchain?

Agent nie zna Twojego projektu. Nie wie, czy testy idą przez pytest, npm test czy make test, ani czy wolno je uruchomić poza kontenerem. Strona toolchain jest jedynym miejscem, z którego komendy work i work-simple biorą te informacje. Zapisujesz ją raz na projekt.

6sekcji strony toolchain

1strona na projekt, zawsze pod adresem toolchain

7punktów, które sprawdza /monolynx:setup

0komend, które project-toolchain uruchamia, żeby je sprawdzić

Kto zapisuje stronę toolchain i kto ją czyta

Stronę zapisuje komenda project-toolchain po Twoim potwierdzeniu. Czytają ją komendy work i work-simple przy każdym tickecie, setup przy kontroli konfiguracji, sprint-end przy testach mutacyjnych i create-mutation-ci-script przy generowaniu etapu CI.

flowchart LR
  A["project-toolchain"] -- "zapis po potwierdzeniu" --> B["Strona wiki Toolchain"]
  B --> C["work i work-simple: lint i testy"]
  B --> D["setup: kontrola sekcji"]
  B --> E["sprint-end: testy mutacyjne"]
  B --> F["create-mutation-ci-script: etap CI"]

Jak wygląda cała strona toolchain?

Poniżej pełna strona dla projektu w Pythonie uruchamianego w Dockerze. Nagłówki sekcji i etykiety pól są stałe. Zmieniają się tylko wartości po dwukropku.

Strona wiki Toolchain: projekt w Dockerze

# Toolchain projektu

Stack: Python 3.12, FastAPI
Uruchamianie: docker

## Lint

komenda: docker compose exec app ruff check .
kto odpala: agent

## Test

komenda: docker compose exec app pytest
kto odpala: agent
testy istnieja: tak
framework: pytest
pełny przebieg: lokalnie

## Worktree

lint: docker compose -p sklep --profile dev run --rm --no-deps -v "$PWD":/app app ruff check .
test: docker compose -p sklep --profile dev run --rm --no-deps -v "$PWD":/app app pytest
izolacja testów: brak

## TDD

stosowac: nie

## Mutacje

narzedzie: brak
powod: nie zainstalowane

## Uwagi

Wszystko przez docker compose exec app - nigdy lokalnie

Projekt bez Dockera ma tę samą stronę, tylko krótszą. Sekcja ## Worktree odsyła wtedy do komend z sekcji wyżej.

Sekcje Lint, Test i Worktree: projekt bez Dockera

## Lint

komenda: npm run lint
kto odpala: agent

## Test

komenda: npm test
kto odpala: agent
testy istnieja: tak
framework: vitest
pełny przebieg: lokalnie

## Worktree

lint: jak wyzej
test: jak wyzej
izolacja testów: tak

Co znaczy każde pole?

Pola dzielą się na trzy grupy: komendy, decyzje o tym, kto je uruchamia, i wiedzę o projekcie.

Sekcja	Pole	Dozwolone wartości	Co z niego wynika
Lint, Test	`komenda`	dokładna komenda	to uruchamia agent albo wypisuje dla Ciebie
Lint, Test	`kto odpala`	`user` albo `agent`	`user`: agent wypisuje komendę i czeka na wynik
Test	`testy istnieja`	`tak` albo `nie`	mówi agentowi, czy projekt ma już testy
Test	`pełny przebieg`	`lokalnie` albo `ci`	gdzie idzie pełny zestaw testów przed zamknięciem ticketu
Worktree	`lint`, `test`	komenda albo `jak wyzej`	komendy dla kopii repozytorium, w której pracuje sesja w tle
Worktree	`izolacja testów`	`tak` albo `brak`	czy testy z dwóch kopii mogą iść jednocześnie
TDD	`stosowac`	`tak` albo `nie`	przy `tak` testy powstają przed implementacją
Mutacje	`narzedzie`	nazwa z wersją albo `brak`	czy projekt ma testy mutacyjne
Uwagi	dowolny tekst	-	reguły repozytorium, na przykład "tylko przez Docker"

Dlaczego sekcja Worktree ma osobne komendy?

Sesje sprintu pracują w osobnych kopiach repozytorium, czyli w worktree. Komenda docker compose exec wchodzi do działającego kontenera, a ten ma zamontowany Twój główny katalog. Uruchomiona z kopii sprawdziłaby więc nie ten kod, nad którym pracuje agent.

Cecha	`docker compose exec`	`docker compose run` z sekcji Worktree
Który kod sprawdza	główny katalog repozytorium	bieżącą kopię, zamontowaną opcją `-v`
Kontener	już działający	jednorazowy, usuwany po przebiegu
Kiedy używana	praca w głównym katalogu	praca w worktree, wybierana automatycznie
Wymaganie	działający stack	działający stack głównego katalogu

Komenda work sama rozpoznaje, że działa w worktree, i wtedy bierze komendy z tej sekcji. Zapis "$PWD" zamienia przed uruchomieniem na literalną ścieżkę kopii.

Co znaczy izolacja testów?

Pole odpowiada na jedno pytanie: czy dwa przebiegi testów z dwóch kopii repozytorium dzielą stan, na przykład bazę o stałej nazwie albo ten sam port.

Wartość	Znaczenie	Co robi `work`
`tak`	przebiegi nie dzielą stanu albo rozdziela je parametr w komendzie `test`	uruchamia testy bez kolejki
`brak`	przebiegi dzielą stan i nie ma parametru, który by go rozdzielił	ustawia testy w kolejce, jeden przebieg naraz

Gdy projekt ma parametr izolacji, komenda test w sekcji Worktree zawiera znacznik <KEY>. Sesja zamienia go na klucz swojego ticketu, więc każdy ticket dostaje własną bazę testową.

Pełny przebieg: lokalnie czy w CI?

W dużym projekcie pełny zestaw testów trwa długo. Pole pełny przebieg pozwala przenieść go do pipeline'u merge requesta.

Cecha	`lokalnie`	`ci`
Lint	pełny, w sesji ticketu	pełny, w sesji ticketu
Testy w sesji ticketu	cały zestaw	tylko zmieniony obszar
Pełny zestaw	w sesji, po ostatniej zmianie	w pipeline'ie merge requesta
Wymagane flagi	brak dodatkowych	`MONOLYNX_AUTOCOMMIT`, `MONOLYNX_AUTOPUSH` i `MONOLYNX_AUTOMR` na `true`
Kiedy ticket trafia do Review	po zielonych testach	dopiero po otwarciu merge requesta

Jak powstaje strona toolchain?

Stronę zapisuje komenda /monolynx:project-toolchain. Uruchamiasz ją w katalogu repozytorium, bez argumentów.

Sprawdzenie stanu
Komenda szuka strony o tytule Toolchain. Gdy istnieje, pokazuje jej treść i pyta, czy ją zaktualizować.
Wykrycie stacku
Komenda czyta pliki konfiguracyjne w repozytorium: Makefile, pyproject.toml, package.json, Cargo.toml, go.mod i podobne. Target z Makefile wygrywa z komendą domyślną.
Potwierdzenie
Wykryte komendy widzisz w tabeli i odpowiadasz na pytania: czy się zgadzają, kto je uruchamia, czy stosować TDD, jak z izolacją testów i gdzie idzie pełny przebieg.
Narzędzie mutacyjne
Krok opcjonalny. Komenda sprawdza, czy narzędzie jest zainstalowane, i pyta o moduły rdzenia. Niczego nie instaluje.
Zapis
Strona trafia do wiki projektu z tytułem Toolchain. Na końcu dostajesz podsumowanie i link.

Pytanie o potwierdzenie wykrytych komend (przykład)

> /monolynx:project-toolchain

Wykryty stack: Python 3.12, FastAPI (docker)

| | Komenda |
| Lint | docker compose exec app ruff check . |
| Test | docker compose exec app pytest |
| Worktree | docker compose -p sklep --profile dev run --rm ... |
| Izolacja testów między worktree | brak - fixture zakłada bazę o stałej nazwie |
| Pełny przebieg testów | lokalnie - 14 plików testowych, brak etapu testów w CI |

Testy w repo: znaleziono 14 plików

1. Komendy się zgadzają? (tak / podaj poprawne)
2. Kto uruchamia lint i testy: user czy agent?
3. Stosować TDD? (tak / nie)
4. Izolacja testów się zgadza? (tak / podaj poprawną)
5. Pełny przebieg testów: lokalnie czy ci?

Co sprawdza /monolynx:setup?

Komenda /monolynx:setup jest listą kontrolną projektu. Sprawdza siedem punktów, każdy oznacza jako OK albo BRAK i przy brakach wskazuje komendę naprawczą.

Punkt	Co sprawdza	Komenda naprawcza
1. Slug projektu	czy repozytorium wie, z którym projektem pracuje	brak; ustawiasz zmienną sam
2. Strona `toolchain`	cztery z sześciu nagłówków (`Lint`, `Test`, `Worktree`, `Mutacje`) i pole `izolacja testów`	`/monolynx:project-toolchain`
3. LLM Wiki	czy metoda jest włączona w projekcie	`/monolynx:wiki-init`
4. Graf zależności w CI	czy CI synchronizuje graf kodu	`/monolynx:create-graph-ci-script`
5. Testy mutacyjne w CI	czy CI ma etap mutacji	`/monolynx:create-mutation-ci-script`
6. Flagi `MONOLYNX_*`	które są ustawione i gdzie	brak; to informacja, nie stan do naprawy
7. CLI `monolynx`	instalacja, logowanie, wersja, lista dozwolonych komend	brak; dostajesz komendy do uruchomienia

Wynik setup w projekcie ze starszą stroną toolchain (przykład)

> /monolynx:setup

| Punkt | Stan | Skill naprawczy |
| 1. Slug projektu | OK (sklep) | - |
| 2. Strona wiki toolchain | BRAK (brakuje: ## Worktree, ## Mutacje) | /monolynx:project-toolchain |
| 3. LLM Wiki | OK | /monolynx:wiki-init |
| 4. Graf zależności w CI | BRAK | /monolynx:create-graph-ci-script |
| 5. Testy mutacyjne w CI | BRAK | /monolynx:create-mutation-ci-script |
| 6. Flagi MONOLYNX_* | INFO (3 jawnie ustawione) | - |
| 7. CLI monolynx | OK (0.4.0, zalogowane, aktualne, allowlista) | - |

Po tabeli komenda pyta, które braki naprawić. Wybrane komendy naprawcze woła po kolei, w stałej kolejności: najpierw project-toolchain, potem wiki-init, graf i na końcu mutacje. Kolejność ma znaczenie, bo etap mutacji w CI czyta sekcję ## Mutacje ze strony toolchain.

Które punkty są naprawdę potrzebne przed pierwszym ticketem?

Do pierwszego ticketu wystarczą punkty 1 i 2: slug projektu i strona toolchain.

Punkt 3 jest potrzebny, gdy chcesz, żeby wiedza z ticketów trafiała do wiki. Punkty 4 i 5 dotyczą projektów z CI. Punkt 7 przyspiesza pracę, ale komendy działają też bez CLI, przez samo połączenie MCP.

Sekcja ## Mutacje z wartością narzedzie: brak ma stan OK. Liczy się obecność sekcji, bo brak narzędzia to świadoma decyzja właściciela repozytorium.

Najczęstsze pytania

Czy mogę napisać stronę toolchain ręcznie?

Tak, o ile zachowasz tytuł Toolchain, nagłówki sekcji i etykiety pól dokładnie tak jak w przykładzie. Bezpieczniej uruchomić /monolynx:project-toolchain i poprawić wartości w odpowiedzi na pytania.

Co zrobić po zmianie komendy testów w projekcie?

Uruchom /monolynx:project-toolchain ponownie. Komenda pokaże obecną stronę, zapyta o aktualizację i zapisze nową treść pod tym samym adresem.

Czy project-toolchain uruchomi moje testy, żeby je sprawdzić?

Nie. Komenda niczego nie uruchamia poza odpytaniem narzędzia mutacyjnego o jego pomoc i wersję. Konfiguracja nie jest testem, a lint na niezapisanych zmianach dałby mylący wynik.

Setup pokazuje BRAK przy stronie, która istnieje. Dlaczego?

Strona powstała w starszej wersji pluginu i brakuje jej sekcji ## Worktree, ## Mutacje albo pola izolacja testów. Tabela wymienia brakujące elementy. Uruchom /monolynx:project-toolchain, żeby je dopisać.

Jak często uruchamiać setup?

Po instalacji pluginu, po jego aktualizacji i wtedy, gdy coś przestaje działać. Komenda tylko czyta, więc możesz ją uruchomić w dowolnej chwili.

Słownik i następny krok

Toolchain: strona wiki projektu z komendami lintu i testów oraz zasadami ich uruchamiania
Worktree: osobna kopia repozytorium na dysku, w której pracuje sesja jednego ticketu
Izolacja testów: cecha projektu: czy dwa równoległe przebiegi testów nie wchodzą sobie w drogę
Pełny przebieg: uruchomienie całego zestawu testów, a nie tylko testów zmienionego obszaru
Slug projektu: krótka nazwa projektu w adresach i w komendach
Komenda naprawcza: komenda pluginu, która uzupełnia brak wskazany przez setup

Założenie konta, projektu i instalację pluginu opisuje wpis Pierwszy projekt w Monolynx. Flagi z punktu 6 wyjaśnia wpis Konfiguracja: które zmienne gdzie ustawić. Gdy strona jest gotowa, przejdź do wpisu Pierwszy ticket ręcznie.

Chcesz zobaczyć, gdzie w projekcie mieszka strona toolchain?

Zobacz moduł Wiki w Monolynx