@hailer/mcp 1.1.13 → 1.1.15

package/.claude/commands/help:tools.md

@@ -0,0 +1,75 @@
+---
+description: MCP tools reference for Hailer MCP
+---
+
+# MCP Tools Reference
+
+Display MCP tools reference to the user.
+
+## Output
+
+```
+╭─────────────────────────────────────────╮
+│      HAILER MCP - TOOLS REFERENCE       │
+╰─────────────────────────────────────────╯
+
+MCP tools provide direct access to Hailer APIs. These are used by
+agents but can also be called directly.
+
+WORKFLOW TOOLS:
+  list_workflows          - List all workflows in workspace
+  list_workflows_minimal  - Compact workflow list with counts
+  list_workflow_phases    - Get phases for a workflow
+  get_workflow_schema     - Get field definitions for a workflow
+  install_workflow        - Create workflow from template
+
+ACTIVITY TOOLS:
+  list_activities         - List activities in a workflow phase
+  show_activity_by_id     - Get single activity details
+  create_activity         - Create new activity (single or bulk)
+  update_activity         - Update activity (single or bulk)
+  count_activities        - Count activities in workflow
+
+DISCUSSION TOOLS:
+  list_my_discussions        - List discussions you're in
+  fetch_discussion_messages  - Read messages from discussion
+  add_discussion_message     - Post to a discussion
+  join_discussion            - Join a discussion
+  leave_discussion           - Leave a discussion
+  invite_discussion_members  - Invite users to discussion
+
+INSIGHT TOOLS:
+  list_insights      - List all insights
+  create_insight     - Create SQL-like insight
+  preview_insight    - Test insight query
+  get_insight_data   - Execute insight and get results
+  update_insight     - Modify existing insight
+
+APP TOOLS:
+  list_apps              - List apps in workspace
+  create_app             - Create app entry
+  update_app             - Update app properties
+  scaffold_hailer_app    - Generate app from template
+  publish_hailer_app     - Deploy app to production
+
+FILE TOOLS:
+  upload_files     - Upload files to Hailer
+  download_file    - Download file from Hailer
+
+USER TOOLS:
+  search_workspace_users - Find users by name
+
+TEMPLATE TOOLS:
+  list_templates     - List marketplace templates
+  get_template       - Get template details
+  install_template   - Install template to workspace
+  publish_template   - Publish workspace as template
+
+USAGE:
+  Tools are called via the MCP protocol. The orchestrator and
+  agents use them automatically based on your requests.
+
+SEE ALSO:
+  /help agents   - How agents use these tools
+  /help commands - Slash commands available
+```

package/.claude/commands/hotfix-squad.md

