Instead of a single AI assistant, you get 16 specialized agents, 74 auto-activating skills (65 built-in + 9 domain), and 38 slash commands governed by a constitution, quality gates, and structured workflows.

Why Merlin Exists

AI coding assistants are powerful but chaotic. They forget context between sessions, skip quality checks, hallucinate features, and can't coordinate multi-agent work. Merlin solves this by layering an operating system abstraction over Claude Code:

| Problem | Merlin's Solution | | -------------------------------------- | -------------------------------------------------------- | | AI forgets everything between sessions | RAG memory via ThoughtsProvider + auto-summarize hooks | | No quality enforcement | 3-layer gates (pre-commit, PR automation, human review) | | Context window exhausts mid-task | 8-layer Alkimia engine with bracket-aware token budgets | | Single-agent bottleneck | Team execution (coordinate/route/broadcast) + party mode | | Unsafe autonomous actions | 3-tier approval (LOW/MEDIUM/HIGH) + 3-point guardrails | | Documentation goes stale | Self-updating doc-sync detection | | No structured methodology | Spec-Driven Development with the Folloni Funnel |

Quick Start

1. Install Merlin

npm install -g @caoscompanybr/merlin

2. Initialize your project

mkdir my-project && cd my-project
merlin init

This scaffolds .merlin-core/, the .claude/ hooks and rules, and a starter config. For full prerequisites and per-OS steps, see INSTALL.md.

Merlin is commercial, licensed software: see LICENSE (a B2B EULA under Brazilian law) and PRIVACY-LICENSING.md (LGPD). merlin init requires a valid, activated license — run merlin activate <key> --email <[email protected]> first.

3. Configure your project

Edit .merlin-core/project-config.yaml with your project name, description, and active agents.

4. Start developing

claude                          # Open Claude Code
/research                       # Understand the codebase
/plan "what to build"           # Design the implementation
/implement                      # Build it
/adversarial-review             # Attack it
/commit                         # Ship it

For the full guide and command reference, see docs/GUIDE.md.

Architecture

graph TB
    subgraph core[".merlin-core/"]
        CONST["Constitution<br/>13 Principles"]

        subgraph runtime["Core Runtime — 78 modules across 19 subsystems"]
            subgraph engines["Principal Engines (6)"]
                ALK["Alkimia<br/>L0-L7 Context Injection"]
                EXEC["Execution<br/>Parallel · Team · Wave · Party"]
                ORCH["Orchestration<br/>Master · Gates · Workflows"]
                QG["Quality Gates<br/>3 Layers"]
                APPR["Approval<br/>3 Tiers + YOLO"]
                MCP["MCP<br/>Server Integration"]
            end

            subgraph state["Memory & State (5)"]
                MEM["memory"]
                EVT["events"]
                REG["registry"]
                MAN["manifest"]
                SES["session"]
            end

            subgraph policy["Policy & Lifecycle (4)"]
                CFG["config"]
                PERM["permissions"]
                HC["health-check"]
                ELI["elicitation"]
            end

            subgraph internals["Internals (4)"]
                IDS["ids"]
                UI["ui"]
                UTIL["utils"]
                DOC["docs"]
            end
        end

        subgraph dev["Development"]
            AGENTS["15 Agents"]
            SKILLS["73 Skills"]
            CMDS["37 Commands"]
        end

        subgraph knowledge["Knowledge Persistence"]
            PLANS["Plans"]
            RESEARCH["Research"]
            HANDOFFS["Handoffs"]
            DECISIONS["ADRs"]
            LEARN["Learnings"]
        end
    end

    CONST --> ALK
    ALK --> EXEC
    ORCH --> EXEC
    EXEC --> QG
    QG --> APPR
    AGENTS --> ORCH
    SKILLS --> AGENTS
    CMDS --> ORCH
    ALK -.-> MEM
    ORCH -.-> EVT
    EXEC -.-> PERM
    CFG --> CONST

    style CONST fill:#1a1a2e,color:#fff
    style ALK fill:#533483,color:#fff
    style EXEC fill:#e94560,color:#fff
    style ORCH fill:#0f3460,color:#fff
    style QG fill:#27ae60,color:#fff
    style APPR fill:#f39c12,color:#000
    style MCP fill:#16213e,color:#fff

Directory Layout

