@gepeiyu/smart 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +84 -55
  2. package/SKILL.md +3 -11
  3. package/package.json +2 -3
  4. package/smart-hotfix/SKILL.md +5 -19
  5. package/smart-issue/SKILL.md +9 -13
  6. package/smart-tweak/SKILL.md +5 -19
package/README.md CHANGED
@@ -1,13 +1,22 @@
1
- # Smart — GitHub Issue 驱动的 OpenSpec 变更流程 agent skill
1
+ # Smart — OpenSpec 五阶段变更流程 + GitHub Issue 双向同步
2
2
 
3
- Smart 让 AI agent 把一个 GitHub Issue 当作 `issue → design → build → verify → archive` 全流程容器推进，直到 Issue 可关闭。一条 Issue = 一个 OpenSpec change；Issue 关闭 ≈ change 归档。
3
+ > 一次变更 = `issue → design → build → verify → archive` 五阶段；容器是 OpenSpec change。
4
4
 
5
- - **工具中性**：`SKILL.md` 主体不依赖任何 agent 工具专有语法
6
- - **纯 Bash 状态机**：`scripts/smart-*.sh`，所有工具都能 `bash scripts/smart-*.sh` 直接跑
7
- - **OpenSpec 复用**：`openspec/specs/` + `openspec/changes/` + `openspec/changes/archive/` 三层
8
- - **Issue 驱动**：`gh issue view` 读取、`gh issue comment` 回写、`gh issue close` 归档
5
+ Smart 是一个 agent skill，把一次变更按五阶段推进，状态机由纯 Bash 脚本驱动、工具中性。**变更的容器是 OpenSpec change**（`openspec/changes/<name>/` 里的 proposal/design/specs/tasks + `.smart.yaml`，贯穿全生命周期）。可选地，把变更与一条 GitHub Issue 双向同步：从 Issue 取需求、向 Issue 回写进度、归档时关闭 Issue。
9
6
 
10
- ## 安装（npm）
7
+ ## Issue 双向同步（可选）
8
+
9
+ **容器是 OpenSpec change，不是 Issue。** Issue 只是变更与 GitHub 之间的一个可选同步面：
10
+
11
+ | 方向 | 时机 | 动作 |
12
+ |------|------|------|
13
+ | 入 | issue 阶段 | `#ID` 触发时 `gh issue view` 读正文/评论作为需求种子（和直接打字 `<描述>` 等价，只是更方便） |
14
+ | 出 | 各阶段边界 | `gh issue comment` 向 Issue 回写进度（收纳 / Design Doc / 任务勾选 / 验证结论） |
15
+ | 出 | archive | `gh issue close` 关闭 Issue，让它跟着 change 走完 |
16
+
17
+ `issue_number` 为 null（用 `<描述>` 触发、或 dogfood）时，脚本跳过所有 `gh` 读写，本地流程照常完整。OpenSpec 负责规格（`specs/changes/archive` 三层），纯 Bash 脚本负责状态机（`.smart.yaml`），Superpowers 负责设计与执行方法论。
18
+
19
+ ## 安装
11
20
 
12
21
  ```bash
13
22
  npm install -g @gepeiyu/smart
@@ -15,80 +24,100 @@ cd your-project
15
24
  smart init
16
25
  ```
17
26
 
18
- `smart init` 会：检测 AI 平台目录（`.opencode`/`.claude`/`.cursor`/`.codex`/...）→ 部署 Smart 8 子 skill + 脚本 + reference + commands → 可选安装 OpenSpec CLI 与 Superpowers → 创建 `docs/superpowers/{specs,plans,reports}` 工作目录与 `.smart/config.yaml`。
27
+ 或免全局安装：`npx @gepeiyu/smart init`
28
+
29
+ `smart init` 会：检测 AI 平台目录（`.opencode`/`.claude`/`.cursor`/`.codex` 等）→ 部署 Smart 8 子 skill + 脚本 + reference + commands → 可选安装 OpenSpec CLI 与 Superpowers → 建 `docs/superpowers/{specs,plans,reports}` 工作目录与 `.smart/config.yaml`。
19
30
 
20
- 无需全局安装也可用：
31
+ ## 上手（30 秒）
21
32
 
