@gepeiyu/smart 0.1.1 → 0.1.2

package/README.md

@@ -1,13 +1,24 @@
-# Smart — GitHub Issue 驱动的 OpenSpec 变更流程 agent skill
+# Smart — 把 GitHub Issue 当作全流程变更容器
 
-Smart 让 AI agent 把一个 GitHub Issue 当作 `issue → design → build → verify → archive` 全流程容器推进，直到 Issue 可关闭。一条 Issue = 一个 OpenSpec change；Issue 关闭 ≈ change 归档。
+> 一条 Issue = 一次 `issue → design → build → verify → archive`；Issue 关闭即变更归档。
 
-- **工具中性**：`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` 归档
+Smart 是一个 agent skill：AI agent 读到一条 GitHub Issue 后，把它当作从需求到归档的整条变更流水线推进——读 Issue 取需求（`gh issue view`）、各阶段向 Issue 回写进度（`gh issue comment`）、归档时关闭 Issue（`gh issue close`）。状态机由纯 Bash 脚本驱动，工具中性。
 
-## 安装（npm）
+## Issue 在 Smart 里是什么
+
+一条 Issue 不只是待办项，而是**一个变更的完整生命周期容器**：
+
+| 阶段 | Issue 的角色 |
+|------|-------------|
+| issue | 触发源——`gh issue view` 读正文/评论，解析为目标/范围/验收 |
+| design | 进度面——回写 Design Doc 链接 |
+| build | 进度面——每完成一个 task 回写勾选进度 |
+| verify | 结论面——回写验证结论 |
+| archive | 关闭信号——`gh issue close`，Issue 关闭 ≈ 变更归档 |
+
+OpenSpec 负责规格（`openspec/specs/` + `openspec/changes/` + `openspec/changes/archive/` 三层），纯 Bash 脚本负责状态机（`.smart.yaml`），Superpowers 负责设计与执行方法论。
+
+## 安装
 
 ```bash
 npm install -g @gepeiyu/smart
@@ -15,80 +26,100 @@ 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`。
+或免全局安装：`npx @gepeiyu/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`。
 
-无需全局安装也可用：
+## 上手（30 秒）
 
 ```bash
-npx @gepeiyu/smart init
+smart init                                         # 在项目里部署 Smart
+gh issue create --title "..." --body "..."         # 建一条 Issue
+# 在 AI 平台里：/smart-issue #1
 ```
 
+`/smart-issue #1` 会用 `gh issue view 1` 拉取 Issue 内容作为需求种子，建 OpenSpec change + `.smart.yaml`，回写收纳评论，然后自动推进 design → build → verify → archive，归档时 `gh issue close 1`。
+
+也可以用描述触发（不绑 Issue）：`/smart-issue <描述>`。
+
 ## CLI 命令
 
 | 命令 | 作用 |
 |------|------|
-| `smart init [path]` | 初始化（检测平台/部署 skill/装依赖/建工作目录）；`--yes` 非交互，`--no-deps` 跳过依赖 |
+| `smart init [path]` | 部署 skill + 装依赖 + 建工作目录（`--yes` 非交互，`--no-deps` 跳过依赖） |
 | `smart status [path]` | 显示活跃 change 与 phase/issue |
-| `smart uninstall [path]` | 卸载 Smart skill（保留 openspec/changes 等用户数据）；`--force` 跳过确认 |
+| `smart uninstall [path]` | 移除 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 前面。
+## 技能清单
 
-## 文件清单
+| 命令 | 阶段 | 作用 |
+|------|------|------|
+| `/smart` | — | 主入口：自动检测当前 change 阶段并分派 |
+| `/smart-issue` | 1 | 从 Issue/描述开启变更（`#ID` 经 `gh` 拉取） |
+| `/smart-design` | 2 | 深度设计（brainstorming + Design Doc） |
+| `/smart-build` | 3 | 计划与构建（实现代码） |
+| `/smart-verify` | 4 | 验证与收尾 |
+| `/smart-archive` | 5 | 归档（合并 spec + `gh issue close`） |
+| `/smart-hotfix` | 预设 | 快速 bug 修复（跳过 brainstorming） |
+| `/smart-tweak` | 预设 | 小改动（文案/配置/文档） |
 
-```
-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            # 项目级配置（可选）
-```
+## 守护脚本（纯 Bash）
 
-## 如何在你用的工具里加载 Smart
+| 脚本 | 用途 |
+|------|------|
+| `smart-env.sh` | 脚本定位 + env 加载 + 共享 helper |
+| `smart-state.sh` | `.smart.yaml` 状态机（init/check/set/get/transition/next/scale/task-checkoff） |
+| `smart-guard.sh` | 阶段守卫（`--apply` 推进 phase；校验交接 hash、Design Doc frontmatter、build 决策） |
+| `smart-handoff.sh` | 交接包生成（带 SHA256 追踪，`--write`/`--hash-only`） |
+| `smart-archive.sh` | 一键归档（合并主 spec + 移动 change + `gh issue close`） |
 
