@hailer/mcp 1.0.28 → 1.1.2

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

@@ -2,7 +2,9 @@
 description: Activate tool-builder mode to implement a new MCP tool
 ---
 
-Load the `tool-builder` skill and enter tool-building mode.
+# Tool Builder Mode
+
+Loading `tool-builder` skill for MCP tool patterns...
 
 **What tool should I build?**
 

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

@@ -17,7 +17,7 @@ Pull the current workspace configuration from Hailer and save it locally.
 **Instructions for Claude:**
 
 1. Read `.env.local` file to get `WORKSPACE_CONFIG_PATH`
-2. Run: `cd "$WORKSPACE_CONFIG_PATH" && npm run ws-pull`
+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

package/.claude/commands/yolo-off.md

@@ -0,0 +1,17 @@
+---
+description: Disable yolo mode and restore normal permissions
+---
+# Disable Yolo Mode
+
+Run this command to disable yolo mode:
+
+```bash
+node .claude/scripts/yolo-toggle.cjs off
+```
+
+This will:
+- Remove the permissive permissions added by yolo mode
+- Restore normal confirmation prompts
+- Delete the .yolo-mode marker file
+
+Confirm when done: "Normal mode restored. Permission prompts re-enabled."

package/.claude/commands/yolo.md

@@ -0,0 +1,82 @@
+---
+description: Run autonomously without asking permission
+argument-hint: <task to complete>
+---
+# AUTONOMOUS MODE
+
+Execute the following task without stopping to ask questions:
+
+**Task:** $ARGUMENTS
+
+## Step 1: Enable yolo mode
+
+Run this command to find and execute yolo-toggle:
+```bash
+node .claude/scripts/yolo-toggle.cjs on
+```
+
+## Step 2: Create restore point (if git available)
+
+If this is a git repository, run `/save "Before YOLO: $ARGUMENTS"` to create a restore point.
+If no git, skip this step silently.
+
+## Step 3: Gather context first
+
+Before writing any code:
+1. Read DEVELOPMENT.md to understand project state
+2. Read relevant PRD if one exists for this task
+3. Check workspace/ files if this is a Hailer project
+4. Understand existing patterns before creating new ones
+
+**Don't skip context gathering** - autonomous doesn't mean blind.
+
+## Step 4: Execute the task
+
+**Rules:**
+1. Make decisions yourself - don't ask for preferences
+2. Choose the most sensible option when multiple approaches exist
+3. Proceed through errors - try to fix them, only stop if truly stuck
+4. Complete the entire task before reporting back
+5. Use your best judgment for code style, naming, structure
+6. **ALWAYS delegate to agents** - Kenji reads, Dmitri writes, Giuseppe builds apps, etc.
+   Yolo = "agents work without permission prompts", NOT "orchestrator does everything".
+   The delegation-reminder hook ENFORCES this - it blocks direct tool use in yolo mode.
+
+**Boundaries:**
+- ONLY edit/create/delete files in the CURRENT PROJECT FOLDER
+- You MAY read other projects for reference/context
+- You MAY NOT edit, write, or modify anything outside this project
+
+**Still requires confirmation:**
+- Push commands (npm run push, fields-push, etc.) - safety hooks still active
+
+## Step 5: Context management
+
+The **context-watchdog hook** monitors context automatically during yolo mode. It will:
+- Warn you at ~20 agent calls (early heads-up)
+- Warn urgently at ~35 agent calls (save progress now)
+- Inject handoff instructions when auto-compaction fires (context IS full)
+- Block you from stopping after compaction until handoff is written
+
+**When you see a watchdog warning**, follow its instructions:
+1. Update DEVELOPMENT.md with current progress
+2. Write SESSION-HANDOFF.md with full state and next steps
+3. Run `/save` with progress description
+4. Tell user: "Context getting full. Run `/yolo` again to continue."
+
+**Don't wait for the watchdog** if you notice the task is large - save progress proactively at natural breakpoints.
+
+## Step 6: When complete
+
+1. Update DEVELOPMENT.md with what was done
+2. If implementing a PRD, update its status (Draft → Complete) and check off completed items
+3. Run `/save` with completion description
+4. Disable yolo mode:
+   ```bash
+   node .claude/scripts/yolo-toggle.cjs off
+   ```
+5. Report summary of what was accomplished
+
+---
+
+GO. Do the task end-to-end, then report what you did.

