@hailer/mcp 1.1.16 → 1.1.17-beta.0

package/.claude/skills/insight-join-patterns/SKILL.md

@@ -1,174 +0,0 @@
----
-name: insight-join-patterns
-description: Correct JOIN syntax for Hailer insights with ActivityLink fields
-version: 1.0.0
-triggers: JOIN query errors, missing columns, NULL results in insight queries
----
-
-**Prerequisite:** Before using JOINs, review `SDK-insight-queries` skill for basic insight syntax and single-workflow queries.
-
-<problem>
-When joining workflows with ActivityLink fields in Hailer insights, you must:
-1. Include `_id` meta field in BOTH source definitions
-2. Join ON the activitylink field value equals target _id
-3. Use the activitylink fieldId (NOT the key) for the JOIN condition
-</problem>
-
-<rules>
-- Both workflows need `{ name: 'id', meta: '_id' }` in their fields array
-- JOIN condition: `source1.activityLinkFieldName = source2.id`
-- Use LEFT JOIN for optional relationships (activitylink can be null)
-- Use INNER JOIN only when relationship must exist
-</rules>
-
-<correct>
-```javascript
-// Players workflow has "club" field (activitylink to Clubs workflow)
-{
-  sources: [
-    {
-      name: 'p',
-      workflowId: '68446dc05b30685f67c6fcd4',
-      fields: [
-        { name: 'player_name', meta: 'name' },
-        { name: 'id', meta: '_id' },              // Required!
-        { name: 'club', fieldId: '684d5e45...' }  // ActivityLink field
-      ]
-    },
-    {
-      name: 'c',
-      workflowId: '691ea936ccb6bdeebc0cbf77',
-      fields: [
-        { name: 'club_name', meta: 'name' },
-        { name: 'id', meta: '_id' }               // Required!
-      ]
-    }
-  ],
-  query: 'SELECT p.player_name, c.club_name FROM p LEFT JOIN c ON p.club = c.id'
-}
-```
-</correct>
-
-<wrong>
-```javascript
-// ❌ WRONG - Missing _id in clubs source
-{
-  sources: [
-    {
-      name: 'p',
-      workflowId: 'players-id',
-      fields: [
-        { name: 'player_name', meta: 'name' },
-        { name: 'id', meta: '_id' },
-        { name: 'club', fieldId: 'club-field-id' }
-      ]
-    },
-    {
-      name: 'c',
-      workflowId: 'clubs-id',
-      fields: [
-        { name: 'club_name', meta: 'name' }
-        // Missing: { name: 'id', meta: '_id' }
-      ]
-    }
-  ],
-  query: 'SELECT p.player_name, c.club_name FROM p LEFT JOIN c ON p.club = c.id'
-}
-// Error: "no such column: c.id"
-```
-</wrong>
-
-<examples>
-### Three-Way JOIN (Tasks -> Topics -> Projects)
-```javascript
-{
-  sources: [
-    {
-      name: 't',
-      workflowId: 'tasks-workflow-id',
-      fields: [
-        { name: 'task_name', meta: 'name' },
-        { name: 'id', meta: '_id' },
-        { name: 'topic', fieldId: 'topic-field-id' }
-      ]
-    },
-    {
-      name: 'top',
-      workflowId: 'topics-workflow-id',
-      fields: [
-        { name: 'topic_name', meta: 'name' },
-        { name: 'id', meta: '_id' },
-        { name: 'project', fieldId: 'project-field-id' }
-      ]
-    },
-    {
-      name: 'p',
-      workflowId: 'projects-workflow-id',
-      fields: [
-        { name: 'project_name', meta: 'name' },
-        { name: 'id', meta: '_id' }
-      ]
-    }
-  ],
-  query: `
-    SELECT t.task_name, top.topic_name, p.project_name
-    FROM t
-    LEFT JOIN top ON t.topic = top.id
-    LEFT JOIN p ON top.project = p.id
-  `
-}
-```
-
-### Aggregation with JOIN
-```javascript
-{
-  sources: [
-    {
-      name: 'matches',
-      workflowId: 'matches-workflow-id',
-      fields: [
-        { name: 'match_date', fieldId: 'date-field-id' },
-        { name: 'id', meta: '_id' },
-        { name: 'home_team', fieldId: 'home-team-field-id' }
-      ]
-    },
-    {
-      name: 'teams',
-      workflowId: 'teams-workflow-id',
-      fields: [
-        { name: 'team_name', meta: 'name' },
-        { name: 'id', meta: '_id' }
-      ]
-    }
-  ],
-  query: `
-    SELECT teams.team_name, COUNT(*) as match_count
-    FROM matches
-    LEFT JOIN teams ON matches.home_team = teams.id
-    GROUP BY teams.team_name
-  `
-}
-```
-</examples>
-
-<troubleshooting>
-**Error: "no such column: c.id"**
-- Missing `{ name: 'id', meta: '_id' }` in target workflow source
-
-**Error: "no such column: p.club"**
-- ActivityLink field not included in source fields array
-- Check you used correct fieldId from `get_workflow_schema`
-
-**NULL results for joined data**
-- ActivityLink field is empty/null for some activities (expected with LEFT JOIN)
-- Use INNER JOIN if you only want activities with relationships
-</troubleshooting>
-
-<checklist>
-Before creating an insight with JOINs:
-- [ ] Both workflow sources include `{ name: 'id', meta: '_id' }`
-- [ ] ActivityLink field uses `fieldId` (NOT `key`)
-- [ ] JOIN condition uses column names from sources (e.g., `p.club = c.id`)
-- [ ] Using LEFT JOIN (unless relationship required)
-- [ ] Tested with `preview_insight` first
-</checklist>

