---
name: spec-author
description: 编写或优化 SPEC、执行计划和分层任务输入。核实项目定义、必要制品与评审，完成上游能力匹配、双向语义覆盖、合同标记和独立正文审阅。
---

# SPEC 编写

帮助规格作者和审阅者得到可执行的最小完整方案。裁剪对象是实现手段与重复工作，不是用户要求、真实验收或安全边界。允许结论为“当前方案无需修改”。

生成过程中，在实现方案和任务拆分定型前完成上游能力正向匹配；生成结束后，结合唯一执行计划核对匹配结论是否进入具体任务。已有实现时先判断缺的是行为、证据还是执行环境，不能把缺证直接转成重新开发。

## 0. 必要前置完成后才编写 SPEC

编写顺序固定为：从用户原始需求与已确认裁决确定行为变化、保留保证、项目和交接；读取各项目当前生效的配置、模板、profile、目录说明和阶段约定，确认迭代是否已经落在文件和调用映射上；按本次影响判断必要制品；实际完成正文、关系与适用评审；之后才输出 SPEC 和执行输入。定义存在或声明已升级不算正文已经齐备。

前置未齐时，只输出需求、具体缺口、实际补齐安排和方案讨论。不给本轮规格命名，不交付 SPEC，也不把补齐写成后续 T0 或“待完善 SPEC”。方法返回 `NEEDS_INPUT` 时保留该真实缺口，不虚构 worker，不把未评审写成通过。与该缺口没有依赖的准备工作可以继续。不得静默缩小请求范围来产出局部 SPEC。

定义适用时直接进入正文检查。无定义或存在阻断缺口时，按授权衔接 `artifact-chain-bootstrap` 或项目已经在用的维护入口，并在返回后重读实际文件。其他流程已经生效的结果直接读取，不强制重跑。旧定义仍然适用就继续沿用。不以定义不足裁掉真实需求。迭代仍不足以表达本次必要内容时，报告具体缺口，不输出 SPEC。

### 0.0 默认测试交接

<!-- @feature ACA27 @scenario S-151 -->

在必要前置制作过程中确定验证范围、接受与停止时，按`references/default-testing.md`实际调用默认plan并读取返回的业务计划；任何方向均不得仅提推荐。不要求尚不存在的未来执行结果，执行阶段条件具备后才实际衔接run。TEST负责测试方法，不代替专业制品作者和独立审阅。

### 0.1 四项判断分开写

对每个受影响项目分别给出四项结论，每项都写依据：

1. 范围依据
2. 正文充分性
3. 必要关系
4. 适用评审

每项写下实际已核实的结论和依据。必要材料、关系与评审都已完成时，已核实结论可以表示为已满足。`缺失`、`未检查`、`依据不足`、`不适用` 分别表示四种缺口，四词不是穷尽值域。不要把它们混成一个总评。

下列情况分别报告，不能互相抵消：

- 必要前置尚未创建
- 必要前置没有被引用
- 必要前置没有进入图
- 节点只指向一个缺失的附件
- 实际依赖的关系没有建立

文件存在、标题、ID、标记齐全、图校验成功或版本锁成功，都不能掩盖正文或关系缺口。`carried_into`、SPEC 引用和图影响只作定位线索，不作为范围上限。Schema 无法表达真实需求时保留需求并报告定义缺口，不把未入图自动当成业务缺失。

沿用历史正文或历史评审时，核对适用范围、版本和当前正文。变化部分必须有自己的适用评审，不全量重审未变化的历史。开发前测试规格与开发后真实执行结果分开记录，开发前不索要尚未发生的执行结果。

### 0.2 独立全文审阅与开发补漏

前置专业评审和完整 SPEC 审阅是两项不同职责，不能互相补签。前置完成后，由不同职责在同一轮集中审阅中先复核范围依据，再核对完整正文和必要附件。作者整理的来源表只是导航，不是审阅范围上限。审阅者必须主动查找作者遗漏的必要来源。

