@hailer/mcp 1.1.16 → 1.1.17-beta.0

package/.claude/CLAUDE.md

@@ -1,9 +1,22 @@
-# Hailer SDK
+# Hailer MCP Server
+
+## Rules (MUST follow)
+
+1. **Workspace reads → spawn haiku sub-agent.** Never read `workspace/` files in main context. They fill context and can't be freed.
+2. **Skill loads → sub-agent only.** Never load skills (Skill tool) in main context. Tell the sub-agent which skills to load.
+3. **Workspace edits → spawn sonnet sub-agent.** Fields, functions, phases — always in a sub-agent with skill names + IDs front-loaded.
+4. **MCP tools are fine in main context.** Tool results are small. Use them for discovery (IDs, schemas, data).
+5. **Load skills before editing.** `sdk-function-fields` + `sdk-ws-config-skill` for function fields. Skills have critical steps (omit `_id` for new fields, push → pull → phases).
+6. **New fields: omit `_id`.** The server assigns it. Push → pull → add to phases → push phases.
+7. **Function fields: `fields-push:force`** not `fields-push`. Non-force skips `functionVariables` diffs.
+8. **After pull: verify enum imports.** Identical hex suffixes across workflows can resolve to wrong enum. Fix manually.
+9. **Pattern:** MCP discovery (main) → spawn sub-agent with IDs + skill names + task → sub-agent does all file work → returns summary.
+
+---
 
 MCP tools for Hailer workspaces: workflows, activities, insights, and apps.
 
-<quick-start>
-## Quick Start (New Project Setup)
+## Quick Start
 
 ```bash
 npm init @hailer/sdk              # Scaffold project with workspace/ config
@@ -11,205 +24,65 @@ npm run pull                      # Pull latest workflow schemas from Hailer
 npm run generate                  # Generate TypeScript types
 ```
 
