ns-living-spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Living Spec Consolidator

Maintain

docs/specs/

as current functional truth of product.

将

docs/specs/

维护为产品当前功能的权威依据。

Session boot

会话启动

See

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

and

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

请参阅

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

和

../../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}/` artifacts	Required ( `Approved` )
Ad-hoc	Invoked by `ns-coder` (or human) after `Code Review: 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.

模式	使用场景	权威来源	Code Review门槛
版本（默认）	交付完成后的版本收尾	`docs/versions/{version_san}/` 制品	必需（已批准）
临时	由 `ns-coder` （或人工）在“Code Review: Approved”后调用	`{task_description}` + 已批准的 `git diff`	必需（已批准）
外观	由 `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

版本收尾阶段且“Code Review: Approved”已通过 —— 版本模式
临时编码、评审已“批准”、
```
docs/specs/
```
已存在 —— 临时模式
原型创建/迭代或规范性视觉指南记录行为式UX —— 外观模式
禁止在获得“批准”结论前使用版本/临时模式

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)

存在

docs/versions/{version_san}/requirements.md

调用者报告“Code Review: Approved”（评分≥9）——无需
```
code-review-report.md
```

存在

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

（任务已完成）

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

```
docs/specs/
```
已存在（禁止从零开始创建目录结构）
调用者报告“Code Review: Approved”（评分≥9）
提供
```
{task_description}
```
+ 已批准的工作区差异（行为变更）
若差异为非行为性变更（ cosmetic、仅重命名、纯重构且无API/架构/UX/领域行为变更），则跳过（不写入）并报告跳过原因

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

输入：外观指南和/或
```
prototype/
```
路径 + 简短行为增量（用户可执行/可见的变更或新增内容）
若
```
docs/specs/
```
+
```
INDEX.md
```
缺失，可创建
仅适用于产品可见的行为（流程、字段、状态、权限提示）
禁止将
```
Element | How it should appear
```
表格粘贴到领域规范中——改为链接指南
若仅为纯界面优化（间距、颜色调整、字体替换，无行为变更），则跳过并报告原因
无需Code Review/批准要求

Workflow

工作流程

Shared steps 1–4 all modes. Changelog label differs by mode.

所有模式共享步骤1–4。变更日志标签因模式而异。

1. Identify affected domains

1. 识别受影响的领域

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

). 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.

将功能映射到标准领域（示例）：

功能领域	领域文件
认证、登录、RBAC	`auth.md`
用户、个人资料	`users.md`
计费	`billing.md`
通知	`notifications.md`
报表	`reports.md`
集成	`integrations.md`
Agent / 图谱	`agent.md`

docs/specs/agent-architecture.md

是动态ADR（由

ns-multi-agent-architect

维护），不属于领域规范，请勿将其视为

{domain}.md

。

命名规则：英文、短横线命名法（kebab-case）、单数形式（如

user-profile.md

）。跨领域功能需更新多个规范。

临时模式：仅从

{task_description}

+ 差异内容映射——不得新增无关领域。

外观模式：仅从行为增量 + 指南/原型范围映射；必要时在“相关/参考”部分添加指向外观文档的领域链接。

2. Per domain

2. 按领域处理

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}

若
docs/specs/{domain}.md
缺失：从

references/domain-spec.template.md

创建

若已存在：完整读取内容；追加或更新——绝不盲目覆盖

针对相关功能：

添加或更新
```
### Requirement:
```
块（使用SHALL + 场景描述）
当架构/API变更时，更新
```
## Data model
```
+
```
## Endpoints
```
（版本/临时模式）
外观模式：优先记录UX/行为需求；不得添加无依据的API/架构内容

追加

## Changelog

条目：

版本模式：

**{version_san}** — {ISO date}: {summary}

临时模式：
```
**adhoc-YYYY-MM-DD** — {ISO date}: {summary}
```
（摘要来自任务 + 差异内容）

外观模式：

**appearance-YYYY-MM-DD** — {ISO date}: {summary}

3. Update INDEX.md

3. 更新INDEX.md

Create or update

docs/specs/INDEX.md

markdown

undefined

创建或更新

docs/specs/INDEX.md

：

markdown

undefined

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}

undefined

Domain	File	Last updated	Versions
auth	`docs/specs/auth.md`	{date}	{version_san or adhoc-YYYY-MM-DD or appearance-YYYY-MM-DD}

undefined

4. Consolidation report

4. 合并报告

Emit short report for handoff:

undefined

生成简短的交接报告：

undefined

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/`):

| 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}

undefined

Reason: {missing docs/specs/|non-behavioral diff|chrome polish only}

undefined

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

规范内容使用英文
需求使用可验证的SHALL表述
写入现有规范前需先读取内容
编排规划器在处理新版本需求前需读取
```
INDEX.md
```
临时模式不得在
```
docs/versions/
```
下创建版本制品
临时模式不得虚构
```
{version_san}
```
外观模式不得将规范性Element|How表格粘贴到规范中
外观模式无需Code Review批准

不得覆盖

docs/specs/agent-architecture.md

（由

ns-multi-agent-architect

维护的动态ADR）。

agent.md

仅记录行为内容

ns-living-spec

Original

Translation

Living Spec Consolidator

Living Spec Consolidator

Session boot

会话启动

Modes

模式

When invoked

调用时机

Prerequisites

前置条件

Version mode

版本模式

Ad-hoc mode

临时模式

Appearance mode

外观模式

Workflow

工作流程

1. Identify affected domains

1. 识别受影响的领域

2. Per domain

2. 按领域处理

3. Update INDEX.md

3. 更新INDEX.md

Domain specs — {product_name}

Domain specs — {product_name}

4. Consolidation report

4. 合并报告

Living specs updated

Living specs updated

Living specs skipped

Living specs skipped

Critical rules

关键规则

Related skills

相关技能