create-merlin-brain 3.22.0 → 4.0.0

package/files/hooks/statusline.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+#
+# Merlin Hook: Notification — HUD Statusline
+#
+# Outputs a single-line statusline for Claude Code's status bar with live
+# Merlin session metrics. Reads only local state files — no network calls.
+#
+# Output JSON:
+#   {"hookSpecificOutput":{"hookEventName":"Notification","statusLine":"..."}}
+#
+# Metrics included:
+#   - Merlin version  (from ~/.claude/merlin/VERSION)
+#   - Active agents   (from ~/.merlin/state/agents.json)
+#   - Task progress   (from ~/.merlin/state/tasks.json)
+#   - Session cost    (from ~/.merlin/state/session-cost.json)
+#   - Git branch      (git rev-parse, fast)
+#   - Context age     (from ~/.merlin/state/last-context.json)
+#   - Rate limit      (from ~/.merlin/state/rate-limit.json)
+#
+# Always exits 0 — purely advisory.
+#
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+STATE_DIR="${HOME}/.merlin/state"
+MERLIN_DIR="${HOME}/.claude/merlin"
+
+# ── Version ────────────────────────────────────────────────────────────────
+VERSION_FILE="${MERLIN_DIR}/VERSION"
+if [ -f "${VERSION_FILE}" ]; then
+  MERLIN_VERSION=$(cat "${VERSION_FILE}" 2>/dev/null | tr -d '[:space:]' || echo "--")
+else
+  MERLIN_VERSION="--"
+fi
+
+# ── Active agents ──────────────────────────────────────────────────────────
+AGENTS_FILE="${STATE_DIR}/agents.json"
+if [ -f "${AGENTS_FILE}" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    AGENT_COUNT=$(jq '.active // 0' "${AGENTS_FILE}" 2>/dev/null || echo "0")
+  else
+    AGENT_COUNT=$(grep -o '"active":[0-9]*' "${AGENTS_FILE}" 2>/dev/null | grep -o '[0-9]*$' || echo "0")
+  fi
+else
+  AGENT_COUNT="0"
+fi
+
+# ── Task progress ──────────────────────────────────────────────────────────
+TASKS_FILE="${STATE_DIR}/tasks.json"
+if [ -f "${TASKS_FILE}" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    TASKS_DONE=$(jq '.done // 0' "${TASKS_FILE}" 2>/dev/null || echo "0")
+    TASKS_TOTAL=$(jq '.total // 0' "${TASKS_FILE}" 2>/dev/null || echo "0")
+  else
+    TASKS_DONE=$(grep -o '"done":[0-9]*' "${TASKS_FILE}" 2>/dev/null | grep -o '[0-9]*$' || echo "0")
+    TASKS_TOTAL=$(grep -o '"total":[0-9]*' "${TASKS_FILE}" 2>/dev/null | grep -o '[0-9]*$' || echo "0")
+  fi
+  if [ "${TASKS_TOTAL}" -gt 0 ] 2>/dev/null; then
+    TASKS_DISPLAY="${TASKS_DONE}/${TASKS_TOTAL} tasks"
+  else
+    TASKS_DISPLAY="--"
+  fi
+else
+  TASKS_DISPLAY="--"
+fi
+
+# ── Session cost ───────────────────────────────────────────────────────────
+COST_FILE="${STATE_DIR}/session-cost.json"
+if [ -f "${COST_FILE}" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    COST_RAW=$(jq -r '.total // ""' "${COST_FILE}" 2>/dev/null || echo "")
+  else
+    COST_RAW=$(grep -o '"total":"[^"]*"' "${COST_FILE}" 2>/dev/null | cut -d'"' -f4 || echo "")
+    # Also try numeric total
+    if [ -z "${COST_RAW}" ]; then
+      COST_RAW=$(grep -o '"total":[0-9.]*' "${COST_FILE}" 2>/dev/null | grep -o '[0-9.]*$' || echo "")
+    fi
+  fi
+  if [ -n "${COST_RAW}" ] && [ "${COST_RAW}" != "null" ]; then
+    COST_DISPLAY="\$${COST_RAW}"
+  else
+    COST_DISPLAY="--"
+  fi
+else
+  COST_DISPLAY="--"
+fi
+
+# ── Git branch ─────────────────────────────────────────────────────────────
+GIT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "--")
+
+# ── Context freshness ──────────────────────────────────────────────────────
+CTX_FILE="${STATE_DIR}/last-context.json"
+if [ -f "${CTX_FILE}" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    LAST_TS=$(jq -r '.timestamp // ""' "${CTX_FILE}" 2>/dev/null || echo "")
+  else
+    LAST_TS=$(grep -o '"timestamp":[0-9]*' "${CTX_FILE}" 2>/dev/null | grep -o '[0-9]*$' || echo "")
+  fi
+  if [ -n "${LAST_TS}" ] && [ "${LAST_TS}" != "null" ] && [ "${LAST_TS}" != "" ]; then
+    NOW=$(date +%s)
+    ELAPSED=$(( NOW - LAST_TS ))
+    if [ "${ELAPSED}" -lt 60 ]; then
+      CTX_DISPLAY="${ELAPSED}s"
+    elif [ "${ELAPSED}" -lt 3600 ]; then
+      CTX_DISPLAY="$(( ELAPSED / 60 ))m"
+    else
+      CTX_DISPLAY="$(( ELAPSED / 3600 ))h"
+    fi
+  else
+    CTX_DISPLAY="--"
+  fi
+else
+  CTX_DISPLAY="--"
+fi
+
+# ── Rate limit status ──────────────────────────────────────────────────────
+RATE_FILE="${STATE_DIR}/rate-limit.json"
+if [ -f "${RATE_FILE}" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    RATE_STATUS=$(jq -r '.status // "OK"' "${RATE_FILE}" 2>/dev/null || echo "OK")
+  else
+    RATE_STATUS=$(grep -o '"status":"[^"]*"' "${RATE_FILE}" 2>/dev/null | cut -d'"' -f4 || echo "OK")
+  fi
+  # Normalize to OK / WARN / BLOCKED
+  case "${RATE_STATUS}" in
+    OK|ok)       RATE_DISPLAY="OK" ;;
+    WARN|warn)   RATE_DISPLAY="WARN" ;;
+    BLOCKED|blocked) RATE_DISPLAY="BLOCKED" ;;
+    *)           RATE_DISPLAY="OK" ;;
+  esac
+else
+  RATE_DISPLAY="OK"
+fi
+
+# ── Compose statusline ─────────────────────────────────────────────────────
+STATUSLINE="v${MERLIN_VERSION} | ${AGENT_COUNT} agents | ${TASKS_DISPLAY} | ${COST_DISPLAY} | ${GIT_BRANCH} | ctx:${CTX_DISPLAY} | rate:${RATE_DISPLAY}"
+
+# ── Output ─────────────────────────────────────────────────────────────────
+if command -v jq >/dev/null 2>&1; then
+  jq -n --arg sl "${STATUSLINE}" \
+    '{"hookSpecificOutput":{"hookEventName":"Notification","statusLine":$sl}}'
+else
+  # Escape double-quotes in statusline for safe inline embedding
+  SAFE="${STATUSLINE//\"/\\\"}"
+  printf '{"hookSpecificOutput":{"hookEventName":"Notification","statusLine":"%s"}}\n' "${SAFE}"
+fi
+
+exit 0