22
33
  ```bash
23
- npx @gepeiyu/smart init
34
+ smart init # 在项目里部署 Smart
35
+ gh issue create --title "..." --body "..." # 建一条 Issue
36
+ # 在 AI 平台里：/smart-issue #1
24
37
  ```
25
38
 
39
+ `/smart-issue #1` 会用 `gh issue view 1` 拉取 Issue 内容作为需求种子，建 OpenSpec change + `.smart.yaml`，回写收纳评论，然后自动推进 design → build → verify → archive，归档时 `gh issue close 1`。
40
+
41
+ 也可以用描述触发（不绑 Issue）：`/smart-issue <描述>`。
42
+
26
43
  ## CLI 命令
27
44
 
28
45
  | 命令 | 作用 |
29
46
  |------|------|
30
- | `smart init [path]` | 初始化（检测平台/部署 skill/装依赖/建工作目录）；`--yes` 非交互，`--no-deps` 跳过依赖 |
47
+ | `smart init [path]` | 部署 skill + 装依赖 + 建工作目录（`--yes` 非交互，`--no-deps` 跳过依赖） |
31
48
  | `smart status [path]` | 显示活跃 change 与 phase/issue |
32
- | `smart uninstall [path]` | 卸载 Smart skill（保留 openspec/changes 等用户数据）；`--force` 跳过确认 |
49
+ | `smart uninstall [path]` | 移除 skill（保留 openspec/changes 等用户数据；`--force`） |
33
50
  | `smart --version` / `--help` | 版本 / 帮助 |
34
51
 
35
- ## 前置依赖
36
-
37
- | 依赖 | 版本/要求 | 验证 |
38
- |------|----------|------|
39
- | `gh` CLI | 已登录 | `gh auth status` |
40
- | OpenSpec CLI | `@fission-ai/openspec` | `npx openspec --version`（本项目已含依赖） |
41
- | Bash | 5.x | Windows 用 Git Bash（`C:\Program Files\Git\bin\bash.exe`）；`bash --version` |
42
- | git | 任意 | `git --version` |
43
-
44
- Windows 用户注意：PATH 里的 `bash` 可能指向 WSL（不可用）。请用 Git Bash 的 `bash.exe`，或把 Git Bash 的 `bin` 加到 PATH 前面。
52
+ ## 技能清单
45
53
 
46
- ## 文件清单
54
+ | 命令 | 阶段 | 作用 |
55
+ |------|------|------|
56
+ | `/smart` | — | 主入口：自动检测当前 change 阶段并分派 |
57
+ | `/smart-issue` | 1 | 从 Issue/描述开启变更（`#ID` 经 `gh` 拉取） |
58
+ | `/smart-design` | 2 | 深度设计（brainstorming + Design Doc） |
59
+ | `/smart-build` | 3 | 计划与构建（实现代码） |
60
+ | `/smart-verify` | 4 | 验证与收尾 |
61
+ | `/smart-archive` | 5 | 归档（合并 spec + `gh issue close`） |
62
+ | `/smart-hotfix` | 预设 | 快速 bug 修复（跳过 brainstorming） |
63
+ | `/smart-tweak` | 预设 | 小改动（文案/配置/文档） |
47
64
 
48
- ```
49
- SKILL.md # 主 skill 文件（工具中性）
50
- scripts/smart-env.sh # 脚本定位 + env 加载
51
- scripts/smart-state.sh # .smart.yaml 状态机
52
- scripts/smart-guard.sh # 阶段守卫
53
- scripts/smart-handoff.sh # 交接包生成
54
- scripts/smart-archive.sh # 一键归档 + gh issue close
55
- reference/smart-yaml-fields.md
56
- reference/file-structure.md
57
- reference/issue-lifecycle.md
58
- .smart/config.yaml # 项目级配置（可选）
59
- ```
65
+ ## 守护脚本（纯 Bash）
60
66
 
