create-merlin-brain 3.2.0 → 3.3.0

package/files/hooks/lib/analytics.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+#
+# Merlin Hooks - Shared Analytics Library
+# Lightweight session tracking and event logging for Claude Code hooks.
+# All functions are POSIX-ish, fast (<10ms), and degrade gracefully.
+#
+
+MERLIN_ANALYTICS_DIR="${HOME}/.claude/merlin/analytics"
+
+get_session_id() {
+  if [ -n "${MERLIN_SESSION_ID:-}" ]; then echo "${MERLIN_SESSION_ID}"; return; fi
+  echo "$(date +%s)-$$"
+}
+
+MERLIN_SESSION_FILE="${MERLIN_SESSION_FILE:-${MERLIN_ANALYTICS_DIR}/session-$(get_session_id).json}"
+
+ensure_session_file() {
+  [ -d "${MERLIN_ANALYTICS_DIR}" ] || mkdir -p "${MERLIN_ANALYTICS_DIR}" 2>/dev/null || return 1
+  if [ ! -f "${MERLIN_SESSION_FILE}" ]; then
+    local stype="raw"
+    [ -n "${MERLIN_LOOP_SESSION:-}" ] && stype="loop"
+    [ -z "${MERLIN_LOOP_SESSION:-}" ] && [ -n "${CLAUDE_CODE_HOOK_NAME:-}" ] && stype="hooks"
+    printf '{"id":"%s","startTime":"%s","sessionType":"%s","events":[]}\n' \
+      "$(get_session_id)" "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "$stype" \
+      > "${MERLIN_SESSION_FILE}" 2>/dev/null || return 1
+  fi
+}
+
+# Core event logger — all specialized loggers call this
+# Usage: log_event "type" '{"key":"value"}'
+log_event() {
+  local etype="${1:-unknown}" edata="${2:-{}}"
+  ensure_session_file || return 1
+  local evt
+  evt=$(printf '{"type":"%s","ts":"%s","data":%s}' "$etype" "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "$edata")
+  if command -v jq >/dev/null 2>&1; then
+    local tmp; tmp=$(mktemp 2>/dev/null || echo "/tmp/merlin-evt-$$")
+    jq --argjson e "$evt" '.events += [$e]' "${MERLIN_SESSION_FILE}" > "$tmp" 2>/dev/null \
+      && mv "$tmp" "${MERLIN_SESSION_FILE}" 2>/dev/null || rm -f "$tmp" 2>/dev/null
+  else
+    echo "$evt" >> "${MERLIN_SESSION_FILE}.log" 2>/dev/null
+  fi
+}
+
+# Specialized loggers — thin wrappers for structured events
+log_sights_call() { log_event "sights_call" "$(printf '{"tool":"%s","query":"%s"}' "${1:-}" "${2:-}")"; }
+log_agent_route() { log_event "agent_route" "$(printf '{"agent":"%s","task":"%s"}' "${1:-}" "${2:-}")"; }
+log_error() { log_event "error" "$(printf '{"errorType":"%s","message":"%s"}' "${1:-}" "${2:-}")"; }
+log_file_edit() { log_event "file_edit" "$(printf '{"file":"%s"}' "${1:-}")"; }
+log_task_complete() { log_event "task_complete" "$(printf '{"task":"%s"}' "${1:-}")"; }
+
+# Finalize session: compute summary stats from events
+finalize_session() {
+  [ -f "${MERLIN_SESSION_FILE}" ] || return 1
+  command -v jq >/dev/null 2>&1 || return 0
+  # Extract start epoch from session ID (format: epoch-pid) for duration calc
+  local sid; sid=$(jq -r '.id // ""' "${MERLIN_SESSION_FILE}" 2>/dev/null)
+  local start_epoch; start_epoch=$(echo "${sid}" | cut -d'-' -f1 2>/dev/null)
+  local end_epoch; end_epoch=$(date +%s)
+  local dur; dur=$(( end_epoch - ${start_epoch:-$end_epoch} ))
+  local tmp; tmp=$(mktemp 2>/dev/null || echo "/tmp/merlin-fin-$$")
+  jq --arg et "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" --argjson dur "${dur}" '
+    .endTime = $et | .durationSeconds = $dur
+    | .summary = {
+        sightsCallCount: [.events[] | select(.type == "sights_call")] | length,
+        filesChanged: [.events[] | select(.type == "file_edit")] | length,
+        tasksCompleted: [.events[] | select(.type == "task_complete")] | length,
+        errorsCount: [.events[] | select(.type == "error")] | length,
+        agentRoutes: [.events[] | select(.type == "agent_route")] | length
+      }
+    | .eventCount = (.events | length)
+  ' "${MERLIN_SESSION_FILE}" > "$tmp" 2>/dev/null \
+    && mv "$tmp" "${MERLIN_SESSION_FILE}" 2>/dev/null || rm -f "$tmp" 2>/dev/null
+}

package/files/hooks/lib/sights-check.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+#
+# Merlin Hooks - Shared Sights Check Library
+# Tracks when Sights was last consulted so hooks can detect stale context.
+#
+
+MERLIN_SIGHTS_LAST_CHECK_FILE="${HOME}/.claude/merlin/.last-sights-check"
+
+# Record that Sights was just called
+record_sights_call() {
+  local dir
+  dir=$(dirname "${MERLIN_SIGHTS_LAST_CHECK_FILE}")
+  mkdir -p "$dir" 2>/dev/null || return 1
+  date +%s > "${MERLIN_SIGHTS_LAST_CHECK_FILE}" 2>/dev/null || return 1
+  return 0
+}
+
+# Check if Sights was consulted within N seconds
+# Returns 0 (true) if recent, 1 (false) if stale or never checked
+sights_was_checked_recently() {
+  local max_age="${1:-120}"
+
+  if [ ! -f "${MERLIN_SIGHTS_LAST_CHECK_FILE}" ]; then
+    return 1
+  fi
+
+  local last_check
+  last_check=$(cat "${MERLIN_SIGHTS_LAST_CHECK_FILE}" 2>/dev/null || echo "0")
+  local now
+  now=$(date +%s)
+  local age=$(( now - ${last_check:-0} ))
+
+  if [ "$age" -le "$max_age" ]; then
+    return 0
+  fi
+  return 1
+}
+
+# Read MERLIN_API_KEY from env or config
+get_merlin_api_key() {
+  # Use ${VAR:-} pattern to avoid crash with set -u
+  if [ -n "${MERLIN_API_KEY:-}" ]; then
+    echo "${MERLIN_API_KEY}"
+    return
+  fi
+
+  local config="${HOME}/.claude/config.json"
+  if [ -f "$config" ] && command -v jq >/dev/null 2>&1; then
+    local key
+    key=$(jq -r '.mcpServers.merlin.env.MERLIN_API_KEY // empty' "$config" 2>/dev/null)
+    if [ -n "$key" ]; then
+      echo "$key"
+      return
+    fi
+  fi
+
+  echo ""
+}

package/files/hooks/post-edit-logger.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+#
+# Merlin Hook: PostToolUse (Edit/Write)
+# Logs file changes for analytics tracking.
+# Always exits 0 — never blocks Claude Code.
+#
+set -euo pipefail
+trap 'exit 0' ERR
+
+HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source shared libraries
+# shellcheck source=lib/analytics.sh
+. "${HOOKS_DIR}/lib/analytics.sh"
+
+# Read tool output from stdin (Claude Code pipes JSON)
+input=""
+if [ ! -t 0 ]; then
+  input=$(cat 2>/dev/null || true)
+fi
+
+# Extract file path and tool name
+file_path=""
+tool_name=""
+if [ -n "$input" ] && command -v jq >/dev/null 2>&1; then
+  file_path=$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null || true)
+  tool_name=$(echo "$input" | jq -r '.tool_name // empty' 2>/dev/null || true)
+fi
+
+# Log file change event
+log_event "file_changed" "$(printf '{"file":"%s","tool":"%s"}' "${file_path:-unknown}" "${tool_name:-unknown}")"
+
+exit 0

