@hailer/mcp 1.1.13 → 1.1.15

package/.claude/commands/swarm.md

@@ -0,0 +1,210 @@
+---
+description: Orchestrator-driven parallel swarm for large-scale tasks
+argument-hint: "description of what to do across many items"
+allowed-tools: Task, Bash, Read, Glob
+---
+
+# Swarm
+
+Orchestrator-driven parallel execution: analyze the task, discover work items, pick agents, split into chunks, dispatch workers, aggregate results.
+
+**Goal:** $ARGUMENTS
+
+## Protocol
+
+### Step 1: Analyze the Task
+
+Read `$ARGUMENTS` and determine:
+
+- **What needs to be done?** (review, edit, check, migrate, update, clean up)
+- **What are the work items?** (files, activities, workflows, agents, skills, configs)
+- **What scope?** (explicit path/glob from user, or infer from task description)
+
+If the scope is unclear, use Glob or Bash to discover items:
+
+```
+# Files
+Glob("src/**/*.ts")
+Glob(".claude/agents/*.md")
+Glob("workspace/*/fields.ts")
+
+# Activities (use Kenji to count/list)
+Task(subagent_type="agent-kenji-data-reader", prompt="Count and list activity IDs for [workflow]")
+```
+
+If fewer than 5 items are discovered, **abort swarm** and suggest running a regular squad or single agent instead. Swarm is for scale.
+
+### Step 2: Pick Agent(s)
+
+Based on the task type, select the right agent(s):
+
+| Task Type | Agent | Examples |
+|-----------|-------|---------|
+| Code review, security audit | **Svetlana** | "review for bugs", "security check", "find vulnerabilities" |
+| Dead code, unused imports, type errors | **Lars** | "find dead code", "check types", "unused imports" |
+| Small edits, string replacements, rule additions | **Simple Writer** | "add header to each file", "replace X with Y", "update rule" |
+| Code cleanup, simplification | **Code Simplifier** | "clean up", "simplify", "refactor for clarity" |
+| Config audit, structure validation | **Bjorn** | "check config", "validate structure", "audit settings" |
+| Data state checks, field validation | **Kenji** | "check all activities", "verify field values", "find missing data" |
+| Query patterns, data analysis | **Viktor** | "analyze patterns", "find anomalies across workflows" |
+| Activity updates, bulk mutations | **Dmitri** | "update all activities", "move to phase", "set field values" |
+
+**Multi-agent swarms:** If the task spans multiple domains, assign different agent types to different items. For example, "clean up the project" might use Lars for `.ts` files, Bjorn for config files, and Code Simplifier for app components.
+
+### Step 3: Calculate Workers
+
+```
+items_count = total discovered items
+items_per_worker = 10 (default)
+max_workers = 5
+
+worker_count = min(ceil(items_count / items_per_worker), max_workers)
+```
+
+Split items into `worker_count` chunks. Try to keep chunks roughly equal size.
+
+For multi-agent swarms, group items by agent type first, then chunk within each type.
+
+### Step 4: Dispatch Workers
+
+Launch all workers in parallel using multiple Task tool calls in a single message. All workers run in background (`run_in_background: true`).
+
+Each worker gets:
+
+```
+Task(subagent_type="[selected-agent]",
+  run_in_background: true,
+  prompt="SWARM WORKER [N] of [TOTAL]
+
+TASK: [User's description from $ARGUMENTS]
+
+YOUR ITEMS ([count]):
+- [item 1]
+- [item 2]
+- [item 3]
+...
+
+Process each item and report results in this format:
+
+RESULTS:
+- [item]: [status] - [details]
+- [item]: [status] - [details]
+
+SUMMARY:
+- Processed: [count]
+- Passed: [count]
+- Issues found: [count]
+- Failed: [count]")
+```
+
+Tell the user:
+```
+Launched [worker_count] workers across [items_count] items.
+Running in background - what else do you want to work on?
+```
+
+### Step 5: Collect Results
+
+When workers complete (check via Read on output files or TaskOutput), aggregate all results.
+
+If any worker failed or timed out:
+- Report which items were in the failed worker's batch
+- Offer to retry just those items
+
+### Step 6: Report
+
+```markdown
+## Swarm Report
+
+### Task
+[User's description]
+
+### Execution
+- **Items:** [total count]
+- **Workers:** [worker count] x [agent type(s)]
+- **Duration:** [time from dispatch to last worker completion]
+
+---
+
+### Results by Worker
+
+#### Worker 1 ([agent type]) - [X items]
+- [item]: [status] - [details]
+- [item]: [status] - [details]
+...
+
+#### Worker 2 ([agent type]) - [X items]
+...
+
+---
+
+### Aggregate Summary
+
+| Status | Count |
+|--------|-------|
+| Passed / Clean | X |
+| Issues Found | X |
+| Failed / Error | X |
+
+### Issues Found
+[Grouped and deduplicated list of all issues across all workers]
+
+1. **[item]**: [issue description]
+2. **[item]**: [issue description]
+...
+
+### Failed Items
+[If any workers failed, list their items for retry]
+
+### Next Steps
+- [Suggested follow-up based on results]
+- [If issues found: suggest /hotfix-squad or Simple Writer to fix]
+- [If edits made: suggest /review-squad to verify]
+```
+
+## Options
+
+| Flag | Effect |
+|------|--------|
+| `--workers=N` | Override worker count (default: auto-calculated, max 5) |
+| `--dry-run` | Show what would be dispatched without actually running |
+| `--no-bg` | Run workers in foreground (wait for all to complete) |
+
+## Examples
+
+```
+# Review all source files for security
+/swarm "review all TypeScript files in src/ for security vulnerabilities"
+→ Discovers 47 .ts files, spawns 5 Svetlana workers
+
+# Bulk edit agent files
+/swarm "add a '## Version History' section to every agent file"
+→ Discovers 27 agent .md files, spawns 3 Simple Writer workers
+
+# Validate workspace configs
+/swarm "check all workflow field definitions for missing descriptions"
+→ Discovers 12 fields.ts files, spawns 2 Kenji workers
+
+# Multi-agent cleanup
+/swarm "clean up the entire apps/ directory"
+→ Discovers 34 files: 20 .tsx → Code Simplifier, 8 .ts → Lars, 6 configs → Bjorn
+→ Spawns 5 workers across 3 agent types
+
+# Data validation
+/swarm "verify all Customer activities have a valid email field"
+→ Kenji counts 200 customers, spawns 5 Kenji workers (40 each)
+
+# Dry run to preview
+/swarm "update all skills to use consistent headers" --dry-run
+→ Shows: "Would dispatch 4 Simple Writer workers across 32 skill files"
+```
+
+## Notes
+
+- Minimum 5 items to trigger swarm (below that, use a regular agent)
+- Default max 5 workers to avoid overwhelming the system
+- Workers run in background by default so user can keep working
+- Multi-agent swarms naturally emerge from the orchestrator's routing logic
+- For write operations (Dmitri, Simple Writer), consider running --dry-run first
+- Swarm vs Squad: Swarm is raw parallel execution without quality gates. Workers operate independently. Squads have convergence, synthesis, and loops. Use swarm for bulk independent items, squads for coordinated workflows.
+- Swarm + squad can combine: `/swarm "review src/"` finds issues, then user can run `/hotfix-squad` on results. This is a manual handoff - user confirms.