61
- ## 如何在你用的工具里加载 Smart
67
+ | 脚本 | 用途 |
68
+ |------|------|
69
+ | `smart-env.sh` | 脚本定位 + env 加载 + 共享 helper |
70
+ | `smart-state.sh` | `.smart.yaml` 状态机（init/check/set/get/transition/next/scale/task-checkoff） |
71
+ | `smart-guard.sh` | 阶段守卫（`--apply` 推进 phase；校验交接 hash、Design Doc frontmatter、build 决策） |
72
+ | `smart-handoff.sh` | 交接包生成（带 SHA256 追踪，`--write`/`--hash-only`） |
73
+ | `smart-archive.sh` | 一键归档（合并主 spec + 移动 change + `gh issue close`） |
62
74
 
63
- Smart 的触发方式因工具而异，但 `SKILL.md` 主体保持中性。各工具只需按其惯用方式让 agent 读到 `SKILL.md` 并能执行 `bash scripts/smart-*.sh`。
75
+ ## 工作流
64
76
 
65
- ### opencode
77
+ ```
78
+ /smart（检测阶段）
79
+ ↓
80
+ /smart-issue ──→ /smart-design ──→ /smart-build ──→ /smart-verify ──→ /smart-archive
81
+ 读 Issue/描述 Design Doc 实现代码 验证报告 归档（+可选 gh issue close）
66
82
 
67
- 把 Smart 放进 `.opencode/skills/smart/`（含 `SKILL.md` + `scripts/` + `reference/`）。然后用 `/smart <issue-number>` 或「请用 smart 推进 #<n>」触发。opencode 会加载 `.opencode/skills/smart/SKILL.md`。
83
+ /smart-hotfix：issue → build → verify → archive（跳过 brainstorming）
84
+ /smart-tweak： issue → 轻量 build → 轻量 verify → archive
85
+ ```
68
86
 
69
- ### Claude Code
87
+ 阶段衔接由 `smart-state.sh next` 输出下一步该调的子 skill；agent 据此自动推进，遇到用户决策点（澄清确认/方案确认/plan-ready/验证失败/归档前）暂停等待。
70
88
 
71
- 把 `SKILL.md` + `scripts/` + `reference/` 放进 `.claude/skills/smart/`。在对话中引用：「读取 `.claude/skills/smart/SKILL.md`，用 Smart 流程推进 Issue #<n>」。
89
+ ## 状态机
72
90
 
73
- ### Cursor
91
+ 每个变更在 `openspec/changes/<name>/.smart.yaml` 记录：`phase`（issue|design|build|verify|archive）、`workflow`（full|hotfix|tweak）、`issue_number`/`issue_repo`、`verify_result`、`archived` 等。所有状态转换走脚本（`smart-state.sh transition` / `smart-guard.sh --apply`），不靠 agent 记忆——断点恢复时 agent 只需读 `.smart.yaml` 即知当前阶段。`issue_number` 为 null 时脚本跳过所有 `gh` 读写（本地流程仍完整）。
74
92
 
75
- 把 `SKILL.md` 内容作为项目规则放进 `.cursor/rules/smart.mdc`（或 `.cursorrules`），并把 `scripts/` 保留在仓库根。触发：「用 Smart 流程推进 Issue #<n>」。
93
+ 项目级配置在 `.smart/config.yaml`（`context_compression`/`review_mode`/`auto_transition` 默认值）。字段详见 `reference/smart-yaml-fields.md`。
76
94
 
77
- ### Codex（OpenAI）
95
+ ## 前置依赖
78
96
 
79
- 在 `AGENTS.md` 引用 Smart：写一行「变更流程遵循 `SKILL.md`（Smart）；触发时用 `bash scripts/smart-*.sh` 管理状态」。触发：「用 Smart 推进 Issue #<n>」。
97
+ | 依赖 | 要求 | 验证 |
98
+ |------|------|------|
99
+ | Node.js | 20+ | `node --version` |
100
+ | `gh` CLI | 已登录 | `gh auth status` |
101
+ | OpenSpec CLI | `smart init` 代装，或手动 `npm i -D @fission-ai/openspec` | `npx openspec --version` |
102
+ | Bash | 5.x（Windows 用 Git Bash） | `bash --version` |
103
+ | git | 任意 | `git --version` |
80
104
 
81
- ### 其他工具
105
+ Windows 注意：PATH 的 `bash` 可能指向 WSL（不可用）；用 Git Bash 的 `bash.exe`，或把 Git Bash 的 `bin` 加到 PATH 前面。
82
106
 
