Living Spec Consolidator

docs/specs/

Session boot

../../ns-harness/references/session-boot.md

../../ns-harness/references/artifact-layout.md

Modes

docs/versions/{version_san}/

Approved

ns-coder

Code Review: Approved

{task_description}

git diff

Approved

ns-proto-creator

ns-proto-visual-guide

appearance

ad-hoc

{version_san}

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

  Approved

  verdict

Prerequisites

Version mode

• docs/versions/{version_san}/requirements.md

• Invoker reports

  Code Review: Approved

  (score ≥ 9) — no

  code-review-report.md

  required

• docs/versions/{version_san}/execution-handoff.md

  (tasks completed)

Ad-hoc mode

• docs/specs/

  already exists (not create tree from scratch)
• Invoker reports

  Code Review: Approved

  (score ≥ 9)

• {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

1. Identify affected domains

auth.md

users.md

billing.md

notifications.md

reports.md

integrations.md

agent.md

docs/specs/agent-architecture.md

ns-multi-agent-architect

{domain}.md

user-profile.md

{task_description}

2. Per domain

docs/specs/{domain}.md

references/domain-spec.template.md

• 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

docs/specs/INDEX.md

# 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

## Living specs updated
| Domain | Action | File |
...
Mode: {version|ad-hoc|appearance}
Requirements added: N
Requirements updated: N
New specs: N

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-multi-agent-architect

  living ADR).

  agent.md

  is behavior only

Related skills

• ns-spec-driven

  — reads living specs when planning (

  references/requirements-generator.md

  )

• ns-reviewer

  — prerequisite approval for Version/Ad-hoc

• ns-coder

  — may invoke ad-hoc after Approved

• ns-proto-creator

  /

  ns-proto-visual-guide

  — may invoke appearance mode