@hailer/mcp 0.1.3 → 0.1.4

package/.claude/agents/ada.md

@@ -29,13 +29,44 @@ I am Ada. Every failure is a lesson waiting to be documented. Output JSON. Full
 </skill-location>
 
 <skill-template>
-# [Skill Name]
-<pattern>[Core concept]</pattern>
-<correct>```code```</correct>
-<wrong>```code```</wrong>
-<fix>[How to fix]</fix>
+```markdown
+---
+name: skill-name
+description: One-line description of what this skill fixes
+triggers: When to load this skill (error patterns, task types)
+---
+
+<problem>
+What goes wrong and why.
+</problem>
+
+<correct>
+```code
+// Working example with comments
+```
+</correct>
+
+<wrong>
+```code
+// Broken example showing the mistake
+```
+</wrong>
+
+<fix>
+1. Step to fix
+2. Step to fix
+</fix>
+```
 </skill-template>
 
+<skill-optional-tags>
+Use when needed:
+- `<rules>` - Critical constraints
+- `<examples>` - Multiple scenarios
+- `<troubleshooting>` - Error → solution mapping
+- `<checklist>` - Pre-flight checks
+</skill-optional-tags>
+
 <agent-update>
 Add ONE LINE to agent's <skills> section:
 Load `skill-name` for [pattern description].

package/.claude/agents/helga.md

@@ -1,6 +1,6 @@
 ---
 name: helga
-description: Manages Hailer workspace config via SDK commands (NOT install_workflow).\n\n<example>\nuser: "Add Due Date field to Tasks"\nassistant: {"status":"ready_to_push","result":{"files_edited":["fields.ts"]},"commands":["npm run fields-push"],"summary":"Added Due Date field"}\n</example>
+description: Manages Hailer workspace config via SDK commands (NOT install_workflow).\n\n<example>\nuser: "Add Due Date field to Tasks"\nassistant: {"status":"success","result":{"files_edited":["fields.ts"],"commands_executed":["npm run fields-push:force"]},"summary":"Added Due Date field"}\n</example>
 model: sonnet
 tools: Bash, Read, Edit, Write, Glob
 ---
@@ -25,22 +25,22 @@ Load `json-only-output` to avoid prose after JSON responses.
 3. **Always npm run pull first** - Never edit stale files.
 4. **Use enums from enums.ts** - Never hardcode IDs.
 5. **New items: omit _id** - Server generates.
-6. **NEVER run push/sync** - Return commands for orchestrator.
+6. **RUN push/sync:force DIRECTLY** - Execute destructive commands yourself.
 7. **JSON ONLY** - Output closing brace, then STOP. Zero prose after JSON.
 </rules>
 
 <commands>
-RUN DIRECTLY: npm run pull
-RETURN TO ORCHESTRATOR: workflows-sync, fields-push, phases-push, teams-push, groups-push, templates-sync, templates-push, push
+RUN DIRECTLY (all with :force): npm run pull, npm run push:force, npm run workflows-sync:force, npm run fields-push:force, npm run phases-push:force, npm run teams-push:force, npm run groups-push:force, npm run templates-sync:force, npm run templates-push:force
 </commands>
 
 <workflow-creation>
-1. npm run pull (run directly)
+1. npm run pull
 2. Edit workflows.ts (omit _id)
-3. Return: { commands: ["npm run workflows-sync"] }
-4. After orchestrator confirms → npm run pull
+3. npm run workflows-sync:force
+4. npm run pull (get server-generated IDs)
 5. Edit fields.ts, phases.ts
-6. Return: { commands: ["npm run fields-push", "npm run phases-push"] }
+6. npm run fields-push:force && npm run phases-push:force
+7. npm run pull (final sync)
 </workflow-creation>
 
 <field-template>
@@ -50,5 +50,5 @@ RETURN TO ORCHESTRATOR: workflows-sync, fields-push, phases-push, teams-push, gr
 <protocol>
 Input: JSON task spec
 Output: JSON only
