ns-spec-driven

NextStage 规格驱动

交付入口，用于规格驱动流程：接收需求、严格澄清、制定规格、（一致性检查 / 拆分）、任务、执行、收尾。

通过构造确保完整性优先于保真度。严格澄清的深挖仅限 Gate 0。确认 Gate 1–4 和 brownfield Step 0.4 保持不变（映射相对于应用目录树仍是最新时自动继续；无法证明最新时则等待）。Clarify-Strict 版本 ≠ 按问题使用的增强器（ns-requirements-enricher）。ns-project-manager 保持解耦。

编排——不要将阶段主体内联实现。委派时读取阶段参考文档。状态保存在磁盘上（docs/versions/、docs/context/、交接文件），而非聊天记录中。

入口优先级 2（功能 / 版本 / SDD / 多日任务 / 恢复）。Harness 表：../../ns-harness/references/code-skill-routing.md。触发短语：references/entry-triggers.md。没有 SDD 上下文的简单快速修复 → 转交给 ns-coder（优先级 5），除非用户明确调用此技能。

路由（先读）

交接	目标
SDD 中的小型 / 快速任务	会话内 ns-coder（轻量执行——不得启动 coder-agent；../../ns-harness/references/subagent-dispatch.md）
版本 + 交接	references/execution-handoff.md + ../ns-coder/references/run-implementation.md + coder-agent（可用时必须使用——重型）
任务文件生成	必须启动项目 Agent task-writer-agent（名称必须完全一致；适配器 model）→ references/task-generator.md。禁止使用 Task inherit / coder / generalPurpose（../../ns-harness/references/subagent-dispatch.md）
没有 SDD 上下文的简单快速修复	转交给 ns-coder（优先级 5）——轻量；会话内；不得启动 coder-agent

Harness

参阅 ../../ns-harness/references/session-boot.md、../../ns-harness/references/artifact-layout.md、references/gates.md。

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

范围外（不属于此技能）

Brownfield 入门准备需手动执行——绝不自动运行，也绝不作为流水线阶段：

需求	技能
在 harness init 后进行完整准备	/ns-harness prepare this repo 或 npx @nextstage-brasil/harness prepare
按问题进行 GitLab 深挖	/ns-requirements-enricher——不是版本 Clarify-Strict

如果 architecture-rules.md 仍是存根，或缺少 docs/context/brownfield-map.md，且任务需要这些内容：告知用户运行 /ns-harness prepare this repo，然后停止——或者只有在警告后用户坚持时，才继续 SDD。

交付流程（仅交付）

flowchart LR
  user[User request]
  size[Auto-size]
  intake[Intake]
  clarify[Clarify-Strict]
  specify[Specify]
  consist[Consistency]
  part[Partition]
  tasks[Tasks]
  units[Delivery units]
  handoff[Handoff]
  exec[Execute]
  close[Close]
  quick[Quick mode]

  user --> size
  size -->|Small| quick
  size -->|Medium+| intake
  intake --> clarify
  clarify --> specify
  specify --> consist
  specify --> part
  specify --> tasks
  tasks --> handoff
  tasks -.->|Gate 4 opt-in| units
  units --> handoff
  handoff --> exec
  quick --> exec
  exec --> close

阶段	时间	参考
接收	来源内容密集 / 粘贴而来	references/source-registry.md — 持久化保存为 source/{slug}.md，添加锚点并分类
澄清	中型及以上项目必须执行	依次参考 references/clarify-requirements.md 和 references/clarify-strict.md：检查清单、D1–D4、Gate 0（会话内）
编写规格	中型及以上项目始终执行	references/requirements-generator.md — 若来源包含 ui-screen，还会编写 ui-contract.md（会话内 — 无 v1 桥接）
一致性分析	任务编写前（大型及以上项目）	references/analyze-consistency.md（会话内 — 无 v1 桥接）
划分	多切片版本	references/version-partitioner.md（会话内 — 无 v1 桥接）
任务	中型及以上项目的正式任务	必须按准确名称启动 task-writer-agent（适配器 model；Task 不得使用 inherit）→ task-generator.md，然后使用单元 / e2e 生成器
交付单元	所有任务完成后（可选）	可使用 GitLab 时执行 Gate 4；仅在发布、并行或存在恢复文件时使用 references/delivery-units.md
交接	任务完成后（若运行则为 Gate 4 后）	references/execution-handoff.md
执行	始终执行	请参阅下方执行路由
收尾	交付后	reviewer-agent → ns-reviewer（可用时必须执行）；仅当 Code Review: Approved 时才在会话内运行 ns-judge；仅当 Delivery Review: Approved 后才运行 ns-living-spec（../ns-reviewer/references/review-gate-workflow.md）。如果步骤 5 已运行这两个步骤，则跳过第二组。
快速处理	≤3 个文件，范围用一句话说明	在会话内使用 ns-coder（成本低 — 不得启动 coder-agent）