@@ -0,0 +1,112 @@
+---
+description: Quick bug fix with Tanya, Simple Writer, and Svetlana
+argument-hint: "bug description"
+allowed-tools: Task, Bash
+---
+# Hotfix Squad
+
+Sequential pipeline with iterative loop: Reproduce bug, apply fix, verify, review. Loops back if review fails.
+
+**Agents:**
+1. **Tanya** - Test runner (create failing test, verify fix)
+2. **Simple Writer** - Code editor (apply minimal fix)
+3. **Svetlana** - Code review (security audit of the fix)
+
+**Goal:** $ARGUMENTS
+
+## Protocol
+
+### Step 1: Tanya (Reproduce Bug)
+
+Spawn Tanya to create a test that demonstrates the bug:
+
+```
+Task(subagent_type="agent-tanya-test-runner", prompt="Create a test that reproduces this bug: $ARGUMENTS.\n\nThe test should:\n- Fail with the current code (red)\n- Clearly demonstrate the bug\n- Be minimal and focused\n\nDo NOT fix the bug yet. Just create the failing test and report the failure.")
+```
+
+Wait for result. The test should be failing (RED state).
+
+### Step 2: Fix-Verify-Review Loop
+
+Track iteration count. Max **3 iterations** before escalating to user with remaining issues.
+
+**Set:** `iteration = 1`
+
+#### Step 2a: Simple Writer (Apply Fix)
+
+Spawn Simple Writer with accumulated context from all previous iterations:
+
+```
+Task(subagent_type="agent-simple-writer", prompt="Fix the bug in: $ARGUMENTS.\n\nContext:\nTanya created a failing test that reproduces the bug:\n[PASTE TANYA'S TEST CODE AND FAILURE OUTPUT]\n\n[IF iteration > 1: Include ALL accumulated feedback:\n- Tanya's latest test results (pass/fail details)\n- Svetlana's review feedback (if review was reached in previous iteration)\n- What was already tried and why it didn't fully work\nThis prevents repeating previous mistakes.]\n\nMake the MINIMAL change needed to make the test pass (GREEN state). Do not refactor or improve surrounding code.")
+```
+
+#### Step 2b: Tanya (Verify Fix)
+
+Run the test to confirm the fix works:
+
+```
+Task(subagent_type="agent-tanya-test-runner", prompt="Re-run the test for: $ARGUMENTS. Confirm it now passes with Simple Writer's fix. Also run any related tests to check for regressions.")
+```
+
+If tests FAIL:
+- If `iteration < 3`: increment iteration, go back to **Step 2a** with the test failure output
+- If `iteration >= 3`: escalate to user (see Step 3)
+
+#### Step 2c: Svetlana (Security Review)
+
+Tests passed. Spawn Svetlana to audit the fix:
+
+```
+Task(subagent_type="agent-svetlana-code-review", prompt="Security review of the hotfix for: $ARGUMENTS.\n\nFix applied by Simple Writer:\n[PASTE SIMPLE WRITER'S CHANGES]\n\nIteration: [iteration] of 3\n\nCheck for:\n- Security vulnerabilities\n- Data validation issues\n- Authentication/authorization concerns\n- Edge cases that could be exploited\n\nReturn verdict: APPROVED or REQUEST_CHANGES with specific issues to fix.")
+```
+
+**If APPROVED:** proceed to Step 3 (report).
+
+**If REQUEST_CHANGES:**
+- If `iteration < 3`: increment iteration, go back to **Step 2a** with Svetlana's feedback
+- If `iteration >= 3`: escalate to user (see Step 3)
+
+### Step 3: Report
+
+```markdown
+## Hotfix Squad Complete
+
+### Loop Summary
+- Iterations: [count] of 3 max
+- Final status: FIXED / ESCALATED
+
+### Tanya (Test)
+- Bug reproduced: YES
+- Test status before fix: FAILED
+- Test status after fix: PASSED / STILL FAILING
+- Regressions found: [yes/no]
+
+### Simple Writer (Fix)
+- Files modified: [list]
+- Lines changed: [count]
+- Approach: [brief description]
+
+### Svetlana (Security)
+- Verdict: APPROVED / REQUEST_CHANGES
+- Critical issues: [count]
+- Warnings: [count]
+- [If REQUEST_CHANGES: list remaining issues]
+
+### Next Steps
+[If FIXED:]
+- Deploy to staging
+- Monitor error logs
+
+[If ESCALATED after 3 iterations:]
+- Manual intervention needed
+- Remaining issues: [list from Svetlana/Tanya]
+- Attempted fixes: [summary of what was tried]
+```
+
+## Notes
+
+- RED -> GREEN -> REVIEW loop ensures quality
+- Fix must be minimal - no refactoring
+- Max 3 iterations prevents infinite loops
+- Each iteration passes previous feedback to Simple Writer so it doesn't repeat mistakes
+- Security check is mandatory before reporting success

package/.claude/commands/integration-squad.md