-Schema: { "status": "success|error|ready_to_push", "result": { "files_edited": [] }, "commands": [], "summary": "" }
+Schema: { "status": "success|error", "result": { "files_edited": [], "commands_executed": [] }, "summary": "" }
 </protocol>

package/.claude/agents/ingrid.md

@@ -1,6 +1,6 @@
 ---
 name: ingrid
-description: Creates and manages Hailer document templates.\n\n<example>\nuser: "Create PDF invoice template"\nassistant: {"status":"ready_to_push","result":{"template_id":"","files_modified":["templates.ts"]},"commands":["npm run templates-sync"],"summary":"Added invoice template"}\n</example>
+description: Creates and manages Hailer document templates.\n\n<example>\nuser: "Create PDF invoice template"\nassistant: {"status":"ready_to_push","result":{"template_id":"","files_modified":["templates.ts"]},"commands":["npm run templates-sync:force"],"summary":"Added invoice template"}\n</example>
 model: sonnet
 tools: Bash, Read, Edit, Write, Glob
 ---
@@ -30,9 +30,9 @@ Load `SDK-ws-config-skill` for full patterns.
 </rules>
 
 <lifecycle>
-CREATE: pull → edit templates.ts → return sync command → (orchestrator runs) → pull → edit config/code → return push command
-UPDATE: pull → edit config/code → return push command
-DELETE: pull → remove from templates.ts → return sync command
+CREATE: pull → edit templates.ts → return sync:force command → (orchestrator runs) → pull → edit config/code → return push:force command
+UPDATE: pull → edit config/code → return push:force command
+DELETE: pull → remove from templates.ts → return sync:force command
 </lifecycle>
 
 <field-mapping>

package/.claude/assistant-knowledge.md

@@ -0,0 +1,23 @@
+# MCP Agents
+
+kenji: Read data/schema from workspace (haiku)
+dmitri: Create/update activities (haiku)
+yevgeni: Discussions and chat (haiku)
+helga: Workflow/field/phase config (sonnet)
+viktor: SQL insights over workflows (sonnet)
+giuseppe: Build Hailer apps (sonnet)
+alejandro: Function/calculated fields (sonnet)
+
+# What MCP Can Do
+
+- Manage Hailer workflows, activities, fields
+- Create SQL-like reports (insights)
+- Build custom apps
+- Handle discussions/messaging
+- Configure workspace structure
+
+# Limitations
+
+- Cannot access external systems
+- Limited to configured workspace
+- Agents run via Claude Code CLI

package/.claude/hooks/agent-failure-detector.cjs

@@ -1,9 +1,33 @@
 #!/usr/bin/env node
 /**
- * Agent Failure Detector Hook
+ * <hook-name>agent-failure-detector</hook-name>
  *
- * PostToolUse hook for Task tool - detects agent failures, categorizes them,
- * and suggests appropriate fixes (skill creation vs agent update).
+ * <purpose>
+ * Detects repeated agent failures, categorizes error types, and suggests fixes.
+ * Tracks failures per agent and prompts for improvement after threshold.
+ * </purpose>
+ *
+ * <triggers>
+ * - PostToolUse on Task tool
+ * - Only when agent response contains error indicators
+ * </triggers>
+ *
+ * <error-categories>
+ * - skill: API/schema errors → Create skill documenting correct pattern
+ * - agent: Behavioral errors → Update agent definition
+ * - user_issue: Permission errors → Ignore (user problem)
+ * - transient: Connection/timeout → Ignore (retry may work)
+ * </error-categories>
+ *
+ * <behavior>
+ * 1. Detects failure patterns in agent response
+ * 2. Categorizes error type
+ * 3. Tracks per-agent failure count
+ * 4. After 2+ failures, suggests fix via AskUserQuestion
+ * 5. Recommends spawning ada to create skill or update agent
+ * </behavior>
+ *
+ * <tracker-file>/tmp/.claude-agent-failures.json</tracker-file>
  */
 
 const fs = require('fs');

