@deepstorm/cli 0.1.0

package/dist/skills/reef-harden/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: reef-harden
+description: 对 AI 生成的 spec、proposal、design、tasks 等 SDD 文档进行系统性加固。使用四道筛 + 反向 grill + Known Limitations 沉淀。当 AI 刚写完或用户想审查 spec/proposal/design/tasks 文档时触发，尤其当用户说"加固spec"、"按四道筛过"、"补不做什么"、"补known limitation" 或需要改进 SDD 文档质量时。
+allowed-tools: Bash(git:*), Bash(find:*), Read, Edit, Write
+deepstorm:
+  tool: reef
+---
+
+# Spec Hardener
+
+## 上下文约定
+
+当前 change 名 = 当前分支名（由 jira-start 阶段三建立）：
+
+```bash
+# 自动发现当前 change
+CHANGE=$(git branch --show-current)
+CHANGE_DIR="openspec/changes/$CHANGE"
+
+# 如分支名与 change 目录不匹配，遍历所有 change 取最近一个
+if [ ! -d "$CHANGE_DIR" ]; then
+  CHANGE=$(ls -t openspec/changes/ 2>/dev/null | head -1)
+  CHANGE_DIR="openspec/changes/$CHANGE"
+fi
+
+# 如仍无结果，列出所有 change 让用户选择
+if [ ! -d "$CHANGE_DIR" ]; then
+  echo "未找到 openspec change，可用的目录:"
+  ls openspec/changes/
+  echo "请指定 change 名"
+fi
+```
+
+## 快速开始
+
+```
+1. 读取当前 change 下所有 SDD 文档（含 design.md 的 Change Scope Matrix）
+2. 按顺序过五道筛：硬数字 → 不做什么 → 验证方法 → 影响链完整性 → 反向 grill
+3. 将发现直接编辑回文档
+4. 将反向 grill 产出的关键风险沉淀为 Known Limitations
+```
+
+## 工作流
+
+### Step 1: 加载文档
+
+```bash
+# 列出当前 change 下所有 SDD 文档
+find "$CHANGE_DIR" -name "*.md" -maxdepth 2 | sort
+```
+
+读取所有这些文档。目录结构通常为：
+
+```
+openspec/changes/<change>/
+├── proposal.md
+├── specs/
+│   ├── 01-core-scenario.md
+│   └── 02-error-scenario.md
+├── design.md
+└── tasks.md
+```
+
+### Step 2: 五道筛
+
+按顺序过筛，每道筛产出可直接编辑到文档中的内容：
+
+#### 第一道筛：特定数字
+
+搜索文档中所有具体数字（5MB、3000、80%、100ms 等），逐一判断：
+- 有引用来源（benchmark、SLA、Figma 等）→ 通过
+- 无引用来源 → 标注 TBD 或在旁边加上 Rationale 说明理由
+- 禁止让"看起来合理但无根据"的数字留在文档里
+
+#### 第二道筛："不做什么"
+
+检查是否存在 `## 不做什么` / `## Out of Scope` 段：
+- 若不存在 → 必须新增
+- 若存在但内容敷衍（< 5 条）→ 用反向提问扩充："这个功能在第一版里应该不做什么？"
+
+至少应覆盖：
+- 不支持的功能/控件/场景（明确列出）
+- 第一版 scale 边界（并发、文件大小、批量操作等）
+- 是 permanent out 还是 v2 做（标注）
+
+#### 第三道筛：验证方法
+
+检查所有验证要求，确保每一条可执行：
+- "定期 review" → 不合格，追问为"谁、频率、用什么工具"
+- "写测试" → 不合格，细化为"FormExportServiceTest：覆盖 X/Y/Z 场景"
+- 每条验证应对应一个 CI 命令或具体测试步骤
+
+#### 第四道筛：影响链完整性
+
+读取 design.md 中的 Change Scope Matrix，遍历矩阵每一层的变更，检查 `specs/` 中是否有对应场景覆盖：
+
+```
+| Matrix 层 | 变更内容 | specs 覆盖 |
+|-----------|---------|-----------|
+| Entity 新增字段 | status | ✅ specs/cap1-spec.md 场景 4 |
+| Controller 新增接口 | POST /users/{id}/approve | ❌ 缺少异常响应场景 |
+| Migration 新增列 | status VARCHAR | ⚠️ 需要回滚场景 |
+```
+
+- ✅ 已覆盖 → 通过
+- ❌ 缺失 → 标记不合格，要求补充对应场景
+- ⚠️ 需人工确认 → 标记提示（如回滚、迁移数据完整性等跨层场景）
+
+**为什么要放在第四道：** 在确认数字合理、边界明确、可验证之后，再从架构层面确认每层变更都有 spec 兜底。不满足此筛时不进入反向 grill，避免在不完整的基础上做无意义质疑。
+
+#### 第五道筛：反向 Grill
+
+以质疑者立场追问自己刚写的 spec：
+"请你从质疑者的角度，给我列五个这份 spec 可能在三个月后让我后悔的地方。"
+
+将产出中有价值的点作为 Known Limitations 或风险标注回文档。
+
+### Step 3: 沉淀 Known Limitations
+
+在 proposal.md 末尾添加 `## Known Limitations` 段，内容来源：
+1. 第二步"不做什么"中标注的边界
+2. 第四步反向 grill 中不可忽视的风险点
+3. 已知但有意推迟的 trade-off
+
+格式：每条限制包含**标题**（加粗）+ 解释原因（一行）。
+
+### Step 4: 汇报
+
+输出一张改动清单：按文档列修改了什么，新增了什么段。
+
+## 注意事项
+
+- 业务指标类数字（如 SLA 数值）若用户确认则无需修改
+- 不要强行给所有数字标 TBD，需要对有根据的数字（如引用 Figma 的颜色值）放行
+- 反向 grill 产出的五点中，选取可落地的 3-5 条写入文档，而非全量
+- 所有编辑应保持原文档风格和格式一致

