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 install

Bez @ 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 repo

Related 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)

# jednorazowo, bez instalowania narzędzia:
uvx --from git+https://github.com/radthenone/ai-instruction-kit-mcp kit-ai install

Wybrany 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.

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 rtk

rtk 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.rtk

Hook, który przepisuje komendy na rtk … poza modelem — po jednym na klienta:

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)

Skille Matta Pococka (mattpocock/skills, aihero.dev/skills) — /grill-me, /tdd

Caveman (JuliusBrussee/caveman)

Ponytail (DietrichGebert/ponytail)

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

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:

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 skills domyślnie robi symlinki, a te na Windowsie wymagają Developer Mode albo admina. Bez tego dodaj --copy.

• Lokalny (stdio) serwer MCP odpalany przez npx uruchamiaj na Windowsie jako cmd /c npx …. Serwery zdalne (Context7, GitHub wyżej) tego nie potrzebują.

• Pełny instalator Caveman: na Windowsie install.ps1, nie install.sh — hooki i tak wołają wersje PowerShell.

• Hooki Ponytail i Caveman (Claude, Codex) potrzebują node w 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/prompts

Doctor — 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ŻENIE z 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 ich src/ / 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 prefiksem backend: / web: / mobile: liczy się tylko wewnątrz katalogu tego Tieru (klucz backend: / web: / mobile: w ## Ścieżki). Plik, który leży wyłącznie w innym Tierze, daje stale-path. Prefiks linii wygrywa z nagłówkiem; ścieżka pełna od roota repo i sekcja bez Tieru — bez zawężania;

• klucze ## Ścieżki w overlayu (backend:, web:, routes-web: …) — katalog albo plik musi istnieć;

• komendy /nazwa — muszą mieć agenta, komendę albo skill u któregoś klienta z clients:; 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):

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 miejsca

Bez --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ę:

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/ i docs/plans/ nazywały się wcześniej docs/superpowers/{specs,plans}. Zmiana jest celowa: Superpowers i mattpocock/skills to 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)

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}"
      ]
    }
  }
}

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).

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

Bundle 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-edge

• Brak klienta albo tieru w models: = brak pola model (agent dziedziczy model sesji). Bez models: 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 blok agents: — komentarze w nim giną.

• Nieznany tier (w models: albo agents:), 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 /headless zwróci limit (kod 75, #257). Tylko alias Claude Code: haiku, sonnet, opus, fable; inny zapis przerywa reload. Brak klucza = model sesji.

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:

1. W manifest.yaml → mappings.tiers.<tier> dopisać dozwolone Stacki (np. fulfillment nie — Tiery to backend/web/mobile; nowy wymiar trafia do decisions albo capabilities).

2. W mcp.json dodać np. "--tag", "physical" albo "--facet", "fulfillment=physical" (docelowa składnia przy implementacji).

3. 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-mcp

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

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.json

Typowy .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, PowerShell i Edit|Write|MultiEdit|NotebookEdit — nie nazwy narzędzi MCP. To jedyne zapisujące narzędzie tego serwera i hooki go nie zatrzymają; dry_run=True jako domyślka plus wymóg jawnego dry_run=False są 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).

Zmienna dla --workspace:

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-overlay

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:

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 → Autopilot

Nie 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-plugins

Co 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 IDE

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

1. Napisz modules/infra/queue/kafka.md.

2. Zarejestruj go w manifest.yaml → modules:.

3. 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-virt albo brak desktopu). Nadpisanie: KIT_HOST_PROFILE=vps|local (alias GUIDES_HOST_PROFILE). CI zawsze dostaje local — pełna weryfikacja należy do CI.

• get_bundle na takim hoście dokleja infra:vps-lightweight do każdego bundle'a (też backend/frontend/architecture); get_index pokazuje - 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 lint lekkie vs task test:e2e cięż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

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

Bootstrap w projekcie docelowym

W repo aplikacji uruchom scripts/bootstrap-project.sh albo skopiuj z templates/:

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

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_status

Bootstrap 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

/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 /compact zamiast 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)

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 → merge

/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-end

Rę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).

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).

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-pip interpreterem z głównego venv (identyczna wersja),

• plik _kit_worktree.pth w site-packages przekierowuje pakiety instalowane w trybie editable (-e) z prefiksem głównego repozytorium na ścieżkę worktree, a następnie dopisuje site-packages głó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 przez python -m … lub uv 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_modules czy współdzielony site-packages nie powinny być modyfikowane z poziomu worktree (postinstall, ensurepip czy instalacja paczek zmieniają środowisko główne).