package/files/merlin/skills/SKILLS-INDEX.md

@@ -0,0 +1,82 @@
+# Merlin Skills Index
+
+When planning or executing a task, search this index to find relevant skills to load.
+Load a skill by reading its full .md file from the matching path. Only load 1-3 skills per task — pick the most relevant ones.
+
+Skills are prompt injections that enhance your capabilities for specific domains. They don't change what tools you have — they change how you think about the problem.
+
+## How to Use
+
+1. Read this index to find skills matching the current task
+2. Load the skill .md file (e.g., `~/.claude/merlin/skills/coding/react-patterns.md`)
+3. Follow the instructions in the skill while executing the task
+4. After the task: if the skill helped, note it. If it was wrong or outdated, improve it.
+
+## Coding > Frontend
+- `coding/react-patterns` — React component patterns, hooks, performance, server components — [react, nextjs, remix, vite]
+- `coding/tailwind-systems` — Design systems with Tailwind CSS, utility patterns, responsive — [tailwind, css, design-system]
+- `coding/css-3d` — Advanced CSS 3D transforms, perspective, immersive effects — [css, 3d, animation]
+- `coding/accessibility` — WCAG compliance, screen readers, keyboard nav, ARIA — [a11y, wcag, accessibility]
+- `coding/performance` — Core Web Vitals, bundle optimization, lazy loading, caching — [performance, lighthouse, web-vitals]
+- `coding/api-design` — RESTful conventions, versioning, OpenAPI specs, pagination — [api, rest, openapi, express]
+
+## Coding > Security
+- `coding/security-hardening` — OWASP top 10, input validation, auth patterns, XSS/CSRF — [security, owasp, auth, validation]
+
+## Testing
+- `testing/tdd-workflow` — Red-green-refactor, write tests first, Jest/Vitest/pytest — [tdd, testing, jest, vitest]
+- `testing/e2e-playwright` — End-to-end browser testing with Playwright — [playwright, e2e, testing, browser]
+
+## DevOps
+- `devops/docker-containers` — Dockerfiles, multi-stage builds, docker-compose, minimal images — [docker, containers, devops]
+- `devops/ci-cd` — GitHub Actions, CI pipelines, automated testing and deployment — [ci, cd, github-actions, deployment]
+
+## Design
+- `design/animation` — Smooth animations with Framer Motion, GSAP, CSS transitions — [animation, framer-motion, gsap, motion]
+
+## Research
+- `research/brainstorm` — Explore 3-5 approaches before committing, present pros/cons — [brainstorm, ideation, exploration]
+- `research/challenge` — Devil's advocate review, poke holes, identify weaknesses — [challenge, review, critique]
+- `research/deep-research` — Study problem domain before proposing, find best practices — [research, analysis, study]
+- `research/step-by-step` — Break task into numbered steps, get approval before building — [planning, steps, breakdown]
+
+## Execution
+- `coding/focus-mode` — GSD mode: minimal questions, maximum speed, make decisions — [focus, gsd, speed, autonomous]
+- `coding/loop` — Test-fix loop: run tests, fix failures, repeat until green — [loop, testing, iteration]
+- `coding/verify` — Validate results: run code, check output, confirm requirements met — [verify, validation, qa]
+- `coding/debug-mode` — Systematic debugging: reproduce, hypothesize, test, fix — [debug, troubleshoot, investigate]
+
+## Communication (Non-Coding)
+- `communication/whatsapp` — Two-way WhatsApp via Business API — direct, no middleware — [whatsapp, messaging, business-api]
+- `communication/telegram` — Telegram bot via Bot API — direct HTTP calls — [telegram, bot, bot-api]
+- `communication/dispatcher` — Central hub: receives from all channels, dispatches to specialists — [dispatcher, hub, routing]
+- `communication/email-gmail` — Gmail read/send/draft/search via API — [email, gmail, mailbox]
+- `communication/discord` — Discord bot: channels, roles, embeds, slash commands — [discord, bot]
+- `communication/slack` — Slack integration: channels, DMs, Block Kit, threads — [slack, messaging, workspace]
+- `communication/email` — Email automation: HTML emails, campaigns, auto-respond — [email, sendgrid, resend, smtp]
+- `communication/sms-voice` — Twilio SMS and voice: notifications, IVR, 2FA — [twilio, sms, voice, phone]
+
+## Automation (Non-Coding)
+- `automation/webhooks` — Receive/send webhooks, parse payloads, validate signatures — [webhooks, http, events]
+- `automation/zapier-make` — Connect 5000+ apps via Zapier/Make automation — [zapier, make, automation, integrations]
+- `automation/scheduled-tasks` — Cron jobs, recurring automations, periodic reports — [cron, scheduling, automation]
+- `automation/monitoring` — Health checks, uptime monitoring, auto-alerts — [monitoring, heartbeat, uptime]
+- `automation/payments` — Stripe: checkout, subscriptions, invoices, webhooks — [stripe, payments, billing]
+
+## Data (Non-Coding)
+- `data/google-sheets` — Read/write Google Sheets, formulas, batch operations — [sheets, google, spreadsheet]
+- `data/airtable` — Airtable CRUD, filters, linked records, attachments — [airtable, database, no-code]
+- `data/notion` — Notion pages, databases, content sync, knowledge base — [notion, wiki, knowledge-base]
+- `data/analytics` — Analytics platforms, dashboards, KPIs, reports — [analytics, mixpanel, amplitude, reporting]
+
+## Marketing (Non-Coding)
+- `marketing/social-media` — Post to Twitter/X, LinkedIn, Instagram, schedule content — [social, twitter, linkedin, instagram]
+
+---
+
+## Evolution
+
+Skills evolve. When you improve a skill after using it:
+1. Update the skill .md file with your improvement
+2. Increment the `version` in the frontmatter
+3. Add a line to `evolution` in the frontmatter describing what changed

