ns-spec-driven

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

NextStage Spec-Driven

NextStage 规格驱动交付

Delivery face for spec-driven journey: clarify, specify, (consistency / partition), tasks, execute, close.

Orchestrate — not implement phase bodies inline. Read phase reference at delegation time. State on disk (

docs/versions/

docs/context/

, handoff files), not chat history.

Entry priority 2 (feature / version / SDD / multi-day / resume). Harness table:

../../ns-harness/references/code-skill-routing.md

. Trigger phrases:

references/entry-triggers.md

. Bare quick fix, no SDD context → redirect

ns-coder

(priority 5) unless user explicitly invoked this skill.

交付界面用于规格驱动的开发流程：澄清需求、制定规格、（一致性检查/任务拆分）、生成任务、执行、收尾。

编排而非内联实现阶段内容。在委托执行时读取阶段参考文档。状态存储在磁盘（

docs/versions/

、

docs/context/

、交接文件）中，而非聊天记录。

进入优先级2（功能/版本/SDD/多日工作/恢复）。参考Harness表：

../../ns-harness/references/code-skill-routing.md

。触发短语：

references/entry-triggers.md

。无SDD上下文的单纯快速修复 → 重定向至

ns-coder

（优先级5），除非用户明确调用本技能。

Routing (read first)

路由规则（请先阅读）

Handoff	Target
Small / quick inside SDD	`coder-agent` → `ns-coder` (MUST bridge when available — `../../ns-harness/references/subagent-dispatch.md` )
Version + handoff	`references/execution-handoff.md` + `../ns-coder/references/run-implementation.md` + `coder-agent` (MUST when available)
Task file generation	`task-writer-agent` → `references/task-generator.md` (MUST bridge when available)
Bare quick fix, no SDD context	Redirect `ns-coder` (priority 5) — if spawning worker: MUST `coder-agent` when available

交接场景	目标技能
SDD范围内的小型/快速任务	`coder-agent` → `ns-coder` （必须在可用时桥接 — `../../ns-harness/references/subagent-dispatch.md` ）
版本+交接文件	`references/execution-handoff.md` + `../ns-coder/references/run-implementation.md` + `coder-agent` （可用时必须使用）
任务文件生成	`task-writer-agent` → `references/task-generator.md` （可用时必须桥接）
无SDD上下文的单纯快速修复	重定向至 `ns-coder` （优先级5）—— 若生成工作进程：可用时必须使用 `coder-agent`

Harness

Harness相关

See

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

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

references/gates.md

Variable	Resolve via
`{version_san}`	User scope or existing folder under `docs/versions/`

详见

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

、

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

、

references/gates.md

。

变量	解析方式
`{version_san}`	用户指定范围或 `docs/versions/` 下的现有文件夹

Out of band (not this skill)

非本技能处理场景

Brownfield onboarding manual — never auto-run, never pipeline phase:

Need	Skill
Full prepare after `harness init`	`/ns-harness prepare this repo` or `npx @nextstage-brasil/harness prepare`
Single worker only	`/ns-harness` + architecture-rules / brownfield / reverse-spec / agents-md

architecture-rules.md

still stub or

docs/context/brownfield-map.md

missing and task needs them: tell user run
/ns-harness prepare this repo
, then stop — or continue SDD only if they insist after warning.

遗留系统接入为手动操作 — 绝不自动运行，绝不作为流水线阶段：

需求	对应技能
`harness init` 后的完整准备操作	`/ns-harness prepare this repo` 或 `npx @nextstage-brasil/harness prepare`
仅需单个工作进程	`/ns-harness` + architecture-rules / brownfield / reverse-spec / agents-md

若

architecture-rules.md

仍为占位文件或

docs/context/brownfield-map.md

缺失且任务需要这些文件：告知用户运行
/ns-harness prepare this repo
，然后停止操作 — 或在用户警告后坚持继续时，才继续SDD流程。

Journey (delivery only)

交付流程（仅交付环节）

mermaid