package/.claude/hooks/app-edit-guard.cjs

@@ -1,20 +1,43 @@
 #!/usr/bin/env node
 /**
- * Claude Code PreToolUse Hook - BULLETPROOF Hailer App Guard
+ * <hook-name>app-edit-guard</hook-name>
  *
- * Blocks ALL direct edits to Hailer app directories.
- * Detection is pattern-based - no registration required.
+ * <purpose>
+ * Blocks direct edits to Hailer app directories.
+ * Forces use of builder agents for app development.
+ * </purpose>
  *
- * A directory is considered a Hailer app if it contains:
- * - public/manifest.json with "appId" field, OR
+ * <triggers>
+ * - PreToolUse on Write and Edit tools
+ * - Only when file is inside a detected Hailer app directory
+ * </triggers>
+ *
+ * <detection>
+ * A directory is a Hailer app if it contains:
+ * - public/manifest.json with "appId" field
  * - package.json with @hailer/app-sdk dependency
+ * - vite.config.ts referencing hailer
+ * </detection>
+ *
+ * <allowed-when>
+ * - Builder agent is active (/tmp/.claude-builder-agent-active exists)
+ * - Builder mode enabled for specific app (--builder-on)
+ * - App released for manual editing (--release)
+ * </allowed-when>
  *
- * Edits are ONLY allowed when:
- * 1. Running inside a subagent (Task tool with CLAUDE_CODE_ENTRYPOINT=task)
- * 2. The app directory has been explicitly released for manual editing
+ * <cli-commands>
+ * --agent-on/off: Global builder mode (affects all apps + src/)
+ * --builder-on/off: Per-app builder mode
+ * --release/revoke: Manual editing permission
+ * --check: Verify if path is Hailer app
+ * --list: Show released apps
+ * </cli-commands>
  *
- * To release an app for manual editing:
- *   node app-edit-guard.cjs --release /path/to/app
+ * <shared-files>
+ * /tmp/.claude-builder-agent-active (shared with builder-mode-manager, src-edit-guard)
+ * /tmp/.claude-released-apps.json
+ * /tmp/.claude-builder-mode/
+ * </shared-files>
  */
 
 const fs = require('fs');

package/.claude/hooks/builder-mode-manager.cjs

@@ -1,13 +1,41 @@
 #!/usr/bin/env node
 /**
- * Builder Mode Manager Hook
+ * <hook-name>builder-mode-manager</hook-name>
  *
- * Automatically enables/disables builder mode for agents that need to edit code.
+ * <purpose>
+ * Automatically manages builder mode for code-editing agents.
+ * Enables before spawn, disables after completion.
+ * Handles nested agent stacks correctly.
+ * </purpose>
  *
- * PreToolUse (Task): Enables builder mode before spawning code-editing agents
- * PostToolUse (Task): Disables builder mode after agent completes
+ * <triggers>
+ * - PreToolUse on Task tool (before agent spawns)
+ * - PostToolUse on Task tool (after agent completes)
+ * </triggers>
  *
- * Code-editing agents: giuseppe, gunther, general-purpose, agent-builder
+ * <code-editing-agents>
+ * giuseppe, gunther, general-purpose, agent-builder, helga, ingrid, ada
+ * </code-editing-agents>
+ *
+ * <behavior>
+ * PreToolUse:
+ *   1. Push agent onto stack
+ *   2. If code-editing agent and builder mode off → enable
+ *
+ * PostToolUse:
+ *   1. Pop agent from stack
+ *   2. If no remaining code-editing agents → disable builder mode
+ * </behavior>
+ *
+ * <shared-files>
+ * /tmp/.claude-builder-agent-active (builder mode flag)
+ * /tmp/.claude-agent-stack.json (nested agent tracking)
+ * </shared-files>
+ *
+ * <cli-commands>
+ * --status: Show builder mode and active agents
+ * --reset: Clear stack and disable builder mode
+ * </cli-commands>
  */
 
 const fs = require('fs');

package/.claude/hooks/interactive-mode.cjs

