@gepeiyu/smart 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gepeiyu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# Smart — GitHub Issue 驱动的 OpenSpec 变更流程 agent skill
+
+Smart 让 AI agent 把一个 GitHub Issue 当作 `issue → design → build → verify → archive` 全流程容器推进，直到 Issue 可关闭。一条 Issue = 一个 OpenSpec change；Issue 关闭 ≈ change 归档。
+
+- **工具中性**：`SKILL.md` 主体不依赖任何 agent 工具专有语法
+- **纯 Bash 状态机**：`scripts/smart-*.sh`，所有工具都能 `bash scripts/smart-*.sh` 直接跑
+- **OpenSpec 复用**：`openspec/specs/` + `openspec/changes/` + `openspec/changes/archive/` 三层
+- **Issue 驱动**：`gh issue view` 读取、`gh issue comment` 回写、`gh issue close` 归档
+
+## 安装（npm）
+
+```bash
+npm install -g @gepeiyu/smart
+cd your-project
+smart init
+```
+
+`smart init` 会：检测 AI 平台目录（`.opencode`/`.claude`/`.cursor`/`.codex`/...）→ 部署 Smart 8 子 skill + 脚本 + reference + commands → 可选安装 OpenSpec CLI 与 Superpowers → 创建 `docs/superpowers/{specs,plans,reports}` 工作目录与 `.smart/config.yaml`。
+
+无需全局安装也可用：
+
+```bash
+npx @gepeiyu/smart init
+```
+
+## CLI 命令
+
+| 命令 | 作用 |
+|------|------|
+| `smart init [path]` | 初始化（检测平台/部署 skill/装依赖/建工作目录）；`--yes` 非交互，`--no-deps` 跳过依赖 |
+| `smart status [path]` | 显示活跃 change 与 phase/issue |
+| `smart uninstall [path]` | 卸载 Smart skill（保留 openspec/changes 等用户数据）；`--force` 跳过确认 |
+| `smart --version` / `--help` | 版本 / 帮助 |
+
+## 前置依赖
+
+| 依赖 | 版本/要求 | 验证 |
+|------|----------|------|
+| `gh` CLI | 已登录 | `gh auth status` |
+| OpenSpec CLI | `@fission-ai/openspec` | `npx openspec --version`（本项目已含依赖） |
+| Bash | 5.x | Windows 用 Git Bash（`C:\Program Files\Git\bin\bash.exe`）；`bash --version` |
+| git | 任意 | `git --version` |
+
+Windows 用户注意：PATH 里的 `bash` 可能指向 WSL（不可用）。请用 Git Bash 的 `bash.exe`，或把 Git Bash 的 `bin` 加到 PATH 前面。
+
+## 文件清单
+
+```
+SKILL.md                      # 主 skill 文件（工具中性）
+scripts/smart-env.sh          # 脚本定位 + env 加载
+scripts/smart-state.sh        # .smart.yaml 状态机
+scripts/smart-guard.sh        # 阶段守卫
+scripts/smart-handoff.sh      # 交接包生成
+scripts/smart-archive.sh      # 一键归档 + gh issue close
+reference/smart-yaml-fields.md
+reference/file-structure.md
+reference/issue-lifecycle.md
+.smart/config.yaml            # 项目级配置（可选）
+```
+
+## 如何在你用的工具里加载 Smart
+
+Smart 的触发方式因工具而异，但 `SKILL.md` 主体保持中性。各工具只需按其惯用方式让 agent 读到 `SKILL.md` 并能执行 `bash scripts/smart-*.sh`。
+
+### opencode
+
+把 Smart 放进 `.opencode/skills/smart/`（含 `SKILL.md` + `scripts/` + `reference/`）。然后用 `/smart <issue-number>` 或「请用 smart 推进 #<n>」触发。opencode 会加载 `.opencode/skills/smart/SKILL.md`。
+
+### Claude Code
+
+把 `SKILL.md` + `scripts/` + `reference/` 放进 `.claude/skills/smart/`。在对话中引用：「读取 `.claude/skills/smart/SKILL.md`，用 Smart 流程推进 Issue #<n>」。
+
+### Cursor
+
+把 `SKILL.md` 内容作为项目规则放进 `.cursor/rules/smart.mdc`（或 `.cursorrules`），并把 `scripts/` 保留在仓库根。触发：「用 Smart 流程推进 Issue #<n>」。
+
+### Codex（OpenAI）
+
+在 `AGENTS.md` 引用 Smart：写一行「变更流程遵循 `SKILL.md`（Smart）；触发时用 `bash scripts/smart-*.sh` 管理状态」。触发：「用 Smart 推进 Issue #<n>」。
+
+### 其他工具
+
+任何能读 Markdown 规则文件、能执行 shell 命令的 agent 工具都可加载 Smart：把 `SKILL.md` 作为规则注入，把 `scripts/` 放在仓库可执行路径，触发时给 Issue 编号即可。
+
+## 快速验证（安装后）
+
+```bash
+# 语法检查
+bash -n scripts/smart-*.sh
+
+# 状态机自检（对一个已有 change）
+bash scripts/smart-state.sh check <change-name> issue
+bash scripts/smart-state.sh next <change-name>
+```