详细信息：references/auto-sizing.md、references/router.md。

启动（强制，每个会话执行一次）

1. 对请求分类 → 小型 / 中型 / 大型（references/auto-sizing.md）。来源内容密集（契约 / 架构表格或约 8 个及以上章节）→ 至少按大型项目处理。
2. **来源检测：**先列出 docs/versions/{version_san}/sdd/source/；否则，若尚未迁移，则列出旧版路径 docs/versions/{version_san}/source/（artifact-layout.md 旧版路径解析）。用户粘贴的规格说明 → 在澄清前先接收（source-registry.md）。
3. 检查恢复信号（execution-handoff.md、version-roadmap.md、不完整版本、未解决的问题）→ references/session-continuity.md。
4. Agent 运行时门控 — agent-api / 智能 SaaS（references/agent-runtime-integration.md）：在进入任何阶段前，必须在会话中加载 ns-langgraph-agents；如果未安装此技能，则停止。
5. 扫描已安装的补充组件（非强制）→ references/skill-integrations.md。
6. 在需要时确认一次：目标版本 ID、Markdown 产物的语言 — 使用自然对话（references/human-communication.md）。开场绝不可使用电报式状态汇报或阶段术语。

人际沟通

使用简短、自然的语言交流。进行任何人工把关或启动确认前，请先阅读 references/human-communication.md。

• 点明下一个交付物（“需求文档”“任务文件”），不要说内部阶段（“Specify”“Clarify”）。
• 聊天内容要能独立理解：用通俗语言概述；只有说明含义后才能提及文档 ID（该文件中的 Gate 1 highlights）。Gate 0：使用编号提问（1. 2. ……）；对于剩余的“是／否”确认（不是开放式问题），人类可以按编号回复，也可以回复 Tudo sim / all yes。行为（何时、HTTP、复制）。产品错误代码：聊天问题见 clarify-strict.md。
• 不要使用 Reply:、Premise: 或 “go for Specify”。
• Caveman / artifact-compress = 仅限文件，绝不用于聊天。

编排要求

• Delegate = 按 ../../ns-harness/references/subagent-dispatch.md 启动把关。低成本执行 / Quick = 在当前会话中使用 ns-coder。繁重工作 / Tasks / Review = 有桥接工具时启动桥接。
• 每个阶段开始前都要阅读相应的阶段参考，不要凭记忆临场发挥。
• 同一规模的流水线中，阶段之间不要询问“继续下一阶段吗？”。
• 不要调用 /ns-harness prepare，也不要查阅 brownfield prepare 参考。
• 不要将多个版本规范加载到上下文中——参见 references/context-budget.md。
• 每个阶段结束后，先确认预期的产物路径存在，再进入下一阶段。

自动确定规模摘要

规模	流水线
Small	在当前会话中使用 ns-coder（快速模式——references/quick-mode.md；低成本执行）
Medium	Intake（如有来源）→ Clarify-Strict → Specify → Tasks（必须启动名称完全匹配的 task-writer-agent）→ 可选的 Gate 4 + 单元 → 交接 → Execute → Close
Large	完整流程，包括视范围需要的 Consistency 和／或 Partition

**安全阀：**范围超过约 3 个文件，或在会话中显著扩大时，应停止并通过 Medium+ 流水线（需求 + 任务）进行正式化。

执行路由

Worker 分派：启动门控 — ../../ns-harness/references/subagent-dispatch.md。简单任务 = 会话内执行；繁重任务 / 审查 / 多项任务 = 有可用的具名桥接时使用具名桥接。

