# Merlin - AI Development Platform
# Instructions for AI agents and LLMs to use this service

## What is Merlin?

Merlin is a complete AI-powered development system for Claude Code, Codex CLI, OpenCode, and Gemini CLI.
It provides: codebase intelligence (Sights API), 34+ specialist agents, 43 slash commands,
20 hooks, 10 hook templates, multi-runtime support, and autonomous orchestration.

## Install

npx create-merlin-brain

## MCP Server

Merlin Sights MCP server provides codebase context to AI coding agents.
Tools: merlin_get_context, merlin_search, merlin_find_files, merlin_get_brief, merlin_route,
       merlin_get_rules, merlin_get_conventions, merlin_save_rule, merlin_check_discovery,
       merlin_teach_discovery, merlin_get_project_status, merlin_get_selected_repo

## Key Features

- Vectorized codebase intelligence (Sights API) — instant context from first query
- 34+ specialist agents (security, frontend, performance, API design, testing, docs, etc.)
- Security hooks (prompt injection scanning, smart auto-approval, secret detection)
- Usage monitoring & cost tracking per agent
- Session intelligence (restore, search across sessions)
- Multi-runtime: Claude Code, Codex CLI, OpenCode, Gemini CLI
- Autonomous orchestration (Merlin Loop) with crash recovery and circuit breaker
- Prompt learning engine — outcomes tracked and scored for continuous improvement
- Behavior → Skill evolution pipeline
- 43 slash commands for full project lifecycle (/merlin:new-project, /merlin:execute-phase, etc.)
- 20 lifecycle hooks (session-start, pre-edit, post-edit, pre-compact, worktree, etc.)
- 10 opt-in community hook templates (auto-format, auto-test, auto-commit, branch-protection, etc.)
- Effort-based routing: high/medium/low effort mapped to model parameters per agent
- Discovery-first routing — checks Merlin Sights before routing to an agent
- Auto-update on session start via session-start.sh hook

## Agent Catalog (34 agents)

### Core Pipeline
- product-spec: Turn ideas into specs and user flows
- system-architect: Design architecture, check conflicts
- implementation-dev: Write production code, reuse patterns
- dry-refactor: Eliminate duplication, enforce DRY
- hardening-guard: Security validation, error handling
- tests-qa: Test design and QA strategy
- ops-railway: Deployment and infrastructure
- docs-keeper: Documentation updates

### Orchestration
- merlin: Primary router — routes tasks to specialists
- merlin-executor: Execute planned tasks step by step
- merlin-planner: Create detailed phased plans
- merlin-researcher: Deep research and technical analysis
- orchestrator-retrofit: Retrofit orchestration into existing projects

### Security
- merlin-security: OWASP audits, threat modeling, penetration testing mindset
- merlin-sast-reviewer: Static analysis security review
- merlin-secret-scanner: Detect secrets and credentials in code
- merlin-access-control-reviewer: Audit access control logic
- merlin-input-validator: Input validation and sanitization review

### Quality & Review
- merlin-reviewer: Code review with actionable feedback
- merlin-debugger: Systematic debugging and root cause analysis
- merlin-verifier: Verify work against requirements
- merlin-work-verifier: Cross-check task completion
- merlin-milestone-auditor: Audit milestone readiness
- merlin-integration-checker: Check integration contracts

### Specialists
- merlin-frontend: React/Vue, accessibility, UI patterns
- merlin-api-designer: REST/GraphQL API design
- merlin-performance: Performance analysis and optimization
- merlin-migrator: Database and code migration planning
- merlin-codebase-mapper: Codebase analysis and documentation
- merlin-dependency-auditor: Audit dependencies for issues
- elite-code-refactorer: Deep refactoring for quality and clarity
- context-guardian: Protect and maintain conversation context
- code-organization-supervisor: Enforce file size and structure rules
- remotion: Video/animation tooling specialist

## Slash Commands (43 commands)

