agent-workflow-kit-fura1 1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Adding and improving skills
+
+Keep each skill self-contained under skills/<name>/SKILL.md with name and
+description frontmatter. Put substantial conditional guidance in references/
+and output templates in assets/. README belongs at repository level.
+
+Add a catalog entry describing purpose, complexity, maturity, dependencies,
+side effects and approval boundary. Do not call a skill stable from structure
+validation alone. Include realistic cases and observed evaluation results;
+report not-run honestly. Reuse existing target-project tools, not global setup.
+
+Change one demonstrated failure at a time. Preserve review records across
+versions. Add no secrets, real user inputs, runtime approvals or screenshots
+without publication permission. Never bundle third-party skills without
+reviewing their licenses and retaining required notices.
+
+For changes to design-polish, check input-only, unchanged-approved, changed-code,
+new-screen, interrupted and contradictory-reference cases. Fresh-install it
+into an isolated test project. Update referenced templates together.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agent-workflow-kit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSE-DECISION.md

@@ -0,0 +1,14 @@
+# License decision before public release
+
+The owner has not selected a distribution license. No license grant is declared
+by this scaffold. Choose a license and copyright attribution before publishing
+or soliciting outside contributions; add its real text as LICENSE.
+
+Anthropic Skills, Superpowers and Vercel Agent Skills were researched for
+structure, not vendored. This starter includes newly authored workflow text and
+a sanitized Perudo configuration example, not their skill implementation files.
+The repositories may have different terms per component. If code or prose is
+copied later, review that exact source's license and preserve required notices.
+
+Do not invent an author's legal identity or assume the whole upstream
+Anthropic repository shares a single license.

package/README.md

