backend-integration-guide@1.0.0

README.md

@@ -6,6 +6,7 @@
 
 - **[format-html](./format-html/SKILL.md)** — форматирование и исправление сырой HTML-разметки (отступы в 4 пробела, выравнивание структуры, закрытие тегов).
 - **[html-to-scss](./html-to-scss/SKILL.md)** — генерация структуры SCSS по методологии БЭМ на основе переданной HTML-разметки.
+- **[backend-integration-guide](./backend-integration-guide/SKILL.md)** — генерация краткой инструкции по интеграции вёрстки для бэкенда/CMS по git-коммиту.
 
 ## Установка
 

backend-integration-guide/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: backend-integration-guide
+description: Generate a concise backend integration guide from a git commit, range, or branch (defaults to the latest commit when none is given). Use when the user asks for integration instructions for backend/CMS developers. Outputs a Russian plain-text guide in chat.
+license: MIT
+metadata:
+  author: Valentin Silyutin
+  version: "1.0.0"
+---
+
+# Backend Integration Guide Generation Instructions
+
+Analyze the changes of a git commit (or range/branch; with no input, the latest commit) and produce **a short Russian guide for the backend/CMS developer**, describing what changed in the markup and data that matters to them.
+
+## Output Rules
+
+- **Language:** the whole guide is written in **Russian**. Only code, paths, selectors, commands and API identifiers stay as-is.
+- **Plain text, no markup:** print the guide as plain text without any Markdown formatting — no `#` headings, no `**bold**`, no backtick fences. Section titles are plain lines, list items start with `- `, JSON is shown with indentation. The output is pasted into a Planfix visual editor that does not parse Markdown or HTML.
+- **Plain human Russian:** write simple, natural sentences. Describe the action in words, not with arrows or jargon. Say «в блок `.catalog-list` добавить класс `.catalog-list_category`», not «`.catalog-list → .catalog-list_category`». Avoid канцелярит («точки монтирования», «статичная разметка»): use «компоненты», «разметка фильтра» и т. п.
+- **Do not list nested content.** If a block is added or removed as a whole, its inner elements and nested blocks are obvious — do not enumerate them.
+- **Destination:** print the guide **in the chat only**. Do **not** create or modify any files.
+- **Concise:** one line per meaningful change. Do not retell the diff.
+- **Report changes only:** never write about what stayed the same — unchanged pages, sections, assets or fields are simply not mentioned.
+- **Never invent:** only mention classes, fields, requests, assets and variables that actually appear in the analyzed changes. If something is absent, do not mention it.
+
+## 1. Determine the Range
+
+Resolve the input into a `BASE` and `TARGET` revision:
+
+- **No argument**: `BASE=HEAD^`, `TARGET=HEAD` (the latest commit).
+- **Single hash `<hash>`**: `BASE=<hash>^`, `TARGET=<hash>`.
+- **Range `<from>..<to>`**: `BASE=<from>`, `TARGET=<to>`.
+- **Branch `<branch>`** (including `origin/<branch>`): `BASE=$(git merge-base HEAD <branch>)`, `TARGET=<branch>`.
+
+Get the task number and title from the commit subject (format `#<номер задачи> <описание>`):
+
+```
+git log -1 --format=%s <TARGET>
+```
+
+## 2. What Changed
+
+Only `src/**` and `html/**` carry integration-relevant changes. Ignore:
+
+- `www/**` — the build output, not tracked in git; never treat it as the markup source (that is `html/**`).
+- `*_index.scss`, `*_index.js`, `src/scripts/mocks/handlers/_index.js`.
+- The preview sitemap page listing links to all preview pages ("Карта сайта"), if the project has one; it is not part of the CMS integration. Do not confuse it with a regular `index` page.
+- Formatting-only changes with no semantic difference.
+
+Detect each category independently:
+
+### HTML markup — source of truth is `html/**`, NOT `src/templates/**`
+
+The folder `html/` contains the built HTML used precisely to see markup changes. `src/templates/**` (Nunjucks) may change while the resulting HTML stays the same.
+
+Use whitespace-insensitive diff to drop indentation noise:
+
+```
+git diff -w --ignore-blank-lines BASE TARGET -- html/
+```
+
+- If `html/**` has real changes → list them per page under **«Изменения по HTML»**.
+- Otherwise → omit the markup section entirely.
+
+When describing a changed HTML page (any `html/**/*.html`, including fragments such as `header/`, `footer/`, `layout/`):
+- new / changed / removed blocks and elements — by BEM class, as a plain sentence;
+- new states (modifiers), new target pages;
+- **ignore plain URL values** (`href`, `data-infinite`, `data-request`, etc.): the backend uses its own addresses, so do not report them.
+
+### Initial page state — `src/json/**` and template globals
+
+Data that must already be on the page at load time — a global object emitted by a template and read by JS (`window.*`, `STATE_*`, etc.).
+
+`src/json/**` files are fixtures: at build time they only become Nunjucks variables used to generate HTML. If such data is used **only to render HTML in Nunjucks**, do not report it.
+
+Report data only when it reaches the JS/Vue layer, because that is the backend contract:
+
+- a global object emitted by a template and read by JS (`window.*`, `STATE_*`, etc.);
+- a direct import of JSON into the code.
+
+Search for such globals directly in the templates (e.g. `STATE_FILTER` in `_catalog.njk`), **even when `src/json/**` did not change**.
+
+Show the expected structure as a **raw JSON example**, not as a prose field list.
+
+### AJAX requests — `src/scripts/**`
+
+Only report a change here when the **data exchange contract with the backend changed**. Determine that contract from whatever the project uses, and show its structure as a **raw JSON example**:
+
+- a shared request helper (`src/scripts/utils/request.js` or a similarly named module) — reference it and list its response formats;
+- mocks (`src/scripts/mocks/**`) — use them as the request/response contract, but note that they are **dev-only** (never loaded in production, see `src/scripts/main.js`) and do **not** require a JS rebuild;
+- an explicit `fetch`/`axios` call.
+
+- Do not describe internal JS logic, refactors, stores, components or composables — the backend only needs to know whether JS changed (see «Пересобрать JS» in the build list).
+- **Do not report URLs, HTTP methods or header values** — the backend sets them. At most, mention that the update is an AJAX request and that extra headers can be passed if such an option exists.
+
+### Assets — `src/images/**`, `src/fonts/**`, `src/videos/**`
+
+- new icons in `src/images/required/icons/**` (SVG sprite);
+- new design images in `src/images/required/**`, content images in `src/images/examples/**`, fonts and videos — list the new files;
+- lazy-loading requirements (`loading="lazy"`, `.lazyload` + `data-background`).
+
+## 3. Build List
+
+Derive the build list from which source folders changed. Emit only relevant items, as a plain list (no todo checkboxes):
+
+- `src/styles/**` `*.scss` changed → **Пересобрать CSS**
+- `src/scripts/**` `*.js`/`*.vue` changed **excluding `src/scripts/mocks/**`** → **Пересобрать JS**
+- `src/images/required/icons/**` changed → **Пересобрать иконки**
+
+The backend rebuilds assets with `yarn build` and copies the result to their side.
+
+## 4. Output Template
+
+Plain-text layout, no Markdown. No title line; the guide starts with the first section.
+
+```
+Сборка
+- Пересобрать CSS
+- Пересобрать JS
+- Пересобрать иконки
+
+Изменения по HTML
+catalog.html
+- <что изменилось: блоки, классы, структура>
+
+Данные при загрузке страницы
+<JSON-пример структуры>
+
+AJAX-запросы
+<JSON-пример контракта ответа, если он изменился>
+
+Ассеты
+- <новые иконки / изображения / шрифты / видео>
+```
+
+- Emit a section only if it has content; sections without changes are omitted entirely (including «Ассеты», when there are no new files).
+- If no integration is needed at all (only internal refactor works with no markup/data change), output a single line: `Интеграция не требуется — <короткая причина>`.
+
+## 5. Workflow
+
+1. Parse the input (hash / range / branch; if nothing is given — the latest commit, `BASE=HEAD^`, `TARGET=HEAD`) and resolve `BASE` and `TARGET`.
+2. Read the commit subject for the task number and title.
+3. If project conventions are unclear (request helper path, the sitemap page, subfolders in `html/`), consult `AGENTS.md` / `README.md` — every project has them.
+4. Run the whitespace-insensitive diff for `html/**` and the diff for `src/**`.
+5. Categorize the changes into: HTML, initial page state, AJAX requests contract, assets, build steps.
+6. Print the Russian plain-text guide in chat using the template above.