flowchart LR
  user[User request]
  size[Auto-size]
  clarify[Clarify]
  specify[Specify]
  consist[Consistency]
  part[Partition]
  tasks[Tasks]
  exec[Execute]
  close[Close]
  quick[Quick mode]

  user --> size
  size -->|Small| quick
  size -->|Medium+| clarify
  clarify --> specify
  specify --> consist
  specify --> part
  specify --> tasks
  tasks --> exec
  exec --> close
  quick --> exec

Phase	When	Reference
Clarify	Ambiguity / gray areas	`references/clarify-requirements.md` (in-session — no v1 bridge)
Specify	Always for Medium+	`references/requirements-generator.md` (in-session — no v1 bridge)
Consistency	Before tasks (Large+)	`references/analyze-consistency.md` (in-session — no v1 bridge)
Partition	Multi-slice versions	`references/version-partitioner.md` (in-session — no v1 bridge)
Tasks	Medium+ formal tasks	`task-writer-agent` → `references/task-generator.md` (MUST when available) then `unit-test-task-generator.md` / `e2e-test-task-generator.md` + `references/execution-handoff.md`
Execute	Always	See execute routing below
Close	After delivery	`reviewer-agent` → `ns-reviewer` (MUST when available) → `ns-living-spec`
Quick	≤3 files, one-sentence scope	`coder-agent` → `ns-coder` (MUST when available)

Details:

references/auto-sizing.md

references/router.md

mermaid

flowchart LR
  user[User request]
  size[Auto-size]
  clarify[Clarify]
  specify[Specify]
  consist[Consistency]
  part[Partition]
  tasks[Tasks]
  exec[Execute]
  close[Close]
  quick[Quick mode]

  user --> size
  size -->|Small| quick
  size -->|Medium+| clarify
  clarify --> specify
  specify --> consist
  specify --> part
  specify --> tasks
  tasks --> exec
  exec --> close
  quick --> exec

阶段	触发时机	参考文档
澄清需求	存在歧义/模糊领域	`references/clarify-requirements.md` （会话内处理 — 无v1桥接）
制定规格	中型及以上项目必须执行	`references/requirements-generator.md` （会话内处理 — 无v1桥接）
一致性检查	生成任务前（大型项目）	`references/analyze-consistency.md` （会话内处理 — 无v1桥接）
任务拆分	多切片版本	`references/version-partitioner.md` （会话内处理 — 无v1桥接）
生成任务	中型及以上项目的正式任务	`task-writer-agent` → `references/task-generator.md` （可用时必须使用），随后调用 `unit-test-task-generator.md` / `e2e-test-task-generator.md` + `references/execution-handoff.md`
执行	所有场景	见下方执行路由规则
收尾	交付完成后	`reviewer-agent` → `ns-reviewer` （可用时必须使用） → `ns-living-spec`
快速模式	≤3个文件、单句描述范围	`coder-agent` → `ns-coder` （可用时必须使用）

详情：

references/auto-sizing.md

、

references/router.md

。

Boot (mandatory, once per session)

会话启动（强制要求，每会话一次）

Classify request → Small / Medium / Large (
```
references/auto-sizing.md
```
).

Check resume signals (

execution-handoff.md

version-roadmap.md

, partial version) →

references/session-continuity.md

Agent runtime gate — agent-api / intelligent SaaS (
```
references/agent-runtime-integration.md
```
): MUST load
```
ns-langgraph-agents
```
in session before any phase; stop if skill not installed.
Scan installed complements (soft) →
```
references/skill-integrations.md
```
.
Confirm once when needed: target version id, language for markdown artifacts — natural chat (
```
references/human-communication.md
```
). Never open with telegraphic status dump or phase jargon.

分类请求 → 小型/中型/大型（
```
references/auto-sizing.md
```
）。

检查恢复信号（

execution-handoff.md

、

version-roadmap.md

、部分完成的版本） →

references/session-continuity.md

。