package/files/merlin/skills/automation/payments.md

@@ -0,0 +1,14 @@
+---
+id: payments
+name: Stripe Payments
+domain: non-coding
+category: automation
+tags: [stripe, payments, billing, subscriptions, checkout]
+version: 1
+source: builtin
+successRate: 0
+usageCount: 0
+evolution: []
+---
+# Stripe Payments
+Interact with Stripe for payment processing. Create Checkout Sessions for one-time payments. Manage Subscriptions with billing cycles. Handle webhooks for payment events (payment_intent.succeeded, invoice.paid, customer.subscription.updated). Process refunds. Generate invoices. Always use Stripe's official SDK, never raw API calls with card numbers.

package/files/merlin/skills/automation/webhooks.md

@@ -0,0 +1,14 @@
+---
+id: webhooks
+name: Webhooks
+domain: non-coding
+category: automation
+tags: [webhooks, http, events, callbacks, integrations]
+version: 1
+source: builtin
+successRate: 0
+usageCount: 0
+evolution: []
+---
+# Webhooks
+Set up webhook endpoints to receive events from external services (GitHub, Stripe, Shopify, etc.) and send outgoing webhooks to trigger actions in other systems. Parse payloads, validate signatures (HMAC-SHA256), handle retries with idempotency keys, and route events to appropriate handlers. Always verify webhook authenticity before processing.

