harveyz-skill 0.1.0

package/skills/superpowers-fork/using-git-worktrees/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: using-git-worktrees
+description: "当需要创建隔离工作区（新分支）进行特性开发时使用。在执行实施计划或开始任何需要与当前工作隔离的任务前，必须先创建 worktree、运行项目设置、验证干净的测试基线。适用于：开始新功能开发、修复 bug、需要隔离环境的任何代码工作。"
+user_invocable: true
+version: "1.0.0"
+---
+
+# Using Git Worktrees - 隔离工作区
+
+## 概述
+
+Git worktree 创建共享同一仓库的隔离工作空间，允许同时在多个分支上工作而无需切换。
+
+**核心原则：** 系统化的目录选择 + 安全验证 = 可靠的隔离。
+
+**开始时宣布：** "正在使用 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 偏好：
+
+```
+未找到 worktree 目录。应该在哪里创建？
+
+1. .worktrees/ (项目本地，隐藏)
+2. ~/worktrees/<项目名>/ (全局位置)
+
+选择哪个？
+```
+
+## 安全验证
+
+### 本地目录（.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. 继续创建 worktree
+
+### 全局目录（~/.config/openclaw/worktrees/）
+
+无需 .gitignore 验证 — 完全在项目外。
+
+## 创建步骤
+
+### 1. 检测项目名称
+
+```bash
+project=$(basename "$(git rev-parse --show-toplevel)")
+```
+
+### 2. 创建 Worktree
+
+```bash
+# 确定完整路径
+case $LOCATION in
+  .worktrees|worktrees)
+    path="$LOCATION/$BRANCH_NAME"
+    ;;
+  ~/.config/openclaw/worktrees/*)
+    path="$HOME/.config/openclaw/worktrees/$project/$BRANCH_NAME"
+    ;;
+esac
+
+# 创建 worktree（带新分支）
+git worktree add "$path" -b "$BRANCH_NAME"
+cd "$path"
+```
+
+### 3. 运行项目设置
+
+自动检测并运行适当的设置：
+
+```bash
+# Node.js
+if [ -f package.json ]; then npm install; fi
+
+# Python
+if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+if [ -f pyproject.toml ]; then poetry install; fi
+
+# Rust
+if [ -f Cargo.toml ]; then cargo build; fi
+
+# Go
+if [ -f go.mod ]; then go mod download; fi
+```
+
+### 4. 验证干净基线
+
+运行测试确保 worktree 起始干净：
+
+```bash
+# 示例（使用项目适当的命令）
+npm test
+cargo test
+pytest
+go test ./...
+```
+
+**如果测试失败：** 报告失败，询问是否继续或调查。
+
+**如果测试通过：** 报告就绪。
+
+### 5. 报告位置
+
+```
+Worktree 就绪于 <full-path>
+测试通过 (<N> 测试，0 失败)
+准备好实现 <feature-name>
+```
+
+## 快速参考
+
+| 情况 | 操作 |
+|------|------|
+| `.worktrees/` 存在 | 使用它（验证被忽略） |
+| `worktrees/` 存在 | 使用它（验证被忽略） |
+| 两者都存在 | 使用 `.worktrees/` |
+| 都不存在 | 检查 CLAUDE.md → 询问用户 |
+| 目录未忽略 | 添加到 .gitignore + 提交 |
+| 基线测试失败 | 报告失败 + 询问 |
+| 无 package.json 等 | 跳过依赖安装 |
+
+## 常见错误
+
+### 跳过忽略验证
+
+- **问题：** Worktree 内容被跟踪，污染 git status
+- **修复：** 创建本地 worktree 前始终使用 `git check-ignore`
+
+### 假设目录位置
+
+- **问题：** 创建不一致，违反项目约定
+- **修复：** 遵循优先级：现有 > CLAUDE.md > 询问
+
+### 测试失败继续
+
+- **问题：** 无法区分新 bug 和已存在问题
+- **修复：** 报告失败，获得明确许可后再继续
+
+### 硬编码设置命令
+
+- **问题：** 在使用不同工具的项目上失败
+- **修复：** 从项目文件自动检测（package.json 等）
+
+## 与其他技能配合
+
+**被调用方：**
+- **brainstorming**（第4阶段）— 设计批准后实施前必需
+- **executing-plans** — 执行任何任务前必需
+- 任何需要隔离工作区的技能
+
+**配合技能：**
+- **finishing-a-development-branch** — 工作完成后清理
+- **writing-plans** — 创建实施计划
+- **brainstorming** — 设计阶段
+
+## OpenClaw 环境适配
+
+在 OpenClaw 环境中：
+- 工作区路径：`~/.openclaw/agents/coding-master/workspace/`
+- 计划保存到：`docs/superpowers/plans/`
+- 规格保存到：`docs/superpowers/specs/`
+- Worktree 创建后，在新目录中继续执行 writing-plans 和 executing-plans

