Memorandum techniczne

KR-TM-1.2

Specyfikacja 1.2 · XI 2026

Dystrybucja: bez ograniczeń · MIT

Bramkowane procedury dostarczania kodu z agentami AI

Żadnego „gotowe” bez dowodów.

Kuznia Relay to otwarta procedura dostarczania prawdziwych funkcjonalności z Claude Code, Codex lub dowolnym CLI agenta. Świeży agent na każdy krok, każda kontrola oddzielona od poprawki, a każde twierdzenie poparte dowodami w plikach: hashe z gita, diff stat, wyniki testów. Niech koordynator prowadzi pętlę w nocy, a ty przeczytaj podsumowanie przy kawie. Albo zatwierdzaj każdą bramkę sam.

Zacznij w 5 minut Gwiazdka na GitHubie

Zwykły Markdown i git. Bez serwera, bez konta, nic do instalowania.

Log sztafety · P1-T1 Version flag na żywo

COORD› prompt P1-T1

PLANNERwrote Workflow/Prompts/P1-T1 - 4 Review.md

P1-T1 - 4 Review: read and follow /home/you/kb/…/P1-T1 - 4 Review.md

AGENTfresh session · detached worktree · origin/wip/p1-t1-version-flag @ 3904ade

F3 should fix commit adds __pycache__/*.pyc

Ran 6 tests in 0.000s OK

Verdict: fix round needed: F3

COORD› report P1-T1

PLANNERF3 → fix: spec fix (.gitignore), then 3 Build (2), 4 Review (2)

COORD› ▍

RYS. 1.— Jeden etap sztafety z przykładu w repozytorium. Agent Review nigdy nie widział sesji Build. Werdykt jest w ostatniej linii, więc koordynator może go odczytać i uruchomić następny krok.

1.0

Raport rozbieżności

Długie sesje agentów zawodzą po cichu.

Znasz to. Agent pracuje godzinę, potem melduje sukces. Okno kontekstu się zapełniło, wczesne decyzje zniknęły, a ta sama sesja, która napisała kod, właśnie go zrecenzowała.

DryfD-1

Długie sesje zapominają, co ustalono na początku. Zakres rozrasta się po cichu.

Sam sobie recenzentemD-2

Autor ocenia własną pracę. Znajduje to, czego się spodziewa.

Deklaracje zamiast dowodówD-3

„Wszystkie testy przechodzą” bez komendy, bez liczby, bez hasha commita.

Typowa deklaracja z czatu

„Zaimplementowałem flagę wersji i zaktualizowałem testy. Wszystko działa, wszystkie testy przechodzą! Funkcjonalność gotowa. ✅”

RYS. 2a.— Tyle zwykle dostajesz. Który commit? Które testy? Kto sprawdził?

Reports/P1-T1 - 3 Build (2).md · fragment

commits: c66916d [P1-T1] Fix F3
git diff --stat:
 .gitignore                             | 1 +
 __pycache__/greet.cpython-313.pyc      | Bin 1496 -> 0 bytes
 __pycache__/test_greet.cpython-313.pyc | Bin 3369 -> 0 bytes
proof: git ls-files __pycache__  (empty)
python3 -m unittest -q
Ran 6 tests in 0.000s
OK
push: wip/p1-t1-version-flag -> wip/p1-t1-version-flag

RYS. 2b.— Co oddaje agent Relay: prawdziwy wynik komend, w pliku, który możesz później sprawdzić.

2.0

Gdzie to pasuje

Brakujący etap między ticketem a pull requestem.

Relay nie zastępuje twojego agenta, edytora ani code review. To procedura wokół nich: jak wymaganie staje się zrecenzowanym, przetestowanym i scalonym commitem na gałęzi funkcjonalności, gotowym do PR, który i tak otwierasz.

Wejście

Ticket

Wymagania, kryteria akceptacji, projekt

Kuznia Relay

01Analyze
02Spec check
03Build
04Review
05Done

Świeży agent na krok · stan w bazie wiedzy w Markdownie · bramki zatwierdza delegowany koordynator lub ty

Wyjście

Pull request

Gałąź funkcjonalności, każde zadanie scalone, otagowane i udokumentowane

RYS. 3.— Relay pracuje na gałęzi funkcjonalności, jedno zadanie naraz. Gdy każde zadanie jest Done, otwierasz PR do gałęzi bazowej. Agenci nigdy tego nie robią.

Już używasz agentów

Claude Code, Codex albo dowolne CLI, które przeczyta plik i uruchomi gita.

Twoje funkcjonalności trwają wiele sesji

Najlepiej sprawdza się przy pracy za dużej na jedno okno kontekstu.

Ktoś musi zaufać wynikowi

Recenzent, klient albo ty za trzy miesiące, czytając ślad w dokumentach.

Chcesz kontroli bez niańczenia

Zatwierdzaj ręcznie albo deleguj czyste kontrole koordynatorowi. Zmiany zakresu zawsze zatrzymują się na tobie.

3.0

Plan lotu

Pięć kroków. Dwie bramki. Jedna pałeczka.

Każde zadanie przechodzi Analyze → Spec check → Build → Review → Done. Każdy krok to nowa sesja agenta, która czyta swój prompt z bazy wiedzy, robi dokładnie jedną rzecz i pisze jeden raport. Wybierz krok.

Kto: Świeży agent, tylko do odczytu
Wynik: Odpowiedzi na pytania z promptu, z odwołaniami plik:linia
Warunek wyjścia: Pytania mają odpowiedzi albo trafiły do Właściciela
Gdzie działa: Jednorazowy, odłączony worktree we własnym folderze roboczym

Poglądowo · przykład pomija Analyze

## Findings or changes
- Q1: where are CLI flags defined?  greet.py:5-10 (build_parser)
- Q2: are flags tested end to end?  no; test_greet.py:6-10 calls greet() directly

RYS. 4.— Dwie bramki: zatwierdzenie specyfikacji przed Build i zatwierdzenie kodu (ze wskazaniem zrecenzowanego commita) przed Done. Delegowane koordynatorowi albo twoje.

Jak przebiega runda

Koordynator (albo ty) rozmawia z planistą (dowolną sesją LLM) prostymi komendami. Planista pisze prompt i zwraca jedną linię do wklejenia świeżemu agentowi. Agent odpowiada raportem w pliku. Nic ważnego nie żyje w oknie czatu.

1.Koord.prompt P1-T1
2.Planistapisze Workflow/Prompts/P1-T1 - 1 Analyze.md, odpowiada jedną linią do wklejenia
3.Koord.uruchamia świeżego agenta z tą linią
4.Agentwykonuje krok, pisze Workflow/Reports/P1-T1 - 1 Analyze.md
5.Koord.report P1-T1
6.Planistaczyta dowody, aktualizuje kartę, Board, Plan, Decisions. Mówi, co dalej

Tryby lotu: autopilot albo ręcznie

Procedura jest taka sama w obu trybach. Zmienia się tylko to, kto otwiera bramki.

AutopilotZalecany · rozszerzenie koordynatora

Sesja koordynatora prowadzi pętlę za ciebie, także w nocy.

—Na start: uporządkowana lista zadań i Done: yes albo no
—Zatwierdza czyste kontrole, jeśli mu to delegujesz. Każde zatwierdzenie trafia do Decisions.md z oznaczeniem do przeglądu
—Zostawia krótkie poranne podsumowanie każdego zadania: co poszło, co zdecydował bez ciebie, czym zająć się najpierw

RęczniePełna kontrola

Sam wysyłasz każdą komendę i otwierasz każdą bramkę.

—prompt, wklej linię świeżemu agentowi, report
—approve specyfikacji, approve zrecenzowanego commita
—Najlepszy na pierwsze funkcjonalności albo kod, któremu jeszcze nie ufasz

Zawsze zatrzymuje się na tobiePytania do klienta lub interesariuszy, zmiany zakresu lub wymagań, limit rund i wszystko, co ryzykowne: force push, konflikt przy merge, czerwone testy po merge. Koordynator odkłada takie zadanie i bierze następne. Przeczytaj rozszerzenie.

4.0

Przydział załogi

Jasne role. Jeden autor na plik.

Każdy plik w bazie wiedzy ma dokładnie jednego autora. Agenci piszą tylko własny raport, więc dwie sesje nigdy nie walczą o ten sam dokument.

Rola	Kto	Robi	Nigdy nie robi
Właściciel Kierownik lotu	Ty, inżynier. Jeden na projekt.	Zakłada gałęzie, zatwierdza specyfikacje i kod albo to deleguje, decyduje o zakresie	Ręcznie edytuje historię kroków zadania
Planista Capcom	Sesja LLM w bazie wiedzy	Pisze plany, specyfikacje i prompty. Czyta raporty. Aktualizuje karty, Board, Decisions	Zmienia repozytorium kodu albo uruchamia agentów
Agent Załoga, świeża na każdy etap	Nowa sesja agenta kodującego na każdy krok	Czyta swój prompt, wykonuje dokładnie jeden krok, pisze jeden raport	Edytuje inne pliki bazy wiedzy, pushuje gdzie indziej, otwiera PR
Koordynator Opcjonalnie · autopilot	Długo działająca sesja LLM, jedna na funkcjonalność	Prowadzi pętlę: wysyła komendy planiście, uruchamia świeżych agentów, zatwierdza czyste kontrole, gdy ma delegację, pisze poranne podsumowania	Edytuje kod lub dokumenty zadań albo mija punkt zatrzymania

5.0

Pętla kontroli i poprawek

Kontrole znajdują. Rundy poprawek poprawiają.

Kontrola nigdy nie zmienia tego, co kontroluje. Ta jedna zasada usuwa większość przypadków „zrecenzowałem i przy okazji po cichu przepisałem”.

KontrolaA

Świeży agent znajduje i zapisuje. Nigdy nie poprawia ani tego nie proponuje.

ZapisB

Planista kopiuje uwagi do karty. Blocker / should fix → fix. Nit → later.

PoprawkaC

Runda o wąskim zakresie: tylko wskazane ID, jeden commit, test, który najpierw nie przechodzi, na każdą uwagę.

Ponowna kontrolaD

Kolejny świeży agent weryfikuje każdą poprawkę, potem patrzy tylko na to, co się zmieniło.

↺ Nowe uwagi dostają kolejne ID (F5, F6…) i idą na następne okrążenie. ID nigdy nie są używane ponownie.

■ Limit przerwania: trzecia nieudana kontrola albo uwaga otwarta ponownie dwa razy zatrzymuje pętlę. Wybierasz: podzielić zadanie, przepisać specyfikację albo zmienić podejście.

RYS. 5.— Pętla kończy się, gdy nie ma otwartej uwagi typu blocker ani should fix. Wtedy bramka się otwiera: przez koordynatora z twoją delegacją albo przez ciebie.

6.0

Dowód A

Prawdziwy przegląd złapał to, co przeoczył build.

Z przykładu w repozytorium. Agent Build zacommitował skompilowane pliki .pyc. Jego testy były zielone. Świeży agent Review to wychwycił, runda poprawek o wąskim zakresie to usunęła, ponowna kontrola to potwierdziła.

Workflow/Reports/P1-T1 - 4 Review.mdFragment

# Report: P1-T1 - 4 Review
 
## Summary
1Reviewed origin/relay/p1...origin/wip/p1-t1-version-flag (3904ade).
Behaviour matches the Spec and REQ-1; 6 tests pass in the throwaway
worktree. The commit also adds two compiled .pyc files.
 
## Findings
| ID | Severity   | Finding
2| F3 | should fix | Commit adds build output __pycache__/*.pyc
|    |            | Fix: A git rm --cached · B A + .gitignore
| F4 | nit        | Tests duplicate stdout capture · later
 
## Git
3git remote get-url --push --all origin -> matches RELAY.md
git diff --stat (origin/relay/p1...3904ade):
 __pycache__/greet.cpython-313.pyc      | Bin 0 -> 1496 bytes
 greet.py                               |  1 +
 test_greet.py                          | 29 +++++++++++++-
 
## Tests
Ran 6 tests in 0.000s   OK
 
4Verdict: fix round needed: F3

1
Inny agent
Recenzuje wypchnięty commit w odłączonym, jednorazowym worktree. Nigdy nie widział sesji Build.
2
Uwagi, nie poprawki
ID, waga, miejsce i opcje, gdy jest realny wybór. Planista zamienia wagę na decyzję.
3
Prawdziwy wynik komend
Sprawdzony remote, diff stat, liczba testów. Gdy komenda się nie powiedzie, tu trafia jej wynik.
4
Werdykt to ostatnia linia
Odczytują go narzędzia i planista. Same nity oznaczają clean.

RYS. 6.— Raport Review, skrócony dla szerokości. Pełny tekst z każdym promptem i raportem: example/.

Dowód B · Dziennik misji, P1-T1

Historia kroków z karty zadania, od początku do końca. Dwie uwagi poprawione, dwie zweryfikowane, dwa nity odłożone na później.

1 Analyzeskipped: one-line change, REQ-1 gives the behaviour in full
2 Spec checkfix round needed: F1
2 Spec fix (2)F1 fixed in Spec Tests
2 Spec check (2)clean; F1 verified
Owner approvedSpec approved → 3 Build
3 Build3904ade pushed, 6 tests OK
4 Reviewfix round needed: F3
2 Spec fix (3)F3 option B: .gitignore added to the spec (small call, logged)
3 Build (2)F3 fixed in c66916d, proof command empty
4 Review (2)clean; F3 verified
Owner approvedCode approved @ c66916d → 5 Done
5 Donemerged 585ee0e, tagged wip/p1-t1-done, pushed

7.0

Zasady lotu

Za każdą zasadą stoi incydent.

Agenci na każdym kroku stosują jeden krótki plik zasad: pushuj tylko do dozwolonego remote, nigdy nie rób force-push, nigdy nie otwieraj pull requestu, scalaj tylko zrecenzowany commit. Oto lekcje, z których powstał.

FR-01Jeden autor na plik

Dlaczego · Dwóch autorów logu decyzji wyprodukowało zdublowane wiersze.

FR-02Zabijaj po PID lub porcie, nigdy pkill -f <wzorzec>

Dlaczego · Zabicie po wzorcu w jednym zadaniu najpewniej ubiło workery testów innego worktree w trakcie testów.

FR-03Pliki robocze tylko we własnym /tmp/<repo>-<task-step>/

Dlaczego · Konfigurację testów przeglądarkowych we wspólnym /tmp usunął późniejszy krok.

FR-04Żadnego --no-verify

Dlaczego · Build pominął hook, żeby obejść lint, więc commit nigdy nie przeszedł kontroli, które uruchamia CI.

FR-05Pełna lista testów przy Done, timeouty uruchamiaj osobno

Dlaczego · Podzbiory przegapiały regresje. Timeouty pod obciążeniem wyglądały jak błędy.

FR-06Przed startem zrób fetch i porównaj z remote

Dlaczego · Praca przenosi się między maszynami w nocy.

Uczciwe zastrzeżenie: dziś te zasady działają na zaufaniu. Nic jeszcze nie zatrzyma agenta, który zignoruje „nigdy nie rób force-push”. Pakiet hooków, który je wymusza, jest na roadmapie.

8.0

Adaptacja polowa

Nie chcesz wdrażać całości? Ukradnij pomysły.

Pełna procedura opłaca się przy funkcjonalnościach na wiele sesji. Ale same zasady działają w każdym układzie z agentami już dziś, nawet w jednym czacie. Oto najmniejsza wersja.

Świeży kontekst na każdy krok
Czysta sesja widzi kod, nie wymówki.
Dowody zamiast deklaracji
Status odtwarza się z wyników, nie z tego, co mówi agent.
Werdykty czytelne dla maszyn
Jedna stała ostatnia linia pozwala narzędziom łączyć kroki bez zgadywania.
Wymagania mają kolejność
Gdy źródła się różnią, rozstrzyga spisana kolejność źródeł.

AGENTS.md · minimum

# Minimalne zasady relay (wklej do AGENTS.md lub CLAUDE.md)
- Jeden krok na sesję. Sesja, która recenzuje kod, nigdy go nie pisała.
- Kontrole tylko znajdują i zapisują. Poprawki idą w osobnej rundzie, potem ponowna kontrola.
- Każde twierdzenie wymaga wyniku: hash commita, git diff --stat, komenda testów i ich liczba.
- Ostatnia linia raportu z kontroli to "Verdict: clean" albo "Verdict: fix round needed: F<n>, ...".
- Stan żyje w plikach, nie w czacie. Napisz raport, nawet gdy utkniesz.
- Drobne decyzje techniczne: zdecyduj, zapisz, jedź dalej. Zakres i zatwierdzenia: zatrzymaj się i zapytaj.

9.0

Procedura startowa

Zacznij w 5 minut.

Potrzebujesz CLI agenta kodującego, sesji LLM dla planisty (może to być to samo narzędzie), Gita 2.28+ i remote, do którego twoi agenci mogą pushować.

T–5:00

Załóż bazę wiedzy obok repozytorium

terminal

git clone https://github.com/Kuznia-Tech/kuznia-relay.git
cp -R kuznia-relay/kit my-project-kb
cp kuznia-relay/SPEC.md kuznia-relay/AGENT-RULES.md my-project-kb/

T–4:00
Uzupełnij RELAY.md
YAML na górze: ścieżka repo, dozwolony remote, komendy testów, twoja pierwsza funkcjonalność. Jej wymagania (ticket, kryteria akceptacji, projekt) wrzuć do sources/.

T–3:00

Utwórz gałąź funkcjonalności i jej worktree

terminal

cd my-project
git fetch origin
git branch --no-track feat/my-feature origin/main && git push -u origin feat/my-feature
git worktree add ../my-project-worktrees/p1 feat/my-feature

T–2:00
Uruchom planistę w folderze bazy wiedzy
Kit zawiera AGENTS.md (Codex) i CLAUDE.md (Claude Code), więc planista sam wczyta swoje instrukcje.
planista
```
plan P1
prompt P1-T1
```
T–1:00
Wykonaj krok w świeżym agencie, w swoim repo
Daj mu prawo zapisu do bazy wiedzy na raport, wklej linię od planisty, potem powiedz planiście report P1-T1. Powtarzaj aż do Done.
terminal
claude --add-dir /home/you/my-project-kb
T–0:00
Dostarcz
Gdy każde zadanie jest Done, sam otwórz pull request z gałęzi funkcjonalności, potem usuń worktree i gałęzie zadań oraz foldery robocze.

Komendy planisty

where are we?	Bieżący krok każdego aktywnego zadania, na kogo czeka, co dalej
plan <F>	Napisz plan funkcjonalności z jej dokumentu wymagań, z listą zadań
new task <F>: <name>	Dodaj jedno zadanie: karta, wiersz w Board, linia w Plan
prompt <task>	Napisz prompt dla bieżącego kroku, odpowiedz linią do wklejenia
report <task>	Przeczytaj najnowszy raport, zaktualizuj dokumenty, przesuń krok
approve <task>	Specyfikacja zatwierdzona → Build. Kod zatwierdzony @ <commit> → Done
fix <task>	Rozpocznij rundę poprawek dla uwag oznaczonych fix
findings <task>	Pokaż otwarte uwagi: ID, waga, decyzja, runda

Ostatnie odliczanie

Spec. Build. Review. Merge. Start.

Przeczytaj specyfikację w dziesięć minut, przejdź przykład, a pierwsze zadanie uruchom jeszcze dziś.

Pobierz z GitHuba Czytaj SPEC.pl.md