• Pliki konfiguracyjne MCP: kopiowane pliki wskazują ścieżkę --workspace głó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.

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śli origin/dev istnieje i nie jest w tyle za gałęzią domyślną; inaczej gałąź domyślna repo. Porzucony dev nie 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 ~/.cache przeżywa restart hosta (/tmp po 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 z infra: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 (i codegen:). 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 python3 liczy z transkryptów subagentów tury, tokeny (input / cache_creation / cache_read / output), maks. kontekst i czas. Wynik trafia do NIGHT-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:

1. 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>.

2. Na każdy model osobny worktree z tego commitu i osobna sesja z dokładnym id modelu:

   git worktree add ../measure-<model> <commit>
   cd ../measure-<model> && claude -p --model <id> "/night-run #<N>, bez merge"

3. PR służy tylko do pomiaru: po zebraniu wyników gh pr close <PR> --delete-branch i git worktree remove ../measure-<model>.

4. Metryki: snippet z sekcji „Pomiar kosztu ticketu” w agencie, uruchomiony na transkryptach sesji i jej subagentów (~/.claude/projects/<projekt>/<sesja>.jsonl i …/<sesja>/subagents/*.jsonl). Koszt liczysz osobno dla input, cache_creation, cache_read i output według aktualnego cennika, nie jedną stawką.

5. Jakość: CI zielone za pierwszym razem (t/n), liczba rund poprawek, potwierdzone findingi review, needs-human (t/n).

6. 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-start itd. — $ARGUMENTS wstrzyknięty automatycznie przy kopiowaniu).

• Codex: agenty instalowane jako natywne skille w .codex/skills/<nazwa>/ (renderowane z templates/shared/agents/*.md przez scripts/install_shared_skills.py). Custom prompts (.codex/agents/*.toml) zostały wycofane w Codex CLI — Codex sam ładuje SKILL.md, gdy description pasuje 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 /nazwa w Copilot Chat).

• Kilo: scripts/render_agent_commands.py kilo → .kilocode/workflows/*.md (wywołanie /nazwa, $ARGUMENTS wspierane).

• Antigravity: agenty jako natywne skille w .agents/skills/<nazwa>/ (agy nie zna workflow — patrz install_agent_skills.py).

• opencode: scripts/render_agent_commands.py opencode → .opencode/command/*.md (wywołanie /nazwa, $ARGUMENTS wspierane). Guardy kita: plugin .opencode/plugins/kit-guards.js + .opencode/hooks/ (sekcja „Guardrails”). Model: projektowy opencode.json dostaje przy install i reload model z globalnego configu OpenCode, tylko gdy projekt nie ma własnego model. Katalog jak w OpenCode: $XDG_CONFIG_HOME/opencode/ albo ~/.config/opencode/ (na Windows %USERPROFILE%\.config\opencode\); pliki config.json, opencode.json, opencode.jsonc (komentarze dozwolone), ostatni z model wygrywa. Kolejność: model w projektowym opencode.json → globalny config → domyślny model OpenCode. Nadpisanie: wpisz model w projektowym opencode.json — reload go nie rusza. Kopia nie śledzi późniejszych zmian globalnego configu; żeby ją odświeżyć, usuń model z projektu i zrób reload. Inne pola globalnego configu (provider, agent) nie są kopiowane. Do tego /goal i /loop jak w Claude Code: templates/opencode/command/{goal,loop}.md + plugin .opencode/plugins/kit-loop.js, który po session.execution.succeeded wysył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 oknie

Skille 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.

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>] "<treść>"

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 git worktree add --detach <katalog runu>/base <ref> i git worktree remove 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, 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); ś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 (bez zabijania; to robi --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.

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.

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.

Fallback przy limicie. Limit dostawcy 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. Limit u ostatniego → kod 75 i zadanie przejmuje host (agent /headless, krok 2). 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):

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:

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.

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.

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 local

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

1. Zaktualizuj klon kita (git pull).

2. W projekcie uruchom kit-ai reload — podmienia pliki hooków i renderuje server-guard.json na nowo.

3. Zacommituj zmienione pliki hooków w projekcie (.claude/hooks/…, .codex/… itd.) — to one jadą na VPS po git pull.

Domyślne deny kita (każde z powodem i alternatywą; allow wygrywa z deny):

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. Poza VPS guard dla narzędzi MCP nie zwraca decyzji (zwykłe pytanie o zgodę), dla Bash jawne allow jak pozostałe guardy kita.

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
    - "bunx eas-cli"
  allow:             # wyjątki, wygrywają z deny
    - "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 miejscem per maszyna jest niecommitowany .claude/settings.local.json (env). 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.mjs

Relacja 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):

Bugbot = blocking/security. Stack /review-* = konwencje z MCP (Severity | Location | Finding | Fix).
Przy codegen: orval w overlay — po zmianie API regeneruj klienta.

Zależności Python (pin majora)

mcp>=1.0.0,<2      # FastMCP (1.x); mcp 2.0 usuwa mcp.server.fastmcp
pyyaml>=6.0,<7

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

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.

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.