Product Workflow

Product Workflow

Скилл ведёт продуктовую проработку «end-to-end»: от анализа продуктового пространства до полностью согласованных артефактов. На выходе пользователь получает согласованные пакеты:

1. Продуктовое описание (docs/product/overview.md + docs/product/scenarios/01..N.md) — задача, персоны, проблемы, цели, N сценариев по строгому шаблону.
2. Журнал решений (docs/product/decisions.md) — варианты, факты, trade-offs, рекомендация агента и явный статус решения.
3. Baseline текущих сценариев (docs/product/current-scenario-baseline.md + docs/product/scenario-cards.md + docs/product/scenario-graph.dot) — карта существующих сценариев, компактные пользовательские истории, страницы и переходы, если продукт уже существует или задача является доработкой.
4. Impact-документ инкремента (docs/product/increments/-impact.md) — как новая фича расширяет, меняет или добавляет сценарии относительно baseline.
5. План реализации (docs/plans/-implementation-plan.md) — command-level задачи T0..TN для оркестратора + worker-а.
6. План усиления (docs/plans/-hardening-plan.md) — архитектура / безопасность / поддерживаемость, не добавляющая функционала; задачи H1..HN с зависимостями от T-задач.
7. Независимый вердикт и PDF (docs/product/validation/verdict.md + PDF в ~/Downloads/) — stakeholder-facing продуктовый документ без T/H-планов по умолчанию.

После завершения работы запускается независимый верификатор — отдельный агент, читающий все артефакты и подтверждающий целостность и непротиворечивость. Его отчёт сохраняется в docs/product/validation/verdict.md. Без свежего разрешающего вердикта работа не считается законченной и PDF не собирается, кроме явного запроса пользователя «собери PDF без проверки».

Когда использовать

• Пользователь сказал: «нужно продуктовое описание», «PRD по фиче X», «спроектируй сценарии», «составь план реализации», «hardening plan», «оформи продукт».
• Есть кодовая база и нужно зафиксировать её продуктовое лицо + roadmap.
• Нужно встроить новую фичу или доработку в уже существующий продукт, не создавая сценарный «остров».
• Есть идея/новый продукт без кода — нужно собрать целостную картину сценариев + план.
• Пользователь хочет один артефакт-PDF для шеринга со стейкхолдерами.

Когда не использовать

• Точечный bug-fix или одиночная фича без претензий на продуктовый уровень — это переусложнение.
• Чисто технический proposal без пользовательских сценариев — лучше обычный design doc.
• Готовое описание уже есть и нужен только PDF — выполни напрямую через scripts/build_pdf.sh.

Работа с пользователем

Все prompt-файлы агентов в agents/ пишутся на английском. Язык итоговых артефактов выбирается по пользовательскому контексту: если запрос, существующие документы или целевые артефакты русскоязычные, агенты пишут хороший русский текст; если контекст английский, пишут по-английски. В русском продукте английский допустим только для кода, команд, путей, API, имён библиотек и устойчивых собственных названий. Тон — продуктовый, без воды. Сценарии и планы — иммутабельные после approval (правки только через явный запрос).

Агент помогает принимать решения, но не подменяет пользователя:

• агент собирает факты, варианты, trade-offs, риски, рекомендацию и вопросы;
• человек принимает продуктовые решения согласно своему видению;
• агент может принять решение сам только если пользователь явно делегировал это решение;
• каждое нетривиальное решение фиксируется со статусом proposed, approved_by_human или delegated_to_agent;
• планы реализации строятся только по решениям approved_by_human или delegated_to_agent.

Совместимость с harness-ом (Claude / Codex)

Скилл агностичен к конкретному harness-у:

• Subagent / sub-task — где в инструкциях написано «запусти subagent с промптом из agents/.md», в Claude это Agent(subagent_type="general-purpose", prompt=...), в Codex — соответствующий механизм child-task. Передавай промпт целиком, без обрезки.
• Уточняющие вопросы пользователю — где написано «задать вопросы пользователю», в Claude AskUserQuestion (до 4 вопросов за вызов), в Codex — interactive prompt в чате.
• Параллельные subagent-ы — если фаза разрешает параллелизм (Phase 0 Discovery), в Claude используется один сообщение с несколькими tool-calls; в Codex — последовательно или согласно его модели параллелизма.
• Скрипты (scripts/build_pdf.sh, scripts/verify_artifacts.py) — bash и python, работают одинаково в обоих harness-ах.
• Финальный артефакт — markdown-файлы в репозитории и единый stakeholder-facing PDF в ~/Downloads/. PDF по умолчанию не содержит implementation/hardening планы.

Если harness не поддерживает одну из возможностей (например, нет structured AskUserQuestion) — fallback на простой текстовый вопрос с явным маркером ? и ожиданием ответа в чате.

Codex no-subagent fallback

Если Codex-сессия не даёт реального механизма отдельного subagent / fresh child task, не имитируй независимость.

• Такой проход must be labeled as fallback.
• Такой проход must not be called independent verification.
• Используй self-review / fresh-context checklist только как временный safety net: перечитай артефакты с начала, проверь чек-лист соответствующей фазы, сохрани отчёт с явной пометкой Fallback review, not independent verification.
• Для Phase 5, Phase 8 и PDF gate настоящий независимый verifier остаётся предпочтительным и обязательным, если tool/harness его поддерживает.

Высокоуровневый поток

Скилл ведёт пользователя через 9 фаз. Между фазами — обязательно подтверждение от пользователя через harness-механизм пользовательских вопросов (Claude AskUserQuestion, Codex — interactive prompt) на критических развилках (scope, локация, число сценариев, growth-направления, выбор решения).

[Phase 0] Discovery, scope & decision support
   ↓
[Phase 1] Overview + N scenarios (строгий шаблон)
   ↓ итеративная критика, до «всё хорошо»
[Phase 2] UX continuity (раздел «Дополнительные сценарии и связь с продуктом»)
   ↓ итеративная критика
[Phase 3] Implementation plan (command-level T-tasks)
   ↓ итеративная критика
[Phase 4] Hardening plan (H-tasks — архитектура/безопасность/поддерживаемость)
   ↓ итеративная критика
[Phase 5] Independent artifact verification (отдельный агент, all artifacts)
   ↓ если «нужны правки» — возврат к нужной фазе
[Phase 6] Editorial/style pass (единый русский стиль)
   ↓ если «нужны правки» — вычитка повторяется
[Phase 7] Product PDF assembly (без T/H-планов по умолчанию)
   ↓ если фича реализована
[Phase 8] Post-implementation scenario verification

Подробности и templates — в references/. Промпты для агентов-критиков — в agents/. Скрипты сборки и проверки — в scripts/.

Codex operating modes

Выбирай самый лёгкий режим, который закрывает запрос пользователя. Не запускай полный pipeline только потому, что скилл умеет полный pipeline.

| Mode | Use when | Required output | Gate rule | | --- | --- | --- | --- | | quick-plan | Пользователь просит «напиши план», «сформулируй», planning checkpoint или design-only artifact без реализации | Один repo-local Markdown artifact с evidence, статусом, assumptions и next steps | Phase 0 gate is mandatory only for unresolved product decisions; it does not block quick-plan when the user explicitly asked for a small planning artifact | | baseline-only | Нужно зафиксировать текущие сценарии существующего продукта | current-scenario-baseline.md, scenario-cards.md, scenario-graph.dot | Human gate только при спорных current/growth классификациях | | increment-impact | Нужно встроить фичу/доработку в существующий baseline | pre-scan при неоднозначности + -impact.md | Не переходить к implementation plan без affected Sxx или явного N/A rationale | | full-prd | Нужен полный PRD / продуктовая проработка / stakeholder package | Phase 0..7 по основному потоку | Phase 0 gate is mandatory before scenarios, implementation plan, hardening plan, or PDF | | pdf-package | Артефакты уже есть, нужно только собрать stakeholder PDF | PDF через scripts/build_pdf.sh | Требуется свежий разрешающий verdict, если пользователь явно не попросил bypass | | post-implementation-check | Реализация T/H-плана завершена или нужна release readiness проверка | implementation-verdict.md + реальные команды проверки | Не утверждать готовность при critical/major blockers |