83
- 任何能读 Markdown 规则文件、能执行 shell 命令的 agent 工具都可加载 Smart：把 `SKILL.md` 作为规则注入，把 `scripts/` 放在仓库可执行路径，触发时给 Issue 编号即可。
107
+ ## 项目结构
84
108
 
85
- ## 快速验证（安装后）
109
+ ```
110
+ your-project/
111
+ ├── .smart/config.yaml # 项目级配置
112
+ ├── .opencode/skills/ # 部署的 skill（.claude/.cursor 等同理）
113
+ │ ├── smart/{SKILL.md, scripts/, reference/}
114
+ │ └── smart-{issue,design,build,verify,archive,hotfix,tweak}/SKILL.md
115
+ ├── openspec/ # OpenSpec 规格
116
+ │ ├── specs/ # 主 spec（归档时从 delta 合并）
117
+ │ └── changes/<name>/ # 活跃变更（含 .smart.yaml）
118
+ └── docs/superpowers/{specs,plans,reports}/ # Design Doc / 计划 / 验证报告
119
+ ```
86
120
 
87
- ```bash
88
- # 语法检查
89
- bash -n scripts/smart-*.sh
121
+ ## License
90
122
 
91
- # 状态机自检（对一个已有 change）
92
- bash scripts/smart-state.sh check <change-name> issue
93
- bash scripts/smart-state.sh next <change-name>
94
- ```
123
+ MIT
package/SKILL.md CHANGED
@@ -5,16 +5,12 @@ description: "Smart — OpenSpec + Superpowers 双星开发流程。用 /smart
5
5
 
6
6
  # Smart — OpenSpec + Superpowers 双星开发流程
7
7
 
8
- OpenSpec 与 Superpowers 如双星系统围绕同一目标运转。
9
-
10
8
  ```
11
9
  OpenSpec 负责 WHAT — 大纲、提案、spec 生命周期、归档
12
10
  Superpowers 负责 HOW — 技术设计、计划、执行、收尾
13
11
  ```
14
12
 
15
- **核心原则：brainstorming 必不可跳过。每次变更都必须经过深度设计（hotfix 和 tweak preset 除外）。**
16
-
17
- ---
13
+ **核心原则：brainstorming 不可跳过。每次变更都必须经过深度设计（hotfix 和 tweak preset 除外）。**
18
14
 
19
15
  ## 决策核心（Decision Core）
20
16
 
@@ -44,6 +40,8 @@ agent 做决策只需读本节，参考附录按需查阅。
44
40
  | 恰好 1 个 | `/smart`（无描述） | → 自动选中，进入 Step 1 |
45
41
  | 多个 | `/smart`（无描述） | → 列出清单让用户选择 |
46
42
 
43
+ **`#` 前缀特殊处理**：若用户参数以 `#` 开头（如 `/smart #42`），视为 Issue 触发的新变更，路由到 `/smart-issue #42`——由 smart-issue 做 gh 状态确认（`gh auth status`）与 Issue 内容拉取（`gh issue view <id>`）。**issue 非流程必需**，仅作需求来源与可选同步面；不绑 Issue（描述触发）时流程照常完整。
44
+
47
45
  <IMPORTANT>
48
46
  当用户选择「创建新变更」时，**必须调用 `/smart-issue`**（禁止直接调用 `/opsx:new`）。
49
47
  `/smart-issue` 负责完整双初始化：OpenSpec artifacts（由内部 `/opsx:new` 创建）+ `.smart.yaml` 状态文件。
@@ -135,8 +133,6 @@ agent 做决策只需读本节，参考附录按需查阅。
135
133
 
136
134
  agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须自动继续推进，不得中途退出。到达决策点时，**禁止跳过用户确认或自动选择——必须通过当前平台可用的用户输入/确认机制明确获取用户选择后才能继续**。
137
135
 
138
- **红旗清单** — 以下想法出现时立即停止并检查：
139
-
140
136
  | Agent 心理 | 实际风险 |
141
137
  |-----------|---------|
142
138
  | "用户应该会同意这个方案" | 不能替用户决策，必须等待用户明确选择 |
