create-merlin-brain 5.0.1 → 5.3.1

package/README.md

@@ -9,11 +9,26 @@
   ╚═╝     ╚═╝╚══════╝╚═╝  ╚═╝╚══════╝╚═╝╚═╝  ╚═══╝
 ```
 
-Merlin is a complete AI-powered development system for Claude Code, Codex, and other CLI runtimes with three integrated layers:
+Merlin curates the best of the Claude Code and Codex CLI ecosystem and wires it together — automated, opinionated, and kept in sync. We didn't invent context engineering, spec-driven workflows, or adversarial code review. We integrated them. One install, you get the patterns the community converged on, made discoverable through slash commands, specialist agents, lifecycle hooks, and an MCP-backed knowledge layer. This is the AI development system connecting Claude Code, Codex CLI, MCP, and the broader ecosystem into a coherent whole.
 
-- **Merlin Sights** - Knowledge layer (instant codebase context)
-- **Merlin Workflows** - Planning & execution (`/merlin:*` commands)
-- **Merlin Agents** - Specialist agents for every task
+---
+
+## Standing on the shoulders of
+
+Merlin would not exist without these projects. We adapted patterns, code, and ideas from each — and we credit them in [`NOTICE.md`](./NOTICE.md). The full machine-readable ledger is in [`upstreams.yaml`](./upstreams.yaml).
+
+| Upstream | What we credit | Link |
+|---|---|---|
+| **GSD (Get Shit Done)** | `.planning/` schema, `/merlin:quick`, `/merlin:health --repair`, fresh-context execution model, multi-runtime adapter pattern | [gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done) |
+| **BMAD-METHOD** | `<critical_actions>` agent hardening, adversarial reviewer, edge-case-hunter, party-review, `/merlin:next`, `/merlin:readiness-gate`, `/merlin:course-correct`, dialectic challenge | [bmad-code-org/BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) |
+| **Ralph Wiggum technique** | Merlin Loop (autonomous iterate-on-failure pattern) | [snwfdhmp/awesome-ralph](https://github.com/snwfdhmp/awesome-ralph) |
+| **Claude Code Best Practice** (shanraisshan) | Curated index of Claude Code patterns we draw from | [shanraisshan/claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice) |
+
+Full attribution and per-file provenance in [`NOTICE.md`](./NOTICE.md).
+
+> Note: The historical internal `get-shit-done/` directory in this repo (deleted in commit `bfe5d2c` v3.0.0) was an unrelated Merlin sub-package, not lifted from external GSD.
+
+---
 
 ## Quick Install
 
@@ -153,6 +168,25 @@ When enabled, the badge swaps to `⟡🔮↔🔮 MERLIN·DUO ›` so you always
 
 Full rules: `~/.claude/rules/duo-routing.md`.
 
+## Standalone Codex Users
+
+If you run Codex directly (without Claude Code), use `merlin-codex` as a drop-in wrapper to get the Merlin orchestrator persona on every invocation:
+
+```bash
+merlin-codex                        # opens interactive Codex shell with Merlin banner
+merlin-codex exec "add auth login"  # exec with Merlin system prompt prepended
+merlin-codex "fix the failing test" # prompt mode with Merlin prompt prepended
+merlin-codex login                  # pass-through — no prompt injection
+```
+
+The wrapper prints the Merlin banner to stderr, loads `~/.claude/merlin-system-prompt.txt` (falls back to a one-liner if missing), and forwards all management subcommands (`login`, `logout`, `mcp`, etc.) unchanged.
+
+## Recommended reading
+
+The single best curated index of Claude Code patterns we draw from:
+
+- **[shanraisshan/claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice)** — 49k★ — community-curated catalog of 82 tips, 10+ workflow taxonomies, and expert distillations from Boris Cherny, Anthropic staff, and the broader community. Endorsed by the Claude Code creator. If you want to understand the patterns Merlin automates, start here.
+
 ## Documentation
 
 Visit [merlin.build/docs](https://merlin.build/docs) for full documentation.

package/bin/install.cjs

@@ -1609,6 +1609,19 @@ async function install() {
     quiet: true, // step 2 already printed the detection summary
   });
 
+  // Step 13.5: Install priority design skills (async, non-blocking)
+  if (!process.env.MERLIN_SKIP_DESIGN_SKILLS) {
+    try {
+      const { spawn } = require('child_process');
+      const designSkillsScript = path.join(SCRIPTS_DIR, 'install-design-skills.sh');
+      if (fs.existsSync(designSkillsScript)) {
+        spawn('bash', [designSkillsScript], { stdio: 'inherit', detached: false });
+      }
+    } catch (err) {
+      // Non-fatal: design skills install failure does not block the main installer
+    }
+  }
+
   // Shell integration (runs after runtime adapters)
   log(`\n${colors.cyan}[shell]${colors.reset} Setting up shell integration...`);
   const shellConfigured = setupShellIntegration();
@@ -1641,6 +1654,13 @@ ${colors.cyan}Autonomous Mode (Merlin Loop):${colors.reset}
      ${colors.bright}merlin-loop build${colors.reset}     - Execute tasks autonomously
      ${colors.bright}merlin-loop --afk auto${colors.reset} - Run unattended with safety limits
 
+${colors.cyan}Universal Task Optimization (NEW in 5.3.0):${colors.reset}
+  • Every task gets the right skill + agent automatically
+  • ${colors.bright}/merlin:optimize "<task>"${colors.reset}  - Preview the recommendation
+  • ${colors.bright}/merlin:design-audit${colors.reset}     - Design review with impeccable + emil
+  • ${colors.bright}/merlin:polish${colors.reset}           - Animation polish via animation-expert
+  • ${colors.bright}/merlin:redesign${colors.reset}         - Full redesign via ui-builder
+
 ${colors.cyan}Merlin works with or without Sights:${colors.reset}
   • ${colors.green}With Sights${colors.reset}: Instant context, cross-session memory
   • ${colors.green}Without${colors.reset}: Full workflows, uses file exploration

package/dist/server/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAwDpE,0CAA0C;AAC1C,wBAAgB,YAAY,IAAI,SAAS,CA4gGxC;AAED,gDAAgD;AAChD,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CA+CjD"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAyDpE,0CAA0C;AAC1C,wBAAgB,YAAY,IAAI,SAAS,CA4lGxC;AAED,gDAAgD;AAChD,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CA+CjD"}

package/dist/server/server.js

@@ -37,6 +37,7 @@ import { registerAutoModeTools } from './tools/auto-mode.js';
 import { registerDreamTools } from './tools/dream.js';
 import { registerComputerUseTools } from './tools/computer-use.js';
 import { registerSkillsTools } from './tools/skills.js';
+import { registerProjectPictureTools } from './tools/project-picture.js';
 import { wrapResponse, getStats, getCompactStats, formatSaveNotification, markSessionStatusShown } from './stats.js';
 import { coachWrap, recordToolCall } from './session-coach.js';
 /** Load saved config from ~/.merlin/config.json */
@@ -608,6 +609,69 @@ export function createServer() {
             if (teachBackPrompt) {
                 context += teachBackPrompt;
             }
+            // ── Phase 9 Wave 4: Project Picture augmentation ─────────────────────
+            // Always-populated on tracked repos (any non-default repository_branches rows).
+            // Feature-flagged; when flag off or API unavailable this is a silent no-op.
+            if (process.env.MERLIN_CROSS_BRANCH_ENABLED === 'true') {
+                try {
+                    // Infer current branch from git HEAD
+                    let currentBranch = null;
+                    try {
+                        const { execFile } = await import('child_process');
+                        const { promisify } = await import('util');
+                        const execFileAsync = promisify(execFile);
+                        const { stdout } = await execFileAsync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { timeout: 3000 });
+                        const b = stdout.trim();
+                        if (b && b !== 'HEAD')
+                            currentBranch = b;
+                    }
+                    catch { /* non-fatal */ }
+                    const apiBase = process.env.MERLIN_API_URL ?? 'https://auth.merlin.build';
+                    const ppUrl = new URL(`/api/repos/${repoId}/project-picture`, apiBase);
+                    if (currentBranch)
+                        ppUrl.searchParams.set('branch', currentBranch);
+                    if (task)
+                        ppUrl.searchParams.set('task', task.slice(0, 200));
+                    const ppHeaders = { 'Content-Type': 'application/json' };
+                    const ppKey = process.env.MERLIN_API_KEY;
+                    if (ppKey)
+                        ppHeaders['Authorization'] = `Bearer ${ppKey}`;
+                    const ppResp = await fetch(ppUrl.toString(), {
+                        headers: ppHeaders,
+                        signal: AbortSignal.timeout(5000),
+                    });
+                    if (ppResp.ok) {
+                        const pp = await ppResp.json();
+                        // Always include even with zero signals so agent knows other branches exist
+                        context += `\n## 🌿 Project Picture (cross-branch)\n`;
+                        context += `_${pp.disclaimer}_\n\n`;
+                        context += `**Current Branch:** \`${pp.currentBranch}\`\n`;
+                        if (pp.liveBranches && pp.liveBranches.length > 0) {
+                            context += `**Live Branches (${pp.liveBranches.length}):** ${pp.liveBranches.slice(0, 8).map(b => `\`${b.name}\``).join(', ')}\n`;
+                        }
+                        else {
+                            context += `**Live Branches:** _(none — single-branch workspace)_\n`;
+                        }
+                        if (pp.signals && pp.signals.length > 0) {
+                            const topSignals = pp.signals.slice(0, 5);
+                            context += `\n**Signals (top ${topSignals.length}):**\n`;
+                            for (const s of topSignals) {
+                                const emoji = s.kind === 'drift' ? '⚠️' : '💡';
+                                context += `${emoji} **${s.kind}** \`${s.filePath}\` severity=${s.severity.toFixed(2)} — ${s.summary}\n`;
+                                context += `  _(${s.sourceBranch} → ${s.targetBranch})_\n`;
+                            }
+                        }
+                        else {
+                            context += `**Signals:** _(none — no cross-branch conflicts detected)_\n`;
+                        }
+                        context += '\n';
+                    }
+                }
+                catch {
+                    // Strictly best-effort — never break context delivery
+                }
+            }
+            // ── End Project Picture augmentation ─────────────────────────────────
             // Wrap with visual header and stats
             const wrappedContext = wrapResponse('merlin_get_context', context, {
                 task,
@@ -2772,6 +2836,17 @@ export function createServer() {
         client,
         resolveRepoId,
     });
+    // ============================================================
+    // PROJECT PICTURE TOOLS - Cross-branch drift + opportunity signals
+    // Phase 9 Wave 4 — works locally (no cloud API key needed)
+    // Feature-flagged: MERLIN_CROSS_BRANCH_ENABLED=true activates signals
+    // ============================================================
+    registerProjectPictureTools({
+        server,
+        client,
+        resolveRepoId,
+        getRepoRootPath,
+    });
     return server;
 }
 /** Start the MCP server with stdio transport */