@peterxiaoyang/superspec 0.1.16-alpha → 0.1.17-alpha

package/templates/workflow/skills/superspec-propose/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: superspec-propose
-description: "编写计划文档（proposal/specs/design/tasks + 不变量 + 测试契约）；通过 transition 推进到 propose_ready。"
+description: "二.编写计划文档（proposal/specs/design/tasks）"
 metadata:
   author: SuperSpec
   source: SuperSpec
@@ -12,23 +12,21 @@ metadata:
 
 ## 驱动方式
 
-所有状态由 transition engine 管理。循环：
+所有状态由工作流引擎管理。循环：
 
-1. `superspec transition next --change "<change>" --risk strict` 获取下一步
+1. `superspec transition next --change "<change>"` 获取下一步
 2. 执行返回的命令
 3. 登记结果
 4. 回到 1
 
-next 返回 `required_job` 说明需要审查工作项——跑 `superspec jobs packet` 拿到工作说明，执行审查，`superspec record job-submit --change "<change>" --job <JOB> --report <FILE>`。
+next 返回需要审查时，先按返回的审查说明完成对应审查，再用 `superspec record job-submit --change "<change>" --job <JOB> --report <FILE>` 提交审查报告。
 
-本技能默认以 `risk=strict` 驱动。计划阶段进入 `propose-ready` 前必须完成这些审核工作项：
+人类可读正文默认使用简体中文；OpenSpec 结构标题、规范关键字、命令、路径、JSON 字段、代码标识符保留原文。
+如果 OpenSpec 生成文档语言不符合预期，先检查 `openspec/config.yaml` 的官方 `context` 设置；不要在变更文档里添加自定义 `language` 字段。
 
-- `proposal-auditor`
-- `critic`
-- `architect`
-- `test-engineer`
+本技能默认走完整审查路径。计划阶段进入实现前，工作流会要求 `critic`、`architect`、`test-engineer` 三个独立审查完成。
 
-所有工作项报告都必须按 packet 的 `job_report_json` 契约提交。
+所有审查工作项必须由独立角色 reviewer 执行，不能由主流程自审代替；报告必须按工作流返回的格式提交，并记录实际审查来源。
 
 ## 本阶段做什么
 
@@ -78,6 +76,23 @@ OpenSpec 能力规范增量（`openspec instructions specs` 格式）。
 | TEST-002 | INV-002 | 订单金额为负时拒绝 |
 ```
 
+### 待用户确认
+如果计划阶段遇到会影响需求范围、验收标准、用户可见行为、方案取舍、测试策略、安全、权限、数据或迁移判断的关键不确定问题，先写入相关计划文档的 `## 待用户确认` 段落：
+
+```markdown
+## 待用户确认
+
+- [ ] DEC-001 是否需要兼容历史行为？
+```
+
+`next` 会在 propose 阶段检查 `proposal.md`、`design.md` 和 `test-contract.md` 的该段落。存在未确认项时，先向用户提问；收到回答后写入 JSON 文件并执行：
+
+```bash
+superspec record user-decision --change "<change>" --input <FILE>
+```
+
+然后把用户决定反映到 proposal/design/test-contract，并将对应确认项改为 `[x]` 或移出未确认列表。局部实现细节、命名、普通文件组织和不影响需求/验收/风险的技术微调不要升级为用户确认。
+
 ## 完成条件
 
 tasks.md 作为计划文档就绪（不是复选框全完成）+ 基础职责文档齐全 → next 返回 propose-ready 命令。
@@ -85,7 +100,8 @@ tasks.md 作为计划文档就绪（不是复选框全完成）+ 基础职责文
 ## Guardrails
 
 - tasks.md 只列任务，不实现
+- 不绕过 `## 待用户确认` 中的未确认项
 - 不改业务代码
 - tdd_required 标注真实
 - 不跳过 transition
-- 不跳过 strict 模式下的审核工作项
+- 不跳过完整审查路径下的审核工作项

package/templates/workflow/skills/superspec-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: superspec-review
-description: "执行最终审查，处理 final-audit 工作项，推进到 accept。"
+description: "四.执行最终审查，处理 verifier 最终验证工作项"
 metadata:
   author: SuperSpec
   source: SuperSpec
@@ -8,28 +8,28 @@ metadata:
 
 # SuperSpec Review
 
-你是审查阶段。职责：最终审查——验证实现质量、处理最终审查工作项、推进到 accept。
+你是审查阶段。职责：最终审查——验证实现质量、处理 verifier 最终验证工作项、推进到 accept。
 
 ## 驱动方式
 
-所有状态由 transition engine 管理。循环：
+所有状态由工作流引擎管理。循环：
 
 1. `superspec transition next --change "<change>"` 获取下一步
 2. 执行返回的命令
 3. 登记结果
 4. 回到 1
 
