@adamancyzhang/claude-orchestrator 0.3.0 → 0.3.1

package/dist/skills/claude-orchestrator/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: claude-orchestrator
+description: Multi-agent orchestration CLI backed by ZooKeeper for service discovery. Register instances, distribute tasks, send messages, and share context across Claude Code instances. Use when the user wants to register, join a team, claim tasks, send messages, check status, or any orchestrator operation.
+---
+
+# Claude Orchestrator
+
+A CLI that provides multi-agent orchestration directly on top of ZooKeeper. Every Claude Code instance becomes a discoverable agent — register, claim tasks, communicate, and share context without a middleman server.
+
+## Architecture
+
+```
+Claude Code  ──CLI──>  ZooKeeper
+(instance A)          (service discovery, task queue, messages, context)
+
+Claude Code  ──CLI──>  ZooKeeper
+(instance B)
+```
+
+Every CLI command talks directly to ZooKeeper. Instance discovery is via ephemeral znodes. Tasks use sequential znodes for FIFO ordering. Messages use watch-based push.
+
+## Setup
+
+```bash
+pip install -e .
+docker-compose up -d   # start ZooKeeper
+```
+
+Verify:
+
+```bash
+claude-orchestrator status
+# {"status": "healthy", "zookeeper": "connected", "instances_online": 0}
+```
+
+## Global Options
+
+| Option | Env var | Default | Description |
+|--------|---------|---------|-------------|
+| `--zk-hosts` | `ZK_HOSTS` | `127.0.0.1:2181` | ZooKeeper connection string |
+| `--instance-id` | — | auto (from config) | Override stored instance ID |
+
+## Commands
+
+### Registration
+
+**Register** this instance:
+
+```bash
+claude-orchestrator register --name Jerry-Dev --role developer
+# {"id": "a1b2c3d4...", "name": "Jerry-Dev", "role": "developer", "status": "idle", ...}
+```
+
+The returned `id` is saved to `~/.claude-orchestrator/config.json`. Pass `--instance-id` on re-registration to reuse the same identity.
+
+**Heartbeat** — keep registration alive, optionally declare current task:
+
+```bash
+claude-orchestrator heartbeat
+claude-orchestrator heartbeat --current-task "fix-login-bug"
+```
+
+ZK session timeout is 30s. Call heartbeat regularly (every 30-60s) while working.
+
+**List instances:**
+
+```bash
+claude-orchestrator list-instances
+# [{"id": "...", "name": "Jerry-Dev", "role": "developer", "status": "busy", ...}, ...]
+```
+
+### Tasks
+
+**Push a task** to the queue:
+
+```bash
+claude-orchestrator push-task --title "Fix login bug" --description "..." --priority 0
+claude-orchestrator push-task --title "Review PR #42" --assignee <instance-id>
+```
+
+Priority: `0` = HIGH, `1` = MEDIUM (default), `2` = LOW.
+
+**Claim a task** — FIFO, higher priority first, assigned-to-you tasks jump the queue:
+
+```bash
+claude-orchestrator claim-task
+# {"id": "task-0000000001", "title": "Fix login bug", ...}   ← claimed
+# {"status": "no_tasks", "message": "No pending tasks available."}  ← empty queue
+```
+
+**Complete a task:**
+
+```bash
+claude-orchestrator complete-task --task-id task-0000000001 --result "Fixed auth middleware, added tests"
+```
+
+**List tasks:**
+
+```bash
+claude-orchestrator list-tasks
+claude-orchestrator list-tasks --status pending
+claude-orchestrator list-tasks --status claimed
+claude-orchestrator list-tasks --status completed
+```
+
+### Messages
+
+**Send a direct message:**
+
+```bash
+claude-orchestrator send-message --to <instance-id> --content "Can you review my PR?"
+```
+
+**Broadcast to all:**
+
+```bash
+claude-orchestrator send-message --broadcast --content "CI is down, don't push"
+```
+
+**Poll messages:**
+
+```bash
+claude-orchestrator poll-messages
+# [{"id": "msg-...", "type": "direct", "from_name": "Lucy-Test", "content": "...", "read": true}]
+```
+
+**Request help** (broadcasts to all):
+
+```bash
+claude-orchestrator request-help --question "How do I test the auth flow?" --context "stack trace..."
+```
+
+### Shared Context
+
+**Set:**
+
+```bash
+claude-orchestrator set-context --key ci_status --value "failing: auth tests"
+```
+
+**Get:**
+
+```bash
+claude-orchestrator get-context --key ci_status
+# {"key": "ci_status", "value": "failing: auth tests"}
+```
+
+### Status
+
+```bash
+claude-orchestrator status
+# {"status": "healthy", "zookeeper": "connected", "instances_online": 3}
+```
+
+## Workflow
+
+A typical agent session:
+
+```bash
+# 1. Join the team
+claude-orchestrator register --name Jerry-Dev --role developer
+
+# 2. Check who's online
+claude-orchestrator list-instances
+
+# 3. Work loop
+while true; do
+  claude-orchestrator poll-messages     # check for messages
+  task=$(claude-orchestrator claim-task)  # grab work
+  if [ "$task" = "no_tasks" ]; then break; fi
+  # ... execute the task ...
+  claude-orchestrator complete-task --task-id <id> --result "Done: ..."
+done
+```
+
+## Error recovery
+
+- **ZooKeeper not connected**: check `docker-compose ps`, retry. ZK client auto-reconnects.
+- **"No instance_id found"**: register first, or pass `--instance-id`
+- **Registration expired**: ephemeral nodes cleaned up on disconnect. Re-register with same `--instance-id` to restore identity.