@@ -0,0 +1,82 @@
+---
+description: Build backend integrations with Kenji, Ivan, and Tanya
+argument-hint: "integration description"
+allowed-tools: Task, Bash, Read
+---
+# Integration Squad
+
+Sequential pipeline: Schema discovery, build integration, then verify with tests.
+
+**Agents:**
+1. **Kenji** - Schema discovery (workflow fields, types, IDs)
+2. **Ivan** - Build integration (monolith webhooks, scheduled jobs, automations)
+3. **Tanya** - Test runner (verify integration with tests)
+
+**Goal:** $ARGUMENTS
+
+## Protocol
+
+### Step 1: Kenji (Schema Discovery)
+
+Start with Kenji to gather workflow schema and field IDs needed for the integration:
+
+```
+Task(subagent_type="agent-kenji-data-reader", prompt="List all workflows and their fields relevant to: $ARGUMENTS. Include field IDs, types, and any existing integrations. Also identify webhook URLs and activity phase names needed.")
+```
+
+Wait for result. Save the schema output - Ivan needs these IDs.
+
+### Step 2: Ivan (Build Integration)
+
+Spawn Ivan with the schema context from Kenji:
+
+```
+Task(subagent_type="agent-ivan-monolith", prompt="Build a backend integration for: $ARGUMENTS.\n\nWorkflow schema from Kenji:\n[PASTE KENJI'S OUTPUT - workflow IDs, field IDs, types, phases]\n\nImplement in the hailer-integration monolith. Use correct IDs for webhooks, scheduled jobs, or automations.")
+```
+
+Wait for result. If `"status": "ready_to_push"`:
+- Run the push commands Ivan provides
+
+### Step 3: Tanya (Test Runner)
+
+Spawn Tanya to verify the integration works:
+
+```
+Task(subagent_type="agent-tanya-test-runner", prompt="Test the integration for: $ARGUMENTS.\n\nTest coverage needed:\n- Webhook payload validation (if webhook)\n- Scheduled job execution (if scheduled)\n- Activity creation/phase transitions\n- Error handling and edge cases\n\nRun tests and report pass/fail counts.")
+```
+
+Wait for result. If tests fail, report which ones and offer to have Ivan fix issues.
+
+### Step 4: Report
+
+```markdown
+## Integration Squad Complete
+
+### Kenji (Schema Discovery)
+- Workflows found: [list]
+- Fields mapped: [count]
+- Phases identified: [list]
+- Existing integrations: [list or "none"]
+
+### Ivan (Monolith Integration)
+- Integration type: [webhook/scheduled/automation]
+- Files created/modified: [list]
+- Endpoints: [list if webhook]
+- Commands run: [list]
+
+### Tanya (Tests)
+- Tests: X passed, X failed
+- Build: Pass/Fail
+- [Failed test details if any]
+
+### Next Steps
+- Deploy to staging environment
+- Test end-to-end in Hailer
+- Monitor for errors in production logs
+```
+
+## Notes
+
+- Kenji must run first to get real IDs - never let Ivan guess IDs
+- Each agent in the pipeline depends on output from the previous step
+- If tests fail, Ivan may need to revise the integration code

package/.claude/commands/janitor-squad.md