@@ -1,9 +1,35 @@
 #!/usr/bin/env node
 /**
- * Claude Code UserPromptSubmit Hook - Interactive Question Mode
+ * <hook-name>interactive-mode</hook-name>
  *
- * Injects a reminder to ask clarifying questions before starting complex tasks.
- * Triggers on every user prompt to encourage interactive behavior.
+ * <purpose>
+ * Encourages Claude to ask clarifying questions before complex tasks.
+ * Injects context-aware question suggestions based on task type.
+ * </purpose>
+ *
+ * <triggers>
+ * - UserPromptSubmit (every user message)
+ * - Only outputs when task patterns are detected
+ * </triggers>
+ *
+ * <task-patterns>
+ * - app: build/create/make app → UI, layout, actions questions
+ * - insight: create insight/report → metrics, workflows, filters questions
+ * - data: import/create activities → workflow, fields, count questions
+ * - schema: add field/workflow/phase → type, required, defaults questions
+ * - update: update/change/modify → records, values, confirmation questions
+ * </task-patterns>
+ *
+ * <behavior>
+ * 1. Matches user prompt against task patterns
+ * 2. If match, outputs <interactive-mode> block to stderr
+ * 3. Suggests relevant questions for Claude to ask
+ * 4. Recommends AskUserQuestion tool usage
+ * </behavior>
+ *
+ * <output-format>
+ * Outputs to stdout (appears as system reminder to Claude)
+ * </output-format>
  */
 
 // Read hook input from stdin

package/.claude/hooks/mcp-server-guard.cjs

@@ -1,11 +1,27 @@
 #!/usr/bin/env node
 /**
- * MCP Server Guard Hook
+ * <hook-name>mcp-server-guard</hook-name>
  *
- * PreToolUse hook that prevents Claude from starting the MCP server.
- * When blocked, instructs Claude to provide manual instructions to the user.
+ * <purpose>
+ * Prevents Claude from starting the MCP server directly.
+ * The user must run the MCP server manually before starting Claude Code.
+ * </purpose>
  *
- * Blocked commands: npm run dev, npm start, tsx src/app.ts, etc.
+ * <triggers>
+ * - npm run dev, npm start
+ * - tsx src/app.ts, node src/app.ts
+ * - Any command that would start the MCP server
+ * </triggers>
+ *
+ * <behavior>
+ * 1. Blocks server start commands with permissionDecision: "deny"
+ * 2. Outputs instructions to stderr for user to run manually
+ * </behavior>
+ *
+ * <user-action>
+ * User runs in separate terminal:
+ *   cd /path/to/hailer-mcp && npm run dev
+ * </user-action>
  */
 
 // Commands that would start the MCP server

package/.claude/hooks/post-scaffold-hook.cjs

@@ -1,11 +1,30 @@
 #!/usr/bin/env node
 /**
- * Claude Code PostToolUse Hook - Asks user about spawning app builder agent
+ * <hook-name>post-scaffold-hook</hook-name>
  *
- * This hook triggers after scaffold_hailer_app completes successfully
- * and ASKS the user if they want to spawn the app builder agent.
+ * <purpose>
+ * Prompts user to spawn builder agent after scaffold_hailer_app completes.
+ * Registers new app with app-edit-guard for edit protection.
+ * </purpose>
  *
- * Also registers the app with app-edit-guard to block direct edits.
+ * <triggers>
+ * - PostToolUse on mcp__hailer__scaffold_hailer_app
+ * - Only when output contains "Setup Complete"
+ * </triggers>
+ *
+ * <behavior>
+ * 1. Detects successful scaffold completion
+ * 2. Registers app in /tmp/.claude-scaffolded-apps/
+ * 3. Outputs AskUserQuestion template for builder spawn decision
+ * 4. Provides instructions for both "spawn builder" and "build manually" paths
+ * </behavior>
+ *
+ * <user-choices>
+ * - "Yes, spawn builder": Load spawn-app-builder skill, spawn giuseppe
+ * - "No, build manually": Load building-hailer-apps-skill in current session
+ * </user-choices>
+ *
+ * <tracker-dir>/tmp/.claude-scaffolded-apps/</tracker-dir>
  */
 
 const path = require('path');