package/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: smart
+description: "Smart — OpenSpec + Superpowers 双星开发流程。用 /smart 启动，自动检测阶段并分发到子命令。五阶段：开启 → 深度设计 → 计划与构建 → 验证与收尾 → 归档。"
+---
+
+# Smart — OpenSpec + Superpowers 双星开发流程
+
+OpenSpec 与 Superpowers 如双星系统围绕同一目标运转。
+
+```
+OpenSpec 负责 WHAT  — 大纲、提案、spec 生命周期、归档
+Superpowers 负责 HOW — 技术设计、计划、执行、收尾
+```
+
+**核心原则：brainstorming 必不可跳过。每次变更都必须经过深度设计（hotfix 和 tweak preset 除外）。**
+
+---
+
+## 决策核心（Decision Core）
+
+agent 做决策只需读本节，参考附录按需查阅。
+
+### 输出语言规则
+
+以触发本次工作流的用户请求语言作为默认输出语言。恢复已有 change 时，如果现有产物有明确主语言，除非用户明确要求切换，否则保持该语言。
+
+### 阶段自动检测
+
+**Step 0: 活跃 Change 发现与意图判定**
+
+1. 先做 Preset 检测；命中 hotfix/tweak 时直接调用对应 preset skill，不进入普通 issue 分支
+2. 未命中 preset 时，运行 `openspec list --json` 获取所有活跃 change
+
+**Preset 检测优先级最高**：
+- 用户明确描述为 bug fix / 热修复 + 满足 hotfix 条件 → 直接 `/smart-hotfix`
+- 用户明确描述为文案/配置/文档/prompt 小调整 + 满足 tweak 条件 → 直接 `/smart-tweak`
+- 未命中 preset → 按下表处理
+
+| 活跃 change | 用户输入 | 行为 |
+|-------------|---------|------|
+| 无 | 非 preset 输入 | → 调用 `/smart-issue` |
+| 恰好 1 个 | `/smart <描述>` | → **询问**：继续该变更 or 创建新变更 |
+| 多个 | `/smart <描述>` | → **询问**：继续现有变更 or 创建新变更；若选继续 → 列出清单让用户选择 |
+| 恰好 1 个 | `/smart`（无描述） | → 自动选中，进入 Step 1 |
+| 多个 | `/smart`（无描述） | → 列出清单让用户选择 |
+
+<IMPORTANT>
+当用户选择「创建新变更」时，**必须调用 `/smart-issue`**（禁止直接调用 `/opsx:new`）。
+`/smart-issue` 负责完整双初始化：OpenSpec artifacts（由内部 `/opsx:new` 创建）+ `.smart.yaml` 状态文件。
+直接调用 `/opsx:new` 会缺失 `.smart.yaml`，导致后续阶段判定失败。
+</IMPORTANT>
+
+**Step 1: 读取 `.smart.yaml` 状态元数据**
+
+优先读取 `openspec/changes/<name>/.smart.yaml`。不存在时回退到 `openspec status --change "<name>" --json`、`tasks.md` 和 `docs/superpowers/` 文件检查。
+
+**断点恢复规则**：
+- 每次恢复上下文时，先重新执行 Step 0 和 Step 1，不依赖对话历史判断阶段
+- 只要存在 active change 且工作区有未提交改动，必须按 `smart/reference/dirty-worktree.md` 协议处理。该协议定义了检查步骤、归因分类和禁令，本文件不重复
+- 若 `phase: build`，先检查 `build_pause`、`plan`、`build_mode` 和 `isolation`（详见下方）：
+  - 若 `build_pause: plan-ready` 但 `isolation` 和 `build_mode` 已经设置，则视为 stale pause：先输出 `[SMART] 检测到 stale pause（build_pause=plan-ready 但 isolation/build_mode 已设置），自动清除并继续`，再运行 `"$SMART_BASH" "$SMART_STATE" set <name> build_pause null`，然后读取 tasks.md 的下一个未勾选任务并按 `build_mode` 恢复执行
+  - 若 `build_pause: plan-ready` 且 plan 文件存在，但 `isolation` 或 `build_mode` 尚未设置，回到 `/smart-build` 的 plan-ready 恢复点，提示用户继续选择隔离方式和执行方式，不重新生成 plan
+  - 若 `build_pause: plan-ready` 但 plan 文件缺失，回到 `/smart-build` 处理状态损坏或重新生成 plan
+  - 若 `build_mode`、`isolation` 或 `tdd_mode` 未设置，回到 `/smart-build` 对应步骤补充后再执行
+  - 若均已设置，读取 tasks.md 的下一个未勾选任务，并按 `build_mode` 恢复执行：
+    - 若 `build_mode: subagent-driven-development`，不得在主窗口直接执行任务；必须回到 `/smart-build` 的后台 subagent 调度规则，由主窗口只做协调
+    - 其他执行方式按 `/smart-build` 的对应规则继续
+- 若 `phase: verify` 且 `verify_result: fail`，进入验证失败决策阻塞点：暂停并询问用户修复或接受偏差；用户选择修复后才运行 `"$SMART_BASH" "$SMART_STATE" transition <name> verify-fail` 并调用 `/smart-build`
+- 若 `phase: issue` 但 proposal/design/tasks 已完整，先运行 `"$SMART_BASH" "$SMART_GUARD" <change-name> issue --apply` 修正状态，再继续判定
+- 若 `phase: archive`，只允许调用 `/smart-archive`；`/smart-archive` 必须先等待归档前最终确认，归档成功后 change 会移动到 archive 目录，不再对原活跃目录运行 guard
+
+**Step 2: 阶段判定**（按顺序，命中即停）
+
+1. `archived: true` 或 change 已移入 archive → 流程已完成
+2. `verify_result: pass` 且 `archived` 不是 `true` → `/smart-archive`（先进行归档前最终确认）
+3. `verify_result: fail` → 进入验证失败决策阻塞点（暂停询问修复或接受偏差；用户选择修复后才 `verify-fail` 并 `/smart-build`）
+4. `phase: verify` 或 tasks.md 全部勾选 → `/smart-verify`
+5. `phase: build` 或已有 Design Doc 但计划/执行未完成 → 优先按 workflow 路由：`hotfix` → `/smart-hotfix`，`tweak` → `/smart-tweak`，`full` → `/smart-build`
+6. `phase: design` 或有 change 但无 Design Doc → `/smart-design`
+7. `phase: issue` 或有活跃 change 但 `.smart.yaml` 缺失 → `/smart-issue`
+8. 无活跃 change → `/smart-issue`
+
+如果元数据与文件状态冲突，以文件状态为准，修正 `.smart.yaml` 后继续。
+
+### 预设升级条件
+
+**hotfix → full**（满足任一即升级）：
+- 改动涉及 **3+ 文件**
+- 涉及架构变更（新模块、新接口、新依赖）
+- 涉及数据库 schema 变更
+- 修复引入新的 public API
+- 修复范围超出单一函数/模块
+
+**tweak → full**（满足任一即升级）：
+- 改动涉及 **5+ 文件**
+- 涉及多个模块的协调修改
+- 需要新增测试用例 **5+**
+- 涉及配置项的新增或删除（非值修改）
+- 需要新增 capability
+- 需要 delta spec（影响了已有规格）
+
+### 错误处理速查
+
+| 场景 | 处理方式 |
+|------|---------|
+| `openspec list --json` 失败 | 检查 openspec 是否已安装，提示 `openspec init` |
+| 子 skill 不可用 | 停止流程，提示安装或启用对应 skill |
+| `.smart.yaml` 格式异常或缺失 | 以文件状态为准，用 `"$SMART_BASH" "$SMART_STATE" set` 修正后继续 |
+| 构建/测试失败 | 返回 build 阶段修复，不进入 verify |
+| change 目录结构不完整 | 按 `smart-issue` 产物要求补齐 |
+
+### 阶段衔接
+
+<IMPORTANT>
+单次 `/smart` 调用从检测到的阶段开始，退出条件满足后进入下一阶段。
+
+流转链：issue → design → build → verify → archive
+
+**连续执行要求**：从检测到的阶段开始，agent 自动推进后续阶段。但**自动推进仅适用于没有用户决策的衔接点**。遇到用户决策点时，**必须使用当前平台可用的用户输入/确认机制暂停并等待用户明确回复**，不得用推荐规则、默认值或历史偏好代替用户确认，也不得仅输出文字提示后继续执行。
+
+**阶段推进与自动衔接的区分**：每个子 skill 退出前都会运行阶段守卫 `--apply` 推进 `.smart.yaml` 的 `phase` 字段——这一步**始终发生**，与 `auto_transition` 无关。之后子 skill 运行 `"$SMART_BASH" "$SMART_STATE" next <name>` 解析下一步：`auto_transition` 不为 `false` 时输出 `NEXT: auto`（自动调用下一 skill），为 `false` 时输出 `NEXT: manual`（不调用下一 skill，提示用户手动运行）。因此 `auto_transition` **只控制是否自动调用下一个 skill，不影响 phase 推进**。无论 `auto_transition` 取何值，下方的用户决策点都必须阻塞等待。
+
+**决策点是阻塞点**：只要到达下列任一节点，当前 `/smart` 调用必须停住，并按 `smart/reference/decision-point.md` 的协议获取用户明确选择。用户明确选择后才能写入对应状态字段、执行对应操作，随后再继续自动流转。
+
+需要用户参与的节点（仅在这些节点暂停）：
+1. issue 阶段 proposal/design/tasks 审视确认
+2. brainstorming 确认设计方案
+3. build 阶段 plan-ready 暂停选择，以及随后选择工作方式（隔离方式 + 执行方式）
+4. verify 不通过时决定修复或接受偏差（含 Spec 漂移处理方式选择）
+5. finishing-branch 选择分支处理方式
+6. archive 阶段执行归档脚本前的最终确认
+7. 遇到升级条件（hotfix/tweak → 完整流程）
+8. build 阶段范围扩张需重新设计或拆分新 change
+9. issue 阶段大型 PRD 需确认拆分为多个 change
+
+agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须自动继续推进，不得中途退出。到达决策点时，**禁止跳过用户确认或自动选择——必须通过当前平台可用的用户输入/确认机制明确获取用户选择后才能继续**。
+
+**红旗清单** — 以下想法出现时立即停止并检查：
+
+| Agent 心理 | 实际风险 |
+|-----------|---------|
+| "用户应该会同意这个方案" | 不能替用户决策，必须等待用户明确选择 |
+| "这只是个小改动，不需要确认" | 决策点无大小之分，阻塞点必须等待 |
+| "用户之前选过 A，这次也选 A" | 历史偏好不能替代当前确认 |
+| "我已经解释了方案，用户没反对" | 没反对 ≠ 同意，必须用工具获取明确选择 |
+| "流程走到这里应该没问题了" | 验证不通过 ≠ 通过，检查 verify_result |
+</IMPORTANT>
+
+---
+
+## 子命令速查
+
+| 命令 | 阶段 | 归属 | 产物 |
+|------|------|------|------|
+| `/smart-issue` | 1. 开启 | OpenSpec | proposal.md、design.md、tasks.md |
+| `/smart-design` | 2. 深度设计 | Superpowers | Design Doc、delta spec |
+| `/smart-build` | 3. 计划与构建 | Superpowers | 实施计划、代码提交 |
+| `/smart-verify` | 4. 验证与收尾 | Both | 验证报告、分支处理 |
+| `/smart-archive` | 5. 归档 | OpenSpec | delta→main spec 同步、design doc 标注、归档 |
+| `/smart-hotfix` | 预设路径 | Both | 快速修复（跳过 brainstorming） |
+| `/smart-tweak` | 预设路径 | Both | 小改动（跳过 brainstorming 和完整 plan） |
+
+```
+/smart
+  ↓ 自动检测
+/smart-issue ──→ /smart-design ──→ /smart-build ──→ /smart-verify ──→ /smart-archive
+  (OpenSpec)      (Superpowers)     (Superpowers)     (Both)          (OpenSpec)
+
+/smart-hotfix（预设路径，跳过 brainstorming）
+  issue ──→ build ──→ verify ──→ archive
+    ↑ 如触发升级条件 → 阻塞确认升级 → 补充 Design Doc → 回到完整流程
+
+/smart-tweak（预设路径，跳过 brainstorming 和完整 plan）
+  issue ──→ lightweight build ──→ light verify ──→ archive
+    ↑ 如触发升级条件 → 阻塞确认升级 → 补充 Design Doc → 回到完整流程
+```
+
+---
+
+## 参考附录（Reference Appendix）
+
+> 字段说明、文件结构和自动衔接协议已提取为渐进式加载参考文档，按需查阅：
+> - **`.smart.yaml` 完整字段表**：按 `smart/reference/smart-yaml-fields.md` 查阅（含必需字段、可选字段和完整示例）
+> - **文件结构**：按 `smart/reference/file-structure.md` 查阅
+> - **自动衔接协议**：按 `smart/reference/auto-transition.md` 查阅
+> - **上下文压缩恢复**：按 `smart/reference/context-recovery.md` 查阅
+> - **用户决策点协议**：按 `smart/reference/decision-point.md` 查阅
+> - **异常调试协议**：按 `smart/reference/debug-gate.md` 查阅
+
+### 状态机硬约束
+
+- `build → verify` 前，`isolation` 必须是 `branch` 或 `worktree`
+- `build → verify` 前，`build_mode` 必须已选择
+- `build_mode: subagent-driven-development` 必须同时有 `subagent_dispatch: confirmed`
+- full workflow 离开 build 阶段前 `tdd_mode` 必须已选择为 `tdd` 或 `direct`
+- `build_mode: direct` 默认只允许 `hotfix` / `tweak`；full workflow 需要 `direct_override: true`
+- `build_pause` 不是执行方式，不得写入 `build_mode`
+- 这些约束同时存在于 `smart-guard.sh build --apply` 和 `smart-state.sh transition <name> build-complete`
+
+### 脚本定位
+
+Smart 脚本随 skill 包分发在 `smart/scripts/` 下。**不硬编码路径** — 定位一次，缓存到环境变量。此块为标准样板，在每个子 skill 中独立重复以确保可独立加载；修改时必须保持所有文件同步（样板版本: `v2`，变更时更新此版本号便于定位需要同步的文件）：
+
+```bash
+SMART_ENV="${SMART_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/scripts/smart-env.sh' -type f -print -quit 2>/dev/null)}"
+if [ -z "$SMART_ENV" ]; then
+  echo "ERROR: smart-env.sh not found. Ensure the smart skill is installed." >&2
+  return 1
+fi
+. "$SMART_ENV"
+
+# 脚本定位失败时停止流程
+if [ -z "$SMART_GUARD" ] || [ -z "$SMART_STATE" ] || [ -z "$SMART_HANDOFF" ] || [ -z "$SMART_ARCHIVE" ]; then
+  echo "ERROR: Smart scripts not found. Ensure the smart skill is installed." >&2
+  echo "Expected path pattern: */scripts/smart-*.sh under project or platform skill directories" >&2
+  return 1
+fi
+```
+
+**自动状态更新**：guard 支持 `--apply` 参数，验证通过后自动更新 `.smart.yaml` 状态字段：
+
+```bash
+"$SMART_BASH" "$SMART_GUARD" <change-name> <phase> --apply
+```
+
+`--apply` 内部委托给 `smart-state transition`。需要直接表达状态事件时使用：
+
+```bash
+"$SMART_BASH" "$SMART_STATE" transition <change-name> issue-complete
+"$SMART_BASH" "$SMART_STATE" transition <change-name> design-complete
+"$SMART_BASH" "$SMART_STATE" transition <change-name> build-complete
+"$SMART_BASH" "$SMART_STATE" transition <change-name> verify-pass
+"$SMART_BASH" "$SMART_STATE" transition <change-name> verify-fail
+"$SMART_BASH" "$SMART_STATE" transition <archive-name> archived
+```
+
+**解析下一步**：阶段守卫推进 phase 后，用 `next` 子命令解析是否自动调用下一个 skill：
+
+```bash
+"$SMART_BASH" "$SMART_STATE" next <change-name>
+```
+
+输出 `NEXT: auto|manual|done` + `SKILL: <skill-name>`（`done` 时省略）+ `HINT`（仅 `manual` 时）。`auto_transition: false` 时输出 `manual`，只暂停下一 skill 调用，不影响已发生的 phase 推进。
+
+**归档脚本**：一键完成归档全部步骤：
+
+```bash
+"$SMART_BASH" "$SMART_ARCHIVE" <change-name>
+```
+
+加载 smart 后，agent 应执行以上变量赋值一次，后续全程复用 `$SMART_GUARD`、`$SMART_STATE`、`$SMART_HANDOFF`、`$SMART_ARCHIVE`。
+
+### 文件结构
+
+按 `smart/reference/file-structure.md` 查阅完整目录结构。
+
+### 最佳实践
+
+1. **brainstorming 不可跳过** — 每次变更必须经过深度设计（hotfix 和 tweak 除外）
+2. **delta spec 是活文档** — 阶段 3 期间可自由修改，归档时同步
+3. **交接包由脚本生成** — OpenSpec → Superpowers 的上下文必须通过 `smart-handoff.sh` 生成 compact 可追溯摘录（需要全文时用 `--full`），并由 guard 校验 source/hash/mode
+4. **保持 tasks.md 同步** — 完成一个勾一个
+5. **频繁提交** — 每个任务一次提交，message 体现设计意图
+6. **先验证再确认归档** — `/smart-verify` 通过后进入 `/smart-archive`，但运行归档脚本前必须等待用户最终确认
+7. **增量更新分级** — 小编辑、中重 brainstorming、大新 change
+8. **Plan 必须关联 change** — 文件头包含 `change:` 和 `design-doc:` 元数据
+9. **归档闭环** — design doc 和 plan 必须标注 `archived-with` 状态
+10. **修改已有功能** — 直接 open 新 change 即可
+11. **Preset 有上限** — hotfix/tweak 满足升级条件时及时切换到完整流程

