project-guides
Serwer MCP project-guides dostarcza agentom AI instrukcje projektu (stack per Tier + overlay) i instaluje pliki kita w repo aplikacji.
Bundle instrukcji —
list_bundlespokazuje dostępne zestawy (backend, frontend, payments, architecture, infra, devops, full) dla bieżącego profilu, aget_bundlezwraca ich pełną treść Markdown wraz z overlayem.Moduły —
list_moduleslistuje wszystkie moduły z manifestu,get_modulepobiera pojedynczy moduł po ID (np.stack:django-drf:backend-standard).Kontekst projektu —
get_indexdaje podsumowanie konfiguracji profilu (Tiery, host, nierozpoznane decyzje),get_overlayzwraca unikalne instrukcje repo z.ai/project.md.Metadane konfiguracji —
get_language(język prozy vs tytuły EN),get_codegen(orval / none / graphql),get_clients(klienci AI z--clients).Presety —
list_presetspokazuje kategorie presetów (_base,shop, …).Status kita —
check_kit_statustanio porównuje commit bootstrapu z HEAD kita i mówi, co re-bootstrap nadpisze.Instalacja/odświeżenie —
bootstrap_workspaceto jedyne narzędzie zapisujące na dysk (domyślniedry_run=Trueplan zmian;dry_run=Falsefaktyczna instalacja hooków, agentów, komend,mcp.json, stampu).
Provides infrastructure module for task queue with Celery.
Provides stack module for Django REST Framework.
Provides stack module for Expo Router (React Native).
Provides code review integration with GitHub (Bugbot).
Provides infrastructure module for message queue with RabbitMQ.
Provides infrastructure module for cache and queue with Redis.
Provides capabilities module for payments with Stripe.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@project-guides show me the Django guides for this project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Instruction Kit — MCP z instrukcjami projektów
Centralne repo MD + serwer MCP. Projekty wybierają Stack per Tier (backend/web/mobile w .ai/project.profile.yaml) + overlay.
Szybki start
Trzy kroki cyklu życia kita w projekcie. Szczegóły każdego kroku są niżej.
Krok 1 — Instalacja
uv tool install git+https://github.com/radthenone/ai-instruction-kit-mcp
cd /m/projects/moja-appka # repo aplikacji
kit-ai installBez @ instalujesz gałąź domyślną (master). Nowsze, jeszcze nie wydane zmiany są na
dev — wtedy dopisz ref, np. …/ai-instruction-kit-mcp@dev.
Krok 2 — Konfiguracja
Zrestartuj IDE / CLI, potem w kliencie AI:
/kit-project-begin # pierwszy raz: pytania o Stack, karta Profilu i .ai/project.md
/kit-project-edit "…" # później: jedna zmiana, np. "zmień web na angular"/kit-project-begin proponuje odpowiedzi wykryte w repo, a /kit-project-edit zmienia jedną
odpowiedź bez całego wywiadu (pełny opis). Po zapisie
zrestartuj klienta.
Krok 3 — Update
uv tool upgrade guides-mcp # nowa wersja kita
kit-ai reload # odśwież pliki kita w projekcie
kit-ai status # w agencie: check_kit_status
kit-ai doctor # ścieżki i komendy w regułach vs repoRelated MCP server: CodeGuard MCP Server
Szczegóły instalacji
Jedna komenda robi instalację i update. Bootstrap jest idempotentny: pliki generowane (agenci, komendy,
hooki, mcp.json) nadpisuje świeżą kopią, a pliki z Twoją treścią (AGENTS.md,
.ai/project.md) zostawia w spokoju. BUGBOT.md odświeża z szablonu, ale blok
<!-- project:rules --> z regułami projektu przechodzi bez zmian — szczegóły w sekcji
Bootstrap.
Wymagania: uv w PATH, bash (Windows: Git for Windows), node (dla hooków),
opcjonalnie npx (skille zewnętrzne).
1. Instalacja / update w projekcie — kit-ai
Bez klona kita — kit-ai jako narzędzie uv (ref po @: branch, tag albo commit):
uv tool install git+https://github.com/radthenone/ai-instruction-kit-mcp # master
uv tool install git+https://github.com/radthenone/ai-instruction-kit-mcp@dev # albo gałąź dev
cd /m/projects/moja-appka # repo aplikacji
kit-ai install # bez ścieżki = bieżący katalog
kit-ai reload | kit-ai status | kit-ai doctor | kit-ai remove [--dry-run]
kit-ai labels [--apply] # brakujące etykiety GitHuba (bez --apply = plan)
kit-ai host # profil hosta: vps | local (detect_host_profile)
kit-ai night-ctx [ścieżka] # nagłówek CTX dla /night-run (Host z kit-ai host)
kit-ai retro scan [ścieżka] [--session ID] [--since YYYY-MM-DD|Nd] # sygnały i koszt sesji → ~/.cache/kit-ai/retro/<repo>/
kit-ai retro report [ścieżka] # propozycje z wielu repo (≥3 sesje albo ≥2 repo), bez znalezisk z issue z markerem (otwartym lub zamkniętym)
# jednorazowo, bez instalowania narzędzia:
uvx --from git+https://github.com/radthenone/ai-instruction-kit-mcp kit-ai installWybrany ref trafia do mcp.json projektu (np. uvx --from git+…@dev), a commit kita do
stampu — kit-ai status porównuje go z commitem zainstalowanego narzędzia. Update:
uv tool upgrade guides-mcp (albo uv tool install --force git+…@<inny-ref>) +
kit-ai reload. Instalacja z lokalnej ścieżki (uv tool install .) nie zna commitu —
status mówi wtedy „nieznany commit”.
install pyta o dwie rzeczy (Język [pl/en] (pl), Klienci (…) (all)) — flagi --language
i --clients pomijają pytania, bez TTY pytań nie ma wcale. Zakłada .ai/project.profile.yaml
(backend/web/mobile: none = sam core) i .ai/project.md, robi Bootstrap, a na końcu
wypisuje JSON serwera MCP i gdzie leży per klient. Repo z kitem install odrzuca — wtedy
reload.
Jedyna konfiguracja to Profil (ADR-0007): język, klienci, Stacki per Tier, codegen:.
Zmiana czegokolwiek = edycja .ai/project.profile.yaml + kit-ai reload. reload nie
rusza .ai/project.md; repo ze starą konfiguracją (stamp z --preset, brak Profilu) dostaje
Profil core + none i nowy mcp.json.
Klucz Profilu | Kiedy zmienić |
|
|
| Stack per Tier (puste Tiery = sam core) |
|
|
|
|
Niskopoziomowo to samo robi scripts/bootstrap-project.sh "$APP" --from "$KIT" --clients … --language …
(dodatkowo --with-overlay, --with-plugins, --keep-unselected-clients). --preset,
--profile, --with-profile i --codegen zostały usunięte — skrypt odmawia i odsyła do kit-ai reload.
2. Po instalacji (kroki, których skrypt nie zrobi za Ciebie)
kit-ai install kończy się blokiem „Dalej” (Superpowers + /kit-project-begin). Pełna
lista poniżej — rób tylko to, czego jeszcze nie masz, i tylko dla klientów z clients:.
Wszystko poza 2.5 robisz raz na maszynę, nie per projekt.
Komendy są te same w Git Bash (Windows) i na Linuksie, chyba że wiersz mówi inaczej. Różnice Windows zebrane są w 2.4.
2.1. rtk — sprawdź, czy jest
rtk --version && rtk gain # oba muszą zadziałać; "command not found" = brak rtkrtk gain nie działa, a rtk --version tak → masz inne narzędzie o tej nazwie
(reachingforthejack/rtk), nie Rust Token Killer. Brak rtk niczego nie psuje — agenci
wykonują wtedy komendy bez prefiksu (core:tooling-rtk).
Instalacja:
# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
# Windows (winget działa też z Git Bash)
winget install rtk-ai.rtkHook, który przepisuje komendy na rtk … poza modelem — po jednym na klienta:
Klient | Komenda | Uwagi |
Claude Code |
| Hook kita |
Codex |
| Potem |
OpenCode |
| |
VS Code (Copilot) | — | Hook przychodzi z kita: |
Antigravity |
|
Po rtk init zrestartuj klienta. Weryfikacja: rtk init --show.
2.2. Pluginy i skille zewnętrzne — per klient
Kolejność bez znaczenia; wszystkie są opcjonalne poza Superpowers (warstwa 3 w
AGENTS.md). npx skills przyjmuje -a claude-code|codex|opencode|github-copilot|antigravity
i dla klientów poza Claude instaluje do .agents/skills/ (dodaj -g, żeby globalnie).
Wyjątek: Antigravity CLI (agy) nie czyta globalnego ~/.agents/skills/, gdzie -g
kładzie skille — globalnie widzi tylko ~/.gemini/config/skills/
(antigravity-cli#103).
Superpowers (obra/superpowers)
Klient | Komenda |
Claude Code | Proponuje się sam przy otwarciu repo (bootstrap wpisuje go do |
Codex | W TUI: |
OpenCode | Napisz agentowi: |
VS Code (Copilot) | Tylko Copilot CLI: |
Antigravity |
|
Skille Matta Pococka (mattpocock/skills, aihero.dev/skills) — /grill-me, /tdd
Klient | Komenda |
Claude Code |
|
Codex, OpenCode, VS Code |
|
Antigravity — per projekt |
|
Antigravity — globalnie |
|
Caveman (JuliusBrussee/caveman)
Klient | Komenda |
Claude Code |
|
Codex |
|
OpenCode |
|
VS Code (Copilot) |
|
Antigravity |
|
Ponytail (DietrichGebert/ponytail)
Klient | Komenda |
Claude Code |
|
Codex |
|
OpenCode | Klon repo + w |
VS Code (Copilot) | Tylko Copilot CLI: |
Antigravity |
|
Zawężenie ponytaila w Claude Code:
kit-ai reloadwpisuje do.claude/settings.local.json(poza gitem — lista agentów zależy od wersji kita; worktree kopiuje plik) zmiennąenv.PONYTAIL_SUBAGENT_MATCHER, która wyklucza agentów procedur kita (git-*,review-*,night-run*,create-*,kit-project-*,teacher-*,headless,cleanup), pozwalając ponytailowi działać tylko w subagentach piszących kod (subagent-backend,subagent-frontend, subagent przejęcia wnight-run) oraz zwykłych subagentach wbudowanych (general-purpose,Explore).
Dlaczego: nacisk ponytaila na „najkrótszą drogę” sprzyja omijaniu procedur i źródeł prawdy kita (np. grep zamiast
get_bundle).Inni klienci: mechanizm dotyczy tylko Claude Code — pozostali klienci kita nie mają filtrowania po typie subagenta.
Własna konfiguracja / wyłączenie: wpisz własną wartość
PONYTAIL_SUBAGENT_MATCHERwenvw.claude/settings.local.json(albo.claude/settings.json) — kit nie nadpisze wpisu użytkownika w żadnym z nich; matcher kita, który wcześniej trafił dosettings.json, reload stamtąd usuwa.kit-ai doctorzgłosi ostrzeżenie, gdy obowiązujący matcher (najpierwsettings.local.json) nie wyklucza procedur kita.Sesja główna: ponytail zostaje włączony — kit nigdzie go nie wyłącza. Reguły briefu kita (hook
language-reminder, instrukcje MCP, blokkit:brief-ruleswAGENTS.md; ADR-0010) mówią, że ponytail i podobne pluginy stylu kodu dotyczą kodu aplikacji, nie procedur kita ani edycji plików kita i konfiguracji projektu (.ai/,AGENTS.md, Profil,templates/,.claude/).Współdzielony plik trybu: ponytail trzyma aktywny tryb w jednym pliku na maszynę (
~/.claude/.ponytail-active), więc różne tryby w równoległych sesjach na jednej maszynie nie są wspierane.
Context7 (upstash/context7) — docs bibliotek (MCP)
Najprościej npx ctx7 setup --claude / --opencode (OAuth + klucz API + konfiguracja).
Reszta ręcznie — serwer zdalny https://mcp.context7.com/mcp, nagłówek
Authorization: Bearer <KLUCZ> (wszystkie klienty):
Klient | Gdzie | Wpis |
Claude Code | CLI |
|
Codex |
|
|
OpenCode |
|
|
VS Code |
|
|
Antigravity |
|
|
CodeGraph (@colbymchenry/codegraph) — graf kodu (MCP + CLI, nie skill)
npm i -g @colbymchenry/codegraph
codegraph install --target claude,codex,opencode,copilot-vscode,antigravity --location global
codegraph init -i # w każdym repo — buduje indeks .codegraph/Zostaw w --target tylko swoich klientów. codegraph install --print-config <id> pokazuje
wpis bez zapisu.
GitHub MCP (github/github-mcp-server) — issues/PR z poziomu agenta
Serwer zdalny https://api.githubcopilot.com/mcp/. Poza VS Code (OAuth) potrzebny PAT
(github.com/settings/tokens, scope repo, read:org, read:user)
w zmiennej środowiskowej, nie w pliku w repo:
Klient | Komenda / wpis |
Claude Code |
|
Codex |
|
OpenCode |
|
VS Code |
|
Antigravity |
|
2.3. Gdzie co ląduje
.agents/skills/ jest wspólny dla Codexa, OpenCode, Copilota i Antigravity — skill dodany
przez npx skills -a codex zobaczą też pozostali. Kit ignoruje ten katalog w .gitignore,
więc na nowej maszynie instalację powtarzasz.
Globalnie Antigravity CLI czyta tylko ~/.gemini/config/skills/ — npx skills update
odświeża ~/.agents/skills/, więc po aktualizacji skopiuj skille ponownie.
2.4. Windows (Git Bash) vs Linux
npx skillsdomyślnie robi symlinki, a te na Windowsie wymagają Developer Mode albo admina. Bez tego dodaj--copy.Lokalny (stdio) serwer MCP odpalany przez
npxuruchamiaj na Windowsie jakocmd /c npx …. Serwery zdalne (Context7, GitHub wyżej) tego nie potrzebują.Pełny instalator Caveman: na Windowsie
install.ps1, nieinstall.sh— hooki i tak wołają wersje PowerShell.Hooki Ponytail i Caveman (Claude, Codex) potrzebują
nodew PATH powłoki nieinteraktywnej — przy nvm to częsta pułapka.Zmienne z tokenami: Git Bash / Linux
export GITHUB_PAT_TOKEN=…, PowerShell$env:GITHUB_PAT_TOKEN = "…". Klient musi wystartować już z ustawioną zmienną.
2.5. Konfiguracja projektu
/kit-project-begin — patrz Krok 2.
Hooka pre-push kit już nie dostarcza (guardraile siedzą w hookach klientów);
istniejący git-hooks/pre-push w Twoim repo zostaje nietknięty.
Zrestartuj IDE / CLI. MCP i komendy ładują się przy starcie — bez restartu zobaczysz stan sprzed bootstrapu.
3. Weryfikacja
# MCP odpowiada i widzi właściwy kit
# w Claude Code: poproś o wywołanie narzędzia check_kit_status
# oczekiwane: "Kit status: aktualny"
# hooki działają (powinno wypisać "deny")
printf '%s' '{"tool_input":{"command":"git reset --hard HEAD"}}' \
| node .claude/hooks/git-guard.mjs
# konfiguracja AI wchodzi do repo, lokalny stan nie
git status --short -uall .claude .codex .github/promptsDoctor — reguły projektu vs drzewo repo
kit-ai reload kończy się raportem doctor:, kit-ai status i MCP check_kit_status
dokładają go do swojego wyniku, a kit-ai doctor uruchamia samą kontrolę. Doctor czyta
BUGBOT.md, .ai/project.md, AGENTS.md i CODING_STANDARDS.md (w repo kita także
komendy w templates/shared/agents/*). Linie AGENTS.md / BUGBOT.md skopiowane bez
zmian z szablonu kita są pomijane — to treść kita, nie reguły projektu:
ścieżki w backtickach — brak w drzewie =
OSTRZEŻENIEz plikiem i numerem linii; globy (**/auth/**) i placeholdery (<N>) są pomijane. Ścieżka może być od roota repo, względem katalogów z## Ścieżki(i ichsrc//app/) albo gołą nazwą (server.py,ui/) szukaną w całym drzewie;zakres Tieru — ścieżka w sekcji z nagłówkiem Tieru (
## Backend,## Frontend (web / mobile)) albo w linii z prefiksembackend:/web:/mobile:liczy się tylko wewnątrz katalogu tego Tieru (kluczbackend:/web:/mobile:w## Ścieżki). Plik, który leży wyłącznie w innym Tierze, dajestale-path. Prefiks linii wygrywa z nagłówkiem; ścieżka pełna od roota repo i sekcja bez Tieru — bez zawężania;klucze
## Ścieżkiw overlayu (backend:,web:,routes-web:…) — katalog albo plik musi istnieć;komendy
/nazwa— muszą mieć agenta, komendę albo skill u któregoś klienta zclients:; komendy innych warstw (Matt, Superpowers, Cursor) są pomijane;pakiety workspace'ów Bun/npm, pnpm i uv, których overlay nie opisuje —
INFO, nie ostrzeżenie.
doctor: 1 ostrzeżenie, 1 informacja
doctor: OSTRZEŻENIE BUGBOT.md:12 — ścieżka `src/auth/` nie istnieje
doctor: INFO .ai/project.md — katalog `packages/ui/` z workspace'u nie jest opisany w `.ai/project.md`Klasy zgłoszeń (pole kind):
| Poziom | Co znaczy |
| ostrzeżenie | ścieżka w regule albo klucz |
| ostrzeżenie | overlay pisze, że ścieżki nie ma („brak |
| ostrzeżenie |
|
| ostrzeżenie | blok |
| ostrzeżenie |
|
| ostrzeżenie | brak klucza w |
| ostrzeżenie | komenda |
| info | pakiet workspace'u bez opisu w |
| info | nieprawidłowe |
| info | tylko z |
kit-ai doctor # linie doctor:, kod wyjścia 0
kit-ai doctor --json # {"warnings", "infos", "findings": [{kind, file, line, value, suggestion, …}]}
kit-ai doctor --verbose # + INFO `path-candidates`, gdy ścieżka pasuje do >1 miejscaBez --verbose ścieżka pasująca do kilku miejsc przechodzi po cichu (jak dotąd);
z flagą każde takie trafienie dostaje linię INFO z listą kandydatów, w obrębie zakresu
Tieru. --verbose łączy się z --json.
OSTRZEŻENIE znaczy, że reguła review albo wpis overlayu wskazuje coś, czego w repo nie
ma — po cichu przestaje działać. INFO to porządki w overlayu. Doctor nigdy nie
blokuje reloadu: raport i tak wychodzi, a kod wyjścia to 0.
Naprawa — tryb C /kit-project-edit "napraw zgłoszenia doctora": proponuje poprawki
w overlayu, w bloku project:rules w BUGBOT.md i w bloku project:agents w AGENTS.md
(przestarzała treść kita), pokazuje jeden podgląd na całą partię i zapisuje po
akceptacji. Ścieżki w szablonowych częściach BUGBOT.md / AGENTS.md i w
CODING_STANDARDS.md wymagają ręcznej decyzji (reload nadpisałby szablon).
Po reloadzie (kit-ai reload, MCP reload_workspace) ostrzeżenia do naprawy trafiają
do pliku stanu .ai/.kit-doctor.json (ten sam format co kit-ai doctor --json); czysty
przebieg plik usuwa, --dry-run go nie dotyka. Raport kończy linia
doctor: N do naprawy → /kit-project-edit "napraw zgłoszenia doctora", a MCP
reload_workspace każe agentowi od razu uruchomić tryb C na tej partii — bez czekania na
prośbę (auto-start). Tryb C bierze partię z pliku stanu albo z kit-ai doctor --json.
4. Kiedy aktualizować
Narzędzie MCP check_kit_status porównuje commit kita zapisany przy bootstrapie
(.ai/.kit-bootstrap.json) z aktualnym HEAD i mówi, co się zmieniło. Rozdziela dwie
rzeczy: pliki, które re-bootstrap wciągnie sam (w tym BUGBOT.md — odświeżany
z szablonu), i te wymagające ręcznego przeniesienia (AGENTS.md, .ai/project.md —
kopiowane tylko gdy brak, żeby nie zdeptać Twojej treści). Gdy pokaże zmiany: kit-ai reload
(z terminala to samo pokazuje kit-ai status).
5. Zanim odpalisz update na repo z pracą w toku
Bootstrap nadpisuje .claude/{agents,commands,hooks}/, .codex/, .github/prompts/,
copilot-instructions.md i pliki MCP. Jeśli edytowałeś je ręcznie — git diff najpierw.
Nie chcesz oglądać planu na sucho? Z poziomu agenta:
reload_workspace() # dry run — lista plików nowych/nadpisanych/usuniętych
reload_workspace(dry_run=False) # odświeżenie z Profilu (= kit-ai reload)Etykiety GitHuba. Agenci kita używają tylko istniejących etykiet: type: *, kategorii
bug / enhancement (słownik /triage), scope: * według Tierów i etykiet stanu
(needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix — nazwy
z docs/agents/triage-labels.md projektu, jeśli jest). Zestaw leży w
templates/shared/labels.tsv; brakujące zakłada ensure_labels(dry_run=False) albo
kit-ai labels --apply (istniejących nie zmienia). /kit-project-begin proponuje to po
reloadzie.
Etykiety design: layout / design: tokens dochodzą tylko przy Tierze web/mobile i
claude w clients: — sesję designu robi człowiek w Claude Code (opis:
docs/agents/design-handoff.md, instalowany przy tych samych warunkach). Treść agentów tylko
dla takich projektów siedzi w blokach <!-- clients: claude -->…<!-- /clients -->; bootstrap
zostawia je (bez znaczników) albo wycina według clients:.
Gdzie żyje konfiguracja AI po instalacji: wszystko poza .claude/settings.local.json
i .agents/skills/ idzie do repo — bootstrap wstawia do .gitignore sekcję między
markerami # >>> instruction-kit >>>. Szczegóły: sekcja „.gitignore" niżej.
Gdzie czytać / zmieniać konfigurację:
Co | Gdzie pisać |
Argumenty MCP ( | ten README (sekcja niżej) + szablony |
Stack per Tier i fork | |
Kanon agentów / reguł (niezależny od IDE) | |
Multi-client design | |
Szczegóły jednego produktu |
|
Inny zestaw modułów niż Tiery |
|
Docelowy kontrakt | |
Cursor |
|
Skille kita (wszyscy klienci) |
|
Struktura docs/
docs/
├── adr/ — decyzje architektoniczne (format Nygarda)
├── agents/ — kontrakt issue trackera, etykiety triage, docs domenowe
├── specs/ — projekty przed implementacją
└── plans/ — plany implementacyjne
docs/specs/idocs/plans/nazywały się wcześniejdocs/superpowers/{specs,plans}. Zmiana jest celowa: Superpowers imattpocock/skillsto zewnętrzne biblioteki, z których kit korzysta — ich nazwa nie powinna strukturyzować drzewa docs tego repo.
Konfiguracja projektu — argumenty guides-mcp
Wszystkie flagi serwera MCP wpisujesz w args klienta (Cursor: .cursor/mcp.json). Kolejność: najpierw --from / nazwa pakietu (guides-mcp), potem flagi poniżej.
Warstwy (co gdzie należy)
Warstwa | Mechanizm | Przykład |
Stack backendu | Tier |
|
Stack webu | Tier |
|
Stack mobile | Tier |
|
Powtarzalny wariant |
|
|
Fakty jednego repo |
| porty, Taskfile |
Inny zestaw modułów niż Tiery |
|
|
Nie mieszaj: nazwa produktu ≠ Stack; porty ≠ tag.
Flagi (aktualne)
{
"mcpServers": {
"project-guides": {
"command": "uvx",
"args": [
"--from", "git+https://github.com/radthenone/ai-instruction-kit-mcp.git",
"guides-mcp",
"--language", "pl",
"--clients", "all",
"--workspace", "${workspaceFolder}"
]
}
}
}Flaga | Wymagana? | Rola | Gdzie / jak zmieniać |
| przy | Źródło zdalne kita: |
|
`--language pl | en` | nie | Język prozy (odpowiedzi, docstringi, body issue/PR, commity). Tytuły issue/PR/branch zawsze EN. Domyślnie: |
| nie | Metadane IDE: | mcp.json / bootstrap |
| nie | Klon kita, z którego serwer czyta | mcp.json — bootstrap dodaje sam przy źródle lokalnym; env |
| zalecane | Root aplikacji — stąd profil | mcp.json; Cursor/VS: |
| nie | Extra MD (można wielokrotnie) | mcp.json — rzadko; zwykle wystarczy workspace |
Stare konfiguracje klienta z --preset / --profile / --codegen nadal startują serwer, ale
te flagi są ignorowane, a bundle i indeks niosą ostrzeżenie o migracji — kit-ai reload
przepisze mcp.json. Bootstrap zapisuje tylko --language i --clients (z Profilu).
Język: MCP tool get_language. Priorytet: --language / GUIDES_LANGUAGE → language: w YAML profilu → pl. Moduł w bundle: core:language-pl albo core:language-en.
Klienci AI: MCP tool get_clients — tylko metadane instalacji; treść get_bundle jest identyczna dla każdego klienta.
Codegen (Orval): wyłącznie codegen: w .ai/project.profile.yaml (orval | none | graphql, domyślnie orval; ADR-0007), odczyt przez MCP tool get_codegen. Bez pary backend + klient (web/mobile) efektywny codegen to zawsze none. Reviewery FE/BE to honorują (przy orval wymagają regeneracji klienta po zmianie API; graphql → moduł arch:api-contract:graphql zamiast REST).
Brief projektu i instrukcje MCP (ADR-0010)
Serwer MCP project-guides przy starcie/handshake'u przekazuje klientowi instrukcje serwera (build_instructions), które niosą Brief projektu oraz zwięzłą mapę narzędzi MCP. Ten sam brief trafia przy kit-ai reload do bloku <!-- kit:brief --> w AGENTS.md (czytanego m.in. przez Claude Code przez import @AGENTS.md).
Zawartość Briefu: metadane projektu (nazwa i Profil, znormalizowany język, Tiery, codegen, klienci, bundle i moduły, baza i komendy wyciągnięte z overlayu) oraz wskaźnik do
get_overlay(). Wykryty Host (vps/local) dokleja tylko serwer MCP w instrukcjach — blok wAGENTS.mdgo nie ma, żeby plik nie starzał się między maszynami.Overlay nie jest wklejany: cała treść pliku
.ai/project.mdnigdy nie jest wklejana do briefu ani instrukcji MCP (aby nie duplikować pliku i nie starzeć się po lokalnych edycjach). Unikalne fakty repozytorium agent pobiera na żądanie przez MCP toolget_overlay(), a reguła nakazuje wywołanieget_overlay()przed pierwszą edycją kodu.Reguły briefu (Brief Rules): kluczowe wytyczne (klasyfikacja zadań kodowych i proceduralnych,
get_overlayprzed pierwszą edycją, format docstringówArgs/Returns, zakaz instalacji na VPS poza formami lock-only wg ADR-0009).Jedno źródło reguł bez ręcznych kopii: reguły briefu mają dokładnie jedno źródło — szablon
templates/shared/rules/brief-rules.mdz placeholderem języka (language:z Profilu). Stamtąd są renderowane do nośników (Carriers):hooka Claude (
templates/claude/language-reminder.mjsi.claude/hooks/language-reminder.mjs, instalowanego dla każdego języka),instrukcji serwera MCP (moduł
src/guides/brief_rules.pyz wariantamiplienpieczonymi w pakiet kita; w runtime serwer wybiera wariant wg Profilu),bloku
<!-- kit:brief-rules -->w commitowanymAGENTS.md, czytanym przez każdego klienta. Świeżość plików wygenerowanych z szablonu weryfikuje test CI (TestBriefRulesFreshnesswtests/test_brief_rules.py); lokalnie to samo sprawdzapython3 scripts/render_brief_rules.py --check. Żaden plik repozytorium nie zawiera ręcznej kopii reguł.
Profil z Tierami (backend/web/mobile)
# .ai/project.profile.yaml w repo aplikacji
name: moja-appka
language: pl
clients: claude,codex
backend: django # none | django | django-html | fastapi | flask
web: react # none | react | react@legacy | angular | angular@rxjs | expo
mobile: none # none | expo | react-native
codegen: orval # orval | none | graphql (bez pary backend + klient: zawsze none)
capabilities:
- auth
- payments
decisions:
database: postgres
auth: jwtBundle liczone są z Tierów: get_bundle backend zawiera Stack z Tieru backend, pusty profil daje sam core. Nierozpoznana wartość Tieru nie wywraca serwera — ląduje w „Nierozpoznanych decyzjach" w get_index (ADR-0004). Stare klucze stacks: / patterns: czytane są nadal.
Model tiers agentów (models: / agents:)
Każdy agent kita ma w template model-tier: (light / standard / heavy; osobny klucz
od tier: Stacku). Profil mapuje tier na model per klient:
models: # ręcznie; reload tego bloku nie rusza
claude:
light: haiku
standard: sonnet
heavy: opus
opencode:
light: anthropic/claude-haiku-5-5
agents: # synchronizuje reload
light: git-start,git-commit,git-end,git-check,cleanup
standard: create-task,create-skill
heavy: night-run,review-edgeBrak klienta albo tieru w
models:= brak polamodel(agent dziedziczy model sesji). Bezmodels:pliki agentów są takie jak przed tą funkcją.agents:przy reloadzie: blok powstaje, gdy go nie ma; brakujący agenci kita trafiają do tieru z template; agenta już przypisanego reload nie przenosi (Profil wygrywa); nazwy spoza kita znikają. Każde dopisanie (+ agents.<tier>: <agent>) i usunięcie (-) jest w wyjściu reloadu. Reload przepisuje tylko blokagents:— komentarze w nim giną.Nieznany tier (w
models:alboagents:), tier bez modelu, agent w dwóch tierach i zapis w jednej linii (models: {…}) przerywają reload z opisem błędu. Oba bloki pisz z wcięciami, jak wyżej;agents:obejmuje wszystkich agentów kita, także Tierów Stacku spoza Profilu.models.claude.takeover(obok tierów, nie tier agenta): model przejęcia ticketu nocnego, gdy wykonawca/headlesszwróci limit (kod 75, #257). Tylko alias Claude Code:haiku,sonnet,opus,fable; inny zapis przerywa reload. Brak klucza = model sesji.
Klient | Wspiera | Plik | Format nazwy modelu | Przykład |
Claude Code | tak |
| alias ( |
|
opencode | tak |
|
|
|
Cursor, Codex, VS Code, Kiro, Kilo, Antigravity | nie — pole pomijane | — | — | — |
Komendy /nazwa Claude (.claude/commands/) zostają bez model: — działają w sesji głównej.
Katalog pytań o projekt (list_questions)
manifest.yaml → questions: trzyma pytania o projekt (Tiery, warianty, codegen, Docker,
Taskfile, CI/CD, monorepo, capability-provider, webhooki, ścieżki per Tier) z opcjami,
domyślnymi (defaults: zależne od Profilu, np. django-html → web/mobile none),
warunkiem when: i sygnałami detect: (glob + opcjonalny regex pattern w treści pliku).
Narzędzie MCP list_questions zwraca katalog z warunkami ocenionymi na bieżącym Profilu —
sygnały sprawdza agent w plikach repo, Python niczego nie skanuje. Odpowiedź ląduje tam, gdzie
wskazuje sets: (klucz Profilu albo paths.<tier> → ## Ścieżki w .ai/project.md), a pytania
tak/nie dopisują include: / patterns: z on_yes:.
Moduły układu katalogów (stack:frontend:*) nie wchodzą do Bundli — layouts: w manifeście
wybiera podpowiedź drzewka dla kombinacji web/mobile (np. web: react + mobile: expo →
react-expo-split), web: expo + mobile: react-native daje ostrzeżenie, brak drzewka →
domyślne ścieżki (backend/, frontend/web/, frontend/mobile/; Expo unified: frontend/).
Tagi / facety (planowane — jeszcze nie w CLI)
Gdy wiele projektów dzieli ten sam powtarzalny wariant instrukcji (np. sklep fizyczny vs cyfrowy), zamiast mnożyć presety shop-jewelry / shop-tokens:
W
manifest.yaml→mappings.tiers.<tier>dopisać dozwolone Stacki (np.fulfillmentnie — Tiery to backend/web/mobile; nowy wymiar trafia dodecisionsalbocapabilities).W mcp.json dodać np.
"--tag", "physical"albo"--facet", "fulfillment=physical"(docelowa składnia przy implementacji).Resolver dołoży wtedy dodatkowe MD z
modules/— bez lokalnego forka, jeśli zestawy capabilities są te same.
Teraz: różnice jubiler vs tokeny → .ai/project.md. Tagi włączaj dopiero gdy wariant wraca w ≥2–3 projektach.
Szkic (nie działa jeszcze):
"args": [
"--from", "…",
"guides-mcp",
"--tag", "physical",
"--tag", "b2c",
"--workspace", "${workspaceFolder}"
]Bootstrap
# Generyczny — profil z Tierami + --language pl
./scripts/bootstrap-project.sh /sciezka/do/projektu \
--from /absolutna/sciezka/do/ai-instruction-kit-mcp \
--with-overlay
# Tylko Cursor
./scripts/bootstrap-project.sh /sciezka/do/projektu \
--clients cursor \
--from /absolutna/sciezka/do/ai-instruction-kit-mcp
# Proza EN, wszyscy klienci AI (Stacki potem w .ai/project.profile.yaml)
./scripts/bootstrap-project.sh /sciezka/do/moj-sklep \
--language en \
--clients all \
--from /absolutna/sciezka/do/ai-instruction-kit-mcpAgenci per Tier: agenci z tier: we frontmatterze (templates/shared/agents/) trafiają do klienta tylko przy wybranym Tierze — tier: backend (review-backend, teacher-backend, subagent-backend) gdy backend ≠ none, tier: client (review-frontend, teacher-frontend, subagent-frontend, review-ui) gdy web lub mobile ≠ none. Tier zmieniony na none + kit-ai reload = ich pliki znikają u wszystkich klientów. Agenci nie zakładają Stacka — biorą go z get_bundle. BUGBOT.md dostaje sekcje (<!-- tier:backend -->, <!-- tier:client -->) tylko wybranych Tierów.
BUGBOT.md i reguły projektu: każdy reload renderuje BUGBOT.md oraz .cursor/BUGBOT.md z bieżącego szablonu — poprawki ścieżek i reguł kita docierają do repo same, także gdy masz własne reguły. Własne reguły wpisuj wyłącznie między <!-- project:rules --> i <!-- /project:rules -->: ten blok przechodzi przez reload bajt w bajt, a reszta pliku jest brana z szablonu. Plik dostosowany przed wprowadzeniem bloku jest migrowany: bootstrap dopasowuje go do najbliższej wersji templates/cursor/BUGBOT.md z historii gita kita i przenosi dopisane linie do bloku, a w wyniku reloadu wypisuje ich listę. Gdy migracja jest niepewna (brak historii — np. kit z koła, albo za duży diff), plik zostaje bez zmian, a reload wypisuje instrukcję ręcznego przeniesienia.
Zapisuje m.in. MCP per klient (--language, --clients, --workspace), agents z templates/shared/agents, BUGBOT.md w root (wszyscy klienci) + .cursor/BUGBOT.md (natywny Cursor BugBot), skill Cursor /compact, hooki gate-* (Cursor), stamp .ai/.kit-bootstrap.json (patrz "Update kita w projekcie"). Wymaga Python 3 (python3 albo python z major==3).
Declarative sync klientów: domyślnie bootstrap usuwa kitowe pliki klientów spoza --clients (np. przełączenie z --clients all na --clients claude sprząta .cursor/, .codex/ itd. wygenerowane przy poprzednim bootstrapie). Flaga --keep-unselected-clients wyłącza to sprzątanie — zostają pliki wszystkich klientów kiedykolwiek bootstrapowanych.
Sprzątanie kasuje wyłącznie pliki kita, po nazwie — listę bierze z przebiegu tych samych funkcji instalacji w pustym katalogu. Własne agenty, komendy, hooki i skille w .claude/, .opencode/, .codex/, .github/prompts/ itd. zostają; katalog znika tylko, gdy po kicie jest pusty. Plik użytkownika o nazwie identycznej z plikiem kita (np. własny .claude/agents/git-start.md) zostanie usunięty razem z kitowymi.
kit-ai remove [ścieżka] [--dry-run] — odinstalowanie: pliki kita wszystkich klientów, konfiguracje MCP, wpisy kita w .claude/settings.json, sekcja # >>> instruction-kit >>> w .gitignore, Profil i stamp (także stara konfiguracja z presetem). Pliki tworzone raz (AGENTS.md, .gitattributes) znikają tylko, gdy są identyczne z bieżącym szablonem kita — zmienione przez Ciebie zostają. BUGBOT.md znika, gdy jest nietkniętym renderem: blok project:rules bez własnych reguł liczy się jak pusty, ale plik z regułami projektu zostaje. Zawsze zostają .ai/project.md, CONTEXT.md, docs/adr/ i Twoje pliki. Kit nie robi kopii, więc nic nie przywraca. --dry-run pokazuje listę bez usuwania.
.gitignore — co z tego wersjonować
Bootstrap wstawia do .gitignore repo aplikacji sekcję między markerami
# >>> instruction-kit >>> i # <<< instruction-kit <<<. Przy kolejnych przebiegach
podmienia ją w całości, więc wpisy się nie duplikują, a reguły spoza markerów zostają
nietknięte. Źródło: templates/gitignore-kit.txt.
Zasada: konfiguracja AI jest częścią repo. Hooki bezpieczeństwa, agenci i komendy mają działać u każdego, kto sklonuje projekt — nie tylko na maszynie, gdzie odpalono bootstrap. Poza gitem zostaje lokalny stan klienta, to, co i tak żyje globalnie, oraz pliki, które bootstrap renderuje ze ścieżką tej maszyny:
Wersjonowane | Ignorowane |
|
|
|
|
|
|
|
|
— |
|
Konfigi MCP i stamp są per maszyna, nie per repo. Przy --from <lokalny klon> bootstrap
wpisuje do nich absolutną ścieżkę klona (uv run --project, --kit-root), a dla Codex
i opencode absolutny --workspace. Zacommitowane z Windowsa (M:/projects/…) na Linuksie
dają CONNECTION_CLOSED bez czytelnego powodu. Każdy odbiornik — PC, laptop, serwer —
odpala kit-ai reload u siebie; język i klienci są w zacommitowanym Profilu, więc nic
więcej nie trzeba pamiętać.
Repo zbootstrapowane wcześniej mają te pliki w indeksie — sam wpis w .gitignore ich nie
odśledzi. Bootstrap wykrywa to i wypisuje gotową komendę (pliki zostają na dysku):
git -C "$APP" rm --cached .mcp.json .vscode/mcp.json .codex/config.toml .ai/.kit-bootstrap.jsonTypowy .gitignore ma .claude/ wpisane hurtem — wtedy hooki i komendy nigdy nie trafiają
do repo, a bootstrap trzeba powtarzać na każdej maszynie. Reguły kita są w formie „ignoruj
katalog, odwróć dla plików kita", bo git nie wchodzi do zignorowanego katalogu i sam wyjątek
na plik by nie wystarczył.
Bootstrap bez klona kita — narzędzie MCP bootstrap_workspace
Jeśli projekt ma już podłączony serwer MCP project-guides, kita nie trzeba klonować ani ręcznie odpalać skryptu — serwer ma szablony pod ręką i uruchamia ten sam bootstrap-project.sh u siebie. Poproś agenta o wywołanie narzędzia:
bootstrap_workspace() # dry run — tylko lista plików
bootstrap_workspace(dry_run=False) # instalacja
bootstrap_workspace(clients="claude", with_overlay=True, dry_run=False)Odświeżenie z Profilu (= kit-ai reload, łącznie z migracją starej konfiguracji) robi reload_workspace() / reload_workspace(dry_run=False).
Argumenty bootstrap_workspace (clients, language, with_overlay, keep_unselected_clients) odpowiadają flagom skryptu; pominięte biorą wartość z parametrów startowych serwera MCP. Cel zapisu to --workspace / GUIDES_WORKSPACE — bez niego narzędzie odmawia, zamiast zapisywać do katalogu, z którego przypadkiem wystartował proces serwera.
dry_run=True jest domyślne i nic nie zapisuje: skrypt leci na kopii kitowej powierzchni repo w katalogu tymczasowym, a raport pokazuje pliki nowe, nadpisane i usunięte przez sprzątanie klientów spoza --clients. Plan pochodzi więc z faktycznego przebiegu skryptu, nie z drugiej listy ścieżek w Pythonie.
Uwaga na bramki. Hooki kita (
PreToolUse) łapiąBash,PowerShelliEdit|Write|MultiEdit|NotebookEdit— nie nazwy narzędzi MCP. To jedyne zapisujące narzędzie tego serwera i hooki go nie zatrzymają;dry_run=Truejako domyślka plus wymóg jawnegodry_run=Falsesą tu całą ochroną. Reszta narzędzi serwera pozostaje tylko do odczytu.
MCP w innych klientach (multi-client)
Kanon treści: templates/shared/{agents,rules}. Adaptery IDE trzymają tylko format MCP / ścieżki natywne. Bootstrap --clients instaluje wybrane pakiety (default all).
Klient | Id | Plik MCP w aplikacji | Klucz top-level | Szablon |
Cursor |
|
|
|
|
Claude Code |
|
|
|
|
Codex CLI |
|
|
|
|
GitHub Copilot (VS Code) |
|
|
|
|
Kiro |
|
|
|
|
Kilo |
|
|
|
|
Antigravity |
|
|
|
|
opencode |
|
|
|
|
Zmienna dla --workspace:
Klient | Zmienna |
Cursor, VS Code, Kiro, Kilo, Antigravity |
|
Claude Code |
|
Codex CLI, opencode | ścieżka absolutna (brak stabilnej zmiennej) |
Instalacja per klient (krok po kroku)
Wspólne dla wszystkich: git clone / masz kita lokalnie → uruchom bootstrap-project.sh w repo aplikacji (nie w repo kita) z --from wskazującym na kita → zrestartuj IDE.
./scripts/bootstrap-project.sh /sciezka/do/mojej-appki \
--from /m/projects/ai-instruction-kit-mcp \
--clients cursor \
--with-overlayKlient |
| Wymaga poza kitem | Extra config po bootstrapie |
Cursor |
| Cursor IDE | Ustaw |
Claude Code |
|
|
|
Codex CLI |
|
|
|
GitHub Copilot (VS Code) |
| VS Code + rozszerzenie GitHub Copilot Chat |
|
Kiro |
| Kiro IDE |
|
Kilo Code |
| rozszerzenie Kilo Code |
|
Google Antigravity |
| Antigravity IDE / CLI ( |
|
opencode |
|
|
|
Wiele klientów naraz: --clients cursor,claude albo --clients all. Każdy klient dostaje ten sam --language/--workspace — różni się tylko format pliku MCP i ścieżka komend.
Po bootstrapie zawsze: zrestartuj IDE/CLI (MCP i komendy ładują się przy starcie), potem sprawdź że MCP wstał (np. get_bundle / lista narzędzi w kliencie).
Czego kit nie robi / brakujące komendy
Świadome braki — nie zgłaszaj jako bug, tylko sprawdź czy potrzebujesz obejścia niżej:
Brak | Status | Obejście |
| Zaprojektowane, nie w CLI | Różnice trzymaj w |
| Usunięte (serwer je ignoruje, bootstrap odmawia) | Profil zawsze |
| Nie istnieje dla Claude/Codex/inne | To alias Cursor UI Summarize; Claude Code ma wbudowane |
Natywna weryfikacja formatu VS Code/Kilo/Antigravity/opencode | Oparta o dokumentację (sierpień 2026), nie testowana na żywych klientach | Jeśli |
Auto-instalacja Superpowers/Autopilot | Niemożliwa ze skryptu (marketplace pluginów Claude/Cursor, wymaga interaktywnego |
|
Pluginy zewnętrzne — schemat użycia (4 warstwy)
Kit nie bundluje tych pluginów w guides-mcp (różna dystrybucja: MCP vs Claude/Cursor plugin marketplace vs npx skill). Pełna tabela warstw i priorytet źródeł: AGENTS.md.
1. Fundament — ten kit (MCP + /git-* + /review-*) → instaluje bootstrap
2. Proces — mattpocock/skills (/grill-me, /tdd) → npx skills@latest add mattpocock/skills
3. Meta/izolacja — Superpowers (worktree, finishing…) → Claude Code: /plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
4. PR → green — Autopilot (Cursor) → Cursor: Settings → Extensions/Skills → AutopilotNie mieszaj warstw: kit = prawda o stacku i nazwach branchy, Matt = proces feature, Superpowers = sesja/worktree/finisz, Autopilot = dociąganie PR.
Auto-instalacja przy bootstrapie: --with-plugins (best-effort, opt-in — nic nie instaluje się bez tej flagi):
./scripts/bootstrap-project.sh ../moj-projekt \
--clients claude \
--from /m/projects/ai-instruction-kit-mcp \
--with-pluginsCo robi: odpala npx skills@latest add mattpocock/skills w TARGET (wymaga npx/Node.js w PATH; best-effort — błąd nie przerywa bootstrapu), i wypisuje gotowe komendy do Superpowers/Autopilot (te dwa wymagają interaktywnego kroku w kliencie, nie da się ich odpalić z bash). TDD: jeden path na feature — domyślnie Matt /tdd, nie mieszaj z Superpowers TDD.
Katalog modułów
modules/
core/ repo-first, workflow, typing, code-review, language-*, tooling-rtk
architecture/ platforms, CI/CD, API (REST/GraphQL), security, testing, i18n,
taskfile, docker-structure, …
stacks/
django-drf/ (+ django/, fastapi/, flask/ layouts)
expo-router/
frontend/ warianty Expo/React (macierz web/mobile — design)
capabilities/ auth (+ allauth/jwt/custom warianty), files, payments (+ expo-stripe gdy Tier expo), …
patterns/ capability-provider, providers-and-settings, gateway, webhooks, …
infra/ database, cache, queue, storage, tasks, search, vps-lightweight (auto na VPS)
templates/
shared/ kanon agents + rules (źródło prawdy)
cursor|claude|… adaptery MCP / format IDESloty infrastruktury (decisions)
decisions:
database: postgres # → infra:database:postgres
cache: redis # → infra:cache:redis
queue: redis # → infra:queue:redis (lub rabbitmq)
storage: s3 # → infra:storage:s3
tasks: celery # → infra:tasks:celery
search: postgres # → infra:search:postgres (lub meilisearch)Moduły infra trafiają automatycznie do bundle infra i devops.
Dodanie nowej technologii nie wymaga Pythona (ADR-0001). Trzy kroki:
Napisz
modules/infra/queue/kafka.md.Zarejestruj go w
manifest.yaml→modules:.Dopisz wartość w
manifest.yaml→mappings.slots.queue.kafka.
Nierozpoznana Decyzja (literówka postgress, technologia bez modułu) nie wywraca
serwera — ląduje w sekcji „Nierozpoznane decyzje" w get_index (ADR-0004).
Lekki tryb VPS (infra:vps-lightweight)
Agenci na słabym VPS-ie (np. 1 vCPU, 4,5 GB RAM, bez swapu, LXC) nie mogą zachowywać
się jak na maszynie dewelopera — pełny docker compose up, next dev czy e2e
potrafią zabić produkcję obok przez OOM.
Wykrywanie bez nazw hostów: Linux, brak CI/WSL, małe zasoby (CPU ≤ 2, RAM ≤ 8 GB, brak swapu) i sygnał serwerowy (wirtualizacja z
systemd-detect-virtalbo brak desktopu). Nadpisanie:KIT_HOST_PROFILE=vps|local(aliasGUIDES_HOST_PROFILE). CI zawsze dostajelocal— pełna weryfikacja należy do CI.get_bundlena takim hoście doklejainfra:vps-lightweightdo każdego bundle'a (teżbackend/frontend/architecture);get_indexpokazuje- Host: vps|local. Bez hooka blokującego — tylko reguła tekstowa, żeby nie zatrzymać celowego deployu.Moduł operuje kategoriami (kontenery, dev serwery, buildy, e2e vs lint/typecheck/ unit in-memory), nie zakłada Django/React/Next ani innego stacku.
Podział Twojego repo dopisz w overlay (
.ai/project.md), np.task lintlekkie vstask test:e2eciężkie — jedna zmiana przez/kit-project-edit.
Wariant auth (decisions.auth)
decisions:
auth: custom # default — brak enforced pakietu, opisz w .ai/project.md
# auth: allauth # → capability:auth:allauth (django-allauth headless)
# auth: jwt # → capability:auth:jwt (djangorestframework-simplejwt)Inny mechanizm niż infra: nie tworzy osobnego bundle'a — dokleja się zaraz po
capability:auth wszędzie tam, gdzie ten moduł już jest wypisany w bundle
(capabilities: [auth] albo include: z ID modułu — routing wg tagów).
W manifeście to mappings.variants.auth (Wariant = wstaw po module bazowym),
w odróżnieniu od mappings.substitutions.codegen (Substytucja = podmień moduł bazowy).
Słownik i decyzje
Plik | Rola |
Ubiquitous language kita — Bundle, Preset, Slot, Wariant, Alias, Overlay… | |
Decyzje architektoniczne z uzasadnieniem (dlaczego tak, a nie inaczej) |
Nazwy z CONTEXT.md obowiązują w kodzie, docstringach i review. Zanim zaproponujesz
zmianę architektury, sprawdź docs/adr/ — część rzeczy już rozstrzygnięto.
Bundle'e MCP
Bundle | Zastosowanie |
| Stack z Tieru backend, capabilities BE |
| Stacki z Tierów web i mobile, UI/UX |
| Stripe, webhooks |
| monorepo, kontrakt API, capability-provider |
| postgres, redis, queue, s3, celery |
| CI/CD + infra |
| wszystko + infra |
Bootstrap w projekcie docelowym
W repo aplikacji uruchom scripts/bootstrap-project.sh albo skopiuj z templates/:
Plik | Rola | Wymagany? |
| uvx → | tak (Cursor) |
| MCP per klient z | wg wybranego klienta |
| Overlay — Taskfile, Docker, porty | zalecany |
| .ai/project.profile.yaml | Tiery (backend/web/mobile) + codegen: — jedyna konfiguracja kita | tak |
| .cursor/rules/use-guides.mdc | Bootstrap MCP | tak |
| .cursor/rules/code-review.mdc | Review przed pushem | tak |
| .cursor/rules/git-branch-pr.mdc | /git-start+/git-check+/git-commit+/git-end, issue#, chronione main/master/dev | tak |
| .cursor/BUGBOT.md | Reguły Bugbota | tak |
| .cursor/hooks.json + hooks/invoke-hook.js + hooks/*.mjs | Guardy: git-guard + sensitive-files (adapter → node) | tak |
| AGENTS.md | Cienki — odsyła do MCP | tak |
| .cursor/agents/*.md | Subagenty /review-*, /subagent-*, /git-* | zalecany |
| .cursor/skills/compact/ | Tylko Cursor: /compact = alias UI Summarize (nie Claude/Codex) | zalecany (Cursor) |
W projekcie docelowym nie duplikuj modules/ — wystarczy profil z Tierami + opcjonalny overlay.
Update kita w projekcie
Komendy update: Szybki start, krok 3. Poniżej to, co update robi z plikami, i lokalny klon kita.
Bootstrap to jednorazowy stempel, nie sync. Cztery różne zachowania:
Co | Przy ponownym |
| Zawsze nadpisane świeżą kopią z kita — traktuj jak wygenerowany kod, nie edytuj ręcznie. |
| Renderowane na nowo z szablonu (sekcje Tierów według Profilu). Blok |
| Kopiowane tylko jeśli brak — bootstrap nigdy więcej ich nie tyka, update ręczny. |
| W ogóle nie kopiowane — MCP czyta je z |
Lokalny klon: uv run --project, nie uvx --from
uvx --from <katalog> nie czyta kita z tego katalogu w czasie działania. uv buduje koło,
w którym manifest.yaml i modules/ lądują jako guides/_data
(force-include w pyproject.toml), i cache'uje je pod wersję pakietu. Wersja nie rośnie
przy zwykłej edycji modułu ani kodu serwera, więc klient dostaje kopię sprzed builda.
Do tego find_kit_root() woli _data od repo, więc check_kit_status traci historię gita.
Objaw: poprawiasz modules/…, restartujesz klienta, a get_bundle wciąż zwraca starą treść.
Bez komunikatu błędu. To samo dotyczy poprawek w src/guides/ — serwer nadal biegnie na
starym kodzie.
Dlatego przy źródle lokalnym bootstrap generuje:
"command": "uv",
"args": ["run", "--project", "/sciezka/do/klona", "guides-mcp", …,
"--kit-root", "/sciezka/do/klona", …]Pakiet ma układ src/, więc uv run instaluje go jako editable — _data w ogóle nie
powstaje, a kod i moduły czytane są wprost z klonu. --kit-root nie jest wtedy konieczny,
ale zostaje: nazywa klon wprost, zamiast pozwalać serwerowi go wnioskować.
Przy źródle zdalnym (git+https://…) nic się nie zmienia — zostaje uvx --from, bo klonu
nie ma, a _data z koła jest jedyną i aktualną kopią.
Projekty zbootstrapowane przed tą zmianą mają w mcp.json stare uvx --from albo
uv run --directory — wystarczy kit-ai reload.
Skąd wiedzieć kiedy re-bootstrapować (bez ciągłego czytania plików kita — tanie, jedno porównanie commitów):
MCP tool: check_kit_statusBootstrap zapisuje .ai/.kit-bootstrap.json (commit kita w momencie bootstrapu). check_kit_status
porównuje go z aktualnym HEAD kita (git rev-parse + git diff --name-only tylko na ścieżkach
które bootstrap faktycznie kopiuje) i zwraca: aktualny / zmienił się (+ lista plików) / brak stampu
(stary bootstrap sprzed tej funkcji) / brak lokalnej historii git (gdy --from to zdalny URL, nie
lokalny klon). Zero kosztu tokenów na nawigację plików — jedno wywołanie tool, agent woła je kiedy
chce sprawdzić stan (np. na początku sesji), nie w pętli.
Gdy pokaże zmiany: bootstrap-project.sh ponownie z tymi samymi flagami co poprzednio.
Slash commands — konwencja nazw
Prefiks | Rola | Przykłady |
| Cursor only — alias UI Summarize w tym projekcie |
|
| Start / sync issue / commit / PR |
|
| Pomysł → ocena na tle repo → issue (bez brancha) |
|
| Pomysł na skill → skill czy agent → issue (bez brancha) |
|
| Konfiguracja projektu po |
|
| Jedna zmiana konfiguracji / odstępstwo od modułu / naprawa doctora |
|
| Review tylko do odczytu, raport |
|
| Praca w dwóch oknach (wymiana raportów) |
|
| Klasyfikacja znalezisk ze skanu sesji (kit / projekt / agent / zewnętrzne); |
|
| Nocna praca na liście issue ( |
|
/compact (wyłącznie Cursor)
Skill: templates/cursor/skills/compact/SKILL.md → tylko .cursor/skills/compact/.
Bootstrap nie kopiuje tego do Claude / Codex. Nie nadpisuje ani nie „tłumaczy” ich wbudowanego /compact.
Po co: w Cursorze jedna komenda
/compactzamiast szukania UI Summarize.Nie jest wspólną konwencją kita cross-tool.
Nie mylić z
/handoff(plik + nowy chat).
/compact/git-start, /git-check, /git-commit, /git-end + Superpowers + Autopilot
Wymaga gh + git. Konwencja: feat/42-add-cart-coupon. Pełne zasady: .cursor/rules/git-branch-pr.mdc.
Podział ról (czytelnie)
Krok | Narzędzie | Uwagi |
Scope / TDD | Matt |
|
Issue + branch |
| Numeracja issue, Conventional name |
Sync issue ↔ diff |
| Gdy tytuł/body rozjechały się z plikami |
Commit(y) |
| Conventional; |
Izolacja (opc.) | Superpowers | Na branchu z |
Review przed pushem |
| Nie wszystkie |
Push + PR |
| Jedno z dwóch. |
CI / komentarze aż green | Autopilot | Po istniejącym PR; bez auto-merge |
Merge | Ty / | Gdy green → GitHub zamyka issue ( |
Krótko: /git-start → kod → [/git-check] → /git-commit → /review-bugbot → /git-end → [Autopilot]
Długo: [/grill-me] → /git-start → worktree → kod → [/git-check] → /git-commit → finishing| /git-end → Autopilot → mergeKomenda kit | Co robi |
| Ocena pomysłu na tle repo → karta issue → utworzenie po akceptacji; |
| Rozstrzyga skill vs agent, potem karta issue z nazwą, |
| Pytania z MCP |
| (A) jedna odpowiedź: Stack per Tier, codegen, klienci, język, sekcja |
|
|
| Dopasuj tytuł (EN) i body (język MCP) issue do realnego diffa; |
| Conventional Commit(s) z diffa; |
| Push + PR z |
| Cursor only — skrót czatu (alias UI Summarize); nie Claude/Codex |
/git-start --help
/git-start feat add cart coupon
/git-start fix #108 login returns 500
/git-start # auto z lokalnego diffa
# … praca zmieniła scope …
/git-check
/git-commit # lub --one / --split / --dry-run
# … review …
/git-end --help
/git-endRęczny odpowiednik:
gh issue create --title "Add cart coupon" --body "…"
gh issue develop 42 --name feat/42-add-cart-coupon --base dev --checkout
# … praca …
git push -u origin HEAD
gh pr create --base dev --title "feat: add cart coupon" --body "Closes #42"UI: GitHub Issue → Development → Create a branch (potem nazwij spójnie typ/N-slug).
Slash | Plik szablonu |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Git worktree (.ai/worktree.mjs)
Zarządzanie worktree przez jedną metodę kita (node .ai/worktree.mjs …): przenosi pliki z .gitignore (w tym konfiguracje MCP i .env) oraz zależności bez doinstalowywania czegokolwiek na VPS.
Konfiguracja (.ai/project.profile.yaml)
Opcjonalna sekcja w profilu projektu:
worktree:
copy: [ ... ] # pliki/katalogi kopiowane z głównego checkoutu (bez nadpisywania istniejących)
link: [ ... ] # symlink do głównego checkoutu (np. frontend/node_modules); bez domyślnych wpisów
setup: [ ... ] # komendy uruchamiane w worktree po copy/link; domyślnie pusta
venv: auto # auto | overlay | none (domyślnie auto)Gdy brak sekcji copy, skrypt kopiuje istniejące wpisy MACHINE_FILES (pliki MCP i stampy kita) + .env + .claude/settings.local.json.
Polecenia w setup: przed uruchomieniem są weryfikowane przez server-guard.mjs (na VPS niebezpieczne komendy, np. instalacja paczek, są pomijane).
Sync działa automatycznie: kit-ai install/reload dopisuje blok kita do hooka gita post-checkout (albo w katalogu z core.hooksPath), więc każdy nowy worktree, także z Orci, terminala czy agenta, od razu dostaje pliki z copy/link i overlay venv. Cudzy hook zostaje. Bez node w PATH hook tylko ostrzega. setup: dalej uruchamia się wyłącznie przy node .ai/worktree.mjs add. Przy względnym core.hooksPath (np. .githooks) git czyta hooki z katalogu nowego worktree, więc blok kita trzeba zacommitować.
Overlay venv i ograniczenia
Dla Pythona tryb venv: auto (oraz overlay) tworzy lekki overlay venv bazujący na głównym .venv:
python -m venv --without-pipinterpreterem z głównego venv (identyczna wersja),plik
_kit_worktree.pthwsite-packagesprzekierowuje pakiety instalowane w trybie editable (-e) z prefiksem głównego repozytorium na ścieżkę worktree, a następnie dopisujesite-packagesgłównego venv,Ograniczenia: metadane paczek i entry pointy pochodzą z głównego venv; overlay venv nie posiada wygenerowanych console scripts w
bin/(testy i komendy uruchamiaj przezpython -m …lubuv run --no-sync python -m …); editable instalowane przez import hook (import __editable___..._finder) nie są przekierowywane (ostrzeżenie w logu).
Zasady zależności i uprawnień
Linkowane zależności są tylko do odczytu:
node_modulesczy współdzielonysite-packagesnie powinny być modyfikowane z poziomu worktree (postinstall, ensurepip czy instalacja paczek zmieniają środowisko główne).Pliki konfiguracyjne MCP: kopiowane pliki wskazują ścieżkę
--workspacegłównego checkoutu (jest to zamierzone i bezpieczne).Server guard w worktree: działa w worktree tylko wtedy, gdy projekt commituje pliki hooków kita (np.
.cursor/hooks/,.claude/hooks/). Doctor nie sprawdza obecności hooków w repozytorium; przed założeniem worktree zweryfikuj ręcznie, np.git ls-files .cursor/hooks .claude/hooks.
/teacher-* — tryb nauki (przed kodem, nie po)
/review-* sprawdza gotowy diff i zwraca tabelę findingów. /teacher-* działa zanim napiszesz kod: bierze Twoją koncepcję (albo bieżący diff, gdy nie podasz argumentu), tłumaczy o co w problemie naprawdę chodzi, pokazuje max 3 opcje z kosztami, wskazuje jedną rekomendację i zostawia Ci zadanie do zrobienia samodzielnie.
Komenda | Zakres |
| Django/DRF (opc. FastAPI, Flask+Pydantic): warstwy, modele, migracje, transakcje, Celery, ACL, pytest, uv/ruff |
| React, React Native/Expo Router (opc. Angular): stan serwera vs klienta, granice komponentów, re-rendery, web/native, typy TS, RTL/Playwright |
| granice FE/BE, kontrakt API, kiedy nie dzielić, infra (Postgres/Redis/Celery/S3), Docker+Taskfile, odwracalność decyzji, ADR |
| praca z samymi agentami: skille, worktree i izolacja zadań, delegacja do subagentów, autonomia ( |
Kontrakt tych agentów: readonly — nie edytują plików, nie dają gotowca do wklejenia (szkic ≤ 20 linii), nazywają wzorce po imieniu i mówią wprost, gdy koncepcja jest zła. Czytają get_bundle + get_overlay, więc uczą na Twoim stacku i Twoim kodzie, nie na Foo/Bar.
/teacher-backend czy walidację ceny dać do serializera czy do serwisu
/teacher-frontend # bez argumentu → uczy o tym, co masz w git diff
/teacher-architecture czy dodać Redisa pod cache koszyka/night-run — lista issue przez noc
Za dnia grillujesz issue (kryteria akceptacji, relacje blocked-by). W nocy /night-run działa sam (wznawia go heartbeat CronCreate, /goal opcjonalny) i daje procedurę: na każdy ticket /git-start → test-first → szybkie bramki → /git-commit → review na diffie → /git-end → CI → merge → jeden raport na PR i zamknięcie issue. Problem zamiast pytania kończy się komentarzem needs-human z pytaniami Q1/Q2 na issue i agent idzie dalej. Pełna procedura: templates/shared/agents/night-run.md.
Agent jest orkiestratorem w głównej sesji (w Claude przez Skill, nie jako subagent). Sam nie czyta kodu: na ticket odpala świeżego subagenta ticketu, a review robi osobny świeży subagent na samym git diff (albo — przy skillach review z argumentów — orkiestrator przez Skill, biorąc od skilla tylko tabelę findingów). Dzięki temu żaden kontekst nie puchnie do 200k, a każda tura nie czyta go od nowa. Niczego nie dopisujesz do overlay:
Gałąź bazowa:
dev, jeśliorigin/devistnieje i nie jest w tyle za gałęzią domyślną; inaczej gałąź domyślna repo. Porzuconydevnie przejmie nocy.Plik kontekstu nocy (
~/.cache/night-run-<repo>-<data>/context.md): mapa aplikacji, konwencje, pułapki toolchainu z pamięci projektu i overlay. Po każdym tickecie orkiestrator dopisuje, co doszło (modele, serwisy, endpointy). Subagent czyta ten plik zamiast AGENTS.md, BUGBOT.md i wszystkich ADR-ów. Katalog w~/.cacheprzeżywa restart hosta (/tmppo restarcie kontenera znika). Commit po każdym zielonym kroku, a deny guarda (server-guard:/git-guard:w powodzie) to reguła, nie awaria — nie obchodzisz jej i nie liczysz do prób naprawy. Na VPS (bundle zinfra:vps-lightweight) kroki odrzucane przez guard idą jako „tylko CI”, a brak checków CI = brak merge.Bramki jakości: kroki
run:z.github/workflows/*.yml+ sekcja kontroli z.ai/project.md(icodegen:). Lokalnie tylko szybkie (lint, typecheck,makemigrations --check, testy dotknięte ticketem); pełny zestaw testów tylko w CI.Model subagenta ticketu:
model: <nazwa>w tekście celu; brak → model sesji.Koszt: po każdym tickecie snippet
python3liczy z transkryptów subagentów tury, tokeny (input / cache_creation / cache_read / output), maks. kontekst i czas. Wynik trafia doNIGHT-RUN REPORT.Wybrana baza, bramki, model i każde założenie trafiają do
NIGHT-RUN REPORT.
Bez /goal, z wykonawcą headless i wskazanym review:
/night-run #150 #151 /headless opencode --timeout 90 "implementacja i testy" /review-edge /review-bugbot/headless zastępuje implementację w subagencie ticketu (subagent pilnuje wrappera, sprawdza raport i commituje resztę); skille review uruchamia orkiestrator przez Skill, nieznany skill albo wykonawca (spoza clients: lub równy hostowi) zatrzymuje noc na starcie jako needs-human, a klient bez /headless wraca do implementacji subagentem. Wykonawca i review każdego ticketu trafiają do NIGHT-RUN REPORT.
Pod /goal sędzia widzi tylko transkrypt, więc warunek żąda dowodów w rozmowie:
/goal Wykonaj issue #150–#157 wg /night-run, model: sonnet. Koniec, gdy w transkrypcie jest
NIGHT-RUN REPORT, w którym każdy ticket ma: MERGED (wynik gh pr view --json state)
albo needs-human (link do komentarza), albo jest wpis "night-run halted".Uwagi dopisujesz za warunkiem („#155 bez PDF”, „bez merge, same PR-y”, „model: sonnet”) — polecenia z celu mają pierwszeństwo przed procedurą. W Claude model: przyjmuje tylko aliasy (sonnet, opus, haiku, fable); konkretną wersję modelu wybierasz dla całej sesji: claude --model <id>.
Pomiar kosztu ticketu na różnych modelach
Tańszy token nie znaczy tańszy ticket: mocniejszy model może zrobić mniej tur i mniej poprawek, a koszt nocy to głównie ponowne czytanie kontekstu (cache_read). Porównanie robisz tak:
Wybierz jeden ticket średniej wielkości (kilka kryteriów akceptacji, jedna aplikacja backendu), bez decyzji o pieniądzach i zgodach, żeby needs-human nie zepsuł porównania. Zapisz commit bazowy:
git rev-parse origin/<BASE>.Na każdy model osobny worktree z tego commitu i osobna sesja z dokładnym id modelu:
node .ai/worktree.mjs add ../measure-<model> --detach <commit> cd ../measure-<model> && claude -p --model <id> "/night-run #<N>, bez merge"PR służy tylko do pomiaru: po zebraniu wyników
gh pr close <PR> --delete-branchinode .ai/worktree.mjs remove ../measure-<model>.Metryki: snippet z sekcji „Pomiar kosztu ticketu” w agencie, uruchomiony na transkryptach sesji i jej subagentów (
~/.claude/projects/<projekt>/<sesja>.jsonli…/<sesja>/subagents/*.jsonl). Koszt liczysz osobno dla input, cache_creation, cache_read i output według aktualnego cennika, nie jedną stawką.Jakość: CI zielone za pierwszym razem (t/n), liczba rund poprawek, potwierdzone findingi review, needs-human (t/n).
Limit: ile ticketów mieści się w jednym oknie limitu sesji. Okno nie jest publiczne, więc szacujesz: zużycie na ticket w stosunku do zużycia skumulowanego w chwili HTTP 429 we wcześniejszym przebiegu.
Wynik (tabela + rekomendacja modelu domyślnego) trafia do issue pomiaru; zmiana domyślnego modelu to jedna linijka w agencie.
Bootstrap (--clients) kopiuje/renderuje shared agents do natywnych ścieżek każdego klienta. Format i mechanizm różnią się per klient:
Cursor:
.cursor/agents/— natywne slash commands, działa 1:1.Claude Code:
.claude/agents/(subagenty, wywołanie przez Task/Agent tool) oraz.claude/commands/(prawdziwe slash commands/git-startitd. —$ARGUMENTSwstrzyknięty automatycznie przy kopiowaniu).Codex: agenty instalowane jako natywne skille w
.codex/skills/<nazwa>/(renderowane ztemplates/shared/agents/*.mdprzezscripts/install_shared_skills.py). Custom prompts (.codex/agents/*.toml) zostały wycofane w Codex CLI — Codex sam ładuje SKILL.md, gdydescriptionpasuje do sytuacji.Kiro:
.kiro/agents/— kopiowane 1:1, format niezweryfikowany na żywym Kiro.VS Code/Copilot:
scripts/render_agent_commands.py vscode→.github/prompts/*.prompt.md(wywołanie/nazwaw Copilot Chat).Kilo:
scripts/render_agent_commands.py kilo→.kilocode/workflows/*.md(wywołanie/nazwa,$ARGUMENTSwspierane).Antigravity: agenty jako natywne skille w
.agents/skills/<nazwa>/(agynie zna workflow — patrzinstall_agent_skills.py).opencode:
scripts/render_agent_commands.py opencode→.opencode/command/*.md(wywołanie/nazwa,$ARGUMENTSwspierane). Guardy kita: plugin.opencode/plugins/kit-guards.js+.opencode/hooks/(sekcja „Guardrails”). Model: projektowyopencode.jsondostaje przy install i reloadmodelz globalnego configu OpenCode, tylko gdy projekt nie ma własnegomodel. Katalog jak w OpenCode:$XDG_CONFIG_HOME/opencode/albo~/.config/opencode/(na Windows%USERPROFILE%\.config\opencode\); plikiconfig.json,opencode.json,opencode.jsonc(komentarze dozwolone), ostatni zmodelwygrywa. Kolejność:modelw projektowymopencode.json→ globalny config → domyślny model OpenCode. Nadpisanie: wpiszmodelw projektowymopencode.json— reload go nie rusza. Kopia nie śledzi późniejszych zmian globalnego configu; żeby ją odświeżyć, usuńmodelz projektu i zrób reload. Inne pola globalnego configu (provider, agent) nie są kopiowane. Do tego/goali/loopjak w Claude Code:templates/opencode/command/{goal,loop}.md+ plugin.opencode/plugins/kit-loop.js, który posession.execution.succeededwysyła kolejną turę. Stop:<promise>DONE</promise>w odpowiedzi, Esc,/goal clear//loop stop, limit tur (goal 25, loop 10,max=N);/loop 5m <zadanie>powtarza co interwał.
Formaty VS Code/Kilo/Antigravity/opencode oparte o publiczną dokumentację tych klientów (sierpień 2026) — nie testowane na żywych instalacjach; jeśli coś nie zadziała, zgłoś różnicę i popraw scripts/render_agent_commands.py.
Po skopiowaniu/wyrenderowaniu zrestartuj okno IDE — agenty/komendy ładują się przy starcie.
Wywołanie
/git-start feat #42 cart coupon # lub bez # — utworzy issue
/git-check # gdy diff rozjechał się z opisem issue
/git-commit # Conventional Commit(s)
/review-backend przejrzyj zmiany w backend/apps/products/
/git-end/subagent-backend przejrzyj zmiany… # potem wklej raport do /subagent-frontend w drugim oknieSkille kita — wspólne źródło
Skill to wiedza, którą model ładuje sam, gdy description pasuje do sytuacji —
w odróżnieniu od agenta (/nazwa), którego ktoś musi wywołać. Jedno źródło:
templates/shared/skills/<nazwa>/SKILL.md (+ opcjonalne references/, scripts/,
assets/). Rozkłada je scripts/install_shared_skills.py.
Klient | Gdzie ląduje | Jak działa |
claude |
| natywnie, z zasobami |
cursor |
| natywnie, z zasobami (obok Cursor-only |
antigravity |
| natywnie, z zasobami |
codex |
| natywnie, z zasobami |
vscode |
| degradacja: komenda |
kiro |
| degradacja: komenda |
kilo |
| degradacja: komenda |
opencode |
| degradacja: komenda |
Degradacja kosztuje dwie rzeczy: skill przestaje odpalać się sam (trzeba wpisać
/nazwa) i gubi wszystko poza SKILL.md, bo komenda to jeden plik. Instalator mówi
o gubionych katalogach na stderr. Skill, którego sens leży w scripts/, będzie
w pięciu na osiem klientów wydmuszką — wtedy to prawdopodobnie powinien być agent.
.claude/skills/ i .agents/skills/ dzielisz ze skillami spoza kita (npx skills add),
więc odznaczenie klienta kasuje tam tylko katalogi o nazwach ze wspólnego źródła,
nigdy całego katalogu skilli.
Nowy skill zakładasz przez /create-skill (issue), a piszesz według skilla
skill-authoring — to on trzyma zasady frontmatter, sufity długości i kryteria odpalania.
/headless — zadanie dla innego klienta
Z dowolnego klienta kitu (host) zlecasz zadanie innemu klientowi uruchomionemu bez interfejsu (wykonawca). Host czeka, wrapper sprząta procesy, host streszcza wynik.
/headless <wykonawca> [--model <id>] [--timeout <min>] [--heartbeat <min>] [--ctx <katalog>] "<treść>"Flaga | Znaczenie |
| Model sesji wykonawcy w jego formacie ( |
| Limit w minutach, domyślnie 60; po nim drzewo procesów jest zabijane (kod |
| Co ile minut linia stanu |
| Katalog nocy (podaje |
Inna flaga = błąd z listą dozwolonych. Treść idzie do wykonawcy słowo w słowo, plus stała
stopka: na branchu typ/<N>-slug linia „Ticket #N: przeczytaj gh issue view N --comments”
(branch bez numeru — bez tej linii), katalog runu na logi testów i pliki robocze, zakaz
git stash / git checkout / git reset (porównanie z bazą przez
node .ai/worktree.mjs add <katalog runu>/base --detach <ref> --plain i node .ai/worktree.mjs remove <katalog runu>/base na końcu),
plan 5–10 kroków przy tickecie z więcej niż 3 kryteriami albo więcej niż jedną aplikacją,
test-first z lokalnym commitem po każdym zielonym kroku, temat commita po polsku wg language z Profilu (po angielsku dla en), na końcu każdego commita trailer Co-Authored-By: Claude <noreply@anthropic.com>, lokalnie tylko testy dotknięte
zmianą i szybkie bramki (pełny zestaw robi CI), na VPS uv run --no-sync, maks. 2 próby
naprawy tego samego błędu, raport ## Zmiany / ## Testy / ## Problemy. Dlatego
/headless <wykonawca> "implementacja i testy" na branchu ticketu wystarcza.
W logu runu linia [headless] ticket #N.
Push i PR robi host (/git-end) po review commitów.
Log i heartbeat. Wrapper przechwytuje wyjście wykonawcy, przepuszcza je dalej i zapisuje
do .ai/headless-runs/<start>-<wykonawca>/headless.log (katalog sam się ignoruje w gicie; przy starcie kasuje runy poza 5 najnowszymi, z wyjątkiem nieudanych bez wycinka w katalogu nocy);
ścieżka logu to pierwsza linia wyjścia. Co --heartbeat minut dopisuje
[headless] ♥ <min> min | pliki: <git status --short> | commity: <od startu> | ostatnio: <linia>,
a po dwóch interwałach bez wyjścia — [headless] możliwe zacięcie: brak wyjścia od X min
(tylko ostrzeżenie; zabija dopiero kontrola postępu, niżej, albo --timeout). Liczy to Node, nie model — zero tokenów. Podgląd na żywo
w osobnym terminalu: tail -f <log>; agent czyta stan jedną linią:
grep '^\[headless\]' <log> | tail -1.
Kontrola postępu co 30 min (#397). Postęp to nowe bajty wyjścia wykonawcy, zmiana HEAD albo
git status, albo wzrost CPU jego potomków (/proc/<pid>/stat; bez /proc liczą log i git). Brak postępu
w oknie 30 min → zrzut drzewa procesów do logu, checker z models.claude.light z Profilu opisuje stan w 1–3 zdaniach
(ostatnie 40 linii wyjścia, git status, czas bez postępu; timeout 60 s; nie decyduje o zabiciu), drzewo zabite
łagodnie jak przy --timeout (SIGTERM, po 2 s SIGKILL), klasa HANG, kod 124, zadanie idzie 1:1 dalej.
Opis trafia do raportu końcowego jako ## zacięcie: …. Brak klucza models.claude.light wyłącza checker, nie kontrolę.
Raport końcowy — zawsze, także po timeoucie (124) i po SIGINT / SIGTERM / SIGHUP wrappera (nie po SIGKILL): git status --short, commity wykonawcy od startu (git log <start>..HEAD --oneline), nowe wpisy
git stash list z ostrzeżeniem UWAGA (bez auto-pop — konflikt) i ostatnie 20 linii
wykonawcy. Agent /headless przenosi ostrzeżenie o stashu do raportu dla użytkownika.
Commity z zakresu wywołania (start..HEAD) bez trailera Co-Authored-By trafiają do linii UWAGA: commity bez trailera z hashami;
wrapper ich nie przepisuje, poprawia je orkiestrator na branchu ticketu przed push.
Wiersz wywołania i raport nocy (#396). Wywołanie z poprawnymi flagami kończy się jedną linią
JSON jako ostatnią linią wyjścia: ticket, wykonawca, lancuch, model, kod, klasa, start,
koniec, log, sprawdz, dzialanie. Klasy: OK; LIMIT (pauza, kod 75); HANG (timeout, brak
postępu 30 min albo sygnał w trakcie pracy wykonawcy); ERROR (kod ≠ 0 albo błąd wywołania); MODEL (nieznany model agy);
SUSPECT (exit 0 bez zmian w repo); POLITYKA (wpis stasha, commit bez trailera Co-Authored-By z hashem w dzialanie albo odmowa wykonawcy spoza zasad kitu; nie uruchamia zastępcy, praca zostaje). POLITYKA ustępuje LIMIT, MODEL, HANG i ERROR.
node .ai/headless.mjs --report --ctx <katalog> składa z bufora HEADLESS REPORT po tickecie oraz listę
wszystkich wywołań w kolejności; bufor kasuje dopiero po wypisaniu, więc przerwany raport go zostawia.
Reguły. Wykonawca musi być w clients: Profilu, mieć tryb headless z guardami kita
i być inny niż host — /headless <host> z tego samego hosta kończy się błędem z listą
dozwolonych wykonawców.
Wykonawca | Komenda | Model | Treść |
|
|
| stdin |
|
|
| argument |
|
|
| argument |
Przekazanie zadania (fallback). Limit (75), HANG, inny kod wyjścia ≠ 0 albo brak binarki u wykonawcy →
wrapper przekazuje tę samą treść 1:1 pozostałym z FALLBACK_ORDER (opencode, antigravity), jeśli są
w clients: i nie są hostem; zastępca bierze swój domyślny model. Klasa MODEL (zły model agy) nie przechodzi dalej,
bo to błąd konfiguracji. Limit u ostatniego → kod 75 i zadanie przejmuje host (agent /headless, krok 2).
Inny błąd albo HANG u ostatniego → kod wyjścia wykonawcy (124 przy zabiciu), wiersz HANG/ERROR; night-run
przejmuje ticket subagentem przejęcia (models.claude.takeover), a porażka przejęcia kończy się needs-human. Z Claude:
/headless opencode "…" → gemini → Claude sam; /headless gemini "…" → opencode → Claude sam.
Limit rozpoznaje tekst w ogonie wyjścia; agy po błędzie dodatkowo agy -p "/quota" — grupa
Gemini Models na 0% = limit, reset z najwcześniejszego wyczerpanego wiersza.
.agents/agy.json — agy nie ma projektowego configu z modelem (tylko globalny
~/.gemini/antigravity-cli/settings.json), więc wrapper czyta ten plik (gitignored):
{"model": "gemini-3.8-flash-high"} albo {"model": "gemini-3.8-flash", "effort": "high"}.
Poziom siedzi w sufiksie nazwy (agy models) albo w effort przy nazwie bazowej — nie oba:
agy odrzuca --effort niezgodny z sufiksem.
Wszyscy wykonawcy mają edycje i bash bez pytań. Guardy kita (git-guard, sensitive-files-guard)
działają u claude i opencode: hooki Claude Code i plugin kit-guards.js w OpenCode (#166).
U antigravity hooki .agents/hooks.json działają mimo --dangerously-skip-permissions
(deny git-guard sprawdzone na agy 1.4.8). Nowy wykonawca
= wiersz w EXECUTORS w templates/shared/headless/headless.mjs i w HEADLESS_EXECUTORS
w scripts/bootstrap-project.sh; opcjonalnie alias w EXECUTOR_ALIASES i miejsce w FALLBACK_ORDER.
Codex ma guardy kitowe przez PreToolUse (node "$(git rev-parse --show-toplevel)/.codex/hooks/invoke-hook.js" <guard>.mjs --to codex, #199) — nie jest jeszcze wykonawcą headless (patrz EXECUTORS w headless.mjs),
ale może być hostem i wywoływać claude lub opencode jako wykonawcę.
Codex odpala projektowy .codex/hooks.json dopiero po zaufaniu hookom repo (/hooks w Codexie);
bez tego guardy leżą na dysku, ale nie działają.
VS Code (Copilot) ma guardy kitowe przez .github/hooks/kit-guards.json
(node .github/hooks/invoke-hook.js <guard>.mjs --to copilot, #200) — nie jest wykonawcą
ani hostem headless w instalacji kita, ale jego agent mode egzekwuje tę samą politykę.
Cursor (cursor-agent -p) ma tryb headless, ale nie jest wykonawcą kita (patrz EXECUTORS
w headless.mjs) — może natomiast być hostem (macierz niżej). Antigravity jest wykonawcą
(agy -p), ma guardy kitowe przez .agents/hooks.json
(node hooks/invoke-hook.js <guard>.mjs --to antigravity, #201). Kiro i Kilo — bez trybu
headless w instalacji kita.
Macierz host × wykonawca (przy kliencie w clients:; wykonawca = klient z guardami
kita i wpisem w EXECUTORS):
Host \ wykonawca |
|
|
|
Claude Code | — (sam siebie) | tak | tak |
OpenCode | tak | — (sam siebie) | tak |
Antigravity | tak | tak | — (sam siebie) |
Codex, Cursor, VS Code, Kiro, Kilo | tak | tak | tak |
Instalacja. Agent /headless trafia do każdego klienta z --clients, gdy lista zawiera
co najmniej dwóch wykonawców (dziś: claude, opencode i antigravity; all też). Bootstrap wpisuje w plik
agenta id hosta, a wrapper kładzie w .ai/headless.mjs. Mniej niż dwóch wykonawców
= agent i wrapper znikają przy reload.
Model — trzy warstwy:
Warstwa | Skąd model |
Agent |
|
Sesja wykonawcy |
|
Agenci kitu wołani w sesji wykonawcy |
|
Sprzątanie procesów. Wrapper uruchamia wykonawcę we własnej grupie procesów (Unix)
i po zakończeniu, błędzie albo timeoucie zabija całe drzewo — z LSP i serwerami MCP
(Windows: taskkill /T /F /PID na wykonawcy i na potomkach zebranych w trakcie przez
Get-CimInstance Win32_Process co 5 s — Windows nie ma grup procesów, a po wyjściu rodzica
/T nie widzi już dzieci). OpenCode leci z --standalone, żeby jego serwer był procesem
potomnym, a nie usługą w tle. Proces żyjący krócej niż 5 s może umknąć snapshotowi.
Zabicie samego wrappera (SIGINT / SIGTERM / SIGHUP — np. koniec sesji hosta) też sprząta
drzewo wykonawcy. Na Windows shim .cmd z npm (opencode2.cmd) wrapper zamienia na
binarkę .exe, którą shim wskazuje ("%dp0%\…\x.exe"), i uruchamia ją bez powłoki. Shim
bez .exe jest odrzucany: cmd.exe rozbiłby wieloliniową treść w argumencie. Nazwa binarki
działa jak nazwa wykonawcy (/headless opencode2 = /headless opencode). Sesje wykonawców zostają na
dysku (historia claude i opencode); wrapper ich nie usuwa.
Guardrails — bezpieczeństwo
Jedno źródło polityki: templates/shared/guards/. Bootstrap kopiuje je do katalogu
hooków wybranego klienta (--clients), więc Claude Code, Cursor, OpenCode, Codex, VS Code
(Copilot) i Antigravity egzekwują dokładnie te same reguły.
Guard | Klient | Zachowanie |
| Claude, Cursor, OpenCode, Codex, VS Code (Copilot), Antigravity | deny: |
| Claude, Cursor, OpenCode, Codex, VS Code (Copilot), Antigravity (tylko narzędzia plikowe — bez Basha) | deny odczyt i zapis sekretów ( |
| Claude, Cursor, OpenCode, Codex, VS Code (Copilot), Antigravity | Tylko VPS (decyzja w runtime): deny kontenery ( |
| Claude | Tylko Windows: deny |
| Claude | Na każdym Hoście: deny całej przestrzeni |
| Claude | PostToolUse po Edit/Write: format → lint edytowanego pliku (ruff, prettier, eslint, shellcheck, hadolint, yamllint), tylko gdy repo ma config danego narzędzia; wynik wraca do modelu jako |
| Claude | SessionStart: brak |
| Claude | SessionEnd (#371): |
| Copilot |
|
| Copilot |
|
| Antigravity |
|
Zero ask (ADR 0006): Guard odpowiada allow albo deny. W auto mode ask z hooka
blokuje tak samo jak prompt, więc bramka, która pyta, nie jest automatyczna. Model dostaje
permissionDecisionReason i sam dobiera bezpieczną alternatywę. Git odzyska wszystko
w repo; poza repo pilnujemy tylko katalogów systemowych i sekretów — resztę gate'uje
natywna permission klienta (cwd + additionalDirectories).
Granica sensitive-files-guarda pod Bash (#231). Guard blokuje oczywiste
odczyty sekretów — komenda czytająca z jawną ścieżką sekretu, w tym forma po
przepisaniu przez RTK (cat .env → rtk read .env, grep KEY .env → rtk grep KEY .env). Nie jest piaskownicą: python -c "open('.env')", grep -r KEY . ani
zapis sekretu przez Bash (echo X > .env, tee .env) przechodzą. Świadomie poza
zakresem jest też każda inna komenda ze ścieżką sekretu (cp .env.example .env,
ls -la .env, rm .env, git check-ignore .env). Parser jest tekstowy
(split po ;/&/&&/||/| + prefiksy), a nie AST — upgrade ścieżką wspólnego
parsera z server-guardem dopiero przy realnym omijaku, nie przez doklejanie wzorców.
Jeden dialekt, adapter na brzegu. Skrypty polityki mówią wyłącznie kontraktem
Claude Code (hookSpecificOutput.permissionDecision). Cursor (permission), OpenCode
({ tool, input } → { decision, reason }), Copilot (nazwy narzędzi runtime, tool_input
jako string) i Antigravity ({ toolCall: { name, args } } → { decision, reason }) mają
własne kształty, więc invoke-hook.js tłumaczy — i to jedyne miejsce w kicie, które
wie o różnicy między klientami.
Klient | Wywołanie | Kontrakt |
Claude Code |
| natywny, bez adaptera |
Cursor |
| tłumaczony przez adapter |
OpenCode | plugin | tłumaczony przez adapter |
Codex |
| tłumaczony przez adapter; wyjście jak Claude Code ( |
Copilot (VS Code + CLI) |
| tłumaczony przez adapter; deny = top-level |
Antigravity |
| tłumaczony przez adapter; wyjście |
Cursor: beforeShellExecution → git-guard + sensitive-files-guard, beforeReadFile →
sensitive-files-guard (--tool Read), preToolUse z matcherem Write → sensitive-files-guard
(--tool Write).
--tool dopisuje tool_name, którego payload Cursora nie niesie. Wszystkie wpisy mają
failClosed: true — padnięty Guard (brak JSON) blokuje akcję, a nieczytelny payload
daje deny. invoke-hook.js po wypisaniu JSON zawsze kończy exit 0 (niezerowy
exit ukrywa payload przy failClosed).
OpenCode (--clients opencode): bootstrap kładzie git-guard.mjs, sensitive-files-guard.mjs
i invoke-hook.js w .opencode/hooks/ oraz plugin V2 .opencode/plugins/kit-guards.js.
Plugin podpina się pod tool.execute.before: shell (dawniej bash) → git-guard +
server-guard + sensitive-files-guard, read /
edit / write / multiedit → sensitive-files-guard, patch → sensitive-files-guard dla każdego
pliku z patchText (także celu Move to). Nazwy i pola narzędzi sprawdzone na opencode 2.0.24.
Działa niezależnie od permission w opencode.json, także przy allow na bash i edycje. Przy
deny narzędzie kończy się błędem, a model widzi Zablokowane przez guard kita — <powód z guarda>
i dobiera inną drogę. Awaria guarda, timeout (10 s) albo wejście bez oczekiwanego pola
(command, path) = deny. grep i glob nie są pilnowane — tak samo jak w Claude Code.
Codex (--clients codex): bootstrap kładzie guardy, invoke-hook.js i server-guard.json
w .codex/hooks/ oraz .codex/hooks.json (PreToolUse). Powłoka (Bash / shell /
local_shell / exec_command, command jako string albo argv) → git-guard + server-guard +
sensitive-files-guard;
Playwright MCP → server-guard; apply_patch i Read|Edit|Write|… → sensitive-files-guard,
dla apply_patch po kolei na każdej ścieżce z nagłówków *** Add|Update|Delete File: /
*** Move to: (patch bez ścieżek = deny). Ścieżka hooka liczona od roota repo
(git rev-parse --show-toplevel), więc sesja z podkatalogu też jest pilnowana. Nazwy narzędzi
i pola payloadu nie są sprawdzone na żywym Codexie — adapter przyjmuje warianty wyżej.
Bootstrap nadpisuje .codex/hooks.json (cp) — własne wpisy dopisz po każdym reloadzie.
Wymaga node w PATH (OpenCode działa na Bunie, guardy na Node). Tylko API pluginów V2 (export default { id, setup }, jak kit-loop.js); bash-guard,
linters-guard i rtk-check zostają tylko w Claude Code.
Copilot (--clients vscode): bootstrap kładzie guardy, invoke-hook.js i server-guard.json
w .github/hooks/ oraz plik kit-guards.json (PreToolUse, obok hooka rtk-rewrite.json
z #67). Plik używa PascalCase PreToolUse, który czyta VS Code; że ten sam plik i kształt czyta
Copilot CLI — zakładamy, niezweryfikowane. Adapter --to copilot sprowadza nazwy narzędzi
(Copilot CLI: bash / view / create / edit; VS Code: run_in_terminal,
create_and_run_task, read_file, create_file, replace_string_in_file) do nazw Claude
i parsuje tool_input (string JSON, filePath/path); apply_patch i
multi_replace_string_in_file idą przez guard ścieżka po ścieżce. Narzędzie plikowe bez
ścieżki = deny. Narzędzia MCP VS Code (mcp_<server>_<tool>) server-guard rozpoznaje jak
mcp__…. Trzy guardy (git-guard, server-guard, sensitive-files-guard) biegną jako osobne
wpisy PreToolUse bez matcher (native VS Code go nie zna). Deny wychodzi jako nadzbiór
(top-level permissionDecision + hookSpecificOutput); allow to pusty stdout — jawne
allow w VS Code auto-approve'owałoby każde narzędzie i wyłączało natywne potwierdzenia.
Timeout hooka (timeout: 5) przepuszcza wywołanie (fail-open). Znana luka: grep_search
i file_search nie są mapowane — sensitive-files-guard ich nie widzi. Najbardziej restrykcyjna
decyzja wygrywa — deny blokuje wywołanie w agent mode. Wymaga node w PATH.
bash-guard / linters-guard / rtk-check zostają w Claude Code — Copilot ma jedno
narzędzie powłoki, więc nie ma czego rozdzielać.
Antigravity (--clients antigravity): bootstrap kładzie guardy, invoke-hook.js i
server-guard.json w .agents/hooks/ oraz workspace'owy .agents/hooks.json (nazwany hook
kit-guards, PreToolUse). Plik dzielimy z użytkownikiem — scripts/antigravity_hooks.py
scala przy install i prune'uje przy odznaczeniu wyłącznie klucz kit-guards, więc własne
hooki zostają (nieparsowalny plik → .bak i wpis kita od zera). Komendy hooków startują
z katalogu, w którym leży hooks.json, stąd node hooks/invoke-hook.js … --to antigravity.
Adapter sprowadza narzędzia runtime (run_command z CommandLine, view_file
z AbsolutePath, write_to_file / replace_file_content / multi_replace_file_content /
edit_file z TargetFile, MCP jednym narzędziem call_mcp_tool z ServerName / ToolName /
Arguments → mcp__<server>__<tool>) do nazw i pól, które znają guardy; brak pola, którego
guard potrzebuje, = deny. Sprawdzone na żywej sesji agy 1.3.0: allow nie omija polityki
uprawnień Antigravity (w -p komenda i MCP dalej wymagają reguły permissions.allow),
pusta decyzja i awaria hooka (exit ≠ 0) = deny, deny działa też z
--dangerously-skip-permissions. Zachowanie przy przekroczeniu timeout: 10 niesprawdzone.
Znana luka: grep_search, find_by_name i list_dir nie są mapowane — sensitive-files-guard
ich nie widzi. Tak samo view_file_outline i view_code_item (w agy 1.3.0 niedostępne
w środowisku narzędzi, argumentów nie dało się podejrzeć) — matcher plikowy jest zakotwiczony
^(...)$, więc ich nie łapie. Pozostałe nazwy zapisu z binarki (create_file, write_file,
delete_file) też poza mapą, bo nie pojawiły się w żywych payloadach. Wymaga node w PATH. Sprawdzone na agy 1.3.0 — /hooks listuje hook
kit-guards; bash-guard / linters-guard / rtk-check zostają w Claude Code.
Guardy są w .mjs i idą przez node — bez basha, więc bez wykrywania Git Basha na
Windows i bez otwartych okien konsoli.
Server guard (VPS) — twarda blokada ciężkich komend
Po incydencie z 2026-10-15 (restart VPS po uv run bez --no-sync, ADR 0009)
sama reguła tekstowa z infra:vps-lightweight nie wystarcza — subagent pod
night-run nie czyta overlayu tak uważnie jak sesja interaktywna. Dlatego kit ma
twardy guard templates/shared/guards/server-guard.mjs: na VPS odrzuca tylko
komendy, które mogą zawiesić serwer albo uderzyć w inne usługi na nim. Reszta
pracy (edycja, git, lint, typecheck, testy) przechodzi.
Kiedy guard jest aktywny. Decyzja zapada w momencie wywołania, nie przy
instalacji — Profil i .claude/settings.json są commitowane i wspólne dla PC
i VPS. Kolejność: server.guard: off w Profilu → allow; KIT_HOST_PROFILE /
GUIDES_HOST_PROFILE = vps / local → wymuszenie (tylko gdy heurystyka się
myli; normalnie niczego nie eksportujesz); heurystyka 1:1 z host_profile.py
(Linux, nie CI, nie WSL, CPU ≤ 2, RAM ≤ 8 GB, swap 0, wirtualizacja albo brak
desktopu) → aktywny; w pozostałych przypadkach → allow. Na PC i w CI ten sam
zainstalowany guard przepuszcza wszystko.
Gdzie guard działa, a gdzie nie. Zakres jest per host i rozstrzyga się w runtime, tym samym plikiem hooka:
Aktywny: mały linuksowy VPS albo kontener serwerowy (heurystyka wyżej: CPU ≤ 2, RAM ≤ 8 GB, swap 0, wirtualizacja albo brak desktopu).
Nieaktywny: Windows (także Git Bash i PowerShell), macOS, WSL, Codespaces / devcontainer i CI — ten sam zainstalowany guard przepuszcza tam wszystko.
Nic nie ustawia się per projekt: ten sam zacommitowany guard działa identycznie w repo kita i w projektach aplikacyjnych na obu maszynach — na PC nie blokuje, na VPS blokuje. Osobnej konfiguracji „tylko lokalnie” nie ma.
Korekta heurystyki per maszyna. Gdy heurystyka pomyli się w którąkolwiek stronę, wymuś profil zmienną środowiskową na tej maszynie — nie w repo:
# Linux / VPS: ~/.profile albo ~/.bashrc (dotyczy tylko tego hosta)
export KIT_HOST_PROFILE=local # PC, który heurystyka fałszywie uznała za VPS
export KIT_HOST_PROFILE=vps # VPS, którego heurystyka nie rozpoznała# Windows (PowerShell): trwała zmienna użytkownika, nowe powłoki ją widzą
setx KIT_HOST_PROFILE localNie używaj do tego server.guard: off w Profilu: Profil jest commitowany, więc
wyłączyłby guard także na VPS. server.guard: off ma sens tylko w repo, które
nigdy nie trafia na VPS.
Wdrożenie nowej wersji guarda w projekcie. Guardy jadą z bootstrapem/reload,
nie osobno:
Zaktualizuj klon kita (
git pull).W projekcie uruchom
kit-ai reload— podmienia pliki hooków i renderujeserver-guard.jsonna nowo.Zacommituj zmienione pliki hooków w projekcie (
.claude/hooks/…,.codex/…itd.) — to one jadą na VPS pogit pull.
Domyślne deny kita (każde z powodem i alternatywą; precedencja:
server.allow > server.deny > allow kita > deny kita):
Kategoria | Deny | Allow (świadomie) | Powód / alternatywa |
Kontenery |
|
| budowanie i uruchamianie kontenerów tylko w CI; na hoście działają cudze kontenery |
Paczki |
|
| remove --no-sync --no-build |
Inne ekosystemy |
|
| instalacja na serwerze — zależności zmieniają się na PC albo w CI |
CLI instalujące paczki |
| — | CLI samo dopisuje zależności; instalacja tylko na PC albo w CI |
Buildy |
|
| buildy produkcyjne tylko w CI |
Launchery JS |
|
| pobieranie z sieci na VPS; |
Przeglądarki / e2e |
| — | przeglądarka to setki MB na instancję; e2e tylko w CI |
Mnożenie procesów |
|
| xdist mnoży procesy na słabym CPU |
Obejścia też łapie: każdy segment po &&, ||, ;, |, & sprawdzany osobno
(także wnętrze bash -c / bash -lc / sh -c, $( … ) i backticków), a przed
dopasowaniem zdejmowane są prefiksy sudo (z flagami), env (z flagami)
i przypisania VAR=…, nice, ionice, timeout, nohup, time, command,
exec, xargs, eval oraz ścieżka binarki (/usr/bin/docker → docker).
Sprawdzana jest też komenda za launcherem: uv [opcje] run [flagi] X, npx /
bunx X, pnpm|yarn|npm dlx|exec X, python -m X — uv run --no-sync pytest -n 4
to deny, uv run --no-sync ruff allow. Separatory w cudzysłowach i treść heredoca
to dane, nie komendy (git commit -m "…; docker …" i body PR przez heredoc
przechodzą). Backticki i $( … ) w pojedynczych apostrofach też są danymi — bash
ich tam nie wykonuje (--body 'Blokuje `docker compose up`' przechodzi); w podwójnych
cudzysłowach dalej deny. Dopasowanie po tokenach od początku segmentu (task nie łapie
taskfoo). UV_NO_SYNC=1 w linii działa jak w env; tak samo UV_OFFLINE=1 zdejmuje
deny uvx. Flagi przed podkomendą liczone tak jak przez narzędzie (uv --color never sync
to deny); --no-sync i --with w uv run liczą się tylko przed nazwą narzędzia; --help /
--version przed nazwą to pomoc (webpack --version allow, npx cowsay --help deny). Poza VPS guard dla narzędzi
MCP nie zwraca decyzji (zwykłe pytanie o zgodę), dla Bash jawne allow jak
pozostałe guardy kita.
Aktualizacja samego lockfile (#317). Ticket, który dodaje zależność, może
na VPS odświeżyć lockfile bez instalacji: uv lock --no-build,
uv add|remove <pkg> --no-sync --no-build, npm install --package-lock-only --ignore-scripts, pnpm install --lockfile-only --ignore-scripts,
bun install / i / add / remove z --lockfile-only --ignore-scripts. Każda inna forma zostaje deny,
a powód wskazuje dozwoloną. pnpm add zostaje deny (dokumentacja pnpm add nie zna --lockfile-only). --no-build w uv nie zatrzymuje budowania samego
projektu (uv czyta metadane workspace'u, więc ciężki backend maturin /
scikit-build może coś skompilować) — to wyjątek „bez instalacji zależności”, nie
„zero kompilacji”. Yarn nie ma wspólnego trybu lock-only dla 1.x i Berry, więc
zostaje deny. Gdy lock-only pada, bo paczka wymaga builda, ticket dostaje
needs-local i komentarz z nazwą paczki i powodem (jak przy blokującym deny z #315).
server.deny może te formy zablokować z powrotem (skutek uboczny precedencji:
server.deny: "uv run" blokuje też uv run --no-sync). Flagi liczą się tylko
przed -- i #, negacje (--no-x, --x=false) i flagi w cudzysłowach dają deny.
pnpm przy --lockfile-only nadal wykonuje .pnpmfile.cjs projektu.
Wrappery wykonania: rtk. Globalna wtyczka RTK przepisuje komendę, zanim
zobaczy ją plugin guarda w opencode: bun install jedzie jako rtk bun install,
a next build jako rtk next — bez słowa build. Guard zdejmuje więc flagi rtk
(-v…, --ultra-compact, --skip-env), rtk proxy|err|test|summary X ocenia
jak X, rtk run -c "…" jak sh -c, rtk run X jak X, a pozostałe
rtk X … jak X …; dodatkowo rtk next X to zawsze next build X (poza --help), a rtk npm X
to npm X i npm run X. W Claude Code hooki PreToolUse widzą oryginalny
tool_input, więc guard dostaje komendę sprzed RTK, a deny wygrywa
z updatedInput; normalizacja pokrywa ten sam przypadek niezależnie od
kolejności hooków.
Rozwijanie wrapperów przy reload. Guard widzi tylko tekst komendy, więc
kit-ai reload / bootstrap czyta Taskfile.yml / .yaml (z includes
krótkimi i z kluczem taskfile:, cmds jako napisy, - cmd:, - task:, block
scalar - |, deps), scripts z każdego package.json w repo (poza
node_modules i katalogami z kropką, np. .ai/headless-runs) i turbo run <x> (wszystkie nazwy) do skryptów <x> we
wszystkich pakietach workspace. Poziomy łączą się dowolnie (task → bun run →
turbo run → skrypt pakietu), rozwijanie iteruje do stabilizacji. Task / skrypt,
którego komendy (po rozwinięciu) pasują do deny kita albo server.deny, ląduje
jako deny (task <nazwa>, bun run, npm run / run-script, npm test|start,
pnpm [run], yarn [run], turbo run <x>, także z --filter / --cwd)
z łańcuchem w powodzie (bun run build → turbo run build → next build). Projekt nie wypisuje tasków
ręcznie. Po zmianie Taskfile albo package.json trzeba kit-ai reload; guard
bez reloadu działa na starej liście.
Konfiguracja w Profilu (.ai/project.profile.yaml, opcjonalna; brak sekcji
= guard: auto, sama lista kita + wrappery):
server:
guard: auto # auto (domyślnie) | off
deny: # dodatki projektu, których automat nie wykryje (wygrywają z allow kita)
- "bunx eas-cli"
allow: # wyjątki projektu, wygrywają z deny projektu i z listą kita
- "task lints:backend:ruff:check"kit-ai reload / bootstrap renderuje listę kita, wrappery i sekcję server do
server-guard.json obok guarda w katalogu hooków każdego klienta (guard nie
parsuje YAML-a). Nieznany klucz albo zły typ w server jest zgłaszany, ale nie
przerywa działania (ADR 0004). Gotowe propozycje dodatków do server.deny:
dev serwery i watchery, pytest bez ścieżki, systemctl / pkill — na serwerze
z kilkoma GB RAM nie zawieszają go same z siebie, więc nie ma ich na liście
domyślnej.
UV_NO_SYNC per maszyna. Task, który w środku woła uv run bez flagi,
przechodzi tylko gdy klient na serwerze ma w env UV_NO_SYNC=1. Dla Claude
kit-ai reload zapisuje env.UV_NO_SYNC="1" do niecommitowanego
.claude/settings.local.json tylko na hoście VPS (kit-ai host); na local wpis
kita jest zdejmowany, a ręczna wartość inna niż 1 zostaje (#334). Ustawienie
env z tego pliku musi docierać do hooka — po stronie VPS sprawdź to ręcznie
(sekcja niżej). OpenCode nie ma pliku env per maszyna — guard widzi środowisko
procesu, więc zmienna musi być w powłoce serwera (np. export UV_NO_SYNC=1 w
~/.profile). Bez niej task z uv run bez --no-sync w środku dostaje deny.
Ręczne sprawdzenie guarda:
echo '{"tool_input":{"command":"docker compose up"}}' | KIT_HOST_PROFILE=vps node .claude/hooks/server-guard.mjsRelacja z CI. Na VPS przechodzą szybkie bramki (lint, typecheck, unit); pełna weryfikacja (kontenery, migracje, integracje, e2e, build) należy do CI.
Czego guard tekstowy nie złapie (agent zapisuje własny skrypt i go odpala)
i zalecenia dla hosta: wyłącz plugin Playwright MCP na serwerze (guard blokuje
narzędzia, ale proces MCP i tak startuje), użytkownik agenta poza grupą docker
i bez sudo bez hasła, limit pamięci na sesję agenta, jeśli host na to pozwala.
Migracja z lokalnego guarda projektu: podbij wersję kita w projekcie,
kit-ai reload, usuń własny plugin guarda; listy „nie uruchamiaj" z overlayu
zastępuje guard.
Regresja: uv run python -m unittest tests.test_guards (tabela allow/deny każdego Guarda)
i bash tests/test_guard_adapter.sh (tłumaczenie kontraktu) — odpalane też przez CI
(tests/test_shell_suites.py wciąga suity powłoki do unittest discover).
Code review (Bugbot + GitHub)
Moduł MCP: core:code-review (bundle devops lub architecture).
Minimalny zestaw przed pushem (nie odpalaj całego wachlarza):
Zmiana | Minimum |
Drobna |
|
Backend / Frontend | Bugbot + |
API + UI | Bugbot + BE+FE lub para |
Auth / płatności |
|
Dowód „działa” |
|
Bugbot = blocking/security. Stack /review-* = konwencje z MCP (Severity | Location | Finding | Fix).
Przy codegen: orval w overlay — po zmianie API regeneruj klienta.
Warstwa | Plik / akcja |
Lokalnie |
|
Przed push |
|
Na PR | Bugbot (GitHub integration) |
Reguły |
|
CI (ten kit) |
|
Hook regresja |
|
Suity powłoki w CI |
|
Zależności Python (pin majora)
mcp>=1.0.0,<2 # FastMCP (1.x); mcp 2.0 usuwa mcp.server.fastmcp
pyyaml>=6.0,<7uvx resolvuje zależności od zera (nie bierze lokalnego uv.lock) — upper bound chroni konsumentów przed breaking major.
Skills / pluginy zewnętrzne (poza tym kitem)
Trzy warstwy — nie bundluj Matt/Superpowers w guides-mcp:
Warstwa | Przykłady | Gdzie | Rola |
Fundament | Context7, | MCP + agents/skills z bootstrap | stack, git, skrót czatu (Cursor) |
Proces |
|
| |
Meta | superpowers, caveman, Autopilot | user / plugin Cursor | worktree, finishing, CI loop |
Priorytet w AGENTS.md: użytkownik → overlay+MCP → review kita → Matt → Superpowers.
TDD: jeden path na feature (preferuj Matt). W repo z kitem setup Matta nie jest potrzebny:
kit-ai reload renderuje jego kontrakt (niżej); poza kitem uruchom /setup-matt-pocock-skills.
Kontrakt Matta w repo z kitem (#241)
Gdy skills-lock.json zawiera mattpocock/skills, reload tworzy brakujące pliki,
których oczekują skille Matta. Wartości bierze z repo i z kita, a format — z ziaren
.agents/skills/setup-matt-pocock-skills/*.md czytanych w momencie reloadu (aktualizacja
skilli przez skills-lock.json zmienia render bez zmian w kicie). Istniejących plików
docs/agents/* nie nadpisuje — możesz je edytować. Brak ziaren albo brak skilli Matta →
krok pomijany bez błędu.
Plik | Skąd wartości |
| ziarno |
| ziarno |
| ziarno |
blok | format setupu Matta; aktualizacja w miejscu, reszta pliku bez zmian |
| indeks źródeł standardów w kolejności ważności: |
CODING_STANDARDS.md to sam indeks (bez kopii reguł), odświeżany przy każdym reloadzie.
Czytają go agenci /review-* kita oraz /code-review i retro Matta — dlatego nazwa
jest zgodna z tym, czego szukają skille Matta. Dzięki temu /code-review nie prosi
o /setup-matt-pocock-skills, a jego oś Standards widzi BUGBOT.md, overlay i ADR-y.
--remove usuwa CODING_STANDARDS.md i docs/agents/* tylko wtedy, gdy są nietkniętym
renderem kita.
Context7 (docs Django/Expo): globalnie npx ctx7 setup --cursor.
Subagenty — szczegóły
Każdy plik agentów jest cienkim wrapperem: przy starcie woła get_bundle / get_overlay z MCP project-guides. Wiedza merytoryczna żyje w modules/.
Praca w dwóch oknach: /subagent-backend ↔ /subagent-frontend — sekcja „Raport do przekazania” na końcu odpowiedzi.
Available Tools
12 toolsbootstrap_workspaceA
Zainstaluj pliki kita (hooki, agenci, komendy, mcp.json, stamp) w repo aplikacji.
Jedyne narzędzie MCP, które zapisuje na dysk — reszta serwera jest tylko do
odczytu. Bez tego trzeba sklonować kit lokalnie i ręcznie odpalić
scripts/bootstrap-project.sh; tu ten sam skrypt uruchamia serwer, który już
ma wszystkie szablony pod ręką.
dry_run=True jest domyślne i nic nie zapisuje: skrypt leci na kopii kitowej
powierzchni repo w katalogu tymczasowym, a wynikiem jest lista plików, które
powstałyby, zostałyby nadpisane albo usunięte. Zapis wymaga jawnego
dry_run=False — hooki PreToolUse łapią Bash/Edit/Write,
a nie nazwy narzędzi MCP, więc ta domyślka jest tu jedyną bramką.
Args:
clients: --clients: all | cursor | claude | codex | vscode | kiro | kilo |
antigravity | opencode (po przecinku). Domyślnie: wartość startowa serwera.
preset: Kategoria presetu (_base, shop). Domyślnie: preset serwera.
language: Język prozy pl/en. Domyślnie: język bieżącego profilu.
codegen: orval/none/graphql. Domyślnie: codegen bieżącego profilu.
with_overlay: Skopiuj szablon .ai/project.md, jeśli repo go nie ma.
keep_unselected_clients: Nie usuwaj kitowych plików klientów spoza clients.
dry_run: True (domyślnie) — tylko plan. False — faktyczny zapis.
Returns: str: Markdown — plan zmian (dry run) albo raport z instalacji i stampu.
Inputs: preset, clients, codegen, dry_run, +3 more. Returns: result
check_kit_statusA
Sprawdź czy kit zmienił się od ostatniego bootstrap-project.sh w tym repo.
Tanie: porównuje commit zapisany w .ai/.kit-bootstrap.json z aktualnym HEAD
kita (git rev-parse/diff --name-only) — nie czyta treści modułów instrukcji.
Moduły (modules/*.md) są i tak czytane live przez get_bundle/get_overlay,
więc nigdy nie "gniją" — ten tool dotyczy tylko plików które bootstrap
kopiuje (agents/commands/mcp.json), bo te są statyczną migawką.
Returns: str: Markdown — aktualny / zmienił się (+ lista plików które re-bootstrap by nadpisał) / brak stampu / brak lokalnej historii git do porównania.
Inputs: no named parameters. Returns: result
get_bundleA
Pobierz pełną treść bundle'a instrukcji.
Args: name: Nazwa bundle'a, np. backend, frontend, architecture, full.
Returns: str: Połączona treść Markdown wszystkich modułów w bundle'u + overlay (jeśli dotyczy).
Inputs: name (required). Returns: result
get_clientsA
Lista klientów AI skonfigurowanych przy starcie MCP (--clients / GUIDES_CLIENTS).
Metadane instalacji szablonów — nie zmieniają treści bundle.
Returns: str: Markdown z wartością flagi i rozwiniętą listą id klientów.
Inputs: no named parameters. Returns: result
get_codegenA
Aktualny wybór generatora klienta API (--codegen / codegen: w profilu).
Returns:
str: Markdown — orval (schema → frontend/src/api/generated + mutatory),
none (tool-agnostyczny klient, konkret w overlay projektu) albo
graphql (GraphQL zamiast REST, patrz arch:api-contract:graphql).
Inputs: no named parameters. Returns: result
get_indexB
Indeks włączonych modułów i bundle'i dla bieżącego profilu.
Returns: str: Markdown z podsumowaniem konfiguracji profilu.
Inputs: no named parameters. Returns: result
get_languageA
Aktualny język instrukcji i polityka tytułów vs prozy.
Returns:
str: Markdown z kodem języka, modułem core:language-* i regułami EN/PL.
Inputs: no named parameters. Returns: result
get_moduleA
Pobierz pojedynczy moduł instrukcji po identyfikatorze.
Args: module_id: Id modułu z manifestu, np. stack:django-drf:backend-standard.
Returns: str: Treść Markdown modułu.
Inputs: module_id (required). Returns: result
get_overlayA
Pobierz overlay projektu — unikalne instrukcje tylko dla tego repo.
Returns:
str: Treść .ai/project.md i innych overlay wskazanych w profilu.
Inputs: no named parameters. Returns: result
list_bundlesA
Lista dostępnych bundle'i instrukcji dla bieżącego profilu projektu.
Returns: str: Markdown z listą bundle'i i liczbą modułów.
Inputs: no named parameters. Returns: result
list_modulesB
Lista wszystkich modułów dostępnych w instruction-kit (manifest).
Returns: str: Markdown z identyfikatorami i tytułami modułów.
Inputs: no named parameters. Returns: result
list_presetsA
Lista dostępnych presetów w instruction-kit (profiles/*.yaml).
Returns:
str: Markdown z kategoriami (_base, shop, …).
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool has a clearly distinct target: get_* returns a specific configuration piece, list_* enumerates available options, check_kit_status compares state, and bootstrap_workspace is the only write operation. Even the overlapping get_overlay and get_bundle are disambiguated by descriptions: overlay-only vs combined bundle.
All tool names follow a consistent snake_case verb_noun pattern with predictable prefixes: get_, list_, check_, bootstrap_. The naming makes the tool surface easy to scan and select from.
12 tools is well within the ideal scope for a configuration/instruction server. Every tool covers a distinct need—reading project guides, listing modules/presets/bundles/clients, checking kit status, and bootstrapping the workspace—with no obvious filler.
The tool surface covers the full lifecycle for this domain: read current project context, discover available content, inspect kit state, and perform the only intended mutation (bootstrap install with dry-run). No critical dead-end operations are missing.
Maintenance
Related MCP Connectors
Read-only AI project discovery, verification, comparison, shortlisting, and stack planning.
Project memory for coding agents: requirements, decisions, code graph and delivery telemetry.
Durable, shareable and governed project memory with smart triage and explicit project composition.
Provide your AI coding tools with token-efficient access to up-to-date technical documentation for…
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides AI agents with professional coding standards, development best practices, and context-aware guidance through static documentation and AI-powered custom recommendations. Enables agents to access comprehensive development guidelines including coding rules, debugging techniques, and AI steering instructions.-
- AlicenseBqualityDmaintenanceProvides centralized security instructions for AI-assisted code generation by matching context-aware rules to the user's programming language and file patterns. It ensures generated code adheres to security best practices without requiring manual maintenance of instruction files across individual repositories.28 npm1MIT
- AlicenseAqualityDmaintenanceManages project standards, configurations, and API debugging for AI-assisted development, ensuring unified development practices across teams and machines.1348 npm6MIT
- AlicenseAqualityDmaintenanceProvides LLMs with structured workflow guidance and next-step instructions for development procedures, ensuring consistent practices across projects.51MIT