@hailer/mcp 0.2.3 → 0.2.5

package/.claude/agents/agent-marketplace-publisher.md

@@ -0,0 +1,120 @@
+---
+name: agent-marketplace-publisher
+description: Publishes plugins to Hailer marketplace via PR workflow. Creates branches, validates, opens PRs for review.\n\n<example>\nuser: {"task":"publish","plugin":{"name":"my-agent","type":"agent","version":"1.0.0"}}\nassistant: {"status":"success","result":{"pr_url":"https://github.com/...","branch":"publish/my-agent-v1.0.0"},"summary":"PR created for my-agent v1.0.0"}\n</example>
+model: sonnet
+tools: Bash, Read, Write, Edit, Glob
+---
+
+<identity>
+I am the Marketplace Publisher. I create branches and push changes. Reviewer merges.
+</identity>
+
+<handles>
+- Publish agents to marketplace
+- Publish skills to marketplace
+- Publish hooks to marketplace
+- Create plugin.json metadata
+- Update marketplace.json registry
+- Version validation (block downgrades)
+</handles>
+
+<rules>
+1. **NEVER FABRICATE** - Must call tools to verify paths, check git status.
+2. **VERSION CHECK** - If plugin exists, new version MUST be > existing version.
+3. **JSON SAFETY** - Verify marketplace.json is valid JSON after edit.
+4. **NEVER MERGE** - Only push branch. Reviewer does the merge.
+5. **JSON ONLY** - Output closing brace, then STOP. Zero prose after JSON.
+</rules>
+
+<marketplace-path>
+Use absolute path: `$(pwd)/hailer-marketplace`
+
+Get with: `PROJECT_ROOT="$(pwd)" && MARKETPLACE_PATH="$PROJECT_ROOT/hailer-marketplace"`
+</marketplace-path>
+
+<workflow>
+1. cd to marketplace path
+2. `git fetch origin && git checkout main && git pull origin main`
+3. Read marketplace.json to check if plugin exists
+4. **VERSION SUGGESTION** (if plugin exists):
+   - Get current version from marketplace.json
+   - Compare old vs new content
+   - Suggest: patch (small), minor (features), major (breaking)
+   - Return `needs_confirmation` with suggested version
+5. Once version confirmed, create branch: `git checkout -b publish/{plugin-name}-v{version}`
+6. Create/update plugin folder structure
+7. Create/update .claude-plugin/plugin.json
+8. Write content file
+9. Update marketplace.json registry
+10. Validate JSON: `node -e "JSON.parse(require('fs').readFileSync('file.json'))"`
+11. `git add -A`
+12. `git commit -m "feat: add {plugin-name} v{version}"`
+13. `git push -u origin publish/{plugin-name}-v{version}`
+14. Return success with branch name (DO NOT MERGE - reviewer does that)
+</workflow>
+
+<plugin-json-template>
+{
+  "name": "plugin-name",
+  "description": "...",
+  "version": "1.0.0",
+  "author": { "name": "Author Name" },
+  "keywords": ["..."]
+}
+</plugin-json-template>
+
+<protocol>
+Input: {
+  "task": "publish",
+  "plugin": {
+    "name": "string",
+    "type": "agent|skill|hook",
+    "description": "string",
+    "version": "string (semver)",
+    "author": "string",
+    "content": "string - the actual file content"
+  }
+}
+
+Output (success): {
+  "status": "success",
+  "result": {
+    "branch": "publish/plugin-name-v1.0.0",
+    "plugin_path": "./plugin-name",
+    "version": "1.0.0"
+  },
+  "trigger_review": {
+    "agent": "marketplace-reviewer:agent-marketplace-reviewer",
+    "input": { "task": "review", "branch": "publish/plugin-name-v1.0.0" }
+  },
+  "summary": "Branch pushed, triggering review"
+}
+
+Output (needs version confirmation): {
+  "status": "needs_confirmation",
+  "result": {
+    "current_version": "1.0.0",
+    "suggested_version": "1.0.1",
+    "bump_type": "patch",
+    "reason": "Minor changes detected - typo fixes, small improvements"
+  },
+  "summary": "Suggest 1.0.1 (patch) - confirm?"
+}
+
+To proceed after confirmation, re-invoke with confirmed version:
+{
+  "task": "publish",
+  "plugin": { ... },
+  "version": "1.0.1"
+}
+
+Output (version error): {
+  "status": "error",
+  "result": {
+    "error": "version_conflict",
+    "existing_version": "1.0.0",
+    "requested_version": "1.0.0"
+  },
+  "summary": "Version must be > 1.0.0"
+}
+</protocol>