package/bin/smart.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../src/index.js';
+run();

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@gepeiyu/smart",
+  "version": "0.1.1",
+  "description": "Smart — GitHub Issue 驱动的 OpenSpec 变更流程 agent skill (comet mirror)",
+  "type": "module",
+  "bin": {
+    "smart": "./bin/smart.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "SKILL.md",
+    "smart-issue",
+    "smart-design",
+    "smart-build",
+    "smart-verify",
+    "smart-archive",
+    "smart-hotfix",
+    "smart-tweak",
+    "scripts",
+    "reference"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "smart",
+    "openspec",
+    "superpowers",
+    "agent-skill",
+    "github-issue",
+    "comet",
+    "spec-driven"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@fission-ai/openspec": "^1.5.0"
+  }
+}

package/reference/file-structure.md

@@ -0,0 +1,61 @@
+# Smart 文件结构
+
+Smart 镜像 Comet 的多 skill 结构：1 个主调度 skill + 7 个阶段/preset 子 skill，共享一套 Bash 脚本与 reference。
+
+## 仓库布局（本仓库即 Smart skill 发行物）
+
+```
+C:\git\smart\                       # 仓库根
+├── SKILL.md                        # 主调度（决策核心 + 阶段自动检测 + 子命令速查）= smart skill
+├── smart-issue/SKILL.md            # 阶段 1：issue（= comet-open，+ #ID gh 拉取）
+├── smart-design/SKILL.md           # 阶段 2：design
+├── smart-build/SKILL.md            # 阶段 3：build
+├── smart-verify/SKILL.md           # 阶段 4：verify
+├── smart-archive/SKILL.md          # 阶段 5：archive（+ gh issue close）
+├── smart-hotfix/SKILL.md           # 预设：hotfix
+├── smart-tweak/SKILL.md            # 预设：tweak
+├── scripts/
+│   ├── smart-env.sh                # 脚本定位 + env 加载 + 共享 helper
+│   ├── smart-state.sh              # .smart.yaml 状态机（init/check/set/get/transition/next/scale/task-checkoff）
+│   ├── smart-guard.sh              # 阶段守卫（--apply 推进 phase）
+│   ├── smart-handoff.sh            # 交接包生成（--write/--hash-only）
+│   └── smart-archive.sh            # 一键归档（openspec archive + gh issue close）
+├── reference/
+│   ├── smart-yaml-fields.md        # .smart.yaml 完整字段表
+│   ├── file-structure.md           # 本文件
+│   └── issue-lifecycle.md          # Issue↔phase 映射 + gh 用法 + 评论模板
+├── README.md                       # 各 agent 工具加载说明 + 前置依赖
+├── .smart/
+│   └── config.yaml                 # 项目级 Smart 配置
+├── openspec/                       # OpenSpec 工作区
+│   ├── config.yaml
+│   ├── specs/                      # 主 spec（归档时从 delta 合并）
+│   └── changes/
+│       ├── <active-change>/        # 活跃 change（含 .smart.yaml）
+│       └── archive/YYYY-MM-DD-<name>/
+├── docs/superpowers/               # Superpowers 产物（Design Doc / plan / report）
+└── package.json                    # @fission-ai/openspec 依赖
+```
+
+## 子 skill 与脚本的关系
+
+- 子 skill（`smart-*/SKILL.md`）= 阶段流程逻辑，agent 按本工具惯用方式加载
+- 脚本（`scripts/smart-*.sh`）= 状态机，所有子 skill 共用，纯 Bash
+- `smart-state.sh next <name>` 输出 `SKILL: smart-issue|smart-design|smart-build|smart-verify|smart-archive|smart-hotfix|smart-tweak`，主调度 `/smart` 据此 dispatch
+
+## 工具安装位置
+
+把 `SKILL.md` + `smart-*/` + `scripts/` + `reference/` 拷贝（或链接）到目标工具的 skill 目录：
+
+| 工具 | 主 skill | 子 skill | 脚本/reference |
+|------|---------|---------|---------------|
+| opencode | `.opencode/skills/smart/` | `.opencode/skills/smart-*/` | `.opencode/skills/smart/{scripts,reference}/` |
+| Claude Code | `.claude/skills/smart/` | `.claude/skills/smart-*/` | `.claude/skills/smart/{scripts,reference}/` |
+| Cursor | `.cursor/rules/` | 同上 | 仓库根 `scripts/` |
+| Codex | `AGENTS.md` 引用 | 同上 | 仓库根 `scripts/` |
+
+opencode 命令（`/smart`、`/smart-issue` 等）放 `.opencode/commands/smart*.md`。详见 `README.md`。
+
+## 脚本定位机制
+
+每个 `smart-*.sh` 优先 source 同目录兄弟 `smart-env.sh`（经 `BASH_SOURCE`），回退 `find . "$HOME"/.*/skills ... -path '*/scripts/smart-env.sh'`。因此无论装在仓库根 `scripts/` 还是工具 skill 目录 `<tool>/skills/smart/scripts/`，都能定位。