package/files/hooks/pre-edit-sights-check.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+#
+# Merlin Hook: PreToolUse (Edit/Write)
+# Checks if Sights was consulted recently before file edits.
+# Advisory only — always exits 0, never blocks edits.
+#
+set -euo pipefail
+trap 'exit 0' ERR
+
+HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source shared libraries
+# shellcheck source=lib/analytics.sh
+. "${HOOKS_DIR}/lib/analytics.sh"
+# shellcheck source=lib/sights-check.sh
+. "${HOOKS_DIR}/lib/sights-check.sh"
+
+# Read tool input from stdin (Claude Code pipes JSON)
+input=""
+if [ ! -t 0 ]; then
+  input=$(cat 2>/dev/null || true)
+fi
+
+# Extract file path from tool input
+file_path=""
+if [ -n "$input" ] && command -v jq >/dev/null 2>&1; then
+  file_path=$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null || true)
+fi
+
+# Check if Sights was consulted recently (within 120 seconds)
+if ! sights_was_checked_recently 120; then
+  log_event "sights_skip_warning" "$(printf '{"file":"%s"}' "${file_path:-unknown}")"
+fi
+
+# Log the pre-edit event
+log_event "pre_edit" "$(printf '{"file":"%s"}' "${file_path:-unknown}")"
+
+exit 0