package/dist/skills/reef-pr/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: reef-pr
+description: 将当前分支的变更创建为 GitHub PR。读取 commits 和 OpenSpec 上下文，生成 PR 描述并提交。用户说「创建 PR」「发起 PR」「pull request」「提 PR」「提交 PR」时触发。
+allowed-tools: Bash(git:*), Bash(gh:*)
+deepstorm:
+  tool: reef
+---
+
+# 创建 Pull Request
+
+## 前置条件
+
+- GitHub CLI (gh) 已安装并登录
+- 当前分支有已提交的 commits
+- `git push` 未阻塞（有远程权限）
+
+## 上下文约定
+
+当前分支名即 OpenSpec change 名（由 jira-start 阶段三创建分支时建立）：
+
+```bash
+BRANCH=$(git branch --show-current)
+CHANGE_DIR="openspec/changes/$BRANCH"
+```
+
+## 工作流
+
+### 1. 收集上下文
+
+先检查未提交变更。如有则提示「请先 commit 再创建 PR」，中止流程。
+
+```bash
+BRANCH=$(git branch --show-current)
+FORK_POINT=$(git merge-base main HEAD 2>/dev/null)
+echo "Branch: $BRANCH"; git status -sb
+echo "Commits:"; git log "$FORK_POINT"..HEAD --oneline
+echo "Changes:"; git diff "$FORK_POINT"..HEAD --stat
+ls -d openspec/changes/$BRANCH/*.md 2>/dev/null
+```
+
+如有 OpenSpec change，读取 `proposal.md` 和 `tasks.md` 作为描述素材。
+
+### 2. 构建 PR 信息
+
+**标题：** OpenSpec proposal 标题优先，否则取第一个 commit 标题。≤ 70 字符。
+
+**正文：**
+
+```markdown
+## Summary
+{2-4 行概括变更动机，优先从 proposal.md 提取}
+## 关联
+JIRA: {commit body / proposal.md / jira-start 元数据}
+OpenSpec: openspec/changes/{branch-name}/
+## 变更清单
+{git diff --stat 输出}
+## Test plan
+- [ ] {前端路径含 src/main/web/ 则加}
+- [ ] {后端路径含 src/main/java/ 则加}
+- [ ] {手动验证步骤，如有}
+```
+
+### 3. 展示并确认
+
+展示 PR 标题和正文。问用户：
+
+- 「需要加 reviewer 和 label 吗？」
+- 「创建 Draft PR？」
+- 「没问题，创建」— 执行步骤 4
+- 「修改一下标题/描述」— 修改后执行
+
+### 4. 推送并创建 PR
+
+先检查是否已有打开的 PR：
+
+```bash
+EXISTING_PR=$(gh pr view --json url 2>/dev/null)
+```
+
+如有则询问「已有 PR，是否更新描述？」，用户确认后用 `gh pr update` 更新；否则正常创建：
+
+```bash
+# 首次推送当前分支
+git push -u origin $(git branch --show-current)
+
+# 创建 PR（如有 reviewer/label/draft 则追加对应参数）
+gh pr create \
+  --title "<标题>" \
+  --body "<正文>" \
+  [--reviewer "<用户>"] \
+  [--label "<标签>"] \
+  [--draft]
+```
+
+### 5. 输出结果
+
+返回 PR 链接。