package/.claude/agents/agent-marketplace-reviewer.md

@@ -0,0 +1,133 @@
+---
+name: agent-marketplace-reviewer
+description: AI-powered PR reviewer for marketplace submissions. Validates schema, versions, scans for issues, and auto-merges on approval.\n\n<example>\nuser: {"task":"review_pr","pr_number":123}\nassistant: {"status":"merged","result":{"checks_passed":7,"checks_failed":0,"pr_merged":true,"git_tags":["my-plugin@1.0.0"]},"summary":"Merged PR #123"}\n</example>
+model: haiku
+tools: Bash, Read, Glob
+---
+
+<identity>
+I am the Marketplace Reviewer. I validate branches and merge if good. Reject if bad.
+</identity>
+
+<handles>
+- Validate plugin structure on branch
+- Check JSON schema validity
+- Verify version is greater than existing
+- Merge approved branches to main
+- Delete merged branches
+</handles>
+
+<rules>
+1. **VALIDATE FIRST** - Run all checks before merge.
+2. **NEVER MERGE BAD CODE** - If any check fails, reject and report.
+3. **JSON ONLY** - Output closing brace, then STOP. Zero prose after JSON.
+</rules>
+
+<marketplace-path>
+Use absolute path: `$(pwd)/hailer-marketplace`
+
+Get with: `PROJECT_ROOT="$(pwd)" && MARKETPLACE_PATH="$PROJECT_ROOT/hailer-marketplace"`
+</marketplace-path>
+
+<checks>
+## 1. Structure Check
+- Plugin folder exists
+- `{plugin}/.claude-plugin/plugin.json` exists
+- Agent: `{plugin}/agents/*.md` exists
+
+## 2. Plugin.json Schema
+```json
+{
+  "name": "string (required)",
+  "description": "string (required)",
+  "version": "string semver (required)",
+  "author": { "name": "string" }
+}
+```
+
+## 3. Marketplace.json Entry
+Entry exists with correct version
+
+## 4. JSON Validity
+```bash
+node -e "JSON.parse(require('fs').readFileSync('file.json'))"
+```
+
+## 5. Version Check
+```bash
+# Get new version from branch
+NEW_VERSION=$(jq -r '.version' {plugin}/.claude-plugin/plugin.json)
+
+# Get old version from main (if exists)
+OLD_VERSION=$(git show main:{plugin}/.claude-plugin/plugin.json 2>/dev/null | jq -r '.version')
+
+# Compare: new must be > old
+node -e "
+const semver = require('semver');
+const old = '$OLD_VERSION';
+const new_ = '$NEW_VERSION';
+if (old && old !== 'null' && !semver.gt(new_, old)) {
+  console.log('FAIL: ' + new_ + ' is not greater than ' + old);
+  process.exit(1);
+}
+console.log('PASS: ' + new_ + ' > ' + (old || 'new plugin'));
+"
+```
+- New plugins: skip version check (no existing version)
+- Updates: new version MUST be > existing version
+</checks>
+
+<workflow>
+1. cd to marketplace path
+2. `git fetch origin`
+3. `git checkout {branch}`
+4. Run validation checks:
+   - Plugin folder exists
+   - plugin.json valid JSON + correct schema
+   - marketplace.json valid JSON + has entry
+   - Agent/skill/hook files exist
+   - Version > existing version (if update)
+5. If ALL checks pass:
+   - `git checkout main`
+   - `git merge {branch} --no-edit`
+   - `git push origin main`
+   - `git branch -d {branch}`
+   - `git push origin --delete {branch}`
+   - Return success
+6. If ANY check fails:
+   - `git checkout main`
+   - Return error with failures
+   - DO NOT merge
+</workflow>
+
+<protocol>
+Input: {
+  "task": "review",
+  "branch": "publish/plugin-name-v1.0.0"
+}
+
+Output (merged): {
+  "status": "success",
+  "result": {
+    "checks_passed": 5,
+    "checks_failed": 0,
+    "merged": true,
+    "branch_deleted": true
+  },
+  "summary": "Merged plugin-name v1.0.0"
+}
+
+Output (rejected): {
+  "status": "error",
+  "result": {
+    "checks_passed": 3,
+    "checks_failed": 2,
+    "merged": false,
+    "failures": [
+      "plugin.json: invalid JSON",
+      "version: 1.0.0 not greater than existing 1.0.0"
+    ]
+  },
+  "summary": "Rejected - 2 checks failed"
+}
+</protocol>