Agent运行时网关 — agent-api / 智能SaaS（
```
references/agent-runtime-integration.md
```
）：必须在任何阶段前加载
```
ns-langgraph-agents
```
到会话中；若技能未安装则停止操作。
扫描已安装的补充技能（软依赖） →
```
references/skill-integrations.md
```
。
必要时确认一次：目标版本ID、Markdown工件使用的语言 — 使用自然对话（
```
references/human-communication.md
```
）。绝不要以电报式状态转储或阶段术语开场。

Human communication

人机沟通规则

Chat short, natural language. Read
references/human-communication.md
before any human gate or boot confirm.

Name next deliverable ("requirements document", "task files") — not internal phases ("Specify", "Clarify").
Chat stand alone: highlights in plain language; document IDs only after meaning (Gate 1 highlights in that file).
Never use
```
Reply:
```
,
```
Premise:
```
, or "go for Specify".
Caveman / artifact-compress = files only — never chat.

使用简短、自然的语言聊天。在进行任何人机网关确认或会话启动确认前，请阅读
references/human-communication.md
。

明确下一个交付物（如“需求文档”、“任务文件”）—— 而非内部阶段名称（如“制定规格”、“澄清需求”）。
聊天内容需独立可理解：用平实语言突出重点；仅在说明含义后提及文档ID（见该文件中的Gate 1 highlights）。
绝不要使用
```
Reply:
```
、
```
Premise:
```
或“进入制定规格阶段”这类表述。
极简/工件压缩模式 = 仅发送文件 — 绝不发送聊天内容。

Orchestration mandate

编排强制规则

Delegate = spawn bridge when available (else read phase reference in-session). Not "skip reference" while bridge present. See
```
../../ns-harness/references/subagent-dispatch.md
```
.
Read phase reference before that phase — never improvise from memory.
Do not ask "continue to next phase?" between phases in same sized pipeline.
Do not invoke
```
/ns-harness prepare
```
or brownfield prepare references.
Do not load multiple version specs into context — see
```
references/context-budget.md
```
.
After each phase, verify expected artifact paths exist before advancing.

委托执行 = 可用时生成桥接（否则在会话内读取阶段参考文档）。桥接存在时绝不要“跳过参考文档”。详见
```
../../ns-harness/references/subagent-dispatch.md
```
。
在进入对应阶段前必须阅读阶段参考文档 — 绝不凭记忆即兴操作。
在同一规模的流水线各阶段之间，不要询问“是否继续下一阶段？”。
不要调用
```
/ns-harness prepare
```
或遗留系统准备相关参考文档。
不要加载多个版本规格到上下文 — 详见
```
references/context-budget.md
```
。
每个阶段完成后，在进入下一阶段前验证预期的工件路径是否存在。

Auto-size summary

自动规模调整总结

Size	Pipeline
Small	`coder-agent` → `ns-coder` (quick mode — `references/quick-mode.md` )
Medium	Clarify (if needed) → Specify → Tasks (MUST `task-writer-agent` when available) + handoff → Execute → Close
Large	Full chain including Consistency and/or Partition when scope warrants

Safety valve: scope exceeds ~3 files or explodes mid-session → stop, formalize via Medium+ pipeline (requirements + tasks).

规模	流水线流程
小型	`coder-agent` → `ns-coder` （快速模式 — `references/quick-mode.md` ）
中型	澄清需求（若需要）→ 制定规格 → 生成任务（可用时必须使用 `task-writer-agent` ）+ 交接 → 执行 → 收尾
大型	完整流程链，包括根据范围需要进行的一致性检查和/或任务拆分

安全机制：范围超过约3个文件或会话中范围突然扩大 → 停止操作，通过中型及以上流水线（需求+任务）规范化处理。

Execute routing

执行路由规则

Worker dispatch: MUST use harness project agents when available —

../../ns-harness/references/subagent-dispatch.md

. Inline mapped skill while bridge present = forbidden.