package/files/merlin/skills/coding/accessibility.md

@@ -0,0 +1,14 @@
+---
+id: accessibility
+name: Accessibility (a11y)
+domain: coding
+category: frontend
+tags: [a11y, wcag, accessibility, screen-reader, keyboard]
+version: 1
+source: builtin
+successRate: 0
+usageCount: 0
+evolution: []
+---
+# Accessibility (a11y)
+Ensure all UI elements are accessible. Add ARIA labels to interactive elements without visible text. Support full keyboard navigation (Tab, Enter, Escape, Arrow keys). Maintain color contrast ratios (WCAG AA: 4.5:1 for text, 3:1 for large text). Use semantic HTML (button not div, nav not div, heading hierarchy). Test with screen reader patterns. Every image needs alt text. Focus management on route changes and modal open/close.

package/files/merlin/skills/coding/api-design.md

@@ -0,0 +1,14 @@
+---
+id: api-design
+name: REST API Design
+domain: coding
+category: backend
+tags: [api, rest, openapi, express, fastify, pagination]
+version: 1
+source: builtin
+successRate: 0
+usageCount: 0
+evolution: []
+---
+# REST API Design
+Design RESTful APIs following best practices: proper HTTP verbs (GET=read, POST=create, PUT=replace, PATCH=update, DELETE=remove), meaningful status codes (200, 201, 204, 400, 401, 403, 404, 409, 500), cursor-based pagination for lists, consistent error response shape `{ error: string, code: string }`, API versioning via URL prefix (/v1/), and OpenAPI/Swagger documentation for every endpoint.

package/files/merlin/skills/coding/debug-mode.md

@@ -0,0 +1,14 @@
+---
+id: debug-mode
+name: Debug Mode
+domain: coding
+category: execution
+tags: [debug, troubleshoot, investigate, hypothesis]
+version: 1
+source: builtin
+successRate: 0
+usageCount: 0
+evolution: []
+---
+# Debug Mode
+Use systematic debugging: 1) Reproduce the issue with a minimal test case, 2) Form a hypothesis about the root cause, 3) Test the hypothesis with targeted investigation, 4) Fix or form new hypothesis. Show your reasoning at each step. Never shotgun-debug (changing random things hoping something works).

package/files/merlin/skills/coding/focus-mode.md

@@ -0,0 +1,14 @@
+---
+id: focus-mode
+name: Focus Mode (GSD)
+domain: coding
+category: execution
+tags: [focus, gsd, speed, autonomous, minimal-questions]
+version: 1
+source: builtin
+successRate: 0
+usageCount: 0
+evolution: []
+---
+# Focus Mode (GSD)
+Work in Get Stuff Done mode. Make reasonable decisions without asking. Build quickly and show results. Only ask questions when truly blocked. Prefer action over deliberation. If two approaches seem equally valid, pick the simpler one and move on.

package/files/merlin/skills/coding/loop.md