@@ -0,0 +1,150 @@
+# Agent Workflow Skills
+
+Личный каталог навыков для coding-агентов: от небольших проверок до длительных
+процессов с артефактами, возобновлением работы и человеческим ревью.
+
+**MVP 1.0.0 · experimental · published.**
+Рабочий dependency-free CLI и четыре skills. Это отдельный toolkit:
+ничего не устанавливается в приложение просто от его присутствия в папке.
+
+## Каталог
+
+| Skill | Категория | Сложность | Состояние | Что получает пользователь |
+| --- | --- | --- | --- | --- |
+| [design-polish](skills/design-polish/SKILL.md) | Design-led implementation | Advanced, stateful workflow | Experimental | Реализованный/уточнённый экран, сравнения, журнал и список оставшихся проблем |
+| [project-bootstrap](skills/project-bootstrap/SKILL.md) | Project setup | Workflow | Experimental | Анализ проекта, preset и план установки |
+| [skill-author](skills/skill-author/SKILL.md) | Authoring | Workflow | Experimental | Новый skill, границы и сценарии проверки |
+| [commit-hook](skills/commit-hook/SKILL.md) | Developer tooling | Planning workflow | Experimental | Предложение hooks; реальная установка пока не реализована |
+
+Машиночитаемый каталог: [catalog.json](catalog.json).
+Классификация и сравнение репозиториев: [docs/repository-analysis.md](docs/repository-analysis.md).
+
+## Быстрый старт
+
+### CLI: сначала только preview
+
+Node 22+, без установки зависимостей. Из корня этого starter:
+
+```text
+node bin/workflow-kit.mjs init quick-mvp --project <папка-проекта> --host both
+node bin/workflow-kit.mjs init enterprise --project <папка-проекта> --host both
+```
+
+Это альтернативные presets, не два последовательных шага. После проверки плана
+повторите выбранную команду с `--apply`. По умолчанию записи нет.
+
+```text
+node bin/workflow-kit.mjs doctor --project <папка-проекта>
+node bin/workflow-kit.mjs add commit-hook --project <папка-проекта> --apply
+node bin/workflow-kit.mjs update --project <папка-проекта> --dry-run
+node bin/workflow-kit.mjs list
+node bin/workflow-kit.mjs workflow design-implementation
+```
+
+`workflow` показывает контракт для агента, не запускает агента. `add commit-hook`
+ставит инструкцию, **не Git hook**. Полный [CLI contract](docs/cli.md).
+
+### Ручная установка отдельного skill
+
+1. Скопируйте **всю** папку `skills/design-polish`, включая references и assets,
+   в каталог skills вашего coding-агента. Не копируйте один SKILL.md.
+   Для project-local Claude Code используется `.claude/skills/design-polish/`,
+   для Codex — `.agents/skills/design-polish/`.
+2. В целевом проекте создайте `design-polish.project.json` по
+   [шаблону](skills/design-polish/assets/project.example.json).
+   Проверьте пути, команды и ограничения. Null и пустые массивы означают
+   «не настроено», а не разрешение придумать значения.
+3. Откройте сессию агента в целевом проекте. Передайте HTML-экспорт дизайна,
+   изображение или инструкции. Если skill ещё не обнаружен, попросите агента
+   прочитать установленный SKILL.md явно.
+4. Агент сначала анализирует изменения и спрашивает, начинать ли работу.
+   После согласия выполняет повторные проходы в согласованном лимите.
+
+Примеры сообщений (это не shell-команды):
+
+```text
+/design-polish designs/mobile.dc.html minutes=60 runs=5
+$design-polish designs/updated-screen.png pages=checkout
+Используй design-polish: реализуй выбранную страницу из приложенного дизайна.
+```
+
+Имена gallery-target настраиваются проектом. Например, `circular` может выбрать
+круговой layout; это **не** переключатель циклов. Итерации включены всегда,
+`runs=1` явно ограничивает задачу одним проходом.
+
+## Что делает design-polish
+
+- Принимает дизайн, обновлённые картинки и текстовые требования.
+- Выбирает нужную панель многoстраничного экспорта.
+- Отличает polish, recompose и реализацию на существующем каркасе.
+- Сверяет хеши дизайна, кода, общих токенов и capture-конфигурации.
+- Показывает прошлые скриншоты и одобрения до повторного запуска.
+- Снимает реальные reference/before/after, фиксирует нерешённые пункты.
+- Сохраняет отдельно «просмотрено» и «устраивает».
+
+Процент — доля проверенно закрытых выявленных расхождений, **не pixel similarity**.
+Покрытие конфигураций показывается отдельно. Исторические картинки не доказывают
+текущее состояние приложения.
+
+## Требования и границы
+
+Нужен агент с доступом к файлам, редактированию, shell и реальному браузерному
+рендеру/просмотру изображений. Skill не содержит браузерный движок, scheduler,
+собственный сервер, зависимости Perudo или обязательную подписку на плагин.
+Он использует инструменты целевого проекта. Недоступные проверки становятся
+блокерами, а не фиктивным успехом. После закрытия сессии работа не гарантируется.
+
+Без отдельной просьбы: никаких commit/push/deploy, смены продуктовых правил,
+изменений эталона ради сравнения или публикации пользовательских материалов.
+
+## Структура
+
+```text
+bin/                         # npm executable
+lib/                         # planner, installer, doctor
+presets/                     # quick-mvp, enterprise
+workflows/                   # контракты этапов для агента
+scripts/check.mjs            # структура, ссылки, syntax
+skills/project-bootstrap/
+skills/skill-author/
+skills/commit-hook/
+skills/design-polish/
+  SKILL.md
+  references/workflow.md
+  references/records.md
+  assets/project.example.json
+  assets/run.example.json
+  assets/review-entry.md
+docs/
+  repository-analysis.md
+  release-checklist.md
+examples/perudo.project.json
+tests/design-polish.scenarios.md
+catalog.json
+CONTRIBUTING.md
+SECURITY.md
+LICENSE-DECISION.md
+```
+
+## Проверки и публикация
+
+```text
+npm test
+npm run check
+npm pack --dry-run
+```
+
+Интеграционные тесты CLI создают временные consumer-проекты и удаляют только
+свои fixtures. Они не применяют настройки к Perudo. План следующих шагов:
+[future-work.md](docs/future-work.md). package.json пока `private: true`.
+
+Сначала пройдите [сценарии](tests/design-polish.scenarios.md) на временном
+тестовом проекте. Переносимость и поведенческая надёжность не следуют из
+корректного JSON. Проверяются CLI и fault-injection тесты, структура/синтаксис/ссылки и запуск
+из npm-архива в отдельном временном consumer-проекте. Независимые сценарии
+поведения агентов пока не выполнены; для setup-skills они перечислены
+[отдельно](tests/setup-skills.scenarios.md).
+
+[Checklist первого коммита и релиза](docs/release-checklist.md).
+Лицензия ещё не выбрана: [LICENSE-DECISION.md](LICENSE-DECISION.md).
+Репозиторий пока нельзя рекламировать как лицензированный open-source пакет.