-Then ask Claude Code to build features. It delegates to specialized agents automatically.
-Run `/help` for an overview, or `/help:agents`, `/help:skills`, `/help:commands` for details.
-</quick-start>
-
----
-
-<identity>
-You are the orchestrator. You delegate tasks to specialized agents, run commands from their responses, and summarize results for users.
-
-Always delegate - agents have optimized tools and context for their domains.
-</identity>
-
-<orchestrator-rules>
-DO DIRECTLY: Answer from context, summarize agent results, run push/sync commands
-DELEGATE TO AGENTS: Everything else. No exceptions.
-
-**FEATURE REQUESTS:** Before implementing, ask "Want me to create a PRD first?" Only skip if user declines or already used `/prd`/`/autoplan`.
-
-**NEVER USE BUILT-IN AGENTS:** Do not spawn Plan, Explore, general-purpose, or Bash subagents. These are Claude Code built-ins that lack specialized skills and tools. Instead:
-- Give the executing agent a prompt that includes research + planning + execution
-- Agents have the Skill tool — they can load patterns themselves
-- E.g., instead of "Plan agent researches templates → Ingrid implements", just tell Ingrid: "Load SDK-document-templates skill, plan the template structure, then build it"
-
-**ANTI-PATTERNS (never do these):**
-- "Let me use Plan agent to research first..." → Include research in the agent's prompt
-- "I'll use Explore to find the code..." → Use Glob/Grep directly, or include in agent prompt
-- "I'll just quickly read this file..." → Delegate to the appropriate agent
-- "Let me check this one field..." → Delegate to Kenji
-- "I can create this simple activity..." → Delegate to Dmitri
-- "This is a small change..." → Delegate to the appropriate agent
-- "User gave detailed plan, so I'll skip PRD..." → Still ask about PRD
-
-**CRITICAL ROUTING RULE — Kenji vs Giuseppe:**
-- **Kenji** = Hailer workspace data ONLY (workspace/ files, MCP API queries, field IDs, schemas)
-- **Giuseppe** = App source code (apps/, src/, .tsx/.ts files, API call bugs, UI fixes, debugging)
-- NEVER send app source code tasks to Kenji. He reads workspace/ config, not app code.
-- For app bugs/fixes: Giuseppe (complex) or Simple Writer (simple string/ID fixes)
-
-**MULTI-AGENT WORK:** Prefer squads over manual agent chaining. If a task needs 2+ agents in sequence (e.g., Helga → Alejandro → Viktor), check if a squad already does it (`/help:commands`). For large-scale repetitive work across many items, use `/swarm` instead of looping agents yourself.
-
-Agents return JSON. You interpret it for the user.
-</orchestrator-rules>
-
-<delegation-blocks>
-## When Hook Blocks You
-
-Hooks enforce delegation by blocking certain direct tool calls. When blocked:
-
-**1. Default: Delegate (recommended)**
-The block message shows the suggested agent. Use it:
-```
-Task(subagent_type="agent-kenji-data-reader", prompt='{"task":"..."}')
-```
-
-**2. Override: Ask user permission first**
-If context suggests user wants direct action, ask:
-```
-AskUserQuestion:
-  question: "Hook wants me to delegate reading workspace/fields.ts to Kenji. Read directly instead?"
-  options:
-    - "Delegate to Kenji (recommended)"
-    - "Read directly this once"
-```
-
-**3. If user approves direct action:**
-1. Run the bypass command shown in block message (writes one-time bypass file)
-2. Retry the original tool call
-3. Bypass auto-deletes after one use
-
-**CRITICAL: NEVER bypass without explicitly asking user.**
-
-**Blocked tools:**
-- `Read` on `workspace/` → Kenji
-- `Glob`/`Grep` code searches → include in appropriate agent's prompt
-- `mcp__hailer__*` tools → appropriate agent (Kenji, Dmitri, Viktor, etc.)
-</delegation-blocks>
-
-<agent-routing>
-## Quick Routing
-
-| Category | Agent |
-|----------|-------|
-| Read workspace/ data, schemas, IDs | **Kenji** |
-| Read/fix/debug app or integration source code | **Giuseppe** or **Simple Writer** |
-| Write activities | **Dmitri** |
-| Workflows, fields, phases | **Helga** |
-| Calculated fields + name functions | **Alejandro** |
-| SQL insights | **Viktor** |
-| Build apps, fix app bugs, debug API calls | **Giuseppe** |
-| App UI/UX design specs | **UI Designer** |
-| Demo/mockup apps (no Hailer connection) | **Marco** |
-| Document templates (PDF/CSV) | **Ingrid** |
-| Activity movers (phase cascades) | **Igor** |
-| Monolith automations (webhooks, scheduled jobs) | **Ivan** |
-| Zapier integrations | **Zara** |
-| Tests (vitest, playwright, build checks) | **Tanya** |
-| Code review (bugs, security, best practices) | **Svetlana** |
-| LSP inspection (dead code, unused imports) | **Lars** |
-| Basic edits (ID swaps, string replacements) | **Simple Writer** |
-| Code simplification and cleanup | **Code Simplifier** |
-| API endpoint documentation | **Marcus** |
-| MCP tool development | **Gunther** |
-| Discussions (read, post, membership) | **Yevgeni** |
-| App permissions (grant/revoke access) | **Permissions Handler** |
-| Skill creation and agent updates | **Ada** |
-| New agent creation | **Builder** |
-| Marketplace publishing | **Marketplace Publisher** |
-| Marketplace PR review | **Marketplace Reviewer** |
-| Web research | **Web Search** |
-| Config audit (CLAUDE.md, hooks, agents) | **Bjorn** |
-
-Ambiguous routing? Load `delegation-routing` skill or run `/help:agents`.
-</agent-routing>
-
-<skill-system>
-## Skill System
-
-Skills are reusable knowledge files (`.claude/skills/<name>/SKILL.md`) that give agents domain-specific patterns, API references, and code templates. They keep agent definitions lean while providing deep expertise on demand.
-
-**Two types of skill loading:**
-
-**1. Auto-injected (no action needed):** Agents declare core skills in their frontmatter `skills:` field. The `SubagentStart` hook (`skill-injector.cjs`) reads the list, loads each `SKILL.md` from `.claude/skills/<name>/`, and injects it as `additionalContext` when the agent spawns.
-
-**2. On-demand (include in prompt):** For specialized tasks, tell the agent to load an extra skill via Skill tool. Only 6 agents have the Skill tool: Giuseppe, Helga, Viktor, Alejandro, Ingrid, Ada.
-
-| Agent | Task pattern | Add to prompt |
-|-------|-------------|---------------|
-| **Giuseppe** | Images, pictures, photos | `Load the hailer-apps-pictures skill.` |
-| **Giuseppe** | Publishing, deploy to prod | `Load the publish-hailer-app skill.` |
-| **Giuseppe** | REST API, direct HTTP calls | `Load the hailer-rest-api skill.` |
-| **Viktor** | JOIN, cross-workflow, linked data | `Load the insight-join-patterns skill.` |
-| **Viktor** | Field config, phases, workspace | `Load the SDK-ws-config-skill skill.` |
-| **Alejandro** | Field config, phases, workspace | `Load the SDK-ws-config-skill skill.` |
-| **Ingrid** | Field config, phases, workspace | `Load the SDK-ws-config-skill skill.` |
-
-**Adding core skills to an agent:**
-```yaml
-# In .claude/agents/agent-name.md frontmatter
-skills:
-  - SDK-ws-config-skill
-  - SDK-generate-skill
-```
-</skill-system>
-
-<task-usage>
-## Task Usage
-
-**Rule: 2+ agents or 3+ steps = create tasks.** Mark in_progress before starting, completed when done.
-
-Examples that need tasks:
-- "Apply these 4 learnings" → 4 tasks
-- "Run review squad" → 1 task per agent + 1 for fixes
-- "Build feature from PRD" → task per implementation step
-
-Skip tasks for: single-agent dispatch, quick lookups, simple edits
-</task-usage>
-
-<background-agents>
-## Background Execution
-
-All agents support `run_in_background: true`. Use it proactively for tasks that take a while (full test suites, multi-file reviews, deep research, app scaffolding). Tell the user "Running X in background" and keep working. Check results via `Read` on the `output_file` path or `TaskOutput(task_id, block=false)`. Multiple agents can run in background simultaneously.
-</background-agents>
-
-<error-detection-skills>
-## Error Detection Skills
-
-Load these skills when you detect common agent failure patterns:
-
-| Trigger | Load Skill |
-|---------|------------|
-| MCP validation fails ("Required" errors, empty receivedArgs) | `tool-parameter-usage` |
-| Agent returns success but tool actually failed | `tool-response-verification` |
-| Empty array/string errors in optional parameters | `optional-parameters` |
-| Agent outputs prose after JSON closing brace | `json-only-output` |
-
-These help you detect and correct issues before reporting to user.
-</error-detection-skills>
-
-<push-commands>
-When agents return `"status": "ready_to_push"`:
-```json
-{ "status": "ready_to_push", "commands": ["npm run fields-push"], "summary": "..." }
-```
-
-YOU run these commands via Bash tool. This triggers safety hooks.
-Do NOT ask user to run them manually.
-</push-commands>
-
-<needs-confirmation>
-When agents return `"status": "needs_confirmation"`:
-1. AskUserQuestion to confirm
-2. If yes: run the `safe_command` from result
-3. If no: report cancellation
-</needs-confirmation>
-
----
-
-<local-first>
-**Why local-first?** Workspace files are instant, free, and contain all structural data (IDs, field types, phases). API calls are slow, rate-limited, and only needed for live activity data. Always check workspace/ BEFORE API calls.
+## How to Work
+
+Do simple things directly. For complex tasks, spawn parallel sub-agents.
+
+**Model usage — conserve Opus for orchestration only:**
+- **You (Opus):** Orchestrate, synthesize results, make decisions. Do NOT write large code blocks yourself.
+- **Sub-agents (Sonnet):** Write code, build features, complex edits. Use `model: "sonnet"`.
+- **Sub-agents (Haiku):** Read files, search code, data lookups, reviews. Use `model: "haiku"`.
+- **Rule:** If a task takes more than ~20 lines of code, delegate to a sonnet sub-agent.
+
+**Speed rules:**
+- Do data discovery yourself (MCP calls are instant)
+- Spawn all agents in one message
+- Front-load context — agents should write code, not discover things
+- Background long tasks with `run_in_background: true`
+
+**Feature requests:** Ask "Want me to create a PRD first?" before implementing.
+
+## Skills
+
+Skills are in `.claude/skills/<name>/SKILL.md`. Load via the Skill tool.
+
+### Workspace & Config
+| Skill | Use when |
+|-------|----------|
+| `sdk-ws-config-skill` | Workflows, fields, phases, teams, groups, new project setup |
+| `sdk-function-fields` | Calculated fields, nameFunction |
+| `sdk-activity-patterns` | Creating/updating activities |
+| `sdk-insight-queries` | SQL-like insight queries, cross-workflow JOINs |
+| `sdk-document-templates` | PDF/CSV document templates |
+| `hailer-permissions-system` | Workflow permissions |
+
+### App Development
+| Skill | Use when |
+|-------|----------|
+| `hailer-app-builder` | Building Hailer apps (React/Chakra) |
+| `hailer-design-system` | Theme, colors, icons, layout, spacing, responsive design |
+| `hailer-apps-pictures` | Images/photos in apps |
+| `publish-hailer-app` | Publishing to production |
+
+### Integrations
+| Skill | Use when |
+|-------|----------|
+| `hailer-monolith-automations` | Webhook handlers, scheduled jobs, phase cascade bots |
+| `zapier-hailer-patterns` | Zapier integrations |
+| `integration-patterns` | General integration patterns |
+| `hailer-api-client` | HailerApiClient for backend |
+
+### Code Quality
+| Skill | Use when |
+|-------|----------|
+| `testing-patterns` | Vitest/playwright tests |
+| `api-documentation-patterns` | API endpoint docs |
+| `lsp-setup` | LSP code inspection |
+| `tool-builder` | Building new MCP tools |
+
+## Local-First Data
+
+Check workspace/ BEFORE making API calls.
 
 ```
 workspace/
@@ -221,150 +94,74 @@ workspace/
 
 LOCAL: Workflow/field/phase IDs, field types, labels, options
 API: Activity data, counts, discussion messages
-
 REFRESH: `npm run pull`
-</local-first>
 
-<hooks>
 ## Hooks
 
-26 CJS hooks in `.claude/hooks/` wired via `settings.json`. Each receives JSON on stdin, returns `{"decision": "allow"}` or `{"decision": "block", "message": "..."}` on stdout.
+4 safety hooks in `.claude/hooks/`:
 
-Key events: `SessionStart` (auto-loads context), `PreToolUse` (guards + delegation enforcement), `PostToolUse` (linting, logging, failure detection), `SubagentStart` (skill injection).
+- `session-start.cjs` — loads SESSION-HANDOFF.md on start
+- `bash-guard.cjs` — confirms destructive shell commands
+- `bulk-activity-guard.cjs` — confirms bulk activity writes
+- `publish-template-guard.cjs` — confirms template publishes
+- `context-watchdog.cjs` — monitors context usage
 
-**If hooks break after `npm install`:** Check `.claude/settings.json` paths, test with `node .claude/hooks/<script>.cjs --help`, or run `/clear-defaults`.
+## App Development
 
-PROTECTED (hooks confirm): npm run push, *-push, *-sync | SAFE: npm run pull, npm run generate
-</hooks>
+**Scaffold:** Always use `scaffold_hailer_app` MCP tool. Never copy an existing app.
 
-<app-development>
-## App Development Rules
+**Local dev:** Scaffold creates app at `http://localhost:3000`. Run `npm run dev`.
 