package/.claude/hooks/_shared-memory.cjs

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+/**
+ * <hook-name>_shared-memory</hook-name>
+ *
+ * <purpose>
+ * Shared memory utility for squad orchestration. Caches schema-level data
+ * (workflow IDs, field definitions, phase lists) between squad runs to
+ * eliminate redundant Kenji lookups.
+ *
+ * Orchestrator writes AND reads. Agents never touch shared memory directly.
+ * </purpose>
+ *
+ * <usage>
+ * As module:
+ *   const mem = require('./_shared-memory.cjs');
+ *   mem.set('workflow-schemas', data, 'agent-kenji-data-reader');
+ *   const cached = mem.get('workflow-schemas');
+ *
+ * As CLI:
+ *   node _shared-memory.cjs --get <key>
+ *   node _shared-memory.cjs --set <key> <json-file>
+ *   node _shared-memory.cjs --status
+ *   node _shared-memory.cjs --invalidate
+ *   node _shared-memory.cjs --help
+ * </usage>
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const os = require('os');
+
+const DEFAULT_MAX_AGE_MS = 30 * 60 * 1000; // 30 minutes
+const STORE_VERSION = 1;
+
+function getProjectDir() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+function getStorePath() {
+  return path.join(getProjectDir(), '.claude', '.shared-memory.json');
+}
+
+function getWorkspaceDir() {
+  return path.join(getProjectDir(), 'workspace');
+}
+
+/**
+ * MD5 hash of workspace/ directory listing for staleness detection.
+ * Returns null if workspace/ doesn't exist.
+ */
+function getWorkspaceHash() {
+  const wsDir = getWorkspaceDir();
+  if (!fs.existsSync(wsDir)) return null;
+
+  try {
+    const entries = [];
+    collectEntries(wsDir, '', entries);
+    entries.sort();
+    return crypto.createHash('md5').update(entries.join('\n')).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+function collectEntries(dir, prefix, entries, depth = 0) {
+  if (depth > 10) return;
+  const items = fs.readdirSync(dir, { withFileTypes: true });
+  for (const item of items) {
+    const rel = prefix ? `${prefix}/${item.name}` : item.name;
+    if (item.isDirectory()) {
+      entries.push(`d:${rel}`);
+      collectEntries(path.join(dir, item.name), rel, entries, depth + 1);
+    } else {
+      const stat = fs.statSync(path.join(dir, item.name));
+      entries.push(`f:${rel}:${stat.size}:${stat.mtimeMs}`);
+    }
+  }
+}
+
+/**
+ * Validate store against current workspace hash and session.
+ * Returns true if valid, false if invalidated.
+ */
+function validateStore(store) {
+  if (!store || store.version !== STORE_VERSION) return false;
+
+  // Session check: invalidate if different session
+  const currentSession = process.env.CLAUDE_SESSION_ID || '';
+  if (currentSession && store.sessionId && store.sessionId !== currentSession) {
+    return false;
+  }
+
+  // Workspace hash check
+  const currentHash = getWorkspaceHash();
+  if (currentHash && store.workspaceHash && store.workspaceHash !== currentHash) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Load the shared memory store. Returns empty store if missing/invalid.
+ */
+function load() {
+  const storePath = getStorePath();
+  try {
+    if (fs.existsSync(storePath)) {
+      const store = JSON.parse(fs.readFileSync(storePath, 'utf8'));
+      if (validateStore(store)) return store;
+      // Invalid store - return fresh
+    }
+  } catch {}
+
+  return createEmptyStore();
+}
+
+function createEmptyStore() {
+  return {
+    version: STORE_VERSION,
+    sessionId: process.env.CLAUDE_SESSION_ID || '',
+    createdAt: new Date().toISOString(),
+    workspaceHash: getWorkspaceHash(),
+    entries: {}
+  };
+}
+
+/**
+ * Atomic save: write to temp file then rename.
+ */
+function save(store) {
+  const storePath = getStorePath();
+  const dir = path.dirname(storePath);
+
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const tmpPath = path.join(os.tmpdir(), `.shared-memory-${process.pid}-${Date.now()}.json`);
+  fs.writeFileSync(tmpPath, JSON.stringify(store, null, 2));
+  fs.renameSync(tmpPath, storePath);
+}
+
+/**
+ * Get an entry by key. Returns null if missing or stale.
+ */
+function get(key, maxAgeMs = DEFAULT_MAX_AGE_MS) {
+  const store = load();
+  const entry = store.entries[key];
+  if (!entry) return null;
+
+  if (isStale(key, maxAgeMs, store)) return null;
+
+  return entry;
+}
+
+/**
+ * Set an entry with metadata.
+ */
+function set(key, data, writtenBy = 'orchestrator') {
+  const store = load();
+  store.entries[key] = {
+    writtenAt: new Date().toISOString(),
+    writtenBy,
+    data
+  };
+  store.workspaceHash = getWorkspaceHash();
+  save(store);
+}
+
+/**
+ * Check if an entry is older than maxAge.
+ */
+function isStale(key, maxAgeMs = DEFAULT_MAX_AGE_MS, store = null) {
+  store = store || load();
+  const entry = store.entries[key];
+  if (!entry) return true;
+
+  const age = Date.now() - new Date(entry.writtenAt).getTime();
+  return age > maxAgeMs;
+}
+
+/**
+ * Clear all entries.
+ */
+function invalidate() {
+  const storePath = getStorePath();
+  try {
+    if (fs.existsSync(storePath)) {
+      fs.unlinkSync(storePath);
+    }
+  } catch {}
+}
+
+/**
+ * Get status of all entries.
+ */
+function status() {
+  const store = load();
+  const currentHash = getWorkspaceHash();
+  const hashMatch = currentHash === store.workspaceHash;
+
+  const entryStatus = {};
+  for (const [key, entry] of Object.entries(store.entries)) {
+    const age = Date.now() - new Date(entry.writtenAt).getTime();
+    const ageMinutes = Math.round(age / 60000);
+    entryStatus[key] = {
+      writtenBy: entry.writtenBy,
+      writtenAt: entry.writtenAt,
+      ageMinutes,
+      stale: age > DEFAULT_MAX_AGE_MS,
+      dataKeys: entry.data ? Object.keys(entry.data) : []
+    };
+  }
+
+  return {
+    version: store.version,
+    sessionId: store.sessionId,
+    createdAt: store.createdAt,
+    workspaceHash: store.workspaceHash,
+    currentHash,
+    hashMatch,
+    entryCount: Object.keys(store.entries).length,
+    entries: entryStatus
+  };
+}
+
+// --- CLI interface ---
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const cmd = args[0];
+
+  if (!cmd || cmd === '--help') {
+    console.log(`Usage:
+  node _shared-memory.cjs --get <key>          Read entry (JSON to stdout)
+  node _shared-memory.cjs --set <key> <file>   Set entry from JSON file
+  node _shared-memory.cjs --status             Show all entries and ages
+  node _shared-memory.cjs --invalidate         Clear all entries
+  node _shared-memory.cjs --help               Show this help`);
+    process.exit(0);
+  }
+
+  if (cmd === '--status') {
+    console.log(JSON.stringify(status(), null, 2));
+    process.exit(0);
+  }
+
+  if (cmd === '--invalidate') {
+    invalidate();
+    console.log('Shared memory invalidated.');
+    process.exit(0);
+  }
+
+  if (cmd === '--get') {
+    const key = args[1];
+    if (!key) {
+      console.error('Usage: --get <key>');
+      process.exit(1);
+    }
+    const entry = get(key);
+    if (entry) {
+      console.log(JSON.stringify(entry, null, 2));
+    } else {
+      console.log('null');
+    }
+    process.exit(0);
+  }
+
+  if (cmd === '--set') {
+    const key = args[1];
+    const file = args[2];
+    if (!key || !file) {
+      console.error('Usage: --set <key> <json-file>');
+      process.exit(1);
+    }
+    try {
+      const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+      set(key, data, 'cli');
+      console.log(`Set "${key}" from ${file}`);
+    } catch (e) {
+      console.error(`Error: ${e.message}`);
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
+  console.error(`Unknown command: ${cmd}. Use --help for usage.`);
+  process.exit(1);
+}
+
+// --- Exports ---
+
+module.exports = {
+  load,
+  save,
+  get,
+  set,
+  isStale,
+  invalidate,
+  status,
+  getWorkspaceHash,
+  validateStore
+};