create-merlin-brain 3.22.0 → 3.23.0

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.

package/files/merlin/skills/design/animation.md

@@ -0,0 +1,14 @@
+---
+id: animation
+name: Motion Design
+domain: coding
+category: design
+tags: [animation, framer-motion, gsap, motion, transitions]
+version: 1
+source: builtin
+successRate: 0
+usageCount: 0
+evolution: []
+---
+# Motion Design
+Create smooth, performant animations. Use Framer Motion for React component enter/exit/layout animations. Use CSS transitions for simple hover/focus states (cheaper than JS). Use GSAP for complex timelines and scroll-triggered animations. Always target 60fps — prefer `transform` and `opacity` (GPU-composited) over `width`, `height`, `top`, `left` (trigger layout). Use `will-change` sparingly. Respect `prefers-reduced-motion` media query.

package/files/merlin/skills/devops/docker-containers.md

@@ -0,0 +1,14 @@
+---
+id: docker-containers
+name: Docker & Containers
+domain: coding
+category: devops
+tags: [docker, containers, dockerfile, docker-compose, devops]
+version: 1
+source: builtin
+successRate: 0
+usageCount: 0
+evolution: []
+---
+# Docker & Containers
+Use Docker best practices: multi-stage builds (build stage + runtime stage), minimal base images (alpine/distroless), non-root users (USER node), health checks (HEALTHCHECK CMD), proper layer caching (COPY package.json first, then npm install, then COPY source), .dockerignore for node_modules/dist/.git. Docker Compose for multi-service local dev. Pin image versions (node:20-alpine, not node:latest).

package/files/merlin/skills/research/brainstorm.md

@@ -0,0 +1,14 @@
+---
+id: brainstorm
+name: Brainstorm
+domain: research
+category: ideation
+tags: [brainstorm, ideation, exploration, approaches]
+version: 1
+source: builtin
+successRate: 0
+usageCount: 0
+evolution: []
+---
+# Brainstorm
+Before implementing, brainstorm 3-5 different approaches. Present them to the user with pros/cons for each. Wait for selection before proceeding. Consider: simplicity, maintainability, performance, time-to-implement, and alignment with existing architecture.

package/files/merlin/skills/testing/tdd-workflow.md

@@ -0,0 +1,58 @@
+---
+id: tdd-workflow
+name: Test-Driven Development
+domain: coding
+category: testing
+tags: [tdd, testing, jest, vitest, pytest, red-green-refactor]
+version: 1
+source: builtin
+successRate: 0
+usageCount: 0
+evolution: []
+---
+
+# Test-Driven Development
+
+Follow the RED-GREEN-REFACTOR cycle for every feature.
+
+## The Cycle
+1. **RED** — Write a failing test that describes the desired behavior
+2. **GREEN** — Write the minimum code to make the test pass
+3. **REFACTOR** — Clean up without changing behavior, tests still pass
+
+## Rules
+- Never write production code without a failing test first
+- Each test should test ONE behavior (not one function — one behavior)
+- Test names describe the behavior: `should return 404 when user not found`
+- Run tests after every change — the cycle takes minutes, not hours
+
+## What to Test
+- Happy path (expected input → expected output)
+- Edge cases (empty input, null, boundary values, max length)
+- Error cases (invalid input, network failure, permission denied)
+- Integration points (API contracts, database queries, external services)
+
+## What NOT to Test
+- Implementation details (private methods, internal state)
+- Framework code (React rendering, Express routing)
+- Third-party libraries (they have their own tests)
+- Trivial code (getters, setters, simple pass-through)
+
+## Test Structure
+```
+describe('[Unit Under Test]', () => {
+  describe('[Scenario]', () => {
+    it('should [expected behavior] when [condition]', () => {
+      // Arrange — set up test data and dependencies
+      // Act — call the function / trigger the behavior
+      // Assert — verify the result
+    });
+  });
+});
+```
+
+## Mocking
+- Mock at boundaries: external APIs, databases, file system, time
+- Don't mock the thing you're testing
+- Prefer dependency injection over module mocking
+- Reset mocks between tests (`afterEach(() => jest.restoreAllMocks())`)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-merlin-brain",
-  "version": "3.22.0",
-  "description": "Merlin - The Ultimate AI Brain for Claude Code. One install: workflows, agents, loop, and Sights MCP server.",
+  "version": "3.23.0",
+  "description": "Merlin - The Ultimate AI Brain for Claude Code, Codex, and other AI CLIs. One install: workflows, agents, loop, and Sights MCP server.",
   "type": "module",
   "main": "./dist/server/index.js",
   "bin": {
@@ -23,6 +23,8 @@
   "keywords": [
     "claude",
     "claude-code",
+    "codex",
+    "codex-cli",
     "merlin",
     "mcp",
     "model-context-protocol",