-**Default: Local development.** Scaffold creates a dev app at `http://localhost:3000` automatically. Run `npm run dev` and test inside Hailer iframe.
+**Publishing:** Only when user asks. Load `publish-hailer-app` skill.
 
-**Publishing: Only when user explicitly asks.** Tell Giuseppe to load the `publish-hailer-app` skill. It handles manifest validation, `publish_hailer_app` upload, and `update_app` to switch URL to production.
-
-**Builder mode for Giuseppe:** The `app-edit-guard` hook blocks file edits in `apps/` unless builder mode is active. Before spawning Giuseppe directly, run:
-```bash
-node .claude/hooks/app-edit-guard.cjs --agent-on
-```
-After Giuseppe completes:
-```bash
-node .claude/hooks/app-edit-guard.cjs --agent-off
-```
-The `/app-squad` command handles this automatically.
-</app-development>
-
----
-
-<session-protocol>
-## Session Protocol
-
-### Starting a Session
-SessionStart hook auto-loads SESSION-HANDOFF.md + DEVELOPMENT.md into context.
-1. Review auto-loaded context, update handoff (remove completed items)
-2. If handoff has "Pending Tasks" → recreate with `TaskCreate`
-3. If no DEVELOPMENT.md → offer to create one
-4. Briefly confirm current state before diving in
-
-### During a Session
-- **Feature request:** Ask "Want me to create a PRD?" even if user provides detailed plan. Only skip if user explicitly declines or already used `/prd`/`/autoplan`.
-- **Tasks:** 2+ agents or 3+ steps = create tasks. Mark in_progress before starting, completed when done. If it won't be done this session, put it in DEVELOPMENT.md backlog.
-- **Learnings:** Use `/learn <cat> <desc>` to capture gotchas and patterns.
-
-### Ending a Session
-- **Completion:** Update DEVELOPMENT.md + PRD status. Offer code-simplifier after features.
-- **Context full:** Update handoff, tell user to run `/handoff`.
-- **When to update DEVELOPMENT.md:** After features/milestones, architecture decisions, or discovering technical constraints.
-
-### Planning Workflow
-1. **Big picture → DEVELOPMENT.md** — Purpose, stack, roadmap linking to PRDs
-2. **Feature details → PRDs** (`docs/prd-*.md`) — One per feature, links back to roadmap
-3. **Implementation → Pick a PRD and build**
-
-**Quick start:** `/autoplan "description"` creates DEVELOPMENT.md + PRDs automatically.
-</session-protocol>
-
-<file-templates>
-## Documentation Hierarchy
-
-| File | Purpose |
-|------|---------|
-| **DEVELOPMENT.md** | Project status, backlog, tech stack, roadmap |
-| **docs/prd-*.md** | Feature requirements and implementation steps |
-| **SESSION-HANDOFF.md** | Current work, next steps, key context |
-
-**DEVELOPMENT.md** has sections: What This Project Does, Roadmap (linking PRDs), Current Status, Known Issues, Technical Decisions.
-**SESSION-HANDOFF.md** has sections: Current Work, Next Steps, Context.
-</file-templates>
-
-<customization>
-**Creating agents:** Load `agent-structure` skill for template.
-**Modify:** Edit `.claude/agents/*.md`
-**Disable:** Move to `docs/agents/`
-</customization>
-
-<config-source>
-## Config Source
-
-Agents, skills, hooks, and commands are in `.claude/` (project-local).
-Update from config repo: `cd ~/hailer-claude-config && git pull`, then copy to project.
-Learnings: `~/hailer-claude-config/inbox/`
-</config-source>
-
-<commands>
 ## Commands
 
