create-merlin-brain 3.6.0 → 3.6.2

package/files/loop/lib/blend.sh

@@ -0,0 +1,731 @@
+#!/usr/bin/env bash
+#
+# ╔═══════════════════════════════════════════════════════════════════════════╗
+# ║  MERLIN BLEND ENGINE - Dynamic Agent Fusion                               ║
+# ║  Creates a custom-optimized specialist for EVERY task                      ║
+# ╚═══════════════════════════════════════════════════════════════════════════╝
+#
+# No static routing. No shortcuts. For every single task:
+# 1. Analyze the task — extract ALL relevant domains
+# 2. Score every available agent against the task
+# 3. Pull the top agents' system prompts
+# 4. Blend into a single, coherent custom specialist
+# 5. Inject Sights codebase context
+# 6. Write a temporary agent .md file
+# 7. Return the path — caller spawns with `claude --agent <path>`
+#
+# The blended agent is NOT a concatenation. It's a coherent new identity:
+# - Primary agent: full system prompt (the core expertise)
+# - Secondary agents: extracted guidelines and patterns (supporting expertise)
+# - Sights context: real codebase knowledge (files, patterns, conventions)
+#
+# Used by both merlin-session.sh and merlin-loop.sh.
+#
+
+# Colors
+: "${RESET:=\033[0m}"
+: "${BOLD:=\033[1m}"
+: "${DIM:=\033[2m}"
+: "${CYAN:=\033[36m}"
+: "${MAGENTA:=\033[35m}"
+: "${GREEN:=\033[32m}"
+: "${YELLOW:=\033[33m}"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Agent Registry
+# keyword → agent_name mapping with primary (3pt) and secondary (1pt) keywords
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Agent directories to search (in order of priority)
+AGENTS_DIR="${HOME}/.claude/agents"
+AGENTS_FALLBACK_DIR=""
+
+# All agents and their scoring keywords
+# Format: BLEND_<safename>_PRIMARY="word1 word2 ..."
+# Format: BLEND_<safename>_SECONDARY="word3 word4 ..."
+# Format: BLEND_<safename>_FILE="agent-name"  (the .md filename without extension)
+# Format: BLEND_<safename>_LABEL="Display Name"
+
+BLEND_impl_PRIMARY="implement build create add feature code write develop make"
+BLEND_impl_SECONDARY="function class module service endpoint handler"
+BLEND_impl_FILE="implementation-dev"
+BLEND_impl_LABEL="Implementation Developer"
+
+BLEND_security_PRIMARY="security auth login password encrypt token 2fa oauth jwt"
+BLEND_security_SECONDARY="validate sanitize session csrf xss injection rate-limit"
+BLEND_security_FILE="hardening-guard"
+BLEND_security_LABEL="Security Specialist"
+
+BLEND_architect_PRIMARY="architect architecture schema model database design service structure"
+BLEND_architect_SECONDARY="migration pattern microservice monolith layer module boundary"
+BLEND_architect_FILE="system-architect"
+BLEND_architect_LABEL="System Architect"
+
+BLEND_spec_PRIMARY="plan spec feature idea milestone roadmap requirement user-story"
+BLEND_spec_SECONDARY="scope priority acceptance-criteria mvp"
+BLEND_spec_FILE="product-spec"
+BLEND_spec_LABEL="Product Spec Writer"
+
+BLEND_test_PRIMARY="test spec coverage unit integration e2e jest pytest mocha"
+BLEND_test_SECONDARY="mock stub fixture snapshot regression assertion"
+BLEND_test_FILE="tests-qa"
+BLEND_test_LABEL="Testing Specialist"
+
+BLEND_debug_PRIMARY="debug fix error bug crash issue trace exception"
+BLEND_debug_SECONDARY="stacktrace log breakpoint reproduce regression"
+BLEND_debug_FILE="merlin-debugger"
+BLEND_debug_LABEL="Debugging Specialist"
+
+BLEND_refactor_PRIMARY="refactor cleanup dry organize split extract consolidate"
+BLEND_refactor_SECONDARY="rename simplify reduce dedup modularize"
+BLEND_refactor_FILE="dry-refactor"
+BLEND_refactor_LABEL="Refactoring Specialist"
+
+BLEND_frontend_PRIMARY="ui component react vue frontend svelte next nuxt"
+BLEND_frontend_SECONDARY="css layout responsive tailwind shadcn radix form modal"
+BLEND_frontend_FILE="merlin-frontend"
+BLEND_frontend_LABEL="Frontend Specialist"
+
+BLEND_api_PRIMARY="api endpoint route rest graphql webhook"
+BLEND_api_SECONDARY="handler controller middleware request response status"
+BLEND_api_FILE="merlin-api-designer"
+BLEND_api_LABEL="API Designer"
+
+BLEND_deploy_PRIMARY="deploy infra railway docker env pipeline ci cd"
+BLEND_deploy_SECONDARY="container kubernetes health monitoring"
+BLEND_deploy_FILE="ops-railway"
+BLEND_deploy_LABEL="DevOps Specialist"
+
+BLEND_docs_PRIMARY="docs readme documentation comment"
+BLEND_docs_SECONDARY="jsdoc typedoc markdown guide tutorial"
+BLEND_docs_FILE="docs-keeper"
+BLEND_docs_LABEL="Documentation Specialist"
+
+BLEND_perf_PRIMARY="performance optimize speed slow memory latency"
+BLEND_perf_SECONDARY="cache profiling bottleneck benchmark bundle"
+BLEND_perf_FILE="merlin-performance"
+BLEND_perf_LABEL="Performance Specialist"
+
+BLEND_migrate_PRIMARY="migrate migration schema database alter table column"
+BLEND_migrate_SECONDARY="seed rollback version upgrade"
+BLEND_migrate_FILE="merlin-migrator"
+BLEND_migrate_LABEL="Migration Specialist"
+
+BLEND_video_PRIMARY="video animation remotion render composition"
+BLEND_video_SECONDARY="frame sequence transition spring interpolate"
+BLEND_video_FILE="remotion"
+BLEND_video_LABEL="Video/Remotion Specialist"
+
+BLEND_secaudit_PRIMARY="audit penetration vulnerability scan"
+BLEND_secaudit_SECONDARY="cve exploit disclosure compliance"
+BLEND_secaudit_FILE="merlin-security"
+BLEND_secaudit_LABEL="Security Auditor"
+
+BLEND_codeorg_PRIMARY="organize structure folder directory file-structure"
+BLEND_codeorg_SECONDARY="barrel index module re-export"
+BLEND_codeorg_FILE="code-organization-supervisor"
+BLEND_codeorg_LABEL="Code Organization Specialist"
+
+BLEND_review_PRIMARY="review pr pull-request code-review"
+BLEND_review_SECONDARY="feedback comment approve change"
+BLEND_review_FILE="merlin-reviewer"
+BLEND_review_LABEL="Code Reviewer"
+
+BLEND_swift_PRIMARY="swift swiftui appkit ios macos iphone"
+BLEND_swift_SECONDARY="ipad xcode cocoa uikit swiftdata coredata swift6"
+BLEND_swift_FILE="apple-swift-expert"
+BLEND_swift_LABEL="Apple Swift Expert"
+
+BLEND_android_PRIMARY="android kotlin compose jetpack"
+BLEND_android_SECONDARY="material gradle room hilt viewmodel coroutine play-store aab apk"
+BLEND_android_FILE="android-expert"
+BLEND_android_LABEL="Android Expert"
+
+BLEND_uidesign_PRIMARY="design-system accessibility wcag visual-hierarchy ux"
+BLEND_uidesign_SECONDARY="color-palette typography spacing wireframe mockup hig"
+BLEND_uidesign_FILE="ui-designer"
+BLEND_uidesign_LABEL="UI Designer"
+
+BLEND_uibuild_PRIMARY="shadcn radix component-library form table"
+BLEND_uibuild_SECONDARY="card modal dialog sheet dropdown popover cva"
+BLEND_uibuild_FILE="ui-builder"
+BLEND_uibuild_LABEL="UI Builder"
+
+BLEND_anim_PRIMARY="animation motion framer gsap transition"
+BLEND_anim_SECONDARY="scroll-animation parallax spring keyframe animate lottie"
+BLEND_anim_FILE="animation-expert"
+BLEND_anim_LABEL="Animation Expert"
+
+BLEND_marketing_PRIMARY="email campaign drip marketing funnel"
+BLEND_marketing_SECONDARY="newsletter automation conversion ab-test analytics tracking utm landing-page growth"
+BLEND_marketing_FILE="marketing-automation"
+BLEND_marketing_LABEL="Marketing Automation"
+
+BLEND_desktop_PRIMARY="electron tauri desktop native ipc"
+BLEND_desktop_SECONDARY="window tray preload menu dmg nsis appimage code-sign notarize"
+BLEND_desktop_FILE="desktop-app-expert"
+BLEND_desktop_LABEL="Desktop App Expert"
+
+# All agent keys (order matters — first match tiebreaker)
+# Domain specialists listed first for priority
+BLEND_ALL_AGENTS="swift android desktop uidesign uibuild anim marketing security architect api frontend test debug refactor deploy video migrate perf secaudit codeorg review docs spec impl"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Scoring Engine
+# Returns scored agents sorted by relevance
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Score a single agent against a task
+# Returns the score (integer)
+_blend_score_agent() {
+  local agent_key="$1"
+  local task_lower="$2"
+  local score=0
+
+  # Get primary keywords
+  local primary_var="BLEND_${agent_key}_PRIMARY"
+  local primary="${!primary_var}"
+
+  # Get secondary keywords
+  local secondary_var="BLEND_${agent_key}_SECONDARY"
+  local secondary="${!secondary_var}"
+
+  # Score primary keywords (3 points each)
+  for word in $primary; do
+    if echo "$task_lower" | grep -qw "$word"; then
+      score=$((score + 3))
+    fi
+  done
+
+  # Score secondary keywords (1 point each)
+  for word in $secondary; do
+    if echo "$task_lower" | grep -qw "$word"; then
+      score=$((score + 1))
+    fi
+  done
+
+  echo "$score"
+}
+
+# Score ALL agents against a task
+# Returns: "score:key:label:file" lines sorted by score descending
+blend_score_all() {
+  local task="$1"
+  local task_lower
+  task_lower=$(echo "$task" | tr '[:upper:]' '[:lower:]')
+
+  local results=""
+
+  for key in $BLEND_ALL_AGENTS; do
+    local score
+    score=$(_blend_score_agent "$key" "$task_lower")
+    local label_var="BLEND_${key}_LABEL"
+    local file_var="BLEND_${key}_FILE"
+    local label="${!label_var}"
+    local file="${!file_var}"
+
+    results="${results}${score}:${key}:${label}:${file}\n"
+  done
+
+  # Sort by score descending, return all with score > 0 plus impl as fallback
+  echo -e "$results" | sort -t: -k1 -nr | head -20
+}
+
+# Get the top N agents for a task (those with score > 0)
+# Returns newline-separated "score:key:label:file" entries
+blend_get_top_agents() {
+  local task="$1"
+  local max_agents="${2:-4}"  # Default: blend up to 4 agents
+
+  local all_scored
+  all_scored=$(blend_score_all "$task")
+
+  local count=0
+  local result=""
+
+  while IFS=: read -r score key label file; do
+    [ -z "$score" ] && continue
+    # Always include agents with score > 0
+    if [ "$score" -gt 0 ] && [ "$count" -lt "$max_agents" ]; then
+      result="${result}${score}:${key}:${label}:${file}\n"
+      count=$((count + 1))
+    fi
+  done <<< "$all_scored"
+
+  # If nothing scored, use implementation-dev as default
+  if [ "$count" -eq 0 ]; then
+    result="0:impl:Implementation Developer:implementation-dev\n"
+  fi
+
+  echo -e "$result"
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Prompt Extraction
+# Read an agent .md file and extract its content (without frontmatter)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Extract the body (everything after frontmatter --- ... ---) from an agent file
+_blend_extract_body() {
+  local agent_file="$1"
+  if [ ! -f "$agent_file" ]; then
+    echo ""
+    return
+  fi
+
+  # Skip YAML frontmatter (between first --- and second ---)
+  awk 'BEGIN{skip=0; found_first=0}
+    /^---$/ {
+      if (!found_first) { found_first=1; skip=1; next }
+      else if (skip) { skip=0; next }
+    }
+    !skip { print }
+  ' "$agent_file"
+}
+
+# Extract a condensed version of an agent (key guidelines and rules only)
+# This is used for secondary agents in the blend — we want their expertise
+# but not their full operational instructions
+_blend_extract_condensed() {
+  local agent_file="$1"
+  local body
+  body=$(_blend_extract_body "$agent_file")
+
+  if [ -z "$body" ]; then
+    echo ""
+    return
+  fi
+
+  # Strategy: Extract sections that contain guidelines, rules, patterns, principles
+  # Skip operational stuff like "When called:", "MERLIN CHECK", "Output format"
+  local condensed=""
+  local in_relevant_section=false
+  local section_lines=0
+  local max_section_lines=30  # Cap each section
+
+  while IFS= read -r line; do
+    # Detect section headers
+    if echo "$line" | grep -qE '^#{1,3} '; then
+      local header_lower
+      header_lower=$(echo "$line" | tr '[:upper:]' '[:lower:]')
+
+      # Relevant sections: anything about guidelines, rules, patterns, expertise
+      if echo "$header_lower" | grep -qiE "guideline|rule|pattern|principle|check|security|validation|error|logging|performance|best.practice|convention|architecture|design|testing|approach"; then
+        in_relevant_section=true
+        section_lines=0
+        condensed="${condensed}\n${line}\n"
+        continue
+      else
+        in_relevant_section=false
+      fi
+    fi
+
+    # Include lines from relevant sections (capped)
+    if [ "$in_relevant_section" = true ] && [ "$section_lines" -lt "$max_section_lines" ]; then
+      condensed="${condensed}${line}\n"
+      section_lines=$((section_lines + 1))
+    fi
+  done <<< "$body"
+
+  # If we couldn't extract sections, take the first ~40 lines as a summary
+  if [ -z "$condensed" ]; then
+    echo "$body" | head -40
+  else
+    echo -e "$condensed"
+  fi
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Sights Context Injection
+# Pull fresh codebase context for the task
+# ═══════════════════════════════════════════════════════════════════════════════
+
+_blend_fetch_sights_context() {
+  local task="$1"
+  local context=""
+
+  # Try merlin CLI first (fastest)
+  if command -v merlin &>/dev/null; then
+    local sights_context
+    sights_context=$(merlin context "$task" 2>/dev/null || echo "")
+    if [ -n "$sights_context" ] && ! echo "$sights_context" | grep -qi "error\|not found\|not connected"; then
+      context="$sights_context"
+    fi
+
+    # Also pull relevant files
+    local files_context
+    files_context=$(merlin files "$task" 2>/dev/null || echo "")
+    if [ -n "$files_context" ] && ! echo "$files_context" | grep -qi "error\|not found"; then
+      context="${context}\n\n${files_context}"
+    fi
+
+    # Pull conventions
+    local conventions
+    conventions=$(merlin rules 2>/dev/null || echo "")
+    if [ -n "$conventions" ] && ! echo "$conventions" | grep -qi "no coding rules"; then
+      context="${context}\n\n## Coding Rules (MUST FOLLOW)\n${conventions}"
+    fi
+  fi
+
+  echo -e "$context"
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Cloud Agent Pull
+# Check if there are specialist agents in Merlin cloud for this domain
+# ═══════════════════════════════════════════════════════════════════════════════
+
+_blend_pull_cloud_agents() {
+  local task="$1"
+  local api_key="${MERLIN_API_KEY:-}"
+  local api_url="${MERLIN_API_URL:-https://api.merlin.build}"
+
+  # Skip if no API key
+  [ -z "$api_key" ] && return
+
+  # Check cloud for relevant agent definitions
+  local cloud_response
+  cloud_response=$(curl -s --max-time 5 \
+    -H "Authorization: Bearer $api_key" \
+    "$api_url/api/agents-sync/recommend?task=$(echo "$task" | head -c 100 | sed 's/ /+/g')" 2>/dev/null || echo "")
+
+  if [ -n "$cloud_response" ] && echo "$cloud_response" | grep -q '"content"'; then
+    # Extract agent content and inject
+    local agent_content
+    agent_content=$(echo "$cloud_response" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    agents = data if isinstance(data, list) else data.get('agents', [])
+    for a in agents[:2]:  # Max 2 cloud agents
+        print(f\"## Cloud Specialist: {a.get('name', 'Unknown')}\")
+        print(a.get('content', a.get('instructions', '')))
+        print()
+except: pass
+" 2>/dev/null || echo "")
+    echo "$agent_content"
+  fi
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Chain-of-Verification (CoVe) — Selective Self-Verification
+# Based on Meta AI Research. Only injected for high-stakes task types where
+# being wrong has real consequences. Zero overhead for simple tasks.
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Task types that benefit from CoVe verification
+COVE_TASK_TYPES="security architect debug review secaudit migrate"
+
+# Check if task warrants CoVe
+_blend_needs_cove() {
+  local primary_key="$1"
+  for cove_type in $COVE_TASK_TYPES; do
+    if [ "$primary_key" = "$cove_type" ]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+# Generate the CoVe instruction block
+_blend_cove_block() {
+  local task_domain="$1"
+
+  cat << 'COVE_BLOCK'
+
+---
+
+## Reasoning Protocol: Chain-of-Verification (CoVe)
+
+This task domain requires high accuracy. Follow this 4-step verification process:
+
+### Step 1: Generate Baseline
+Produce your initial solution/analysis.
+
+### Step 2: Plan Verification Questions
+Generate 3-5 specific, falsifiable questions that would expose errors in your baseline:
+- Factual claims that could be wrong
+- Assumptions that might not hold
+- Edge cases you might have missed
+- Security or correctness gaps
+
+### Step 3: Independent Verification
+Answer each verification question AS IF you had never seen your baseline.
+Do NOT reference or defend your initial answer. Treat each as a standalone query.
+Examine the actual codebase independently for each question.
+
+### Step 4: Final Verified Response
+Compare verification answers against your baseline. Where they conflict,
+trust the verification. Produce a corrected final response.
+
+CRITICAL: Step 3 must be truly independent. Never justify your baseline — interrogate it.
+COVE_BLOCK
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# THE BLEND ENGINE
+# This is the core — creates a custom agent for every task
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Main entry point: blend agents for a task
+# Returns: path to the temporary blended agent .md file
+#
+# Usage:
+#   agent_path=$(blend_for_task "refactor the Python authentication API")
+#   claude --agent "$agent_path" -p "your prompt"
+#
+blend_for_task() {
+  local task="$1"
+  local session_dir="${2:-/tmp/merlin-blend-$$}"
+
+  mkdir -p "$session_dir"
+
+  # 1. Score all agents
+  local top_agents
+  top_agents=$(blend_get_top_agents "$task" 4)
+
+  # Parse the top agents
+  local primary_file="" primary_label="" primary_score=0
+  local secondary_files=() secondary_labels=()
+  local agent_count=0
+  local all_labels=""
+
+  while IFS=: read -r score key label file; do
+    [ -z "$score" ] && continue
+    [ -z "$file" ] && continue
+
+    agent_count=$((agent_count + 1))
+
+    if [ $agent_count -eq 1 ]; then
+      # Primary agent — full prompt
+      primary_file="$file"
+      primary_label="$label"
+      primary_score="$score"
+      all_labels="**${label}** (primary)"
+    else
+      # Secondary agents — condensed expertise
+      secondary_files+=("$file")
+      secondary_labels+=("$label")
+      all_labels="${all_labels}, ${label}"
+    fi
+  done <<< "$top_agents"
+
+  # 2. Read primary agent's full prompt
+  local primary_path="${AGENTS_DIR}/${primary_file}.md"
+  local primary_body=""
+  if [ -f "$primary_path" ]; then
+    primary_body=$(_blend_extract_body "$primary_path")
+  fi
+
+  # 3. Read secondary agents' condensed prompts
+  local secondary_sections=""
+  for i in "${!secondary_files[@]}"; do
+    local sec_file="${secondary_files[$i]}"
+    local sec_label="${secondary_labels[$i]}"
+    local sec_path="${AGENTS_DIR}/${sec_file}.md"
+
+    if [ -f "$sec_path" ]; then
+      local condensed
+      condensed=$(_blend_extract_condensed "$sec_path")
+      if [ -n "$condensed" ]; then
+        secondary_sections="${secondary_sections}\n\n## Additional Expertise: ${sec_label}\n\n${condensed}"
+      fi
+    fi
+  done
+
+  # 4. Fetch Sights context
+  local sights_context=""
+  sights_context=$(_blend_fetch_sights_context "$task")
+
+  # 5. Pull cloud agents (if any)
+  local cloud_context=""
+  cloud_context=$(_blend_pull_cloud_agents "$task")
+
+  # 6. Determine the optimal model
+  # Complex multi-domain tasks → opus. Simple single-domain → sonnet.
+  local model="sonnet"
+  if [ "$agent_count" -ge 3 ] || [ "$primary_score" -ge 6 ]; then
+    model="sonnet"  # Still sonnet for speed, but could be opus for really complex tasks
+  fi
+
+  # 7. Build the blended agent identity
+  local blend_name="merlin-blend-$(date +%s)"
+  local description="Custom specialist blending: ${all_labels}"
+
+  # 8. Assemble the blended agent file
+  local blend_path="${session_dir}/${blend_name}.md"
+
+  cat > "$blend_path" << BLEND_EOF
+---
+name: ${blend_name}
+description: ${description}
+model: ${model}
+tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch
+permissionMode: bypassPermissions
+maxTurns: 200
+---
+
+# Custom Specialist — Blended for This Task
+
+You are a custom AI specialist dynamically created for this specific task. You combine deep expertise from multiple domains into a single coherent identity.
+
+**Your expertise blend:** ${all_labels}
+
+You don't just know one thing. You understand the intersections. When security meets API design, when testing meets performance, when frontend meets architecture — you see the full picture and make integrated decisions.
+
+---
+
+## Primary Expertise: ${primary_label}
+
+${primary_body}
+
+${secondary_sections}
+
+BLEND_EOF
+
+  # Add Sights context if available
+  if [ -n "$sights_context" ]; then
+    cat >> "$blend_path" << SIGHTS_EOF
+
+---
+
+## Codebase Context (from Merlin Sights — REAL project knowledge)
+
+This is YOUR codebase. These are the actual files, patterns, and conventions. Follow them.
+
+${sights_context}
+
+SIGHTS_EOF
+  fi
+
+  # Add cloud agents if available
+  if [ -n "$cloud_context" ]; then
+    cat >> "$blend_path" << CLOUD_EOF
+
+---
+
+## Specialist Knowledge (from Merlin Cloud)
+
+${cloud_context}
+
+CLOUD_EOF
+  fi
+
+  # Add CoVe verification protocol for high-stakes tasks
+  # This is selective — only security, architecture, debugging, review, audit, migration
+  local primary_key=""
+  if [ -n "$top_agents" ]; then
+    primary_key=$(echo "$top_agents" | head -1 | cut -d: -f2)
+  fi
+
+  if _blend_needs_cove "$primary_key" 2>/dev/null; then
+    _blend_cove_block "$primary_key" >> "$blend_path"
+  fi
+
+  # Add the task as final instruction
+  cat >> "$blend_path" << TASK_EOF
+
+---
+
+## Your Task
+
+${task}
+
+Execute this task using your full blended expertise. Be thorough, be smart, and ship clean code.
+TASK_EOF
+
+  echo "$blend_path"
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Display Helpers
+# Show what the blend engine decided (for the user)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Show the blend decision to the user
+blend_show_decision() {
+  local task="$1"
+
+  local top_agents
+  top_agents=$(blend_get_top_agents "$task" 4)
+
+  echo -e "${MAGENTA}${BOLD}  Blend:${RESET}"
+
+  local count=0
+  while IFS=: read -r score key label file; do
+    [ -z "$score" ] && continue
+    [ -z "$file" ] && continue
+    count=$((count + 1))
+
+    if [ $count -eq 1 ]; then
+      echo -e "    ${GREEN}${BOLD}[primary]${RESET} ${label} ${DIM}(score: ${score})${RESET}"
+    else
+      echo -e "    ${CYAN}[blend]${RESET}   ${label} ${DIM}(score: ${score})${RESET}"
+    fi
+  done <<< "$top_agents"
+
+  # Show Sights status
+  if command -v merlin &>/dev/null; then
+    echo -e "    ${CYAN}[sights]${RESET}  Codebase context will be injected"
+  fi
+
+  # Show CoVe status
+  local primary_key=""
+  primary_key=$(echo "$top_agents" | head -1 | cut -d: -f2)
+  if _blend_needs_cove "$primary_key" 2>/dev/null; then
+    echo -e "    ${YELLOW}[CoVe]${RESET}    Chain-of-Verification enabled (high-stakes task)"
+  fi
+}
+
+# Show a one-line summary of the blend
+blend_summary() {
+  local task="$1"
+
+  local top_agents
+  top_agents=$(blend_get_top_agents "$task" 4)
+
+  local labels=""
+  while IFS=: read -r score key label file; do
+    [ -z "$label" ] && continue
+    if [ -z "$labels" ]; then
+      labels="$label"
+    else
+      labels="${labels} + ${label}"
+    fi
+  done <<< "$top_agents"
+
+  echo "$labels"
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Convenience: Spawn with blend (one function call)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Blend and spawn in one call
+# Returns the claude output
+blend_and_spawn() {
+  local task="$1"
+  local extra_context="${2:-}"
+  local session_dir="${3:-/tmp/merlin-blend-$$}"
+
+  # Create the blended agent
+  local agent_path
+  agent_path=$(blend_for_task "$task" "$session_dir")
+
+  # Build the prompt (task + any extra context)
+  local prompt="$task"
+  if [ -n "$extra_context" ]; then
+    prompt="${prompt}\n\n## Additional Context\n\n${extra_context}"
+  fi
+
+  # Spawn
+  local output
+  output=$(claude --agent "$agent_path" --output-format text -p "$prompt" 2>&1)
+  local exit_code=$?
+
+  # Clean up temp agent file
+  # rm -f "$agent_path"  # Keep for debugging — uncomment for production
+
+  echo "$output"
+  return $exit_code
+}

package/files/loop/merlin-loop.sh

@@ -40,6 +40,7 @@ source "$SCRIPT_DIR/lib/context.sh"
 source "$SCRIPT_DIR/lib/modes.sh"
 source "$SCRIPT_DIR/lib/sights.sh" 2>/dev/null || true       # Sights integration
 source "$SCRIPT_DIR/lib/agents.sh" 2>/dev/null || true      # Agent profiles and routing
+source "$SCRIPT_DIR/lib/blend.sh" 2>/dev/null || true       # Dynamic agent blending engine
 source "$SCRIPT_DIR/lib/teams.sh" 2>/dev/null || true      # Agent Teams integration
 source "$SCRIPT_DIR/lib/boot.sh" 2>/dev/null || true        # Boot sequence
 source "$SCRIPT_DIR/lib/session-end.sh" 2>/dev/null || true # Session end protocol
@@ -402,23 +403,40 @@ run_iteration() {
   local output
   local exit_code=0
 
-  # Route to the specialist agent selected by boot sequence
+  # ═══════════════════════════════════════════════════════════════════════════
+  # BLEND ENGINE: Create a custom specialist for this task
+  # Instead of routing to a single static agent, blend multiple agents
+  # into a custom-optimized specialist for every iteration.
+  # Fallback: use boot-selected agent if blend engine not available.
+  # ═══════════════════════════════════════════════════════════════════════════
   local agent_cli_name="merlin"
-  if [ -n "${BOOT_SELECTED_AGENT:-}" ] && type get_agent_cli_name &> /dev/null; then
+  local agent_display_name="merlin"
+
+  if type blend_for_task &>/dev/null; then
+    # Blend engine available — create custom specialist
+    mkdir -p "$LOOP_DIR/blends"
+    local blend_path
+    blend_path=$(blend_for_task "$current_task_desc" "$LOOP_DIR/blends")
+    agent_cli_name="$blend_path"
+    agent_display_name=$(blend_summary "$current_task_desc" 2>/dev/null || echo "Blended Specialist")
+
+    if type blend_show_decision &>/dev/null; then
+      blend_show_decision "$current_task_desc"
+    fi
+  elif [ -n "${BOOT_SELECTED_AGENT:-}" ] && type get_agent_cli_name &> /dev/null; then
+    # Fallback: static agent routing (pre-blend behavior)
     agent_cli_name=$(get_agent_cli_name "$BOOT_SELECTED_AGENT")
-  fi
-
-  local agent_display_name="$agent_cli_name"
-  if type get_agent_display_name &> /dev/null && [ -n "${BOOT_SELECTED_AGENT:-}" ]; then
-    agent_display_name=$(get_agent_display_name "$BOOT_SELECTED_AGENT")
+    if type get_agent_display_name &> /dev/null; then
+      agent_display_name=$(get_agent_display_name "$BOOT_SELECTED_AGENT")
+    fi
   fi
 
   echo -e "${BLUE}Spawning Claude as ${BOLD}${agent_display_name}${RESET}${BLUE}...${RESET}"
-  echo -e "${BLUE}Agent: --agent ${agent_cli_name} | Task list: ${TASK_LIST_ID}${RESET}"
+  echo -e "${BLUE}Agent: --agent $(basename "$agent_cli_name" .md) | Task list: ${TASK_LIST_ID}${RESET}"
 
   # Capture output and exit code
   # CLAUDE_CODE_TASK_LIST_ID enables cross-session task coordination
-  # --agent routes to the specialist selected by boot sequence
+  # --agent routes to the blended specialist (or fallback agent)
   set +e
   output=$(CLAUDE_CODE_TASK_LIST_ID="$TASK_LIST_ID" claude --agent "$agent_cli_name" --output-format stream-json 2>&1 <<< "$full_prompt")
   exit_code=$?

package/files/loop/merlin-session.sh

@@ -44,6 +44,7 @@ source "$SCRIPT_DIR/lib/tui.sh" 2>/dev/null || true
 source "$SCRIPT_DIR/lib/agents.sh" 2>/dev/null || true
 source "$SCRIPT_DIR/lib/sights.sh" 2>/dev/null || true
 source "$SCRIPT_DIR/lib/boot.sh" 2>/dev/null || true
+source "$SCRIPT_DIR/lib/blend.sh" 2>/dev/null || true
 
 # Colors
 : "${RESET:=\033[0m}"
@@ -77,7 +78,7 @@ banner() {
   echo " / /  / /  __/ /  / / / / / /"
   echo "/_/  /_/\___/_/  /_/_/_/ /_/"
   echo -e "${RESET}"
-  echo -e "${DIM}Interactive Session — Each agent = fresh Claude session${RESET}"
+  echo -e "${DIM}Interactive Session — Blended agents = custom specialist per task${RESET}"
   echo -e "${DIM}────────────────────────────────────────────────────────${RESET}"
   echo ""
 }
@@ -400,34 +401,143 @@ spawn_agent() {
 }
 
 # ═══════════════════════════════════════════════════════════════════════════════
-# Pipeline Support
+# Blended Spawn — THE DEFAULT PATH
+# Every task gets a custom-optimized specialist
 # ═══════════════════════════════════════════════════════════════════════════════
 
-# Run a pipeline of agents for a task
-# Usage: run_pipeline "add authentication" spec architect implement test
+# Spawn a blended agent for a task (replaces route_to_agent + spawn_agent)
+spawn_blended() {
+  local task="$1"
+
+  # Create session directory
+  mkdir -p "$SESSION_DIR"
+
+  # Create the blended agent
+  local blend_path
+  blend_path=$(blend_for_task "$task" "$SESSION_DIR")
+
+  local blend_label
+  blend_label=$(blend_summary "$task")
+
+  # Build additional context (pipeline context from previous agents)
+  local prompt="$task"
+  if [ -n "$PIPELINE_CONTEXT" ]; then
+    prompt="${prompt}
+
+## Previous Agent Output
+
+${PIPELINE_CONTEXT}"
+  fi
+  if [ -f "PROJECT.md" ]; then
+    prompt="${prompt}
+
+## Project Info
+
+See PROJECT.md in the repo root."
+  fi
+
+  # Show spawn info
+  echo ""
+  echo -e "${DIM}────────────────────────────────────────────────────────${RESET}"
+  echo -e "${MAGENTA}${BOLD}  Spawning: ${blend_label}${RESET}"
+  echo -e "${DIM}  Fresh Claude session (200K context, custom blended specialist)${RESET}"
+  echo -e "${DIM}────────────────────────────────────────────────────────${RESET}"
+  echo ""
+
+  # Spawn fresh Claude with blended agent
+  local output=""
+  local exit_code=0
+  local start_time
+  start_time=$(date +%s)
+
+  set +e
+  output=$(claude --agent "$blend_path" --output-format text -p "$prompt" 2>&1)
+  exit_code=$?
+  set -e
+
+  local end_time
+  end_time=$(date +%s)
+  local duration=$((end_time - start_time))
+
+  # Save result
+  echo "$output" > "$RESULT_FILE"
+
+  # Update state
+  AGENT_RUNS=$((AGENT_RUNS + 1))
+  LAST_AGENT="$blend_label"
+  LAST_RESULT="$output"
+  PIPELINE_CONTEXT="$output"
+
+  # Log to history
+  echo "{\"agent\":\"blend:${blend_label}\",\"task\":\"$(echo "$task" | head -c 100)\",\"duration\":$duration,\"exit_code\":$exit_code,\"timestamp\":$(date +%s)}" >> "$HISTORY_FILE"
+
+  # Show result
+  echo ""
+  echo -e "${DIM}────────────────────────────────────────────────────────${RESET}"
+  if [ $exit_code -eq 0 ]; then
+    echo -e "${GREEN}${BOLD}  ✓ Completed${RESET} ${DIM}(${duration}s)${RESET}"
+  else
+    echo -e "${RED}${BOLD}  ✗ Failed${RESET} ${DIM}(exit $exit_code, ${duration}s)${RESET}"
+  fi
+  echo -e "${DIM}────────────────────────────────────────────────────────${RESET}"
+  echo ""
+
+  # Show the output (truncated for display)
+  local line_count
+  line_count=$(echo "$output" | wc -l | tr -d ' ')
+  if [ "$line_count" -gt 50 ]; then
+    echo "$output" | head -40
+    echo ""
+    echo -e "${DIM}  ... ($((line_count - 40)) more lines — full output in $RESULT_FILE)${RESET}"
+    echo ""
+    echo "$output" | tail -10
+  else
+    echo "$output"
+  fi
+
+  return $exit_code
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Pipeline Support — Each step gets its own custom-blended specialist
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Run a blended pipeline — each phase gets a custom specialist
 run_pipeline() {
   local task="$1"
-  shift
-  local agents=("$@")
 
-  echo -e "\n${MAGENTA}${BOLD}Pipeline:${RESET} ${agents[*]}"
-  echo -e "${DIM}Each agent runs in a fresh session and passes context to the next.${RESET}\n"
+  local phases=(
+    "Define the requirements and write a clear spec for: $task"
+    "Design the architecture and data models for: $task"
+    "Implement the full feature: $task"
+    "Write comprehensive tests for: $task"
+  )
+  local phase_names=("Spec" "Architecture" "Implementation" "Testing")
+
+  echo -e "\n${MAGENTA}${BOLD}Pipeline:${RESET} Spec → Architecture → Implementation → Testing"
+  echo -e "${DIM}Each phase gets a custom-blended specialist with fresh 200K context.${RESET}\n"
 
   PIPELINE_CONTEXT=""
 
-  for i in "${!agents[@]}"; do
-    local agent="${agents[$i]}"
+  for i in "${!phases[@]}"; do
+    local phase="${phases[$i]}"
+    local name="${phase_names[$i]}"
     local step=$((i + 1))
-    local total=${#agents[@]}
+    local total=${#phases[@]}
 
-    echo -e "${CYAN}[${step}/${total}]${RESET} ${BOLD}${agent}${RESET}"
+    echo -e "\n${CYAN}[${step}/${total}]${RESET} ${BOLD}${name}${RESET}"
 
-    spawn_agent "$agent" "$task"
+    # Show the blend for this phase
+    if type blend_show_decision &>/dev/null; then
+      blend_show_decision "$phase"
+    fi
+
+    spawn_blended "$phase"
     local exit_code=$?
 
     if [ $exit_code -ne 0 ]; then
-      echo -e "\n${RED}Pipeline stopped at ${agent} (exit $exit_code)${RESET}"
-      echo -e "${YELLOW}Continue anyway? [y/N]${RESET} "
+      echo -e "\n${RED}Pipeline stopped at ${name} (exit $exit_code)${RESET}"
+      echo -ne "${YELLOW}Continue anyway? [y/N]: ${RESET}"
       read -r continue_choice
       if [ "$continue_choice" != "y" ] && [ "$continue_choice" != "Y" ]; then
         return 1
@@ -436,8 +546,9 @@ run_pipeline() {
 
     # Between pipeline steps, ask user if they want to continue
     if [ $step -lt $total ]; then
+      local next_name="${phase_names[$((i+1))]}"
       echo ""
-      echo -e "${WHITE}[enter]${RESET} Continue to ${agents[$((i+1))]}  ${WHITE}[s]${RESET} Skip  ${WHITE}[q]${RESET} Stop pipeline"
+      echo -e "${WHITE}[enter]${RESET} Continue to ${BOLD}${next_name}${RESET}  ${WHITE}[s]${RESET} Skip  ${WHITE}[q]${RESET} Stop pipeline"
       read -r pipeline_choice
       case "$pipeline_choice" in
         s|S) continue ;;
@@ -447,7 +558,7 @@ run_pipeline() {
     fi
   done
 
-  echo -e "\n${GREEN}${BOLD}✓ Pipeline complete${RESET}"
+  echo -e "\n${GREEN}${BOLD}✓ Pipeline complete${RESET} (4 blended specialists ran)"
 }
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -466,9 +577,9 @@ handle_special_commands() {
     help|h|\?)
       echo ""
       echo -e "${BOLD}Commands:${RESET}"
-      echo -e "  ${WHITE}Any text${RESET}      → Routes to the best agent automatically"
+      echo -e "  ${WHITE}Any text${RESET}      → Blends the best agents into a custom specialist"
       echo -e "  ${WHITE}@agent task${RESET}   → Force a specific agent (e.g. @tests-qa add tests)"
-      echo -e "  ${WHITE}pipeline${RESET}      → Run full pipeline: spec → arch → impl → test"
+      echo -e "  ${WHITE}pipeline${RESET}      → Run blended pipeline: spec → arch → impl → test"
       echo -e "  ${WHITE}history${RESET}       → Show agent history this session"
       echo -e "  ${WHITE}result${RESET}        → Show last agent's full output"
       echo -e "  ${WHITE}status${RESET}        → Show project status"
@@ -516,7 +627,7 @@ handle_special_commands() {
       echo -ne "${MAGENTA}❯${RESET} "
       read -r pipeline_task
       if [ -n "$pipeline_task" ]; then
-        run_pipeline "$pipeline_task" product-spec system-architect implementation-dev tests-qa
+        run_pipeline "$pipeline_task"
       fi
       return 0
       ;;
@@ -603,13 +714,23 @@ main() {
       continue
     fi
 
-    # Route to the right agent (deterministic)
-    local agent
-    agent=$(route_to_agent "$user_input")
-
-    echo -e "${DIM}Routed to: ${CYAN}${agent}${RESET}"
+    # ═════════════════════════════════════════════════════════════════════════
+    # BLEND ENGINE: Show what custom specialist will be created for this task
+    # ═════════════════════════════════════════════════════════════════════════
+    local use_blend=false
+    if type blend_show_decision &>/dev/null; then
+      echo ""
+      blend_show_decision "$user_input"
+      use_blend=true
+    else
+      # Fallback: static routing
+      local agent
+      agent=$(route_to_agent "$user_input")
+      echo -e "${DIM}Routed to: ${CYAN}${agent}${RESET}"
+    fi
 
     # Ask for confirmation (quick — enter to confirm, or change)
+    echo ""
     echo -ne "${DIM}[enter] Go  [c] Change agent  [p] Full pipeline: ${RESET}"
     read -r confirm
 
@@ -619,24 +740,34 @@ main() {
         echo -e "  product-spec, system-architect, implementation-dev, dry-refactor"
         echo -e "  hardening-guard, tests-qa, ops-railway, docs-keeper"
         echo -e "  merlin-frontend, merlin-api-designer, merlin-debugger, remotion"
+        echo -e "  apple-swift-expert, android-expert, ui-designer, ui-builder"
+        echo -e "  animation-expert, marketing-automation, desktop-app-expert"
         echo -ne "\n${WHITE}Agent: ${RESET}"
         read -r new_agent
         if [ -n "$new_agent" ]; then
-          agent="$new_agent"
+          spawn_agent "$new_agent" "$user_input"
+          use_blend=false
         fi
         ;;
       p|P|pipeline)
-        run_pipeline "$user_input" product-spec system-architect implementation-dev tests-qa
+        run_pipeline "$user_input"
         continue
         ;;
       *)
-        ;; # proceed with auto-routed agent
+        ;; # proceed with blend
     esac
 
-    # Spawn the agent
-    spawn_agent "$agent" "$user_input"
+    # Spawn the blended specialist (or skip if user changed agent)
+    if [ "$use_blend" = true ] && [ "$confirm" != "c" ] && [ "$confirm" != "C" ]; then
+      spawn_blended "$user_input"
+    elif [ "$use_blend" = false ] && [ "$confirm" != "c" ] && [ "$confirm" != "C" ]; then
+      # Fallback: no blend engine, use static routing
+      local agent
+      agent=$(route_to_agent "$user_input")
+      spawn_agent "$agent" "$user_input"
+    fi
 
-    # After agent completes, suggest next steps
+    # After agent completes, suggest next steps (also blended!)
     echo ""
     echo -e "${WHITE}What's next?${RESET}"
     echo -e "  ${DIM}[enter] New task  [t] Test this  [r] Refactor  [d] Docs  [q] Quit${RESET}"
@@ -645,13 +776,25 @@ main() {
 
     case "$next_choice" in
       t|T|test)
-        spawn_agent "tests-qa" "Write tests for what was just implemented: $user_input"
+        if [ "$use_blend" = true ]; then
+          spawn_blended "Write comprehensive tests for what was just implemented: $user_input"
+        else
+          spawn_agent "tests-qa" "Write tests for what was just implemented: $user_input"
+        fi
         ;;
       r|R|refactor)
-        spawn_agent "dry-refactor" "Refactor and clean up the code from: $user_input"
+        if [ "$use_blend" = true ]; then
+          spawn_blended "Refactor and clean up the code from: $user_input"
+        else
+          spawn_agent "dry-refactor" "Refactor and clean up the code from: $user_input"
+        fi
         ;;
       d|D|docs)
-        spawn_agent "docs-keeper" "Document what was just built: $user_input"
+        if [ "$use_blend" = true ]; then
+          spawn_blended "Document what was just built: $user_input"
+        else
+          spawn_agent "docs-keeper" "Document what was just built: $user_input"
+        fi
         ;;
       q|Q|quit|exit)
         echo -e "\n${MAGENTA}Session ended.${RESET} ${DIM}($AGENT_RUNS agents spawned)${RESET}\n"

package/files/merlin/VERSION

@@ -1 +1 @@
-3.6.0
+3.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-merlin-brain",
-  "version": "3.6.0",
+  "version": "3.6.2",
   "description": "Merlin - The Ultimate AI Brain for Claude Code. One install: workflows, agents, loop, and Sights MCP server.",
   "type": "module",
   "main": "./dist/server/index.js",