# usecases-skill

<!-- README-I18N:START -->
[English](./README.md) | **Русский** | [Esperanto](./README.eo.md)
<!-- README-I18N:END -->

[pi](https://pi.dev)-пакет, объединяющий **два Agent Skill** для управления **use cases в стиле Коберна** — `summary` → `user-goal` → `subfunction` — с реестром, декомпозицией, PlantUML-картами и связью с OpenSpec. Skill пишет use cases на **вашем** языке; идентификаторы и перечисления остаются в каноническом виде.

![Пример: карта декомпозиции us-0001 «Manage the library catalog» — два актора, три user goal, одна subfunction](https://gitverse.ru/api/repos/ars/usecases-skill/raw/branch/main/assets/example.png)

## Что вы получите

Реальный `usecase.md`, который генерирует skill: frontmatter, scope, таблица детей и ссылки на соответствующую OpenSpec-смену. Skill пишет на любом языке; сниппет ниже — на русском, и это **не случайно** — English не требуется:

```markdown
---
id: us-0002
title: Представить архитектуру TS-проекта в машиночитаемом виде
level: summary
scope: system
primary_actor: Архитектор, Разработчик
status: draft
related_change: generate-module-tree
children: [us-0002.01, us-0002.02]
---

# us-0002 — Представить архитектуру TS-проекта

## Декомпозиция

| ID | Название | Primary actor | Статус |
|---|---|---|---|
| `us-0002.01` | Сгенерировать YAML-описание модулей | Разработчик | MVP |
| `us-0002.02` | Валидировать соответствие кода эталону | Разработчик | backlog |

## Связи
- Смена: `openspec/changes/generate-module-tree/`
- Карта декомпозиции: `./usecase-map.puml`
- Реестр: `../registry.md`
```

Тот же файл, та же структура — меняется только язык прозы.

## Установка

```bash
# из npm (после публикации)
pi install npm:usecases-skill

# из локального чекаута
pi install ./usecases-skill
```

Установка в проект (доступно команде) — добавьте `-l`:

```bash
pi install -l ./usecases-skill
```

## Использование

Skill подгружается по запросу, когда задача совпадает с его описанием. Принудительный запуск — через команду skill:

```
/skill:usecases
```

Типичные запросы, которые он обрабатывает:

- «Настрой реестр use cases в проекте.»
- «Создай use case уровня sea-level для <...>.»
- «Декомпозируй summary us-0002 в user goals.»
- «Обнови top-level карту use cases.»
- «Свяжи us-0002.01 с OpenSpec-изменением <change>.»

## Что внутри

```
usecases-skill/
├── package.json                   ← манифест pi-пакета
└── skills/
    ├── usecases/                  ← жизненный цикл и контент use case
    │   ├── SKILL.md               ← сам skill (workflows A–H)
    │   ├── templates/             ← реестр, use case (3 уровня)
    │   ├── references/            ← конвенции + правила написания по Коберну
    │   └── use-case-guide.md      ← руководство по Коберну
    └── usecase-map-puml/          ← стиль и шаблоны PlantUML-карт
        ├── SKILL.md               ← руководство по стилю usecase-map.puml
        └── templates/             ← map.top-level, map.decomposition
```

## Конвенции кратко

- **IDs**: `us-NNNN` (summary / top-level user goal), `us-NNNN.NN` (user goal в декомпозиции), `us-NNNN.NN.NN` (subfunction).
- **Уровни** (по Коберну): `summary` → `user-goal` → `subfunction`. Большинство требований пишите на уровне **`user-goal`**.
- **Хранение**: `registry.md` (реестр) + `registry/us-NNNN-<kebab>/usecase.md` + `children/` + `usecase-map.puml`.
- **Top-level карта** показывает summaries и только те user goals, которые **не** входят ни в одну из показанных summary.

Подробности: [`skills/usecases/references/conventions.md`](skills/usecases/references/conventions.md).
Сам метод Коберна сжат в [`skills/usecases/use-case-guide.md`](skills/usecases/use-case-guide.md).

## Лицензия

MIT