Для quick-plan не создавай overview.md, scenario-файлы, implementation plan или hardening plan, если пользователь не попросил их явно. Такой артефакт должен быть помечен как planning/design-only, если поведение не проверялось тестами или runtime evidence.

Режим baseline

Используй режим baseline, когда продукт уже существует, когда пользователь просит доработку/новую фичу поверх существующего поведения, или когда сценарии должны стать устойчивой опорой для будущих инкрементов.

Цель режима — зафиксировать текущие сценарии и заставить каждую новую фичу объяснять своё место в существующем пользовательском пути.

Минимальные артефакты:

• docs/product/current-scenario-baseline.md — текущие сценарии, страницы/команды/API, входы, выходы, known gaps.
• docs/product/scenario-cards.md — компактные карточки Sxx: user story, happy path, extension points, regression checks, что читать перед планированием.
• docs/product/scenario-graph.dot — явный граф страниц/сценариев и переходов в DOT. DOT — визуальная карта, не единственный источник продуктовой семантики.
• docs/product/increments/-pre-scan.md — быстрый скрининг affected/rejected scenarios перед impact, если зона влияния неочевидна или фича cross-cutting.
• docs/product/increments/-impact.md — только для инкремента: affected scenarios, added/changed flows, обновления FR/AC/Test plan, verification impact.

Правила:

• Новая фича не описывается как отдельный остров. Она должна быть классифицирована как extends, changes, adds, splits, replaces или deprecates относительно baseline.
• Если фича добавляет новый сценарий, impact-документ обязан указать вход из существующего сценария и возврат/следующий шаг.
• Если фича меняет существующий сценарий, нужно перечислить конкретные scenario cards, extension points, happy-path steps, regression checks и FR/AC/Test plan, которые меняются.
• Перед планированием инкремента агент обязан открыть scenario-cards.md, найти affected Sxx и прочитать только их карточки плюс referenced evidence.
• Если affected Sxx неясны, фича меняет широкую пользовательскую область или может затронуть cross-cutting areas, сначала создать docs/product/increments/-pre-scan.md, а не писать impact или план реализации. Cross-cutting areas: auth/session/legal, search/recall/navigation, settings/preferences/privacy, operator/admin/runtime. Для каждой области укажи Baseline scenario = Sxx или N/A с rationale.
• Pre-scan обязан перечислить candidate affected scenarios, rejected scenarios с rationale, cross-cutting checklist, evidence opened и open decisions.
• DOT фиксирует явные связи страниц/сценариев и, при необходимости, шаги продуктового инкремента через edge labels вроде increment: .
• Для нового продукта без существующего поведения baseline создаётся после Phase 1 как первичная карта current/growth-сценариев; impact-документ не нужен, пока нет инкремента.
• Для доработки существующего продукта baseline — preflight перед Phase 1/3: сначала найти или создать карту текущих сценариев, затем проектировать изменение.

Шаблоны: [references/baseline-template.md](references/baseline-template.md), [references/scenario-card-template.md](references/scenario-card-template.md), [references/impact-pre-scan-template.md](references/impact-pre-scan-template.md) и [references/increment-impact-template.md](references/increment-impact-template.md).

Phase gates

