Instruction Kit — MCP z instrukcjami projektów

Centralne repo MD + serwer MCP. Projekty wybierają kategorię (--preset) + opcjonalnie overlay / fork.

Szybki start — instalacja i update

Jedna komenda robi oba. Bootstrap jest idempotentny: pliki generowane (agenci, komendy, hooki, mcp.json) nadpisuje świeżą kopią, a pliki z Twoją treścią (AGENTS.md, .ai/project.md, BUGBOT.md) zostawia w spokoju.

Wymagania: uv w PATH, bash (Windows: Git for Windows), node (dla hooków), opcjonalnie npx (skille zewnętrzne).

1. Instalacja / update w projekcie

Ustaw dwie ścieżki i uruchom — reszta bloków korzysta z tych zmiennych:

KIT=/m/projects/ai-instruction-kit-mcp      # klon tego repo
APP=/m/projects/moja-appka                  # repo aplikacji

bash --noprofile --norc "$KIT/scripts/bootstrap-project.sh" "$APP" \
  --from "$KIT" \
  --clients claude,codex,vscode \
  --preset shop \
  --language pl \
  --codegen orval \
  --with-overlay

2. Po instalacji (kroki, których skrypt nie zrobi za Ciebie)

# a) hook pre-push — skrypt kopiuje go do git-hooks/, ale nie do .git/
cp "$APP/git-hooks/pre-push" "$APP/.git/hooks/pre-push"
chmod +x "$APP/.git/hooks/pre-push"

# b) Superpowers — plugin marketplace Claude Code, nie da się ze skryptu.
#    Wpisz w Claude Code:
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

c) 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 "$APP/.claude/hooks/invoke-hook.js" gate-destructive.sh

# konfiguracja AI wchodzi do repo, lokalny stan nie
git -C "$APP" status --short -uall .claude .codex .github/prompts

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, i te wymagające ręcznego przeniesienia (AGENTS.md, BUGBOT.md, .ai/project.md, git-hooks/pre-push — kopiowane tylko gdy brak, żeby nie zdeptać Twojej treści). Gdy pokaże zmiany, powtórz komendę z kroku 1 z tymi samymi flagami.

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:

bootstrap_workspace()               # dry run — lista plików nowych/nadpisanych/usuniętych
bootstrap_workspace(dry_run=False)  # instalacja

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

Related MCP server: CodeGuard MCP Server

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 ≠ preset; porty ≠ tag.

Flagi (aktualne)

{
  "mcpServers": {
    "project-guides": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/TWOJ_USER/ai-instruction-kit-mcp.git",
        "guides-mcp",
        "--preset", "_base",
        "--language", "pl",
        "--clients", "all",
        "--workspace", "${workspaceFolder}"
      ]
    }
  }
}

Albo --profile, albo --preset — nie oba naraz. Bootstrap bez --preset w CLI i tak zapisuje _base w mcp.json. Bootstrap zapisuje też --language (domyślnie pl) oraz --clients (domyślnie all).

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): flaga --codegen orval (default) | none | graphql, do tego env GUIDES_CODEGEN i MCP tool get_codegen. Priorytet: --codegen / GUIDES_CODEGEN → codegen: w YAML profilu → orval. Reviewery FE/BE to honorują (przy orval wymagają regeneracji klienta po zmianie API; graphql → moduł arch:api-contract:graphql zamiast REST).

Sklep: "--preset", "shop". Szczegóły produktu tylko w .ai/project.md.

Fork kategorii (inny zestaw capabilities / decisions):

# .ai/project.profile.yaml w repo aplikacji
name: moj-fork
extends: profiles/shop.yaml
decisions:
  queue: rabbitmq

W mcp.json zamień --preset na:

"--profile", "${workspaceFolder}/.ai/project.profile.yaml"