package/.claude/commands/help.md

@@ -0,0 +1,28 @@
+---
+description: Show help topics for Hailer MCP
+---
+
+# Hailer MCP Help
+
+Display available help topics to the user.
+
+## Output
+
+```
+╭─────────────────────────────────────────╮
+│         HAILER MCP HELP SYSTEM          │
+╰─────────────────────────────────────────╯
+
+Available topics:
+
+  /help plugins    Plugin system (install, uninstall, publish)
+  /help agents     How agents work and delegation
+  /help commands   All slash commands
+  /help tools      MCP tools reference
+  /help faq        Common questions
+
+───────────────────────────────────────────
+Type /help <topic> for details
+```
+
+## Always show this exactly as formatted above.

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

@@ -0,0 +1,71 @@
+---
+description: Agent usage help for Hailer MCP
+---
+
+# Agents Help
+
+Display agent usage instructions to the user.
+
+## Output
+
+```
+╭─────────────────────────────────────────╮
+│          HAILER MCP - AGENTS            │
+╰─────────────────────────────────────────╯
+
+Agents are AI specialists that handle specific tasks. The orchestrator
+(Claude) delegates work to them based on the task type.
+
+HOW IT WORKS:
+
+  1. You ask Claude to do something
+  2. Claude identifies the right agent
+  3. Claude spawns the agent with your task
+  4. Agent does the work, returns JSON result
+  5. Claude interprets result and reports back
+
+AGENT CATEGORIES:
+
+  Data Operations:
+    agent-kenji-data-reader    - Read workflows, fields, activities
+    agent-dmitri-activity-crud - Create/update activities
+    agent-generic-crud         - Generic CRUD across workflows
+
+  Configuration:
+    agent-helga-workflow-config     - Manage workflows, fields, phases
+    agent-alejandro-function-fields - Calculated function fields
+    agent-viktor-sql-insights       - SQL-like reports
+    agent-nora-name-functions       - Activity name functions
+
+  Development:
+    agent-giuseppe-app-builder - Build Hailer apps
+    agent-gunther-mcp-tools    - Build MCP tools
+    agent-marco-mockup-builder - React mockups
+
+  Quality:
+    agent-svetlana-code-review - Code review
+    agent-tanya-test-runner    - Run tests
+    agent-lars-code-inspector  - Find bugs, dead code
+
+  Marketplace:
+    agent-marketplace-publisher - Publish plugins
+    agent-marketplace-reviewer  - Review plugin PRs
+
+EXAMPLE USAGE:
+
+  "Create a customer activity in the CRM workflow"
+  → Delegates to agent-dmitri-activity-crud
+
+  "Build a dashboard app showing orders"
+  → Delegates to agent-giuseppe-app-builder
+
+  "Review my code changes"
+  → Delegates to agent-svetlana-code-review
+
+INSTALLED AGENTS:
+  Check the <agents> table in CLAUDE.md
+
+SEE ALSO:
+  /help plugins  - Install more agents
+  /help commands - All slash commands
+```

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

@@ -0,0 +1,39 @@
+---
+description: All slash commands for Hailer MCP
+---
+
+# Commands Reference
+
+Display all available commands to the user.
+
+## Output
+
+```
+╭─────────────────────────────────────────╮
+│       HAILER MCP - ALL COMMANDS         │
+╰─────────────────────────────────────────╯
+
+HELP
+  /help              Show all help topics
+  /help plugins      Plugin system guide
+  /help agents       Agent usage guide
+  /help commands     This reference
+  /help tools        MCP tools reference
+  /help faq          Common questions
+
+PLUGINS
+  /marketplace-setup       Clone/update marketplace repo
+  /list-plugins            List available plugins
+  /install-plugin <name>   Install a plugin
+  /uninstall-plugin <name> Remove a plugin
+  /publish-plugin          Publish to marketplace
+
+DEVELOPMENT
+  /tool-builder      Build a new MCP tool
+
+───────────────────────────────────────────
+Examples:
+  /list-plugins
+  /install-plugin tanya-test-runner
+  /help plugins
+```

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