@@ -0,0 +1,167 @@
+---
+description: Deep project cleanup - code, config, and data patterns
+argument-hint: [scope or blank for full project]
+allowed-tools: Task, Bash
+---
+# Janitor Squad
+
+Deep project cleanup across code, configuration, and data. Discovers dead patterns and auto-fixes clear-cut removals.
+
+**Agents:**
+- **Lars** - Dead code detection (unused imports, unreachable code, type errors via LSP)
+- **Bjorn** - Configuration audit (deprecated fields, broken references, unused workflows)
+- **Viktor** - Data analysis (unpopulated fields, zero-activity workflows, silent insights)
+- **Simple Writer** - Auto-fix confirmed dead code and unused imports (fix loop)
+- **Code Simplifier** - Simplify complex code blocks identified during discovery (fix loop)
+
+**Target:** $ARGUMENTS (if blank, scan full project)
+
+**Changed files:** Orchestrator runs `git diff --name-only HEAD` to scope if needed.
+
+## Protocol
+
+### Step 1: Determine Scope
+
+If `$ARGUMENTS` has specific files/directories, use those as the target.
+Otherwise, scan the entire project.
+
+If `$ARGUMENTS` contains `--code-only`:
+- Skip Bjorn and Viktor
+- Only run Lars in discovery phase
+
+If `$ARGUMENTS` contains `--config-only`:
+- Skip Lars and Viktor
+- Only run Bjorn in discovery phase
+
+If `$ARGUMENTS` contains `--report-only`:
+- Skip all fix loop iterations
+- Report findings only (no auto-fixes)
+
+### Step 2: Launch Discovery Agents in Parallel
+
+**Set:** `iteration = 1`
+
+Spawn all three discovery agents simultaneously using multiple Task tool calls in a single message:
+
+**Lars:**
+```
+Task(subagent_type="agent-lars-code-inspector", prompt="Inspect the project for dead code patterns: [TARGET]. Find:\n- Unused imports\n- Unreachable code blocks\n- Unused variables and functions\n- Type errors\n\nUse LSP if available, fall back to tsc/eslint. Return detailed findings grouped by file.")
+```
+
+**Bjorn:**
+```
+Task(subagent_type="agent-bjorn-config-audit", prompt="Audit workspace configuration for zombie patterns: [TARGET]. Check:\n- Deprecated fields in workspace/fields.ts\n- Broken field references in phases\n- Unused workflows (defined but zero activities)\n- Broken enum references\n- Orphaned configuration entries\n\nReturn issues grouped by category with severity.")
+```
+
+**Viktor:**
+```
+Task(subagent_type="agent-viktor-sql-insights", prompt="Analyze data patterns in workflows: [TARGET]. Find:\n- Fields that are defined but never populated (zero values across all activities)\n- Workflows with zero activities (created but unused)\n- Insights that return empty data (broken or obsolete)\n- Calculated fields that never execute\n- Orphaned data patterns\n\nReturn findings with field IDs, workflow IDs, and impact estimates.")
+```
+
+### Step 3: Categorize Findings
+
+Collect results from all three agents. Categorize each finding as:
+
+**AUTO-FIXABLE** (Simple Writer can safely remove):
+- Unused imports identified by Lars
+- Dead code blocks with no side effects
+- Workflow definitions with zero activities (from Viktor + Bjorn)
+- Deprecated enum references (from Bjorn)
+- Never-populated fields that can be safely archived (from Viktor + Bjorn)
+
+**NEEDS-HUMAN-REVIEW** (escalate to user):
+- Architecture concerns
+- Fields that are rarely used but intentional
+- Complex logic entangled with dead code
+- Data cleanup that affects reporting history
+- Performance optimizations requiring design changes
+
+### Step 4: Auto-Fix Loop (if auto-fixable items found AND `--report-only` not set AND `iteration < 3`)
+
+If critical auto-fixable items exist, spawn two agents to clean up. If Simple Writer's fixes introduce new issues detected by re-audit, escalate remaining issues to user after max 2 iterations.
+
+**Simple Writer:**
+```
+Task(subagent_type="agent-simple-writer", prompt="Remove confirmed dead code and unused imports from the project:\n\n[LIST AUTO-FIXABLE ITEMS WITH FILE PATHS AND LINE NUMBERS]\n\nFrom Lars:\n- [Unused imports with files]\n- [Dead code blocks with files]\n\nFrom Bjorn:\n- [Deprecated enum references with files]\n- [Unused workflow definitions with IDs]\n\nFrom Viktor:\n- [Never-populated field definitions with IDs]\n\nApply minimal removals only. Do not refactor or improve beyond confirmed dead patterns.")
+```
+
+**Code Simplifier:**
+```
+Task(subagent_type="agent-code-simplifier", prompt="After dead code removal, simplify complex code blocks identified as difficult to maintain: [TARGET].\n\nFocus on:\n- Variable naming clarity\n- Function complexity reduction\n- Comment clarity around remaining logic\n- Code organization in affected files\n\nReturn refactoring suggestions with before/after examples.")
+```
+
+After both finish:
+- Increment `iteration`
+- Go back to **Step 2** to re-run all discovery agents
+- On re-discovery, tell agents to verify previous issues are resolved
+- Max 2 re-check iterations (3 total discovery runs)
+
+### Step 5: Report
+
+```markdown
+## Janitor Squad Report
+
+### Loop Summary
+- Discovery iterations: [count]
+- Auto-fixes applied: [yes/no]
+- Items removed: [count by category]
+
+### Lars (Dead Code Detection)
+- Unused imports: X (Y auto-removed)
+- Dead code blocks: X (Y auto-removed)
+- Type errors: X
+- [Remaining issues grouped by file]
+
+### Bjorn (Config Audit)
+- Deprecated fields: X
+- Broken references: X (Y auto-removed)
+- Unused workflows: X (Y auto-removed)
+- Orphaned config: X
+- [Remaining issues grouped by category]
+
+### Viktor (Data Analysis)
+- Never-populated fields: X (Y marked for archival)
+- Zero-activity workflows: X (Y removed)
+- Silent insights: X
+- Orphaned data patterns: X
+- [Remaining items grouped by workflow]
+
+### Auto-Fixes Applied
+[If any fixes were made:]
+- [File/ID]: [what was removed/archived]
+- [File/ID]: [what was removed/archived]
+
+### Remaining Issues (Manual Action Needed)
+[Issues that require human review]
+- [Category]: [Details]
+
+### Recommended Cleanup Order
+1. [Remove these orphaned items first]
+2. [Archive these fields next]
+3. [Review these design concerns]
+
+### Summary
+[Overall health assessment]
+[Estimated time to apply remaining cleanup]
+```
+
+If any agent fails or times out, report partial results from successful agents, note which failed, and offer to re-run individually.
+
+## Options
+
+| Flag | Effect |
+|------|--------|
+| `--code-only` | Skip Bjorn and Viktor, just code cleanup via Lars |
+| `--config-only` | Skip Lars and Viktor, just workspace config audit via Bjorn |
+| `--report-only` | Report findings only, no auto-fix loop (discovery phase only) |
+| `--bg` | Run all discovery agents in background mode |
+
+If `--bg` is present, launch all discovery agents with `run_in_background: true` and tell the user they'll be notified when discovery is complete, then proceed with fix loop when they're ready.
+
+## Notes
+
+- Max 2 re-discovery iterations (3 total) to prevent infinite loops
+- Simple Writer only removes clear-cut dead code - ambiguous items go to user review
+- Data cleanup (Viktor findings) may affect reports/history - always prompt user before removal
+- Each re-discovery is a full parallel sweep across all enabled agents
+- The `--report-only` flag gives discovery results without auto-fixes