package/files/hooks/session-end.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+#
+# Merlin Hook: SessionEnd / Stop
+# Saves checkpoint and finalizes session analytics.
+# Always exits 0 — never blocks Claude Code shutdown.
+#
+set -euo pipefail
+trap 'exit 0' ERR
+
+HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source shared libraries
+# shellcheck source=lib/analytics.sh
+. "${HOOKS_DIR}/lib/analytics.sh"
+
+# Log session end
+log_event "session_end" '{}'
+
+# Finalize session analytics (adds endTime, duration, summary)
+finalize_session
+
+# If merlin CLI is available, save checkpoint in background
+if command -v merlin >/dev/null 2>&1; then
+  merlin save-checkpoint "Session ended" >/dev/null 2>&1 &
+fi
+
+exit 0

package/files/hooks/session-start.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+#
+# Merlin Hook: SessionStart
+# Initializes analytics session and kicks off Sights context in background.
+# Always exits 0 — never blocks Claude Code startup.
+#
+set -euo pipefail
+trap 'exit 0' ERR
+
+HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source shared libraries
+# shellcheck source=lib/analytics.sh
+. "${HOOKS_DIR}/lib/analytics.sh"
+# shellcheck source=lib/sights-check.sh
+. "${HOOKS_DIR}/lib/sights-check.sh"
+
+# Initialize analytics session
+ensure_session_file
+
+# Log session start with working directory
+cwd="${PWD:-$(pwd)}"
+log_event "session_start" "$(printf '{"cwd":"%s"}' "$cwd")"
+
+# If merlin CLI is available, warm up Sights context in background
+if command -v merlin >/dev/null 2>&1; then
+  merlin context "session start" >/dev/null 2>&1 &
+  record_sights_call
+fi
+
+exit 0

package/files/hooks/stop-check.md

@@ -0,0 +1,14 @@
+# Stop Check - Merlin Quality Gate
+
+Before stopping this session, evaluate:
+
+1. **Sights Usage**: Did you check Merlin Sights (merlin_get_context, merlin_find_files, merlin_search) before making code changes? If not, you should check now.
+
+2. **Uncommitted Work**: Are there uncommitted changes that should be saved? If so, suggest committing before stopping.
+
+3. **Checkpoint**: Has a Merlin checkpoint been saved for this session? If significant work was done, save one with merlin_save_checkpoint.
+
+4. **Verification**: If code was written, were basic checks run (build, types, lint)? If not, run merlin_run_verification first.
+
+If all checks pass, respond with "STOP_APPROVED".
+If any check fails, explain what should be done first before stopping.

package/files/hooks/subagent-context.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+#
+# Merlin Hook: SubagentStart
+# When a subagent/teammate starts, inject Merlin Sights context.
+# Advisory only — always exits 0, never blocks subagent startup.
+#
+set -euo pipefail
+trap 'exit 0' ERR
+
+HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source shared libraries
+# shellcheck source=lib/analytics.sh
+. "${HOOKS_DIR}/lib/analytics.sh"
+
+# Read subagent info from stdin (JSON with agent name, task)
+input=""
+if [ ! -t 0 ]; then
+  input=$(cat 2>/dev/null || true)
+fi
+
+# Extract task description if available
+task_desc=""
+if [ -n "$input" ] && command -v jq >/dev/null 2>&1; then
+  task_desc=$(echo "$input" | jq -r '.task // .description // empty' 2>/dev/null || true)
+fi
+
+# Log subagent start event
+log_event "subagent_start" "$(printf '{"task":"%s"}' "${task_desc:-unknown}")"
+
+# If Merlin CLI available, fetch and output context for the task
+if [ -n "$task_desc" ] && command -v merlin >/dev/null 2>&1; then
+  merlin context "$task_desc" 2>/dev/null || true
+fi
+
+exit 0