Szczegóły: [profiles/README.md](profiles/README.md).

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 profiles/shop.yaml zdefiniować dozwolone facety (np. fulfillment: [physical, digital]).

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",
  "--preset", "shop",
  "--tag", "physical",
  "--tag", "b2c",
  "--workspace", "${workspaceFolder}"
]

Bootstrap

# Generyczny — default _base + --language pl (nie podawaj --preset)
./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

# Kategoria e-commerce, proza EN, wszyscy klienci AI
./scripts/bootstrap-project.sh /sciezka/do/moj-sklep \
  --preset shop \
  --language en \
  --clients all \
  --from /absolutna/sciezka/do/ai-instruction-kit-mcp

Zapisuje m.in. MCP per klient (--preset, --language, --codegen, --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.

.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 i to, co i tak żyje globalnie:

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)

Argumenty (clients, preset, language, codegen, 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 --preset/--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, …
  domains/           shop
  patterns/          capability-provider, providers-and-settings, gateway, webhooks, …
  infra/             database, cache, queue, storage, tasks, search
profiles/
  _base.yaml         fundament stacku (default)
  shop.yaml          kategoria e-commerce
  *.yaml             kolejne kategorie (blog, …) — nie nazwy produktów
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).

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 ręcznie w bundles.backend/bundles.frontend). 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 | Lokalne nadpisania presetu | nie (tylko fork) | | .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/*.sh | Review + blokady destrukcyjne (node → bash wg OS) | 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 preset + opcjonalny overlay.

Update kita w projekcie

Bootstrap to jednorazowy stempel, nie sync. Trzy różne zachowania:

Lokalny klon: uv run --directory, 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, modules/ i profiles/ 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", "--directory", "/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 — odpal bootstrap ponownie z tymi samymi flagami.

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

/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

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: scripts/render_agent_commands.py antigravity → .agents/workflows/*.md (wywołanie /nazwa; limit 12 000 znaków/plik, kit przycina jeśli trzeba).

• opencode: scripts/render_agent_commands.py opencode → .opencode/command/*.md (wywołanie /nazwa, $ARGUMENTS wspierane).

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.

Guardrails — bezpieczeństwo

Jedno źródło polityki: templates/shared/guards/. Bootstrap kopiuje je do katalogu hooków wybranego klienta (--clients), więc Cursor i Claude Code egzekwują dokładnie te same reguły.

Git odzyska wszystko, co zacommitowane. Dlatego polityka celuje w dwie rzeczy, których nie odzyska: pracę niezacommitowaną i pliki spoza repo.

Jeden dialekt, adapter na brzegu. Skrypty polityki mówią wyłącznie kontraktem Claude Code (hookSpecificOutput.permissionDecision). Cursor ma własny kształt (permission), więc invoke-hook.js tłumaczy — i to jedyne miejsce w kicie, które wie o różnicy między klientami.

gate-destructive ma failClosed: true — padnięty skrypt (brak JSON) blokuje akcję. Nieczytelny payload daje ask, nie allow: skoro nie wiadomo, co przeszłoby przez bramkę, decyzję podejmuje człowiek. invoke-hook.js po wypisaniu JSON zawsze kończy exit 0 (niezerowy exit ukrywa payload przy failClosed).

Wykrywanie OS (bez hardcodu Windows w trackowanym JSON): invoke-hook.js na Linux/macOS woła bash --noprofile --norc z PATH; na Windows szuka Git Basha (Git/bin/bash.exe) i ustawia windowsHide. Sama ścieżka .sh w konfiguracji hooka → na Windows klient robi bash --login -i i zostawia otwartą konsolę.

Adapter parsuje payload raz i podaje komendę w GUARD_COMMAND, żeby skrypt polityki nie startował własnego interpretera przy każdym wywołaniu — przy shimach w stylu pyenv-win to różnica rzędu sekund na komendę.

Regresja: bash tests/test_gate_destructive.sh (polityka) 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). Setup Matt: po instalacji uruchom /setup-matt-pocock-skills.

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.