package/reference/issue-lifecycle.md

@@ -0,0 +1,96 @@
+# Issue 生命周期映射
+
+一条 GitHub Issue = 一个 Smart change。Issue 既是触发源、进度面，也是关闭信号。
+
+## Issue ↔ phase 映射
+
+| phase | Issue 动作 | gh 命令 |
+|-------|-----------|---------|
+| issue | 读取 Issue 正文+评论 → 解析需求；收纳后回写评论 | `gh issue view <n> --json number,title,body,comments,labels`；`gh issue comment <n> --body "<收纳确认>"` |
+| design | 回写 Design Doc 链接 | `gh issue comment <n> --body "<design 链接>"` |
+| build | 每完成一个 task 回写进度（勾 tasks.md） | `gh issue comment <n> --body "<进度>"` |
+| verify | 回写验证结论 | `gh issue comment <n> --body "<验证结论>"` |
+| archive | 关闭 Issue | `gh issue close <n> [--repo <owner/repo>]` |
+
+`issue_number` 为 `null` 时（如 dogfood bootstrap），所有 gh 读写跳过，仅本地操作。
+
+## 读取 Issue
+
+```bash
+gh issue view <n> --json number,title,body,comments,labels
+```
+
+解析为结构化需求：
+- **目标**：Issue 正文陈述的问题/期望
+- **非目标**：明确不做的
+- **范围边界**：涉及/不涉及的模块
+- **关键未知项**：评论中未澄清的假设
+- **验收场景草案**：Issue 正文 + 评论中的验收线索
+
+## 评论模板
+
+### issue 收纳确认
+
+```markdown
+## Smart 已收纳
+
+- **change**: `<name>`
+- **issue**: #<n>
+- **阶段计划**: issue → design → build → verify → archive
+- **workflow**: full|hotfix|tweak
+
+已创建 OpenSpec change 目录与 `.smart.yaml`。接下来进入 design 阶段做深度技术设计。
+```
+
+### design 完成
+
+```markdown
+## Design 完成
+
+- **Design Doc**: `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
+- **关键决策**: <一句话>
+- **Spec Patch**: <有/无>
+
+进入 build 阶段。
+```
+
+### build 进度（每 task）
+
+```markdown
+## Build 进度
+
+- [x] X.Y <task>
+- [ ] X.Z <next task>
+
+<commit 或备注>
+```
+
+### verify 结论
+
+```markdown
+## 验证结论
+
+- **verify_mode**: light|full
+- **结果**: PASS
+- **报告**: `docs/superpowers/reports/YYYY-MM-DD-<name>-verify.md`
+- **分支处理**: <merged/PR/kept/discarded>
+
+进入 archive。
+```
+
+## 关闭 Issue
+
+由 `smart-archive.sh` 在归档时执行：
+
+```bash
+gh issue close <n>                              # issue_repo 为 null 时
+gh issue close <n> --repo <owner/repo>          # issue_repo 已设时
+```
+
+Issue 关闭 ≈ change 归档。若归档后需重开，先 `smart-state.sh transition <name> archive-reopen`（回到 verify），再手动重开 Issue（`gh issue reopen <n>`）。
+
+## 前置依赖
+
+- `gh` CLI 已登录（`gh auth status` 验证）
+- 对目标 repo 有 issue 读写权限
+- 若跨 repo，`.smart.yaml` 的 `issue_repo` 必须设为 `<owner/repo>`

package/reference/smart-yaml-fields.md

@@ -0,0 +1,66 @@
+# `.smart.yaml` 字段表
+
+每条 change 的状态文件位于 `openspec/changes/<name>/.smart.yaml`，由 `smart-state.sh` 管理。flat YAML（`key: value`，无嵌套）。
+
+## 必需字段
+
+| 字段 | 取值 | 说明 |
+|------|------|------|
+| `change_name` | `<name>` | kebab-case change 名 |
+| `phase` | `issue\|design\|build\|verify\|archive` | 当前阶段 |
+| `workflow` | `full\|hotfix\|tweak` | 工作流类型 |
+| `archived` | `true\|false` | 是否已归档 |
+| `issue_number` | `null\|<n>` | Smart 专属；关联 GitHub Issue 编号；null 时脚本跳过 gh 读写 |
+| `verify_result` | `pending\|pass\|fail` | 验证结果 |
+| `auto_transition` | `true\|false` | 是否自动进入下一阶段（仅控制衔接，不影响 phase 推进） |
+| `created` | `YYYY-MM-DD` | init 时写入 |
+
+## 条件必需字段
+
+| 字段 | 何时必需 | 取值 |
+|------|---------|------|
+| `review_mode` | full workflow 离开 build 前 | `off\|standard\|thorough` |
+| `design_doc` | full workflow 的 design→build | `null\|<path>` |
+| `build_mode` | build→verify 前 | `subagent-driven-development\|executing-plans\|direct` |
+| `isolation` | build→verify 前 | `branch\|worktree` |
+| `tdd_mode` | full workflow 离开 build 前 | `tdd\|direct` |
+| `subagent_dispatch` | `build_mode=subagent-driven-development` 时 | `confirmed` |
+| `direct_override` | full workflow 用 `build_mode=direct` 时 | `true` |
+| `verification_report` | verify→archive 前 | `<path>` |
+| `branch_status` | verify→archive 前 | `handled` |
+
+## 可选字段
+
+| 字段 | 取值 | 说明 |
+|------|------|------|
+| `issue_repo` | `null\|<owner/repo>` | Issue 所在 repo；`gh issue close --repo` 用 |
+| `verify_mode` | `null\|light\|full` | 由 `smart-state.sh scale` 设置 |
+| `verified_at` | `null\|YYYY-MM-DD` | verify-pass 时写入 |
+| `context_compression` | `off\|beta` | **v1 只实现 `off`；`beta` 为 stub** |
+| `plan` | `null\|<path>` | 实施计划文件路径 |
+| `build_pause` | `null\|plan-ready` | plan-ready 暂停标记（不是执行方式） |
+| `direct_override` | `null\|true` | full workflow 用 direct 的显式 override |
+| `handoff_context` | `null\|<path>` | 由 `smart-handoff.sh --write` 写入 |
+| `handoff_hash` | `null\|<sha256>` | 由 `smart-handoff.sh --write` 写入 |
+| `build_command` | `null\|<cmd>` | 项目级构建命令（guard 探测） |
+| `verify_command` | `null\|<cmd>` | 项目级验证命令 |
+
+## 项目级配置 `.smart/config.yaml`
+
+类比 Comet 的 `.comet/config.yaml`。放仓库根，提供默认值：
+
+```yaml
+context_compression: off      # v1 只支持 off
+review_mode: off              # 默认审查模式
+auto_transition: true         # 默认自动衔接
+# build_command: npm run build  # 可选
+# verify_command: npm test      # 可选
+```
+
+`smart-state.sh init` 创建 change 时，`auto_transition`/`context_compression`/`review_mode` 从项目配置取默认值（v1：硬编码默认 true/off/off；读取项目配置为 v1.1 待办）。
+
+## v1 实现范围
+
+- 已实现：上述全部字段的读写（`smart-state.sh init/set/get`）、`transition` 事件、`check` 入口校验、`next`/`scale`
+- stub：`context_compression: beta`（handoff 双格式未实现，v1 只 compact 单格式）
+- 待办（v1.1）：从 `.smart/config.yaml` 读取项目级默认值；`build_command`/`verify_command` 探测