开发补漏或遗留补档仍先了解需求影响和有效定义：

- 事实明确，只缺说明或关系：按授权补齐并复审受影响制品、SPEC 和实现。
- 实现偏离已批准设计：报告冲突，交给相应职责，不在规格里隐性改要求。
- 意图不明：保留待确认。不从代码反推批准需求，不倒填历史。
- 没有真实方法返回时，不报告闭环通过。

### 0.3 来源索引、增量正文与项目模板

SPEC 由两部分组成：来源索引，加上本轮相对基线的增量正文。完整 PRD、场景和详细设计仍由原制品维护。索引写明制品身份、具体章节、本轮采用的内容和版本依据。版本依据使用项目现有 Git 引用、版本锁或本轮评审记录。引用未提交正文时写明工作树基线，并指向已经核验的评审快照。`HEAD` 不是未提交正文的版本。不能只凭摘要声称可以恢复全文。

增量正文依据已核实的产品需求与设计，描述规格所定义的产品变更：目标行为、保留要求、关键实现决定、实现涉及的源文件、派生物、外部对象及可观察验收。关键实现指向已评审设计的具体章节。执行计划独立引用，不把完整任务进度复制进 SPEC。不得只放链接，也不得复制整份制品变成第二份日常正文。

默认对照插件 `templates/core/spec-entry.starter.md`。该模板保留五个生命周期章节和全部合同标记：`changes`、`scope`、`acceptance`、`acceptance-record`、`archive-record`。项目已经有实际模板时，以项目模板为准。

## 1. 限定本次检查

按本次任务选择编写、改稿或只读审阅，并明确关注的风险与阶段。

读取适用的 AGENTS.md、用户原目标及当前 SPEC、执行计划中本次判断所需的完整内容。先从现行入口确认权威关系与读取范围，不默认把原规格、返工规格和全部复审材料一起加载。再按风险阅读直接相关的接口、调用方、测试或证据。缺材料时给出条件结论，不补造项目事实。

不默认检索全部会话、扫描所有项目、运行全量测试或安排多个审阅者。不为本技能建立计划树、评分表、证据登记表或执行器。短小改动只检查实际相关项。

## 2. 先保护结果，再裁剪手段

从原目标确认用户可观察的结果、真实使用场景、兼容要求、安全边界和完成条件。执行者生成的设计、自测结果与完成报告不能覆盖这些要求。

对拟修改内容逐项询问：

- 删除后，哪一项用户结果、合同或已观察故障会失去保证？没有具体答案时，优先移除或延后该手段。
- 现有实现或上游公共能力能否覆盖？按行为保证归为直接采用、薄层适配、领域实现或上游缺口，不按文件名或所在仓库归类。
- 当前复杂度来自真实必要条件，还是未来预留、对称性、保险检查或验证器自身的要求？

比较能够完成同一目标的完整方案。不能让轻方案省掉安全要求，再据此认定重方案更可靠；也不能用“优化”名义删除原验收。改变目标、合同、权限或权威归属的建议单列，等待所需裁决。

## 3. 规格阶段完成正向能力匹配

在方案和任务拆分定型前，从本次实际场景出发主动查找可复用能力。优先核对项目已有工具和已声明上游；发现新的共性处理需要时，再查询相关公共能力。匹配结果用于确定实现与验证方式。

在拆写集、估工期和委派之前，读取 [上游能力正向匹配](references/capability-matching.md)，按当前版本的公开能力逐项问“本次哪个场景可以使用”。对命中项读取公共合同与现有接线，再核对 SPEC 的拟建脚本是否重复。通用处理即使被命名为领域脚本，也必须拆开比较。

将结论直接写进权威 SPEC 的“底层能力采用与编排”部分。每个采用项必须明确场景、提供方与精确版本、能力 ID 或公共入口、调用位置和输入输出、项目保留职责、验证方式、产品安全要求和外部动作；任务表引用同一结论，不再维护副本。与方案有关但未采用的候选须给出具体理由；没有相关场景的检索提示无需写入正文。