@@ -146,8 +142,6 @@ agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须
146
142
  | "流程走到这里应该没问题了" | 验证不通过 ≠ 通过，检查 verify_result |
147
143
  </IMPORTANT>
148
144
 
149
- ---
150
-
151
145
  ## 子命令速查
152
146
 
153
147
  | 命令 | 阶段 | 归属 | 产物 |
@@ -175,8 +169,6 @@ agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须
175
169
  ↑ 如触发升级条件 → 阻塞确认升级 → 补充 Design Doc → 回到完整流程
176
170
  ```
177
171
 
178
- ---
179
-
180
172
  ## 参考附录（Reference Appendix）
181
173
 
182
174
  > 字段说明、文件结构和自动衔接协议已提取为渐进式加载参考文档，按需查阅：
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@gepeiyu/smart",
3
- "version": "0.1.1",
4
- "description": "Smart — GitHub Issue 驱动的 OpenSpec 变更流程 agent skill (comet mirror)",
3
+ "version": "0.1.3",
4
+ "description": "Smart — OpenSpec 五阶段变更流程 agent skill（可选 GitHub Issue 双向同步）",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "smart": "./bin/smart.js"
@@ -29,7 +29,6 @@
29
29
  "superpowers",
30
30
  "agent-skill",
31
31
  "github-issue",
32
- "comet",
33
32
  "spec-driven"
34
33
  ],
35
34
  "license": "MIT",
package/smart-hotfix/SKILL.md CHANGED
@@ -5,8 +5,6 @@ description: "Smart 预设路径：Bug fix / 热修复。跳过 brainstorming，
5
5
 
6
6
  # Smart 预设路径：Hotfix
7
7
 
8
- 快速 bug fix 工作流：issue → build → verify → archive。跳过 brainstorming 和完整 plan，适用于行为修复、不涉及新 capability 设计的场景。
9
-
10
8
  **适用条件**（必须全部满足）：
11
9
  1. 修复已有功能的 bug，不新增 capability
12
10
  2. 不涉及接口变更或架构调整
@@ -14,8 +12,6 @@ description: "Smart 预设路径：Bug fix / 热修复。跳过 brainstorming，
14
12
 
15
13
  **不适用**：如修复过程发现需要架构调整，应升级为完整 `/smart` 流程。
16
14
 
17
- ---
18
-
19
15
  ## 流程（preset workflow，6 步）
20
16
 
21
17
  ### 0. 输出语言约束
@@ -136,25 +132,17 @@ fi
136
132
  **立即执行：** 使用 Skill 工具加载 `smart-archive` 技能进行归档。禁止跳过此步骤。
137
133
  如有 delta spec，按 smart-archive 规则同步到 main spec，并处理关联 Design Doc 与 Plan 的归档标注。
138
134
 
139
- ---
140
-
141
135
  ## 连续执行模式
142
136
 
143
137
  <IMPORTANT>
144
- Hotfix 流程默认 **一次性连续执行**。调用 `/smart-hotfix` 后，agent 在 hotfix 自有步骤间自动推进，不主动停顿。**例外**：若 `auto_transition: false`，则在每个 phase 边界（build/verify/archive 之间）停下，由用户手动运行下一阶段命令——此时连续执行降级为逐阶段手动推进，详见下方「自动衔接下一阶段」。但无论 `auto_transition` 取何值，以下情况都必须暂停等待用户确认：
145
-
146
- 1. 遇到升级条件（见"升级条件"章节），**必须使用当前平台可用的用户输入/确认机制暂停并等待用户明确确认**升级为完整流程
147
- 2. 任务超过 3 个转入 `/smart-build` 时的工作区隔离和执行方式选择
148
- 3. 验证阶段（smart-verify）的验证失败决策和分支处理决策
149
- 4. 归档前最终确认（smart-archive 执行归档脚本前）
138
+ 默认一次性连续执行。`auto_transition: false` 时在 phase 边界停下由用户手动推进。无论 `auto_transition` 取值，以下情况必须暂停等待用户确认：
150
139
 
151
- 执行顺序：快速开启 → 直接构建 → 根因消除检查 → 验证 → 归档 → 完成
152
-
153
- 每个阶段完成后立即进入下一阶段。阶段内部仍必须按上文要求调用对应 Smart/OpenSpec/Superpowers skill，被调用的 skill 如有自己的用户决策点，按该 skill 规则执行。
140
+ 1. 升级条件触发 → 暂停确认升级
141
+ 2. 任务 > 3 转入 `/smart-build` → 选择隔离/执行方式
142
+ 3. 验证失败决策和分支处理决策
143
+ 4. 归档前最终确认
154
144
  </IMPORTANT>
155
145
 
156
- ---
157
-
158
146
  ## 升级条件
159
147
 
160
148
  满足以下**任一**条件时，停止 hotfix 流程，升级为完整 `/smart`：
@@ -178,8 +166,6 @@ Hotfix 流程默认 **一次性连续执行**。调用 `/smart-hotfix` 后，age
178
166
 
179
167
  然后在当前 change 基础上补充 Design Doc：**立即使用 Skill 工具加载 `smart-design` skill**，后续正常走完整流程。若用户不确认升级，停止 hotfix 并报告当前变更已超出 hotfix 适用范围。
180
168
 
181
- ---
182
-
183
169
  ## 退出条件
184
170
 
185
171
  - Bug 已修复，测试通过
package/smart-issue/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: smart-issue
3
- description: "Smart 阶段 1：开启（issue）。用 /smart-issue 调用。从 GitHub Issue（#ID 经 gh 拉取）或描述出发，通过 OpenSpec 探索、澄清，创建 change 结构（proposal + design + tasks + .smart.yaml）。"
3
+ description: "Smart 阶段 1：issue。用 /smart-issue 调用。从描述或 GitHub Issue（#ID 经 gh 拉取）出发，经 OpenSpec 探索澄清，创建 change 结构。"
4
4
  ---
5
5
 
6
6
  # Smart 阶段 1：issue（开启）
@@ -8,7 +8,7 @@ description: "Smart 阶段 1：开启（issue）。用 /smart-issue 调用。从
8
8
  ## 前置条件
9
9
 
10
10
  - 无活跃 change，或用户希望创建新 change
11
- - 触发源：`/smart-issue <描述>` 或 `/smart-issue #<issue-id>`
11
+ - 触发参数：`/smart-issue <描述>` 或 `/smart-issue #<issue-id>`（需 gh 已登录）
12
12
 
