specops 0.2.3 → 0.2.4

package/.opencode/skills/using-git-worktrees/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: using-git-worktrees
+description: 开始需要与当前工作区隔离的功能开发时使用，或在执行实现计划前使用，创建带有智能目录选择和安全验证的隔离 git 工作树
+---
+
+# 使用 Git 工作树
+
+## 概述
+
+Git 工作树创建共享同一仓库的隔离工作区，允许同时在多个分支上工作而无需切换。
+
+**核心原则：** 系统化目录选择 + 安全验证 = 可靠隔离。
+
+**开始时宣布：** "我正在使用 using-git-worktrees skill 来设置隔离工作区。"
+
+## 目录选择流程
+
+按以下优先级顺序：
+
+### 1. 检查现有目录
+
+```bash
+# 按优先级检查
+ls -d .worktrees 2>/dev/null     # 首选（隐藏）
+ls -d worktrees 2>/dev/null      # 备选
+```
+
+**如果找到：** 使用该目录。如果两个都存在，`.worktrees` 优先。
+
+### 2. 检查 CLAUDE.md
+
+```bash
+grep -i "worktree.*director" CLAUDE.md 2>/dev/null
+```
+
+**如果指定了偏好：** 直接使用，不用询问。
+
+### 3. 询问用户
+
+如果没有现有目录且 CLAUDE.md 中没有偏好：
+
+```
+未找到工作树目录。应该在哪里创建工作树？
+
+1. .worktrees/（项目本地，隐藏）
+2. ~/.config/specops/worktrees/<项目名>/（全局位置）
+
+你倾向哪个？
+```
+
+## 安全验证
+
+### 项目本地目录（.worktrees 或 worktrees）
+
+**创建工作树前必须验证目录被忽略：**
+
+```bash
+# 检查目录是否被忽略（遵循本地、全局和系统 gitignore）
+git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+```
+
+**如果未被忽略：**
+
+按照"立即修复坏掉的东西"原则：
+1. 在 .gitignore 中添加相应行
+2. 提交变更
+3. 继续创建工作树
+
+**为什么关键：** 防止意外将工作树内容提交到仓库。
+
+### 全局目录（~/.config/specops/worktrees）
+
+不需要 .gitignore 验证，完全在项目之外。
+
+## 创建步骤
+
+### 1. 检测项目名称
+
+```bash
+project=$(basename "$(git rev-parse --show-toplevel)")
+```
+
+### 2. 创建工作树
+
+```bash
+# 确定完整路径
+case $LOCATION in
+  .worktrees|worktrees)
+    path="$LOCATION/$BRANCH_NAME"
+    ;;
+  ~/.config/specops/worktrees/*)
+    path="~/.config/specops/worktrees/$project/$BRANCH_NAME"
+    ;;
+esac
+
+# 创建工作树并新建分支
+git worktree add "$path" -b "$BRANCH_NAME"
+cd "$path"
+```
+
+### 3. 运行项目设置
+
+自动检测并运行相应的设置：
+
+```bash
+# Node.js
+if [ -f package.json ]; then npm install; fi
+
+# Rust
+if [ -f Cargo.toml ]; then cargo build; fi
+
+# Python
+if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+if [ -f pyproject.toml ]; then poetry install; fi
+
+# Go
+if [ -f go.mod ]; then go mod download; fi
+```
+
+### 4. 验证干净基线
+
+运行测试确保工作树起始状态干净：
+
+```bash
+# 示例 - 使用项目对应的命令
+npm test
+cargo test
+pytest
+go test ./...
+```
+
+**如果测试失败：** 报告失败，询问是否继续还是排查。
+
+**如果测试通过：** 报告就绪。
+
+### 5. 报告位置
+
+```
+工作树就绪，位于 <完整路径>
+测试通过（<N> 个测试，0 个失败）
+准备实现 <功能名称>
+```
+
+## 快速参考
+
+| 情况 | 操作 |
+|------|------|
+| `.worktrees/` 存在 | 使用它（验证已忽略） |
+| `worktrees/` 存在 | 使用它（验证已忽略） |
+| 两个都存在 | 使用 `.worktrees/` |
+| 都不存在 | 检查 CLAUDE.md → 询问用户 |
+| 目录未被忽略 | 添加到 .gitignore + 提交 |
+| 基线测试失败 | 报告失败 + 询问 |
+| 没有 package.json/Cargo.toml | 跳过依赖安装 |
+
+## 常见错误
+
+### 跳过忽略验证
+
+- **问题：** 工作树内容被跟踪，污染 git status
+- **修正：** 创建项目本地工作树前始终使用 `git check-ignore`
+
+### 假设目录位置
+
+- **问题：** 造成不一致，违反项目约定
+- **修正：** 遵循优先级：现有 > CLAUDE.md > 询问
+
+### 测试失败时继续
+
+- **问题：** 无法区分新 bug 和已有问题
+- **修正：** 报告失败，获得明确许可后再继续
+
+### 硬编码设置命令
+
+- **问题：** 在使用不同工具的项目上会坏
+- **修正：** 从项目文件自动检测（package.json 等）
+
+## 示例工作流
+
+```
+你：我正在使用 using-git-worktrees skill 来设置隔离工作区。
+
+[检查 .worktrees/ - 存在]
+[验证已忽略 - git check-ignore 确认 .worktrees/ 被忽略]
+[创建工作树：git worktree add .worktrees/auth -b feature/auth]
+[运行 npm install]
+[运行 npm test - 47 个通过]
+
+工作树就绪，位于 /Users/jesse/myproject/.worktrees/auth
+测试通过（47 个测试，0 个失败）
+准备实现 auth 功能
+```
+
+## 红线
+
+**绝对不要：**
+- 不验证是否被忽略就创建工作树（项目本地）
+- 跳过基线测试验证
+- 测试失败时不询问就继续
+- 位置不明确时假设目录位置
+- 跳过 CLAUDE.md 检查
+
+**始终：**
+- 遵循目录优先级：现有 > CLAUDE.md > 询问
+- 项目本地目录验证是否被忽略
+- 自动检测并运行项目设置
+- 验证干净的测试基线
+
+## 集成
+
+**被调用方：**
+- **specops:brainstorming**（阶段 4）- 设计通过且要开始实现时必需
+- **specops:subagent-driven-development** - 执行任何任务前必需
+- **specops:executing-plans** - 执行任何任务前必需
+- 任何需要隔离工作区的 skill
+
+**配合使用：**
+- **specops:finishing-a-development-branch** - 工作完成后清理必需