生成或优化 SPEC 时，按能力匹配参考第 6 节核对本轮 SPEC 与相关制品的双向语义覆盖，并沿用该节的处置表。

缺少会改变接口、写集或验证方式的能力事实时，该切片仍是待决草稿，不能交给执行者“自行选择上游或自建”。已选择的入口允许执行时核对环境和填入由事实确定的参数；更换提供方、版本、机制、职责或测试编排时，先修订同一 SPEC 的受影响决定。

## 3.1 修改粒度、删除重命名与反例

读取 [规格修改与审阅方法](references/openspec-methods.md)，并在语义准备、对照组织和交付核对中实际使用：

- 以完整需求及全部相关场景为修改单位；
- 分别检查删除与重命名；
- 按需求展示基线与目标差异；
- 把配置结构错误交给现有加载与 `artifact-chain-setup` 诊断；
- 关系配置的结构、取值与诊断按上述参考第 4 节核对；
- 识别遗漏场景、同名异义、空材料和勾选无证据。

需求登记、add/modify/delete 回写和 SPEC 条目创建仍由 `artifact-chain-requirements` 负责。本技能在材料缺口处引导进入已有制作与评审入口，不汇总审阅结果，不自造审阅控制器。profile 或 worker 未就绪时如实报告未评审，不伪造通过。

## 3.2 标记合同与独立正文审阅

生成或优化完整 `SPEC` 时，先确认目标项目实际采用的合同，再对完整新 `SPEC` 做两层检查。标记通过不等于业务完整；上游 PRD 审阅、已有 `prd-feature/review` 结论、前置专业评审，以及通用 `review` 的目录或就绪结果，都不能代替本轮独立的完整 `SPEC` 正文审阅。前置专业评审与完整 SPEC 审阅不能互相补签。独立审阅先复核范围依据，再核对完整正文和必要附件；作者来源表只是导航，不是审阅范围上限，审阅者必须主动查找遗漏的必要来源。

官方合同身份是 `artifact.spec@1`，声明源只在 Graph 包 `contracts/spec/schema.json`。`authority` 与 `namespace` 均为 `artifact`。本技能采用该合同，不在助手参考目录复制另一份同身份 schema，也不新增加载器、导出或注册表。

采用步骤：

1. 读取目标项目实际使用的 SPEC 模板。默认对照插件 `templates/core/spec-entry.starter.md`；项目另有模板时以项目实际文件为准。SPEC 写来源索引和本轮增量正文。`HEAD` 不是未提交正文的版本。执行计划独立引用。
2. 用现有 CLI `artifact-graph contract explain --contract artifact.spec@1 --contracts-dir <contracts> --format json` 读取真实 `identity`、`revisionDigest` 和 `semanticMarkers`。摘要以本次 `explain` / `loadContract` 结果为准，不在技能正文维护平行常量。
3. 有效机械采用必须看到非空的必需标记集合，覆盖三个业务槽：`changes`（行为变更及完整场景）、`scope`（修改范围与项目边界）、`acceptance`（可观察验收）。`acceptance-record`、`archive-record` 是可选标记，对应正式模板里原有的验收与归档正文；执行草稿不得把未完成项写成 `passed` 或伪造归档。
4. 对完整新 `SPEC` 调用现有 `artifact-graph contract validate-markers`，提供真实参数：`--contract artifact.spec@1`、`--contracts-dir`、`--revision-digest`（与本次 `explain` 一致）、`--markdown`（完整 SPEC 路径）、`--format json`。不得用 `contract validate` 或 `normalize` 冒充正文验证。`jsonPointer` 只描述同一语义槽，本命令不解引用，也不声称已验证指针映射。
5. 标记齐全后，交由不同职责方只读审阅完整正文、业务来源和必要附件。两层都通过，才可完成 `SPEC` 验收。 独立职责实际读取 `<plugin-root>/skills/artifact-review/references/type-methods.md` 的 `spec` 方法；采用 `artifact-review spec` 路由时，仍须通过原项目 profile 就绪检查并提交真实独立语义 Review Result。缺少 profile、输入或审阅结果时如实保留缺口，不以通用 worker 补签。

