@adamancyzhang/claude-orchestrator 0.3.0 → 0.3.2

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,244 @@
+---
+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
+npm install -g @adamancyzhang/claude-orchestrator
+docker-compose up -d   # start ZooKeeper
+```
+
+Initialize environment:
+
+```bash
+# Leader (team coordinator):
+claude-orchestrator setup --leader --name Tom
+
+# Worker (the doers):
+claude-orchestrator setup --name Jerry --role builder
+```
+
+This creates:
+- `.claude-orchestrator/agents/` — message templates (7 templates for leader + 5 worker links)
+- `.claude/skills/` — 8 Claude Code skills (responsibility chain + infrastructure)
+- `.claude-orchestrator/config.json` — project config (name, role)
+- `~/.claude-orchestrator/config.json` — global config (ZK hosts, CLI command, cache dir)
+
+Verify:
+
+```bash
+claude-orchestrator config
+# Shows current configuration
+```
+
+## Global Options
+
+| Option | Env var | Default | Description |
+|--------|---------|---------|-------------|
+| `--zookeeper`, `-z` | `ZK_HOSTS` | `127.0.0.1:2181` | ZooKeeper connection string |
+| `--instance-id`, `-i` | — | auto (from config) | Override stored instance ID |
+
+## Commands
+
+### Leader
+
+```bash
+claude-orchestrator leader --name Tom
+# Launches read-only TUI: team panel, task board, event log
+```
+
+Only one Leader at a time (ZK ephemeral node). The TUI shows who's online, what tasks are in each state, and a scrolling event log.
+
+### Registration
+
+**Setup** — one-time initialization:
+
+```bash
+claude-orchestrator setup --leader --name Tom                    # Leader
+claude-orchestrator setup --name Jerry --role builder             # Worker
+claude-orchestrator setup --name Lucy --role verifier \
+  --cache-dir ~/shared/sessions --command "claude -p"             # Custom CLI
+```
+
+Setup options:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--leader` | false | Initialize as Leader environment |
+| `--name <name>` | — | Instance display name |
+| `--role <role>` | builder | Role: planner, builder, verifier, reviewer, accepter |
+| `--cache-dir <path>` | `~/.claude-orchestrator/sessions` | Shared cache directory |
+| `--command <cmd>` | `claude --dangerously-skip-permissions --permission-mode dontAsk` | Claude CLI command |
+| `--global` | false | Write only global config, skip project files |
+
+**Register** — join the swarm:
+
+```bash
+# Connect and listen for messages (reads name/role from .claude-orchestrator/config.json):
+claude-orchestrator register
+# Worker Watcher starts, listens for messages, processes via claude -p
+# Press Ctrl+C to stop and unregister
+```
+
+Registration creates an ephemeral ZK node. The instance auto-deregisters on disconnect (Ctrl+C or timeout). The Worker Watcher listens for messages on `/messages/{instance_id}` and processes them using the template that matches the message's `link` field.
+
+**Unregister:**
+
+```bash
+claude-orchestrator unregister
+```
+
+### Tasks
+
+**Push a task** to the queue:
+
+```bash
+claude-orchestrator push-task --title "Implement login endpoint" --priority 0
+claude-orchestrator push-task --title "Verify auth module" --link verify --priority 1
+claude-orchestrator push-task --title "Review PR #42" --link review --assignee <instance-id>
+claude-orchestrator push-task --title "Part 2" --chain-id chain-001 --depends-on task-0000000001
+```
+
+Push options:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--title <text>` | required | Task title |
+| `--description <text>` | "" | Task description |
+| `--priority <n>` | 1 | 0=HIGH, 1=MEDIUM, 2=LOW |
+| `--assignee <id>` | — | Target instance ID |
+| `--link <link>` | — | Responsibility chain link: plan, build, verify, review, accept |
+| `--chain-id <id>` | — | Group related tasks under one chain |
+| `--depends-on <ids>` | — | Comma-separated task IDs this task depends on |
+| `--blocked-by <ids>` | — | Comma-separated task IDs blocking this task |
+
+**Claim a task** — FIFO, higher priority first, assigned-to-you tasks jump the queue:
+
+```bash
+claude-orchestrator claim-task
+# → { "id": "task-0000000001", "title": "Implement login endpoint", "status": "claimed", ... }
+# → { "status": "no_tasks", "message": "No pending tasks available." }
+```
+
+**Complete a task:**
+
+```bash
+claude-orchestrator complete-task --task-id task-0000000001 --result "PR #42 — login endpoint with tests"
+```
+
+**Poll tasks:**
+
+```bash
+claude-orchestrator poll-task
+claude-orchestrator poll-task --status pending
+claude-orchestrator poll-task --status claimed
+claude-orchestrator poll-task --status completed
+claude-orchestrator poll-task --status blocked
+claude-orchestrator poll-task --status failed
+```
+
+**Task lifecycle commands:**
+
+```bash
+claude-orchestrator task-block --task-id task-0000000001 --reason "Waiting for API key"
+claude-orchestrator task-fail --task-id task-0000000001 --reason "Test environment unavailable"
+claude-orchestrator task-retry --task-id task-0000000001
+# → Re-queued with retry_count + 1 (max 3 retries)
+```
+
+Task state machine:
+
+```
+pending → claimed → in_progress → completed
+                            → blocked → pending (retry)
+                            → failed  → pending (retry, max 3)
+claimed → pending (Worker disconnect, Leader recovers orphan)
+```
+
+### Messages
+
+**Send a direct message:**
+
+```bash
+claude-orchestrator send-message --to-name Jerry --content "Can you review my PR?"
+```
+
+**Broadcast to all:**
+
+```bash
+claude-orchestrator send-message --broadcast --content "CI is down, don't push"
+```
+
+**Request help** (broadcasts to all with help flag):
+
+```bash
+claude-orchestrator send-message --request-help --broadcast --content "How do I test the auth flow?"
+```
+
+**Poll messages:**
+
+```bash
+claude-orchestrator poll-message
+# [{ "id": "msg-...", "type": "direct", "from_name": "Tom", "content": "...", "read": true }]
+```
+
+**Delete a message:**
+
+```bash
+claude-orchestrator delete-message --message-id msg-0000000000
+```
+
+### Config
+
+```bash
+claude-orchestrator config
+# Shows global and project configuration
+```
+
+## Roles
+
+| Role | Value | Typical behavior |
+|------|-------|-----------------|
+| Leader | `leader` | Runs TUI, monitors team, recovers orphaned tasks |
+| Planner | `planner` | Uses `task-planning` + `task-traceability` skills |
+| Builder | `builder` | Uses `task-execution` + `task-traceability` skills |
+| Verifier | `verifier` | Uses `task-verification` + `task-traceability` skills |
+| Reviewer | `reviewer` | Uses `task-review` + `task-traceability` skills |
+| Accepter | `accepter` | Uses `task-acceptance` + `task-traceability` skills |
+
+## Workflow
+
+A typical agent session:
+
+```bash
+# 1. Initialize (first time only)
+claude-orchestrator setup --name Jerry --role builder
+
+# 2. Join the team — Worker Watcher auto-processes incoming messages via claude -p
+claude-orchestrator register
+# Press Ctrl+C to stop and unregister
+```
+
+## Error recovery
+
+- **ZooKeeper not connected**: check `docker-compose ps`, retry. ZK client auto-reconnects.
+- **"No instance_id found"**: run `setup` first, or check `.claude-orchestrator/config.json`
+- **Registration expired**: ephemeral nodes cleaned up on disconnect. Re-register to restore identity.