package/.opencode/skills/using-superpowers/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: using-superpowers
+description: "在开始任何对话时使用 - 建立如何查找和使用 skill，要求在任何响应（包括澄清问题）之前先调用 Skill 工具"
+triggers:
+  - "开始对话"
+  - "新任务"
+  - "检查 skill"
+---
+
+<EXTREMELY-IMPORTANT>
+如果你认为哪怕只有 1% 的可能性某个 skill 适用于你正在做的事情，你绝对必须调用那个 skill。
+
+如果某个 SKILL 适用于你的任务，你没有选择。你必须使用它。
+
+这不可商量。这不是可选的。你不能给自己找理由跳过。
+</EXTREMELY-IMPORTANT>
+
+## 如何访问 Skill
+
+**在 Claude Code 中：** 使用 `Skill` 工具。调用 skill 时，其内容会被加载并展示给你，直接按照它执行。永远不要用 Read 工具读取 skill 文件。
+
+**在其他环境中：** 查看你所在平台的文档了解 skill 的加载方式。
+
+# 使用 Skill
+
+## 规则
+
+**在任何响应或行动之前，先调用相关或被请求的 skill。** 哪怕只有 1% 的可能性某个 skill 适用，你也应该调用它来检查。如果调用后发现不适合当前情况，你不需要使用它。
+
+```dot
+digraph skill_flow {
+    "收到用户消息" [shape=doublecircle];
+    "即将进入规划模式？" [shape=doublecircle];
+    "已经做过头脑风暴？" [shape=diamond];
+    "调用 brainstorming skill" [shape=box];
+    "可能有 skill 适用？" [shape=diamond];
+    "调用 Skill 工具" [shape=box];
+    "宣布：'使用 [skill] 来 [目的]'" [shape=box];
+    "有检查清单？" [shape=diamond];
+    "为每项创建 TodoWrite 任务" [shape=box];
+    "严格按照 skill 执行" [shape=box];
+    "响应（包括澄清问题）" [shape=doublecircle];
+
+    "即将进入规划模式？" -> "已经做过头脑风暴？";
+    "已经做过头脑风暴？" -> "调用 brainstorming skill" [label="否"];
+    "已经做过头脑风暴？" -> "可能有 skill 适用？" [label="是"];
+    "调用 brainstorming skill" -> "可能有 skill 适用？";
+
+    "收到用户消息" -> "可能有 skill 适用？";
+    "可能有 skill 适用？" -> "调用 Skill 工具" [label="是，哪怕只有 1%"];
+    "可能有 skill 适用？" -> "响应（包括澄清问题）" [label="确定没有"];
+    "调用 Skill 工具" -> "宣布：'使用 [skill] 来 [目的]'";
+    "宣布：'使用 [skill] 来 [目的]'" -> "有检查清单？";
+    "有检查清单？" -> "为每项创建 TodoWrite 任务" [label="是"];
+    "有检查清单？" -> "严格按照 skill 执行" [label="否"];
+    "为每项创建 TodoWrite 任务" -> "严格按照 skill 执行";
+}
+```
+
+## 危险信号
+
+这些想法意味着停下来。你在给自己找理由：
+
+| 想法 | 现实 |
+|------|------|
+| "这只是个简单问题" | 问题也是任务。检查 skill。 |
+| "我需要先了解更多上下文" | Skill 检查在澄清问题之前。 |
+| "让我先看看代码库" | Skill 会告诉你怎么看。先检查。 |
+| "我可以快速查一下 git/文件" | 文件缺少对话上下文。检查 skill。 |
+| "让我先收集信息" | Skill 会告诉你怎么收集信息。 |
+| "这不需要正式的 skill" | 如果 skill 存在，就用它。 |
+| "我记得这个 skill" | Skill 会更新。读当前版本。 |
+| "这不算一个任务" | 行动 = 任务。检查 skill。 |
+| "这个 skill 太重了" | 简单的事情会变复杂。用它。 |
+| "我先做这一件事" | 做任何事之前先检查。 |
+| "这样做效率很高" | 没有纪律的行动浪费时间。Skill 能防止这种情况。 |
+| "我知道那是什么意思" | 知道概念 ≠ 使用 skill。调用它。 |
+
+## Skill 优先级
+
+当多个 skill 可能适用时，按这个顺序：
+
+1. **流程 skill 优先**（brainstorming、systematic-debugging）- 这些决定如何处理任务
+2. **实现 skill 其次**（frontend-design、mcp-builder）- 这些指导执行
+
+"来构建 X" → 先 brainstorming，然后进入 specops 需求分析流程。
+"修复这个 bug" → 先 systematic-debugging，然后是领域相关的 skill。
+
+## Skill 类型
+
+**刚性**（TDD、debugging）：严格遵循。不要为了适应而放弃纪律。
+
+**柔性**（模式类）：根据上下文调整原则。
+
+Skill 本身会告诉你它属于哪种。
+
+## 用户指令
+
+指令说的是做什么，不是怎么做。"添加 X" 或 "修复 Y" 不意味着跳过工作流。