-Smart 的触发方式因工具而异，但 `SKILL.md` 主体保持中性。各工具只需按其惯用方式让 agent 读到 `SKILL.md` 并能执行 `bash scripts/smart-*.sh`。
+## 工作流
 
-### opencode
+```
+/smart（检测阶段）
+  ↓
+/smart-issue ──→ /smart-design ──→ /smart-build ──→ /smart-verify ──→ /smart-archive
+   读 Issue         Design Doc        实现代码          验证报告          gh issue close
 
-把 Smart 放进 `.opencode/skills/smart/`（含 `SKILL.md` + `scripts/` + `reference/`）。然后用 `/smart <issue-number>` 或「请用 smart 推进 #<n>」触发。opencode 会加载 `.opencode/skills/smart/SKILL.md`。
+/smart-hotfix：issue → build → verify → archive（跳过 brainstorming）
+/smart-tweak：  issue → 轻量 build → 轻量 verify → archive
+```
 
-### Claude Code
+阶段衔接由 `smart-state.sh next` 输出下一步该调的子 skill；agent 据此自动推进，遇到用户决策点（澄清确认/方案确认/plan-ready/验证失败/归档前）暂停等待。
 
-把 `SKILL.md` + `scripts/` + `reference/` 放进 `.claude/skills/smart/`。在对话中引用：「读取 `.claude/skills/smart/SKILL.md`，用 Smart 流程推进 Issue #<n>」。
+## 状态机
 
-### Cursor
+每个变更在 `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` 读写（本地流程仍完整）。
 
-把 `SKILL.md` 内容作为项目规则放进 `.cursor/rules/smart.mdc`（或 `.cursorrules`），并把 `scripts/` 保留在仓库根。触发：「用 Smart 流程推进 Issue #<n>」。
+项目级配置在 `.smart/config.yaml`（`context_compression`/`review_mode`/`auto_transition` 默认值）。字段详见 `reference/smart-yaml-fields.md`。
 
-### Codex（OpenAI）
+## 前置依赖
 
-在 `AGENTS.md` 引用 Smart：写一行「变更流程遵循 `SKILL.md`（Smart）；触发时用 `bash scripts/smart-*.sh` 管理状态」。触发：「用 Smart 推进 Issue #<n>」。
+| 依赖 | 要求 | 验证 |
+|------|------|------|
+| Node.js | 20+ | `node --version` |
+| `gh` CLI | 已登录 | `gh auth status` |
+| OpenSpec CLI | `smart init` 代装，或手动 `npm i -D @fission-ai/openspec` | `npx openspec --version` |
+| Bash | 5.x（Windows 用 Git Bash） | `bash --version` |
+| git | 任意 | `git --version` |
 
-### 其他工具
+Windows 注意：PATH 的 `bash` 可能指向 WSL（不可用）；用 Git Bash 的 `bash.exe`，或把 Git Bash 的 `bin` 加到 PATH 前面。
 
-任何能读 Markdown 规则文件、能执行 shell 命令的 agent 工具都可加载 Smart：把 `SKILL.md` 作为规则注入，把 `scripts/` 放在仓库可执行路径，触发时给 Issue 编号即可。
+## 项目结构
 
-## 快速验证（安装后）
+```
+your-project/
+├── .smart/config.yaml              # 项目级配置
+├── .opencode/skills/               # 部署的 skill（.claude/.cursor 等同理）
+│   ├── smart/{SKILL.md, scripts/, reference/}
+│   └── smart-{issue,design,build,verify,archive,hotfix,tweak}/SKILL.md
+├── openspec/                       # OpenSpec 规格
+│   ├── specs/                      # 主 spec（归档时从 delta 合并）
+│   └── changes/<name>/             # 活跃变更（含 .smart.yaml）
+└── docs/superpowers/{specs,plans,reports}/   # Design Doc / 计划 / 验证报告
+```
 
-```bash
-# 语法检查
-bash -n scripts/smart-*.sh
+## License
 
-# 状态机自检（对一个已有 change）
-bash scripts/smart-state.sh check <change-name> issue
-bash scripts/smart-state.sh next <change-name>
-```
+MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gepeiyu/smart",
-  "version": "0.1.1",
-  "description": "Smart — GitHub Issue 驱动的 OpenSpec 变更流程 agent skill (comet mirror)",
+  "version": "0.1.2",
+  "description": "Smart — GitHub Issue 驱动的 OpenSpec 变更流程 agent skill",
   "type": "module",
   "bin": {
     "smart": "./bin/smart.js"
@@ -29,7 +29,6 @@
     "superpowers",
     "agent-skill",
     "github-issue",
-    "comet",
     "spec-driven"
   ],
   "license": "MIT",