-**Syntax:** `/command <param>` (angle brackets = required). `/help:topic` (colon = subtopic).
-
-**Essential:** `/save`, `/handoff`, `/prd`, `/autoplan`, `/ws-pull`, `/learn`
+`/command <param>` (angle brackets = required). `/help:topic` (colon = subtopic).
 
-**Squads** (multi-agent workflows):
+**Essential:** `/save`, `/handoff`, `/prd`, `/autoplan`, `/ws-pull`
 
-| Squad | Agents | Use for |
-|-------|--------|---------|
-| `/app-squad` | Kenji → Designer → Giuseppe → Tanya | Build apps end-to-end |
-| `/review-squad` | Svetlana + Lars + Tanya | Code review with auto-fix |
-| `/config-squad` | Helga → Alejandro → Viktor | Workflow + fields + insights |
-| `/hotfix-squad` | Tanya → Simple Writer → Svetlana | Quick bug fixes |
-| `/debug-squad` | Kenji + Viktor + Svetlana + Tanya | Parallel investigation |
-| `/swarm <desc>` | Auto-selected | Large-scale parallel work |
+**Squads:**
+| Squad | Use for |
+|-------|---------|
+| `/app-squad` | Build apps end-to-end |
+| `/review-squad` | Code review + tests |
+| `/config-squad` | Workflow + fields + insights |
+| `/hotfix-squad` | Quick bug fixes |
+| `/debug-squad` | Investigation |
+| `/swarm <desc>` | Large-scale parallel work |
 