Context	Worker
Ad-hoc / quick / single task	`coder-agent` → `ns-coder` (MUST bridge when available)
Version with `execution-handoff.md`	`../ns-coder/references/run-implementation.md` — classic batched dispatch (same-layer consecutive `pending` , prefer 4–7, hard max 7; size 1 = single task) + `coder-agent` (MUST when available) / `ns-coder` or `ns-autonomous` ; handoff rows stay per task; Progress Next task = first id of next batch
Partitioned version ( `version-roadmap.md` )	`references/orchestrator.md` (slice workers via `coder-agent` — MUST when available; already batched per slice)
GitLab issue URL + MCP available	`ns-execution-gitlab-issue` (soft — prefer when GitLab present)
Autonomous multi-step local plan	`ns-autonomous`

Face = orchestrator (

ns-spec-driven

); does not implement — drives

run-implementation.md

(classic) or

orchestrator.md

(slices).

Tests while executing version tasks: unit/integration only. Forbidden for agents to run E2E during task/batch loop; human runs E2E at version end (

../ns-coder/references/run-implementation.md

工作进程调度：必须在可用时使用Harness项目Agent —

../../ns-harness/references/subagent-dispatch.md

。桥接存在时禁止使用内联映射技能。

上下文	工作进程
临时/快速/单个任务	`coder-agent` → `ns-coder` （可用时必须桥接）
带有 `execution-handoff.md` 的版本	`../ns-coder/references/run-implementation.md` — 经典批量调度（同层连续 `pending` 任务，优先4–7个，硬上限7个；规模1则为单个任务） + `coder-agent` （可用时必须使用）/ `ns-coder` 或 `ns-autonomous` ；每个任务保留交接行；进度“下一个任务”=下一批次的第一个ID
已拆分的版本（ `version-roadmap.md` ）	`references/orchestrator.md` （通过 `coder-agent` 调度切片工作进程 — 可用时必须使用；已按切片批量处理）
GitLab问题URL + MCP可用	`ns-execution-gitlab-issue` （软依赖 — 存在GitLab时优先使用）
自主多步骤本地计划	`ns-autonomous`

界面=编排器（

ns-spec-driven

）；不负责实现 — 驱动

run-implementation.md

（经典模式）或

orchestrator.md

（切片模式）。

执行版本任务时的测试：仅支持单元/集成测试。禁止Agent在任务/批量循环中运行端到端测试；需由人工在版本结束时运行端到端测试（

../ns-coder/references/run-implementation.md

）。

Trigger → reference

触发词→参考文档

User says	Read first
"specify", "requirements for vX"	`references/router.md` → `requirements-generator.md`
"clarify", vague scope	`references/router.md` → `clarify-requirements.md`
"implement", "build version", tasks exist	`references/session-continuity.md` + Execute
"quick fix", "just change X"	`references/quick-mode.md`
"resume", "continue version", partial `docs/versions/`	`references/session-continuity.md`
"orchestrate slices", partitioned roadmap	`references/orchestrator.md`
UI / design work	`references/skill-integrations.md` → `ns-frontend-design`
README / docs	`references/skill-integrations.md` → `ns-docs-writer`
security headers / modernize	`references/skill-integrations.md` → `ns-best-practices`
agent-api / intelligent SaaS / LangGraph scope	`references/agent-runtime-integration.md` → `ns-langgraph-agents` (mandatory)
MR / PR review	`ns-reviewer` directly (not this face)

用户表述	优先阅读文档
"specify"、"requirements for vX"	`references/router.md` → `requirements-generator.md`
"clarify"、模糊范围	`references/router.md` → `clarify-requirements.md`
"implement"、"build version"、任务已存在	`references/session-continuity.md` + 执行阶段
"quick fix"、"just change X"	`references/quick-mode.md`
"resume"、"continue version"、 `docs/versions/` 下存在部分工件	`references/session-continuity.md`
"orchestrate slices"、已拆分的路线图	`references/orchestrator.md`
UI/设计工作	`references/skill-integrations.md` → `ns-frontend-design`
README/文档	`references/skill-integrations.md` → `ns-docs-writer`
安全头/现代化改造	`references/skill-integrations.md` → `ns-best-practices`
agent-api/智能SaaS/LangGraph范围	`references/agent-runtime-integration.md` → `ns-langgraph-agents` （强制要求）
MR/PR评审	直接使用 `ns-reviewer` （而非本界面）

Agent runtime (mandatory when detected)

Agent运行时（检测到则强制要求）

Non-negotiable for agent-api and intelligent SaaS products. See

references/agent-runtime-integration.md

. Greenfield with no

agent-api/

: Feature 001 = langgraph bootstrap, then version deltas.

对于agent-api和智能SaaS产品为非协商要求。详见

references/agent-runtime-integration.md

。无

agent-api/

的新项目：Feature 001=LangGraph引导，然后进行版本增量开发。

Complement integrations

补充技能集成

spec-driven

gitlab

agents

ship

ns-frontend-design

ns-docs-writer

, and

ns-best-practices

via

ns-coder

depends

. Check

.agents/skills/

once per session; if present → delegate (

references/skill-integrations.md

). If absent (minimal install) → continue and recommend install once per session (agent runtime not optional — see above):

bash

npx @nextstage-brasil/harness --skill ns-frontend-design --skill ns-docs-writer --skill ns-best-practices --no-scaffold -y

spec-driven

gitlab

agents

通过

ns-coder

的

depends

依赖提供

ns-frontend-design

、

ns-docs-writer

和

ns-best-practices

。每会话检查一次

.agents/skills/

；若存在 → 委托执行（

references/skill-integrations.md

）。若不存在（最小化安装）→ 继续操作并每会话推荐安装一次（agent运行时不可选 — 见上文）：

bash

npx @nextstage-brasil/harness --skill ns-frontend-design --skill ns-docs-writer --skill ns-best-practices --no-scaffold -y

Completion summary

完成总结

When version or quick fix closes, report:

Artifacts written or updated (paths).
Handoff status if applicable.
Suggested next step (living spec done → next version clarify; quick fix → optional review).

版本或快速修复完成时，需报告：

已写入或更新的工件（路径）。
交接状态（若适用）。
建议的下一步操作（活规格完成 → 下一版本需求澄清；快速修复 → 可选评审）。

Forbidden

禁止操作

Auto-run or chain
```
/ns-harness prepare
```
.
List Prepare as SDD phase.
Hard-require complement skills when missing from
```
.agents/skills/
```
(delegate when present; see Complement integrations).
Plan or execute agent-api / intelligent SaaS work without loading
```
ns-langgraph-agents
```
when detection signals match.
Generate requirements/tasks yourself without reading phase references / delegating task files via
```
task-writer-agent
```
.
Skip
```
execution-handoff.md
```
when formal tasks exist for version.
Address human with internal phase names ("Specify", "Clarify") or bot chrome (
```
Reply:
```
,
```
Premise:
```
).

自动运行或链式调用
```
/ns-harness prepare
```
。
将Prepare列为SDD阶段。
当
```
.agents/skills/
```
中缺少补充技能时强制要求使用（存在时委托执行；见补充技能集成）。
检测到匹配信号时，未加载
```
ns-langgraph-agents
```
就规划或执行agent-api/智能SaaS工作。
未阅读阶段参考文档/未通过
```
task-writer-agent
```
委托生成任务文件，自行生成需求/任务。
版本存在正式任务时跳过
```
execution-handoff.md
```
。
使用内部阶段名称（如“制定规格”、“澄清需求”）或机器人格式（如
```
Reply:
```
、
```
Premise:
```
）与用户沟通。

Invocation examples

调用示例

/ns-spec-driven

Specify and implement user notifications for version 2.1

Quick fix: add nullable email field to the signup form

Resume implementation — handoff exists for docs/versions/1.0.0/

Continue partitioned version 3.8.0 — run pending slices from version-roadmap.md

/ns-spec-driven

Specify and implement user notifications for version 2.1

Quick fix: add nullable email field to the signup form

Resume implementation — handoff exists for docs/versions/1.0.0/

Continue partitioned version 3.8.0 — run pending slices from version-roadmap.md