design · git:20260907.ad5db37 · 2026-09-07 · sha256 b0fca4dfc9fd3018
design git:20260907.ad5db37A
Immutable. This exact content is served forever at /api/v1/blob/b0fca4dfc9fd3018.
---
name: design
description: Create a doc-as-code design package from a PRD or SPEC. Conditionally generates C4 diagrams (Context/Container/Component), sequence diagrams, ER diagram + Data Dictionary, OpenAPI 3.0, AsyncAPI 3.0, ADRs, domain glossary, state diagrams, and deployment view as Mermaid-rendered Markdown files. Use when PM mentions "design", "architecture diagrams", "doc-as-code artifacts", "C4", "ERD", "OpenAPI spec", "AsyncAPI", "event-driven", "Kafka", "message broker", "sequence diagram", "state machine", "domain glossary", "ADR", or before handing a SPEC to another team. Trigger liberally — undertriggering loses architectural value, overtriggering is recoverable (PM can delete).
argument-hint: "[PRD-XXX | SPEC-XXX] [--inputs=path1.md,path2.md] [--only=c4_context,openapi,...] [--skip=deployment,state,...]"
cli_requires: "task_tool"
---
# /polisade:design [PRD-XXX | SPEC-XXX] — Doc-as-code design package через субагент
Создание набора doc-as-code артефактов (C4, sequence, ERD, OpenAPI, AsyncAPI, ADR, glossary, state, deployment) на основе PRD или SPEC. Все артефакты — Markdown с Mermaid/YAML, нативно рендерятся в GitHub/GitLab/Notion.
> **⚠️ DESIGN-NNN силосы — deprecated для brownfield (Pipeline V2 Ф4, WP4.3 / #221).**
> Per-SPEC пакет `DESIGN-NNN-<slug>/` (изолированный силос) на существующем
> корпусе **устаревает**: intent-подмножество (ADR, NFR/QAS, glossary, context-map,
> C4 L1, deployment) ведётся в едином **живом корпусе** `docs/architecture/`
> (`/polisade:design-corpus` строит его best-effort с громкой пометкой
> `INFERRED/GAP`, а не молча выдаёт за проверенный), а derived
> (C4 L2/L3, ER, state, sequences) — регенерируется, руками не пишется. Разрез —
> `docs/pipeline-v2/intent-derived-split.md`. **Greenfield-путь полного DESIGN
> (новый модуль с нуля) остаётся живым** — deprecated значит «помечен и не
> развивается», не «удалён». Классификация силоса intent/derived (read-only
> отчёт) — `scripts/polisade_migrate_design.py --report`. Living-корпус —
> `/polisade:design-corpus` (experimental, за `settings.experimental.designCorpus`).
<!-- polisade:silo-legacy CAPSULE BEGIN -->
> **Силос → корпус.** Живой корпус `docs/architecture/` — **источник правды**
> по архитектуре. Пакет
> `docs/architecture/DESIGN-NNN-<slug>/` — **legacy-силос**: сначала ищи факт в
> корпусе (`model/`, `c4/`, `glossary/`, `quality/`, `flows/`, `contracts/`,
> `decisions/`), и только если там его нет — читай силос. **Прочитал силос —
> скажи вслух**, отдельной строкой в выводе:
> `⚠️ переходное чтение силоса: <путь> (источник правды — корпус docs/architecture/)`.
> Молчаливое чтение силоса — дефект, а не экономия: PM не видит, что решение
> принято по устаревшему укладу. Если в пакете есть `MIGRATED.md`, его карта
> домов обязательна к прочтению, и читается она так: **из силоса перестают
> читать ТОЛЬКО файлы таблицы «Перенесено 1:1»** — они уже лежат в корпусе
> целиком. Файлы таблицы «Ещё НЕ в корпусе» **не переносились**: там назван
> целевой дом, которого ещё нет, и **единственная копия факта — в силосе**.
> Такой файл читают отсюда (громко), пока модель не свернула его в корпус;
> считать его устаревшим — потерять факт. Перевод силоса на корпус —
> `${POLISADE_PYTHON:-python3} scripts/polisade_migrate_silo.py <пакет>` (dry-run по умолчанию,
> запись — явным `--apply`, конфликты — выбор человека, не скрипта).
<!-- polisade:silo-legacy CAPSULE END -->
<!-- polisade:exec-denied CAPSULE BEGIN -->
> ⛔ **Вызов скрипта отклонён или не запустился** (`Command references protected path` / `Install directory is read-protected` / `Filesystem Guard` / `the tool's default permission is 'deny'`, отказ песочницы, ненулевой exit без вывода) — **STOP**.
> Процитируй отказ дословно. НЕ пересказывай по исходнику, что скрипт «сделал бы»; НЕ собирай dry-run вручную; НЕ переходи к apply/push/pr-create.
> НЕ транскрибируй скрипт (прочитать → записать копию в `/tmp` или в проект → запустить копию): копия не байт-идентична — уезжают классы символов в regex, форма возврата функций, пропадают целые функции — и молча меняется набор применённых изменений.
> Отказ инструмента — это отказ, а не результат. Доложи PM дословный текст отказа и сошлись на #127 (доставка скриптов в проект).
<!-- polisade:exec-denied CAPSULE END -->
<!-- polisade:corpus-writer CAPSULE BEGIN -->
> ⛔ **Живой корпус `docs/architecture/` пишет ОДИН исполнитель** —
> `${POLISADE_PYTHON:-python3} {plugin_root}/scripts/polisade_corpus_io.py` (stdlib-only). Ни
> `Write`, ни `Edit`, ни `cp`, ни `mv`, ни `>` в корпус не идут: примитив даёт
> пофайловую атомарность, блокировку от второго писателя, журнал оборванной
> промоции, проверяемый манифестом backup и отказ на симлинках и побегах пути.
> Ручное копирование обходит всё перечисленное — это регресс, а не «то же самое».
>
> **Хэш-контракт.** Всё, что ты проверил ДО вызова, к моменту записи могло
> устареть, поэтому объявляй примитиву, каким ты ВИДЕЛ цель, — он сверит это
> сам, вплотную к записи: `--expect-absent` для нового файла (публикация идёт
> атомарным `linkat`, занятое имя отвергает ядро) и `--expect-sha256 <hex>`
> для правки существующего (ключ — из ПРОЧИТАННЫХ байтов, не из размера и не
> из даты); для `promote` — карта `--expect-from <json>` вида
> `{путь: sha256|absent}`. Отказ `E-expect-*` значит, что файл правил кто-то
> ещё: **не повторяй с `--force`, покажи расхождение PM.**
>
> Исключение ровно одно, и оно названо, а не умолчано: legacy-силос
> `docs/architecture/DESIGN-NNN-<slug>/` пишет `/polisade:design` своим
> Write-инструментом. Силос deprecated и переносится в корпус скриптом
> `scripts/polisade_migrate_silo.py`, а не развивается.
<!-- polisade:corpus-writer CAPSULE END -->
## Использование
```
/polisade:design PRD-001 # дизайн на основе PRD
/polisade:design SPEC-001 # дизайн на основе SPEC (обогащает существующую спеку)
/polisade:design # выбрать из доступных ready PRD/SPEC
/polisade:design PRD-001 --inputs=docs/research/market.md # с дополнительным контекстом
/polisade:design PRD-001 --only=c4_context,openapi # только указанные артефакты
/polisade:design PRD-001 --skip=deployment,state # все, кроме указанных
```
## Когда нужен дизайн-пакет
**Создавай дизайн:**
- Новый модуль или сервис
- Архитектурное переписывание
- Перед передачей SPEC другой команде
- Любой PRD/SPEC, где есть: ≥ 2 сущности, ≥ 1 endpoint, multi-step flow, состояния, integration с внешним сервисом
- Когда PM хочет «чтобы остался след» — артефакты как ubiquitous language для команды
**Не нужен дизайн (иди сразу в `/polisade:tasks` или `/polisade:roadmap`):**
- Тривиальные UI-правки
- Багфиксы
- Конфиг-изменения
## Производимые артефакты (12 типов, conditional)
| # | Артефакт | Файл в package | Когда генерируется |
|---|---|---|---|
| 1 | C4 Context (Level 1) | `c4-context.md` | **MANDATORY** если `external_systems` non-empty; иначе — есть внешние акторы или integration |
| 2 | C4 Container (Level 2) | `c4-container.md` | ≥ 2 deployable units (frontend/backend/worker/DB/cache/queue) |
| 3 | C4 Component (Level 3) | `c4-component.md` | Сложный single container с явно выделяемыми компонентами |
| 4 | Sequence diagrams | `sequences.md` | Multi-step flows, OAuth, retries, compensation |
| 5 | ER diagram + Data Dictionary | `data-model.md` | ≥ 2 entities или явная схема БД |
| 6 | OpenAPI 3.0 | `api.md` | ≥ 1 REST endpoint |
| 7 | AsyncAPI 3.0 | `async-api.md` | Message broker, event-driven, WebSocket, pub/sub |
| 8 | ADR | `docs/architecture/decisions/ADR-XXX-*.md` | Каждое серьёзное архитектурное решение с alternatives |
| 9 | Domain Glossary | `glossary.md` | ≥ 5 уникальных доменных терминов |
| 10 | State diagrams | `state-machines.md` | Сущность с ≥ 3 состояниями (lifecycle) |
| 11 | Deployment view | `deployment.md` | Явные NFRs (HA, multi-region, k8s) |
| 12 | Quality Scenarios | `quality-scenarios.md` | Любое NFR в source SPEC секции 6 (arc42 §10) |
Подробные триггеры — в `references/conditional-triggers.md`. Подробные шаблоны и Mermaid-примеры — в `references/<тип>-guide.md` (читать только нужные).
## Архитектура с субагентом
```
┌─────────────────────────────────────────────────────────────┐
│ PM: /polisade:design PRD-001 [--inputs=...] [--only/skip=...] │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ ОСНОВНОЙ АГЕНТ │
│ Phase 1: Parse args, validate, resolve input artifact │
│ Phase 2: Conditional analysis → needed_artifacts set │
│ Phase 3: Allocate IDs (DESIGN + ADRs), build file plan │
│ Phase 4: Pack subagent context (only relevant references/) │
│ Phase 5: Launch ONE subagent with full design prompt │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ СУБАГЕНТ general-purpose (clean context) │
│ │
│ System role: Solution Design Architect │
│ Input: source artifact + parent + inputs + knowledge + │
│ relevant references/ │
│ │
│ Делает: │
│ 1. Generates glossary FIRST (seeds ubiquitous language) │
│ 2. Generates remaining artifacts следуя glossary terms │
│ 3. Creates ADRs только для серьёзных decisions │
│ 4. Возвращает: список файлов, skipped + причины, вопросы │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ ОСНОВНОЙ АГЕНТ │
│ Phase 6: Holistic Quality Review Loop (max 2 iterations) │
│ Phase 7: State updates (PROJECT_STATE, counters, ADRs) │
│ Phase 8: Report to PM │
└─────────────────────────────────────────────────────────────┘
```
## Алгоритм
### Phase 1 — Parse args & validate
1. Распарсь `$ARGUMENTS`:
- первый позиционный аргумент: `PRD-XXX` или `SPEC-XXX` (опционально)
- `--inputs=path1,path2,...` — дополнительные context-файлы
- `--reference=path` — reference-спека (файл или папка), которую передал PM
как ВНЕШНИЙ эталон контракта: JSON Schema / OpenAPI / AsyncAPI. Включает
Phase 5.9 (issue #164). Не передана — Phase 5.9 не выполняется, и в
отчёте это пишется как «эталон не передан», а не как «расхождений нет».
- `--only=type1,type2` — whitelist (override conditional logic)
- `--skip=type1,type2` — blacklist
2. Прочитай `.state/PROJECT_STATE.json`
3. Resolve input artifact:
- Если ID указан: найди в `artifacts`, проверь что это `PRD` или `SPEC` и `status == ready`
- Если не указан: покажи список ready PRD + SPEC, спроси какой использовать
- FEAT в v1 не поддерживается — если PM передал FEAT-XXX, скажи: "Для FEAT сначала создай SPEC через /polisade:spec, затем /polisade:design SPEC-XXX"
4. Если `--inputs` указаны: проверь что каждый файл существует и читаем
5. Прочитай `.state/knowledge.json`
```
Нет готовых PRD или SPEC для создания дизайн-пакета.
Доступные действия:
→ /polisade:prd для крупной инициативы
→ /polisade:spec PRD-XXX для технической спецификации
→ /polisade:state для обзора проекта
```
### Phase 1.5 — Валидация технического контекста (обязательный checkpoint)
**Цель:** убедиться, что `.state/knowledge.json` содержит актуальный технический контекст.
Дизайн-пакет генерирует конкретные артефакты (C4, ERD, OpenAPI, ADR) — если субагент не знает
реальный стек, он выдумает технологии, и package будет бесполезен.
1. Проверь следующие поля в `.state/knowledge.json`:
| Поле | Критичность | Что проверить |
|------|-------------|---------------|
| `projectContext.techStack` | **ОБЯЗАТЕЛЬНО** | Не пустой массив |
| `projectContext.description` | **ОБЯЗАТЕЛЬНО** | Не пустая строка |
| `projectContext.keyFiles` | желательно | Не пустой массив |
| `projectContext.entryPoints` | желательно | Не пустой массив |
| `patterns` | желательно | Не пустой массив |
| `testing.testCommand` | желательно | Не null |
2. **Если ВСЕ обязательные поля заполнены** → покажи краткую сводку и запроси подтверждение:
```
═══════════════════════════════════════════
ТЕХНИЧЕСКИЙ КОНТЕКСТ (из knowledge.json)
═══════════════════════════════════════════
Tech Stack: TypeScript, React, Node.js, PostgreSQL, Redis
Description: Платформа для управления проектами
Patterns: REST API, Repository pattern, DI
Key Files: src/index.ts, src/server.ts
Контекст актуален? [y / update]
═══════════════════════════════════════════
```
- `y` → продолжить к Phase 2
- `update` → перейти к интервью (пункт 3 ниже)
3. **Если ЛЮБОЕ обязательное поле пусто** → провести обязательное интервью:
a. **Автодетект** — просканируй корень проекта на наличие маркеров стека:
- `package.json` → Node.js/TypeScript (проверь `dependencies`/`devDependencies`)
- `tsconfig.json` → TypeScript (даже без package.json, напр. Deno)
- `go.mod` → Go
- `pyproject.toml` / `requirements.txt` / `setup.py` → Python
- `Cargo.toml` → Rust
- `pom.xml` / `build.gradle` / `build.gradle.kts` → Java/Kotlin
- `build.sbt` / `.scalafmt.conf` → Scala/sbt
- `gradlew` / `mvnw` → JVM wrapper scripts (Gradle/Maven)
- `application.yml` / `application.properties` → Spring Boot
- `*.csproj` / `*.sln` → C# / .NET
- `docker-compose.yml` → infrastructure hints (DB, cache, queue, Kafka)
- `.env.example` → environment variables
- `Makefile` / `Justfile` → build/test commands
- `jest.config.*` / `vitest.config.*` / `pytest.ini` / `.rspec` → test framework
- `playwright.config.*` → Playwright (E2E)
- `cucumber.yml` / `features/*.feature` → Cucumber (BDD)
b. **Предложи и спроси** — покажи обнаруженное и задай обязательные вопросы:
```
═══════════════════════════════════════════
ТЕХНИЧЕСКИЙ КОНТЕКСТ НЕ ЗАПОЛНЕН
═══════════════════════════════════════════
Обнаружено в проекте: ← примеры для разных стеков:
──── Пример A (JVM) ────
• build.gradle.kts → Kotlin, Spring Boot 3.2
• application.yml → Spring Boot config
• docker-compose.yml → PostgreSQL 16, Kafka 3.6
• src/test/ → JUnit 5, Cucumber
──── Пример B (Node.js) ────
• package.json → TypeScript 5, Express 4
• playwright.config.ts → Playwright (E2E)
• docker-compose.yml → PostgreSQL 16, Redis 7
──── Пример C (Scala) ────
• build.sbt → Scala 3, Akka HTTP
• .scalafmt.conf → Scala formatter
• docker-compose.yml → PostgreSQL 16, Kafka 3.6
Обязательные вопросы (без ответов дизайн-пакет НЕ будет создан):
1. Язык(и) программирования и основные фреймворки?
Пример A: Kotlin, Spring Boot 3.2
Пример B: TypeScript 5, Express 4
Пример C: Scala 3, Akka HTTP
2. База данных и хранилища?
Пример A: PostgreSQL 16, Kafka 3.6
Пример B: PostgreSQL 16, Redis 7
Пример C: PostgreSQL 16, Kafka 3.6
3. Архитектурный стиль?
(монолит / микросервисы / serverless / модульный монолит / другое)
4. Ключевые ограничения или стандарты?
(GDPR, конкретный cloud provider, legacy интеграции...)
5. Протокол коммуникации между компонентами?
(REST / gRPC / GraphQL / message broker / комбинация)
Это критично для выбора OpenAPI vs AsyncAPI артефактов.
Необязательные (но полезные для качества дизайна):
6. Deployment target?
(Docker / Kubernetes / serverless / bare metal / PaaS)
7. Ключевые файлы (entry points, конфигурация)?
Предложение: src/app/layout.tsx, src/server.ts
═══════════════════════════════════════════
```
c. **Дождись ответа пользователя.** Агент МОЖЕТ предложить варианты на основе
автодетекта, но КАЖДЫЙ ответ на обязательные вопросы (1-5) должен быть
**явно подтверждён** пользователем (архитектором). Не продолжай без ответов
на вопросы 1-5. Пользователь может ответить кратко ("да, всё верно" — значит
предложения приняты) или скорректировать.
d. **Запиши подтверждённые данные** в `.state/knowledge.json`:
- `projectContext.techStack` — массив строк (языки, фреймворки, БД, инфра)
- `projectContext.description` — строка с описанием проекта
- `projectContext.keyFiles` — массив путей (если пользователь указал)
- `projectContext.entryPoints` — массив путей (если пользователь указал)
- `patterns` — если пользователь указал архитектурные паттерны, добавь как
массив строк (например, `["REST API", "Repository pattern", "DI"]`)
- `testing.testCommand` — команда тестирования (если указана)
e. Запиши обновлённый `knowledge.json` (2-space indent, stable key order).
⛔ **БЛОКЕР:** Без заполненных `techStack` и `description` переходить к Phase 2
**ЗАПРЕЩЕНО**. Дизайн-пакет без технического контекста будет содержать выдуманные
технологии в C4, ERD и OpenAPI — это хуже, чем отсутствие дизайна.
### Phase 2 — Conditional analysis (main agent, no subagent)
1. Прочитай input artifact (PRD или SPEC) полностью
2. Если parent chain существует (SPEC → PRD), прочитай parent тоже
3. Прочитай каждый файл из `--inputs`
4. **Checkpoint: границы системы.** Если source artifact (PRD или SPEC) или parent PRD упоминает внешние системы / интеграции → убедись, что информация о смежных системах передаётся в субагент для генерации C4 Context diagram. Если упоминания есть, но раздел «Внешние системы» (6A) отсутствует → зафиксируй Open Question.
5. **Trigger detection**: пройди по таблице из `references/conditional-triggers.md`. Для каждого из 12 типов артефактов — проверь свои триггеры (case-insensitive regex/keyword search). Сформируй `needed_artifacts` set.
- **IMPORTANT**: если source SPEC содержит non-empty `external_systems` или source PRD содержит заполненную секцию §6A → `c4_context` **ОБЯЗАТЕЛЕН** (добавить в `needed_artifacts` безусловно, `--skip=c4_context` НЕ удаляет его).
6. Применить `--only` (whitelist полностью переопределяет detection) и `--skip` (вычитает из detected)
7. **Если `needed_artifacts` пуст** → exit clean без state mutation:
```
═══════════════════════════════════════════
DESIGN PACKAGE НЕ НУЖЕН
═══════════════════════════════════════════
Анализ {PRD-001 | SPEC-001} не выявил архитектурных артефактов:
- нет API endpoints
- нет entities/data model
- нет multi-step flows
- нет архитектурных decisions
Рекомендую:
→ /polisade:tasks {PRD-001 | SPEC-001} — создать задачи напрямую
→ /polisade:roadmap SPEC-001 — если есть SPEC и нужен план фаз
═══════════════════════════════════════════
```
8. **PM checkpoint**: покажи detected набор + краткое "почему" на каждый артефакт + список ADR-кандидатов:
```
═══════════════════════════════════════════
DESIGN PACKAGE PLAN: DESIGN-001 from PRD-001
═══════════════════════════════════════════
Будут созданы артефакты:
✓ c4-context.md — внешние акторы: User, OAuth Provider
✓ c4-container.md — 4 контейнера: Web App, API, PostgreSQL, Redis
✓ sequences.md — 2 потока: OAuth callback, Token refresh
✓ data-model.md — 3 entities: User, Session, Token
✓ api.md — 6 endpoints (OpenAPI 3.0)
✓ glossary.md — 12 терминов из домена auth
✓ ADR-003 — Mermaid over PlantUML for doc-as-code
✓ ADR-004 — Sessions in Redis vs DB
Пропущены (не обнаружены триггеры):
✗ c4-component.md — single container не требует Level 3
✗ async-api.md — нет message broker / event-driven паттернов
✗ state-machines.md — нет сущностей с ≥ 3 состояниями
✗ deployment.md — нет явных NFRs про инфраструктуру
Продолжить? [y / n / edit]
═══════════════════════════════════════════
```
PM выбирает:
- `y` → Phase 3
- `n` → exit без изменений
- `edit` → показать interactive picker, дать добавить/убрать, повторить confirmation
### Phase 3 — Allocate IDs and paths
<!-- polisade:exec-denied CAPSULE BEGIN -->
> ⛔ **Вызов скрипта отклонён или не запустился** (`Command references protected path` / `Install directory is read-protected` / `Filesystem Guard` / `the tool's default permission is 'deny'`, отказ песочницы, ненулевой exit без вывода) — **STOP**.
> Процитируй отказ дословно. НЕ пересказывай по исходнику, что скрипт «сделал бы»; НЕ собирай dry-run вручную; НЕ переходи к apply/push/pr-create.
> НЕ транскрибируй скрипт (прочитать → записать копию в `/tmp` или в проект → запустить копию): копия не байт-идентична — уезжают классы символов в regex, форма возврата функций, пропадают целые функции — и молча меняется набор применённых изменений.
> Отказ инструмента — это отказ, а не результат. Доложи PM дословный текст отказа и сошлись на #127 (доставка скриптов в проект).
<!-- polisade:exec-denied CAPSULE END -->
1. **Вычисли next-id для DESIGN и ADR** по протоколу из
`skills/tasks/references/compute-next-id.md`.
Для DESIGN источник file-scan — имена директорий
`docs/architecture/DESIGN-*/` (авторитет), не содержимое README. Для
ADR — `docs/architecture/decisions/ADR-*.md`. При **Counter drift** (любой из двух типов)
— АБОРТ с рекомендацией
`${POLISADE_PYTHON:-python3} {plugin_root}/scripts/polisade_sync.py . --apply --yes`.
2. **Write-guard.** Перед созданием директории пакета
`docs/architecture/DESIGN-{N}-slug/` проверь, что директория не
существует и что `DESIGN-{N}` нет в `state.artifactIndex`. Для каждого
ADR в наборе — аналогично для `docs/architecture/decisions/ADR-{Nk}-slug.md`. При
коллизии — АБОРТ до любого IO.
> Этот guard проверяет план, а не момент записи: между ним и публикацией
> ADR проходит вся генерация и ревью. Окно закрывает не он, а
> `--expect-absent` примитива в Phase 6.5 — guard экономит работу, контракт
> защищает файл.
3. Инкрементируй `DESIGN` → `DESIGN-NNN`
4. Если ADR в наборе: для каждого ADR инкрементируй `ADR` → `ADR-NNN`
5. Вычисли `slug` = kebab-case от title input artifact
6. Build file plan:
```
Package dir: docs/architecture/DESIGN-{NNN}-{slug}/
Files:
- docs/architecture/DESIGN-{NNN}-{slug}/README.md (always)
- docs/architecture/DESIGN-{NNN}-{slug}/manifest.yaml (always — machine-readable index)
- docs/architecture/DESIGN-{NNN}-{slug}/c4-context.md (if in set)
- docs/architecture/DESIGN-{NNN}-{slug}/c4-container.md (if in set)
- docs/architecture/DESIGN-{NNN}-{slug}/c4-component.md (if in set)
- docs/architecture/DESIGN-{NNN}-{slug}/sequences.md (if in set)
- docs/architecture/DESIGN-{NNN}-{slug}/data-model.md (if in set)
- docs/architecture/DESIGN-{NNN}-{slug}/api.md (if in set)
- docs/architecture/DESIGN-{NNN}-{slug}/async-api.md (if in set)
- docs/architecture/DESIGN-{NNN}-{slug}/state-machines.md (if in set)
- docs/architecture/DESIGN-{NNN}-{slug}/deployment.md (if in set)
- docs/architecture/DESIGN-{NNN}-{slug}/glossary.md (if in set)
- docs/architecture/DESIGN-{NNN}-{slug}/quality-scenarios.md (if in set)
ADRs — генерируются в STAGING, а не в корпус (см. капсулу «единственный
писатель»); в docs/architecture/decisions/ их кладёт примитив в Phase 6.5:
- .polisade/tmp/design/DESIGN-{NNN}/decisions/ADR-{N1}-{slug1}.md
- .polisade/tmp/design/DESIGN-{NNN}/decisions/ADR-{N2}-{slug2}.md
→ docs/architecture/decisions/ADR-{N1}-{slug1}.md (Phase 6.5)
→ docs/architecture/decisions/ADR-{N2}-{slug2}.md (Phase 6.5)
```
### Phase 4 — Prepare subagent context
Собери в один большой context block:
1. **Source artifact** — полное содержимое PRD или SPEC
2. **Parent artifact** — если SPEC → читать parent PRD; иначе "N/A"
3. **Extra inputs** — concatenated содержимое каждого `--inputs` файла
4. **Constraints, Assumptions, Dependencies** (из source SPEC §4, если source — SPEC):
- Извлеки секцию 4 целиком (Assumptions A-N, Constraints C-N, Dependencies D-N)
- Если source — PRD (SPEC ещё нет): "N/A — constraints будут определены в SPEC"
- Constraints критичны для design decisions: если C-1 говорит "PostgreSQL only" —
ADR НЕ должен предлагать MongoDB; если C-2 — "GDPR" — deployment view
ОБЯЗАН показать EU-region isolation
4b. **System boundary for C4 Context** (если `c4_context` в `needed_artifacts`):
- Из SPEC frontmatter: `system_boundary` → label для центрального `System()` блока
- Из SPEC frontmatter: `external_systems[]` → каждый элемент становится `System_Ext()` блоком
- Из SPEC §7.0 Integration Matrix: протоколы → labels для `Rel()` связей
- Если source — PRD: из §6A.1 → `System()`, из §6A.2 → `System_Ext()`
5. **Project knowledge** (из `.state/knowledge.json`):
- `projectContext.name`, `description`, `techStack`, `keyFiles`
- `patterns` (следуй), `antiPatterns` (избегай)
- `decisions` (учитывай существующие ADRs)
- `architecture.activeADRs` из PROJECT_STATE — список активных ADRs (не дублируй)
6. **Relevant references** — для каждого артефакта в `needed_artifacts` прочитай соответствующий `skills/design/references/<type>-guide.md`. **Не читай гайды для skipped артефактов** — это экономит контекст.
7. **`skills/design/references/manifest-schema.md`** — ВСЕГДА (для генерации manifest.yaml)
8. **`docs/templates/adr-template.md`** — только если ADR в наборе
### Phase 5 — Launch subagent (general-purpose, clean context)
Используй Task tool:
```
Task tool:
subagent_type: "general-purpose"
description: "Create design package DESIGN-{NNN} from {PRD-XXX | SPEC-XXX}"
prompt: [structured prompt below]
```
**Prompt structure:**
```
═══════════════════════════════════════════
SYSTEM ROLE: Solution Design Architect
═══════════════════════════════════════════
Ты — senior software architect. Ты создаёшь doc-as-code design package: набор
Markdown-файлов с Mermaid-диаграммами, OpenAPI-спекой, AsyncAPI-спекой и ADR.
ПРИНЦИПЫ:
1. C4 FIRST (Simon Brown)
Для архитектурных диаграмм используй C4 model. Уровни Context → Container →
Component слоятся консистентно: имена сервисов в Container == participants в
sequence diagrams == tags в OpenAPI.
**C4 Context обязателен** если `external_systems` в source SPEC non-empty:
- `system_boundary` из SPEC → центральный `System()` блок
- Каждая запись `external_systems` → `System_Ext()` блок
- Протоколы из §7.0 Integration Matrix → labels на `Rel()` связях
- Skip C4 Context разрешён ТОЛЬКО для доказанно standalone систем (нет external_systems)
2. UBIQUITOUS LANGUAGE (DDD)
Если glossary в наборе — генерируй его ПЕРВЫМ. Все entities, services, термины
в остальных артефактах ДОЛЖНЫ использовать имена из glossary. Если glossary нет
— выработай consistent naming сам и применяй везде.
3. MERMAID ONLY
Все диаграммы — fenced ```mermaid блоки внутри .md файлов. PlantUML НЕ используем.
Поддерживаемые типы: C4Context, C4Container, C4Component, sequenceDiagram, erDiagram,
stateDiagram-v2, flowchart (для deployment).
4. ADR — ДЛЯ DECISIONS, НЕ ОПИСАНИЙ
Создавай ADR ТОЛЬКО когда:
- Серьёзно рассматривалась альтернатива
- Решение имеет долгосрочные последствия
- Решение отклоняется от patterns/antiPatterns в knowledge.json
НЕ создавай ADR на тривиальные выборы вроде "используем JSON для API".
5. OPENAPI + ASYNCAPI КАК SOURCE OF TRUTH ДЛЯ API
OpenAPI 3.0 YAML — внутри fenced ```yaml блока в `api.md` (sync REST).
AsyncAPI 3.0 YAML — внутри fenced ```yaml блока в `async-api.md` (event-driven).
НЕ создавай отдельные .yaml файлы. Все REST endpoints → OpenAPI, все
каналы/events → AsyncAPI. Schema names в `components.schemas` обеих спек
ДОЛЖНЫ совпадать (User = User, Order = Order). Если система имеет и REST,
и async — создаются ОБА артефакта.
Если `docs/contracts/provided/` существует — запиши OpenAPI/AsyncAPI YAML туда
(например `docs/contracts/provided/api-<slug>.yaml`), а в `api.md`/`async-api.md`
сделай ссылку: **Source of truth:** `docs/contracts/provided/<file>`. YAML в fenced-блоке
`api.md` при этом не дублируется — только ссылка и архитектурный комментарий.
6. NO PLACEHOLDERS
Никаких "и т.д.", "при необходимости", "TBD", "{example}". Конкретные имена
полей, конкретные эндпоинты, конкретные участники в sequence flows.
7. CONSERVATIVE INCLUSION
Если есть сомнения нужен ли артефакт — включай и помечай "low confidence" в
README. PM удалит лишнее быстрее, чем заметит отсутствующее.
8. RESPECT CONSTRAINTS
Constraints из SPEC §4 (C-N) — нерушимые. Если constraint фиксирует стек
(например, "PostgreSQL only") — ни один ADR, data-model или deployment не должен
предлагать альтернативы. Если constraint задаёт compliance — deployment view и
data-model обязаны его отражать. Dependencies (D-N) должны появиться как
external systems в C4 Context/Container. Assumptions (A-N) — пометь в README
какие design decisions зависят от каких assumptions.
═══════════════════════════════════════════
NEEDED ARTIFACTS (создавай ТОЛЬКО эти)
═══════════════════════════════════════════
DESIGN-{NNN}, package dir: docs/architecture/DESIGN-{NNN}-{slug}/
Артефакты для генерации:
{список из needed_artifacts с rationale из Phase 2}
ADR кандидаты:
{список ADR с предварительными titles}
═══════════════════════════════════════════
SOURCE ARTIFACT: {PRD-XXX | SPEC-XXX}
═══════════════════════════════════════════
{полное содержимое source artifact}
═══════════════════════════════════════════
PARENT ARTIFACT (если есть)
═══════════════════════════════════════════
{полное содержимое parent или "N/A"}
═══════════════════════════════════════════
EXTRA CONTEXT (из --inputs)
═══════════════════════════════════════════
{concatenated --inputs или "N/A"}
═══════════════════════════════════════════
CONSTRAINTS, ASSUMPTIONS, DEPENDENCIES (из SPEC §4)
═══════════════════════════════════════════
{секция 4 из source SPEC целиком (A-N, C-N, D-N) или "N/A — source is PRD, no SPEC yet"}
ИНСТРУКЦИЯ ПО CONSTRAINTS:
- Constraints (C-N) — нерушимые ограничения. Каждый ADR и каждое design decision
ОБЯЗАНЫ быть совместимы со ВСЕМИ constraints. Если constraint фиксирует технологию
(C-1: "PostgreSQL only") — НЕ предлагай альтернативы. Если constraint задаёт
compliance (C-2: "GDPR") — deployment view и data-model ОБЯЗАНЫ это отражать.
- Assumptions (A-N) — подвержены изменению. Отметь в README если дизайн-решение
зависит от assumption — чтобы при invalidation было понятно что пересматривать.
- Dependencies (D-N) — отрази в C4 Context/Container как внешние системы/библиотеки.
═══════════════════════════════════════════
PROJECT KNOWLEDGE
═══════════════════════════════════════════
Project: {knowledge.projectContext.name}
Description: {knowledge.projectContext.description}
Tech stack: {knowledge.projectContext.techStack}
Key files: {knowledge.projectContext.keyFiles}
Patterns to follow:
{knowledge.patterns}
Anti-patterns to avoid:
{knowledge.antiPatterns}
Existing decisions (do NOT duplicate):
{knowledge.decisions}
Active ADRs:
{PROJECT_STATE.architecture.activeADRs}
═══════════════════════════════════════════
REFERENCE GUIDES (per artifact type)
═══════════════════════════════════════════
{concatenated relevant references/*.md files for needed_artifacts}
═══════════════════════════════════════════
MANIFEST SCHEMA (всегда)
═══════════════════════════════════════════
{полное содержимое skills/design/references/manifest-schema.md}
═══════════════════════════════════════════
ADR TEMPLATE (только если ADR в наборе)
═══════════════════════════════════════════
{содержимое docs/templates/adr-template.md или "N/A"}
═══════════════════════════════════════════
OUTPUT REQUIREMENTS
═══════════════════════════════════════════
1. Используй Write tool для каждого файла из плана.
2. ПОРЯДОК ГЕНЕРАЦИИ:
a. glossary.md ПЕРВЫМ если в наборе (seeds ubiquitous language)
b. data-model.md (если в наборе) — определяет entities
c. api.md (если в наборе) — endpoints + schemas (имена из glossary/data-model)
c2. async-api.md (если в наборе) — channels + events + payload schemas (имена из glossary/data-model, совпадают с api.md schemas)
d. c4-* (если в наборе) — сервисы используют те же имена
e. sequences.md (если в наборе) — participants = сервисы из C4
f. state-machines.md (если в наборе) — entities из data-model
g. deployment.md (если в наборе)
h. quality-scenarios.md (если в наборе) — каждый scenario ссылается на NFR-NNN из source SPEC
i. ADRs — отдельные файлы, но пиши их в STAGING
`.polisade/tmp/design/DESIGN-{NNN}/decisions/ADR-{Nk}-{slug}.md`, НЕ в
`docs/architecture/decisions/`. Живой корпус пишет только примитив
`polisade_corpus_io.py`; ADR попадёт туда в Phase 6.5 после ревью.
Write-инструментом в `docs/architecture/` не пиши ничего, кроме файлов
самого пакета `docs/architecture/DESIGN-{NNN}-{slug}/`.
j. README.md — собирает всё; ОБЯЗАТЕЛЬНО заполняй секцию "Solution Strategy"
3-5 буллетов с ключевыми архитектурными решениями: style, persistence, communication,
deployment, observability. Каждый буллет ссылается на ADR если решение зафиксировано
в ADR. Это arc42 §4 — карта решений для нового человека/агента.
README.md ОПЦИОНАЛЬНО включает секцию "Risks and Technical Debt" (arc42 §11)
если в source PRD/SPEC обнаружены:
- риски (markers: "risk", "concern", "if X happens", "SPOF", "single point of failure")
- accepted shortcuts (markers: "for now", "MVP", "TODO", "later", "Phase 2", "quick win")
- open issues (markers: "TBD", "decide later", "to be confirmed")
Если хотя бы один маркер найден — заполни секцию с таблицами:
- Known Risks: ID=R-NNN, Risk, Probability, Impact, Mitigation
- Accepted Technical Debt: ID=TD-NNN, Description, Reason, Payback Plan, Priority
- Open Issues: checklist items
Если ни один маркер не найден — удали секцию из README целиком (не оставляй пустую).
Подробные триггеры — в `references/conditional-triggers.md` секция `risks_tech_debt`.
k. manifest.yaml (САМЫМ ПОСЛЕДНИМ) — machine-readable индекс package.
Schema и пример — см. секцию "MANIFEST SCHEMA" выше. Заполняй ОБЯЗАТЕЛЬНО:
- `id`, `parent`, `title`, `created`, `status: ready`, `schema_version: 1`
- `artifacts[]` — для КАЖДОГО созданного sub-artifact файла одна запись с
`type`, `file`, `realizes_requirements` (как во frontmatter sub-artifact),
и type-specific полями (entities, components, scenarios и т.п.)
- `adrs[]` — для КАЖДОГО созданного ADR: `id`, `title`, `file` (относительный
путь от package dir, обычно `../../adr/ADR-NNN-slug.md`), `status`, `addresses`
- `skipped[]` — для каждого артефакта, который не создавался, с `reason`
manifest.yaml ДОЛЖЕН быть консистентен с frontmatter sub-артефактов:
`realizes_requirements` в manifest для каждого артефакта = значение в его
frontmatter (агрегация без противоречий).
3. FRONTMATTER КАЖДОГО ФАЙЛА:
- README.md: id, type=design-package, title, status=ready, created, parent, children, source, input_artifact, extra_inputs, artifacts (см. ниже)
- Sub-artifacts (c4-*, sequences, data-model, api, async-api, state-machines, deployment, glossary, quality-scenarios):
type, parent=DESIGN-{NNN}, created
realizes_requirements: [{DOC}.FR-NNN, {DOC}.NFR-NNN, ...] — ОБЯЗАТЕЛЬНО
заполнить composite IDs (DOC = manifest.parent, т.е. SPEC-XXX / PRD-XXX
/ FEAT-XXX). Bare `FR-NNN` допустим только если в проекте ровно один
top-level doc объявляет это FR; иначе lint блокирует.
Значения должны СОВПАДАТЬ с `manifest.yaml` `artifacts[].realizes_requirements`
для того же файла (lint ловит drift).
Glossary доменно-независим → realizes_requirements: []
quality-scenarios адресует исключительно NFR → realizes_requirements: [{DOC}.NFR-NNN, ...]
НЕ добавляй status (наследуется от DESIGN-PKG)
- ADR (полный MADR — см. references/adr-guide.md): id, title, status=proposed,
date, deciders, consulted, informed, superseded_by=null,
related: [DESIGN-{NNN}, {parent_artifact_id}],
addresses: [{DOC}.FR-NNN, {DOC}.NFR-NNN] — ОБЯЗАТЕЛЬНО: composite IDs
требований, которые адресует ADR (для traceability — изменение NFR →
найти затронутые ADR)
ADR body ОБЯЗАН содержать секции (полный MADR, не minimal):
Context and Problem Statement / Decision Drivers / Considered Options /
Decision Outcome (с Consequences: Positive/Negative/Risks) /
Pros and Cons of the Options (≥ 2 options, для каждой ≥ 1 ✓ и ≥ 1 ✗) /
Validation / More Information / Related Decisions
Decision Drivers — измеримые/бинарные критерии, по которым сравниваются
Considered Options. Если NFR в source SPEC влияет на выбор — driver
должен явно ссылаться на NFR-NNN.
4. CROSS-REFERENCES:
- В README.md: ссылки на каждый созданный файл + ссылка на `manifest.yaml`
- В каждом sub-artifact: backlink на README package
- В ADRs: related включает DESIGN-{NNN} и source artifact
- manifest.yaml не содержит markdown-ссылок — это data-файл
5. INTEGRATION SELF-REVIEW (если `external_systems` в source SPEC/PRD):
Для каждой интеграции проверь:
- Есть ли sequence diagram с error path (timeout, retry, fallback)?
- Есть ли circuit breaker / retry в quality scenarios?
- Совпадает ли data model с consumed contract (если contract_ref указан)?
Если проверка выявила пробелы — добавь Open Question в README.md секцию
"Open Issues" (или создай её), НЕ блокируй генерацию.
═══════════════════════════════════════════
ФОРМАТ ОТВЕТА
═══════════════════════════════════════════
После создания всех файлов верни:
РЕЗУЛЬТАТ:
- Status: ready | waiting_pm
- Package: docs/architecture/DESIGN-{NNN}-{slug}/
ФАЙЛЫ СОЗДАНЫ:
- {path1}
- {path2}
- ...
ADR СОЗДАНЫ:
- ADR-XXX: {title}
- ADR-YYY: {title}
ПРОПУЩЕНЫ (с причиной):
- {type}: {почему}
CROSS-REFERENCES (sanity check):
- glossary terms used in: {list of files}
- entities in data-model match OpenAPI schemas: yes/no
- entities in data-model match AsyncAPI payload schemas: yes/no (если async-api.md создан)
- OpenAPI и AsyncAPI components.schemas consistent: yes/no (если оба созданы)
- C4 container names match sequence participants: yes/no
- manifest.yaml artifacts[].realizes_requirements == sub-artifact frontmatter: yes/no
- manifest.yaml adrs[].addresses == ADR frontmatter addresses: yes/no
ВОПРОСЫ К PM (если status=waiting_pm):
- {question}
```
### Phase 5.9 — Сверка с внешним эталоном (только если PM его передал)
Выполняется, **если** PM передал reference-спеку — файл или папку со схемами
(`--reference=<путь>`, либо явно назвал её в диалоге; часто она приезжает и как
`--inputs`). Не передал — фазы нет, и в отчёте так и пишется: «эталон не
передан», а не «расхождений нет».
Мотив (issue #164): модель «перечитала и вроде совпадает» пропускает ровно тот
класс, который дороже всего чинить — **вариативность по типу сообщения**.
В корп-сессии `NOTIFICATION` нёс `parentRequestId` (`format: uuid`), а
`RESPONSE` — `parentrequestId` (`pattern: ^[a-f0-9]{32}$`); модель объявила
разницу «опечаткой в документации» и несколько итераций правила артефакт
правдоподобно и неверно. Поэтому сверка здесь **механическая**, а не
внимательная.
<!-- polisade:exec-denied CAPSULE BEGIN -->
> ⛔ **Вызов скрипта отклонён или не запустился** (`Command references protected path` / `Install directory is read-protected` / `Filesystem Guard` / `the tool's default permission is 'deny'`, отказ песочницы, ненулевой exit без вывода) — **STOP**.
> Процитируй отказ дословно. НЕ пересказывай по исходнику, что скрипт «сделал бы»; НЕ собирай dry-run вручную; НЕ переходи к apply/push/pr-create.
> НЕ транскрибируй скрипт (прочитать → записать копию в `/tmp` или в проект → запустить копию): копия не байт-идентична — уезжают классы символов в regex, форма возврата функций, пропадают целые функции — и молча меняется набор применённых изменений.
> Отказ инструмента — это отказ, а не результат. Доложи PM дословный текст отказа и сошлись на #127 (доставка скриптов в проект).
<!-- polisade:exec-denied CAPSULE END -->
```bash
${POLISADE_PYTHON:-python3} {plugin_root}/scripts/polisade_reference_fields.py \
diff <файл-или-каталог-эталона> <файл-артефакта> --json
```
Эталоном может быть **файл или каталог** — каталог скрипт обходит сам
(не рекурсивно, по расширениям `.json/.yaml/.yml/.md`, в отсортированном
порядке) и печатает список источников со статусом каждого. ⛔ Не собирай
таблицу из папки вручную и не выбирай «главный» файл: набор источников должен
быть виден в выводе, а не в твоей голове. Пара «эталон — артефакт» подбирается
по смыслу контракта: схемы сообщений ↔ `async-api.md`, OpenAPI-эталон ↔ `api.md`.
Обработка exit-кода:
- **0** — расхождений по сверенным измерениям нет. В отчёт идёт именно эта
формулировка, а не «артефакт соответствует эталону»: сравниваются только
имя, тип, `format`/`pattern` и `required` (полный список слепых пятен —
`--rules`).
- **1** — есть расхождения. Таблицу `[вариант, поле, ожидание, текущее,
вердикт]` вставь в отчёт Phase 8 ЦЕЛИКОМ и повтори сверку в **каждой**
Improvement-итерации Phase 6.
- **2** — не разобрано (якорь YAML, многострочный блок, второй документ,
неизвестная форма). Это **не** «чисто»: процитируй `файл:строка` из вывода
и скажи PM, что сверка не выполнена. Подать неразбор как отсутствие
расхождений запрещено.
⛔ **Что делать с расхождением — решает PM, а не ты** (дисциплина #88):
- НЕ объявляй расхождение эталона «опечаткой в документации»;
- НЕ выбирай одно из двух имён/форматов «основным» и не приводи к нему
артефакт;
- НЕ схлопывай вариативность по типу сообщения в один «общий» набор полей;
- зафиксируй каждый спорный пункт как **открытый вопрос**:
```
DECISION NEEDED — сверка с эталоном
Вариант: RESPONSE
Поле: parentrequestId (эталон) vs parentRequestId (артефакт)
Эталон: pattern ^[a-f0-9]{32}$, required
Артефакт: format uuid, required
Вопрос: какое написание и какой формат канонические для этого типа
сообщения? Правка артефакта до ответа не делается.
```
Граница (ADR-0003): это сверка **двух документов** — линт формы на входе. Это
не сверка с кодом (её best-effort сосед — `/polisade:reconcile-docs`) и не
вердикт об архитектурном корпусе.
### Phase 6 — Holistic Quality Review Loop
Адаптация Quality Review Loop из `/polisade:spec` (lines 242-388), но **холистическая** (один ревью на весь package, не per-file).
```
┌──────────────────────────────────────────┐
│ REVIEW SUBAGENT (clean context) │
│ INPUT: source PRD/SPEC + parent (если) │
│ OUTPUT: ВСЕ файлы package + ВСЕ ADRs │
│ → Score 1-10 по 5 критериям │
│ → Конкретные улучшения │
└──────────────────┬───────────────────────┘
▼
┌───────────────┐
│ Score >= 8? │───YES──→ PROCEED
└───────┬───────┘
NO
▼
┌──────────────────────────────────────────┐
│ IMPROVEMENT SUBAGENT (clean context) │
│ → Применяет improvements ко всему package│
└──────────────────┬───────────────────────┘
▼
┌───────────────┐
│ Iteration < 2?│───NO──→ PROCEED (log warning)
└───────┬───────┘
YES → Back to review
```
**Anti-loop safety**: max 2 итерации (review + improve). После 2-й — proceed с предупреждением в session-log.
#### Renderability — детерминированный критерий (issue #188)
Depth оценивает модель («диаграмма детальная, не placeholder»); рендеримость
модель не видит вовсе — битый ` ```mermaid `-блок читается в исходнике как
правдоподобный, а в GitHub/GitLab/VS Code даёт `Parse error` и исчезает
целиком. Инцидент 2026-06-22: 5 блоков в 4 файлах упали из-за `;` в подписях
стрелок и в метках `loop`/`alt`/`else`.
Поэтому **до** запуска Review-субагента прогони линт по сгенерированному
пакету и по staging'у ADR:
<!-- polisade:exec-denied CAPSULE BEGIN -->
> ⛔ **Вызов скрипта отклонён или не запустился** (`Command references protected path` / `Install directory is read-protected` / `Filesystem Guard` / `the tool's default permission is 'deny'`, отказ песочницы, ненулевой exit без вывода) — **STOP**.
> Процитируй отказ дословно. НЕ пересказывай по исходнику, что скрипт «сделал бы»; НЕ собирай dry-run вручную; НЕ переходи к apply/push/pr-create.
> НЕ транскрибируй скрипт (прочитать → записать копию в `/tmp` или в проект → запустить копию): копия не байт-идентична — уезжают классы символов в regex, форма возврата функций, пропадают целые функции — и молча меняется набор применённых изменений.
> Отказ инструмента — это отказ, а не результат. Доложи PM дословный текст отказа и сошлись на #127 (доставка скриптов в проект).
<!-- polisade:exec-denied CAPSULE END -->
```bash
${POLISADE_PYTHON:-python3} {plugin_root}/scripts/polisade_lint_mermaid.py . \
--paths 'docs/architecture/DESIGN-{NNN}-*/**/*.md' \
'.polisade/tmp/design/DESIGN-{NNN}/**/*.md' \
--json
```
Обработка:
- **exit 0** — критерий `Renderability: PASS (N блоков)`. Это значит «ни одна
из известных граблей не найдена», а НЕ «диаграмма рендерится»: линт —
детектор класса ошибок, не парсер Mermaid (список слепых пятен — в его
`--help`). Не заявляй PM большего.
- **exit 1** — каждая находка цитируется как `файл:строка` + код (`MM-01`…)
и уходит в Improvement-итерацию Phase 6 **как блокер наравне с критичными
проблемами ревью**. После Improvement линт запускается заново.
- **После 2-й итерации с красным линтом** — `waiting_pm`, не `ready`.
В отчёте PM: список `файл:строка код` целиком. ⛔ Пометить пакет `ready`
при красном линте запрещено — «тихо ready» это и есть тот класс, из-за
которого PM получал архитектуру с битыми диаграммами.
- **exit 2** — ошибка использования (не каталог, пустой `--paths`): это
сломанный вызов, а не зелёный результат. Почини вызов, не пропускай шаг.
#### Сверка с эталоном — в КАЖДОЙ Improvement-итерации (issue #164)
Если Phase 5.9 выполнялась, её `diff` повторяется после каждой Improvement-
итерации, ровно как линт рендеримости выше. Причина та же: правка, сделанная
«по смыслу», легко уводит имя поля или `format` от эталона, а следующий проход
ревью этого не увидит — он сверяет пакет с source SPEC, а не с внешней спекой.
- exit 1 после Improvement — расхождения идут в следующую итерацию наравне с
критичными замечаниями ревью;
- расхождения, помеченные PM как **Decision needed**, Improvement-субагент
**не чинит** и не «приводит к одному виду» — они остаются открытыми
вопросами до ответа PM;
- после 2-й итерации с оставшимися расхождениями — `waiting_pm` с таблицей
целиком, не `ready`.
#### Запуск Review субагента
Прочитай:
1. Source PRD/SPEC + parent (если есть)
2. **ВСЕ файлы созданного package** (README + все sub-artifacts)
3. **ВСЕ созданные ADRs** — они ещё в staging
(`.polisade/tmp/design/DESIGN-{NNN}/decisions/`), в корпусе их пока нет;
ревью и правки идут ИМЕННО ТАМ, публикация — Phase 6.5
Запусти Task tool:
```
Task tool:
subagent_type: "general-purpose"
description: "Holistic quality review DESIGN-{NNN}"
prompt: [prompt ниже]
```
Prompt для review субагента:
```
═══════════════════════════════════════════
SYSTEM ROLE: Independent Design Reviewer
═══════════════════════════════════════════
Ты — независимый ревьюер архитектурного дизайна. Ты НЕ автор этого package.
Твоя задача — холистически (целиком) оценить package на соответствие source artifact.
ПРАВИЛА:
1. Оценивай ТОЛЬКО по фактам из source — не додумывай
2. Каждое замечание ссылается на конкретный файл и место в source
3. Не хвали — только конкретные проблемы и оценки
4. Если всё хорошо — высокий балл, не ищи проблемы искусственно
═══════════════════════════════════════════
SOURCE ARTIFACT
═══════════════════════════════════════════
{полное содержимое source PRD или SPEC + parent}
═══════════════════════════════════════════
DESIGN PACKAGE (все файлы)
═══════════════════════════════════════════
{полное содержимое README.md package}
{полное содержимое каждого sub-artifact}
{полное содержимое каждого созданного ADR}
═══════════════════════════════════════════
COVERAGE MATRIX (для критериев Requirement Coverage и Implementation Fidelity)
═══════════════════════════════════════════
Перед оценкой Requirement Coverage:
1. Извлеки список FR-NNN и NFR-NNN из source SPEC секций 5/6
2. Извлеки realizes_requirements из frontmatter КАЖДОГО sub-artifact
3. Извлеки addresses из frontmatter КАЖДОГО созданного ADR
4. Построй матрицу: каждое требование → артефакты которые его адресуют
5. В критичных проблемах перечисли непокрытые FR/NFR явно
Перед оценкой FR/NFR Implementation Fidelity:
6. Для КАЖДОГО FR извлеки из source SPEC все конкретные значения:
- Числа (timeout, размеры, лимиты, retry counts, TTL, expiration)
- Поля и типы данных (что должно храниться, что возвращаться)
- Edge cases и error conditions из EARS / Gherkin acceptance
7. Для КАЖДОГО NFR определи его категорию (performance / security / reliability / usability / …)
и найди соответствующий sub-artifact или ADR, который его материализует
8. Сравни буквально: FR-NNN.{значение/поле/условие} ↔ DESIGN.{значение/поле/условие}.
Любое расхождение — критичная проблема.
═══════════════════════════════════════════
КРИТЕРИИ ОЦЕНКИ (X/10 каждый)
═══════════════════════════════════════════
1. Artifact Coverage (X/10) — каждый артефакт из NEEDED set действительно создан и заполнен (не stub)
2. Requirement Coverage (X/10) — каждое FR/NFR из source SPEC адресовано хотя бы одним sub-artifact:
- FR должен быть в realizes_requirements хотя бы одного sub-artifact
- NFR должен быть в realizes_requirements (предпочтительно в quality-scenarios.md как arc42 §10 measurable scenario)
ИЛИ в addresses одного из созданных ADR
- Если quality-scenarios.md в наборе: каждое NFR из source SPEC ОБЯЗАТЕЛЬНО имеет ≥ 1 сценарий Q-NNN
3. Consistency (X/10) — имена entities в ERD == schema names в OpenAPI == payload schema bases в AsyncAPI == terms в glossary == participants в sequences == container names в C4
4. Depth (X/10) — Mermaid диаграммы детальные, не placeholder; OpenAPI имеет request/response/errors; AsyncAPI имеет channels/operations/payload schemas.
Синтаксическую рендеримость блоков НЕ оценивай: её уже проверил
детерминированный линт (`polisade_lint_mermaid.py`, критерий Renderability),
и твоя догадка на этот счёт не добавляет сигнала
5. Source Alignment (X/10) — ничего не выдумано сверх source PRD/SPEC; все требования source отражены
6. Clarity (X/10) — нет placeholders, "и т.д.", "TBD"; concrete имена и поля
7. FR Implementation Fidelity (X/10) — для каждого FR из source SPEC реализующий
sub-artifact ТОЧНО отражает требование (не просто упомянут — буквально совпадает):
- Числовые значения (timeout, размеры, лимиты, TTL, retry, expiration) совпадают
до конкретных значений (30 минут != 3600 секунд если SPEC говорит «30 минут»)
- Поля и типы в data-model совпадают с описанием в FR (если FR требует
`user_id, action, timestamp` — все три должны быть в Log entity, не два из трёх)
- Endpoint paths, methods, status codes в OpenAPI совпадают с тем, что описано в FR
- Edge cases из FR.acceptance (Gherkin scenarios, EARS «WHEN/IF») отражены
в sequence diagrams или error responses в OpenAPI
В justification ОБЯЗАТЕЛЬНО покажи проверку для каждого FR одним из форматов:
- "FR-001 → c4-container.md (auth-service): OK"
- "FR-005 → data-model.md: NOT OK — поле user_id отсутствует в Log entity"
- "FR-007 → api.md (POST /sessions): NOT OK — expires_in=3600, SPEC требует 1800 (30 минут)"
8. NFR Implementation Fidelity (X/10) — для каждого NFR из source SPEC найди
материализацию И проверь что цифры/условия совпадают:
- Performance NFR (latency/throughput/load) → quality-scenarios.md Q-NNN с теми же
значениями, или явно в deployment.md/api.md (rate limits, timeouts)
- Security NFR → отражено в OpenAPI security schemes / sequence auth flows / ADR
- Reliability NFR (availability, RPO/RTO, fault tolerance) → deployment view
или sequence error/retry/compensation paths
- Usability/Maintainability/Portability → ADR addresses или quality-scenarios
В justification покажи каждое NFR одним из форматов:
- "NFR-002 → quality-scenarios.md Q-003: OK (rate limit 100 req/min/user)"
- "NFR-002 → NOT FOUND — rate limit 100 req/min/user не упомянут ни в одном sub-artifact"
- "NFR-004 → deployment.md: NOT OK — SPEC требует RTO 5 мин, deployment описывает 30 мин"
═══════════════════════════════════════════
ФОРМАТ ОТВЕТА
═══════════════════════════════════════════
ОЦЕНКИ:
- Artifact Coverage: X/10 — {brief justification}
- Requirement Coverage: X/10 — {brief justification, mention uncovered list если есть}
- Consistency: X/10 — {brief justification}
- Depth: X/10 — {brief justification}
- Source Alignment: X/10 — {brief justification}
- Clarity: X/10 — {brief justification}
- FR Implementation Fidelity: X/10 — {per-FR check, см. формат выше}
- NFR Implementation Fidelity: X/10 — {per-NFR check, см. формат выше}
- ИТОГО: X/10 (среднее по 8 критериям)
КРИТИЧНЫЕ ПРОБЛЕМЫ (блокеры, если есть):
1. {file:section}: {FR-NNN | NFR-NNN}: {что требует source} → {что не так в DESIGN}
Примеры:
- "data-model.md: FR-005 требует поле user_id в Log entity, но Log имеет только action+timestamp"
- "api.md POST /sessions: FR-001 требует session 30 минут, expires_in=3600 (1 час)"
- "quality-scenarios.md: NFR-002 требует rate limit 100 req/min/user, не упомянут нигде"
УЛУЧШЕНИЯ (конкретные, применимые):
1. {file:section}: {что изменить} → {как изменить}
2. ...
ВЕРДИКТ: PASS (среднее >= 8 И Requirement Coverage >= 8 И FR Implementation Fidelity >= 8 И NFR Implementation Fidelity >= 8) | IMPROVE (иначе)
Жёсткие минимумы на Requirement Coverage и FR/NFR Implementation Fidelity означают:
непокрытие требований ИЛИ расхождение конкретных значений (числа/поля/edge cases)
не компенсируются хорошими оценками других критериев — это блокеры.
```
#### Обработка результата review
**Если PASS (score >= 8):**
- Логируй score в session-log
- Phase 7
**Если IMPROVE (score < 8):**
- Запусти Improvement субагент → re-review (max 2 итерации)
#### Запуск Improvement субагента
```
Task tool:
subagent_type: "general-purpose"
description: "Improve DESIGN-{NNN} package based on review"
prompt: [prompt ниже]
```
Prompt:
```
Ты получил результаты независимого ревью design package.
Задача — применить конкретные улучшения к файлам package.
PACKAGE: docs/architecture/DESIGN-{NNN}-{slug}/
ADR (ещё не в корпусе): .polisade/tmp/design/DESIGN-{NNN}/decisions/
РЕКОМЕНДАЦИИ РЕВЬЮ:
{полный ответ review субагента}
ИНСТРУКЦИИ:
1. Прочитай каждый указанный в рекомендациях файл (Read tool)
2. Примени ТОЛЬКО рекомендации из ревью — не добавляй лишнего
3. Сохрани обновлённые файлы (Edit tool)
4. Верни список применённых изменений
```
#### Логирование
Добавь запись в `.state/session-log.md`:
```markdown
### Quality Review: DESIGN-{NNN} (from {SOURCE-ID})
- Date: {today}
- Renderability (polisade_lint_mermaid.py): {PASS N блоков | FAIL: файл:строка код, …}
- Iteration 1: {score}/10 → {PASS|IMPROVE}
- Iteration 2: {score}/10 → {PASS|IMPROVE} (если была)
- Files in package: {count}
- ADRs created: {count}
- Command: /polisade:design
```
### Phase 6.5 — Публикация ADR в корпус (единственный писатель)
До этого шага ADR лежат в staging и корпуса не касались. Здесь они попадают в
`docs/architecture/decisions/` — и только через примитив.
Для КАЖДОГО ADR из набора, по одному:
<!-- polisade:exec-denied CAPSULE BEGIN -->
> ⛔ **Вызов скрипта отклонён или не запустился** (`Command references protected path` / `Install directory is read-protected` / `Filesystem Guard` / `the tool's default permission is 'deny'`, отказ песочницы, ненулевой exit без вывода) — **STOP**.
> Процитируй отказ дословно. НЕ пересказывай по исходнику, что скрипт «сделал бы»; НЕ собирай dry-run вручную; НЕ переходи к apply/push/pr-create.
> НЕ транскрибируй скрипт (прочитать → записать копию в `/tmp` или в проект → запустить копию): копия не байт-идентична — уезжают классы символов в regex, форма возврата функций, пропадают целые функции — и молча меняется набор применённых изменений.
> Отказ инструмента — это отказ, а не результат. Доложи PM дословный текст отказа и сошлись на #127 (доставка скриптов в проект).
<!-- polisade:exec-denied CAPSULE END -->
```
${POLISADE_PYTHON:-python3} {plugin_root}/scripts/polisade_corpus_io.py write \
docs/architecture/decisions/ADR-{Nk}-{slug}.md \
--from .polisade/tmp/design/DESIGN-{NNN}/decisions/ADR-{Nk}-{slug}.md \
--run-id design-{NNN} --expect-absent --json
```
- `--expect-absent` — не украшение: между Write-guard'ом Phase 3 и этим
моментом прошли генерация и до двух итераций ревью. Если за это время ADR
под тем же номером создал кто-то другой, примитив откажет (`E-expect-present`
/ `E-expect-raced`), а не затрёт чужое решение.
- Ненулевой exit по ЛЮБОМУ ADR — **STOP до Phase 7**: покажи PM `code`, `hint`
и путь staging-файла (содержимое не потеряно, оно там лежит), не повторяй с
`--force` и не переходи к обновлению state. Уже опубликованные ADR остаются
в корпусе — назови их поимённо, чтобы PM видел, что доехало, а что нет.
- Успех — сверь, что `ok: true` и `expectMode: absent-atomic-link` (на
POSIX). `absent-checked` означает платформу без атомарного `linkat`:
гарантия слабее, скажи об этом в отчёте, а не молчи.
- Staging-каталог `.polisade/tmp/design/DESIGN-{NNN}/` после успеха можно
оставить: он gitignored и служит уликой того, что именно публиковалось.
### Phase 7 — State updates
1. **counters.json**: инкремент `DESIGN` (уже сделан в Phase 3); ADR счётчик уже инкрементирован
2. **PROJECT_STATE.json `artifacts`** — добавь **краткую** entry для DESIGN-PKG.
Rich-данные (realizes_requirements, components, scenarios, addresses) НЕ
дублируются здесь — они живут только в `manifest.yaml`. PROJECT_STATE хранит
только pointer на манифест и плоский список `{type, path}` для быстрого discovery:
```json
"DESIGN-001": {
"type": "DESIGN-PKG",
"title": "Design: {source title}",
"status": "ready",
"path": "docs/architecture/DESIGN-001-{slug}/README.md",
"created": "{today}",
"parent": "{SOURCE-ID}",
"children": ["ADR-003", "ADR-004"],
"package": {
"dir": "docs/architecture/DESIGN-001-{slug}/",
"manifest": "manifest.yaml",
"artifacts": [
{"type": "c4-context", "path": "c4-context.md"},
{"type": "c4-container", "path": "c4-container.md"},
{"type": "sequence", "path": "sequences.md"},
{"type": "erd", "path": "data-model.md"},
{"type": "openapi", "path": "api.md"},
{"type": "asyncapi", "path": "async-api.md"},
{"type": "glossary", "path": "glossary.md"},
{"type": "quality-scenarios", "path": "quality-scenarios.md"}
]
}
}
```
Поле `package.manifest` всегда `"manifest.yaml"` — relative path внутри `package.dir`.
Скрипты, которым нужны `realizes_requirements` или другие rich-поля, открывают
`{dir}/{manifest}` на месте.
3. **PROJECT_STATE.json — каждый созданный ADR** добавь как отдельную запись:
```json
"ADR-003": {
"type": "ADR",
"title": "Mermaid over PlantUML for doc-as-code",
"status": "proposed",
"path": "docs/architecture/decisions/ADR-003-mermaid-over-plantuml.md",
"created": "{today}",
"parent": null,
"children": []
}
```
4. **DESIGN-{NNN} → `readyToWork`**
5. **`architecture.activeADRs`** — append каждый созданный `ADR-{N}.id` (это поле сейчас dead, оживляется новым скиллом)
6. **Parent (PRD/SPEC)** — обнови:
- В `.md` файле frontmatter: добавь DESIGN-{NNN} в `children:`
- В `PROJECT_STATE.artifacts[parent_id].children`: добавь DESIGN-{NNN}
- **Статус parent НЕ меняй** (правило из `/polisade:spec` line 504)
7. **SPEC dedup — только если parent == SPEC:**
Цель: устранить дублирование API/data контента между SPEC и DESIGN-PKG.
После создания DESIGN-PKG в parent SPEC должны остаться только ссылки.
a. **Frontmatter parent SPEC** — установи поля:
```yaml
design_package: DESIGN-{NNN}
design_waiver: false
```
Если `design_waiver` был `true` (PM давал waiver ранее) — **сбрось в `false`**.
Waiver — временная мера до создания DESIGN. Теперь design создан,
enforcement восстанавливается для всех новых TASKs.
(`design_package` включает Режим B для секций 7.1 / 7.2 — см. spec-template.md)
b. **Секция 7.1 "Контракты компонентов / операций"** — если содержит
inline-таблицу Operations:
- Заменить таблицу на link-блок:
```markdown
> **См.** [[DESIGN-{NNN}/api.md]]
>
> SPEC определяет требования к API на уровне operations и связанных FR.
> Конкретные endpoints, request/response schemas, error codes —
> в `docs/architecture/DESIGN-{NNN}-{slug}/api.md`.
```
- Удалить inline-таблицу полностью
- Если в SPEC уже link-блок (Режим B уже стоял) — просто обнови ID
c. **Секция 7.2 "Контракты данных"** — если содержит inline-таблицу
Entities:
- Заменить таблицу на link-блок:
```markdown
> **См.** [[DESIGN-{NNN}/data-model.md]]
>
> SPEC определяет требования к данным на уровне entities и связанных FR/NFR.
> ER-диаграмма, физические типы, индексы, миграции —
> в `docs/architecture/DESIGN-{NNN}-{slug}/data-model.md`.
```
- Удалить inline-таблицу полностью
d. **Секция 3 "Глоссарий"** (опционально, если в DESIGN-PKG есть glossary.md):
- Установи `glossary_source: "DESIGN-{NNN}/glossary.md"` во frontmatter
- Если в SPEC inline-таблица терминов — оставь как есть (термины
специфичные для SPEC), но добавь заголовок:
`**Источник:** [[DESIGN-{NNN}/glossary.md]] (плюс inline ниже)`
ВАЖНО: эти изменения делает основной агент через Edit tool после
успешного завершения субагента и Quality Review (PASS). Это устраняет
единственный источник дрифта между SPEC и DESIGN.
Не меняй FR / NFR / Open Questions / Traceability — только секции 7.1 / 7.2
и frontmatter `design_package` / `glossary_source`.
8. **Federation glossary в knowledge.json — только если `glossary.md` создан в этом package:**
Цель: распространить ubiquitous language из package на downstream subagents
(`/polisade:tasks`, `/polisade:implement`, `/polisade:spec`), чтобы они использовали те же
термины и не плодили синонимы (Session vs UserSession vs SessionRecord).
a. Прочитай `docs/architecture/DESIGN-{NNN}-{slug}/glossary.md`
b. Извлеки термины. Glossary имеет одну запись на термин со структурой:
`**Term** — definition` (или таблицу с колонками term/definition).
Для каждого термина построй объект:
```json
{
"term": "Session",
"definition": "Authenticated user state, identified by token",
"source": "DESIGN-{NNN}/glossary.md",
"synonyms_to_avoid": [],
"added": "{today}"
}
```
`synonyms_to_avoid` оставляй пустым, если в glossary нет явных запретов
(«НЕ путать с …»). Если есть — извлекай.
c. Прочитай `.state/knowledge.json`. Если поля `glossary` нет (старая схема)
— добавь как пустой массив.
d. Для каждого извлечённого термина:
- Поиск по `knowledge.glossary[].term` (case-insensitive exact match).
- **Не найден** → append новый объект.
- **Найден И definition совпадает** → пропустить (idempotent).
- **Найден И definition отличается** → CONFLICT:
- НЕ перезаписывать запись автоматически.
- Добавь warning в session-log:
```markdown
### Glossary conflict: DESIGN-{NNN}
- Term: "{term}"
- Existing: "{old_definition}" (source: {old_source})
- New: "{new_definition}" (source: DESIGN-{NNN}/glossary.md)
- Action: kept existing, PM should resolve
```
- Включи термин в список конфликтов в Phase 8 report (waiting_pm fragment).
e. Запиши обновлённый `.state/knowledge.json` (2-space indent, stable key order).
f. Логирование в session-log:
```markdown
### Glossary federation: DESIGN-{NNN} → knowledge.json
- Terms added: {N_added}
- Terms updated: 0 (federation никогда не перезаписывает)
- Conflicts: {N_conflicts}
- Source: docs/architecture/DESIGN-{NNN}-{slug}/glossary.md
```
Если в наборе нет `glossary.md` (например, `--skip=glossary` или conditional
trigger не сработал) — этот шаг полностью пропускается.
### Phase 8 — Report to PM
#### При успешном создании (status=ready)
```
═══════════════════════════════════════════
DESIGN PACKAGE СОЗДАН
═══════════════════════════════════════════
ID: DESIGN-001
Source: {PRD-001 | SPEC-001}
Package: docs/architecture/DESIGN-001-{slug}/
Status: ready
АРТЕФАКТЫ ({N} файлов):
✓ README.md (включает Solution Strategy — 5 ключевых решений)
✓ manifest.yaml (machine-readable индекс — для doctor/codex/roadmap review)
✓ c4-context.md — System Context
✓ c4-container.md — 4 containers
✓ sequences.md — 2 flows
✓ data-model.md — 3 entities + dictionary
✓ api.md — 6 OpenAPI endpoints
✓ async-api.md — 3 Kafka channels, 6 events (AsyncAPI 3.0)
✓ glossary.md — 12 terms
✓ quality-scenarios.md — 4 measurable scenarios (Q1-Q4 для NFR-001..NFR-004)
ADR СОЗДАНЫ:
✓ ADR-003: Mermaid over PlantUML
✓ ADR-004: Sessions in Redis vs DB
GLOSSARY FEDERATION (если был glossary.md):
✓ knowledge.glossary: +12 терминов из DESIGN-001/glossary.md
✓ Конфликтов: 0
(downstream subagents tasks/implement/spec теперь видят словарь)
ПРОПУЩЕНЫ:
✗ c4-component.md — single container не требует Level 3
✗ async-api.md — нет message broker / event-driven
✗ state-machines.md — нет lifecycle сущностей
✗ deployment.md — нет явных NFRs
───────────────────────────────────────────
QUALITY REVIEW
───────────────────────────────────────────
Iteration: 1/2
Score: 8.7/10
• Artifact Coverage: 9/10
• Requirement Coverage: 9/10
• Consistency: 9/10
• Depth: 8/10
• Source Alignment: 9/10
• Clarity: 8/10
Вердикт: PASS
───────────────────────────────────────────
───────────────────────────────────────────
СВЕРКА С ВНЕШНИМ ЭТАЛОНОМ (issue #164)
───────────────────────────────────────────
Эталон: {путь | «не передан» — тогда сверки НЕ БЫЛО, и это не «чисто»}
Пары: {эталон-файл ↔ артефакт-файл}, …
Итог: {расхождений нет по сверенным измерениям (имя, тип, format/pattern,
required) | таблица расхождений ЦЕЛИКОМ | «не разобрано: файл:строка»}
| ВАРИАНТ | ПОЛЕ | ОЖИДАНИЕ (эталон) | ТЕКУЩЕЕ (артефакт) | ВЕРДИКТ |
|---|---|---|---|---|
| RESPONSE | parentrequestId | pattern ^[a-f0-9]{32}$, req | поля нет | MISSING |
| RESPONSE | parentRequestId | поля нет | format uuid, req | EXTRA |
DECISION NEEDED (не чинится до ответа PM): {список}
───────────────────────────────────────────
═══════════════════════════════════════════
СЛЕДУЮЩИЙ ШАГ:
→ /polisade:roadmap {SPEC-XXX} — план фаз с учётом дизайна
→ /polisade:tasks {PRD/SPEC-XXX} — создать задачи (subagent учтёт api.md)
→ Открой docs/architecture/DESIGN-001-{slug}/README.md в IDE
═══════════════════════════════════════════
```
#### При улучшении после ревью
```
─────────────────────────────────────────
QUALITY REVIEW
─────────────────────────────────────────
Iteration 1: Score 6.4/10 → IMPROVE
Применено 5 улучшений
Iteration 2: Score 8.4/10 → PASS
─────────────────────────────────────────
```
#### При наличии вопросов (waiting_pm)
```
═══════════════════════════════════════════
DESIGN PACKAGE ТРЕБУЕТ УТОЧНЕНИЙ
═══════════════════════════════════════════
ID: DESIGN-001 (status: draft)
Package: docs/architecture/DESIGN-001-{slug}/
Source: PRD-001
Создан как draft. Вопросы для PM:
1. {Вопрос 1}
2. {Вопрос 2}
═══════════════════════════════════════════
СЛЕДУЮЩИЙ ШАГ:
→ Ответь на вопросы
→ /polisade:unblock для продолжения
═══════════════════════════════════════════
```
## References (per-artifact guides)
Дополнительные гайды загружаются субагентом по нужде, по одному на тип артефакта:
| Reference | Когда читать |
|---|---|
| `references/artifact-catalog.md` | Всегда (компактная таблица всех типов) |
| `references/conditional-triggers.md` | Phase 2 (расширенная таблица триггеров) |
| `references/manifest-schema.md` | Всегда в Phase 5 (subagent создаёт manifest.yaml последним) |
| `references/c4-guide.md` | Если c4_context, c4_container или c4_component в наборе |
| `references/mermaid-sequence.md` | Если sequence в наборе |
| `references/mermaid-er.md` | Если erd в наборе |
| `references/mermaid-state.md` | Если state в наборе |
| `references/mermaid-deployment.md` | Если deployment в наборе |
| `references/openapi-guide.md` | Если openapi в наборе |
| `references/asyncapi-guide.md` | Если asyncapi в наборе |
| `references/adr-guide.md` | Если adr в наборе |
| `references/glossary-guide.md` | Если glossary в наборе |
| `references/quality-scenarios-guide.md` | Если quality_scenarios в наборе |
Это сознательное отступление от Polisade Orchestrator-конвенции одно-файловых скиллов. `/polisade:design` единственный, кто производит 12 разнородных артефактов; модульность references/ даёт progressive disclosure (грузить только нужное).
## Важно
- Субагент работает в чистом контексте — передавай весь нужный контекст в prompt
- Glossary генерируется первым и seeds ubiquitous language для всего package
- Quality Review — холистический (один ревью на весь package), не per-file
- ADR хранятся в `docs/architecture/decisions/` (стандарт MADR), а не внутри package dir
- Sub-артефакты НЕ имеют своих ID; они адресуются путём в package dir
- Только DESIGN-{NNN} и ADR-{N} занимают counters.json
- Парент-артефакт (PRD/SPEC) НЕ меняет статус после генерации дизайна
- Sub-артефакты НЕ имеют поля `status` (наследуется от DESIGN-PKG)
- При conditional analysis: conservatism rule — при сомнении ВКЛЮЧАЙ артефакт
- `architecture.activeADRs` в PROJECT_STATE.json — источник правды о live решениях, обновляется на каждый созданный ADR
- `manifest.yaml` рядом с README.md — machine-readable source of truth о структуре package; PROJECT_STATE.json `package` хранит только pointer на manifest, без дублирования rich-данных
- `knowledge.glossary` в `.state/knowledge.json` — federation назначение для терминов package'а; пополняется в Phase 7 на каждый созданный `glossary.md` и читается downstream-субагентами (`/polisade:tasks`, `/polisade:implement`, `/polisade:spec`) как ubiquitous language project-wide. Конфликты НЕ перезаписывают существующие записи — только сигнализируют через session-log и Phase 8 report