| 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.
Использование
/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
- Распарсь
$ARGUMENTS:
- первый позиционный аргумент:
PRD-XXX или SPEC-XXX (опционально)
--inputs=path1,path2,... — дополнительные context-файлы--only=type1,type2 — whitelist (override conditional logic)--skip=type1,type2 — blacklist
- Прочитай
.state/PROJECT_STATE.json
- 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"
- Если
--inputs указаны: проверь что каждый файл существует и читаем
- Прочитай
.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 будет бесполезен.
- Проверь следующие поля в
.state/knowledge.json:
| Поле | Критичность | Что проверить |
|---|
projectContext.techStack | ОБЯЗАТЕЛЬНО | Не пустой массив |
projectContext.description | ОБЯЗАТЕЛЬНО | Не пустая строка |
projectContext.keyFiles | желательно | Не пустой массив |
projectContext.entryPoints | желательно | Не пустой массив |
patterns | желательно | Не пустой массив |
testing.testCommand | желательно | Не null |
- Если ВСЕ обязательные поля заполнены → покажи краткую сводку и запроси подтверждение:
═══════════════════════════════════════════
ТЕХНИЧЕСКИЙ КОНТЕКСТ (из 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 2update → перейти к интервью (пункт 3 ниже)
-
Если ЛЮБОЕ обязательное поле пусто → провести обязательное интервью:
a. Автодетект — просканируй корень проекта на наличие маркеров стека:
package.json → Node.js/TypeScript (проверь dependencies/devDependencies)tsconfig.json → TypeScript (даже без package.json, напр. Deno)go.mod → Gopyproject.toml / requirements.txt / setup.py → PythonCargo.toml → Rustpom.xml / build.gradle / build.gradle.kts → Java/Kotlinbuild.sbt / .scalafmt.conf → Scala/sbtgradlew / mvnw → JVM wrapper scripts (Gradle/Maven)application.yml / application.properties → Spring Boot*.csproj / *.sln → C# / .NETdocker-compose.yml → infrastructure hints (DB, cache, queue, Kafka).env.example → environment variablesMakefile / Justfile → build/test commandsjest.config.* / vitest.config.* / pytest.ini / .rspec → test frameworkplaywright.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)
- Прочитай input artifact (PRD или SPEC) полностью
- Если parent chain существует (SPEC → PRD), прочитай parent тоже
- Прочитай каждый файл из
--inputs
- Checkpoint: границы системы. Если source artifact (PRD или SPEC) или parent PRD упоминает внешние системы / интеграции → убедись, что информация о смежных системах передаётся в субагент для генерации C4 Context diagram. Если упоминания есть, но раздел «Внешние системы» (6A) отсутствует → зафиксируй Open Question.
- 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 НЕ удаляет его).
- Применить
--only (whitelist полностью переопределяет detection) и --skip (вычитает из detected)
- Если
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 и нужен план фаз
═══════════════════════════════════════════
- 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 3n → exit без измененийedit → показать interactive picker, дать добавить/убрать, повторить confirmation
Phase 3 — Allocate IDs and paths
- Вычисли 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 (любой из двух типов)
— АБОРТ с рекомендацией
python3 {plugin_root}/scripts/polisade_sync.py . --apply --yes.
- Write-guard. Перед созданием директории пакета
docs/architecture/DESIGN-{N}-slug/ проверь, что директория не
существует и что DESIGN-{N} нет в state.artifactIndex. Для каждого
ADR в наборе — аналогично для docs/architecture/decisions/ADR-{Nk}-slug.md. При
коллизии — АБОРТ до любого IO.
- Инкрементируй
DESIGN → DESIGN-NNN
- Если ADR в наборе: для каждого ADR инкрементируй
ADR → ADR-NNN
- Вычисли
slug = kebab-case от title input artifact
- 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 (separate, in docs/architecture/decisions/):
- docs/architecture/decisions/ADR-{N1}-{slug1}.md
- docs/architecture/decisions/ADR-{N2}-{slug2}.md
Phase 4 — Prepare subagent context
Собери в один большой context block:
- Source artifact — полное содержимое PRD или SPEC
- Parent artifact — если SPEC → читать parent PRD; иначе "N/A"
- Extra inputs — concatenated содержимое каждого
--inputs файла
- 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()
- Project knowledge (из
.state/knowledge.json):
projectContext.name, description, techStack, keyFilespatterns (следуй), antiPatterns (избегай)decisions (учитывай существующие ADRs)architecture.activeADRs из PROJECT_STATE — список активных ADRs (не дублируй)
- Relevant references — для каждого артефакта в
needed_artifacts прочитай соответствующий skills/design/references/<type>-guide.md. Не читай гайды для skipped артефактов — это экономит контекст.
skills/design/references/manifest-schema.md — ВСЕГДА (для генерации manifest.yaml)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 (отдельные файлы в docs/architecture/decisions/)
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 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.
Запуск Review субагента
Прочитай:
- Source PRD/SPEC + parent (если есть)
- ВСЕ файлы созданного package (README + все sub-artifacts)
- ВСЕ созданные ADRs
Запусти 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
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}/
РЕКОМЕНДАЦИИ РЕВЬЮ:
{полный ответ review субагента}
ИНСТРУКЦИИ:
1. Прочитай каждый указанный в рекомендациях файл (Read tool)
2. Примени ТОЛЬКО рекомендации из ревью — не добавляй лишнего
3. Сохрани обновлённые файлы (Edit tool)
4. Верни список применённых изменений
Логирование
Добавь запись в .state/session-log.md:
### Quality Review: DESIGN-{NNN} (from {SOURCE-ID})
- Date: {today}
- Iteration 1: {score}/10 → {PASS|IMPROVE}
- Iteration 2: {score}/10 → {PASS|IMPROVE} (если была)
- Files in package: {count}
- ADRs created: {count}
- Command: /polisade:design
Phase 7 — State updates
-
counters.json: инкремент DESIGN (уже сделан в Phase 3); ADR счётчик уже инкрементирован
-
PROJECT_STATE.json artifacts — добавь краткую entry для DESIGN-PKG.
Rich-данные (realizes_requirements, components, scenarios, addresses) НЕ
дублируются здесь — они живут только в manifest.yaml. PROJECT_STATE хранит
только pointer на манифест и плоский список {type, path} для быстрого discovery:
"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} на месте.
- PROJECT_STATE.json — каждый созданный ADR добавь как отдельную запись:
"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": []
}
-
DESIGN-{NNN} → readyToWork
-
architecture.activeADRs — append каждый созданный ADR-{N}.id (это поле сейчас dead, оживляется новым скиллом)
-
Parent (PRD/SPEC) — обнови:
- В
.md файле frontmatter: добавь DESIGN-{NNN} в children:
- В
PROJECT_STATE.artifacts[parent_id].children: добавь DESIGN-{NNN}
- Статус parent НЕ меняй (правило из
/polisade:spec line 504)
-
SPEC dedup — только если parent == SPEC:
Цель: устранить дублирование API/data контента между SPEC и DESIGN-PKG.
После создания DESIGN-PKG в parent SPEC должны остаться только ссылки.
a. Frontmatter parent SPEC — установи поля:
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-блок:
> **См.** [[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-блок:
> **См.** [[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.
-
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).
Для каждого термина построй объект:
{
"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:
e. Запиши обновлённый .state/knowledge.json (2-space indent, stable key order).
f. Логирование в session-log:
### 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
───────────────────────────────────────────
═══════════════════════════════════════════
СЛЕДУЮЩИЙ ШАГ:
→ /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 решениях, обновляется на каждый созданный ADRmanifest.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