package/dist/skills/reef-review/SKILL.md.tmpl

@@ -0,0 +1,107 @@
+---
+name: reef-review
+description: 对当前分支变更执行前后端代码审查。自动检测变更范围，派发 Sub‑Agent 执行审查并生成结构化报告。
+allowed-tools: Bash(git:*), Agent
+deepstorm:
+  tool: reef
+---
+
+# 统一代码审查（Sub‑Agent 模式）
+
+自动检测变更类别，派发对应 Sub‑Agent 执行审查。
+
+## 工作流
+
+### Step 1: 检测变更范围
+
+```bash
+# 获取 fork-point（检测当前分支基于哪个分支创建）
+FORK_POINT=$(git merge-base "$(git reflog --date=local | grep "checkout: moving from.* to $(git rev-parse --abbrev-ref HEAD)$" | head -1 | sed -n 's/.*from \([^ ]*\) to .*/\1/p' || echo main)" HEAD)
+echo "FORK_POINT=$FORK_POINT"
+echo "变更文件统计:"
+git diff "$FORK_POINT"..HEAD --stat
+
+# 按类别提取文件清单
+FILE_LIST=$(git diff "$FORK_POINT"..HEAD --name-only)
+FILE_COUNT=$(echo "$FILE_LIST" | wc -l | tr -d ' ')
+BACKEND_FILES=$(git diff "$FORK_POINT"..HEAD --name-only -- {{reef.backend.language.sourcePath}})
+FRONTEND_FILES=$(git diff "$FORK_POINT"..HEAD --name-only -- {{reef.frontend.framework.sourcePath}})
+INFRA_FILES=$(git diff "$FORK_POINT"..HEAD --name-only | grep -v '^{{reef.backend.language.sourcePath}}' | grep -v '^{{reef.frontend.framework.sourcePath}}')
+SECURITY_FILES=$(git diff "$FORK_POINT"..HEAD --name-only -- {{reef.backend.language.sourcePath}} {{reef.frontend.framework.sourcePath}} | grep -iE 'auth|tenant|security|oauth|token|password|permission' || true)
+```
+
+判断哪些类别有变更：
+
+| 类别 | 判断条件 |
+|------|---------|
+| 后端 | `BACKEND_FILES` 非空 |
+| 前端 | `FRONTEND_FILES` 非空 |
+| 基础配置 | `INFRA_FILES` 非空 |
+| 安全敏感 | `SECURITY_FILES` 非空 |
+| 无匹配 | 全部为空 |
+
+据此决定派发哪些 agent：
+
+| 有变更的类别 | 派发 agent |
+|-------------|-----------|
+| 仅后端 | `backend-code-audit` |
+| 仅前端 | `frontend-code-audit` |
+| 仅基础配置 | `infra-code-audit` |
+| 后端 + 基础配置 | 并行 `backend-code-audit` + `infra-code-audit` |
+| 前端 + 基础配置 | 并行 `frontend-code-audit` + `infra-code-audit` |
+| 全栈 | 并行 `backend-code-audit` + `frontend-code-audit` |
+| 全栈 + 基础配置 | 并行 `backend-code-audit` + `frontend-code-audit` + `infra-code-audit` |
+| **安全敏感变更** | 在以上基础上 **额外** 并行 `security-code-audit` |
+| 无匹配 | 输出提示，不派发 agent |
+
+> 安全敏感变更判定：SECURITY_FILES 非空 或 变更涉及权限/认证逻辑（由调用的 fork-point 范围决定）。
+
+### Step 2: 派发 Sub‑Agent
+
+每个 agent 按各自类别的文件清单构造 prompt。后端 agent 的清单含后端源文件，前端和 infra agent 只含自己的文件。
+
+| Agent | prompt 中的文件清单 |
+|-------|-------------------|
+| `backend-code-audit` | 后端文件 |
+| `frontend-code-audit` | 前端文件 |
+| `infra-code-audit` | 基础配置文件 |
+| `security-code-audit` | 安全敏感文件 + 所有变更文件中有安全风险的 diff |
+
+```
+Fork point: {FORK_POINT}
+变更文件数: {count}
+变更文件清单:
+{file_list}
+```
+
+Agent 的 system prompt（定义在 `.claude/agents/` 目录中）包含完整的 Checklist + Rules + 输出格式。
+
+| Agent | 定义文件 |
+|-------|---------|
+| `reef-review-backend` | `../../agents/reef-review-backend.md` |
+| `reef-review-frontend` | `../../agents/reef-review-frontend.md` |
+| `reef-review-infra` | `../../agents/reef-review-infra.md` |
+| `reef-review-security` | `../../agents/reef-review-security.md` |
+
+多 agent 场景全部使用 `run_in_background: true` 并行执行。每个 agent 设置超时 300 秒（5 分钟），超时未返回则标记为超时，继续等待其他 agent。
+
+### Step 3: 汇总报告
+
+1. 等待所有已派发的 agent 返回（收到全部 task-notification 后才汇总）。任一 agent 超时 300 秒未返回则标记为超时，继续等待其他 agent
+2. 分章节输出各 agent 的审查报告：
+
+```
+## 后端代码审查报告
+{后端 agent 输出}
+
+## 前端代码审查报告
+{前端 agent 输出}
+
+## 基础配置审查报告
+{infra agent 输出}
+
+## 安全审查报告
+{security agent 输出（仅安全敏感变更时）}
+```
+
+3. 最终结论取最低评分。若某 agent 失败（API Error / 超时等），标注失败原因，忽略其评分。仅有派发过的 agent 输出对应章节。