package/dist/skills/task-acceptance/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: task-acceptance
+description: PM task-level acceptance verification with full traceability. Use when the PM needs to verify completed work from team members, run acceptance on daily work assignments, or confirm deliverables before signing off — every acceptance decision must be traceable to specific criteria and verified deliverables. Triggers on keywords like "确认并验收", "验收一下", "verify and accept", "检查完成情况", "task acceptance", "任务验收". Covers per-task-assignment verification workflow with cross-worktree git checks, commit signature validation, and report data cross-validation.
+---
+
+# Task Acceptance
+
+> 验收不是读报告，是逐项验证代码、测试、git commit 的真实存在。本技能与 [[task-traceability]] 协作，确保每次验收不走形式、不漏步骤、可追溯——每个 Go/No-Go 决策都可追溯到具体的验收标准和经过验证的交付物。
+
+---
+
+## 何时触发
+
+- 用户说"确认并验收"、"验收一下"、"检查一下完成情况"
+- 团队成员报告任务完成，PM 需要核实
+- daily work assignment 文档中所有任务标记为已完成
+- PM 准备签阶段验收报告
+
+---
+
+## 验收八步法
+
+按顺序执行，每一步通过才进入下一步。任一步不通过 → 记录问题，最终 No-Go。
+
+### 1. 读取工作分配文档
+
+找到对应的任务分配文档（如 `docs/pm/YYYY-MM-DD/daily-work-assignment.md`），提取：
+- 每个成员的任务清单和验收标准
+- 预期的产出物路径
+- 依赖链（谁依赖谁先完成）
+
+### 2. 检查产出物是否存在
+
+对每个成员，检查指定的产出目录下是否有对应的产出文件。
+
+```bash
+ls -la docs/{member}/YYYY-MM-DD/
+```
+
+如果报告引用了产出物但文件不存在 → P1 问题。
+
+### 3. 验证代码变更真实存在
+
+**不要轻信报告中的描述。** 对每项声称的代码修改，直接 grep 验证：
+
+```bash
+# 示例：验证某组件是否真的引入了某个依赖
+grep -n "<key-symbol>" <source-file-path>
+
+# 示例：验证是否替换了特定常量
+grep -n "<new-value>" <spec-file-path>
+
+# 验证旧引用已清除
+grep "<old-value>" <spec-file-path>  # 应无结果
+```
+
+如果代码变更不存在但报告声称已完成 → P0 问题（虚假报告）。
+
+### 4. 运行测试验证数字
+
+报告中的测试数字必须可复现：
+
+```bash
+# 运行单元测试
+<project-test-command> 2>&1 | tail -20
+
+# 统计测试文件中的实际测试数量
+for f in <test-glob-pattern>; do
+  count=$(grep -c "test(" "$f")
+  echo "$f: $count tests"
+done
+```
+
+将实际测试数与报告中的数字对比。不一致 → P2 问题（报告错误）。
+
+### 5. 验证 git commit 真实存在
+
+**关键**：如项目使用多个独立 git worktree 或子模块，必须在对应目录下检查 commit。
+
+```bash
+# 检查各仓库的 git log
+cd <subdir> && git log --oneline -10
+```
+
+对报告中引用的每个 commit hash：
+
+```bash
+cd <subdir> && git log --all --oneline | grep "^<commit-hash>"
+```
+
+如果 commit hash 不存在 → P0 问题（commits 未生成或引用了虚构 hash）。
+
+同时检查**工作区是否干净**（`git status`）—— 如果有未提交的变更，成果可能未真正落盘。
+
+### 6. 验证 commit message 格式
+
+根据项目 CLAUDE.md 中的 Git Commit Rules 检查 commit message 格式：
+
+```bash
+# 检查每个相关 commit 的完整 message
+cd <subdir> && git log --format="%B" <commit-hash> -1
+```
+
+格式不符合项目规范 → P1 问题（规范违规）。
+
+> **amend 边界**：如果 commit 未 push 到 remote，可 amend 修复；已 push 则必须新建 commit。
+
+### 7. 交叉验证报告数据
+
+报告中的数字必须自洽：
+
+- 分项测试数相加是否等于合计？
+- 表格是否有重复行？
+- 截图数量是否与声称一致？
+- 引用文件路径是否真实存在？
+
+```bash
+# 检查截图文件是否存在
+ls -la docs/{member}/YYYY-MM-DD/*.png
+```
+
+不一致 → P2 问题。
+
+### 8. 产出验收报告
+
+写入 PM 的验收报告文件（如 `docs/pm/YYYY-MM-DD/acceptance-report.md`），使用以下模板：
+
+```markdown
+# 验收报告
+
+> PM | YYYY-MM-DD | 验收范围：成员 A / 成员 B / ... 交付物
+
+## 验收结论：Go / No-Go
+
+（一句话结论 + 原因）
+
+---
+
+## 逐项验收
+
+### 成员 A — 任务名称
+
+| 检查项 | 预期 | 实际 | 结果 |
+|--------|------|------|------|
+| ... | ... | ... | ✅/❌/⚠️ |
+
+### 成员 B — 任务名称
+
+...
+
+---
+
+## 问题清单
+
+| # | 严重度 | 问题 | 责任人 | 修复方案 |
+|---|--------|------|--------|---------|
+| 1 | P0/P1/P2 | 描述 | @name | 具体操作 |
+
+---
+
+## 验收完成标准重检
+
+- [ ] 标准 1 ✅/❌
+- [ ] 标准 2 ✅/❌
+...
+
+---
+
+*PM — YYYY-MM-DD*
+```
+
+---
+
+## 问题严重度分级
+
+| 级别 | 定义 | 示例 |
+|------|------|------|
+| P0 | 虚假报告、代码变更不存在、commit 不存在 | 引用不存在的 commit hash |
+| P1 | 规范违规、产出物缺失、签名格式错误 | commit 格式不符合项目要求 |
+| P2 | 报告数据错误、表格笔误 | 测试数分项与合计不对应 |
+
+验收标准：**零问题才能签 Go**。不做"条件通过"。
+
+---
+
+## 与其他技能的协作
+
+- **[[task-traceability]]**：基础层。Accepter 严格遵循追溯 → 执行 → 映射 → 举证 → 记录的五步法。追溯全链产出和验收标准（Trace），逐项核实验收标准（Execute），映射交付物到验收标准（Map），提供代码检查、测试运行、git log 等证据（Evidence），签署验收报告并记录 Go/No-Go（Record）。零问题才能签 Go——不做条件通过。
+- **[[task-planning]]**：Accepter 以 Planner 蓝图中的验收标准为核实基准。
+- **[[task-execution]]**：Accepter 核验 Builder 的代码变更和 commit hash 是否真实存在。
+- **[[task-verification]]**：Accepter 引用 Verifier 的报告，但不替代自己的独立核实。
+- **[[task-review]]**：Accepter 依赖 Reviewer 的 Pass 结论。Review 不通过无须进入 Accept。
+
+---
+
+## 特别注意
+
+- **外部阻塞不是缺陷**：如外部依赖未就绪导致某些验收项无法执行，在报告中标注为外部阻塞，不计入问题清单，但须明确放行条件。
+- **worktree / 多仓库**：如项目使用多个独立 git worktree 或子模块，git 操作必须 `cd` 到对应子目录执行。根目录的 `git log` 看不到子目录的 commit。
+- **报告 ≠ 真相**：报告中的 claim 必须可独立验证。如果某项验收标准无法复现（如需要外部系统产出），标记为 ⏸ Blocked，不打 ☑。
+- **commit 后验收**：团队成员应在验收前完成 commit。如果发现未 commit，退回要求先 commit 再验收。