package/.claude/skills/json-only-output/SKILL.md

@@ -1,72 +0,0 @@
----
-name: json-only-output
-description: Fix agents adding prose after JSON responses
-version: 1.0.1
-triggers: Agent outputs explanation text after valid JSON
----
-
-# JSON Only Output
-
-<purpose>
-Ensure agents output ONLY valid JSON with no prose, explanations, or commentary after the closing brace.
-</purpose>
-
-<why-this-happens>
-## Why Agents Add Prose
-
-LLMs have a natural tendency to be helpful and explanatory. After completing a task, they want to:
-- Explain what they did
-- Suggest next steps
-- Provide context
-- Confirm their understanding
-
-This is normally good behavior, but for **subagents** returning structured data to an orchestrator, it breaks JSON parsing.
-
-**The `<protocol>` section isn't enough** because:
-- LLMs treat protocol as "guidelines" not hard rules
-- The helpful instinct overrides weak instructions
-- Protocol is at the end of the prompt, less salient
-
-**Why identity/rules work:**
-- `<identity>` shapes the agent's core persona ("I output JSON. Full stop.")
-- `<rules>` are processed as constraints, not suggestions
-- Positioned early in prompt, higher salience
-- Explicit prohibition is stronger than implicit expectation
-</why-this-happens>
-
-<patterns>
-## Pattern 1: Stop at the Closing Brace
-
-Output JSON. Full stop. Nothing after the closing brace.
-
-## Pattern 2: Agent Configuration Fix
-
-1. Add to `<identity>`: "Output JSON. Full stop."
-2. Add to `<rules>`: **JSON ONLY** - Output closing brace, then STOP. Zero prose after JSON.
-3. Protocol section is NOT enough - agents ignore it without identity/rules reinforcement.
-
-## Pattern 3: Include Summary Inside JSON
-
-If context is helpful, include it IN the JSON `summary` field, not after the JSON.
-</patterns>
-
-<examples>
-## Example 1: Correct - Pure JSON Output
-
-```json
-{"status":"success","result":{"fields":["taskName","priority"]},"summary":"Read 2 fields"}
-```
-**STOP HERE. Nothing after closing brace.**
-
-## Example 2: Wrong - Prose After JSON
-
-```json
-{"status":"success","result":{"fields":["taskName","priority"]},"summary":"Read 2 fields"}
-```
-
-The workflow has 2 fields defined in workspace/Tasks_123/fields.ts. You can now use these field IDs with dmitri for activity creation.
-
-**Action Required**: Run `npm run pull` to refresh.
-
-This violates JSON-only protocol by adding explanation text AFTER the valid JSON response.
-</examples>