package/.claude/commands/learn-auto.md

@@ -0,0 +1,120 @@
+---
+description: Scan conversation for learnings and capture to inbox
+argument-hint: [optional focus area]
+---
+# Auto-Learn
+
+Scan conversation for potential learnings, present for confirmation, write to inbox.
+
+## Trigger Patterns
+
+Scan conversation for these signals:
+
+### 1. Error → Fix Sequences
+```
+Pattern: Error/failure message followed by successful resolution
+Signal: "Error:", "failed", "doesn't work" → later "fixed", "working now", "solved"
+Extract: What was wrong, what fixed it
+```
+
+### 2. User Corrections
+```
+Pattern: User corrects agent output or approach
+Signal: "No, it should be...", "Actually, use...", "That's wrong, do..."
+Extract: Wrong approach, correct approach
+```
+
+### 3. Explicit Learning Signals
+```
+Pattern: User explicitly notes something important
+Signal: "Good to know", "I'll remember that", "Important:", "Note to self"
+Extract: The insight
+```
+
+### 4. Agent Failures
+```
+Pattern: Agent returned error or wrong result
+Signal: "status": "error", validation failures, user says "that's not right"
+Extract: What failed, why, how to prevent
+```
+
+### 5. Repeated Attempts
+```
+Pattern: Same operation tried multiple times before success
+Signal: 2+ similar tool calls, retries with different parameters
+Extract: What didn't work, what finally worked
+```
+
+## Instructions
+
+### Step 1: Scan Conversation
+
+Review the conversation for patterns above. For each potential learning, note:
+- **Type**: error-fix | correction | insight | agent-failure | retry-pattern
+- **Context**: What was happening
+- **Learning**: The key takeaway
+- **Category**: agent/X | skill/X | pattern | gotcha | bug
+
+### Step 2: Present Findings
+
+If learnings found, present to user:
+
+```
+Found [N] potential learnings from this session:
+
+1. [agent/kenji] Field lookup should check enums.ts first
+   Context: Kenji made API call when data was available locally
+
+2. [pattern] Date fields from Hailer come pre-formatted
+   Context: Tried to format already-formatted date, got wrong output
+
+3. [gotcha] Push must complete before pull
+   Context: Pull overwrote local changes
+
+Confirm which to save? (all / 1,2 / none)
+```
+
+Use AskUserQuestion:
+- "Save all"
+- "Select specific (enter numbers)"
+- "Skip - nothing worth saving"
+
+### Step 3: Write to Inbox
+
+For confirmed learnings, append to `inbox.md`:
+
+```markdown
+## Pending
+
+- [<category>] <learning description> _(from: <project>, <date>, auto-learn)_
+```
+
+If in hub repo (hailer-claude-reference), write directly to `inbox.md`.
+If in project repo, write to `docs/learnings.md` or project's inbox location.
+
+### Step 4: Report
+
+```
+Captured [N] learnings to inbox:
+- [agent/kenji] Field lookup should check enums.ts first
+- [pattern] Date fields from Hailer come pre-formatted
+
+Review later with /learn to apply fixes, or let Ada auto-process.
+```
+
+## No Learnings Found
+
+If conversation has no clear learnings:
+
+```
+No obvious learnings detected in this session.
+
+To capture something manually: /learn <category> <description>
+```
+
+## Notes
+
+- This is DETECTION only - doesn't apply fixes (that's /learn or Ada's job)
+- User confirms before anything is saved
+- Bias toward false negatives (miss some) rather than false positives (noise)
+- Works best at end of session when there's context to analyze

