@gepeiyu/smart 0.1.2 → 0.1.3

package/README.md

@@ -1,22 +1,20 @@
-# Smart — 把 GitHub Issue 当作全流程变更容器
+# Smart — OpenSpec 五阶段变更流程 + GitHub Issue 双向同步
 
-> 一条 Issue = 一次 `issue → design → build → verify → archive`；Issue 关闭即变更归档。
+> 一次变更 = `issue → design → build → verify → archive` 五阶段；容器是 OpenSpec change。
 
-Smart 是一个 agent skill：AI agent 读到一条 GitHub Issue 后，把它当作从需求到归档的整条变更流水线推进——读 Issue 取需求（`gh issue view`）、各阶段向 Issue 回写进度（`gh issue comment`）、归档时关闭 Issue（`gh issue close`）。状态机由纯 Bash 脚本驱动，工具中性。
+Smart 是一个 agent skill，把一次变更按五阶段推进，状态机由纯 Bash 脚本驱动、工具中性。**变更的容器是 OpenSpec change**（`openspec/changes/<name>/` 里的 proposal/design/specs/tasks + `.smart.yaml`，贯穿全生命周期）。可选地，把变更与一条 GitHub Issue 双向同步：从 Issue 取需求、向 Issue 回写进度、归档时关闭 Issue。
 
-## Issue 在 Smart 里是什么
+## Issue 双向同步（可选）
 
-一条 Issue 不只是待办项，而是**一个变更的完整生命周期容器**：
+**容器是 OpenSpec change，不是 Issue。** Issue 只是变更与 GitHub 之间的一个可选同步面：
 
-| 阶段 | Issue 的角色 |
-|------|-------------|
-| issue | 触发源——`gh issue view` 读正文/评论，解析为目标/范围/验收 |
-| design | 进度面——回写 Design Doc 链接 |
-| build | 进度面——每完成一个 task 回写勾选进度 |
-| verify | 结论面——回写验证结论 |
-| archive | 关闭信号——`gh issue close`，Issue 关闭 ≈ 变更归档 |
+| 方向 | 时机 | 动作 |
+|------|------|------|
+| 入 | issue 阶段 | `#ID` 触发时 `gh issue view` 读正文/评论作为需求种子（和直接打字 `<描述>` 等价，只是更方便） |
+| 出 | 各阶段边界 | `gh issue comment` 向 Issue 回写进度（收纳 / Design Doc / 任务勾选 / 验证结论） |
+| 出 | archive | `gh issue close` 关闭 Issue，让它跟着 change 走完 |
 
-OpenSpec 负责规格（`openspec/specs/` + `openspec/changes/` + `openspec/changes/archive/` 三层），纯 Bash 脚本负责状态机（`.smart.yaml`），Superpowers 负责设计与执行方法论。
+`issue_number` 为 null（用 `<描述>` 触发、或 dogfood）时，脚本跳过所有 `gh` 读写，本地流程照常完整。OpenSpec 负责规格（`specs/changes/archive` 三层），纯 Bash 脚本负责状态机（`.smart.yaml`），Superpowers 负责设计与执行方法论。
 
 ## 安装
 
@@ -80,7 +78,7 @@ gh issue create --title "..." --body "..."         # 建一条 Issue
 /smart（检测阶段）
   ↓
 /smart-issue ──→ /smart-design ──→ /smart-build ──→ /smart-verify ──→ /smart-archive
-   读 Issue         Design Doc        实现代码          验证报告          gh issue close
+  读 Issue/描述      Design Doc        实现代码          验证报告        归档（+可选 gh issue close）
 
 /smart-hotfix：issue → build → verify → archive（跳过 brainstorming）
 /smart-tweak：  issue → 轻量 build → 轻量 verify → archive

package/SKILL.md

@@ -5,16 +5,12 @@ description: "Smart — OpenSpec + Superpowers 双星开发流程。用 /smart
 
 # Smart — OpenSpec + Superpowers 双星开发流程
 
-OpenSpec 与 Superpowers 如双星系统围绕同一目标运转。
-
 ```
 OpenSpec 负责 WHAT  — 大纲、提案、spec 生命周期、归档
 Superpowers 负责 HOW — 技术设计、计划、执行、收尾
 ```
 