package/dist/skills/reef-scope/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: reef-scope
+description: 分支范围检查与拆分 — 在提交代码时验证分支是否涉及多个业务领域，以及自动拆分
+allowed-tools: Bash(git:*), Bash(curl:*), Bash(python3:*), Bash(reef-scope-check.sh:*)
+deepstorm:
+  tool: reef
+---
+
+# 分支范围检查 (Branch Scope Validation)
+
+在 `git commit` 和 CI/PR 时自动检测当前分支是否涉及多个业务领域，阻止跨领域提交，并提供自动拆分能力。
+
+## 工作原理
+
+```mermaid
+flowchart LR
+    COMMIT["git commit"] --> HOOK["pre-commit hook"]
+    HOOK --> CHECK["reef-scope-check.sh<br>AI 语义分析 diff"]
+    CHECK --> GATE{"涉及几个<br>业务领域？"}
+    GATE -->|"≤ 1"| PASS["✅ 通过<br>commit 继续"]
+    GATE -->|"> 1"| BLOCK["🚫 阻断<br>输出拆分建议"]
+    BLOCK --> USER{"用户确认<br>拆分？"}
+    USER -->|"是"| SPLIT["🔀 自动创建分支<br>拆分文件并提交"]
+    USER -->|"否"| ABORT["⏹ commit 取消<br>等待人工处理"]
+```
+
+## 命令清单
+
+### 检查分支范围
+
+```bash
+# 方式1: 自动获取当前分支与 main 的 diff
+bash packages/reef/hooks/reef-scope-check.sh
+
+# 方式2: 指定基准分支
+bash packages/reef/hooks/reef-scope-check.sh --diff-from develop
+
+# 方式3: 从 stdin 传入 diff
+git diff main...HEAD | bash packages/reef/hooks/reef-scope-check.sh
+```
+
+### 门禁检查（阻断式）
+
+```bash
+# 本地 commit 检查（exit code 2 = 多领域）
+bash packages/reef/hooks/reef-scope-gate.sh
+
+# CI 模式
+bash packages/reef/hooks/reef-scope-gate.sh --ci
+```
+
+### 安装与卸载
+
+```bash
+# 安装 pre-commit hook（git commit 时自动检查）
+bash packages/reef/hooks/reef-scope-setup.sh install
+
+# 查看安装状态
+bash packages/reef/hooks/reef-scope-setup.sh status
+
+# 卸载
+bash packages/reef/hooks/reef-scope-setup.sh uninstall
+```
+
+### 分支拆分
+
+```bash
+# 分析并拆分多领域分支
+bash packages/reef/hooks/reef-scope-split.sh
+```
+
+## 配置文件
+
+安装后生成 `.deepstorm/scope-config.json`：
+
+```json
+{
+  "enabled": true,
+  "ciEnabled": true,
+  "domains": []
+}
+```
+
+- `enabled`: 本地 commit 门禁开关
+- `ciEnabled`: CI 门禁开关（独立控制）
+- `domains`: 项目业务领域列表（空 = AI 自由分类，非空 = AI 对齐到这些领域）
+
+## 使用流程
+
+1. **安装**: 运行一次 `reef-scope-setup.sh install`
+2. **日常开发**: 正常 `git commit`，多领域时自动阻断
+3. **被阻断时**: 查看拆分建议 → `reef-scope-split.sh` → 确认 → 自动拆分
+4. **CI 集成**: 在 CI 流程中调用 `reef-scope-ci.sh`
+
+## CI 集成示例
+
+### GitHub Actions
+
+```yaml
+- name: Check branch scope
+  run: |
+    bash packages/reef/hooks/reef-scope-ci.sh --diff-from ${{ github.base_ref }}
+```
+
+### GitLab CI
+
+```yaml
+scope-check:
+  script:
+    - bash packages/reef/hooks/reef-scope-ci.sh --diff-from $CI_MERGE_REQUEST_TARGET_BRANCH_NAME
+```
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `ANTHROPIC_API_KEY` | — | Claude API Key（优先使用） |
+| `OPENAI_API_KEY` | — | OpenAI API Key（备选） |
+| `LLM_MODEL` | `claude-sonnet-4-20250514` | 使用的模型 |
+| `MAX_DIFF_CHARS` | 20000 | diff 截断字符数 |
+
+## 常见问题
+
+**Q: 我不想在所有项目上都启用这个检查？**
+A: 每个项目独立安装和配置，`scope-config.json` 中的 `enabled: false` 可关闭。
+
+**Q: 我改了文档也要被阻断吗？**
+A: 不会。文档（markdown、README 等）变更会被归类为 `documentation` 领域，不计入多领域阻断判断。
+
+**Q: 没有 API Key 怎么办？**
+A: 工具会 fallback 到跳过模式，不阻断提交但输出提示消息。
+
+**Q: 拆分后原来分支的未提交变更还在吗？**
+A: 会先自动 stash 备份，拆分执行完成后恢复。