create-merlin-brain 3.15.2 → 3.18.0

package/files/commands/merlin/challenge.md

@@ -0,0 +1,224 @@
+---
+name: merlin:challenge
+description: Run a dialectic challenge — Insider (context-aware) vs Academic (first-principles) with Arbiter synthesis. Use before committing to an approach for any significant task.
+argument-hint: "[task description or phase number]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - Agent
+  - AskUserQuestion
+  - mcp__merlin__merlin_get_context
+  - mcp__merlin__merlin_find_files
+  - mcp__merlin__merlin_get_conventions
+  - mcp__merlin__merlin_record_challenge
+  - mcp__merlin__merlin_get_challenge_stats
+---
+
+<objective>
+Run a dialectic challenge: two agents independently design approaches to a task, then an arbiter evaluates and synthesizes.
+
+- **Insider**: Has full codebase context via Merlin Sights. Designs the best approach given what exists.
+- **Academic**: Has NO codebase context. Designs the best approach from first principles and industry research.
+- **Arbiter**: Compares both on weighted criteria, produces a scored recommendation or synthesis.
+
+The challenge process reveals blind spots, confirmation bias, and potentially better approaches that a single-track planning process would miss.
+</objective>
+
+<process>
+
+<step name="parse_task">
+## Step 1: Parse the Task
+
+Parse the command arguments:
+- If a phase number is given (e.g., `3`, `Phase 3`), load the phase from ROADMAP.md
+- If text is given, use it as the task description
+- If no arguments, ask the user what to challenge
+
+Gather context:
+```
+Call: merlin_get_context
+Task: "[the task being challenged]"
+```
+
+Determine the tech stack from project files (package.json, tsconfig.json, etc).
+
+Prepare two handoff documents:
+1. **Insider handoff**: full task + tech stack + constraints + "use Merlin Sights for codebase context"
+2. **Academic handoff**: task description + tech stack + constraints ONLY. No file paths, no existing patterns, no module names.
+</step>
+
+<step name="run_parallel">
+## Step 2: Run Insider and Academic in Parallel
+
+Launch BOTH agents simultaneously using the Agent tool:
+
+```
+Agent(
+  subagent_type="challenger-insider",
+  prompt="[insider handoff with full context]",
+  description="Insider approach design"
+)
+
+Agent(
+  subagent_type="challenger-academic",
+  prompt="[academic handoff — problem + stack + constraints only]",
+  description="Academic approach design"
+)
+```
+
+**CRITICAL: Launch both in the SAME message** to run them in parallel. Do not wait for one before starting the other.
+
+Both agents return structured approach proposals (see agent definitions for format).
+</step>
+
+<step name="run_arbiter">
+## Step 3: Run the Arbiter
+
+Once both proposals are received, prepare the arbiter handoff:
+
+```markdown
+# Arbiter Challenge: [Task Name]
+
+## Original Task
+[The task description]
+
+## Tech Stack
+[Languages, frameworks, databases]
+
+## Constraints
+[Hard constraints that both approaches must satisfy]
+
+---
+
+## Proposal A: Insider Approach
+[Full insider proposal text]
+
+---
+
+## Proposal B: Academic Approach
+[Full academic proposal text]
+
+---
+
+Evaluate both approaches using your scoring framework. Produce a verdict with scorecard, synthesis recommendation, and performance tracking data.
+```
+
+Launch the arbiter:
+```
+Agent(
+  subagent_type="challenger-arbiter",
+  prompt="[arbiter handoff]",
+  description="Arbiter evaluation"
+)
+```
+</step>
+
+<step name="present_results">
+## Step 4: Present Results
+
+### In AI Automation mode (default):
+
+Parse the arbiter's verdict and present:
+
+```
+⟡🔮 MERLIN › Challenge Complete: [Task Name]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📊 Scorecard:
+   Insider:  [score]/110
+   Academic: [score]/110
+
+🏆 Verdict: [INSIDER | ACADEMIC | SYNTHESIS]
+   Confidence: [HIGH | MEDIUM | LOW]
+
+📝 Key Insight:
+   [The one-sentence insight from the arbiter]
+
+[If SYNTHESIS:]
+✨ Synthesis takes from Insider:
+   - [element 1]
+   - [element 2]
+
+✨ Synthesis takes from Academic:
+   - [element 1]
+   - [element 2]
+
+[If confidence is LOW:]
+⚠️  Low confidence — recommend discussing before proceeding.
+```
+
+Then auto-record the challenge:
+```
+Call: merlin_record_challenge
+```
+
+### In Control mode:
+
+Present the full arbiter report and ask the user to choose:
+```
+[1] Accept the arbiter's recommendation
+[2] Go with the Insider approach
+[3] Go with the Academic approach
+[4] Discuss further before deciding
+```
+</step>
+
+<step name="record_outcome">
+## Step 5: Record the Challenge
+
+Call the MCP tool to track this challenge for long-term analytics:
+
+```
+Call: merlin_record_challenge
+  task: "[task description]"
+  insiderScore: [number]
+  academicScore: [number]
+  verdict: "insider" | "academic" | "synthesis"
+  synthesisRatio: [0.0-1.0]
+  confidence: "high" | "medium" | "low"
+  keyInsight: "[one sentence]"
+  phase: "[phase number if applicable]"
+```
+
+Show tracking confirmation:
+```
+⟡🔮 MERLIN › Challenge recorded · Run /merlin:challenge-stats to see trends
+```
+</step>
+
+</process>
+
+<integration_with_planning>
+## Auto-Challenge During Planning
+
+This command can be invoked automatically during `/merlin:plan-phase` when:
+- The phase involves architectural decisions
+- The phase touches 5+ files
+- The phase introduces new patterns or services
+- The user has enabled `auto_challenge: true` in merlin config
+
+When auto-invoked, prefix output with:
+```
+⟡🔮 MERLIN › Auto-challenge triggered for Phase [N] — checking if current approach is optimal
+```
+</integration_with_planning>
+
+<anti_patterns>
+- Don't run challenges for trivial tasks (config changes, typo fixes, docs)
+- Don't let the insider see the academic's output before submitting (and vice versa)
+- Don't skip the arbiter — the synthesis is where the real value is
+- Don't ignore LOW confidence verdicts — they mean genuine uncertainty
+- Don't run challenges sequentially — always parallel insider + academic
+</anti_patterns>
+
+<success_criteria>
+- [ ] Insider and Academic run in parallel (not sequentially)
+- [ ] Academic receives NO codebase-specific information
+- [ ] Arbiter produces scored comparison with weighted criteria
+- [ ] Verdict is recorded via merlin_record_challenge
+- [ ] User sees clear, actionable recommendation
+- [ ] Challenge completes in under 5 minutes total
+</success_criteria>

package/files/hooks/session-start.sh

@@ -201,7 +201,7 @@ _voice_note=""
 printf '{
   "hookSpecificOutput": {
     "hookEventName": "SessionStart",
-    "additionalContext": "STOP. Your FIRST action must be: call merlin_get_selected_repo, then call merlin_get_project_status, then show the user a status summary. Do not respond to the user until you complete these calls.%s"
+    "additionalContext": "STOP. Your FIRST action must be: call merlin_get_selected_repo, then call merlin_get_project_status, then call merlin_get_rules and merlin_get_brief in parallel. After boot, auto-detect the user intent and take action — do NOT just show options. Do not respond to the user until you complete the boot sequence.%s"
   }
 }\n' "${_voice_note}"
 

package/files/merlin/VERSION

@@ -1 +1 @@
-3.8.0-beta.1
+3.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-merlin-brain",
-  "version": "3.15.2",
+  "version": "3.18.0",
   "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",