sync-site-gdd

name

sync-site-gdd

description

Обновление manifest сайта docs.u2game.space — добавление новых ГД-релевантных документов в docs/gdd/site/content/manifest.json, локальная сборка сайта, PR. Используй когда в main появились новые ADR, доктрины бренда, GDD/PvE/Marketing/Audit/Gameplay-спеки, и нужно, чтобы они появились на публичном сайте. Триггеры: «обнови сайт», «sync site», «синхронизируй docs.u2game.space», «добавь ADR-NNNN на сайт», «новые доктрины не показаны на сайте». Не трогает VPS напрямую — после merge PR GitHub Actions сам передеплоит сайт за < 5 минут. Не правит навигацию проекта — для этого есть /sync-docs.

Sync Site GDD — обновление manifest публичного сайта

/sync-site-gdd добавляет новые ГД-релевантные документы в docs/gdd/site/content/manifest.json, проверяет сборку сайта локально и открывает PR. После merge оператором GitHub Actions автоматически передеплоит docs.u2game.space (SLA < 5 минут по docs/gdd/gdd_site_maintenance_v0.1.md §12).

Что скилл делает и что не делает

Делает:

• Находит ГД-релевантные документы в docs/**, которых нет в manifest.json.
• Решает по таблице соответствия, в какой раздел сайта они идут.
• Добавляет записи в manifest.json в правильный раздел с корректным order.
• Прогоняет локальную сборку npm run build в docs/gdd/site/ — должна пройти без ошибок.
• Открывает PR. После merge GitHub Actions автоматически передеплоит сайт.

Не делает:

• Не заходит на VPS. Деплой полностью автоматический через GitHub Actions.
• Не правит исходные документы (frontmatter, текст). Только запись в manifest.
• Не правит docs/INDEX.md или ADR-INDEX.md — для этого есть /sync-docs. Запускай этот скилл после /sync-docs, не вместо.
• Не трогает технические документы (docs/specs/tech/*, research, infrastructure) — они не идут на публичный сайт.
• Не делает редизайн, не правит кураторские страницы content/pages/NN_*.md — это отдельная работа game-designer-агента.

Когда не запускать

• Все ГД-релевантные документы из main уже есть в manifest.json.
• Триггер — изменение текста или статуса уже учтённого документа. Сайт перечитает frontmatter автоматически при следующем деплое — manifest не трогается.
• Документ-кандидат не ГД-релевантный (тех-спека, research, infrastructure).

Промпт активации

/sync-site-gdd

Триггер: <merge PR #N с новыми ADR/доктринами | оператор просит проверить пропуски>
Кандидаты на добавление: <список slug-ов или "auto — find by missing">

Таблица «куда какой документ идёт»

Источник правила — docs/gdd/gdd_site_maintenance_v0.1.md §3.1 шаг 3.

Slug раздела ниже — это реальный section.slug из manifest.json (docs/gdd/site/content/manifest.json). Скрипт find-missing.py возвращает такой же slug в hint-колонке — чтобы таблица не расходилась с кодом, поддерживай эти значения синхронно при изменениях manifest.

Категория источника	На сайт?	Slug раздела (manifest section.slug)	Раздел в UI
docs/architecture/ADR-*.md (active/draft)	Да	architecture	«Архитектурные решения (ADR)»
docs/brand/*.md	Да	brand	«Бренд и идентичность»
docs/gdd/*.md (active/primary)	Да	?ambiguous — решает скилл по frontmatter	каталог содержит документы из разных разделов (vision, economy, gameplay-systems); скрипт возвращает hint ?ambiguous
docs/pve/*.md	Да	pve	«PvE-контент»
docs/marketing/*.md (текущая версия)	Да	vision	«Видение и питч»
docs/specs/audit/*.md	Да	audit	«Аудит и риски»
docs/specs/gameplay/*.md	Да	gameplay-systems	«Геймплей: системы и взаимодействия»
docs/specs/fa/*.md	Да	gameplay-systems	«Геймплей: системы и взаимодействия»
docs/specs/economy/*.md или экономика по тегам	Да	economy	«Экономика и монетизация»
docs/specs/ui/*.md	Да	ui-ux	«UI / UX»
docs/specs/tech/*.md	Нет	—	(технические)
docs/research/*.md	Нет	—	(внутренние исследования)
docs/plans/*.md, docs/incidents/*.md	Нет	—	(служебные)
.agents/*, .claude/*, .memory-bank/*	Нет	—	(инфраструктура агентов)

В сомнительных случаях:

• Документ описывает геймплей, баланс, нарратив, бренд, монетизацию, экономику, UX → Да.
• Документ описывает CI/CD, тестовую инфраструктуру, релизы, аудит безопасности кода → Нет.
• Документ имеет status: archived или status: superseded → добавить с флагом "archived": true, перейдёт в раздел «Архив».

Workflow

Шаг 1 — Найти пропуски

Используй scripts/find-missing.py рядом с этим скиллом — он надёжно сравнивает manifest.json со списком ГД-релевантных документов в docs/. Эвристика разделов и набор исключений (ADR-INDEX, ARCHIVE и т.п.) совпадают с таблицей в этом SKILL.md.

cd D:/GitHub/u2-sync-site-<YYYY-MM-DD>   # запускать из worktree от свежего main, см. Шаг 3
python .claude/skills/sync-site-gdd/scripts/find-missing.py

Скрипт выводит на stdout <section_hint>\t<source-path> для каждого пропуска. Пустой вывод = всё актуально, выход. На stderr — короткий summary с количеством пропусков.

Запускай из worktree от свежего origin/main, а не из основного репо. Основной репозиторий оператора может быть на другой ветке с неполным набором документов — тогда скрипт даст частичный список и ты пропустишь часть документов на сайт. Этот шаг идёт после Шага 3 (создание worktree); порядок в SKILL.md перевернут только потому, что классификация пропусков нужна для понимания scope-а PR ещё до правок.

find-missing.py — единственный канонический способ поиска пропусков в этом скилле. Не подменяй его одноразовым bash-однострочником: уровни вложенности git ls-tree и manifest.source различаются на docs/-префикс, ошибка нормализации даст ложные пропуски на каждом запуске и риск массовых неправильных добавлений в manifest.json (см. Codex P1 review к commit 4c71c14). Если скрипт сломан или каталог изменился — фикси скрипт отдельным PR, а не обходи в bash.

Шаг 2 — Классифицировать пропуски

Для каждого кандидата:

1. Прочитай первые 15 строк (frontmatter): title, status, version, tags.
2. Определи раздел по таблице выше — особое внимание ?ambiguous hint от скрипта.
3. Если status: superseded или status: archived — флаг "archived": true.
4. Если hint скрипта — ?ambiguous или ?, ИЛИ ты не уверен в разделе по другой причине — спроси оператора через AskUserQuestion с 2-4 конкретными вариантами разделов. Не угадывай: ошибочный раздел = публикация документа не в той категории на публичном сайте.

Шаг 3 — Создать worktree

git worktree add D:\GitHub\u2-sync-site-<YYYY-MM-DD> -B docs/sync-site-manifest-<YYYY-MM-DD> origin/main
cd D:\GitHub\u2-sync-site-<YYYY-MM-DD>

Применяются те же запреты, что в /sync-docs: только нативный Windows git, только внутри D:\GitHub\, не трогать основной worktree оператора.

Шаг 4 — Обновить manifest.json

Шаблон записи в items[]:

{
  "slug": "<kebab-slug-без-расширения>",
  "title": "<заголовок из frontmatter или человекочитаемый>",
  "source": "<path-relative-to-docs/>",
  "order": <next-int-в-разделе>
}

Для архивных:

{
  "slug": "<slug>",
  "title": "<title>",
  "source": "<path>",
  "order": <N>,
  "archived": true
}

Правила:

• slug — латиница, kebab-case, без префикса и расширения. Пример: adr-0023-base-personal-storage.
• title — из frontmatter title: (а не из имени файла). Если в frontmatter длинно — допустимо сократить, оставив суть.
• source — путь от корня docs/. Пример: architecture/ADR-0023-base-personal-storage.md.
• order — следующий целый после максимального в разделе. Не переупорядочивай существующие.

Внимание на длинные кириллические правки. Если в manifest добавляется больше 5 записей или общий объём правки > 5 KB — используй python+UTF-8, не Edit. См. /sync-docs Шаг 5.

Шаг 5 — Локальная сборка сайта

cd docs/gdd/site
npm ci          # если node_modules устарел или отсутствует — иначе пропусти
npm run build
cd -

Сборка должна:

• Завершиться без ошибок.
• Не упасть на резолве source: для добавленных записей (валидация в build-content.ts).
• Не выдавать warnings про broken-links на добавленных документах.

Если сборка падает на отсутствующем источнике — значит ты ссылаешься на файл, которого нет в main. Проверь путь.

Шаг 6 — Проверка перед коммитом

git diff --stat
git diff docs/gdd/site/content/manifest.json

Чеклист:

• В diff только docs/gdd/site/content/manifest.json. Никаких других файлов.
• В diff только добавления в items[] массивы (и опционально archived: true флаги). Никаких удалений, никакого переупорядочивания.
• JSON синтаксически валиден (если есть jq — jq . docs/gdd/site/content/manifest.json > /dev/null).
• npm run build прошёл (из Шага 5).

Шаг 7 — Коммит

git add docs/gdd/site/content/manifest.json
git commit -F commit-msg.txt

Шаблон commit-msg.txt:

docs(site): добавление новых документов на docs.u2game.space

В manifest сайта добавлены N документов после <триггер>:

Раздел «Архитектура» (slug `architecture`):
- ADR-NNNN: <тема>
- ...

Раздел «Бренд» (slug `brand`):
- <slug>: <заголовок>
- ...

Локальная сборка пройдена.

После merge GitHub Actions автоматически передеплоит docs.u2game.space (SLA < 5 минут).

Шаг 8 — Push + PR

git push -u origin docs/sync-site-manifest-<YYYY-MM-DD>

gh pr create \
  --base main \
  --head docs/sync-site-manifest-<YYYY-MM-DD> \
  --title "docs(site): sync manifest docs.u2game.space — добавление N документов" \
  --body-file pr-body.txt

Шаблон pr-body.txt:

Обновление manifest публичного сайта docs.u2game.space после <триггер>.

Добавлены N документов в разделы:
- «Архитектура»: M записей (ADR-XXXX..ADR-YYYY)
- «Бренд»: K записей
- ...

Локальная сборка: пройдена.
После merge GitHub Actions автоматически передеплоит сайт за < 5 минут (SLA по gdd_site_maintenance §12).

Постпроверка после merge (опционально, оператор):
- HTTPS docs.u2game.space → 200.
- В разделе «Архитектура» появились новые ADR-карточки.
- Поиск находит новые документы по slug или заголовку.

Tier ревью: Light (только manifest.json, без логики кода).

— Site Sync (Claude Opus 4.7)

Шаг 9 — После merge оператором

cd D:\GitHub\u2
git worktree remove D:\GitHub\u2-sync-site-<YYYY-MM-DD>
git branch -D docs/sync-site-manifest-<YYYY-MM-DD>

GitHub Actions при merge автоматически:

• Соберёт сайт.
• Прогонит post-deploy smoke.
• При провале — авто-rollback на предыдущий релиз.

Скилл сам не дёргает workflow и не проверяет сайт после merge — это область оператора или devops-агента при инцидентах.

Если что-то пошло не так

Симптом	Действие
Локальная сборка падает на резолве source	Проверь путь — файл реально в docs/<source> от корня репо?
Сборка падает на JSON-синтаксисе	Прогон jq . manifest.json — найди опечатку (запятая, кавычка)
Не уверен в разделе для документа	AskUserQuestion оператору с 2-4 вариантами разделов
Документ имеет status: draft — добавлять?	Да, draft-документы попадают на сайт со штампом «черновик». Решение оператора — пропускать или нет
Источник — большой файл в docs/archive/	Уточни у оператора, нужен ли он на сайте. По умолчанию архив не добавляется
Кандидат — superseded документ	Добавляй с "archived": true, попадёт в раздел «Архив»

Запреты

• Не делать SSH на VPS. Деплой автоматический.
• Не править content/pages/NN_*.md (кураторские страницы) — это работа game-designer-агента, отдельный PR.
• Не править исходные документы в docs/ (frontmatter, текст). Только запись в manifest.
• Не переупорядочивать существующие записи в manifest без отдельной задачи.
• Не push в main напрямую.
• Не делать worktree через WSL/bound-mount.
• Не запускать без локальной npm run build — иначе можно ушибить публичный сайт после merge.

Канонические ссылки

• docs/gdd/gdd_site_maintenance_v0.1.md — полный регламент сайта.
• docs/gdd/gdd_site_maintenance_v0.1.md §3.1 — поток добавления документа.
• docs/gdd/gdd_site_maintenance_v0.1.md §9 — регламент обновления INDEX (взаимосвязь с /sync-docs).
• docs/gdd/gdd_site_deploy_plan_v0.1.md — деплой и инфраструктура.
• docs/gdd/site/CHECKLIST_BRAND.md — проверка визуала (для редизайн-PR, не для manifest-update).
• .agents/AGENT_ROLES.md §0 — подпись модели обязательна.
• Связанный скилл — /sync-docs (запускается до этого скилла).