13
13
  ## 步骤
14
14
 
@@ -16,19 +16,15 @@ description: "Smart 阶段 1：开启（issue）。用 /smart-issue 调用。从
16
16
 
17
17
  传递给 OpenSpec 的所有提问和产物要求都必须包含输出语言约束：使用触发本次工作流的用户请求语言。恢复已有 change 且产物已有明确主语言时，除非用户明确要求切换，否则保持该语言。
18
18
 
19
- ### 1. 触发源解析与需求种子
19
+ ### 1. 触发源解析
20
20
 
21
- **两种触发方式**：
21
+ - **参数以 `#` 开头**（如 `#42`）→ Issue 模式：
22
+ 1. `gh auth status` 确认登录；未登录则报错并提示 `gh auth login`，停止。
23
+ 2. `gh issue view <id> --json number,title,body,comments,labels` 按 `#` 后 id 拉取 Issue 内容。
24
+ 3. 解析为需求种子；记 `issue_number=<id>`、`issue_repo=<owner/repo>`。
25
+ - **其他/无参数**（描述）→ 描述模式：描述即种子，`issue_number=null`。
22
26
 
23
- - **`/smart-issue #<id>`**（Issue 驱动）：从 GitHub Issue 拉取需求种子。立即执行：
24
-
25
- ```bash
26
- gh issue view <id> --json number,title,body,comments,labels
27
- ```
28
-
29
- 将 Issue 的 `title` + `body` + `comments` 解析为需求种子（目标/非目标/范围边界/验收场景线索）。记下 `issue_number=<id>` 与 `issue_repo=<owner/repo>`（取 gh 默认 repo，或用户以 `--repo` 指定）。后续阶段会向该 Issue 回写进度，归档时关闭它。
30
-
31
- - **`/smart-issue <描述>`**（描述驱动）：用户描述即需求种子，`issue_number=null`（用户稍后可回填）。
27
+ 两种模式后续流程一致。issue 非必需，仅作需求来源与可选同步面。
32
28
 