-**核心原则：brainstorming 必不可跳过。每次变更都必须经过深度设计（hotfix 和 tweak preset 除外）。**
-
----
+**核心原则：brainstorming 不可跳过。每次变更都必须经过深度设计（hotfix 和 tweak preset 除外）。**
 
 ## 决策核心（Decision Core）
 
@@ -44,6 +40,8 @@ agent 做决策只需读本节，参考附录按需查阅。
 | 恰好 1 个 | `/smart`（无描述） | → 自动选中，进入 Step 1 |
 | 多个 | `/smart`（无描述） | → 列出清单让用户选择 |
 
+**`#` 前缀特殊处理**：若用户参数以 `#` 开头（如 `/smart #42`），视为 Issue 触发的新变更，路由到 `/smart-issue #42`——由 smart-issue 做 gh 状态确认（`gh auth status`）与 Issue 内容拉取（`gh issue view <id>`）。**issue 非流程必需**，仅作需求来源与可选同步面；不绑 Issue（描述触发）时流程照常完整。
+
 <IMPORTANT>
 当用户选择「创建新变更」时，**必须调用 `/smart-issue`**（禁止直接调用 `/opsx:new`）。
 `/smart-issue` 负责完整双初始化：OpenSpec artifacts（由内部 `/opsx:new` 创建）+ `.smart.yaml` 状态文件。
@@ -135,8 +133,6 @@ agent 做决策只需读本节，参考附录按需查阅。
 
 agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须自动继续推进，不得中途退出。到达决策点时，**禁止跳过用户确认或自动选择——必须通过当前平台可用的用户输入/确认机制明确获取用户选择后才能继续**。
 
-**红旗清单** — 以下想法出现时立即停止并检查：
-
 | Agent 心理 | 实际风险 |
 |-----------|---------|
 | "用户应该会同意这个方案" | 不能替用户决策，必须等待用户明确选择 |
@@ -146,8 +142,6 @@ agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须
 | "流程走到这里应该没问题了" | 验证不通过 ≠ 通过，检查 verify_result |
 </IMPORTANT>
 
----
-
 ## 子命令速查
 
 | 命令 | 阶段 | 归属 | 产物 |
