# Ns Living Spec

> (NS) Living domain specs under docs/specs/. Use after version closure when requirements, `Code Review: Approved`, and execution-handoff exist; ad-hoc when Approved behavioral diff + docs/specs/; appearance mode from ns-proto-creator / ns-proto-visual-guide (no Code Review gate). Incremental only. Do NOT run Version/Ad-hoc before `Code Review: Approved` (appearance mode excepted).

- Skill: `nextstage-brasil/ns-living-spec` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add nextstage-brasil/ns-living-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nextstage-brasil/ns-living-spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: Apache-2.0
- Author: nextstage-brasil (https://skillmd.com/u/nextstage-brasil)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nextstage-brasil/ns-living-spec

---


# 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 Review gate |
| ---- | ---- | --------------- | ---------------- |
| **Version** (default) | Version closure after delivery | `docs/versions/{version_san}/sdd/` artifacts | Required (`Approved` = score **10**) |
| **Ad-hoc** | Invoked by `ns-coder` (or human) after `Approved` | `{task_description}` + approved `git diff` | Required (`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` — **Version**
- Ad-hoc coding, review **Approved**, `docs/specs/` exists — **Ad-hoc**
- Prototype create/evolve or normative visual guides documenting behavioral UX — **Appearance**
- **Not** Version/Ad-hoc before `Code Review: Approved`

## Prerequisites

### Version mode

- Resolved `requirements.md` — `sdd/` first, else legacy version root (`artifact-layout.md` **Legacy path resolution**)
- Invoker reports `Code 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`
- `{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-coder` — may invoke ad-hoc after `Approved`
- `ns-proto-creator` / `ns-proto-visual-guide` — may invoke appearance mode