package/.claude/commands/tool-builder.md

@@ -0,0 +1,39 @@
+---
+description: Activate tool-builder mode to implement a new MCP tool
+---
+
+# Tool Builder Mode
+
+Loading `tool-builder` skill for MCP tool patterns...
+
+**What tool should I build?**
+
+Please provide:
+
+- **Tool Name**: `tool_name` (snake_case)
+- **Purpose**: What does it do?
+- **API Endpoint**: `v3.endpoint.method`
+- **Request Format**: `[arg1, arg2]`
+- **Response Format**: What the API returns
+- **Target File**: Which file in `src/mcp/tools/`?
+- **Tool Group**: READ | WRITE | PLAYGROUND
+
+---
+
+**Example:**
+```
+Tool Name: list_insights
+Purpose: List all insights in workspace
+API Endpoint: v3.insight.list
+Request: [workspaceId]
+Response: { insights: [{_id, name, query, sources}] }
+Target File: insight.ts
+Tool Group: PLAYGROUND
+```
+
+I'll:
+1. Load tool-builder skill
+2. Read existing patterns in target file
+3. Implement the tool
+4. Register in src/app.ts
+5. Report what was created

package/.claude/commands/ws-pull.md

@@ -0,0 +1,44 @@
+---
+description: Pull workspace configuration from Hailer (READ-ONLY)
+---
+
+Pull the current workspace configuration from Hailer and save it locally.
+
+**What this does:**
+- Downloads workflows, insights, teams, groups, and phases from Hailer workspace
+- Saves configuration as JSON files to the `WORKSPACE_CONFIG_PATH` directory
+- READ-ONLY operation - does not modify anything on Hailer
+- Safe to run anytime
+
+**Requirements:**
+- Must have `WORKSPACE_CONFIG_PATH` set in `.env.local`
+- Hailer credentials must be configured
+
+**Instructions for Claude:**
+
+1. Read `.env.local` file to get `WORKSPACE_CONFIG_PATH`
+2. Run: `cd "$WORKSPACE_CONFIG_PATH" && npm run pull`
+3. **AUTOMATICALLY read the generated files to load context:**
+   - Read `workspace/enums.ts` (complete file - contains ALL field and phase IDs)
+   - List `workspace/` directory to see all workflow folders
+   - Read 1-2 example workflow configs (main.ts, fields.ts, phases.ts) to understand structure
+4. Provide summary of what workflows were pulled and confirm context is loaded
+
+**What gets downloaded:**
+- `workspace/enums.ts` - Type-safe field and phase ID enums for ALL workflows
+- `workspace/workflows.ts` - Main workflows export
+- `workspace/insights.ts` - SQL insight definitions
+- `workspace/teams.ts` - Team structures
+- `workspace/groups.ts` - User groups
+- `workspace/<workflow_name>/` - Individual workflow configs (main.ts, fields.ts, phases.ts)
+
+**Why automatic reading matters:**
+- Loads all field/phase IDs into conversation context immediately
+- Enables local-first strategy without manual file reads
+- Saves 75% of API calls and hundreds of tokens on subsequent operations
+- You'll know the workspace structure instantly
+
+**Common use cases:**
+- Backup current workspace configuration
+- Review workflow structures locally
+- Prepare for making configuration changes