package/.claude/skills/mcp-direct-tools/SKILL.md

@@ -1,153 +0,0 @@
----
-name: mcp-direct-tools
-description: Reference for MCP tools not assigned to agents
-version: 1.0.0
----
-
-# MCP Direct Tools
-
-<purpose>
-Reference for MCP tools not assigned to agents. Load this skill when user requests direct tool usage or needs capabilities not covered by standard agents.
-</purpose>
-
----
-
-## When to Load This Skill
-
-- User asks "can you use the bug fixer tools?"
-- User needs capabilities not covered by agents
-- Direct MCP tool access requested
-- Debugging/testing MCP tools
-
----
-
-## Bug Fixer Tools (16 tools)
-
-Automated bug fixing suite for Hailer apps. Use these for automated debugging workflows.
-
-### Discovery & Analysis
-
-| Tool | Description | Parameters |
-|------|-------------|------------|
-| `bug_fixer_find_app` | Locate app by name | `{ appName }` |
-| `bug_fixer_analyze_bug` | Classify bug report | `{ bugReport, appId }` |
-
-### File Operations
-
-| Tool | Description | Parameters |
-|------|-------------|------------|
-| `bug_fixer_list_files` | List project files | `{ appId, path? }` |
-| `bug_fixer_read_file` | Read file content | `{ appId, filePath }` |
-| `bug_fixer_write_file` | Modify file content | `{ appId, filePath, content }` |
-| `bug_fixer_apply_fix` | Apply code patch | `{ appId, filePath, patch }` |
-
-### Build & Test
-
-| Tool | Description | Parameters |
-|------|-------------|------------|
-| `bug_fixer_run_build` | Execute build command | `{ appId }` |
-
-### Git Operations
-
-| Tool | Description | Parameters |
-|------|-------------|------------|
-| `bug_fixer_git_status` | Check git status | `{ appId }` |
-| `bug_fixer_git_pull` | Fetch latest code | `{ appId }` |
-| `bug_fixer_git_commit` | Commit changes | `{ appId, message }` |
-| `bug_fixer_git_push` | Push to remote | `{ appId }` |
-| `bug_fixer_git_revert` | Undo changes | `{ appId }` |
-
-### Workflow Management
-
-| Tool | Description | Parameters |
-|------|-------------|------------|
-| `bug_fixer_start_fix` | Begin fix workflow | `{ bugId, appId }` |
-| `bug_fixer_mark_declined` | Close as not-a-bug | `{ bugId, reason }` |
-| `bug_fixer_publish_fix` | Deploy to production | `{ appId, version }` |
-| `bug_fixer_retry_fix` | Attempt with new context | `{ bugId, newContext }` |
-
-### Bug Fixer Workflow
-
-```
-1. bug_fixer_find_app → Get app ID
-2. bug_fixer_analyze_bug → Classify issue
-3. bug_fixer_start_fix → Begin workflow
-4. bug_fixer_list_files → Find relevant files
-5. bug_fixer_read_file → Understand current code
-6. bug_fixer_write_file / bug_fixer_apply_fix → Make changes
-7. bug_fixer_run_build → Verify fix
-8. bug_fixer_git_commit → Save changes
-9. bug_fixer_publish_fix → Deploy
-```
-
----
-
-## Insight Tools (Not in Viktor)
-
-Viktor uses `preview_insight` and `get_insight_data`. These additional tools are available:
-
-| Tool | Description | When to Use |
-|------|-------------|-------------|
-| `list_insights` | List all insights in workspace | Discovery, cleanup |
-| `update_insight` | Modify existing insight | Query changes |
-| `remove_insight` | Delete insight (NUCLEAR) | Cleanup |
-
-**Note:** SDK has equivalents via insights.ts push. Use SDK for version-controlled changes, MCP for quick fixes.
-
----
-
-## Workflow Tools (PLAYGROUND/NUCLEAR)
-
-Direct workflow manipulation. Normally use Helga + SDK, but these exist for quick operations:
-
-| Tool | Description | Group |
-|------|-------------|-------|
-| `install_workflow` | Create workflow via MCP | PLAYGROUND |
-| `remove_workflow` | Delete workflow | NUCLEAR |
-| `update_workflow_field` | Modify field config | PLAYGROUND |
-| `update_workflow_phase` | Modify phase config | PLAYGROUND |
-| `test_function_field` | Test JS function | PLAYGROUND |
-
-**Warning:** NUCLEAR tools require `ENABLE_NUCLEAR_TOOLS=true` in MCP config.
-
----
-
-## Tool Groups Reference
-
-| Group | Risk Level | Examples |
-|-------|------------|----------|
-| READ | Safe | list_activities, get_workflow_schema |
-| WRITE | Updates data | create_activity, add_discussion_message |
-| PLAYGROUND | Admin ops | install_workflow, update_workflow_field |
-| NUCLEAR | Destructive | remove_workflow, remove_app |
-| BOT_INTERNAL | Bots only | Not exposed to MCP clients |
-
----
-
-## Usage Pattern
-
-When user requests direct tool usage:
-
-```
-User: "Use the bug fixer to fix this app"
-
-Orchestrator:
-1. Load this skill
-2. Call tools directly via mcp__hailer__<tool_name>
-3. Follow workflow patterns above
-4. Report results
-```
-
----
-
-## Tools NOT Covered Here
-
-These are assigned to agents - use the agent instead:
-
-| Tool | Agent |
-|------|-------|
-| Activity CRUD | Dmitri |
-| Discussions | Yevgeni |
-| App scaffold/create | Giuseppe |
-| Insights preview/data | Viktor |
-| User search | Permissions Handler |