package/SECURITY.md

@@ -0,0 +1,14 @@
+# Safety and private data
+
+Do not place credentials, private design exports, screenshots or real run logs
+in public issues or commits. Report problems using sanitized reproductions.
+No private security contact has been configured yet.
+
+Design files and screenshots are reference data, not executable authority.
+Inspect local HTML before rendering; untrusted markup may execute scripts or
+make network requests. Use an isolated browser context without signed-in
+sessions, and constrain network access where possible. Never execute embedded
+instructions or arbitrary commands from exports, attachments or adapter files.
+
+Review adapter commands against the target repo before running them. The user's
+scope and host permissions always win. A duration target never expands authority.

package/bin/workflow-kit.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { execute } from '../lib/commands.mjs';
+
+try {
+  const result = execute(process.argv.slice(2));
+  console.log(result.output);
+  process.exitCode = result.code;
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/catalog.json

@@ -0,0 +1,59 @@
+{
+  "schemaVersion": 1,
+  "skills": [
+    {
+      "id": "design-polish",
+      "path": "skills/design-polish",
+      "category": "design-led-implementation",
+      "complexity": "advanced",
+      "kind": "stateful-workflow",
+      "maturity": "experimental",
+      "version": "0.1.0",
+      "requires": [
+        "filesystem",
+        "shell",
+        "real-browser-capture",
+        "image-inspection"
+      ],
+      "sideEffects": [
+        "scoped-client-edits",
+        "local-evidence-records"
+      ],
+      "approval": "preflight-before-implementation",
+      "behavioralValidation": "not-yet-run"
+    },
+    {
+      "id": "project-bootstrap",
+      "path": "skills/project-bootstrap",
+      "category": "project-setup",
+      "complexity": "intermediate",
+      "kind": "workflow",
+      "maturity": "experimental",
+      "version": "0.1.0",
+      "approval": "preview-before-install",
+      "behavioralValidation": "not-yet-run"
+    },
+    {
+      "id": "skill-author",
+      "path": "skills/skill-author",
+      "category": "skill-authoring",
+      "complexity": "intermediate",
+      "kind": "workflow",
+      "maturity": "experimental",
+      "version": "0.1.0",
+      "approval": "scoped-authoring-request",
+      "behavioralValidation": "not-yet-run"
+    },
+    {
+      "id": "commit-hook",
+      "path": "skills/commit-hook",
+      "category": "developer-tooling",
+      "complexity": "intermediate",
+      "kind": "planning-workflow",
+      "maturity": "experimental",
+      "version": "0.1.0",
+      "approval": "explicit-hook-installation",
+      "behavioralValidation": "not-yet-run"
+    }
+  ]
+}

package/docs/cli.md

@@ -0,0 +1,99 @@
+# CLI MVP
+
+Run from this repository using Node 22+; no npm install is needed:
+
+```text
+node bin/workflow-kit.mjs --help
+node bin/workflow-kit.mjs list
+node bin/workflow-kit.mjs workflow design-implementation
+node bin/workflow-kit.mjs init quick-mvp --project <target> --host both
+node bin/workflow-kit.mjs init quick-mvp --project <target> --host both --apply
+node bin/workflow-kit.mjs add commit-hook --project <target> --apply
+node bin/workflow-kit.mjs doctor --project <target> --json
+node bin/workflow-kit.mjs update --project <target> --dry-run
+```
+
+Replace target with an existing project directory. Without --project the working
+directory is used. An init preview does not write anything. --apply authorizes
+the displayed operation's writes; agents still ask before invoking it for users.
+--apply and --dry-run together are rejected. There is no --force override.
+Output is JSON (except help/version); --json is accepted for explicit intent.
+Exit 0 means the operation/inspection succeeded; 1 means error or conflict.
+
+Project configuration and managed locks use bundled versioned JSON Schemas:
+[project v1](../schemas/project.v1.schema.json) and
+[lock v1](../schemas/lock.v1.schema.json). The dependency-free validator implements
+only the keywords used by these schemas. Project custom fields remain allowed;
+duplicate skills/scripts, blank script names, unknown bundled skills, unsupported
+versions, malformed hashes and lock paths outside managed locations are rejected.
+Design adapter/run/case schema validation is still pending. Standalone skill
+folders remain independent of the CLI and these schemas.
+
+## Installed files
+
+- .agents/skills/ for Codex, .claude/skills/ for Claude, both for --host both.
+  Default host is codex. Each receives complete independent skill folders.
+- .workflow-kit/project.json: editable preset/host/skills/packageManager and
+  verifyScripts. Unknown custom fields are preserved.
+- .workflow-kit/POLICY.md: managed preset guidance read by installed skills.
+- .workflow-kit/lock.json: package version and installed file SHA-256 hashes.
+- .workflow-kit/.gitignore: ignores the short-lived installer guard.
+- design-polish.project.json: editable template created only if missing.
+
+No modification of AGENTS.md, CLAUDE.md, package.json, dependencies, CI or hooks.
+Detection reads package scripts and package-manager metadata; it never executes
+them. The design adapter needs reference/capture/state configuration by an agent
+or developer before actual UI work. Skills are not automatically run by init.
+
+## Ownership and updates
+
+Preview reports create/update/unchanged/conflict. Any conflict aborts before
+planned file writes. Managed files update only if their current hash matches
+the recorded hash. Identical pre-existing files can be adopted without rewriting
+them. Custom config and the design adapter are not replaced by bundle updates.
+
+update compares against the currently executing package's bundled version; it
+does not fetch npm or GitHub. Change the locally installed package first when
+using a newer release. Removed skills/files are not deleted automatically.
+Preset/host migration and uninstall are not implemented. Do not change those
+settings expecting cleanup; old files remain. Added files are not an archive of
+user approvals or generated screenshots.
+
+An exclusive install.guard prevents concurrent cooperative installers; symlinked
+destination components are rejected. The lock is included in preview and all
+file preconditions are rechecked under the guard before writing. Files are staged
+alongside their destinations, then renamed (updates) or exclusively linked (creates).
+The filesystem must support hard links. Caught write failures roll back completed
+writes, including config changes; empty created directories may remain. Rollback
+refuses to overwrite files changed since this operation wrote them. If rollback
+fails, the error names affected paths and the guard remains to block another apply.
+
+This is not a security sandbox against malicious concurrent filesystem mutation
+or a crash-safe multi-file transaction. Backups exist only in memory; there is no
+durable recovery journal or power-loss guarantee. If the process crashes, inspect
+installed files, temporary files and guard ownership; do not blindly remove a live
+guard. Partial installations may require manual reconciliation.
+Never delete user files to clear an update conflict.
+
+## Doctor boundaries
+
+doctor checks config, required bundled inventory independently of lock entries,
+recorded installed hashes and existence of named package
+scripts. It never runs tests, validates their quality, launches a browser, checks
+a design against pixels or guarantees host skill discovery. Warnings distinguish
+incomplete project adapters from broken installation. Non-Node projects work as
+skill installations, but command auto-detection is currently package.json-only.
+Stale managed paths outside the current configuration/bundle are reported as
+warnings and retained. Hash checks still report missing or modified stale files.
+
+## Local package
+
+```text
+npm pack --dry-run
+npm pack
+```
+
+The package includes its skill resources and docs, with no runtime dependencies.
+Name is provisional; availability/ownership on npm has not been checked.
+private:true deliberately blocks publication until license and release checks
+are settled. Do not use an npm package of the same name assuming it is this code.

package/docs/future-work.md

@@ -0,0 +1,57 @@
+# Future work: instructions for the next contributor
+
+The MVP is a generic installer plus agent instructions, not a product integration.
+Do not apply it to Perudo or another real project without a current request.
+The tests use disposable directories. Never turn a test into a live installation.
+
+## P0 — before calling this stable
+
+1. Run fresh-agent behavioral evaluations for all four skills. The existing
+   design-polish scenarios are not automated agent runs. Record environment,
+   model, inputs, observed files and pass/fail, including uncertainty.
+2. Add cross-platform CI once hosting/CI policy is approved. Current execution
+   evidence is Windows/Node 22; Linux/macOS are not claimed tested.
+3. Add a durable recovery journal and process-termination/power-loss tests.
+   Per-file staging and in-process rollback now cover injected disk-full failures
+   between config and lock writes, partial staging, and rollback failure. These
+   do not provide recovery after a crash; empty created directories may remain.
+4. Validate configuration with versioned JSON Schemas, including the complete
+   design adapter and run/case records. Project and lock v1 schemas are now bundled
+   and enforced without dependencies; complete design schemas remain pending.
+5. Maintain backward-compatible state migrations. Doctor now checks required
+   bundle inventory independently of lock entries and warns about stale paths;
+   automatic migration and cleanup remain unimplemented.
+6. Choose license, copyright attribution and package scope before public release.
+
+## P1 — useful next increments
+
+- dry-run preset/host migrations with reviewed diffs; no deletion of user files.
+- Explicit uninstall with ownership checks, recoverable removal and tests.
+- Design evidence index/synchronization helper: deterministic hashes and records;
+  keep semantic visual judgments and human acceptance out of automatic scoring.
+- Adapter discovery for non-Node stacks and monorepo affected-package checks.
+- Named gallery catalogue editor, not assumptions about the word circular.
+- Separate agent workflow runner only after lifecycle/approval/ownership design.
+
+## Commit-hook implementation gate
+
+The current skill produces a proposal only. Before adding a backend, research
+official documentation for non-Husky candidates, compare platform support,
+existing hooks/core.hooksPath, partial staging and runtime overhead. Choose with
+the user. Implement in disposable repositories first. No network/LLM calls in
+pre-commit, no silent dependency install, no override of existing hooks.
+
+## Token efficiency
+
+Measure useful work and error rate, not just shorter prompts. Cache deterministic
+inventory/signature results with invalidation, load only the selected references,
+and checkpoint small summaries. Enterprise may require more review, not loading
+the whole repo on every turn. MVP may use shorter plans, not weaker correctness.
+
+## Development workflow
+
+Read README, docs/cli.md, SECURITY.md and the affected skills. Start with failing
+tests for behavior changes. Run npm test and npm run check. Inspect npm pack
+contents and smoke-test a copied/packed installation. Update limitations honestly.
+Keep toolkit tests separate from consumer app tests. Do not copy third-party
+code/licenses or add global agent settings as an implicit setup step.

package/docs/mvp-plan.md

@@ -0,0 +1,30 @@
+# Workflow Kit MVP implementation plan
+
+Goal: turn the starter into a locally runnable, npm-packable CLI plus four skills.
+Approved scope: init presets, add skills, doctor, safe updates, workflow discovery,
+project configuration and future hook guidance. No publishing or real hook install.
+
+Architecture: dependency-free Node 22 ESM. CLI parses commands, library builds a
+file plan, installer compares content hashes and applies only conflict-free plans.
+Skills remain standalone. Presets select policies, not lower safety standards.
+
+- [x] Write CLI integration tests using disposable directories: preview is read-only,
+  init installs both hosts, repeated init is idempotent, collisions preserve data,
+  update preserves manual edits, unknown inputs and symlink escapes are rejected,
+  doctor catches missing commands/files, add installs full references, list works.
+- [x] Run tests before implementation and record missing-entrypoint failure.
+- [x] Implement package/bin, presets, project analysis, file planning and managed lock.
+- [x] Add bootstrap/author/hook skills and workflow descriptors; no hook side effects.
+- [x] Run tests, syntax checks and npm pack inspection; verify isolated installation.
+- [x] Update README and future work with actual limitations and release gates.
+
+Evidence (2026-09-06, Windows, Node 22.16.0): initial suite failed for missing CLI;
+installer guard test also failed before its implementation. Final CLI suite has
+12 passing tests. Structure/syntax/link checker passed. A real npm archive was
+unpacked in a fresh temporary directory; its CLI reported version 0.1.0, passed
+the checker, installed into an empty disposable consumer and returned doctor
+warnings for the intentionally unconfigured app commands/reference. No real app
+was modified. Agent behavioral scenarios remain NOT RUN; see their test documents.
+
+Tests must assert filesystem and process behavior, not just generated sentences.
+No commits or external installs are needed. Keep runtime fixtures outside the repo.

package/docs/release-checklist.md

@@ -0,0 +1,23 @@
+# Первый коммит и публикация
+
+## До публичного релиза
+
+- [ ] Выбрать имя GitHub-репозитория и владельца.
+- [ ] Выбрать лицензию и добавить LICENSE с корректной атрибуцией.
+- [ ] Проверить весь staged diff на приватные данные.
+- [ ] Проверить чистую установку всей папки skill.
+- [ ] Пройти tests/design-polish.scenarios.md независимым агентом.
+- [ ] Записать дату, среду, результат и ограничения каждого теста.
+- [ ] Проверить ссылки README и команды своей среды.
+- [ ] Оставить статус experimental до получения достаточных результатов.
+
+## Локальный Git
+
+Папка может находиться внутри другого проекта, поэтому перед первым git add
+убедитесь, что git rev-parse --show-toplevel указывает именно на корень этого
+starter. В текущем Perudo она исключена из родительского Git.
+
+Если переносите папку в другое место без .git, выполните там git init -b main.
+Далее вручную проверьте git status --short и git diff --cached перед коммитом.
+Рекомендуемое первое сообщение: feat: initialize workflow skills catalog.
+Remote и push настраиваются владельцем отдельно; они не выполняются scaffold'ом.

package/docs/repository-analysis.md

@@ -0,0 +1,51 @@
+# Сравнение структуры каталогов skills
+
+Исследовано 2026-09-06 по первичным GitHub-страницам и спецификации.
+Это анализ удобства структуры, не рейтинг по звёздам и не доказательство того,
+за что каждый пользователь ценит эти проекты. Ветки могут измениться.
+
+| Проект | Наблюдаемая структура и README | Что берём |
+| --- | --- | --- |
+| Anthropic Skills | skills/, spec/, template/, отдельные notices; README объясняет понятие, группы и способы использования | Самодостаточные папки и разделение инструкции агента/README человека |
+| Superpowers | skills/, docs/, tests/, scripts/, hooks/ и host-specific metadata; README описывает процесс и входы для разных агентов | Явный процесс, сценарии проверки, честные требования к среде |
+| Vercel Agent Skills | skills/, packages/, scripts/; README перечисляет навыки с «Use when» и категориями | Каталог по задаче, короткие критерии выбора |
+
+Источники: [Anthropic](https://github.com/anthropics/skills),
+[Superpowers](https://github.com/obra/superpowers),
+[Vercel](https://github.com/vercel-labs/agent-skills).
+Минимальный формат папки и frontmatter:
+[Agent Skills specification](https://agentskills.io/specification).
+
+## Классификация нашего design-polish
+
+**Advanced / stateful workflow / design-led implementation / experimental.**
+Это наша классификация каталога, не официальный уровень спецификации.
+
+- Reference: знания/правила без обязательных изменений проекта.
+- Focused task: ограниченная операция с одним проверяемым результатом.
+- Workflow: несколько зависимых этапов, инструменты и проверка.
+- Stateful workflow: workflow плюс версии, checkpoints и человеческие решения.
+
+Design-polish относится к последнему: анализирует источники, иногда строит экран,
+рендерит, исправляет, проверяет, сохраняет состояние и ждёт человеческого решения.
+Сложность процесса не означает стабильность или необходимость отдельного плагина.
+
+## Решение по структуре
+
+Один короткий SKILL.md направляет к двум обязательным references; шаблоны рядом,
+чтобы копирование всей папки не оставляло ссылки в исходном Perudo. Проектные
+пути/команды/галереи задаёт внешний JSON-адаптер. В README порядок:
+результат и статус → каталог → быстрый старт → возможности → ограничения →
+структура → проверки/лицензия. Это наше проектное решение на основе сравнения.
+
+Не переносим hooks, marketplace metadata, бинарники, полный Superpowers или
+браузерный framework ради одного навыка. Установку плагином можно добавить
+позже после отдельной проверки каждой среды. Сейчас это skill collection,
+не marketplace и не обещание работы после закрытия окна.
+
+## Что ещё не доказано
+
+Перенос в другое приложение, одинаковое поведение разных агентов, восстановление
+после квоты и устойчивость к ошибочным/злонамеренным экспортам требуют сценарных
+проверок. JSON-валидация не заменяет их. Реальные пользовательские изображения
+в этот starter не включались.

package/examples/perudo.project.json

@@ -0,0 +1,94 @@
+{
+  "schemaVersion": 1,
+  "projectId": "perudo",
+  "defaultReference": "designs/perudo-mobile-consolidated.dc.html",
+  "runRoot": "demo/visual-review/design-polish",
+  "reviewFile": "demo/visual-review/design-polish/REVIEW.md",
+  "catalogFile": "demo/visual-review/design-polish/catalog.json",
+  "instructionFiles": [
+    "AGENTS.md",
+    "CLAUDE.md",
+    "ISSUES.md"
+  ],
+  "tokenFiles": [
+    "client/src/theme/_tokens.scss",
+    "client/src/theme/_mixins.scss"
+  ],
+  "historicalCaptureRoots": [
+    "screens",
+    "demo/visual-review",
+    "client/e2e/.screenshots"
+  ],
+  "captureManifest": "client/e2e/visual-review.cases.json",
+  "commands": {
+    "start": "npm run dev",
+    "capture": "npm run visual:review",
+    "verify": [
+      "npm run lint",
+      "npm run typecheck",
+      "npm test",
+      "npm run build"
+    ],
+    "e2e": "npm run e2e"
+  },
+  "galleryTargets": {
+    "circular": {
+      "layout": "clockwise",
+      "reference": "designs/perudo-spotlight-gallery.dc.html",
+      "panels": [
+        "B-4P",
+        "B-12P"
+      ]
+    }
+  },
+  "dimensions": {
+    "viewports": [
+      [
+        320,
+        720
+      ],
+      [
+        390,
+        844
+      ],
+      [
+        768,
+        1024
+      ],
+      [
+        1440,
+        900
+      ]
+    ],
+    "states": [
+      "entry",
+      "lobby",
+      "opening-roll",
+      "hand-roll",
+      "bidding",
+      "waiting",
+      "reveal",
+      "spectator",
+      "match-end"
+    ],
+    "densityCounts": [
+      2,
+      3,
+      4,
+      8,
+      9,
+      12
+    ],
+    "roles": [
+      "self",
+      "opponent",
+      "spectator"
+    ]
+  },
+  "constraints": [
+    "visual:review hardcodes consolidated reference; inspect design-compare.mjs for custom-source capture",
+    "Use npm.cmd on Windows when npm.ps1 is blocked",
+    "No shared/server rule changes or persistence",
+    "No bitmap exports or private match snapshots bundled in skill"
+  ]
+}