上下文	Worker
临时 / 快速 / 单项任务	会话内 ns-coder（简单任务 — MUST NOT 启动 coder-agent）
带有 delivery-units.md 的版本	按单元分派（按波次顺序）；仅当 Gate 4 允许并行且标记为 A ∥ B 时才并行。GitLab：delivery-units.md 是 GitLab 状态/已耗时（SSoT）。已发布且存在 G → ns-execution-gitlab-issue SDD 单元模式；否则在 run-implementation.md 中执行本地单元批次
仅带有 execution-handoff.md 的版本（无单元文件）	../ns-coder/references/run-implementation.md — 经典批次式分派（同层级连续的 pending 项，优先 4–7 项，最多 7 项；数量为 1 时即单项任务）+ coder-agent（MUST，若可用 — 繁重任务）/ ns-coder 或 ns-autonomous；交接行按任务保留；Progress Next task = 下一批次的第一个 id
分区版本（version-roadmap.md）	references/orchestrator.md — 存在 delivery-units.md 时按单元执行（每个单元提交/MR）；否则通过 coder-agent 分派切片 Worker（MUST，若可用 — 繁重任务）
外部 GitLab ISSUE_URL + MCP 可用	ns-execution-gitlab-issue（优先级 1 — 非 SDD 单元模式）
自主多步骤本地计划	ns-autonomous

负责人 = orchestrator（ns-spec-driven）；不负责实现 — 驱动 run-implementation.md（经典模式），或 orchestrator.md（存在 delivery-units.md 时按单元执行；否则按切片执行）。

**执行版本任务期间的测试：**仅单元 / 集成测试。禁止 Agent 在任务 / 批次循环期间运行 E2E；版本结束时由人工运行 E2E（../ns-coder/references/run-implementation.md）。

触发条件 → 参考文档

用户的说法	首先阅读
"specify", "requirements for vX"	references/router.md → requirements-generator.md
"clarify", 范围模糊，重新进行澄清	references/router.md → 通过 clarify-requirements.md 阅读 clarify-strict.md
收集信息 / 持久化来源 / 覆盖范围	references/source-registry.md + references/spec-coverage.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（高频路径）；所有单元/切片完成后 → references/orchestrator-closure.md
UI / 设计工作（屏幕没有 Layout SSoT）	references/skill-integrations.md → ns-frontend-design
UI 已注册 Layout SSoT（role: ui-layout，引用了 *-visual.md）	ns-coder 补充委派 — 阅读 SSoT；跳过 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 运行时（检测到时必须使用）

对于 agent-api 和智能 SaaS 产品，这是不可妥协的要求。参见 references/agent-runtime-integration.md。没有 agent-api/ 的全新项目：Feature 001 = langgraph 引导，然后应用版本增量。

补充集成

spec-driven / gitlab / agents 通过 ns-coder 的 depends 提供 ns-frontend-design、ns-docs-writer 和 ns-best-practices。每个会话检查一次 .agents/skills/；若存在 → 委派（references/skill-integrations.md）。若不存在（最小化安装）→ 继续并在每个会话中建议安装一次（Agent 运行时不是可选项 — 见上文）：

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

完成摘要

版本或快速修复结束时，报告：

1. 已编写或更新的产物（路径）。
2. 适用时说明交接状态。
3. 建议的下一步（动态规范完成 → 澄清下一版本；快速修复 → 可选审查）。

禁止事项

• 自动运行或串接 /ns-harness prepare。
• 将 Prepare 列为 SDD 阶段。
• 当 .agents/skills/ 中缺少补充技能时，将其设为硬性要求（存在时再委派；参见 补充集成）。
• 检测信号匹配时，未加载 ns-langgraph-agents 就规划或执行 agent-api / 智能 SaaS 工作。
• 未阅读阶段参考资料或通过 task-writer-agent 委派任务文件，就自行生成需求/任务。
• 该版本存在正式任务时，跳过 execution-handoff.md。
• 人类选择发布或并行时，跳过 delivery-units.md + Gate 4。
• 在默认的本地顺序路径上（无 GitLab 能力，且人类未提出要求）生成 delivery-units.md。
• 为每个 task-NNN 创建一个 GitLab issue，或为整个版本创建一个 issue。
• 未使用 A ∥ B，或未通过 Gate 4 选择并行，就并行执行单元。
• 使用内部阶段名称（「Specify」「Clarify」）或机器人格式用语（Reply:、Premise:）称呼人类。
• 存在尚未解决的关键未知项时进行 Specify（未获准「skip clarify」豁免）。
• 对未获答复的关键问题默默作出假设。
• Gate 1 之后编辑 docs/versions/{version_san}/sdd/source/。
• 为尚未映射的可映射源文档章节创建任务卡。
• UI 在范围内时，未编写 ui-contract.md 就创建 UI 实现任务。

调用示例

/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/sdd/

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