-next 返回 `required_job` 说明需要 final-audit——跑 `superspec jobs packet` 拿工作说明，执行审查，`superspec record job-submit --change "<change>" --job <JOB> --report <FILE>`。
+next 返回需要 verifier 工作项时，先按返回的验证说明执行核对，再用 `superspec record job-submit --change "<change>" --job <JOB> --report <FILE>` 提交验证报告。
 
 ## 本阶段做什么
 
 1. **确认所有任务完成**：review-ready 会检查 tasks.md 无未完成项
-2. **处理 final-audit**：审查 proposal + 实现 + 测试契约一致性
+2. **处理 verifier**：核对 proposal + 实现 + 测试契约一致性
 3. **accept**：`superspec transition accept --change "<change>"`
 
 ## Guardrails
 
 - 不改业务代码（审查阶段只读）
-- 不跳过 final-audit 直接 accept
+- 不跳过 verifier 最终验证直接 accept
 - 审查报告必须真实引用文件内容，不编造
 - 不跳过 transition

package/templates/workflow/agents/final-audit.toml

@@ -1,13 +0,0 @@
-# SuperSpec Codex agent: final-audit
-name = "final-audit"
-description = "Final SuperSpec audit before accept"
-model_reasoning_effort = "high"
-developer_instructions = """
-Role: Final Audit. Audit final consistency between plan documents, completed tasks, test contract, and available evidence before accept.
-
-Prompt binding: load `.codex/prompts/final-audit.md` first, then read the provided job packet or `prompt_ref`. Packet refs, output kind, contract fields, and stop conditions override static prompt memory.
-
-Boundary: read-only. Do not edit files or advance workflow state.
-
-Output: submit a `job_report_json` report with `role:"final-audit"`, `verdict`, and `findings`.
-"""

package/templates/workflow/agents/proposal-auditor.toml

@@ -1,13 +0,0 @@
-# SuperSpec Codex agent: proposal-auditor
-name = "proposal-auditor"
-description = "Review proposal-stage documents before implementation readiness"
-model_reasoning_effort = "high"
-developer_instructions = """
-Role: Proposal Auditor. Audit proposal, tasks, design, discovery, business invariants, and test contract before propose-ready.
-
-Prompt binding: load `.codex/prompts/proposal-auditor.md` first, then read the provided job packet or `prompt_ref`. Packet refs, output kind, contract fields, and stop conditions override static prompt memory.
-
-Boundary: read-only. Do not edit files or advance workflow state.
-
-Output: submit a `job_report_json` report with `role:"proposal-auditor"`, `verdict`, and `findings`.
-"""

package/templates/workflow/prompts/final-audit.md

@@ -1,32 +0,0 @@
----
-description: "最终审查工作项角色"
-argument-hint: "final-audit job packet 或 prompt_ref"
----
-
-# Final Audit
-
-你是 Final Audit。你在实现完成后审查 proposal、tasks、design、discovery、business-invariants、test-contract 与当前完成状态是否一致，确认是否可以进入 accept。
-
-## 读写边界
-
-- 只读；不要修改业务代码、OpenSpec 文档或 `.superspec/**`。
-- 必须核对所有 packet 绑定文件。
-- 缺少测试证据、任务未完成、文档与实现不一致时输出 `verdict:"fail"`。
-
-## 输出格式
-
-如果 packet 的 `required_output_kind` 是 `job_report_json`，提交报告必须是 JSON：
-
-```json
-{
-  "role": "final-audit",
-  "verdict": "pass",
-  "findings": [],
-  "summary": "简短结论",
-  "evidence_refs": [],
-  "risks": [],
-  "open_questions": []
-}
-```
-
-`role`、`verdict`、`findings` 是必填字段。`verdict` 只能是 `pass` 或 `fail`。

package/templates/workflow/prompts/proposal-auditor.md

@@ -1,34 +0,0 @@
----
-description: "计划文档就绪审查角色"
-argument-hint: "proposal-auditor job packet 或 prompt_ref"
----
-
-# Proposal Auditor
-
-## 角色身份
-
-你是 Proposal Auditor。你审查 proposal/tasks/design/discovery/business-invariants/test-contract 是否足够进入实现准备阶段。
-
-## 读写边界
-
-- 只读；不要修改文件。
-- 只审查 packet 绑定的文件，不凭记忆判断。
-- 发现计划、范围、任务、测试契约或业务不变量缺口时输出 `verdict:"fail"`。
-
-## 输出格式
-
-如果 packet 的 `required_output_kind` 是 `job_report_json`，提交报告必须是 JSON：
-
-```json
-{
-  "role": "proposal-auditor",
-  "verdict": "pass",
-  "findings": [],
-  "summary": "简短结论",
-  "evidence_refs": [],
-  "risks": [],
-  "open_questions": []
-}
-```
-
-`role`、`verdict`、`findings` 是必填字段。`verdict` 只能是 `pass` 或 `fail`。