usecases-skill

English | Русский | Esperanto

A pi package that bundles two Agent Skills for managing Cockburn-style use cases — summary → user-goal → subfunction — with a registry, decomposition, PlantUML maps, and OpenSpec linkage. The skill writes use cases in your language; identifiers and enums stay canonical.

What you get

A real usecase.md produced by the skill — frontmatter, scope, children table, and links to the matching OpenSpec change. The skill writes in any language; the snippet below is in Russian on purpose, to show that English is not required:

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

Same file, same structure — only the prose language changes.

Install

# from npm (once published)
pi install npm:usecases-skill

# from a local checkout
pi install ./usecases-skill

Project-scoped install (shared with the team) — add -l:

pi install -l ./usecases-skill

Use

The skill loads on demand when the task matches its description. Force it with a skill command:

/skill:usecases

Typical requests it handles:

• "Set up the use cases registry in the project."
• "Create a sea-level use case for <...>."
• "Decompose summary us-0002 into user goals."
• "Update the top-level use cases map."
• "Link us-0002.01 to the OpenSpec change ."

What's inside

usecases-skill/
├── package.json                   ← pi package manifest
└── skills/
    ├── usecases/                  ← use case lifecycle and content
    │   ├── SKILL.md               ← the skill (workflows A–H)
    │   ├── templates/             ← registry, use case (3 levels)
    │   ├── references/            ← conventions + Cockburn writing rules
    │   └── use-case-guide.md      ← Cockburn writing guide
    └── usecase-map-puml/          ← PlantUML map style and templates
        ├── SKILL.md               ← usecase-map.puml style guide
        └── templates/             ← map.top-level, map.decomposition

Conventions in brief

• IDs: us-NNNN (summary / top-level user goal), us-NNNN.NN (user goal in a decomposition), us-NNNN.NN.NN (subfunction).
• Levels (Cockburn): summary → user-goal → subfunction. Write most requirements at user-goal level.
• Storage: registry.md (registry) + registry/us-NNNN-<kebab>/usecase.md + children/ + usecase-map.puml.
• Top-level map shows summaries and only the user goals that are not part of any shown summary.

Full details: skills/usecases/references/conventions.md. The Cockburn method is condensed in skills/usecases/use-case-guide.md.

License

MIT