@@ -0,0 +1,14 @@
+---
+id: loop
+name: Test-Fix Loop
+domain: coding
+category: execution
+tags: [loop, testing, iteration, fix]
+version: 1
+source: builtin
+successRate: 0
+usageCount: 0
+evolution: []
+---
+# Test-Fix Loop
+After implementing, run tests. If tests fail, fix the issues and re-run. Repeat until all tests pass. Show the test results at each iteration. Maximum 5 iterations — if still failing after 5, stop and explain what's wrong.

package/files/merlin/skills/coding/performance.md

@@ -0,0 +1,14 @@
+---
+id: performance
+name: Performance Optimization
+domain: coding
+category: frontend
+tags: [performance, lighthouse, web-vitals, bundle, lazy-loading]
+version: 1
+source: builtin
+successRate: 0
+usageCount: 0
+evolution: []
+---
+# Performance Optimization
+Optimize for performance. Use code splitting and dynamic imports for route-level chunks. Lazy load below-fold images and heavy components. Set proper Cache-Control headers for static assets. Minimize main thread blocking (defer non-critical JS). Target Core Web Vitals: LCP < 2.5s, FID < 100ms, CLS < 0.1. Use `next/image` or equivalent for automatic image optimization.

package/files/merlin/skills/coding/react-patterns.md

@@ -0,0 +1,51 @@
+---
+id: react-patterns
+name: React Patterns
+domain: coding
+category: frontend
+tags: [react, nextjs, remix, vite, hooks, components, server-components]
+version: 1
+source: builtin
+successRate: 0
+usageCount: 0
+evolution: []
+---
+
+# React Patterns
+
+You are an expert in modern React patterns. Apply these when building or reviewing React code.
+
+## Component Architecture
+- Prefer function components with hooks over class components
+- Co-locate related code: component + hook + types + styles in the same directory
+- Extract custom hooks when logic is reused across 2+ components
+- Use `React.memo()` only when profiling shows re-render cost (not preemptively)
+
+## Hooks
+- `useState` for simple local state; `useReducer` when state transitions are complex
+- `useCallback` and `useMemo` only when passing to memoized children or expensive computations
+- Custom hooks should start with `use` and return a typed object (not a tuple for >2 values)
+- `useEffect` cleanup: always return cleanup functions for subscriptions, timers, event listeners
+
+## Server Components (Next.js 13+)
+- Default to Server Components — only add `'use client'` when you need interactivity, hooks, or browser APIs
+- Data fetching belongs in Server Components (no useEffect for initial data)
+- Pass serializable props from Server → Client components (no functions, no classes)
+
+## Performance
+- Lazy load heavy components: `const Heavy = dynamic(() => import('./Heavy'), { ssr: false })`
+- Use `Suspense` boundaries around async components
+- Virtualize long lists (react-window, @tanstack/virtual)
+- Image optimization: next/image with explicit width/height, priority for above-fold
+
+## Error Handling
+- Wrap route segments with Error Boundaries
+- Use `error.tsx` convention in Next.js App Router
+- Show meaningful fallback UI, not blank screens
+- Log errors to a service (Sentry, LogRocket) in production
+
+## State Management
+- Local state first (useState/useReducer) — don't reach for global state prematurely
+- URL state for shareable UI state (search params, filters)
+- Server state via TanStack Query or SWR (not Redux for API data)
+- Global client state only for truly app-wide concerns (auth, theme, locale)

package/files/merlin/skills/coding/security-hardening.md

