diff --git a/README.md b/README.md index 1c1080b..c4487ee 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,6 @@ - **[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-коммиту. - **[optimize-fonts](./optimize-fonts/SKILL.md)** — оптимизация подключения шрифтов: сабсетинг, variable-шрифты, `unicode-range` и metric-override fallback для устранения сдвига (CLS). - **[plan-orchestrator](./plan-orchestrator/SKILL.md)** — исполнение согласованного плана по пунктам силами субагентов: фаза плана, вопросы, работа, независимая проверка и коммит на каждый пункт. diff --git a/backend-integration-guide/SKILL.md b/backend-integration-guide/SKILL.md deleted file mode 100644 index 3fbcab0..0000000 --- a/backend-integration-guide/SKILL.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -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 ``**: `BASE=^`, `TARGET=`. -- **Range `..`**: `BASE=`, `TARGET=`. -- **Branch ``** (including `origin/`): `BASE=$(git merge-base HEAD )`, `TARGET=`. - -Get the task number and title from the commit subject (format `#<номер задачи> <описание>`): - -``` -git log -1 --format=%s -``` - -## 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 -- <что изменилось: блоки, классы, структура> - -Данные при загрузке страницы - - -AJAX-запросы - - -Ассеты -- <новые иконки / изображения / шрифты / видео> -``` - -- 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.