package/.claude/commands/learn.md

@@ -0,0 +1,120 @@
+---
+description: Capture learning and apply fix to the right place
+argument-hint: <category> <description>
+---
+# Learn & Apply
+
+Capture a learning, ask clarifying questions, then apply the fix to the right place.
+
+## Usage
+`/learn <category> <description>`
+
+## Categories
+- `agent/<name>` - Agent behavior issue (e.g., `agent/kenji`)
+- `skill/<name>` - Skill missing pattern (e.g., `skill/function-fields`)
+- `pattern` - General pattern to document
+- `bug` - Bug in code/config
+- `gotcha` - Common mistake to prevent
+
+## Examples
+```
+/learn agent/kenji should check enums.ts before API calls
+/learn skill/insights JOIN syntax was wrong for linked fields
+/learn pattern always verify push succeeded before continuing
+/learn gotcha phase IDs change when workflow is copied
+```
+
+## Instructions
+
+### Step 1: Parse & Understand
+
+Parse the input:
+- Category: first word (e.g., `agent/kenji`)
+- Description: rest of the text
+
+### Step 2: Ask Clarifying Questions
+
+Use AskUserQuestion to gather details:
+
+**For agent issues:**
+- "What was the symptom?" (wrong output, error, missed step)
+- "What should the agent do differently?"
+- "Should this be a rule, a skill addition, or both?"
+
+**For skill issues:**
+- "What was missing or wrong?"
+- "Can you give an example of correct vs incorrect?"
+
+**For patterns/gotchas:**
+- "What went wrong when this wasn't followed?"
+- "Where should this be documented?" (skill, agent, CLAUDE.md)
+
+### Step 3: Determine Target
+
+Based on category and answers, decide where the fix goes:
+
+| Category | Likely Target |
+|----------|---------------|
+| `agent/X` | `.claude/agents/agent-X.md` |
+| `skill/X` | `.claude/skills/X/SKILL.md` |
+| `pattern` | Relevant skill or CLAUDE.md |
+| `bug` | Code fix + possibly skill |
+| `gotcha` | Skill or agent rules section |
+
+### Step 4: Apply the Fix
+
+**Option A: Direct edit (if simple)**
+- Edit the target file directly
+- Add to appropriate section (rules, patterns, examples)
+
+**Option B: Delegate to Ada (if complex)**
+For complex changes, invoke Ada agent:
+```
+Task(subagent_type="agent-ada-skill-builder", prompt={
+  "task": "apply_learning",
+  "category": "<category>",
+  "learning": "<description>",
+  "details": "<clarification answers>",
+  "target": "<determined target>"
+})
+```
+
+### Step 5: Log & Confirm
+
+1. Log to `docs/learnings.md` for history:
+   ```markdown
+   - [<category>] <description> → Applied to <target> _(YYYY-MM-DD)_
+   ```
+
+2. Report what was done:
+   ```
+   Learning applied:
+   - Category: agent/kenji
+   - Fix: Added rule "Check enums.ts before making API calls"
+   - Location: .claude/agents/agent-kenji-data-reader.md
+   ```
+
+## File Template
+
+If creating `docs/learnings.md`:
+
+```markdown
+# Applied Learnings
+
+History of fixes applied from learnings.
+
+---
+
+## Log
+
+- [agent/kenji] Check enums.ts first → Added to rules _(2026-01-31)_
+- [skill/insights] JOIN syntax example → Added to SKILL.md _(2026-01-31)_
+```
+
+## Notes
+
+- This command APPLIES fixes, not just logs them
+- Ask questions to understand the real issue
+- Small fixes: edit directly
+- Complex fixes: delegate to Ada
+- Always log what was done for history