Project lifecycle: new-project, create-roadmap, plan-phase, execute-phase, execute-plan,
                  complete-milestone, new-milestone, define-requirements, plan-milestone-gaps

Progress & status: progress, standup, verify-work, audit-milestone, readiness-gate,
                  check-todos, add-todo, list-phase-assumptions

Navigation: next, update, whats-new, help, workflow, loop-recipes

Research: research-project, research-phase, map-codebase

Execution: route, quick, execute-plan, execute-phase, sandbox, promote

Session: resume-work, pause-work, course-correct, debug, health, usage, profiles

Planning: add-phase, insert-phase, remove-phase, discuss-phase, discuss-milestone, plan-phase

Learning: optimize-prompts

## Hook Catalog (20 hooks)

session-start.sh — Load project context, sync agent state, check for updates
session-end.sh — Persist session state, write outcome data for learning engine
session-start-context.sh — Inject Merlin Sights context at session start
session-end-memory-sync.sh — Sync memory to cloud at session end
pre-edit-sights-check.sh — Check Sights context before file edits; blocks on secret detection
post-edit-logger.sh — Log file edits for analytics and session history
security-scanner.sh — Scan tool calls for prompt injection patterns
smart-approve.sh — Auto-approve low-risk tool calls, flag high-risk
check-file-size.sh — Warn when files approach 400-line limit
pre-compact.sh — Prepare context summary before compaction
subagent-context.sh — Inject context for subagent spawns
instructions-loaded.sh — Validate instructions integrity on load
task-completed-verify.sh — Trigger verification after task completion
teammate-idle-verify.sh — Verify work when teammate agent goes idle
worktree-create.sh — Initialize Merlin state in new worktrees
worktree-remove.sh — Clean up Merlin state when worktrees are removed
config-change.sh — Audit trail for configuration changes
notify-desktop.sh — Desktop notifications for session events
notify-webhook.sh — Webhook notifications for CI/CD integration
agent-sync.sh — Sync agent state across sessions (reference file)

## Hook Templates (10 opt-in templates)

auto-format.sh — Run formatter after every file edit
auto-test.sh — Run tests after every file edit
auto-commit.sh — Auto-commit after task completion (blocks on failure)
branch-protection.sh — Block commits to main/master directly
complexity-check.sh — Warn on high cyclomatic complexity
changelog-reminder.sh — Remind to update CHANGELOG on file changes
import-audit.sh — Audit import statements for issues
license-header.sh — Enforce license headers on new files
todo-tracker.sh — Track TODO comments across sessions
pr-description.sh — Generate PR descriptions from changes

## MCP Config Example

```json
{
  "mcpServers": {
    "merlin": {
      "command": "merlin-brain",
      "env": {
        "MERLIN_API_KEY": "your-api-key"
      }
    }
  }
}
```

## API Endpoints

### Public Wiki API
GET /api/public/wiki/{owner}/{repo}       # Full documentation
GET /api/public/wiki/{owner}/{repo}/agent # AI-optimized format
GET /api/public/explore                   # Browse analyzed repos

### Sights Index API
GET /api/public/sights/search             # Search public Sights catalog
GET /api/public/sights/recommend          # Get recommendations for a task
GET /api/public/sights/context/{owner}/{repo} # Get detailed Sight context

## Rate Limits

- Public endpoints: 100 requests/minute per IP
- Authenticated: 1000 requests/minute
- No auth required for public repositories

## AI Discovery Files

- Agent Manifest: https://merlin.build/agents.json
- OpenAPI Spec: https://merlin.build/.well-known/openapi.json
- AI Plugin: https://merlin.build/.well-known/ai-plugin.json
- LLM Instructions: https://merlin.build/llms.txt (this file)

## Links

Website: https://merlin.build
GitHub: https://github.com/sandman66666/merlin
npm: https://www.npmjs.com/package/create-merlin-brain
Sights Catalog: https://merlin.build/sights
Install: https://merlin.build/install
API Docs: https://merlin.build/.well-known/openapi.json
Contact: support@merlin.build