Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add nextstage-brasil/skills --skill ns-living-spec -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/ns-living-spec/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/ns-living-spec/

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

Similar skills

All skills for Writing and docs →

From the same set20

The whole set →
ns-autonomous ns-autonomous — a skill for Claude Code, Codex, Cursor, Copilot and Gemini CLI that takes a local plan or pasted text and runs it autonomously inside an isolated worktree. CX Codex +1 152installs ns-e2e-tests The ns-e2e-tests skill structures Cypress end-to-end work across devices and keeps tests in a separate project. Use it when adding or refactoring specs. CX Codex +1 151installs ns-backend-tests ns-backend-tests — a skill for writing and running PHPUnit unit and integration tests directly in your IDE. Runs only in Docker containers, helping you quickly test a new Laravel project or rewrite existing tests. CX Codex +1 151installs ns-docs-writer ns-docs-writer — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that produces human-facing project docs: README files, docs/ guides, runbooks, and contributor markdown. CX Codex +1 151installs ns-coder ns-coder handles focused code changes such as fixes, small refactors, scripts, and migrations. Use it for ad-hoc work outside a multi-stage SDD handoff. CX Codex +1 151installs ns-reviewer ns-reviewer grades code changes against SOLID principles, clean code patterns, performance, security, and testability. Approves only at score 10; score 9 triggers rejection. CX Codex +1 140installs ns-proto-visual-guide The ns-proto-visual-guide Claude Code skill documents the required appearance of cards, forms, shells, and overlays. It activates for normative visual guides and visual QA checklists. CX Codex +1 106installs ns-proto-creator ns-proto-creator — a Claude Code skill that captures live interfaces with Playwright and builds or updates a prototype. It runs for URL-based prototyping, screen reconstruction, and changes to an existing prototype/. CX Codex +1 106installs

Project sponsors

Companies that keep this analytics open