@shirlytaylor73/superharness 1.5.0

package/plugins/superharness/skills/trivial/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: trivial
+description: 当用户描述 typo 修复、单文件配置调整、改个常量、改个文案、小幅且明确的轻量改动时使用——只对 ≤ 3 文件 / ≤ 50 行 / 不引新依赖 / 不动公共 API 与 schema 的小修适用；超出任一边界必须立即转回 intake
+metadata:
+  type: workflow-state
+---
+
+# Trivial — 单点小改 + 自带验证
+
+## 概述
+
+你处在快速通道。这条路把 plan / verification / finishing 全跳过——你既是 implementer，也是 reviewer，**所有事都在这一个状态内完成**。
+
+**核心原则：** 改动必须真的轻量。任何"顺手再改一点"的冲动都意味着你不应该在 trivial 里。
+
+## 何时使用 / 不使用
+
+**适用**（**全部**满足才能留在 trivial）：
+
+- 改 typo / 错别字 / 注释笔误
+- 调整 1-3 个配置项（如 timeout、buffer 大小、feature flag 默认值）
+- 改个常量或字面量
+- 改文案 / log message / 错误信息
+- 单文件函数体内的小幅 bugfix（不动签名、不动调用方）
+
+**不适用**（出现任一条立即 transition 回 `intake`）：
+
+- 改动会跨 ≥ 4 个文件
+- 实质改动 > 50 行（不算空白行、纯重命名、纯格式化）
+- 需要新增依赖、新增配置文件、新增 npm/pip 包
+- 改动函数签名 / 导出接口 / 公共 API
+- 改动 schema：DB schema、API contract、消息格式、配置文件结构
+- 改动行为语义（哪怕只改一行——一行 `if` 反转都可能不是 trivial）
+- 你需要先去查代码、对比方案、想架构才能决定怎么改
+
+## 改动边界（硬约束）
+
+```
+≤ 3 个文件
+≤ 50 行实质改动（不算空白行 / 纯重命名 / 纯格式化）
+不引入新依赖
+不改公共 API / 导出接口 / 函数签名
+不改 schema（DB / API contract / 配置结构 / 消息格式）
+```
+
+**违反任一条 → 立即 transition_state 到 `intake`**，reason 写明"超出 trivial 边界：[具体哪条]"，让用户决定是否升级到 `brainstorming`。
+
+**不要试图把改动"切碎"绕过边界**——边界的精神是"心智负担可以一眼读完"，违反字面就是违反精神。
+
+## 自带验证（改完必须做）
+
+改完代码后，**在 transition 出去之前**必须完成以下验证，并把结果写进 transition 的 reason：
+
+1. **跑相关测试**：找到覆盖你改动的测试文件 / test 函数，运行它们。看到通过结果，不要"假设会过"。
+2. **跑 lint**：项目有 lint 命令就跑（npm run lint / ruff / eslint / 等等）。
+3. **跑类型检查**：项目有类型检查就跑（tsc --noEmit / mypy / 等等）。
+4. **没有自动化测试时**：至少手动验证 happy path——明确写出"我手动验证了 X 场景，输出 Y"。
+
+**验证不通过**：见下方"异常出口"。**不许**用"应该能过"、"看起来对了"、"改动很小不可能出错"这类话替代实际运行验证命令。
+
+## 异常出口
+
+| 情况 | 出口 |
+|---|---|
+| 测试失败 / lint 报错 / 类型错误 / 运行报错 | transition 到 `systematic_debugging` |
+| 发现真实改动范围超过任一边界 | transition 回 `intake`，reason 注明超边界细节 |
+| 改完发现需要顺手 refactor 才合理 | **不要 refactor**，transition 回 `intake` 让用户决定 |
+
+## 完成后
+
+完成 = 改动落地 + 自带验证全过。然后 transition_state 回 `intake`。
+
+**reason 必须包含两段**：
+
+1. **改了什么**：具体文件路径 + 函数名 / 行号 / 改动的本质（如 "src/utils/timeout.ts 把 DEFAULT_TIMEOUT 从 5000 改为 10000"）
+2. **验证结果**：实际运行了哪些命令 + 看到了什么输出（如 "npm test src/utils/timeout.test.ts 通过 12/12；npm run lint 0 errors"）
+
+reason 不写或敷衍 = 等同于在审计日志里说谎。
+
+## 反 anti-pattern（红线）
+
+以下任一条出现 → **停**，重新评估：
+
+- 在 trivial 里搞 refactor（**不要**——transition 回 intake）
+- "顺手优化"了一段无关代码（**回滚那段**，只保留任务本身的改动）
+- 跳过 self-verification 直接 transition（**回头跑验证**）
+- 改完之后想"我再多改一点点 X 就完美了"（**不要**——超出边界的征兆）
+- 用 "应该" / "大概" / "看起来对了" 替代实际验证命令（**跑命令看输出**）
+- 测试失败但跟自己说"这个 bug 跟我改的无关"（**transition 到 systematic_debugging**，不要绕过）
+
+## 防止合理化
+
+| 借口 | 现实 |
+|---|---|
+| "改动这么小不可能出错" | 小改动也会破测试，跑一遍 30 秒 |
+| "测试覆盖的不是我改的地方所以不用跑" | 行为可能传染到任何 caller，跑相关测试 |
+| "顺手把这段 if/else 改清楚一点" | 那是 refactor，不在 trivial 范围 |
+| "lint warning 不算 error" | 看项目设定，CI 报红就是 error |
+| "类型检查通过等于功能正确" | 错的——它只证明类型对 |
+| "范围只超了一点点" | 边界数字是硬的，超了就 transition |
+| "改完发现还得改另一个文件，但加上才 4 个" | 4 > 3，transition 回 intake 升级到 brainstorming |
+
+## 红线——停下来 transition 回 intake
+
+- 即将动第 4 个文件
+- 实质改动已经 > 50 行
+- 准备 npm install / pip install 任何东西
+- 准备改某个 export / public 函数签名
+- 准备改 schema / migration / API 契约
+- 准备做"顺手的 refactor"
+
+**以上任一条 = trivial 已经不适用。transition 回 intake，让用户决定是否走 brainstorming。**
+
+## 底线
+
+trivial 之所以快，是因为它**小到可以一眼审完**。一旦你需要"想一下"才能确定改对了——就不再 trivial。
+
+不要用 trivial 偷渡你本该走 brainstorming / planning 的工作。这条快速通道的存在前提是：使用者诚实地遵守边界。