拒绝把下列情况写成机械通过：未知合同；合同未定义或 `semanticMarkers` 为空；只有可选标记、缺少任一必需标记；重复标记；未知标记。内核仍对无标记合同保持兼容（未定义时校验器返回 valid）；宿主必须阅读真实 `explain` 结果再判断，不能把兼容空集当成本轮有效采用。

采用前确认实际安装的 Graph 包提供 artifact.spec@1，并按正式包或工作树候选的真实来源记录身份。缺少合同或必需标记定义时，报告具体缺口。隔离消费从实际安装包定位合同。

项目可显式采用自身合同，但必须使用自身身份并有项目采用依据，不得冒用 `artifact` 官方身份。正式 starter 仍保留原五节生命周期规则。

## 4. 将规格组织为可承接的执行输入

多职责、跨会话或存在任务依赖时，读取 [执行编排与分层读取](references/execution-contract.md)，交付业务规格、独立启动单、唯一公共执行计划和各职责的任务文件。沿用项目现有文件；单职责、窄写集且无跨会话交接的小改动可以保持单文件。

SPEC 定义产品结果、合同、产品实现范围、底层能力采用及验收。公共计划安排产品实施任务的依赖、职责、读写集、交接、验证和进度。启动单明确产品执行目标、首个动作及完成条件，任务文件说明各职责如何交付其完整结果。

从承接者可见的输入顺读主会话启动、代表实现和独立审阅路径，继续展开必读引用。各职责完整取得当前任务所需的业务合同，不默认加载全部领域和历史。具体读取方法与交付核对按执行参考第 3、5 节完成。

评审、方法绑定或业务输入存在真实缺口时，写清受影响任务、缺少的材料及满足条件；任务写集使用实际文件路径。用户限定单文件或局部修改时，交付范围内的结果并说明尚未完成的结构部分。

## 5. 核对产品实现路径

集中检查事实与复用、依赖与编排、验证与证据、收尾与成本。只展开存在信号的部分。每项验收指出真实入口、输入、应观察的业务结果和最近的既有检查。退出 0、产物存在和模型自报不代替完整业务值验收。

实现和返工使用成组聚焦测试；稳定快照集中审阅、统一裁决和修复，批末运行权威完整门禁。不把完整测试改名为聚焦测试。不为前置检查新增包装器。

## 6. 按风险补查，不常驻展开

SPEC 涉及测试分组、并行、昂贵初始化或跨阶段复用时，读取宿主可发现的 `test-performance-optimizer`。没有慢测试证据时，优先沿用既有策略。Foundation 命中项的采用诊断使用可用的 `foundation-adoption-review`。专项技能不可用时说明限制，只给范围内建议。

遇到阶段循环、入口受限、反复交接、上下文成本、风险裁决或收尾状态混用时，读取 [条件检查](references/conditional-checks.md)。

## 7. 文档生成后优化可读性

本技能生成或修改的各类中文文档，在内容成稿后、最终交付核对前，按插件内已发布公共参考执行拟稿与核收。执行本节前，必须从当前插件安装根完整读取：

- `$PLUGIN_ROOT/skills/spec-author/references/shared-writing-workflow.md`
- `$PLUGIN_ROOT/skills/spec-author/references/expression-service-config.md`

两份参考与 Docs 公开发布版本 `skill-family-docs-v0.6.7`（提交 `7433554d2e2995729c2aafee52eb525ca827446d`）字节一致。不要改写这两份参考；更新只能来自明确采用的新发布版本。运行时不依赖 Docs 工作树、Docs 已安装或个人技能目录。隔离插件只要带有本技能树，即可定位两份参考和表达脚本。

