@adamancyzhang/claude-orchestrator 0.2.8 → 0.3.1

package/dist/skills/claude-code-developer/SKILL.md

@@ -0,0 +1,325 @@
+---
+name: claude-code-developer
+description: Reference for developing Claude Code extensions — hooks, settings, MCP, CLI, and skills. Use when building tools on Claude Code, configuring automation, debugging hooks, or understanding extension points.
+---
+
+# Claude Code Developer Guide
+
+Reference for building tools and automations on top of Claude Code. Covers hooks, settings, MCP integration, and CLI usage.
+
+## Hooks
+
+Hooks run shell commands at specific points in Claude Code's lifecycle. Configured in `settings.json` under `hooks.<EventName>`.
+
+### Hook Event Reference
+
+| Event | Matcher | Fires when | Use for |
+|-------|---------|-----------|---------|
+| `SessionStart` | — | Session starts | Auto-register, init workspace |
+| `SessionEnd` | — | Session truly ends | Cleanup, unregister |
+| `Stop` | — | Claude stops (clear/resume/compact too) | Logging — prefer `SessionEnd` for cleanup |
+| `UserPromptSubmit` | — | User submits a prompt | Pre-processing, logging |
+| `PreToolUse` | Tool name | Before a tool runs | Validation, blocking dangerous ops |
+| `PostToolUse` | Tool name | After a tool succeeds | Formatting, logging, notifications |
+| `PostToolUseFailure` | Tool name | After a tool fails | Error recovery |
+| `PreCompact` | `"manual"`/`"auto"` | Before context compaction | Save state, warn user |
+| `PostCompact` | `"manual"`/`"auto"` | After compaction | Post-processing |
+| `Notification` | Notification type | On notifications | Custom notification handling |
+| `PermissionRequest` | Tool name | Before permission prompt | Custom permission logic |
+| `SubagentStart` | — | Subagent spawns | Agent lifecycle tracking |
+| `SubagentStop` | — | Subagent exits | Agent lifecycle tracking |
+
+### Hook Structure
+
+```json
+{
+  "hooks": {
+    "EVENT_NAME": [
+      {
+        "matcher": "ToolName|OtherTool",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "your-command-here",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+- **matcher**: tool name (`"Bash"`, `"Write"`, `"Edit"`), pipe-separated list (`"Write|Edit"`), or `""` to match all. For non-tool events, omit or use `""`.
+- **hooks**: array of hook objects, each with `type` and type-specific fields.
+
+### Hook Types
+
+**command** — Shell command:
+```json
+{ "type": "command", "command": "echo 'hello'", "timeout": 30 }
+```
+- Receives JSON on stdin with event context
+- `timeout` in seconds (optional)
+- `statusMessage` for spinner text (optional)
+- `once`: auto-remove after first run (optional)
+- `async`: run in background without blocking (optional)
+
+**prompt** — LLM evaluation (PreToolUse/PostToolUse/PermissionRequest only):
+```json
+{ "type": "prompt", "prompt": "Is this safe? $ARGUMENTS" }
+```
+- `$ARGUMENTS` placeholder replaced with hook input JSON
+
+**agent** — Agent with tools (PreToolUse/PostToolUse/PermissionRequest only):
+```json
+{ "type": "agent", "prompt": "Verify tests pass", "timeout": 60 }
+```
+
+**http** — POST hook input to a URL:
+```json
+{ "type": "http", "url": "https://example.com/hook", "headers": {} }
+```
+
+**mcp_tool** — Call an MCP tool:
+```json
+{ "type": "mcp_tool", "server": "server-name", "tool": "tool_name", "input": {} }
+```
+
+### Hook stdin JSON
+
+Hooks receive context on stdin. Key fields:
+
+```json
+{
+  "session_id": "abc123",
+  "tool_name": "Write",
+  "tool_input": { "file_path": "/path/to/file.txt", "content": "..." },
+  "tool_response": { "success": true }
+}
+```
+
+Extract with `jq`:
+```bash
+jq -r '.tool_input.file_path'
+jq -r '.tool_input.command'  # for Bash
+```
+
+### Hook JSON Output
+
+Commands can output JSON to control behavior:
+
+```json
+{
+  "systemMessage": "Warning shown to user",
+  "continue": false,
+  "stopReason": "Blocked because...",
+  "decision": "block",
+  "reason": "Explanation",
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "additionalContext": "Injected into model context",
+    "permissionDecision": "allow",
+    "permissionDecisionReason": "Why allowed"
+  }
+}
+```
+
+### Common Hook Pitfalls
+
+1. **`Stop` vs `SessionEnd`**: `Stop` fires on clear/resume/compact — use `SessionEnd` for cleanup
+2. **Matcher is required**: each hook entry needs `"matcher"` (use `""` for all)
+3. **Nested hooks array**: the outer `hooks` object contains arrays of `{matcher, hooks:[...]}`
+4. **Silent failure**: invalid JSON in settings.json silently disables ALL settings from that file
+5. **Hook command format**: `{matcher: "", hooks: [{type: "command", command: "..."}]}` — NOT flat `{matcher: "", command: "..."}`
+
+## Settings
+
+### File Locations
+
+| File | Scope | Git | Use for |
+|------|-------|-----|---------|
+| `~/.claude/settings.json` | Global (user) | No | Personal preferences |
+| `.claude/settings.json` | Project | Yes | Team-wide config |
+| `.claude/settings.local.json` | Project local | Gitignore | Personal overrides |
+
+Priority: user → project → local (later overrides earlier).
+
+### Key Settings for Tool Developers
+
+**Permissions** — allow/deny tool operations:
+```json
+{
+  "permissions": {
+    "allow": ["Bash(npm *)", "Bash(git *)"],
+    "deny": ["Bash(rm -rf *)"],
+    "defaultMode": "default"
+  }
+}
+```
+
+**MCP Servers** — manage server approval:
+```json
+{
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": ["orchestrator"],
+  "disabledMcpjsonServers": ["blocked-server"]
+}
+```
+
+**Environment Variables**:
+```json
+{ "env": { "DEBUG": "true", "ZK_HOSTS": "127.0.0.1:2181" } }
+```
+
+**Model & Agent**:
+```json
+{ "model": "sonnet", "agent": "agent-name" }
+```
+
+**Plugins**:
+```json
+{ "enabledPlugins": { "formatter@anthropic-tools": true } }
+```
+
+**Status Line** — custom terminal status bar:
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "echo '$(date +%H:%M)'",
+    "padding": 0
+  }
+}
+```
+
+### JSON Validation
+
+Broken JSON in settings.json silently disables the entire file. Validate with:
+```bash
+jq -e '.hooks.SessionStart' .claude/settings.json
+python3 -m json.tool .claude/settings.json > /dev/null
+```
+
+## MCP Integration
+
+### .mcp.json Format
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "type": "http",
+      "url": "http://127.0.0.1:3100/mcp",
+      "headers": {
+        "X-Instance-Name": "my-instance",
+        "X-Instance-Role": "developer"
+      }
+    }
+  }
+}
+```
+
+- `type`: `"http"` for Streamable HTTP, `"stdio"` for subprocess
+- `headers`: custom HTTP headers sent with every request
+- MCP tools appear as callable tools in Claude Code
+
+### MCP Server Best Practices
+
+1. Use Streamable HTTP transport on `127.0.0.1` for local servers
+2. Expose a `/health` endpoint for diagnostics
+3. Provide REST endpoints alongside MCP tools for CLI-based interaction
+4. Use `resources/subscribe` for push notifications to Claude Code
+5. Stateless sessions simplify scaling (set `sessionIdGenerator: undefined`)
+
+## CLI Reference
+
+### Key Commands
+
+```bash
+claude                      # Interactive session
+claude -p "prompt"          # One-shot, print and exit
+claude -c                   # Continue last session
+claude -r                   # Resume by ID or picker
+claude --resume <id>        # Resume specific session
+claude --model sonnet       # Override model
+claude --mcp-config file.json  # Additional MCP config
+claude --settings file.json    # Additional settings
+claude --add-dir /path      # Additional workspace dir
+claude --debug              # Debug mode
+claude --debug hooks        # Debug hooks specifically
+claude --bare               # Minimal mode (no hooks/LSP/plugins)
+```
+
+### Useful Subcommands
+
+```bash
+claude mcp                  # MCP server management
+claude auth                 # Auth management
+claude doctor               # Health check
+claude update               # Check for updates
+claude agents               # Background agents management
+claude plugin               # Plugin management
+```
+
+### Hook Testing
+
+```bash
+# Debug hooks
+claude --debug hooks
+
+# Stream hook events
+claude --include-hook-events --output-format stream-json -p "test"
+
+# Validate hook JSON
+jq -e '.hooks.<event>[] | select(.matcher == "<matcher>") | .hooks[] | select(.type == "command") | .command' .claude/settings.json
+```
+
+## Skills
+
+### Skill File Format
+
+Skills live in `skills/<name>/SKILL.md`:
+
+```markdown
+---
+name: skill-name
+description: One-line description — used for trigger matching
+---
+
+# Skill Title
+
+Skill content with instructions for the LLM.
+```
+
+- `name`: unique identifier, used for `/skill-name` invocation
+- `description`: used by Claude Code to auto-detect when to invoke the skill
+
+### Skill Design Guidelines
+
+1. **Clear triggers in description** — mention keywords users will say
+2. **Step-by-step instructions** — the LLM follows the skill literally
+3. **Include bash commands** — for the LLM to run
+4. **Handle edge cases** — re-registration, cleanup, verification
+5. **Keep it concise** — skills are loaded into context
+
+## Development Workflow
+
+### Testing a Hook
+
+1. Write the hook in `.claude/settings.json`
+2. Validate JSON: `jq -e '.hooks' .claude/settings.json`
+3. Reload config: open `/hooks` in Claude Code or restart
+4. Test with `--debug hooks` to see execution logs
+5. For tool hooks: trigger the tool and verify the side effect
+6. For lifecycle hooks (`SessionStart`, `SessionEnd`, `Stop`): restart Claude Code
+
+### Troubleshooting
+
+| Symptom | Likely cause |
+|---------|-------------|
+| Hook doesn't fire | Invalid JSON, wrong event name, matcher mismatch |
+| All settings ignored | Syntax error in settings.json |
+| Hook fires but command fails | Command not in PATH, permission denied, timeout |
+| `Stop` fires unexpectedly | `Stop` triggers on clear/compact too — use `SessionEnd` |
+| MCP tools not showing | Server not running, wrong URL in mcp.json, port conflict |

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 再验收。