@hailer/mcp 1.1.14 → 1.1.16

package/.claude/commands/handoff.md

@@ -0,0 +1,137 @@
+---
+description: Create or update session handoff for continuity
+argument-hint: [optional summary]
+---
+# Session Handoff
+
+Context is getting full or session is ending. Create/update handoff for next session.
+
+## Step 0: Capture Learnings (Auto-Learn)
+
+Before creating handoff, scan for learnings from this session.
+
+**Run the learn-auto logic:**
+1. Scan conversation for: error→fix patterns, user corrections, explicit insights, agent failures
+2. Present any findings to user for confirmation
+3. Write confirmed learnings to inbox
+
+This ensures valuable insights aren't lost when session ends.
+
+If no learnings found or user skips, continue to Step 1.
+
+---
+
+## Step 1: Gather Current State
+
+Collect:
+- What was worked on this session
+- Current state of in-progress work
+- Any blockers or issues found
+- Uncommitted changes (`git status`)
+- Next steps
+
+## Step 2: Graduate Auto Memory
+
+Check if the project has auto memory entries to graduate.
+
+**Find the memory file:**
+1. Get project root from working directory
+2. Transform path: replace `/` with `-` (e.g., `/Users/timoahonen/my-project` → `-Users-timoahonen-my-project`)
+3. Memory path: `~/.claude/projects/<transformed-path>/memory/MEMORY.md`
+
+**If MEMORY.md exists and has content:**
+1. Read it
+2. For each entry, decide:
+   - **Project-specific gotcha** (field ID quirks, workflow-specific behavior) → Move to SESSION-HANDOFF.md "Context to Preserve"
+   - **Reusable pattern** (SDK behavior, API gotchas, agent tips) → Capture via `/learn-hub` or note for inbox
+   - **Already in a skill or CLAUDE.md** → Remove (it graduated in a previous session)
+   - **Stale or wrong** → Remove
+3. Remove graduated/stale entries from MEMORY.md
+4. Keep only entries that are still being validated (discovered this session, not yet confirmed)
+
+**Goal:** MEMORY.md is a scratch buffer, not permanent storage. At handoff, everything graduates out.
+
+## Step 3: Check for Active Tasks
+
+Run `TaskList`. If tasks exist:
+- Export pending/in_progress tasks to handoff
+- Summarize completed tasks in "What Was Done"
+
+## Step 4: Update Documentation (if applicable)
+
+**Did this session complete any features?**
+
+If YES:
+- Update the PRD file (docs/prd-*.md): change Status to "Complete", check off completed items
+- Update DEVELOPMENT.md Roadmap: mark feature as Complete
+- Update "Current Status"
+- Add any technical decisions
+- Note new issues discovered
+
+## Step 5: Create/Update SESSION-HANDOFF.md
+
+If file exists → UPDATE it (remove stale items, keep relevant context)
+If not exists → CREATE it
+
+```markdown
+# Session Handoff
+
+**Last Updated:** YYYY-MM-DD HH:MM
+
+## What Was Done
+- [Completed items with context]
+
+## Current Work
+- [What's actively being worked on]
+- [State of in-progress features]
+
+## Pending Tasks
+_From TaskList - will be recreated next session_
+- [ ] Task description
+- [ ] Task description
+
+## Blockers / Issues
+- [Problems encountered]
+- [Things that need investigation]
+
+## Next Steps
+1. [First thing to do when resuming]
+2. [Second thing]
+3. [Third thing]
+
+## Key Decisions
+- [Decision]: [Why]
+
+## Files Modified
+- `path/to/file` - [what changed]
+
+## Context to Preserve
+- [Important notes that shouldn't be lost]
+- [Gotchas discovered]
+```
+
+## Step 6: Save Progress
+
+If git is initialized and there are changes:
+```
+/save "Session handoff: [brief summary]"
+```
+
+## Step 7: Report
+
+Tell user:
+```
+Session handoff complete:
+- SESSION-HANDOFF.md updated
+- DEVELOPMENT.md updated (if features completed)
+- [X] files have uncommitted changes
+
+To continue: Start new session - handoff will be read automatically.
+```
+
+## Notes
+
+- **UPDATE, don't delete** - SESSION-HANDOFF.md accumulates context
+- Remove items that are no longer relevant
+- Keep decisions and gotchas even after tasks complete
+- Next session reads handoff, then updates it (removes completed items)

package/.claude/commands/health.md