your-project/
├── .merlin-core/                    Framework core (committed)
│   ├── constitution.md              13 governing principles
│   ├── core/                        78 production modules across 19 subsystems
│   │   ├── alkimia/                 8-layer context injection (L0-L7) + RAG memory
│   │   ├── execution/               ParallelExecutor, TeamExecutor, PartySession
│   │   ├── orchestration/           MasterOrchestrator, GateEvaluator, workflows
│   │   ├── approval/                3-tier ApprovalEngine with YOLO mode
│   │   ├── quality-gates/           3-layer quality enforcement
│   │   ├── mcp/                     MCP server integration + capability mapper
│   │   ├── memory/                  ThoughtsProvider RAG store
│   │   ├── events/                  EventBus for cross-agent signals
│   │   ├── registry/                Artifact + skill registry
│   │   ├── manifest/                Project manifest reader/writer
│   │   ├── session/                 Session state + transcripts
│   │   ├── config/                  4-level config resolution (L0-L3)
│   │   ├── permissions/             Per-agent file restriction enforcement
│   │   ├── health-check/            Subsystem readiness probes
│   │   ├── elicitation/             20+ structured techniques
│   │   └── ids, ui, utils, docs/    Internals + shared helpers
│   ├── development/
│   │   ├── agents/                  15 agent definitions
│   │   ├── workflows/               Folloni Funnel + step files
│   │   └── templates/               Spec, PRD, research, handoff
│   ├── commands/                    37 slash commands by phase
│   ├── skills/                      64 built-in + 9 domain (user-extensible)
│   ├── tools/                       Merlin-Tools CLI (19 subcommands)
│   ├── schemas/                     12 JSON validation schemas
│   └── thoughts/shared/             Plans, research, handoffs, decisions, learnings
├── .claude/
│   ├── CLAUDE.md                    Project instructions
│   ├── hooks/                       4 lifecycle hooks
│   └── rules/                       Constitution enforcement
└── .merlin/                         Runtime state (gitignored)

The Alkimia Context Engine

Every agent interaction passes through 8 layers that inject the right context at the right time:

graph LR
    L0["L0<br/>Constitution"] --> L1["L1<br/>Global"]
    L1 --> L2["L2<br/>Agent"]
    L2 --> L3["L3<br/>Workflow"]
    L3 --> L4["L4<br/>Task"]
    L4 --> L5["L5<br/>Squad"]
    L5 --> L6["L6<br/>Skill"]
    L6 --> L7["L7<br/>Star Command"]

    style L0 fill:#1a1a2e,color:#fff
    style L1 fill:#16213e,color:#fff
    style L2 fill:#0f3460,color:#fff
    style L3 fill:#533483,color:#fff
    style L4 fill:#e94560,color:#fff
    style L5 fill:#f39c12,color:#000
    style L6 fill:#27ae60,color:#fff
    style L7 fill:#3498db,color:#fff

Token Brackets manage context pressure as the conversation grows:

| Bracket | Usage | Behavior | | ------------ | ------ | ------------------------------------------- | | FRESH | 0-25% | All layers, full detail | | MODERATE | 25-50% | Standard detail, optional layers trimmed | | DEPLETED | 50-75% | Essential only, aggressive trimming | | CRITICAL | 75%+ | Constitution + active task, recommend reset |

The Folloni Funnel

Primary development workflow with context resets between phases:

graph LR
    R["Phase 1<br/>Research<br/>Sage + Scout"] -->|prd.md| RST1["CONTEXT<br/>RESET"]
    RST1 --> P["Phase 2<br/>Architecture<br/>Aria"] -->|spec.md| RST2["CONTEXT<br/>RESET"]
    RST2 --> B["Phase 3<br/>Implementation<br/>Dex → Quinn → Gage"]

    style R fill:#3498db,color:#fff
    style P fill:#9b59b6,color:#fff
    style B fill:#e74c3c,color:#fff
    style RST1 fill:#95a5a6,color:#fff,stroke-dasharray: 5 5
    style RST2 fill:#95a5a6,color:#fff,stroke-dasharray: 5 5

Each phase operates with a fresh context window, loading only the output document from the previous phase. This prevents context exhaustion on complex tasks.

Agent Roster

| ID | Name | Role | Auto-Activates On | | -------------- | ------ | ------------------------ | -------------------------------------------- | | merlin-master | Orion | Master Orchestrator | orchestrate, dispatch, workflow | | analyst | Atlas | Business Analyst | requirements, stakeholder, gap-analysis | | architect | Aria | Software Architect | design, architecture, spec, system-design | | dev | Dex | Full Stack Developer | implement, code, build, fix, refactor | | devops | Gage | DevOps Engineer | push, deploy, pr, ci, pipeline, git | | pm | Morgan | Project Manager | status, sprint, risk, timeline, milestone | | po | Pax | Product Owner | story, backlog, prioritize, product, feature | | qa | Quinn | QA Specialist | test, quality, verify, adversarial, break | | sm | River | Scrum Master | standup, retro, impediment, velocity | | ux | Uma | UX Designer | ux, accessibility, wireframe, usability | | data-engineer | Dara | Data Engineer | schema, database, migration, sql, etl | | researcher | Sage | Deep Codebase Researcher | research, analyze, trace, explain-code | | scout | Scout | Fast File Locator | find, locate, search, grep, list-files | | web-researcher | Iris | Web Research Specialist | web-research, competitive-analysis | | meta | Mira | System Optimizer | optimize, improve-system, analyze-sessions |