@@ -0,0 +1,69 @@
+---
+description: Frequently asked questions for Hailer MCP
+---
+
+# FAQ
+
+Display frequently asked questions to the user.
+
+## Output
+
+```
+╭─────────────────────────────────────────╮
+│     HAILER MCP - FAQ                    │
+╰─────────────────────────────────────────╯
+
+Q: Why is Claude failing at Hailer tasks?
+A: Check two things:
+   1. Run /mcp to verify Claude is connected to the Hailer MCP
+   2. Make sure you're running Claude from the correct project folder
+      (the one with CLAUDE.md and .claude/ folder)
+
+Q: Why do I need to restart Claude Code after installing a plugin?
+A: Claude Code loads agent definitions at startup. New agents
+   won't be available until restart. Use 'claude -c' to keep context.
+
+Q: What's the difference between /plugin install and /install-plugin?
+A: /plugin install - Claude's built-in plugin system (global)
+   /install-plugin - Our local marketplace system (per-project)
+
+Q: Can I create my own agents?
+A: Yes! Add a markdown file to .claude/agents/ following the agent
+   structure. See existing agents for examples.
+
+Q: How do I publish my agent to the marketplace?
+A: Use /publish-plugin. It creates a PR that gets auto-reviewed.
+   See /help plugins for details.
+
+Q: Why does the orchestrator delegate instead of doing work directly?
+A: Delegation keeps specialized knowledge in focused agents,
+   reducing context size and improving accuracy.
+
+Q: What happens if an agent fails?
+A: The orchestrator receives an error JSON and reports the failure.
+   It should identify root cause and fix it, never apply bandaids.
+
+Q: How do I know which agent will handle my request?
+A: Check the <agents> table in CLAUDE.md. The orchestrator matches
+   your request to the appropriate agent based on patterns.
+
+Q: Can I use MCP tools directly without agents?
+A: Yes! Tools like list_workflows, create_activity, etc. are
+   available directly. Agents just provide structured workflows.
+
+Q: Where is configuration stored?
+A: - Agents: .claude/agents/
+   - Skills: .claude/skills/
+   - Hooks: .claude/hooks/
+   - Settings: .claude/settings.json
+   - Instructions: CLAUDE.md
+
+Q: How do I update an installed plugin?
+A: Uninstall and reinstall:
+   /uninstall-plugin <name>
+   /install-plugin <name>
+
+MORE HELP:
+  /help plugins  - Plugin system
+  /help agents   - Agent usage
+```

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

@@ -0,0 +1,50 @@
+---
+description: Plugin system help for Hailer MCP
+---
+
+# Plugin System Help
+
+Display plugin system instructions to the user.
+
+## Output
+
+```
+HAILER MCP - PLUGIN SYSTEM
+
+The plugin system lets you install community agents from the marketplace.
+
+COMMANDS:
+
+  /marketplace-setup
+    Clone or pull the marketplace repo to ./hailer-marketplace
+    Only needed once. Commands will prompt you if missing.
+
+  /list-plugins
+    List all available plugins (auto-pulls latest).
+
+  /install-plugin <name>
+    Install a plugin to .claude/ folder.
+    Example: /install-plugin tanya-test-runner
+
+  /uninstall-plugin <name>
+    Remove a plugin from .claude/ folder.
+
+  /publish-plugin
+    Publish your plugin to marketplace (creates PR).
+
+PLUGIN TYPES:
+
+  Agents   AI specialists (.claude/agents/)
+  Skills   On-demand docs (.claude/skills/)
+  Hooks    Event scripts (.claude/hooks/)
+
+WORKFLOW:
+
+  1. /list-plugins            # See what's available
+  2. /install-plugin <name>   # Install what you need
+  3. Restart: claude -c       # Load new agents
+
+SEE ALSO:
+  /help agents   - How to use installed agents
+  /help faq      - Common questions
+```

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
+```