@@ -0,0 +1,49 @@
+---
+description: Run project health check and config audit
+allowed-tools: Task, Bash, Read
+---
+# Project Health Check
+
+Run a quick audit of the current project configuration.
+
+**Check the following:**
+
+1. **Workspace sync status**
+   - Run `npm run pull` to check connectivity
+   - Compare local workspace/ timestamps with server
+
+2. **CLAUDE.md accuracy**
+   - Does CLAUDE.md exist?
+   - Are listed agents present in .claude/agents/?
+   - Are referenced skills present in .claude/skills/?
+
+3. **Hooks integrity**
+   - Are all hooks in settings.json present in .claude/hooks/?
+   - Do hook files have execute permissions?
+
+4. **Dependencies**
+   - Run `npm outdated` to check for updates
+   - Check if node_modules exists
+
+5. **Git status**
+   - Any uncommitted changes?
+   - Is branch up to date with remote?
+
+**Output format:**
+
+```
+## Health Check - [Project Name]
+
+[x] Workspace synced (last pull: X minutes ago)
+[x] CLAUDE.md valid (15 agents, 10 skills)
+[x] Hooks intact (8/8 present)
+[ ] Dependencies outdated (3 packages)
+[x] Git clean
+
+### Issues Found
+- @hailer/sdk outdated: 0.8.3 → 0.8.5
+- Missing hook: xyz.cjs referenced but not found
+
+### Recommendations
+- Run `npm update @hailer/sdk`
+```

package/.claude/commands/help.md