package/.claude/hooks/publish-template-guard.cjs

@@ -1,18 +1,36 @@
 #!/usr/bin/env node
 /**
- * Claude Code PreToolUse Hook - Ensures all required fields before publish_template
+ * <hook-name>publish-template-guard</hook-name>
  *
- * This hook intercepts publish_template calls and blocks them if required fields
- * are missing, prompting Claude to gather all information first.
+ * <purpose>
+ * Ensures all required fields are provided before publish_template is called.
+ * Blocks incomplete calls and instructs Claude to gather information first.
+ * </purpose>
  *
- * Required fields from Hailer UI:
- * - title (Name) - max 64 chars
- * - description - max 4096 chars
- * - version - e.g. "1.0.0"
- * - versionDescription - release notes
- * - publisher - publishing company name
- * - iconFileId - uploaded icon (JPEG/PNG)
- * - imageFileIds - preview images array (optional but recommended)
+ * <triggers>
+ * - mcp__hailer__publish_template tool calls
+ * </triggers>
+ *
+ * <required-fields>
+ * - title: Template name (max 64 chars)
+ * - description: What it includes (max 4096 chars)
+ * - version: Semantic version (e.g. "1.0.0")
+ * - versionDescription: Release notes
+ * - publisher: Company or person name
+ * - iconFileId: Uploaded icon ID (24 chars)
+ * </required-fields>
+ *
+ * <behavior>
+ * 1. Checks tool_input for missing required fields
+ * 2. Blocks with decision: "block" if incomplete
+ * 3. Provides AskUserQuestion template for Claude to gather info
+ * </behavior>
+ *
+ * <workflow>
+ * 1. Claude asks user for template details
+ * 2. Claude uploads icon with upload_files
+ * 3. Claude calls publish_template with ALL fields
+ * </workflow>
  */
 
 // Read hook input from stdin

package/.claude/hooks/src-edit-guard.cjs

@@ -1,14 +1,38 @@
 #!/usr/bin/env node
 /**
- * Claude Code PreToolUse Hook - Source Code Edit Guard
+ * <hook-name>src-edit-guard</hook-name>
  *
- * Blocks direct edits to src/ directory files.
- * Forces the main agent to spawn subagents for code changes.
- * This saves context in the main agent for orchestration.
+ * <purpose>
+ * Blocks direct edits to src/ directory.
+ * Forces main agent to spawn subagents for MCP server code changes.
+ * Preserves orchestrator context by delegating implementation work.
+ * </purpose>
  *
- * Edits are ONLY allowed when:
- * - Running inside a subagent (builder mode active)
+ * <triggers>
+ * - PreToolUse on Write and Edit tools
+ * - Only when file path starts with src/
+ * </triggers>
+ *
+ * <allowed-when>
+ * - Builder mode is active (/tmp/.claude-builder-agent-active exists)
  * - File is outside src/ directory
+ * </allowed-when>
+ *
+ * <behavior>
+ * 1. Checks if file is in src/ directory
+ * 2. Checks builder mode status
+ * 3. Blocks with instructions to spawn general-purpose agent
+ * </behavior>
+ *
+ * <shared-files>
+ * /tmp/.claude-builder-agent-active (shared with app-edit-guard, builder-mode-manager)
+ * </shared-files>
+ *
+ * <cli-commands>
+ * --on: Enable builder mode (allow src/ edits)
+ * --off: Disable builder mode (block src/ edits)
+ * --status: Check current mode
+ * </cli-commands>
  */
 
 const fs = require('fs');

package/.claude/settings.json

@@ -34,11 +34,6 @@
       {
         "matcher": "Bash",
         "hooks": [
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/sdk-delete-guard.cjs\"",
-            "timeout": 5
-          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/mcp-server-guard.cjs\"",