@@ -175,8 +169,6 @@ agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须
     ↑ 如触发升级条件 → 阻塞确认升级 → 补充 Design Doc → 回到完整流程
 ```
 
----
-
 ## 参考附录（Reference Appendix）
 
 > 字段说明、文件结构和自动衔接协议已提取为渐进式加载参考文档，按需查阅：

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gepeiyu/smart",
-  "version": "0.1.2",
-  "description": "Smart — GitHub Issue 驱动的 OpenSpec 变更流程 agent skill",
+  "version": "0.1.3",
+  "description": "Smart — OpenSpec 五阶段变更流程 agent skill（可选 GitHub Issue 双向同步）",
   "type": "module",
   "bin": {
     "smart": "./bin/smart.js"

package/smart-hotfix/SKILL.md

@@ -5,8 +5,6 @@ description: "Smart 预设路径：Bug fix / 热修复。跳过 brainstorming，
 
 # Smart 预设路径：Hotfix
 
-快速 bug fix 工作流：issue → build → verify → archive。跳过 brainstorming 和完整 plan，适用于行为修复、不涉及新 capability 设计的场景。
-
 **适用条件**（必须全部满足）：
 1. 修复已有功能的 bug，不新增 capability
 2. 不涉及接口变更或架构调整
@@ -14,8 +12,6 @@ description: "Smart 预设路径：Bug fix / 热修复。跳过 brainstorming，
 
 **不适用**：如修复过程发现需要架构调整，应升级为完整 `/smart` 流程。
 
----
-
 ## 流程（preset workflow，6 步）
 
 ### 0. 输出语言约束
@@ -136,25 +132,17 @@ fi
 **立即执行：** 使用 Skill 工具加载 `smart-archive` 技能进行归档。禁止跳过此步骤。
 如有 delta spec，按 smart-archive 规则同步到 main spec，并处理关联 Design Doc 与 Plan 的归档标注。
 
----
-
 ## 连续执行模式
 
 <IMPORTANT>
-Hotfix 流程默认 **一次性连续执行**。调用 `/smart-hotfix` 后，agent 在 hotfix 自有步骤间自动推进，不主动停顿。**例外**：若 `auto_transition: false`，则在每个 phase 边界（build/verify/archive 之间）停下，由用户手动运行下一阶段命令——此时连续执行降级为逐阶段手动推进，详见下方「自动衔接下一阶段」。但无论 `auto_transition` 取何值，以下情况都必须暂停等待用户确认：
-
-1. 遇到升级条件（见"升级条件"章节），**必须使用当前平台可用的用户输入/确认机制暂停并等待用户明确确认**升级为完整流程
-2. 任务超过 3 个转入 `/smart-build` 时的工作区隔离和执行方式选择
-3. 验证阶段（smart-verify）的验证失败决策和分支处理决策
-4. 归档前最终确认（smart-archive 执行归档脚本前）
+默认一次性连续执行。`auto_transition: false` 时在 phase 边界停下由用户手动推进。无论 `auto_transition` 取值，以下情况必须暂停等待用户确认：
 
-执行顺序：快速开启 → 直接构建 → 根因消除检查 → 验证 → 归档 → 完成
-
-每个阶段完成后立即进入下一阶段。阶段内部仍必须按上文要求调用对应 Smart/OpenSpec/Superpowers skill，被调用的 skill 如有自己的用户决策点，按该 skill 规则执行。
+1. 升级条件触发 → 暂停确认升级
+2. 任务 > 3 转入 `/smart-build` → 选择隔离/执行方式
+3. 验证失败决策和分支处理决策
+4. 归档前最终确认
 </IMPORTANT>
 
----
-
 ## 升级条件
 
 满足以下**任一**条件时，停止 hotfix 流程，升级为完整 `/smart`：
@@ -178,8 +166,6 @@ Hotfix 流程默认 **一次性连续执行**。调用 `/smart-hotfix` 后，age
 
 然后在当前 change 基础上补充 Design Doc：**立即使用 Skill 工具加载 `smart-design` skill**，后续正常走完整流程。若用户不确认升级，停止 hotfix 并报告当前变更已超出 hotfix 适用范围。
 
----
-
 ## 退出条件
 
 - Bug 已修复，测试通过

package/smart-issue/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: smart-issue
-description: "Smart 阶段 1：开启（issue）。用 /smart-issue 调用。从 GitHub Issue（#ID 经 gh 拉取）或描述出发，通过 OpenSpec 探索、澄清，创建 change 结构（proposal + design + tasks + .smart.yaml）。"
+description: "Smart 阶段 1：issue。用 /smart-issue 调用。从描述或 GitHub Issue（#ID 经 gh 拉取）出发，经 OpenSpec 探索澄清，创建 change 结构。"
 ---
 
 # Smart 阶段 1：issue（开启）
@@ -8,7 +8,7 @@ description: "Smart 阶段 1：开启（issue）。用 /smart-issue 调用。从
 ## 前置条件
 
 - 无活跃 change，或用户希望创建新 change
-- 触发源：`/smart-issue <描述>` 或 `/smart-issue #<issue-id>`
+- 触发参数：`/smart-issue <描述>` 或 `/smart-issue #<issue-id>`（需 gh 已登录）
 
 ## 步骤
 
@@ -16,19 +16,15 @@ description: "Smart 阶段 1：开启（issue）。用 /smart-issue 调用。从
 
 传递给 OpenSpec 的所有提问和产物要求都必须包含输出语言约束：使用触发本次工作流的用户请求语言。恢复已有 change 且产物已有明确主语言时，除非用户明确要求切换，否则保持该语言。
 
-### 1. 触发源解析与需求种子
+### 1. 触发源解析
 
-**两种触发方式**：
+- **参数以 `#` 开头**（如 `#42`）→ Issue 模式：
+  1. `gh auth status` 确认登录；未登录则报错并提示 `gh auth login`，停止。
+  2. `gh issue view <id> --json number,title,body,comments,labels` 按 `#` 后 id 拉取 Issue 内容。
+  3. 解析为需求种子；记 `issue_number=<id>`、`issue_repo=<owner/repo>`。
+- **其他/无参数**（描述）→ 描述模式：描述即种子，`issue_number=null`。
 
