speccore 8.3.275 → 8.3.276

package/.agents/skills/spec-once/SKILL.md

@@ -6,6 +6,8 @@ description: >
   双模式：默认人机交互（每个节点停下确认）；用户说「全自动/自动跑/别停」时切全自动模式（节点间不等待，
   但范围确认、质量门禁失败、冒烟失败仍停下）。支持步骤回退重跑（重分析 / 重拆指定模块 / 重执行单任务）。
   触发词：spec once、/once、一次跑完、快速跑、快速分析、小步快跑、端到端 等。
+  用户仅询问使用方法（「spec-once 怎么用 / 使用说明 / 使用步骤 / 能干什么」）时不启动流程，
+  按正文「使用说明」节输出纯文字指南，不要执行任何 speccore 命令。
   与流水线（speccore run/dev）的区别：spec-once 由宿主 AI 单会话编排现有命令，
   覆盖「开发到部署验证」的快速闭环（不含 PR 提交/归档收尾，那些按需走 pr/done），
   适合少量功能单元（建议 ≤3 个）的快速推进；大范围多单元请走流水线。
@@ -15,6 +17,36 @@ disable-model-invocation: false
 
 # spec-once — 单会话端到端执行
 
+## 使用说明（用户仅询问「怎么用/使用说明/使用步骤/能干什么」时，输出本指南，不启动流程）
+
+**它是什么**：SpecCore 的单会话端到端编排技能——把「需求 → 澄清 → 分析 → 拆分任务 → 开发 → 冒烟 → 部署验证」整条链在这一次对话里跑完，全程由 AI 按剧本编排 speccore 命令。
+
+**怎么触发**：直接对 AI 说，例如：
+- 「spec once，帮我从 features/ 下的门禁授权同步开始跑」
+- 「一次跑完这个文档：/path/to/PRD.docx」
+- 「小步快跑：做一个会议室签到功能」（一句话需求也可以）
+
+**三种入口**：
+1. **已切好的功能单元**——说单元名或「全部」（建议 ≤3 个，多了建议走流水线）
+2. **一个需求文档地址**——.md 直接切分；.docx/.pdf 先转 Markdown 再切分
+3. **一句话需求**——AI 先整理成 PRD 级需求文档，再切分
+
+**两种执行模式**：
+- **人机交互（默认）**：每个节点停下等你确认（范围 → 分析 → 拆分 → 执行 → 冒烟 → 部署），适合要盯过程的场景
+- **全自动**：说「全自动/别停下」即可，节点间不等待；只有三个安全点会停下：范围确认、质量门禁失败、冒烟失败
+
+**六步流程**：① 范围确认 → ② 澄清与分析（生成 020-specs 规格文档）→ ③ 拆分任务（生成 030-tasks 任务）→ ④ 执行开发（生成代码）→ ⑤ 本地冒烟（编译+测试）→ ⑥ 本地部署验证（默认不自动执行，要你说「部署」才做）
+
+**跑完后可继续**：`speccore pr` 提交代码建 PR、`speccore done` 归档收尾（按需，不自动）。
+
+**哪一步不满意可回退重跑**：
+- 分析不好 → 重分析该单元（覆盖前自动备份）
+- 拆分不合理 → 只重拆指定模块（旧任务自动备份，其它保留）
+- 执行不满意 → 重执行单个任务
+- 切分不理想 → 重切同名单元三选一（跳过/覆盖/重命名）
+
+**适用边界**：少量单元（≤3）的快速闭环；不适合大范围多单元（走 `speccore run` 流水线）。
+
 ## 定位
 把「澄清→分析→拆分→执行→冒烟→部署验证」六步装进一次会话，一步到位。
 底层全部复用 speccore 现有命令，本 skill 只做编排与交互节点（像 article-to-html 一样

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speccore",
-  "version": "8.3.275",
+  "version": "8.3.276",
   "description": "SpecCore - Code by Spec, Not by Vibe.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",