ns-living-spec — скилл для Claude Code: что делает и как установить
Скилл ns-living-spec синхронизирует спецификации проекта в каталоге docs/specs/ с кодом. Обновляет доменные требования после закрытия версий или подтверждённых ревью.
Apache-2.0 140 установок обновлён 2026-10-24
npx skills add nextstage-brasil/skills --skill ns-living-spec -a claude-codeЧто делает ns-living-spec
Скилл ns-living-spec поддерживает документацию в папке docs/specs/ в роли актуального описания системы. Инструмент работает в трёх режимах: релизном (Version), точечном (Ad-hoc) и визуальном (Appearance). При закрытии версии скилл читает артефакты из папки docs/versions/{version_san}/sdd/. Для быстрых правок он сопоставляет задачу с подтверждённым git diff.
По каждому домену скилл обновляет требования формулировками SHALL, правит схемы данных и конечные точки, а затем переписывает docs/specs/INDEX.md. Документ agent-architecture.md остаётся нетронутым, так как относится к архитектурным решениям агента. Без статусов Code Review: Approved и Delivery Review: Approved запуск в режимах Version и Ad-hoc сразу блокируется.
Какие задачи решает
- синхронизировать спецификации в
docs/specs/после закрытия версии - зафиксировать изменения схем данных и эндпоинтов после код-ревью
- обновить реестр доменов в
docs/specs/INDEX.md - отфильтровать косметические правки без влияния на поведение системы
Примеры запросов агенту
- Обнови спецификации доменов для закрытой версии
v1.2.0 - Синхронизируй docs/specs в режиме ad-hoc для проверенной задачи auth-rbac
- Зафиксируй изменения UX-поведения в режиме appearance для prototype/onboarding
Как установить ns-living-spec
1Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-living-spec -a claude-code2Вручную: положить файлы
~/.claude/skills/ns-living-spec/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/ns-living-spec/
1Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-living-spec -a codex2Вручную: положить файлы
.agents/skills/ns-living-spec/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-living-spec -a cursor2Вручную: положить файлы
.cursor/skills/ns-living-spec/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install nextstage-brasil/skills skills/ns-living-spec2Вручную: положить файлы
.github/skills/ns-living-spec/SKILL.md1Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-living-spec -a gemini-cli2Командой платформы
gemini skills install https://github.com/nextstage-brasil/skills --path skills/ns-living-specВручную: положить файлы
.devin/skills/ns-living-spec/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-living-spec -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о ns-living-spec
Как установить ns-living-spec в Claude Code?
Выполните команду npx skills add nextstage-brasil/skills --skill ns-living-spec -a claude-code. Скилл запишется по пути ~/.claude/skills/ns-living-spec/SKILL.md.
Что делает ns-living-spec?
Скилл ведёт функциональные спецификации проекта в docs/specs/. Он дополняет требования, эндпоинты и структуры данных только после проверенных ревью кода и поставки.
В каком случае скилл пропустит обновление в режиме Ad-hoc?
Скилл остановит работу, если в git diff нет изменений бизнес-логики, схемы или API, либо если каталог docs/specs/ ещё не был создан.
Исходный текст
SKILL.md · Apache-2.0
---
name: ns-living-spec
description: "(NS) Living domain specs under docs/specs/. Use after version closure when requirements, `Code Review: Approved`, `Delivery Review: Approved`, and execution-handoff exist; ad-hoc when both Approved + behavioral diff + docs/specs/; appearance mode from ns-proto-creator / ns-proto-visual-guide (no review gates). Incremental only. Do NOT run Version/Ad-hoc before both Approved (appearance mode excepted)."
license: Apache-2.0
metadata:
author: nextstage-brasil
version: "1.8"
depends:
- ns-harness
---
# Living Spec Consolidator
Maintain `docs/specs/` as current functional truth of product.
## Session boot
See `../../ns-harness/references/session-boot.md` and `../../ns-harness/references/artifact-layout.md`.
## Modes
| Mode | When | Source of truth | Code + delivery gates |
| ---- | ---- | --------------- | --------------------- |
| **Version** (default) | Version closure after delivery | `docs/versions/{version_san}/sdd/` artifacts | Required (`Code Review: Approved` and `Delivery Review: Approved`, each score **10**) |
| **Ad-hoc** | Invoked by `ns-coder` (or human) after both Approved | `{task_description}` + approved `git diff` | Required (both `Approved`) |
| **Appearance** | Invoked by `ns-proto-creator` or `ns-proto-visual-guide` | Guide/prototype path + short behavioral delta | **None** |
**Appearance** if invoker pass mode `appearance` (or equivalent: guide/prototype path + behavioral delta, no review verdict). **Ad-hoc** if mode `ad-hoc` (or equivalent: no `{version_san}`, task description + approved diff). Else **Version**.
## When invoked
- Version closure post `Code Review: Approved` **and** `Delivery Review: Approved` — **Version**
- Ad-hoc coding, both reviews **Approved**, `docs/specs/` exists — **Ad-hoc**
- Prototype create/evolve or normative visual guides documenting behavioral UX — **Appearance**
- **Not** Version/Ad-hoc before both `Approved`
## Prerequisites
### Version mode
- Resolved `requirements.md` — `sdd/` first, else legacy version root (`artifact-layout.md` **Legacy path resolution**)
- Invoker reports `Code Review: Approved` and `Delivery Review: Approved` — no `code-review-report.md` required
- Resolved `execution-handoff.md` — `sdd/` first, else legacy version root (tasks completed)
### Ad-hoc mode
- `docs/specs/` already exists (**not** create tree from scratch)
- Invoker reports `Code Review: Approved` and `Delivery Review: Approved`
- `{task_description}` + approved working-tree diff (behavioral change)
- **Skip** (no writes) if diff non-behavioral: cosmetic, rename-only, pure refactor with no API/schema/UX/domain behavior change — report skipped
### Appearance mode
- Input: path to appearance guide and/or `prototype/` surface + short **behavioral delta** (what users can do / see changed or captured)
- May **create** `docs/specs/` + `INDEX.md` if missing
- SHALL only for **product-visible** behavior (flows, fields, states, permissions cues)
- **Never** paste `Element | How it should appear` tables into domain specs — link guide instead
- **Skip** pure chrome polish (spacing, color tweak, font swap, no behavior change) — report reason
- No Code Review / Approved requirement
## Workflow
Shared steps 1–4 all modes. Changelog label differs by mode.
### 1. Identify affected domains
Map features to canonical domains (examples):
| Feature area | Domain file |
| ----------------- | ------------------ |
| Auth, login, RBAC | `auth.md` |
| Users, profiles | `users.md` |
| Billing | `billing.md` |
| Notifications | `notifications.md` |
| Reports | `reports.md` |
| Integrations | `integrations.md` |
| Agent / graph | `agent.md` |
`docs/specs/agent-architecture.md` is the living ADR (`ns-agent-architecture`). Not a domain spec. Do not treat as `{domain}.md`.
Naming: English, kebab-case, singular (`user-profile.md`). Multi-domain features update multiple specs.
**Ad-hoc:** map from `{task_description}` + diff only — no invent unrelated domains.
**Appearance:** map from behavioral delta + guide/prototype scope only; add domain links to appearance docs under Related / references when useful.
### 2. Per domain
**If `docs/specs/{domain}.md` missing:** create from `references/domain-spec.template.md`
**If exists:** read entirely; **append or update** — never blind overwrite
Per relevant feature:
- Add or update `### Requirement:` blocks (SHALL + scenarios)
- Update `## Data model` + `## Endpoints` when schema/API changed (Version/Ad-hoc)
- Appearance: prefer UX/behavior requirements; no invent APIs/schemas not evidenced
- Append `## Changelog` entry:
- **Version:** `**{version_san}** — {ISO date}: {summary}`
- **Ad-hoc:** `**adhoc-YYYY-MM-DD** — {ISO date}: {summary}` (summary from task + diff)
- **Appearance:** `**appearance-YYYY-MM-DD** — {ISO date}: {summary}`
### 3. Update INDEX.md
Create or update `docs/specs/INDEX.md`:
```markdown
# Domain specs — {product_name}
| Domain | File | Last updated | Versions |
| ------ | -------------------- | ------------ | ------------- |
| auth | `docs/specs/auth.md` | {date} | {version_san or adhoc-YYYY-MM-DD or appearance-YYYY-MM-DD} |
```
### 4. Consolidation report
Emit short report for handoff:
```
## Living specs updated
| Domain | Action | File |
...
Mode: {version|ad-hoc|appearance}
Requirements added: N
Requirements updated: N
New specs: N
```
If skipped (non-behavioral, polish-only, or Ad-hoc missing `docs/specs/`):
```
## Living specs skipped
Reason: {missing docs/specs/|non-behavioral diff|chrome polish only}
```
## Critical rules
- English for spec content
- Requirements use verifiable SHALL language
- Read before write on existing specs
- Planning orchestrator read `INDEX.md` before new version requirements
- Ad-hoc must not create version artifacts under `docs/versions/`
- Ad-hoc must not invent `{version_san}`
- Appearance must not paste normative Element|How tables into specs
- Appearance must not require Code Review Approved
- Do not overwrite `docs/specs/agent-architecture.md` (`ns-agent-architecture` living ADR). `agent.md` is behavior only
## Related skills
- `ns-spec-driven` — reads living specs when planning (`references/requirements-generator.md`)
- `ns-reviewer` — prerequisite `Code Review: Approved` for Version/Ad-hoc
- `ns-judge` — prerequisite `Delivery Review: Approved` for Version/Ad-hoc
- `ns-coder` — may invoke ad-hoc after both `Approved`
- `ns-proto-creator` / `ns-proto-visual-guide` — may invoke appearance mode
© nextstage-brasil · Apache-2.0 · nextstage-brasil/skills