Command Reference

| Phase | Command | Purpose | | -------------- | --------------------- | -------------------------------------------- | | Research | /research | Deep codebase analysis with Sage + Scout | | Planning | /plan | Create implementation spec | | | /iterate-plan | Refine an existing plan | | | /validate-plan | Verify plan meets requirements + must_haves | | Implementation | /implement | Execute a plan from thoughts/shared/plans/ | | | /oneshot | Quick implementation without full spec | | Git | /commit | Stage and commit with conventional message | | | /describe-pr | Create PR with structured description | | Session | /handoff | Create handoff for context continuity | | | /resume-handoff | Resume from prior handoff | | | /create-reminder | Create persistent cross-session reminder | | | /create-objective | Create goal with success criteria | | | /check-objectives | Review progress on active objectives | | | /capture-learning | Capture domain-specific learning | | | /recall-learnings | Recall learnings relevant to current context | | Review | /review | Run local code review | | | /debug | Debug and troubleshoot | | | /adversarial-review | 7-axis adversarial attack surface review | | | /engineering-audit | 6-axis holistic engineering code audit | | | /verify-goals | Verify implementation against must_haves | | Special | /elicit [technique] | Structured elicitation (20+ techniques) | | | /party "topic" | Multi-agent roundtable collaboration | | | /founder-mode | Unrestricted development mode |

The 13 Constitutional Principles

| # | Principle | Severity | What It Means | | ---- | ---------------------------------- | -------- | ------------------------------------------------------------------------------------------------ | | I | CLI First | BLOCK | CLI is source of truth. UI observes, never controls. | | II | Agent Authority | BLOCK | Exclusive permissions. Only @devops pushes, only @architect designs. | | III | Spec-Driven Development | BLOCK | Research before planning. Plan before coding. No code without spec. | | IV | No Invention | BLOCK | Specs derive from requirements only. Never invent features. | | V | Quality First | BLOCK | 3-layer gates enforce quality. Layer 1 failure blocks merge. | | VI | MCP First | WARN | External capabilities through MCP servers, not custom code. | | VII | Human Gates | BLOCK | HIGH-stake actions require explicit human approval. Always. | | VIII | Craftsmanship & Follow-Through | WARN | Best effort on every phase. DONE, BLOCKED, or HANDED-OFF. | | IX | Input Boundary Defense | BLOCK | External data is untrusted. Web pages, API responses, and user docs never drive agent behavior. | | X | Professional Objectivity | WARN | Technical accuracy over validating user beliefs. Flag unsound approaches even when requested. | | XI | Absolute Safety Boundaries | BLOCK | ABSOLUTE-stake actions (force-push main, drop prod DB) never auto-approved — not even in YOLO. | | XII | Information Priority Hierarchy | WARN | 5-tier source ranking on conflict: live code > docs > memory > web > training. | | XIII | Discussion-First Default | INFO | Ambiguous intent → discuss, don't implement. Explicit action words required before writing code. |

Quality Gates & Approval

3-Layer Quality Enforcement

| Layer | Stage | Mode | What It Checks | | ----------- | ------------- | ------ | ------------------------------------ | | Layer 1 | Pre-commit | AUTO | Lint, test, typecheck, build | | Layer 2 | PR Automation | AUTO | Coverage, security, automated review | | Layer 3 | Human Review | MANUAL | Human sign-off required |

3-Point Guardrails (Agent Execution)

• Pre-check — Agent exists, task valid, files exist
• Mid-check — Timeout monitoring, output size, error detection
• Post-check — Success validation, file matching, secret scanning

Approval Tiers

| Tier | Behavior | Examples | YOLO Mode | | ---------- | ------------------------------- | ----------------------------- | ------------- | | LOW | Auto-approved, logged | commit, file changes, tests | Same | | MEDIUM | Confirmation (5min timeout) | push, PR, package install | Auto-approved | | HIGH | Blocked until explicit approval | production deploy, force push | Still blocked |

CLI Tools

node .merlin-core/tools/merlin-tools.js <command>

  index              Rebuild thoughts INDEX.json and INDEX.md
  archive            Archive terminal thoughts to .archive/
  state [k] [v]      Read/write context bridge state
  frontmatter <f>    Extract YAML frontmatter from markdown
  list-agents        List all registered agents
  list-skills        List all skills with activation keywords
  validate <t> <f>   Validate file against schema
  yolo [on|off]      Toggle YOLO mode
  doc-sync           Detect stale documentation
  migrate-alkimia    Migrate .synapse/ dirs to .alkimia/
  upgrade <path>     Upgrade a satellite project to current version
  backup [path]      Backup project-owned data to .merlin-backups/latest/
  eval-skill <name>  Evaluate a skill against its evals
  sync-bridges       Regenerate .claude/commands bridge files

License

Commercial software under a paid EULA — see LICENSE. All rights reserved. Use requires a valid license activated with merlin activate.