-More squads + full command list: `/help:commands`
-</commands>
-
-<directory>
 ## Project Structure
 
 ```
+src/                 # MCP server source
 workspace/           # Hailer config - check FIRST for IDs
 apps/                # Frontend apps
 integrations/        # Backend services
-.claude/             # Agents, hooks, skills, commands (project-local)
-DEVELOPMENT.md       # Project status
+.claude/             # Skills, hooks, commands
 ```
-</directory>
 
-<sdk-gotchas>
-## Hailer SDK Quick Reference
+## When to Use SDK Files vs MCP Tools
+
+| Task | Use | NOT |
+|------|-----|-----|
+| Create/modify fields, phases, workflows | Edit `workspace/` files → `npm run push` | MCP `update_workflow_field` |
+| Create function fields | Edit `fields.ts` + `functions/` → `vitest` → `npm run fields-push` | MCP tools |
+| Read/write activity data | MCP tools (`list_activities`, `create_activity`, etc.) | Editing files |
+| Query/report on data | MCP `preview_insight`, `create_insight` | — |
+| Test existing function field code | MCP `test_function_field` (with `functionVariables`) | — |
 
-Common pitfalls that cause debugging loops - check these FIRST:
+**Function field workflow:** See Rules #5-8 at top of file.
+
+## Hailer SDK Gotchas
 
 | Gotcha | Correct | Wrong |
 |--------|---------|-------|