package/plugins/superharness/skills/using-git-worktrees/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: using-git-worktrees
+description: 当需要开始与当前工作区隔离的功能开发或执行实现计划之前使用——创建具有智能目录选择和安全验证的隔离 git 工作树
+---
+
+# 使用 Git 工作树
+
+## 概述
+
+Git 工作树创建共享同一仓库的隔离工作区，允许同时在多个分支上工作而无需切换。
+
+**核心原则：** 系统化的目录选择 + 安全验证 = 可靠的隔离。
+
+**开始时宣布：** "我正在使用 using-git-worktrees 技能来建立一个隔离的工作区。"
+
+## 目录选择流程
+
+按以下优先顺序执行：
+
+### 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/superpowers/worktrees/<project-name>/（全局位置）
+
+你倾向哪个？
+```
+
+## 安全验证
+
+### 项目本地目录（.worktrees 或 worktrees）
+
+**创建工作树前必须验证目录已被忽略：**
+
+```bash
+# 检查目录是否被忽略（遵循本地、全局和系统 gitignore）
+git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+```
+
+**如果未被忽略：**
+
+根据 Jesse 的规则"立即修复坏掉的东西"：
+1. 在 .gitignore 中添加相应条目
+2. 提交更改
+3. 继续创建工作树
+
+**为什么这很关键：** 防止意外将工作树内容提交到仓库。
+
+### 全局目录（~/.config/superpowers/worktrees）
+
+无需 .gitignore 验证——完全在项目之外。
+
+## 创建步骤
+
+### 1. 检测项目名称
+
+```bash
+project=$(basename "$(git rev-parse --show-toplevel)")
+```
+
+### 2. 创建工作树
+
+```bash
+# 确定完整路径
+case $LOCATION in
+  .worktrees|worktrees)
+    path="$LOCATION/$BRANCH_NAME"
+    ;;
+  ~/.config/superpowers/worktrees/*)
+    path="~/.config/superpowers/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. 报告位置
+
+```
+工作树已就绪：<full-path>
+测试通过（<N> 个测试，0 个失败）
+准备实现 <feature-name>
+```
+
+## 快速参考
+
+| 情况 | 操作 |
+|------|------|
+| `.worktrees/` 存在 | 使用它（验证已忽略） |
+| `worktrees/` 存在 | 使用它（验证已忽略） |
+| 两者都存在 | 使用 `.worktrees/` |
+| 都不存在 | 检查 CLAUDE.md → 询问用户 |
+| 目录未被忽略 | 添加到 .gitignore + 提交 |
+| 基线测试失败 | 报告失败 + 询问 |
+| 无 package.json/Cargo.toml | 跳过依赖安装 |
+
+## 常见错误
+
+### 跳过忽略验证
+
+- **问题：** 工作树内容被跟踪，污染 git status
+- **修复：** 创建项目本地工作树前始终使用 `git check-ignore`
+
+### 假设目录位置
+
+- **问题：** 造成不一致，违反项目约定
+- **修复：** 遵循优先级：现有目录 > CLAUDE.md > 询问
+
+### 带着失败的测试继续
+
+- **问题：** 无法区分新 bug 和已有问题
+- **修复：** 报告失败，获得明确许可后再继续
+
+### 硬编码设置命令
+
+- **问题：** 在使用不同工具的项目上会出错
+- **修复：** 从项目文件自动检测（package.json 等）
+
+## 示例工作流
+
+```
+你：我正在使用 using-git-worktrees 技能来建立一个隔离的工作区。
+
+[检查 .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 > 询问
+- 对项目本地目录验证是否已忽略
+- 自动检测并运行项目设置
+- 验证测试基线干净
+
+## 集成
+
+**被以下技能调用：**
+- **brainstorming**（阶段 4）- 设计通过且需要实现时必需
+- **parallel-execution** - 执行任何任务前必需
+- **serial-execution** - 执行任何任务前必需
+- 任何需要隔离工作区的技能
+
+**配合使用：**
+- **finishing** - 工作完成后清理时必需

package/plugins/superharness/skills/verification/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: verification
+description: 在宣称工作完成、已修复或测试通过之前使用，在提交或创建 PR 之前——必须运行验证命令并确认输出后才能声称成功；始终用证据支撑断言
+---
+
+# 完成前验证
+
+## 概述
+
+在没有验证的情况下宣称工作完成，这不是高效，而是不诚实。
+
+**核心原则：** 始终用证据支撑结论。
+
+**对这条规则敷衍了事，就等于违背了它的精神。**
+
+## 铁律
+
+```
+没有新鲜的验证证据，不许宣称完成
+```
+
+如果你在这条消息中没有运行验证命令，就不能声称测试通过。
+
+## 门控函数
+
+```
+在宣称任何状态或表达满意之前：
+
+1. 确定：什么命令能证明这个结论？
+2. 运行：执行完整命令（重新运行，完整执行）
+3. 阅读：完整输出，检查退出码，统计失败数
+4. 验证：输出是否支持这个结论？
+   - 如果否：用证据说明实际状态
+   - 如果是：带证据陈述结论
+5. 只有这时：才能做出结论
+
+跳过任何一步 = 说谎，不是验证
+```
+
+## 常见失败模式
+
+| 结论 | 需要 | 不够格 |
+|------|------|--------|
+| 测试通过 | 测试命令输出：0 failures | 之前的运行结果、"应该会通过" |
+| Linter 无报错 | Linter 输出：0 errors | 部分检查、推断 |
+| 构建成功 | 构建命令：exit 0 | linter 通过、日志看起来没问题 |
+| Bug 已修复 | 测试原始症状：通过 | 代码改了，假设已修复 |
+| 回归测试有效 | 红-绿循环已验证 | 测试只通过了一次 |
+| 代理已完成 | VCS diff 显示变更 | 代理报告"成功" |
+| 需求已满足 | 逐项核对清单 | 测试通过 |
+
+## 红线——停下来
+
+- 使用"应该"、"大概"、"似乎"
+- 验证前就表达满意（"太好了！"、"完美！"、"搞定！"等）
+- 即将提交/推送/创建 PR 却没有验证
+- 信任代理的成功报告
+- 依赖部分验证
+- 想着"就这一次"
+- 累了想赶紧收工
+- **任何暗示成功但实际未运行验证的措辞**
+
+## 防止合理化
+
+| 借口 | 现实 |
+|------|------|
+| "应该能行了" | 运行验证命令 |
+| "我有信心" | 信心 ≠ 证据 |
+| "就这一次" | 没有例外 |
+| "Linter 通过了" | Linter ≠ 编译器 |
+| "代理说成功了" | 独立验证 |
+| "我累了" | 疲劳 ≠ 借口 |
+| "部分检查就够了" | 部分检查什么也证明不了 |
+| "换个说法这条规则就不适用了" | 精神大于字面 |
+
+## 关键模式
+
+**测试：**
+```
+✅ [运行测试命令] [看到：34/34 pass] "全部测试通过"
+❌ "应该能通过了" / "看起来对了"
+```
+
+**回归测试（TDD 红-绿）：**
+```
+✅ 编写 → 运行（通过）→ 回退修复 → 运行（必须失败）→ 恢复 → 运行（通过）
+❌ "我写了回归测试"（没有经过红-绿验证）
+```
+
+**构建：**
+```
+✅ [运行构建] [看到：exit 0] "构建通过"
+❌ "Linter 通过了"（linter 不检查编译）
+```
+
+**需求：**
+```
+✅ 重读计划 → 创建核对清单 → 逐项验证 → 报告缺口或完成
+❌ "测试通过了，阶段完成"
+```
+
+**代理委派：**
+```
+✅ 代理报告成功 → 检查 VCS diff → 验证变更 → 报告实际状态
+❌ 信任代理报告
+```
+
+## 为什么这很重要
+
+来自 24 次失败记录：
+- 搭档说"我不信你"——信任被破坏
+- 未定义的函数被交付——会直接崩溃
+- 遗漏需求被交付——功能不完整
+- 虚假完成浪费的时间 → 返工 → 重做
+- 违反原则："诚实是核心价值。如果你说谎，就会被替换。"
+
+## 何时使用
+
+**以下情况之前必须使用：**
+- 任何形式的成功/完成声明
+- 任何满意的表达
+- 任何关于工作状态的正面陈述
+- 提交、创建 PR、标记任务完成
+- 进入下一个任务
+- 委派给代理
+
+**本规则适用于：**
+- 准确措辞
+- 同义词和换一种说法
+- 暗示成功
+- 任何传达完成/正确性的沟通
+
+## 底线
+
+**验证没有捷径。**
+
+运行命令。阅读输出。然后才能宣称结果。
+
+这没有商量余地。

package/plugins/superharness/skills/workflow-runner/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: workflow-runner
+description: "在 Claude Code 和 Codex 中直接运行 agency-orchestrator YAML 工作流——无需 API key，使用当前会话的 LLM 作为执行引擎。当用户提供 .yaml 工作流文件或要求多角色协作完成任务时触发。"
+---
+
+# 工作流执行器：在 AI 工具内运行多角色编排
+
+直接在当前会话中执行 agency-orchestrator 的 YAML 工作流，无需配置 API key。当前 LLM 就是执行引擎——依次扮演每个角色完成任务。
+
+## 适用场景
+
+- 用户提供了一个 `.yaml` 工作流文件（如 `运行 workflows/story-creation.yaml`）
+- 用户要求多个角色协作完成任务（如"用产品经理和架构师一起评审这个 PRD"）
+- 用户安装了 `agency-agents-zh` 并希望直接在 AI 工具内编排多角色
+
+## 执行流程（5 步）
+
+按以下顺序执行，不要跳步：
+
+### 第 1 步：解析工作流
+
+用 Read 工具读取用户指定的 YAML 文件，提取以下字段：
+
+```yaml
+name: "工作流名称"
+agents_dir: "agency-agents-zh"    # 角色定义目录
+inputs:                            # 输入变量
+  - name: xxx
+    required: true/false
+    default: "默认值"
+steps:                             # 执行步骤
+  - id: step_id
+    role: "category/agent-name"    # 角色路径
+    task: "任务描述 {{变量}}"       # 支持模板变量
+    output: variable_name          # 输出变量名
+    depends_on: [other_step_id]    # 依赖关系
+```
+
+**忽略 `llm`、`concurrency`、`timeout`、`retry` 配置**——Skill 模式使用当前会话的 LLM，这些字段仅用于 CLI 模式。
+
+**定位角色目录**：用 Bash `test -d` 按以下顺序检查，用第一个存在的：
+1. 当前工作目录下的 `{agents_dir}/`（如 `./agency-agents-zh/`）
+2. `../{agents_dir}/`（上级目录）
+3. 相对于 YAML 文件所在目录的 `{agents_dir}/`
+4. `node_modules/agency-agents-zh/`
+
+如果全部找不到，**停止执行**并提示用户：
+```
+找不到角色目录。请先安装：
+  git clone --depth 1 https://github.com/jnMetaCode/agency-agents-zh.git
+  或：npm install agency-agents-zh
+```
+
+### 第 2 步：收集输入
+
+- 对每个 `required: true` 的输入，检查用户消息中是否已提供值
+- 未提供的必填输入：**立即向用户询问**，不要猜测或用空值
+- 有 `default` 的可选输入：使用默认值
+- 无默认值的可选输入：设为空字符串
+
+### 第 3 步：构建执行顺序
+
+根据 `depends_on` 进行拓扑排序，将步骤分成多个层级：
+
+- **无 depends_on 的步骤** → 第 1 层
+- **depends_on 全部在第 N 层或之前的步骤** → 第 N+1 层
+- **同一层内的步骤**互不依赖，可并行
+
+在回复中展示执行计划：
+```
+执行计划（共 N 步）：
+  第 1 层: [step_id] — 角色名
+  第 2 层: [step_a, step_b] — 并行
+  第 3 层: [step_id] — 角色名
+```
+
+### 第 4 步：逐层执行
+
+对每一层：
+
+#### 4a. 预读角色文件
+
+用 Read 工具读取该层所有步骤的角色 `.md` 文件：`{角色目录}/{role}.md`
+
+从文件中提取：
+- **角色名**：frontmatter 中的 `name` 字段
+- **角色 system prompt**：第二个 `---` 之后的全部 markdown 内容
+
+#### 4b. 渲染 task 模板
+
+将 task 中的 `{{变量名}}` 替换为：
+- 来自 inputs 的用户输入值
+- 来自前序步骤 output 的结果文本
+
+#### 4c. 执行
+
+**单步骤层**：直接在主会话中扮演该角色执行。格式：
+
+```
+### Step N/Total: step_id（角色名）
+
+[以该角色身份完成 task，使用角色的专业知识和沟通风格]
+```
+
+**多步骤层（并行）**：使用 Agent 工具为每个步骤启动子代理。每个子代理的 prompt 必须包含：
+- 角色文件的**完整文本内容**（不是路径——子代理可能无法读文件）
+- 渲染后的 task 文本
+- 指令："以上是你的角色定义，请以该角色身份完成以下任务，直接输出结果"
+
+#### 4d. 保存输出到上下文
+
+如果 step 有 `output` 字段，将该步骤的输出文本存入变量上下文，供后续步骤的 `{{变量}}` 使用。
+
+### 第 5 步：保存结果并展示
+
+用 Write 工具将结果保存到文件：
+
+```
+.ao-output/{工作流名称}-{YYYY-MM-DD}/
+├── steps/
+│   ├── 1-{step_id}.md       # 每步的输出
+│   ├── 2-{step_id}.md
+│   └── ...
+├── summary.md                # 最后一步的完整输出（最终成果）
+└── metadata.json             # 基本元数据
+```
+
+metadata.json 格式：
+```json
+{
+  "name": "工作流名称",
+  "date": "2026-03-22",
+  "success": true,
+  "steps": [
+    {"id": "step_id", "role": "category/agent", "status": "completed"},
+    ...
+  ]
+}
+```
+
+执行完毕后，向用户展示：
+1. 最终成果（summary.md 的内容）
+2. 文件保存位置
+3. 执行了几个步骤
+
+## 重要规则
+
+<HARD-GATE>
+- 每个步骤都必须真正扮演对应角色，使用该角色的专业知识和沟通风格，不能泛泛回答
+- 角色切换必须明确——每步开始时标注角色名
+- 不要跳过步骤或合并步骤，严格按 DAG 层级顺序执行
+- 如果角色文件找不到，告知用户并建议安装 agency-agents-zh
+- 不要在没有读取角色 .md 文件的情况下执行步骤——必须先 Read 再执行
+</HARD-GATE>
+
+## 没有 YAML 文件时的快捷模式
+
+如果用户没有指定 YAML 文件，但描述了需要多角色协作的任务：
+
+1. 根据用户描述，**自动生成** YAML 工作流定义
+2. 展示给用户确认
+3. 确认后按上述流程执行
+
+示例：
+- 用户说"帮我用叙事学家和心理学家写个故事" → 生成 story-creation 类似的工作流
+- 用户说"让产品经理和架构师评审这个 PRD" → 生成 product-review 类似的工作流
+
+## 故障处理
+
+- **角色文件不存在**：提示用户运行 `ao init` 或 `npm install agency-agents-zh`
+- **模板变量未定义**：检查上下文，如果是必填输入则向用户询问
+- **步骤执行失败**：标记该步骤为失败，跳过所有依赖它的下游步骤，继续执行其他独立步骤