@@ -0,0 +1,29 @@
+---
+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 agents     How agents work and delegation
+  /help skills     Skills reference (patterns, templates, fixes)
+  /help commands   All slash commands
+  /help tools      MCP tools reference
+  /help plugins    Plugin system (install, uninstall, publish)
+  /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,151 @@
+---
+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 RELATIONSHIPS (who calls who):
+
+  Kenji → Dmitri       Kenji gets IDs, Dmitri creates/updates
+  Kenji → Helga        Kenji gets structure, Helga modifies config
+  Kenji → Alejandro    Kenji gets field IDs, Alejandro creates functions
+  Kenji → Viktor       Kenji gets schema, Viktor creates insights
+  Kenji → Giuseppe     Kenji gets data structure, Giuseppe builds app
+  Marco → Giuseppe     Marco validates mockup, Giuseppe builds production
+  Ada ← (any failure)  Ada creates skills from repeated failures
+
+  Common chains:
+  • Add field:     Kenji → Helga → (push) → Kenji (verify)
+  • Create app:    Kenji → Viktor → Giuseppe → Tanya
+  • Activity CRUD: Kenji → Dmitri
+
+─────────────────────────────────────────────────────────────────────────
+
+AGENT TOOL ACCESS:
+
+  MCP Tools Only (restricted):
+    Kenji     - list_workflows, count_activities, list_activities
+    Dmitri    - create_activity, update_activity
+    Permissions - list_apps, add/remove_app_member, search_users
+    Yevgeni   - discussion tools (list, fetch, post, invite)
+
+  Code Tools (Bash, Read, Write, Edit):
+    Giuseppe  - App building (+scaffold_hailer_app)
+    Gunther   - MCP tool building
+    Helga     - Workflow config
+    Igor      - Activity movers
+    Ivan      - Monolith automations
+    Marco     - Mockups
+    Ingrid    - Document templates
+
+  Read-Only (Read, Glob, Grep):
+    Svetlana  - Code review
+    Bjorn     - Config audit
+    Tanya     - Test runner (+ Bash for test execution)
+
+  Light Edit (Read, Edit, Glob):
+    Simple Writer - Basic edits only (haiku model, fast)
+    Code Simplifier - Simplify code for clarity (sonnet model)
+
+  Special:
+    Lars      - LSP only (code inspection)
+    Ada       - Read, Write, Edit, Glob (skill creation)
+
+─────────────────────────────────────────────────────────────────────────
+
+AGENT CATEGORIES:
+
+  Data Operations:
+    agent-kenji-data-reader    - Read workflows, fields, activities (LOCAL FIRST)
+    agent-dmitri-activity-crud - Create/update activities
+    agent-yevgeni-discussions  - Read/post discussion messages
+    agent-permissions-handler  - Manage app access
+    agent-simple-writer        - Basic code edits (ID swaps, string replacements)
+
+  Configuration:
+    agent-helga-workflow-config     - Manage workflows, fields, phases
+    agent-alejandro-function-fields - Calculated fields + name functions
+    agent-viktor-sql-insights       - SQL-like reports
+    agent-ingrid-doc-templates      - PDF/CSV document templates
+
+  Development:
+    agent-giuseppe-app-builder - Build Hailer apps (production)
+    agent-marco-mockup-builder - Build demo apps (validation)
+    agent-gunther-mcp-tools    - Build MCP tools
+    agent-igor-activity-mover  - Phase cascade microservices
+    agent-ivan-monolith        - Monolith automations
+    agent-zara-zapier          - Zapier integrations
+
+  Quality:
+    agent-svetlana-code-review - Code review (READ-ONLY)
+    agent-tanya-test-runner    - Run tests
+    agent-lars-code-inspector  - Find bugs, dead code (LSP)
+    agent-bjorn-config-audit   - Audit configuration
+    agent-code-simplifier      - Simplify code for clarity
+
+  Meta:
+    agent-ada-skill-builder       - Create skills from failures
+    agent-builder-agent-creator   - Create new agents
+    agent-marcus-api-documenter   - Document API endpoints
+    agent-marketplace-publisher   - Publish plugins
+    agent-marketplace-reviewer    - Review plugin PRs
+
+─────────────────────────────────────────────────────────────────────────
+
+CRITICAL BOUNDARIES:
+
+  Kenji vs Dmitri:
+    Kenji = READ (schema, lists, counts)
+    Dmitri = WRITE (create, update)
+    Dmitri needs IDs from Kenji first!
+
+  Marco vs Giuseppe:
+    Marco = DEMO apps (non-functional, for validation)
+    Giuseppe = PRODUCTION apps (real data, functional)
+    Use Marco first to validate concept, then Giuseppe
+
+─────────────────────────────────────────────────────────────────────────
+
+EXAMPLE USAGE:
+
+  "Create a customer activity in the CRM workflow"
+  → Kenji (get IDs) → Dmitri (create activity)
+
+  "Build a dashboard app showing orders"
+  → Kenji (get schema) → Giuseppe (build app)
+
+  "Add a calculated total field"
+  → Kenji (get field IDs) → Alejandro (create function)
+
+  "Review my code changes"
+  → Svetlana (code review)
+
+─────────────────────────────────────────────────────────────────────────
+
+SEE ALSO:
+  /stats         - View agent usage statistics
+  /help plugins  - Install more agents
+  /help commands - All slash commands
+```

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

@@ -0,0 +1,78 @@
+---
+description: All slash commands for Hailer MCP
+---
+
+# Commands Reference
+
+Display all available commands to the user.
+
+## Output
+
+```
+╭─────────────────────────────────────────╮
+│       HAILER MCP - ALL COMMANDS         │
+╰─────────────────────────────────────────╯
+
+HELP SYSTEM
+  /help               Show all help topics
+  /help:agents        Agent usage, relationships, tool access
+  /help:commands      This reference
+  /help:plugins       Plugin system guide
+  /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
+  /publish                 Publish (alias)
+  /version-check           Show out-of-sync plugins
+
+WORKSPACE
+  /ws-pull           Pull workspace config from Hailer (read-only)
+
+DEVELOPMENT
+  /tool-builder      Enter MCP tool building mode
+  /stats             View agent usage statistics
+  /stats recent      Show last 20 agent calls
+  /health            Run project health check
+
+PLANNING
+  /autoplan <desc>       Quick project planning with PRDs
+  /plan-workspace <desc> Thorough workspace discovery (10 phases)
+  /prd <feature>         Create PRD for a feature
+  /project-status        Sync DEVELOPMENT.md with PRD statuses
+
+SQUADS (multi-agent commands)
+  /review-squad [files]    Parallel+Loop: Svetlana + Lars + Tanya + Simple Writer
+  /cleanup-squad [files]   Parallel: Bjorn + Code Simplifier + Lars
+  /app-squad <desc>        Pipeline+Loop: Kenji → UI Designer → Giuseppe → Tanya (build verify)
+  /config-squad <desc>     Pipeline: Helga → Alejandro → Viktor
+  /crud-squad <desc>       Pipeline: Kenji → Dmitri → Kenji (verify)
+  /data-squad <desc>       Pipeline: Kenji → Alejandro → Viktor
+  /integration-squad <desc> Pipeline: Kenji → Ivan → Tanya
+  /doc-squad <desc>        Pipeline: Lars → Marcus
+  /hotfix-squad <desc>     Pipeline+Loop: Tanya → Simple Writer → Svetlana (max 3 iter)
+  /debug-squad <desc>      Parallel+Loop: Kenji + Viktor + Svetlana + Tanya (--debate for competing hypotheses)
+  /audit-squad             Parallel: Svetlana + Permissions + Gunther (security audit)
+  /onboard-squad <desc>    Pipeline+Loop: Helga → Alejandro → Giuseppe → Bjorn (bootstrap)
+  /janitor-squad           Parallel+Loop: Lars + Bjorn + Viktor → Simple Writer (cleanup)
+  /swarm <desc>            Swarm: orchestrator picks agents, splits work, dispatches parallel workers
+
+SESSION
+  /recap [focus]     Resume session - load handoff, status, learnings
+  /save <message>    Save changes to git (local commit)
+  /restore           Restore to a previous save point
+  /handoff           Create session handoff for next session
+  /learn <cat> <desc> Capture learning and apply fix
+
+───────────────────────────────────────────
+Examples:
+  /plan-workspace "CRM system"  Thorough discovery for new project
+  /autoplan "Add invoicing"     Quick planning for feature
+  /prd "customer portal"        Create PRD for feature
+  /save "Add customer form"     Local git commit
+  /learn agent/kenji "Check enums first"
+```

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

@@ -0,0 +1,79 @@
+---
+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-list 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>
+
+Q: What's the difference between /autoplan and /plan-workspace?
+A: /autoplan - Quick planning, creates DEVELOPMENT.md + PRDs
+   /plan-workspace - Thorough 10-phase discovery for complex workspaces
+   Use /autoplan for features, /plan-workspace for new projects.
+
+Q: How do PRDs and DEVELOPMENT.md work together?
+A: DEVELOPMENT.md is the big picture (roadmap, status, decisions).
+   PRDs (docs/prd-*.md) are detailed requirements for each feature.
+   DEVELOPMENT.md roadmap links to individual PRDs.
+
+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:skills.md

@@ -0,0 +1,93 @@
+---
+description: Skills reference for Hailer MCP
+---
+
+# Skills Reference
+
+Display skills reference to the user.
+
+## Output
+
+```
+╭─────────────────────────────────────────╮
+│     HAILER MCP - SKILLS REFERENCE       │
+╰─────────────────────────────────────────╯
+
+Skills are reusable knowledge files (.claude/skills/<name>/SKILL.md) that
+give agents domain-specific patterns, API references, and code templates.
+
+HOW SKILLS WORK:
+
+  Auto-injected: Agents declare skills in their frontmatter. The
+  SubagentStart hook injects them automatically when the agent spawns.
+
+  On-demand: The orchestrator tells an agent to load a skill via the
+  Skill tool. Only 6 agents have it: Giuseppe, Helga, Viktor,
+  Alejandro, Ingrid, Ada.
+
+─────────────────────────────────────────────────────────────────────────
+
+SDK SKILLS (core patterns):
+  SDK-activity-patterns    - Field value formats, dates, users, links
+  SDK-document-templates   - PDF/CSV template structure + generation
+  SDK-function-fields      - Calculated fields in Hailer workflows
+  SDK-generate-skill       - TypeScript type generation from workspace
+  SDK-init-skill           - Initialize new Hailer SDK projects
+  SDK-insight-queries      - SQL query patterns for insights
+  SDK-ws-config-skill      - Workflow config: fields, phases, schemas
+
+HAILER PLATFORM SKILLS:
+  hailer-activity-mover    - Phase cascade microservice patterns
+  hailer-api-client        - @hailer/cli auth, requests, signals
+  hailer-app-builder       - Build apps with @hailer/app-sdk
+  hailer-apps-pictures     - Fetch and display images from Hailer
+  hailer-design-system     - Chakra UI theme, colors, icons, components
+  hailer-monolith-automations - Webhooks, scheduled jobs in monolith
+  hailer-permissions-system - Users, teams, access control
+  hailer-project-protocol  - Full SDK workflow reference
+  hailer-rest-api          - Direct HTTP API endpoints
+
+INTEGRATION SKILLS:
+  integration-patterns     - Activity movers, webhooks, SCIM, Kafka
+  zapier-hailer-patterns   - Zapier triggers, actions, Zap configs
+  insight-join-patterns    - JOIN syntax for cross-workflow insights
+
+TOOL & AGENT SKILLS:
+  agent-structure          - Template for creating new agents
+  delegation-routing       - Full routing table + chaining patterns
+  tool-builder             - Building MCP tools for Hailer server
+  mcp-direct-tools         - MCP tools not assigned to agents
+
+QUALITY & FIX SKILLS (auto-loaded on errors):
+  tool-parameter-usage     - Extract IDs, correct parameter formats
+  tool-response-verification - Verify MCP results before reporting
+  optional-parameters      - Omit optional params vs empty values
+  json-only-output         - Fix agents adding prose after JSON
+  testing-patterns         - vitest, playwright, build verification
+
+REFERENCE SKILLS:
+  api-documentation-patterns - API doc standards for Marcus
+  chrome-mcp-reference     - Browser automation reference
+  frontend-design          - UI design patterns
+  lsp-setup                - Language Server Protocol setup
+  publish-hailer-app       - App publishing to production
+
+─────────────────────────────────────────────────────────────────────────
+
+ON-DEMAND SKILL LOADING (tell the orchestrator):
+
+  "Load hailer-apps-pictures for Giuseppe"
+  → Giuseppe gets image handling patterns
+
+  "Viktor needs insight-join-patterns for this query"
+  → Viktor gets JOIN syntax for cross-workflow data
+
+  Only works with: Giuseppe, Helga, Viktor, Alejandro, Ingrid, Ada
+
+─────────────────────────────────────────────────────────────────────────
+
+SEE ALSO:
+  /help agents   - Which agents use which skills
+  /help commands - All slash commands
+  /help tools    - MCP tools reference
+```