ns-living-spec — Claude Code skill: what it does, how to install
ns-living-spec maintains domain specifications in docs/specs/ after version releases or approved reviews. Turns diffs and release artifacts into functional truth.
Apache-2.0 140 installs updated 2026-10-24
npx skills add nextstage-brasil/skills --skill ns-living-spec -a claude-codeWhat ns-living-spec does
The ns-living-spec skill keeps documentation in docs/specs/ aligned with actual system behavior. It supports three execution modes: Version for formal release closures, Ad-hoc for quick verified patches, and Appearance for user-facing prototype guides. In Version mode, it reads artifacts from docs/versions/{version_san}/sdd/, whereas Ad-hoc mode pairs the task description with an approved git diff.
For every affected domain, the skill updates requirement blocks with verifiable SHALL statements, adjusts endpoints, and writes new entries to docs/specs/INDEX.md. The agent-architecture.md file remains untouched because it serves as an ADR. Without both Code Review: Approved and Delivery Review: Approved verdicts, Version and Ad-hoc modes refuse to run.
What it helps with
- align domain specifications in
docs/specs/with delivered code - record API endpoints and data model changes after review approval
- maintain the central domain registry in
docs/specs/INDEX.md - prevent documentation churn from cosmetic or refactoring diffs
Example prompts for the agent
- Update domain specs for closed version
v1.2.0 - Sync docs/specs in ad-hoc mode for the approved auth-rbac task
- Record behavioral UI changes in appearance mode for prototype/onboarding
How to install ns-living-spec
1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-living-spec -a claude-code2Manually: put the files in place
~/.claude/skills/ns-living-spec/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ns-living-spec/
1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-living-spec -a codex2Manually: put the files in place
.agents/skills/ns-living-spec/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-living-spec -a cursor2Manually: put the files in place
.cursor/skills/ns-living-spec/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install nextstage-brasil/skills skills/ns-living-spec2Manually: put the files in place
.github/skills/ns-living-spec/SKILL.md1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-living-spec -a gemini-cli2Platform CLI
gemini skills install https://github.com/nextstage-brasil/skills --path skills/ns-living-specManually: put the files in place
.devin/skills/ns-living-spec/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-living-spec -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about ns-living-spec
How to install ns-living-spec in Claude Code?
Run npx skills add nextstage-brasil/skills --skill ns-living-spec -a claude-code. The file will be placed in ~/.claude/skills/ns-living-spec/SKILL.md.
What does ns-living-spec do?
It consolidates product domain specifications inside docs/specs/ from SDD artifacts or approved code diffs, tracking functional requirements and changelogs.
What triggers a skipped run in Ad-hoc mode?
The run aborts if docs/specs/ does not exist yet or if the diff contains only cosmetic updates, renames, and refactors without domain behavior changes.
Source text
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