package/files/hooks/task-completed-verify.md

@@ -0,0 +1,14 @@
+# Task Completion Verification - Merlin Quality Gate
+
+Before marking this task as complete, verify:
+
+1. **Code Quality**: Does the implementation follow the project's coding conventions? Check with merlin_get_conventions if unsure.
+
+2. **Sights Alignment**: Is the code consistent with existing patterns? Verify with merlin_get_context for the modified areas.
+
+3. **No Regressions**: Run the project's test suite if it exists. Check build passes.
+
+4. **Documentation**: If the task added new APIs or features, are they documented?
+
+If all verifications pass, allow task completion.
+If issues are found, list them and suggest fixes before completing.

package/files/hooks/task-completed-verify.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+#
+# Merlin Hook: Notification (task_completed)
+# Runs lightweight verification checks when a task completes.
+# Informational only — always exits 0 for v1.
+#
+set -euo pipefail
+trap 'exit 0' ERR
+
+HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source shared libraries
+# shellcheck source=lib/analytics.sh
+. "${HOOKS_DIR}/lib/analytics.sh"
+
+# Log task completion
+log_event "task_completed" '{}'
+
+# Check for build script in package.json
+if [ -f "package.json" ] && command -v jq >/dev/null 2>&1; then
+  build_script=$(jq -r '.scripts.build // empty' package.json 2>/dev/null || true)
+  if [ -n "$build_script" ]; then
+    build_output=$(npm run build --if-present 2>&1) || true
+    build_exit=$?
+    if [ "$build_exit" -ne 0 ]; then
+      log_event "build_failed" "$(printf '{"exit_code":%d}' "$build_exit")"
+      echo "Merlin: Build check failed (exit $build_exit)" >&2
+    else
+      log_event "build_passed" '{}'
+    fi
+  fi
+fi
+
+# Check TypeScript compilation
+if [ -f "tsconfig.json" ] && command -v npx >/dev/null 2>&1; then
+  tsc_output=$(npx tsc --noEmit 2>&1) || true
+  tsc_exit=$?
+  if [ "$tsc_exit" -ne 0 ]; then
+    log_event "typecheck_failed" "$(printf '{"exit_code":%d}' "$tsc_exit")"
+    echo "Merlin: Type check failed (exit $tsc_exit)" >&2
+  else
+    log_event "typecheck_passed" '{}'
+  fi
+fi
+
+exit 0

package/files/hooks/teammate-idle-verify.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+#
+# Merlin Hook: TeammateIdle
+# When a teammate finishes work, verify quality against Sights patterns.
+# Advisory only — always exits 0, never blocks teammates.
+#
+set -euo pipefail
+trap 'exit 0' ERR
+
+HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source shared libraries
+# shellcheck source=lib/analytics.sh
+. "${HOOKS_DIR}/lib/analytics.sh"
+
+# Read teammate work summary from stdin (JSON from Claude Code)
+input=""
+if [ ! -t 0 ]; then
+  input=$(cat 2>/dev/null || true)
+fi
+
+# Extract modified files if available
+modified_files=""
+if [ -n "$input" ] && command -v jq >/dev/null 2>&1; then
+  modified_files=$(echo "$input" | jq -r '.files_modified // empty' 2>/dev/null || true)
+fi
+
+# Log teammate idle event
+log_event "teammate_idle_verify" "$(printf '{"modified_files":"%s"}' "${modified_files:-none}")"
+
+# If Merlin CLI is available, run quick Sights check on modified files
+if [ -n "$modified_files" ] && command -v merlin >/dev/null 2>&1; then
+  merlin context "verify changes in ${modified_files}" >/dev/null 2>&1 &
+fi
+
+# Quick build check (non-blocking, advisory only)
+if command -v npm >/dev/null 2>&1; then
+  npm run build --if-present >/dev/null 2>&1 || true
+fi
+
+exit 0

package/files/loop/lib/sights.sh