| Фаза | Вход | Выход | Machine check | Human gate | | --- | --- | --- | --- | --- | | 0 | запрос пользователя + repo/идея | scope summary + docs/product/decisions.md | evidence paths в explorer-отчётах | подтверждение scope и решений | | 1 | approved/delegated scope | overview + сценарии | scripts/verify_artifacts.py --phase scenarios | подтверждение сценариев | | baseline | существующий продукт или approved сценарии | current-scenario-baseline.md + scenario-cards.md + scenario-graph.dot + optional increment impact | --phase baseline; для инкремента также --phase pre-scan и --phase impact; semantic связность проверяют scenario-critic + independent-verifier | подтверждение только при спорном impact | | 2 | сценарии Phase 1 | UX continuity во всех сценариях | --phase scenarios + scenario-critic | только при смысловых развилках | | 3 | approved сценарии | implementation plan + gap.yaml | --phase plan | подтверждение известных пробелов | | 4 | implementation plan | hardening plan | --phase hardening | подтверждение backlog/probes вне scope | | 5 | product + plans | docs/product/validation/verdict.md | --phase validation | блокер, если есть critical/major | | 6 | свежий verdict | вычитанные product docs | style-editor report + повторный verifier | утверждение тона при спорных правках | | 7 | вычитанные docs | PDF в ~/Downloads/ | build_pdf.sh с validation gate | визуальная проверка PDF | | 8 | выполненный T/H-план | implementation readiness verdict | implementation-verifier + реальные tests | решение о готовности релиза |

Mandatory Phase 0 user gate

Перед созданием overview.md, файлов сценариев, implementation plan или hardening plan остановись и запроси у пользователя подтверждение Phase 0 scope.

Сообщение с запросом подтверждения должно содержать:

1. Краткую discovery-сводку: что уже известно, какие evidence paths найдены, какие unknowns остаются.
2. Нумерованный список решений, на которые пользователь должен ответить.
3. Для каждого решения: варианты, помеченную Рекомендация, rationale/evidence и impact выбора.
4. Финальный явный вопрос с маркером ?.

Не переходи к Phase 1, пока пользователь не ответил или явно не делегировал агенту все решения.

Обязательные вопросы Phase 0:

• Локация артефактов.
• Число сценариев.
• Соотношение current vs growth.
• Persona-список.
• Нужен ли режим baseline: продукт уже существует / это инкремент / это новый продукт без baseline.
• Любая продуктовая развилка scope, найденная во время discovery.

Если structured-механизм пользовательских вопросов недоступен, задай эти вопросы обычным Markdown-сообщением в чате и дождись ответа. Не продолжай работу в том же ходе после вопроса.

Phase 0 — Discovery, scope & decision support

Цель: понять продуктовое пространство, собрать факты для решений и зафиксировать scope без самовольного выбора продуктового направления.

1. Если есть кодовая база — запусти 2-3 параллельных Explore агентов:

• UI / пользовательские поверхности: [agents/explore-ui.md](agents/explore-ui.md).
• API / контракты: [agents/explore-api.md](agents/explore-api.md).
• Runtime / верификация: [agents/explore-runtime.md](agents/explore-runtime.md).

Результаты идут в docs/product/discovery/ или в рабочий контекст фазы: evidence paths, confidence, unknowns, risk notes.

1. Через AskUserQuestion уточни:

• Локация артефактов (рекомендация: docs/product/, docs/plans/).
• Число сценариев: 5-7 (компактный продукт), 8-12 (типичный), 13+ (большой).
• Соотношение current vs growth: сколько сценариев описывают текущую функциональность, сколько — точки роста.
• Persona-список: кто целевая аудитория (developer / agent / QA / PM / support / other).

1. Создай или обнови docs/product/decisions.md по шаблону [references/decision-log-template.md](references/decision-log-template.md).
2. По каждой смысловой развилке покажи человеку варианты, evidence, trade-offs, recommendation и impact. Не выбирай молча.
3. Запиши scope-сводку (одним сообщением пользователю, перед стартом Phase 1) и дождись подтверждения.

Если задача является инкрементом существующего продукта, не переходи к планированию реализации, пока не с

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ehlyzov
• Source: ehlyzov/skills
• License: MIT

Install and usage instructions live in the source repository linked above.