package/dist/skills/task-execution/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: task-execution
+description: Guided task execution for the Builder role. Use when the Builder claims a task from the orchestrator queue and needs to execute it — reading the blueprint, making code changes, running verification, and reporting results with full traceability from every code change back to the Plan. Triggers on keywords like "执行任务", "开始构建", "claim task", "build", "implement", "开发", "写代码", or when a Builder has claimed a task and is ready to work. Complements task-traceability as the foundational traceability layer.
+---
+
+# Task Execution
+
+> 执行不是凭感觉写代码，是理解蓝图 → 精准实现 → 自证正确 → 记录可追溯的完整闭环。本技能与 [[task-traceability]] 协作，确保 Builder 的每次执行产出可被 Verifier 独立验证，每个代码变更都可追溯到具体的 Plan 要求。
+
+---
+
+## 何时触发
+
+- Worker 通过 `claude-orchestrator claim-task` 认领了 build 类型的任务
+- 用户说"开始执行"、"开始构建"、"implement this task"
+- Leader 直接分配了 build 任务给 Builder
+- 任务蓝图中标记为 build 的项需要开工
+
+---
+
+## 执行六步法
+
+按顺序执行，每一步通过才进入下一步。
+
+### 1. 认领任务并获取上下文
+
+```bash
+# 认领任务
+claude-orchestrator claim-task
+
+# 获取蓝图
+claude-orchestrator get-context --key plan-<目标slug>
+```
+
+从任务和蓝图中提取：
+- 本任务的验收标准（具体到命令和文件路径）
+- 前序依赖任务的产出物（Plan 的输出、上游 Build 的产出）
+- 本任务的预期产出物
+
+如果蓝图不在共享上下文中，通过消息向 Planner 索要。
+
+### 2. 理解执行范围
+
+通读蓝图中的相关部分，确认理解无误：
+
+- 明确"做什么"和"不做什么"——不要在实现中越界
+- 识别与上游产出物的接口（API 契约、文件协议等）
+- 确认验收标准的可复现性——如果你无法按验收标准自测，验收标准本身有缺陷，反馈给 Planner
+
+如果蓝图有歧义或不清晰 → 通过消息联系 Planner 澄清，不要猜测。
+
+### 3. 执行实现
+
+按照蓝图执行代码变更：
+
+- 只做任务范围内的事，不顺手重构无关代码
+- 遵循项目现有的代码规范和架构模式
+- 编写必要的测试（如果验收标准要求）
+- 产出物（测试报告、截图等）放入约定的输出路径
+
+**与 [[task-traceability]] 协作**：每次代码提交遵循可追溯工作流——自己的名字签名、commit hash 记录回任务文档。
+
+### 4. 自测验证
+
+在报告完成之前，自行运行验收标准中的验证命令：
+
+```bash
+# 示例：运行测试
+npm test -- <test-pattern> 2>&1
+
+# 示例：检查产出物
+ls -la <expected-output-path>
+```
+
+如果验收标准中定义了多个检查点，逐项执行并记录结果。所有检查点通过后才进入下一步。
+
+如果某项检查失败但属于外部原因（非本任务引入的问题），在报告中标注为已知问题，不阻塞完成。
+
+### 5. 提交代码
+
+按照 [[task-traceability]] Step 3-5 完成提交链：
+
+```bash
+# Step 3: 提交代码（用自己的名字签名）
+git add <changed-files>
+git commit -m "feat(<scope>): <description>
+
+<details>
+
+<Your Name>"
+
+# Step 4: 记录 commit hash 到任务文档
+# Step 5: 提交文档更新
+```
+
+关键规则：
+- 一个逻辑单元一个 commit，不批量提交不相关的变更
+- commit message 末尾签自己的名字
+- 记录 commit hash 回任务文档
+
+### 6. 报告完成
+
+标记任务完成并通知：
+
+```bash
+claude-orchestrator complete-task \
+  --task-id <task-id> \
+  --result "完成了 XXX，commit: a1b2c3d。测试全部通过。产出物: <path>"
+```
+
+---
+
+## 执行完成检查清单
+
+```
+□ 已认领任务并从蓝图获取上下文
+□ 已理解执行范围和验收标准
+□ 代码变更只在任务范围内，无越界修改
+□ 验收标准中的命令自测全部通过
+□ 代码已提交，签名为自己的名字 (task-traceability Step 3)
+□ commit hash 已记录回任务文档 (task-traceability Step 4)
+□ 任务文档更新已提交 (task-traceability Step 5)
+□ 已通过 orchestrator complete-task 报告完成
+```
+
+---
+
+## 与其他技能的协作
+
+- **[[task-traceability]]**：基础层。Builder 严格遵循追溯 → 执行 → 映射 → 举证 → 记录的五步法。每个代码变更必须追溯至 Plan 的具体要求，映射到实现，附带测试证据，并通过 commit hash 记录回任务文档。
+- **[[task-planning]]**：Builder 依赖 Planner 的蓝图和追溯链来理解执行范围。如果蓝图有歧义，反馈给 Planner 澄清。
+- **[[task-verification]]**：Verifier 将独立验证 Builder 的产出。Builder 的自测和可追溯记录降低了 Verifier 发现基础问题的概率。
+
+---
+
+## 常见错误
+
+- **不读蓝图直接写代码**：跳过 Step 1-2，凭任务标题猜测需求。结果往往偏离 Planner 的设计意图。
+- **越界修改**：顺手"优化"了无关代码。增加了 Reviewer 的审查负担和 Verifier 的验证范围，可能引入新 bug。
+- **不跑验收命令就报完成**：验收标准写明了 `npm test -- foo`，但 Builder 没跑就说完成了。Verifier 一跑就挂。
+- **跳过自测结果记录**：只完成了代码，但验收标准要求产出截图/测试报告，Builder 没产出。Verifier 无法验证。
+- **commit 没签自己的名**：commit hash 记录了但签名用的是别人。追溯链断了——谁做的不可知。