package/skills/superpowers-fork/writing-plans/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: writing-plans
+description: "当有规格说明或需求文档后，将设计拆解为可执行的小任务时使用。每个任务应该是 2-5 分钟可完成的，包含精确文件路径、完整代码和验证步骤。此技能与 brainstorming（生成规格）和 executing-plans（执行计划）配合使用，构成完整的工作流。"
+user_invocable: true
+version: "1.0.0"
+---
+
+# Writing Plans - 实施计划编写
+
+## 概述
+
+将设计文档拆解为详细、可执行的实施计划。假设执行者对代码库零上下文但技能熟练。
+
+**开始时宣布：** "正在使用 writing-plans 技能创建实施计划。"
+
+## 计划文件位置
+
+保存到：`docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
+
+## 计划结构
+
+### 文件头部（必须）
+
+```markdown
+# [功能名称] 实施计划
+
+**目标：** [一句话描述构建内容]
+
+**架构：** [2-3 句话描述方法]
+
+**技术栈：** [关键技术和库]
+
+---
+```
+
+### 任务结构
+
+```
+### Task N: [组件名称]
+
+**文件：**
+- 创建: `exact/path/to/file.py`
+- 修改: `exact/path/to/existing.py:123-145`
+- 测试: `tests/exact/path/to/test.py`
+
+- [ ] **Step 1: 编写失败的测试**
+
+```python
+def test_specific_behavior():
+    result = function(input)
+    assert result == expected
+```
+
+- [ ] **Step 2: 运行测试确认失败**
+
+运行: `pytest tests/path/test.py::test_name -v`
+预期: FAIL
+
+- [ ] **Step 3: 编写最小实现**
+
+```python
+def function(input):
+    return expected
+```
+
+- [ ] **Step 4: 运行测试确认通过**
+
+运行: `pytest tests/path/test.py::test_name -v`
+预期: PASS
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add tests/path/test.py src/path/file.py
+git commit -m "feat: add specific feature"
+```
+```
+
+## 任务粒度
+
+**每个步骤 2-5 分钟完成：**
+- "编写失败的测试" — 一步
+- "运行测试确认失败" — 一步
+- "编写最小实现" — 一步
+- "运行测试确认通过" — 一步
+- "提交" — 一步
+
+## 文件结构规划
+
+在定义任务前，先规划需要创建或修改的文件：
+- 每个文件职责清晰
+- 文件边界清晰
+- 文件应一起修改的放一起
+- 遵循现有代码库模式
+
+## 禁止占位符
+
+以下都是计划失败，禁止写入：
+- "TBD"、"TODO"、"后续实现"
+- "添加适当的错误处理"
+- "参考 Task N"（必须重复代码）
+- 描述做什么但不展示如何做
+- 引用未在任何任务中定义的类型、函数或方法
+
+## 自检清单
+
+完成计划后，用新眼光检查：
+
+### 1. 规格覆盖
+浏览规格的每个部分，能否指向实现它的任务？列出任何空白。
+
+### 2. 占位符扫描
+搜索：TBD、TODO、"后续"、"类似 Task N" 等模式
+
+### 3. 类型一致性
+在后续任务中使用的类型、方法签名、属性名是否与前面定义一致？
+
+## 执行移交
+
+保存计划后，提供执行选项：
+
+**"计划已完成并保存到 `docs/superpowers/plans/<filename>.md`。两个执行选项：**
+
+**1. 子 Agent 驱动（推荐）** — 每个任务派发一个新的 subagent，任务间 review，快速迭代
+
+**2. 内联执行** — 在当前 session 使用 executing-plans 执行，批量执行带检查点
+
+**选择哪个？"**
+
+## 典型计划示例
+
+```markdown
+# 用户认证功能 实施计划
+
+**目标：** 添加邮箱+密码用户认证
+
+**架构：** 使用 JWT，无状态认证，密码 bcrypt 哈希
+
+**技术栈：** Python, Flask, PyJWT, bcrypt
+
+---
+
+### Task 1: 用户注册 API
+
+**文件：**
+- 创建: `src/api/users.py`
+- 修改: `src/models/user.py`
+- 测试: `tests/api/test_users.py`
+
+- [ ] **Step 1: 编写注册失败测试**
+
+```python
+def test_register_creates_user():
+    response = client.post('/api/register', json={
+        'email': 'test@example.com',
+        'password': 'secure123'
+    })
+    assert response.status_code == 201
+```
+
+- [ ] **Step 2: 运行测试**
+
+...
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/api/users.py src/models/user.py tests/api/test_users.py
+git commit -m "feat: add user registration endpoint"
+```
+```
+
+## 与其他技能配合
+
+- **brainstorming** — 生成规格文档
+- **executing-plans** — 执行计划
+- **using-git-worktrees** — 创建隔离工作区
+- **systematic-debugging** — 调试问题
+
+## 常见错误
+
+| 错误 | 正确做法 |
+|------|----------|
+| 任务太大 | 拆分为 2-5 分钟的步骤 |
+| 缺少测试代码 | 每个任务都要有完整测试 |
+| "参考其他地方" | 重复必要的代码 |
+| 未验证一致性 | 自检清单第三项 |

package/skills/task/pm-task-dispatch/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: pm-task-dispatch
+description: PM 任务派发技能。当需要创建新任务并派发给其他 Agent 时触发。流程：理解任务 → 需求澄清 → 分析细化 → 创建任务文档 → sessions_send 派发 → 追踪反馈。触发场景包括：（1）Harvey 提出新任务需求，（2）要求向特定 Agent 分派任务，（3）询问任务如何派发。
+---
+
+# PM Task Dispatch
+
+PM 任务派发的标准流程。
+
+## 工作流
+
+```
+1. 理解任务 → 2. 需求澄清 → 3. 分析细化 → 4. 创建任务文档 → 5. 派发任务
+```
+
+---
+
+## Step 1：理解任务
+
+接收 Harvey 的任务描述，明确：
+- **任务目标**：要完成什么？
+- **约束条件**：有哪些限制（预算、技术栈、时间等）？
+- **期望输出**：结果以什么形式交付？
+
+---
+
+## Step 2：需求澄清
+
+**判断标准——是否需要 brainstorming：**
+
+```
+Harvey 给了模糊指令？
+  ├── 是 → 必须用 brainstorming skill 澄清
+  └── 否，但缺少以下任一信息？
+        ├── 任务范围和边界
+        ├── 优先级（priority）
+        ├── 资源限制（GPU、API key、预算）
+        └── 执行 Agent（assignee）
+            └── 是 → 向 Harvey 确认后再继续
+```
+
+**何时可以跳过 brainstorming：**
+- Harvey 指令明确包含"做 X，用 Y agent，约束 Z"
+- 任务来自已确认的 roadmap 或 project plan
+- 重复性任务格式固定（如 daily article fetch）
+
+---
+
+## Step 3：分析细化
+
+**与 Step 2 的边界区分：**
+- Step 2 = 向 Harvey 澄清意图（提问 → 得到确认答案）
+- Step 3 = 分析任务本身（不向 Harvey 提问，基于已有信息决策）
+
+**Step 3 内容：**
+
+1. **确定项目**：确认任务属于哪个项目（已有项目填项目名，新项目先命名）
+2. **拆分任务**：将任务拆为具体的 subtask
+3. **匹配 Agent**：根据任务类型匹配执行 Agent（见 `references/agent-mapping.md`）
+4. **确认验收标准**：如何确认任务完成？
+
+---
+
+## Step 4：创建任务文档
+
+详见 `references/task-template.md`
+
+**路径规则：**
+- Task 文件夹：`~/Projects/project-management/tasks/<id>/`
+- Task 文件：`~/Projects/project-management/tasks/<id>/task.md`
+- Issue 文件：`projects/{project}/issues/{open|closed}/<id>-<slug>.md`
+
+---
+
+## Step 5：派发任务
+
+**优化原则：** sessions_send 消息只包含简洁指令，任务详情由目标 Agent 自行读取 Markdown 文件。
+
+```javascript
+sessions_send({
+  sessionKey: "agent:{target-agent}:discord:channel:{channel-id}",
+  message: "📋 新任务派发\n\n" +
+    "**任务编号：** {id}\n" +
+    "**任务文件夹：** tasks/{id}/\n\n" +
+    "请读取 tasks/{id}/task.md，根据文件内容执行任务。\n" +
+    "完成后使用 task-close skill 进行收尾。",
+  timeoutSeconds: 0    // 必须为 0
+})
+```
+
+**⚠️ 重要：timeoutSeconds 必须为 0（fire-and-forget）**
+
+**任务文件结构（Agent 读取后执行）：**
+- `id` / `project` / `assignee` / `assigner` / `priority` / `status` → frontmatter 元数据
+- `主要目标` → 核心目标（必读）
+- `关键约束` → 约束条件（必读）
+- `工作流` → 分步指引（可选）
+- `使用工具` → 可用工具列表（可选）
+- `评估标准` → 验收标准（可选）
+- `资料管理` → 相关资料（可选）
+
+---
+
+## 错误处理
+
+### sessions_send 失败
+
+```
+sessions_send 返回 error？
+  ├── 网络问题 → 重试 1 次，间隔 10s
+  ├── session 不存在 → 检查 agent-mapping，确认 channel-id 正确
+  └── 其他 → 立即向 Harvey 汇报
+```
+
+### Agent 无响应
+
+```
+派发后超过预期时间无反馈？
+  ├── 检查 sessions_history 确认任务状态
+  ├── 若 stopReason = "lane wait exceeded" → 目标队列堵塞，向 Harvey 汇报
+  └── 若任务卡住超过 30 分钟 → 向 Harvey 汇报阻塞情况
+```
+
+### 重复派发
+
+```
+收到重复任务指令？
+  ├── 检查 tasks/ 目录是否已有相同 id 的任务文件夹
+  ├── 已有且 status ≠ done → 跳过派发，告知 Harvey
+  └── 已有但 Harvey 要求重新执行 → 更新任务文件后重新派发
+```
+
+---
+
+## 负面示例
+
+> **模糊指令 → 直接派发 → 任务失败**
+
+❌ 错误做法：
+```
+Harvey："研究一下 AI 模型"
+→ 直接派给 research-scientist
+→ Agent 问："研究什么？哪方面？什么约束？"
+→ 任务卡住
+```
+
+✅ 正确做法：
+```
+Harvey："研究一下 AI 模型"
+→ Step 2 触发：用 brainstorming 向 Harvey 确认
+   "研究 AI 模型——请问：(1) 具体哪类模型？(2) 研究目的是什么（选型/学习/实现）？(3) 有预算或技术栈限制吗？"
+→ Harvey 回复："研究本地 STT 模型，用于 Discord 语音转命令，成本敏感"
+→ Step 3 分析：任务明确，assignee = research-scientist
+→ Step 4 创建任务文档
+→ Step 5 派发
+```
+
+---
+
+## Reference 文件索引
+
+| 文件 | 内容 |
+|------|------|
+| `references/task-template.md` | Task 工单格式规范（frontmatter / 正文结构 / 示例） |
+| `references/agent-mapping.md` | Agent 通道映射（openclaw/<agent> / channel-id / 职责） |

package/skills/task/pm-task-dispatch/references/agent-mapping.md

@@ -0,0 +1,59 @@
+# Agent 通道映射
+
+## 当前已登记 Agent
+
+| Agent | openclaw/<agent> | Discord 频道 | Channel ID |
+|-------|----------------|-------------|-----------|
+| research-scientist | `openclaw/research-scientist` | #research-scientist | `1489128984246751242` |
+| coding-master | `openclaw/coding-master` | #coding-master | `1484628751005515886` |
+| writing-assistant | `openclaw/writing-assistant` | #writing-assistant | `1482389159636107474` |
+| general-affairs | `openclaw/general-affairs` | #general-affair | `1481354036580978688` |
+
+---
+
+## Agent 职责速查
+
+| Agent | 典型任务类型 |
+|-------|-------------|
+| **research-scientist** | 技术调研、方案研究、竞品分析、架构设计 |
+| **coding-master** | 代码开发、功能实现、PR 审查、Git 操作 |
+| **writing-assistant** | 文章抓取、翻译、内容整理、文档撰写 |
+| **general-affairs** | 日常事务、提醒设置、信息查询、配额监控 |
+
+---
+
+## 通知频道
+
+- **Channel ID：** `1484647806127050753`（#notification）
+- **用途：** Agent 完成任务后发送 `task_complete` 通知
+
+---
+
+## sessions_send 标准格式
+
+```javascript
+sessions_send({
+  sessionKey: "agent:{target-agent}:discord:channel:{channel-id}",
+  message: "Task #{id} 开始执行：{标题}\n\n...",
+  timeoutSeconds: 0    // 必须为 0
+})
+```
+
+### 常见错误
+
+| 错误 | 后果 |
+|------|------|
+| `timeoutSeconds` 非 0 | PM session 等待目标响应时卡住 |
+| 发到错误 channel | 目标 Agent 收不到 |
+| 通知发到 #product-manager | 回不到原 session |
+
+---
+
+## 任务派发后追踪
+
+1. **通知查询**：去 #notification（1484647806127050753）查 `task_complete`
+2. **兜底查询**：`sessions_history({ sessionKey: "agent:{target}:...", limit: 3 })`
+3. **状态判断**：
+   - `stopReason: stop` = 完成
+   - `toolUse` = 进行中
+   - `lane wait exceeded` = 目标队列堵塞