package/.opencode/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: verification-before-completion
+description: 在声称工作完成、修复成功或测试通过之前使用，在提交或创建 PR 之前，要求运行验证命令并确认输出后才能做出任何成功声明；证据先于断言，始终如此
+---
+
+# 完成前验证
+
+## 概述
+
+在没有验证的情况下声称工作完成，是不诚实，不是高效。
+
+**核心原则：** 证据先于声明，始终如此。
+
+**违反这条规则的字面意思就是违反这条规则的精神。**
+
+## 铁律
+
+```
+没有新鲜的验证证据，就不能声称完成
+```
+
+如果你在这条消息中没有运行验证命令，你不能声称它通过了。
+
+## 门控函数
+
+```
+在声称任何状态或表达满意之前：
+
+1. 识别：什么命令能证明这个声明？
+2. 运行：执行完整命令（新鲜的、完整的）
+3. 阅读：完整输出，检查退出码，计算失败数
+4. 验证：输出是否确认了声明？
+   - 如果否：用证据陈述实际状态
+   - 如果是：带着证据陈述声明
+5. 然后才能：做出声明
+
+跳过任何步骤 = 撒谎，不是验证
+```
+
+## 常见失败
+
+| 声明 | 需要 | 不够 |
+|------|------|------|
+| 测试通过 | 测试命令输出：0 失败 | 之前的运行结果，"应该通过" |
+| Linter 干净 | Linter 输出：0 错误 | 部分检查，推断 |
+| 构建成功 | 构建命令：exit 0 | Linter 通过，日志看起来没问题 |
+| Bug 修复了 | 测试原始症状：通过 | 代码改了，假设修好了 |
+| 回归测试有效 | 红-绿循环已验证 | 测试通过了一次 |
+| Agent 完成了 | VCS diff 显示变更 | Agent 报告"成功" |
+| 需求满足 | 逐行检查清单 | 测试通过 |
+| 验收通过 | specops 验收运行器：全部 PASS | 只跑了部分检查 |
+
+## 危险信号 - 停下来
+
+- 使用"应该"、"大概"、"看起来"
+- 在验证之前表达满意（"太好了！"、"完美！"、"搞定！"等）
+- 准备在没有验证的情况下提交/推送/创建 PR
+- 信任 agent 的成功报告
+- 依赖部分验证
+- 想着"就这一次"
+- 累了想赶紧结束
+- **任何暗示成功但没有运行验证的措辞**
+
+## 合理化防御
+
+| 借口 | 现实 |
+|------|------|
+| "现在应该能用了" | 运行验证 |
+| "我很有信心" | 信心 ≠ 证据 |
+| "就这一次" | 没有例外 |
+| "Linter 通过了" | Linter ≠ 编译器 |
+| "Agent 说成功了" | 独立验证 |
+| "我累了" | 疲劳 ≠ 借口 |
+| "部分检查够了" | 部分什么都证明不了 |
+| "换个说法所以规则不适用" | 精神高于字面 |
+
+## specops 验收集成
+
+在 specops 工作流中，验收不只是运行测试：
+
+1. **自动验收**：specops acceptance runner 串联 tsc + vitest + tech-guard + 偷懒检测
+2. **E2E 验收**：验收 Agent 使用浏览器 MCP 走完业务流程
+3. **人工验收**：UAT 清单逐项确认
+
+每一项都必须有证据。不接受"应该通过了"。
+
+## 关键模式
+
+**测试：**
+```
+✅ [运行测试命令] [看到：34/34 通过] "所有测试通过"
+❌ "现在应该通过了" / "看起来对了"
+```
+
+**回归测试（TDD 红-绿）：**
+```
+✅ 写 → 运行（通过）→ 回退修复 → 运行（必须失败）→ 恢复 → 运行（通过）
+❌ "我写了回归测试"（没有红-绿验证）
+```
+
+**构建：**
+```
+✅ [运行构建] [看到：exit 0] "构建通过"
+❌ "Linter 通过了"（linter 不检查编译）
+```
+
+**需求：**
+```
+✅ 重读计划 → 创建检查清单 → 逐项验证 → 报告差距或完成
+❌ "测试通过了，阶段完成"
+```
+
+**Agent 委派：**
+```
+✅ Agent 报告成功 → 检查 VCS diff → 验证变更 → 报告实际状态
+❌ 信任 agent 报告
+```
+
+## 为什么这很重要
+
+来自 24 次失败记忆：
+- 你的人类搭档说"我不信你" - 信任被打破
+- 未定义的函数被发布 - 会崩溃
+- 遗漏的需求被发布 - 功能不完整
+- 在虚假完成上浪费时间 → 纠正 → 返工
+- 违反了："诚实是核心价值。如果你撒谎，你会被替换。"
+
+## 何时应用
+
+**始终在以下操作之前：**
+- 任何形式的成功/完成声明
+- 任何满意的表达
+- 任何关于工作状态的正面陈述
+- 提交、创建 PR、标记任务完成
+- 进入下一个任务
+- 委派给 agent
+
+**规则适用于：**
+- 精确措辞
+- 释义和同义词
+- 暗示成功
+- 任何暗示完成/正确的沟通
+
+## 底线
+
+**验证没有捷径。**
+
+运行命令。阅读输出。然后才能声称结果。
+
+这是不可协商的。