@@ -21,13 +21,24 @@ CACHED_TRAJECTORY=""
 # ═══════════════════════════════════════════════════════════════════════════════
 
 get_api_key() {
-  # Check environment variable first
-  if [ -n "$MERLIN_API_KEY" ]; then
-    echo "$MERLIN_API_KEY"
+  # Check environment variable first (use :- to avoid crash with set -u)
+  if [ -n "${MERLIN_API_KEY:-}" ]; then
+    echo "${MERLIN_API_KEY}"
     return
   fi
 
-  # Check ~/.merlin/config.json
+  # Check Claude Code MCP config (where most users have their API key)
+  local claude_config="$HOME/.claude/config.json"
+  if [ -f "$claude_config" ] && command -v jq &> /dev/null; then
+    local key
+    key=$(jq -r '.mcpServers.merlin.env.MERLIN_API_KEY // empty' "$claude_config" 2>/dev/null)
+    if [ -n "$key" ]; then
+      echo "$key"
+      return
+    fi
+  fi
+
+  # Check ~/.merlin/config.json (legacy location)
   local config_file="$HOME/.merlin/config.json"
   if [ -f "$config_file" ] && command -v jq &> /dev/null; then
     local key

package/files/loop/lib/teams.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+#
+# Merlin Loop - Agent Teams Integration
+# Enables parallel specialist execution using Claude Code Agent Teams.
+#
+# When CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set and the user passes
+# --teams, wave plans execute as parallel teammates instead of sequential
+# --agent -p invocations.
+#
+# Architecture:
+#   teams_available()          - Check if Agent Teams feature flag is set
+#   teams_enabled()            - Check if user opted in AND feature is available
+#   execute_wave_teams()       - Run wave plans as parallel teammates
+#   execute_wave_sequential()  - Fallback: run plans one by one
+#   execute_wave()             - Dispatcher: picks teams or sequential
+#
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Detection
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Check if Agent Teams runtime is available (feature flag)
+teams_available() {
+  [ "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-0}" = "1" ]
+}
+
+# Check if teams mode is enabled by user AND runtime supports it
+teams_enabled() {
+  [ "${MERLIN_TEAMS_MODE:-false}" = "true" ] && teams_available
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Wave Execution: Agent Teams (Parallel)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+execute_wave_teams() {
+  local wave_number="$1"
+  shift
+  local plan_files=("$@")
+
+  local plan_count=${#plan_files[@]}
+  echo -e "${MAGENTA:-}Agent Teams: Executing wave $wave_number with $plan_count parallel teammates${RESET:-}"
+
+  # Build the team lead prompt — coordinates teammates, doesn't implement
+  local team_prompt="You are the Merlin Team Lead coordinating wave $wave_number execution.
+
+You have $plan_count teammates, each assigned to one plan. Delegate each plan to its teammate.
+Do NOT implement yourself — only coordinate and verify results.
+
+Plans for this wave:"
+
+  for plan_file in "${plan_files[@]}"; do
+    local plan_name
+    plan_name=$(basename "$plan_file" -PLAN.md)
+    team_prompt="${team_prompt}
+- ${plan_name}: ${plan_file}"
+  done
+
+  team_prompt="${team_prompt}
+
+Instructions:
+1. Assign each plan to a separate teammate using the Task tool
+2. Each teammate should read their PLAN.md and execute all tasks
+3. Each teammate should commit their work atomically
+4. Wait for all teammates to complete
+5. Verify results and report back with a summary
+
+Use the Task tool to delegate to teammates. Each teammate gets fresh context."
+
+  # Execute with Agent Teams enabled — the team lead orchestrates
+  local exit_code=0
+  set +e
+  echo "$team_prompt" | CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 \
+    claude --agent merlin --output-format stream-json 2>&1
+  exit_code=$?
+  set -e
+
+  if [ $exit_code -ne 0 ]; then
+    echo -e "${RED:-}Agent Teams wave $wave_number failed (exit $exit_code)${RESET:-}"
+    echo -e "${YELLOW:-}Falling back to sequential execution...${RESET:-}"
+    execute_wave_sequential "$wave_number" "${plan_files[@]}"
+    return $?
+  fi
+
+  return 0
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Wave Execution: Sequential Fallback
+# ═══════════════════════════════════════════════════════════════════════════════
+
+execute_wave_sequential() {
+  local wave_number="$1"
+  shift
+  local plan_files=("$@")
+
+  echo -e "${BLUE:-}Sequential execution: wave $wave_number (${#plan_files[@]} plans)${RESET:-}"
+
+  for plan_file in "${plan_files[@]}"; do
+    local plan_name
+    plan_name=$(basename "$plan_file" -PLAN.md)
+    echo -e "${CYAN:-}Executing: $plan_name${RESET:-}"
+
+    # Use existing --agent -p pattern (fresh 200K context per plan)
+    local exit_code=0
+    set +e
+    cat "$plan_file" | claude --agent merlin-executor --output-format stream-json 2>&1
+    exit_code=$?
+    set -e
+
+    if [ $exit_code -ne 0 ]; then
+      echo -e "${RED:-}Plan $plan_name failed (exit $exit_code)${RESET:-}"
+      return $exit_code
+    fi
+
+    echo -e "${GREEN:-}Plan $plan_name completed${RESET:-}"
+  done
+
+  return 0
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Dispatcher
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Main wave execution entry point — picks teams or sequential
+execute_wave() {
+  local wave_number="$1"
+  shift
+  local plan_files=("$@")
+
+  # Single plan: no point using teams
+  if [ ${#plan_files[@]} -le 1 ]; then
+    execute_wave_sequential "$wave_number" "${plan_files[@]}"
+    return $?
+  fi
+
+  if teams_enabled; then
+    execute_wave_teams "$wave_number" "${plan_files[@]}"
+  else
+    execute_wave_sequential "$wave_number" "${plan_files[@]}"
+  fi
+}

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/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
 source "$SCRIPT_DIR/lib/tui.sh" 2>/dev/null || true         # Interactive TUI
@@ -182,6 +183,15 @@ show_launch_screen() {
   echo -e "  ${CYAN}Pause Timeout:${RESET} ${BOLD}$(get_timeout_status 2>/dev/null || echo "${PAUSE_TIMEOUT}s")${RESET}"
   echo -e "  ${CYAN}Cloud Sync:${RESET}     ${BOLD}$CLOUD_SYNC${RESET}"
   echo -e "  ${CYAN}Task List:${RESET}      ${BOLD}${TASK_LIST_ID:-auto}${RESET}"
+  if type teams_available &> /dev/null; then
+    if teams_enabled 2>/dev/null; then
+      echo -e "  ${CYAN}Agent Teams:${RESET}    ${GREEN}Enabled (parallel waves)${RESET}"
+    elif teams_available 2>/dev/null; then
+      echo -e "  ${CYAN}Agent Teams:${RESET}    ${YELLOW}Available${RESET} (use --teams to enable)"
+    else
+      echo -e "  ${CYAN}Agent Teams:${RESET}    ${YELLOW}Not available${RESET} (experimental)"
+    fi
+  fi
   echo ""
   echo -e "  ${MAGENTA}───────────────────────────────────────────────────────────────${RESET}"
   echo ""
@@ -747,6 +757,7 @@ usage() {
   echo "  --max N         Maximum iterations (default: 50)"
   echo "  --cooldown N    Seconds between iterations (default: 2)"
   echo "  --no-sync       Disable cloud sync"
+  echo "  --teams         Enable Agent Teams for parallel wave execution (experimental)"
   echo "  --afk           AFK mode (stricter safety, shorter timeout, auto mode)"
   echo "  --quiet         Minimal output"
   echo ""
@@ -756,6 +767,7 @@ usage() {
   echo "  merlin-loop --mode auto build       # Fully automated, no pauses"
   echo "  merlin-loop --mode interactive build # Pause after every task"
   echo "  merlin-loop --max 100 build         # Allow up to 100 iterations"
+  echo "  merlin-loop --teams build           # Parallel wave execution (experimental)"
   echo "  merlin-loop --afk auto              # Run unattended (auto mode)"
 }
 
@@ -799,6 +811,10 @@ parse_args() {
         CLOUD_SYNC="false"
         shift
         ;;
+      --teams)
+        MERLIN_TEAMS_MODE="true"
+        shift
+        ;;
       --afk)
         # AFK mode: stricter limits, auto mode, shorter timeout, more safety
         CIRCUIT_BREAKER_THRESHOLD=3