33
29
  **立即执行：** 使用 Skill 工具加载 `openspec-explore` 技能。禁止跳过此步骤。
34
30
 
package/smart-tweak/SKILL.md CHANGED
@@ -5,9 +5,7 @@ description: "Smart 预设路径：非 bug 的小改动（tweak）。跳过 brai
5
5
 
6
6
  # Smart 预设路径：Tweak
7
7
 
8
- Tweak 是 Smart 五阶段能力的预设工作流，不是独立的平行流程。它复用 issue、build、verify、archive 能力，仅跳过 brainstorming 和完整 plan。
9
-
10
- 适用于非 bug 的小范围变更，例如文案调整、配置调整、文档或 prompt 的局部优化。
8
+ Tweak 复用 issue、build、verify、archive 能力，跳过 brainstorming 和完整 plan。适用于文案、配置、文档或 prompt 的局部优化。
11
9
 
12
10
  **适用条件**（必须全部满足）：
13
11
  1. 不新增 capability
@@ -17,8 +15,6 @@ Tweak 是 Smart 五阶段能力的预设工作流，不是独立的平行流程
17
15
 
18
16
  **不适用**：如变更过程中发现需要 capability、架构或接口调整，应升级为完整 `/smart` 流程。
19
17
 
20
- ---
21
-
22
18
  ## 流程（preset workflow，4 阶段）
23
19
 
24
20
  ### 0. 输出语言约束
@@ -112,24 +108,16 @@ fi
112
108
 
113
109
  **立即执行：** 使用 Skill 工具加载 `smart-archive` 技能进行归档。禁止跳过此步骤。
114
110
 
115
- ---
116
-
117
111
  ## 连续执行模式
118
112
 
119
113
  <IMPORTANT>
120
- Tweak 流程默认 **一次性连续执行**。调用 `/smart-tweak` 后，agent 在 tweak 自有步骤间自动推进，不主动停顿。**例外**：若 `auto_transition: false`，则在每个 phase 边界（build/verify/archive 之间）停下，由用户手动运行下一阶段命令——此时连续执行降级为逐阶段手动推进，详见下方「自动衔接下一阶段」。但无论 `auto_transition` 取何值，以下情况都必须暂停等待用户确认：
121
-
122
- 1. 遇到升级条件（见"升级条件"章节），**必须使用当前平台可用的用户输入/确认机制暂停并等待用户明确确认**升级为完整流程
123
- 2. 验证阶段（smart-verify）的验证失败决策和分支处理决策
124
- 3. 归档前最终确认（smart-archive 执行归档脚本前）
114
+ 默认一次性连续执行。`auto_transition: false` 时在 phase 边界停下由用户手动推进。无论 `auto_transition` 取值，以下情况必须暂停等待用户确认：
125
115
 
126
- 执行顺序：快速开启 → 轻量构建 → 轻量验证 → 归档 → 完成
127
-
128
- 每个阶段完成后立即进入下一阶段。阶段内部仍必须按上文要求调用对应 Smart/OpenSpec/Superpowers skill，被调用的 skill 如有自己的用户决策点，按该 skill 规则执行。
116
+ 1. 升级条件触发 → 暂停确认升级
117
+ 2. 验证失败决策和分支处理决策
118
+ 3. 归档前最终确认
129
119
  </IMPORTANT>
130
120
 
131
- ---
132
-
133
121
  ## 升级条件
134
122
 
135
123
  满足以下**任一**条件时，停止 tweak 流程，升级为完整 `/smart`：
@@ -154,8 +142,6 @@ Tweak 流程默认 **一次性连续执行**。调用 `/smart-tweak` 后，agent
154
142
 
155
143
  然后在当前 change 基础上补充 Design Doc：**立即使用 Skill 工具加载 `smart-design` skill**，后续正常走完整流程。若用户不确认升级，停止 tweak 并报告当前变更已超出 tweak 适用范围。
156
144
 
157
- ---
158
-
159
145
  ## 退出条件
160
146
 
161
147
  - 小改动已完成，测试通过