Instruction Kit — MCP z instrukcjami projektów

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

Gdzie czytać / zmieniać konfigurację:

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) — dziś w overlay, nie w CLI: w .ai/project.md / templates/extras.md ustaw codegen: orval (default) | none | graphql. Reviewery FE/BE honorują to (przy orval wymagają regeneracji klienta po zmianie API; graphql → arch:api-contract:graphql zamiast REST). Docelowo flaga MCP --codegen — zob. design overlays.

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.

Related MCP server: CodeGuard MCP Server

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:

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

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: templates/codex/agents/*.toml (ręczny, curated) → .codex/agents/; agenci bez ręcznego TOML są auto-renderowani z templates/shared/agents/*.md (scripts/render_agent_commands.py codex) — pełna lista /git-*, /review-*, /subagent-* trafia do .codex/agents/, curated ma pierwszeństwo nad auto.

• 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

Cursor Hooks — bezpieczeństwo

gate-destructive ma failClosed: true — padnięty skrypt (brak JSON) blokuje akcję.
invoke-hook.js po wypisaniu JSON z permission zawsze kończy exit 0 (niezerowy exit ukrywa payload przy failClosed).

Hooks — wykrywanie OS (Bash wszędzie, bez hardcodu Windows w trackowanym JSON):

Sama ścieżka .sh w hooks.json → Cursor na Windows robi bash --login -i i zostawia konsolę.
Terminal IDE (Git Bash) bez zmian — to tylko spawn hooków.

Szablon: templates/cursor/hooks/gate-destructive.sh (bootstrap → .cursor/hooks/).
Regresja plus-refspec / -f: bash tests/test_gate_destructive.sh — 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.