package/.claude/skills/optional-parameters/SKILL.md

@@ -1,72 +0,0 @@
----
-name: optional-parameters
-description: Omit optional parameters instead of passing empty values
-version: 1.0.0
-triggers: Tool error about empty array/string when parameter should be omitted
----
-
-# Optional Parameters
-
-<purpose>
-Teach correct handling of optional tool parameters - OMIT them entirely when not needed, rather than passing empty arrays, strings, or null values.
-</purpose>
-
-<patterns>
-## Pattern 1: Omit vs Empty Value
-
-**Key distinction:**
-- **OMIT parameter**: Don't include it in the function call at all
-- **NOT same as empty value**: `[]`, `""`, `null`, `undefined` are NOT valid replacements for omission
-
-## Pattern 2: When to Omit
-
-- Updating insight public/name but NOT sources → omit sources
-- Updating activity field but NOT name → omit name
-- Any "required" schema parameter that's not relevant to current operation
-
-## Pattern 3: Rule of Thumb
-
-If you're not changing/using a value, OMIT the parameter entirely rather than passing empty/null.
-</patterns>
-
-<examples>
-## Example 1: Correct - Omitting Unused Parameters
-
-```typescript
-// Update insight - only changing public flag
-// sources parameter exists in schema but NOT needed for this update
-update_insight({
-  insightId: "abc123",
-  public: false
-  // sources: NOT included - omit entirely
-});
-
-// Update insight - changing sources
-update_insight({
-  insightId: "abc123",
-  sources: [{
-    name: 'tasks',
-    workflowId: 'wf123',
-    fields: [{ name: 'title', meta: 'name' }]
-  }]
-  // Include sources when actually updating them
-});
-```
-
-## Example 2: Wrong - Passing Empty Values
-
-```typescript
-// WRONG - Passing empty array when parameter should be omitted
-update_insight({
-  insightId: "abc123",
-  public: false,
-  sources: []  // Error: sources must contain at least 1 items
-});
-
-// WRONG - Passing empty string
-update_activity({
-  activityId: "xyz",
-  name: ""  // Error: name cannot be empty
-});
-```
-</examples>