-- **`/smart-issue #<id>`**（Issue 驱动）：从 GitHub Issue 拉取需求种子。立即执行：
-
-  ```bash
-  gh issue view <id> --json number,title,body,comments,labels
-  ```
-
-  将 Issue 的 `title` + `body` + `comments` 解析为需求种子（目标/非目标/范围边界/验收场景线索）。记下 `issue_number=<id>` 与 `issue_repo=<owner/repo>`（取 gh 默认 repo，或用户以 `--repo` 指定）。后续阶段会向该 Issue 回写进度，归档时关闭它。
-
-- **`/smart-issue <描述>`**（描述驱动）：用户描述即需求种子，`issue_number=null`（用户稍后可回填）。
+两种模式后续流程一致。issue 非必需，仅作需求来源与可选同步面。
 
 **立即执行：** 使用 Skill 工具加载 `openspec-explore` 技能。禁止跳过此步骤。
 

package/smart-tweak/SKILL.md

@@ -5,9 +5,7 @@ description: "Smart 预设路径：非 bug 的小改动（tweak）。跳过 brai
 
 # Smart 预设路径：Tweak
 
-Tweak 是 Smart 五阶段能力的预设工作流，不是独立的平行流程。它复用 issue、build、verify、archive 能力，仅跳过 brainstorming 和完整 plan。
-
-适用于非 bug 的小范围变更，例如文案调整、配置调整、文档或 prompt 的局部优化。
+Tweak 复用 issue、build、verify、archive 能力，跳过 brainstorming 和完整 plan。适用于文案、配置、文档或 prompt 的局部优化。
 
 **适用条件**（必须全部满足）：
 1. 不新增 capability
@@ -17,8 +15,6 @@ Tweak 是 Smart 五阶段能力的预设工作流，不是独立的平行流程
 
 **不适用**：如变更过程中发现需要 capability、架构或接口调整，应升级为完整 `/smart` 流程。
 
----
-
 ## 流程（preset workflow，4 阶段）
 
 ### 0. 输出语言约束
@@ -112,24 +108,16 @@ fi
 
 **立即执行：** 使用 Skill 工具加载 `smart-archive` 技能进行归档。禁止跳过此步骤。
 
----
-
 ## 连续执行模式
 
 <IMPORTANT>
-Tweak 流程默认 **一次性连续执行**。调用 `/smart-tweak` 后，agent 在 tweak 自有步骤间自动推进，不主动停顿。**例外**：若 `auto_transition: false`，则在每个 phase 边界（build/verify/archive 之间）停下，由用户手动运行下一阶段命令——此时连续执行降级为逐阶段手动推进，详见下方「自动衔接下一阶段」。但无论 `auto_transition` 取何值，以下情况都必须暂停等待用户确认：
-
-1. 遇到升级条件（见"升级条件"章节），**必须使用当前平台可用的用户输入/确认机制暂停并等待用户明确确认**升级为完整流程
-2. 验证阶段（smart-verify）的验证失败决策和分支处理决策
-3. 归档前最终确认（smart-archive 执行归档脚本前）
+默认一次性连续执行。`auto_transition: false` 时在 phase 边界停下由用户手动推进。无论 `auto_transition` 取值，以下情况必须暂停等待用户确认：
 
-执行顺序：快速开启 → 轻量构建 → 轻量验证 → 归档 → 完成
-
-每个阶段完成后立即进入下一阶段。阶段内部仍必须按上文要求调用对应 Smart/OpenSpec/Superpowers skill，被调用的 skill 如有自己的用户决策点，按该 skill 规则执行。
+1. 升级条件触发 → 暂停确认升级
+2. 验证失败决策和分支处理决策
+3. 归档前最终确认
 </IMPORTANT>
 
----
-
 ## 升级条件
 
 满足以下**任一**条件时，停止 tweak 流程，升级为完整 `/smart`：
@@ -154,8 +142,6 @@ Tweak 流程默认 **一次性连续执行**。调用 `/smart-tweak` 后，agent
 
 然后在当前 change 基础上补充 Design Doc：**立即使用 Skill 工具加载 `smart-design` skill**，后续正常走完整流程。若用户不确认升级，停止 tweak 并报告当前变更已超出 tweak 适用范围。
 
----
-
 ## 退出条件
 
 - 小改动已完成，测试通过