@@ -0,0 +1,56 @@
+---
+id: security-hardening
+name: Security Hardening
+domain: coding
+category: security
+tags: [security, owasp, auth, validation, xss, csrf, injection]
+version: 1
+source: builtin
+successRate: 0
+usageCount: 0
+evolution: []
+---
+
+# Security Hardening
+
+Apply security best practices to every piece of code you write or review.
+
+## Input Validation
+- Validate ALL user input at the boundary (API route handler, form submission)
+- Use Zod, Joi, or equivalent schema validation — never trust `typeof` alone
+- Whitelist allowed values rather than blacklisting dangerous ones
+- Validate types, lengths, ranges, formats before processing
+
+## Injection Prevention
+- SQL: Use parameterized queries / prepared statements. NEVER string-concatenate user input into SQL
+- NoSQL: Validate query operators. Reject `$gt`, `$regex` etc. from user input
+- Command injection: Use `execFile` (not `exec`). Never pass user input to shell commands
+- Template injection: Sanitize before rendering in templates
+
+## Authentication
+- Hash passwords with bcrypt/argon2 (cost factor >= 12)
+- Use constant-time comparison for secrets (`crypto.timingSafeEqual`)
+- JWTs: short expiry (15min access, 7d refresh), validate `iss`, `aud`, `exp`
+- Session IDs: cryptographically random, >= 128 bits entropy
+
+## Authorization
+- Check permissions on EVERY protected endpoint (not just the frontend)
+- Verify resource ownership: `WHERE user_id = $authenticatedUser AND id = $resourceId`
+- Use middleware for role checks, not inline if-statements
+- Principle of least privilege: default deny, explicitly grant
+
+## XSS Prevention
+- React/Vue auto-escape by default — but `dangerouslySetInnerHTML` / `v-html` bypasses it
+- Sanitize HTML with DOMPurify before rendering user content
+- Set `Content-Security-Policy` headers (no inline scripts)
+- HttpOnly + Secure + SameSite cookies for session tokens
+
+## CSRF Protection
+- SameSite=Lax cookies (minimum) or SameSite=Strict
+- CSRF tokens for state-changing operations if using cookies
+- Verify `Origin` / `Referer` headers on sensitive endpoints
+
+## Error Handling
+- Never expose stack traces, SQL errors, or internal paths to the client
+- Use generic error messages: "Something went wrong" (log the real error server-side)
+- Return consistent error shapes: `{ error: string, code: string }`

package/files/merlin/skills/coding/verify.md

@@ -0,0 +1,14 @@
+---
+id: verify
+name: Verify Results
+domain: coding
+category: execution
+tags: [verify, validation, qa, check]
+version: 1
+source: builtin
+successRate: 0
+usageCount: 0
+evolution: []
+---
+# Verify Results
+After completing the task, verify the result. Run the code, check the output, and confirm it meets the requirements. Report any issues found. Never claim "done" without actually testing.

package/files/merlin/skills/communication/dispatcher.md

@@ -0,0 +1,40 @@
+---
+id: dispatcher
+name: Communications Dispatcher
+domain: non-coding
+category: communication
+tags: [dispatcher, hub, routing, whatsapp, telegram, email, always-on]
+version: 1
+source: builtin
+successRate: 0
+usageCount: 0
+evolution: []
+---
+
+# Communications Dispatcher
+
+You are the central communications hub. You receive messages from multiple channels (WhatsApp, Telegram, email) and either respond directly or dispatch tasks to specialist agents.
+
+## Your Role
+- You are ALWAYS listening. You run on a heartbeat — checking channels continuously.
+- When a message arrives, you decide: can you handle it, or does it need a specialist?
+- You respond in the same channel the message came from.
+- You maintain context across channels — if someone emails you, then WhatsApps about the same topic, you connect the dots.
+
+## Channels
+- **WhatsApp**: Two-way messaging via OpenClaw. You receive and send messages.
+- **Telegram**: Bot integration. Respond to commands and conversations.
+- **Email**: Read from connected Gmail mailboxes. Draft and send replies.
+
+## Dispatch Rules
+- Simple questions, scheduling, reminders → handle yourself
+- Code tasks → dispatch to implementation-dev or bug-doctor
+- Content/writing → dispatch to docs-keeper
+- Research → dispatch to researcher
+- Security concerns → dispatch to hardening-guard
+
+## Response Style
+- Be concise in WhatsApp/Telegram (people expect short messages)
+- Be more detailed in email (people expect structured responses)
+- Always confirm when dispatching: "I'm sending this to [Agent] — I'll update you when it's done"
+- Proactively update the user on dispatched task progress

package/files/merlin/skills/communication/email-gmail.md

@@ -0,0 +1,31 @@
+---
+id: email-gmail
+name: Gmail Integration
+domain: non-coding
+category: communication
+tags: [email, gmail, mailbox, inbox, send, read, draft]
+version: 1
+source: builtin
+successRate: 0
+usageCount: 0
+evolution: []
+---
+
+# Gmail Integration
+
+You can read from and send emails through connected Gmail mailboxes.
+
+## Capabilities
+- Read new emails from connected inboxes
+- Search emails by sender, subject, date, or content
+- Draft and send replies
+- Create new emails with rich formatting
+- Manage labels and organize inbox
+- Handle multiple mailboxes (personal + work)
+
+## Rules
+- Never auto-send without user confirmation (draft first, send on approval)
+- Summarize long email threads before responding
+- Detect urgency: flag emails that need immediate attention
+- Respect "do not reply" and unsubscribe patterns
+- Keep sent email tone professional unless user specifies otherwise