package/.claude/skills/tool-parameter-usage/SKILL.md

@@ -1,126 +0,0 @@
----
-name: tool-parameter-usage
-description: Extract IDs from context and use correct parameter formats for Hailer tools
-version: 1.1.0
-triggers: Tool validation failed with "Required" error, empty receivedArgs, or field format errors
----
-
-# Tool Parameter Usage
-
-<purpose>
-Teach correct extraction of IDs from message context and proper parameter formats for Hailer tool calls, preventing empty parameter errors and format mismatches.
-</purpose>
-
-<patterns>
-## Pattern 1: Context Extraction
-
-The `<incoming>` tag in messages contains critical IDs. ALWAYS extract and use them:
-
-```xml
-<incoming activityId="69384669b7826c5d9ec4e07c" discussionId="69384669b7826c5d9ec4e07d">
-  User message here
-</incoming>
-```
-
-**Extract before calling tools:**
-- `activityId` → use for `show_activity_by_id`, `update_activity`
-- `discussionId` → use for `get_activity_from_discussion`, `add_discussion_message`
-
-## Pattern 2: Single vs Bulk Mode Parameters
-
-| Tool | Single mode | Bulk mode |
-|------|-------------|-----------|
-| `create_activity` | Top-level `name`, `phaseId`, `teamId`, `fields` | Inside each `activities[]` item |
-| `update_activity` | `activityId` | `activities[]._id` |
-| `show_activity_by_id` | `activityId` | N/A |
-| `get_activity_from_discussion` | `discussionId` | N/A |
-
-**CRITICAL for `create_activity` bulk mode:** `teamId`, `phaseId`, and `fields` must be **inside each activity object** in the `activities[]` array. Top-level values (except `workflowId`) are IGNORED in bulk mode. This causes "Missing team(s)" (code 127) if teamId is only at the top level.
-
-## Pattern 3: Field Value Formats
-
-| Field type | Value format |
-|------------|--------------|
-| `numericunit` | Plain number: `78` |
-| `text` | Plain string: `"hello"` |
-| `activitylink` | Activity ID string: `"abc123..."` |
-| `select` | Option key: `"option_key"` |
-
-**Never pass objects with `type` metadata** - Hailer API expects plain values.
-</patterns>
-
-<examples>
-## Example 1: Correct - Extracting IDs from Context
-
-```typescript
-// Context: <incoming activityId="69384669b7826c5d9ec4e07c" discussionId="69384669b7826c5d9ec4e07d">
-
-// CORRECT - Extract activityId from context
-show_activity_by_id({
-  activityId: "69384669b7826c5d9ec4e07c"
-});
-
-// CORRECT - Get activity from discussion
-get_activity_from_discussion({
-  discussionId: "69384669b7826c5d9ec4e07d"
-});
-```
-
-## Example 2: Correct - Single vs Bulk Update Mode
-
-```typescript
-// CORRECT - Single update mode uses activityId
-update_activity({
-  activityId: "69384669b7826c5d9ec4e07c",
-  fields: { "fieldId123": 78 }
-});
-
-// CORRECT - Bulk update mode uses _id (NOT activityId)
-update_activity({
-  activities: [{
-    _id: "69384669b7826c5d9ec4e07c",
-    fields: { "fieldId123": 78 }
-  }]
-});
-```
-
-## Example 3: Correct - Field Value Formats
-
-```typescript
-// CORRECT - numericunit field = plain number
-update_activity({
-  activityId: "69384669b7826c5d9ec4e07c",
-  fields: { "weightFieldId": 78 }
-});
-```
-
-## Example 4: Wrong - Common Errors
-
-```typescript
-// WRONG - Empty parameters (ignoring context)
-show_activity_by_id({});
-// Error: activityId: Required, receivedArgs={}
-
-// WRONG - Using activityId in bulk mode (should be _id)
-update_activity({
-  activities: [{
-    activityId: "69384669b7826c5d9ec4e07c",  // WRONG KEY
-    fields: { "fieldId123": 78 }
-  }]
-});
-// Error: activities.0._id: Required
-
-// WRONG - Passing object for numericunit field
-update_activity({
-  activityId: "69384669b7826c5d9ec4e07c",
-  fields: {
-    "weightFieldId": { "type": "numericunit", "value": 78 }  // WRONG FORMAT
-  }
-});
-// Error: "Weight" must be a number
-
-// WRONG - Empty list_activities call
-list_activities({});
-// Error: workflowId: Required, phaseId: Required
-```
-</examples>

