# usecases-skill

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

[pi](https://pi.dev)-pakaĵo, kiu kunigas **du Agent Skills** por administrado de **use cases en la stilo de Cockburn** — `summary` → `user-goal` → `subfunction` — kun registro, malkompono, PlantUML-mapoj kaj OpenSpec-ligilo. La skill skribas use cases en **via** lingvo; identigiloj kaj enumeracioj restas kanonikaj.

![Ekzemplo: malkompona mapo de us-0001 «Manage the library catalog» — du aktoroj, tri user goal, unu subfunction](https://gitverse.ru/api/repos/ars/usecases-skill/raw/branch/main/assets/example.png)

## Kion vi ricevas

Reala `usecase.md`, kiun generas la skill: frontmatter, scope, tabelo de infanoj kaj ligiloj al la koncerna OpenSpec-ŝanĝo. La skill skribas en iu ajn lingvo; la fragmento sube estas **intence** en la rusa, por montri ke la angla ne estas deviga:

```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`
```

Sama dosiero, sama strukturo — ŝanĝiĝas nur la lingvo de la prozo.

## Instalado

```bash
# el npm (post publikigo)
pi install npm:usecases-skill

# el loka checkout
pi install ./usecases-skill
```

Projekta instalo (komuna por la teamo) — aldonu `-l`:

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

## Uzado

La skill ŝarĝiĝas laŭpeto, kiam la tasko kongruas kun ĝia priskribo. Deviga ŝarĝo — per la skill-komando:

```
/skill:usecases
```

Tipaj petoj, kiujn ĝi traktas:

- «Starigu la registron de use cases en la projekto.»
- «Kreu use case de sea-level por <...>.»
- «Malkomponu summary us-0002 en user goals.»
- «Ĝisdatigu la top-level mapon de use cases.»
- «Ligu us-0002.01 al la OpenSpec-ŝanĝo <change>.»

## Kio estas interne

```
usecases-skill/
├── package.json                   ← pi-pakaĵa manifesto
└── skills/
    ├── usecases/                  ← vivociklo kaj enhavo de use case
    │   ├── SKILL.md               ← la skill mem (workflows A–H)
    │   ├── templates/             ← registro, use case (3 niveloj)
    │   ├── references/            ← konvencioj + skribreguloj laŭ Cockburn
    │   └── use-case-guide.md      ← gvido laŭ Cockburn
    └── usecase-map-puml/          ← PlantUML-map-stilo kaj ŝablonoj
        ├── SKILL.md               ← stila gvido por usecase-map.puml
        └── templates/             ← map.top-level, map.decomposition
```

## Konvencioj resume

- **IDs**: `us-NNNN` (summary / top-level user goal), `us-NNNN.NN` (user goal en malkompono), `us-NNNN.NN.NN` (subfunction).
- **Niveloj** (laŭ Cockburn): `summary` → `user-goal` → `subfunction`. Plej multajn postulojn skribu je la nivelo **`user-goal`**.
- **Stokado**: `registry.md` (registro) + `registry/us-NNNN-<kebab>/usecase.md` + `children/` + `usecase-map.puml`.
- **Top-level mapo** montras summary-nivelojn kaj nur tiujn user goals, kiuj **ne** apartenas al iu montrita summary.

Pliaj detaloj: [`skills/usecases/references/conventions.md`](skills/usecases/references/conventions.md).
La metodo de Cockburn mem estas densigita en [`skills/usecases/use-case-guide.md`](skills/usecases/use-case-guide.md).

## Permesilo

MIT