package/.opencode/skills/writing-plans/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: writing-plans
+description: "有规格或多步骤任务需求时使用，在接触代码之前"
+triggers:
+  - "制定计划"
+  - "实现计划"
+  - "写实现方案"
+  - "规划任务"
+---
+
+# 编写实现计划
+
+## 概述
+
+编写全面的实现计划，假设工程师对我们的代码库零上下文、品味堪忧。记录他们需要知道的一切：每个任务要改哪些文件、代码、测试、可能需要查阅的文档、如何验证。把整个计划拆成小任务。DRY。YAGNI。TDD。频繁提交。
+
+假设他们是熟练的开发者，但对我们的工具集和问题领域几乎一无所知。假设他们不太擅长测试设计。
+
+**开始时宣布：** "我正在使用 writing-plans skill 来创建实现计划。"
+
+**上下文：** 这应该在专用的 worktree 中运行（由 brainstorming skill 创建）。
+
+**计划保存到：** `.specops/plans/YYYY-MM-DD-<功能名>.md`
+
+## 小任务粒度
+
+**每一步是一个动作（2-5 分钟）：**
+- "编写失败的测试" - 一步
+- "运行测试确认它失败" - 一步
+- "编写最少代码让测试通过" - 一步
+- "运行测试确认它通过" - 一步
+- "提交" - 一步
+
+## 计划文档头部
+
+**每个计划必须以这个头部开始：**
+
+```markdown
+# [功能名称] 实现计划
+
+> **给 Claude 的指令：** 必须使用的子 SKILL：使用 specops:executing-plans 来逐任务实现此计划。
+
+**目标：** [一句话描述这个计划要构建什么]
+
+**架构：** [2-3 句话描述方案]
+
+**技术栈：** [关键技术/库]
+
+---
+```
+
+## 任务结构
+
+````markdown
+### 任务 N：[组件名称]
+
+**文件：**
+- 创建：`exact/path/to/file.py`
+- 修改：`exact/path/to/existing.py:123-145`
+- 测试：`tests/exact/path/to/test.py`
+
+**步骤 1：编写失败的测试**
+
+```python
+def test_specific_behavior():
+    # 测试特定行为
+    result = function(input)
+    assert result == expected
+```
+
+**步骤 2：运行测试确认它失败**
+
+运行：`pytest tests/path/test.py::test_name -v`
+预期：FAIL，报错 "function not defined"
+
+**步骤 3：编写最少实现**
+
+```python
+def function(input):
+    # 最少实现让测试通过
+    return expected
+```
+
+**步骤 4：运行测试确认它通过**
+
+运行：`pytest tests/path/test.py::test_name -v`
+预期：PASS
+
+**步骤 5：提交**
+
+```bash
+git add tests/path/test.py src/path/file.py
+git commit -m "feat: 添加特定功能"
+```
+````
+
+## 注意事项
+- 始终使用精确的文件路径
+- 计划中包含完整代码（不是"添加验证"这种模糊描述）
+- 精确的命令和预期输出
+- 用 @ 语法引用相关 skill
+- DRY、YAGNI、TDD、频繁提交
+
+## 执行交接
+
+保存计划后，提供执行选择：
+
+**"计划已完成并保存到 `.specops/plans/<文件名>.md`。两种执行方式：**
+
+**1. 子 Agent 驱动（当前会话）** - 每个任务分派一个新的子 Agent，任务间进行审查，快速迭代
+
+**2. 并行会话（单独开）** - 在新会话中使用 executing-plans，分批执行带检查点
+
+**选哪种？"**
+
+**如果选择子 Agent 驱动：**
+- **必须使用的子 SKILL：** 使用 specops:subagent-driven-development
+- 留在当前会话
+- 每个任务一个新子 Agent + 代码审查
+
+**如果选择并行会话：**
+- 引导用户在 worktree 中打开新会话
+- **必须使用的子 SKILL：** 新会话使用 specops:executing-plans