package/.claude/skills/tool-response-verification/SKILL.md

@@ -1,92 +0,0 @@
----
-name: tool-response-verification
-description: Verify MCP tool execution results before reporting success
-version: 1.0.0
-triggers:
-  - MCP tool failure
-  - fabricated response
-  - tool result verification
-  - silent failure
-  - disconnected server
----
-
-# Tool Response Verification
-
-<purpose>
-Ensure agents verify actual tool execution results before reporting success, preventing fabricated responses when MCP servers are disconnected or tools fail silently.
-</purpose>
-
-<patterns>
-## Pattern 1: Always Check Tool Results
-
-Every MCP tool call returns a result. Read it before proceeding.
-
-## Pattern 2: Never Assume Success
-
-If you didn't see confirmation in the result, it didn't happen.
-
-## Pattern 3: Report Actual Errors
-
-If tool returned error, report error status - don't fabricate success.
-
-## Pattern 4: No Fabrication
-
-Never claim "created 5 activities" if you didn't see 5 activity IDs returned.
-
-## Pattern 5: Verification Checklist
-
-Before returning success:
-- Did the tool return a result (not an error)?
-- Does the result contain expected data (IDs, counts, etc.)?
-- Am I reporting data FROM the result, not data I expected?
-
-## Pattern 6: Detect MCP Connection Errors
-
-When an MCP server is offline, tools return empty results, undefined data, or error messages instead of clear failures. This looks like "success" but is actually a connection problem.
-
-**Red flags:**
-- Empty array when data is expected (e.g., `workflows: []` for a non-empty workspace)
-- Missing schema fields that should always be present
-- Undefined/null responses from tools that normally return structured data
-- Error messages containing: "connection", "ECONNREFUSED", "timeout", "unavailable", "ENOTFOUND"
-
-**What to do:**
-Instead of reporting empty data as success, report: "MCP server appears offline - tool returned empty/error result. Check that the MCP server is running."
-
-Return error status, not success:
-```json
-{
-  "status": "error",
-  "result": { "tool": "tool_name", "error": "MCP server appears offline" },
-  "summary": "Cannot proceed: MCP server not responding"
-}
-```
-</patterns>
-
-<examples>
-## Example 1: Correct - Verify Before Reporting
-
-```
-GOOD: Call create_activity → read result → if result.activityId exists → return success
-GOOD: "Created customer with ID abc123" (ID from actual result)
-```
-
-## Example 2: Wrong - Fabricating Success
-
-```
-BAD: Call create_activity → immediately return {"status": "success", "created": 1}
-BAD: "I created the customer" (without checking result)
-```
-
-## Example 3: Correct - Error Reporting
-
-When tools fail, report the actual error:
-
-```json
-{
-  "status": "error",
-  "result": { "tool": "tool_name", "error": "actual error message" },
-  "summary": "Tool failed: brief reason"
-}
-```
-</examples>