公共参考按原字节保留。本入口补充本领域边界，不改写参考正文：

- 只读审校可以定位事实、理解和表达问题，但不修改受检正文，也不自动把整份私有材料发给模型。
- 本轮新写的中文报告仍须按已有授权走本节优化，并经宿主核收后交付。
- 材料可以是公开材料，或已有明确外发授权的材料。不得把 Docs 站点的公开材料限制扩到 Artifact。
- 表达优化不能改变验收、依赖、职责、授权、停止条件或规则强度；技术合同、代码、命令、路径、版本、任务 ID 和机器字段保持原值。

脚本路径为 `$PLUGIN_ROOT/skills/spec-author/scripts/expression-outbound.mjs`。它与 Docs 公开发布版本 `skill-family-docs-v0.6.6`（提交 `084b53a60bf871dd311e3eb62b398a9c48e3821b`）字节一致；该脚本与 0.6.7 公开脚本字节相同，本轮保留 0.6.6 来源声明，不升级脚本版本。不要修改该副本。

配置沿用 `SKILL_FAMILY_DOCS_ENDPOINT`、`SKILL_FAMILY_DOCS_MODEL`、`SKILL_FAMILY_DOCS_CREDENTIAL_ENV`（值为存放凭据的环境变量名）。配置检查只通过 `artifact-chain-setup` → `$PLUGIN_ROOT/scripts/setup-checks.mjs` 进行。公共配置参考里的示例命令不是第二套检查入口，不自动从 `LLM_*` 补齐，配置存在不等于服务可用。缺配置、调用失败、候选拒收或材料未获授权时，语义审阅、图查询与机械检查可以继续，但必须报告“可读性优化未完成”。凭据不得进入材料、命令参数、候选或日志。公开产品不得硬编码模型名、服务地址或 API key。

按已读取的公共写作流程执行，不得另建阶段状态、runner 或第二套表达脚本：

1. 先读完全文材料，明确读者、阅读任务和必须保留的机器身份，并写入已纠正失效事实的完整材料。
2. 用同一脚本生成仓外大纲候选；宿主审核大纲后另存审核大纲。
3. 按完整语义单元顺序拟稿；每次只提供当前单元及必要事实。短文传入全部已接受前文，长文传入上一节全文和更早内容的覆盖摘要。第一节写明没有前文。
4. 只有宿主接受的稿可以作为后续小节前文。待审候选不能充当前文。
5. 各节接受后拼接全文，做事实覆盖核对和目标读者冷读。

候选必须写到仓外绝对路径。脚本没有接受权、没有重试、没有语义判断。交付时分别报告外发表达步骤状态与宿主语义核收状态：前者以脚本实际返回为准，后者覆盖大纲审核、各节核收、全文核对和冷读的实际范围。候选产生、失败或退出码 0 都不代表文档通过。

## 8. 一次收敛并交付

集中输出有依据的修改；每项说明观察、最小调整、保留的验收及预期减少的成本。无实测时不填节省百分比或精确耗时。

允许改稿时更新第 4 节要求的整组执行输入；只读时返回对应缺口，不改文件。交付前按执行编排参考第 5 节完成一次集中核对，并按能力匹配参考第 6 节与 [规格修改与审阅方法](references/openspec-methods.md) 再做覆盖与反例核对。风格、链接、图关系或版本锁检查通过，以及图边或 ID 能够对应，都不能代替 SPEC 与相关制品正文的语义覆盖。

文档齐全但仍有覆盖未决时，报告“文档已整理，相关任务暂不可委派”，并写明等待补充评审还是等待用户裁决。只做规格优化就如实声明尚未实施。

完整 SPEC 的前置条件以第 0 节为准；标记合同和独立正文审阅按第 3.2 节完成。