package/files/merlin/skills/communication/telegram.md

@@ -0,0 +1,50 @@
+---
+id: telegram
+name: Telegram Direct
+domain: non-coding
+category: communication
+tags: [telegram, bot, direct, bot-api, two-way]
+version: 2
+source: builtin
+successRate: 0
+usageCount: 0
+evolution:
+  - "v2: Direct Telegram Bot API — no external dependencies"
+---
+
+# Telegram Direct Integration
+
+Send and receive Telegram messages directly via the Bot API. No middleware — direct HTTP calls.
+
+## Receiving Messages
+Telegram sends updates to our webhook. Each update has: chat_id, sender info, message text, message_id, date.
+
+## Sending Messages
+```
+POST https://api.telegram.org/bot{BOT_TOKEN}/sendMessage
+Content-Type: application/json
+
+{
+  "chat_id": 123456789,
+  "text": "Your message here",
+  "parse_mode": "Markdown"
+}
+```
+
+## Key API Methods
+- `sendMessage` — send text (supports Markdown and HTML)
+- `sendPhoto` / `sendDocument` — send media files
+- `editMessageText` — update a sent message (good for progress updates)
+- `deleteMessage` — remove a message
+- `sendChatAction` — show "typing..." indicator
+- `getUpdates` — poll for messages (fallback if webhook fails)
+
+## Setup
+- Create a bot via @BotFather on Telegram → get BOT_TOKEN
+- Set webhook: `POST https://api.telegram.org/bot{TOKEN}/setWebhook?url=https://merlin.build/api/hooks/telegram/{userId}`
+
+## Response Rules
+- Markdown formatting supported (bold, italic, code blocks)
+- Messages can be longer than WhatsApp — up to 4096 chars
+- Use "typing..." action before long responses: `sendChatAction({ chat_id, action: "typing" })`
+- Reply to specific messages with `reply_to_message_id`

package/files/merlin/skills/communication/whatsapp.md

@@ -0,0 +1,47 @@
+---
+id: whatsapp
+name: WhatsApp Direct
+domain: non-coding
+category: communication
+tags: [whatsapp, messaging, business-api, direct, two-way]
+version: 2
+source: builtin
+successRate: 0
+usageCount: 0
+evolution:
+  - "v2: Direct WhatsApp Business API — no external dependencies"
+---
+
+# WhatsApp Direct Integration
+
+Send and receive WhatsApp messages directly via the WhatsApp Business API. No middleware, no OpenClaw — direct API calls.
+
+## Receiving Messages
+Messages arrive via webhook → Merlin API → your Claude session. Each message has: sender phone, text, timestamp, message type (text/image/document).
+
+## Sending Messages
+```
+POST https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}/messages
+Authorization: Bearer {WHATSAPP_ACCESS_TOKEN}
+Content-Type: application/json
+
+{
+  "messaging_product": "whatsapp",
+  "to": "1234567890",
+  "type": "text",
+  "text": { "body": "Your message here" }
+}
+```
+
+## Message Types
+- Text: simple messages
+- Template: pre-approved messages (required for initiating conversations)
+- Media: images, documents, audio (send URL or upload)
+- Interactive: buttons, lists (for structured choices)
+
+## Response Rules
+- Keep under 300 chars — mobile reading
+- Use line breaks, not bullets
+- Respond within seconds
+- Break long content into 2-3 sequential messages
+- Mark messages as read: POST `/{PHONE_NUMBER_ID}/messages` with `{ status: "read", message_id: "..." }`

package/files/merlin/skills/data/google-sheets.md

@@ -0,0 +1,14 @@
+---
+id: google-sheets
+name: Google Sheets
+domain: non-coding
+category: data
+tags: [sheets, google, spreadsheet, data]
+version: 1
+source: builtin
+successRate: 0
+usageCount: 0
+evolution: []
+---
+# Google Sheets
+Read from and write to Google Sheets. Pull data for analysis, update cells, create new sheets, and use Sheets as a simple database. Support for batch operations (batchUpdate for multiple writes) and formula generation. Use the Google Sheets API v4 with service account credentials for server-side access.