platform-landing

name

platform-landing

description

Детерминированная процедура для concept-репозитория платформы (он же coordination/solution-root для полирепозиторной платформы). Две части. PART I — сборка и 5-pass рефактор лендинга-витрины concept README + парного docs/get-started.md под потребителя concept-уровня (за 60 секунд решить «годится ли платформа», затем первый шаг). PART II — полный жизненный цикл кросс-сервисной фичи (на >1 сервис): spec → plan → декомпозиция на per-service задачи со ссылками на backlog каждого сервиса → синхронизация статусов → закрытие; по практике spec-driven development и polyrepo-координации (PR в порядке зависимости, «Depends on #X», единые имена веток). Рассчитан на слабую модель (уровня Qwen 37B): проходы, жёсткие лимиты, таблицы-роутеры, STOP-правила, чеклисты. Применять В CONCEPT-репозитории. Не применять для документации одного сервиса — это скилл documentation; для ревью качества — doc-quality-review.

platform-landing — concept-репозиторий платформы

Concept-репо играет две роли сразу:

• витрина платформы для внешнего потребителя (PART I);
• coordination-root для кросс-сервисных фич полирепозиторной платформы (PART II).

Скилл — процедура, а не справочник. Делай по шагам, не импровизируй. Соблюдай числовые лимиты буквально. Сработало STOP-правило → остановись, спроси оператора.

Документация одного сервиса (README сервиса, его docs/architecture.md) — скилл documentation. Ревью качества готовой доки — скилл doc-quality-review.

Выбор части:

Задача	Часть
Собрать/рефакторить лендинг concept (README + get-started)	PART I
Фича затрагивает >1 сервис платформы	PART II
Фича внутри одного сервиса	НЕ сюда → documentation + per-repo флоу

---

PART I — лендинг-витрина concept

Потребитель: инженер-потребитель concept-уровня и менеджер. Job: за 60 секунд решить «годится ли мне эта платформа», затем сделать первый шаг.

Документы: README.md концепт-репо (витрина) + парный docs/get-started.md (пошаговое подключение).

I.0 Жёсткие лимиты (буквально)

• README concept — одна прокрутка: ≤ 60 строк тела (без больших ASCII-блоков).
• Hero-предложение «что это» — ≤ 25 слов, одно предложение.
• Любой пункт списка — ≤ 12 слов.
• Команды запуска конкретного сервиса в concept README — 0 (они в репо сервиса).

I.1 Анти-контент: чего НЕ должно быть в concept README

Пройди по таблице. Нашёл такой контент → вынеси по колонке «куда», не оставляй.

Если в concept README есть…	…куда вынести
API-эндпоинты, pipe-описания	README сервиса
Архитектура конкретного сервиса	docs/architecture.md сервиса
Модель данных, структура проекта, команды запуска	README сервиса
Детали реализации любого уровня	репо сервиса
Длинный quickstart, troubleshooting	docs/get-started.md концепта
Манифест / архитектура платформы / roadmap (развёрнуто)	docs/manifesto.md / docs/architecture.md / docs/roadmap.md концепта

Правило: concept описывает СИСТЕМУ, не сервис. Concept ссылается, не копирует.

I.2 Пять проходов рефактора README (по порядку)

Pass L1 — Hero. Первая строка после заголовка: что за платформа, ≤ 25 слов, одно предложение. Затем — для кого (1 строка). (Проверка: одно предложение, ≤ 25 слов.)

Pass L2 — Из чего состоит. Картина целого: список нод/сервисов/форматов платформы, каждый — одна строка ≤ 12 слов. Это «из каких кусков система», без деталей куска. (Проверка: список, не проза; нет деталей одного сервиса.)

Pass L3 — Анти-контент чистка. Прогони раздел I.1 по всему README. Каждый найденный класс — вынеси. (Проверка: ни одна строка таблицы I.1 не применима.)

Pass L4 — Стек и схема платформы. Таблица компонент платформы → технология + одна ASCII-диаграмма верхнего уровня (ноды/связи), не внутренности сервиса. (Проверка: диаграмма про платформу, не про один сервис.)

Pass L5 — Первый шаг. Ссылки: на docs/get-started.md (пошаговое подключение) и на конкретные сервисы-примеры (напр. passkey-demo). Текст ссылки описателен. (Проверка: есть ссылка на get-started и хотя бы один сервис.)

I.3 Парная страница docs/get-started.md

Отдельный файл — пошаговое подключение к платформе (то, что не влезает в витрину): предпосылки → шаги подключения (нумерованные, одно действие на шаг) → проверка → troubleshooting. Лимит проходов A6 из documentation (команды копируются и работают).

I.4 STOP (PART I)

• Просят положить в concept README API/архитектуру/данные конкретного сервиса → STOP, вынеси по I.1.
• README уже написан человеком и правка масштабная → STOP, подтверди before.

---

PART II — кросс-сервисная фича

Применяй, когда фича затрагивает больше одного сервиса платформы. Concept-репо — coordination-root: проектирование и общий план стартуют здесь, потом «впадают» в локальные backlog.md сервисов.

Метод — spec-driven development (spec → plan → tasks) поверх polyrepo-координации.

II.0 Где живёт артефакт

<concept-repo>/docs/features/<slug>/
  spec.md   — что и зачем (SDD spec)
  plan.md   — кросс-сервисная декомпозиция + ссылки на backlog сервисов + статусы

<slug> — kebab-case имя фичи. Один каталог = одна фича.

Шаблоны (заполнять по фазам ниже):

• spec.md — docs/templates/feature-spec.md
• plan.md — docs/templates/feature-plan.md

II.1 Фаза 1 — Specify (spec.md)

Создай docs/features/<slug>/spec.md. Заполни ровно эти блоки (SDD — 6 элементов):

Блок	Что писать
Проблема / outcome	какую задачу решаем, что считается успехом
Затронутые сервисы	список репозиториев платформы, которые меняются
Границы (scope)	что входит и что НЕ входит
Constraints	контракты/совместимость/нефункциональные ограничения
Прежние решения	ссылки на ADR/concept (на чём стоим, что не пересматриваем)
Критерии приёмки	как поймём, что фича готова (кросс-сервисный сценарий)

(Проверка: все 6 блоков заполнены; «затронутые сервисы» ≥ 2 — иначе это не PART II.)

II.2 Фаза 2 — Дизайн (high-level, в spec.md)

Как фича ложится на платформу: какие контракты между сервисами появляются/меняются (OpenAPI/AsyncAPI), кто кого вызывает, последовательность.

• Любой новый контракт между сервисами проектируется spec-first (skill http-io для исходящего HTTP; контракт в api-specification/ соответствующего сервиса).
• STOP, если контракт между сервисами не определён, а декомпозиция его требует.

II.3 Фаза 3 — Plan (plan.md, декомпозиция)

Создай docs/features/<slug>/plan.md. Главное — таблица per-service со ссылками:

| # | Сервис (репо)      | Что делает в рамках фичи      | Backlog-задача                         | Зависит от | Статус |
|---|--------------------|-------------------------------|----------------------------------------|------------|--------|
| 1 | auth-service       | новый эндпоинт X              | auth-service/backlog.md#<task>          | —          | todo   |
| 2 | gateway            | проксирование X               | gateway/backlog.md#<task>               | 1          | todo   |
| 3 | client-sdk         | метод-обёртка                 | client-sdk/backlog.md#<task>            | 2          | todo   |

Правила (проверь):

• Порядок строк = порядок зависимости (backend → shared → frontend).
• Каждая строка ссылается на конкретную задачу в backlog.md своего сервиса.
• Колонка «Зависит от» — номера строк-предшественников (для порядка PR).

II.4 Фаза 4 — Связывание (per-service)

Для каждой строки plan.md:

1. В репо сервиса заведи задачу в его backlog.md со ссылкой обратно на фичу (<concept-repo>/docs/features/<slug>/).
2. Дальше сервис идёт своим флоу: program-design → program-implementation.
3. Единое имя ветки во всех репо: feat/<slug>.
4. PR-ы открываются в порядке зависимости; в теле PR — Depends on <repo>#<PR>.

(Проверка: у каждой задачи в сервисе есть обратная ссылка на фичу.)

II.5 Фаза 5 — Синхронизация статусов

plan.md — единственный источник правды о прогрессе фичи.

• При каждом merge в сервисе → обнови колонку «Статус» соответствующей строки (todo / in_progress / done).
• Не дублируй прогресс в других местах — только plan.md.

(Проверка: статус в plan.md совпадает с реальным состоянием задач сервисов.)

II.6 Фаза 6 — Закрытие

Фича закрывается, когда:

• все строки plan.md в статусе done, И
• кросс-сервисный сценарий из «Критериев приёмки» (II.1) проходит (кросс-репо компонентные/контракт-тесты зелёные).

Тогда: пометь фичу done в plan.md (шапка), оставь каталог как запись истории.

II.7 STOP (PART II)

• «Затронутые сервисы» < 2 → это не кросс-сервисная фича, верни в documentation + per-repo флоу.
• Контракт между сервисами требуется декомпозицией, но не спроектирован → STOP, спроси.
• Просят слить PR сервиса вне порядка зависимости → STOP, предупреди о поломке порядка.
• Мерж PR делает только оператор (агент не мержит).

---

Финальный чеклист

PART I (лендинг):

• README concept ≤ 60 строк, hero ≤ 25 слов.
• Ни одна строка анти-таблицы I.1 не применима.
• Есть ссылки на docs/get-started.md и хотя бы один сервис.

PART II (фича):

• spec.md: все 6 блоков; затронутых сервисов ≥ 2.
• Новые контракты между сервисами — spec-first, в api-specification/.
• plan.md: строки в порядке зависимости, каждая ссылается на backlog сервиса.
• У каждой per-service задачи есть обратная ссылка на фичу.
• Статусы в plan.md синхронны с реальностью; других источников прогресса нет.
• Закрытие — только при всех done + зелёных кросс-сервисных критериях приёмки.