-| Activity field updates | `{type: "string", value: "x"}` wrapper | Raw value `"x"` |
-| `linkedfrom` in isolated-vm | Does NOT work - use ActivityLink field instead | Trying cross-link resolution |
-| Code in isolated-vm | Plain JavaScript only | TypeScript syntax (`as`, type annotations) |
-| Phase transitions | Exact string: `"Uudet"` → `"Tehty"` | Guessed names |
-| Field IDs | Read from workspace/ files | Guessing from labels |
+| Activity field updates | `{type: "string", value: "x"}` | Raw value `"x"` |
+| `linkedfrom` field type | Does NOT work in isolated-vm | Use `<` backlink dependency in functionVariables instead |
+| Code in isolated-vm | Plain JavaScript only | TypeScript syntax |
+| Phase transitions | Exact string match | Guessed names |
+| Field IDs | Read from workspace/ | Guessing from labels |
 | Dropdown values | `{data: [{value, label}]}` | `{options: [...]}` |
-| ActivityLink format | Plain string array of workflow IDs | Nested objects |
-
-**Rule:** When touching Hailer fields, ALWAYS read workspace/ first via Kenji. Never guess IDs or formats.
-</sdk-gotchas>
-
-<bulk-operations>
-## Bulk Tasks
+| ActivityLink format | Plain string array | Nested objects |
 
-For repetitive edits, use `/swarm` or headless mode (`claude -p "..." --allowedTools "Edit,Read,Grep,Glob"`). Act first — grep to find instances, then edit immediately.
-</bulk-operations>
+**Rule:** Always read workspace/ first. Never guess IDs or formats.