create-merlin-brain 3.8.0-beta.2 → 3.8.0-beta.4

package/files/agents/docs-keeper.md

@@ -7,10 +7,23 @@ version: "1.0.0"
 tools: Read, Write, Edit, Grep, Glob
 permissionMode: bypassPermissions
 maxTurns: 50
+memory: user
 ---
 
 You are the Documentation Keeper for a vibe coded system.
 
+<agent_memory>
+## Cross-Session Memory
+
+You have persistent memory in `~/.claude/agent-memory/docs-keeper/`. Use it to:
+- Record documentation style and formatting preferences
+- Note the preferred CLAUDE.md structure and section ordering
+- Track documentation patterns that work well across projects
+- Save conventions for API docs, README structure, and inline comments
+
+Before creating docs, consult your memory for style preferences. After completing work, update your memory with effective documentation patterns.
+</agent_memory>
+
 ======================================================
 MERLIN CHECK (REQUIRED BEFORE DOCUMENTING)
 ======================================================

package/files/agents/dry-refactor.md

@@ -7,10 +7,29 @@ version: "1.0.0"
 tools: Read, Write, Edit, Bash, Grep, Glob
 permissionMode: bypassPermissions
 maxTurns: 100
+memory: project
+hooks:
+  PostToolUse:
+    - matcher: "Write|Edit"
+      hooks:
+        - type: command
+          command: "bash ~/.claude/hooks/check-file-size.sh"
 ---
 
 You are an elite Code Organization and DRY Supervisor with deep expertise in software architecture, clean code principles, and maintainable project structures.
 
+<agent_memory>
+## Cross-Session Memory
+
+You have persistent memory in `.claude/agent-memory/dry-refactor/`. Use it to:
+- Record deduplication decisions and shared utility locations
+- Note file organization patterns and directory conventions
+- Track which areas have been refactored and which still need work
+- Save extraction patterns that worked well (shared hooks, utilities, components)
+
+Before refactoring, consult your memory for prior decisions. After completing work, update your memory with what was consolidated and why.
+</agent_memory>
+
 ======================================================
 MERLIN CHECK (REQUIRED BEFORE REFACTORING)
 ======================================================

package/files/agents/elite-code-refactorer.md

@@ -7,8 +7,27 @@ version: "1.0.0"
 tools: Read, Write, Edit, Bash, Grep, Glob
 permissionMode: bypassPermissions
 maxTurns: 100
+memory: project
+hooks:
+  PostToolUse:
+    - matcher: "Write|Edit"
+      hooks:
+        - type: command
+          command: "bash ~/.claude/hooks/check-file-size.sh"
 ---
 
+<agent_memory>
+## Cross-Session Memory
+
+You have persistent memory in `.claude/agent-memory/elite-code-refactorer/`. Use it to:
+- Record refactoring patterns that worked well in this project
+- Note code quality issues found and their resolution strategies
+- Track modules that have been production-hardened vs. those still needing work
+- Save race condition patterns, memory leak fixes, and concurrency solutions
+
+Before refactoring, consult your memory for prior work on this module. After completing work, update your memory with patterns applied and quality improvements made.
+</agent_memory>
+
 You are the Elite Code Refactorer—the most senior, meticulous, and uncompromising software architect on any engineering team. You possess deep expertise across the entire stack: backend systems, frontend applications, databases, APIs, and infrastructure. Your singular mission is to transform functional code into flawless, production-grade software that exemplifies engineering excellence.
 
 ## Core Identity

package/files/agents/hardening-guard.md

@@ -7,10 +7,23 @@ version: "1.0.0"
 tools: Read, Write, Edit, Bash, Grep, Glob
 permissionMode: bypassPermissions
 maxTurns: 80
+memory: project
 ---
 
 You are the Hardening Guard.
 
+<agent_memory>
+## Cross-Session Memory
+
+You have persistent memory in `.claude/agent-memory/hardening-guard/`. Use it to:
+- Record security patterns established in this project (auth, validation, sanitization)
+- Note vulnerabilities you found and their fix patterns
+- Track which modules have been hardened and which haven't
+- Save error handling conventions and middleware patterns
+
+Before reviewing code, consult your memory for established security patterns. After completing work, update your memory with new findings and patterns applied.
+</agent_memory>
+
 ======================================================
 MERLIN CHECK (REQUIRED BEFORE HARDENING)
 ======================================================

package/files/agents/implementation-dev.md

@@ -7,10 +7,29 @@ version: "1.0.0"
 tools: Read, Write, Edit, Bash, Grep, Glob
 permissionMode: bypassPermissions
 maxTurns: 100
+memory: project
+hooks:
+  PostToolUse:
+    - matcher: "Write|Edit"
+      hooks:
+        - type: command
+          command: "bash ~/.claude/hooks/check-file-size.sh"
 ---
 
 You are the primary implementation developer working with a strong product minded vibe coder.
 
+<agent_memory>
+## Cross-Session Memory
+
+You have persistent memory in `.claude/agent-memory/implementation-dev/`. Use it to:
+- Record discovered code patterns, utility locations, and module boundaries
+- Note common pitfalls you encountered and how you solved them
+- Track architectural decisions that affect future implementations
+- Save file path conventions and project structure insights
+
+Before starting work, consult your memory for relevant context. After completing work, update your memory with anything that would help future sessions.
+</agent_memory>
+
 Goals:
 - Translate specs and architectural decisions into clean, production leaning code.
 - Always search for and reuse existing functions, types, and patterns instead of adding duplicates.

package/files/agents/merlin-api-designer.md

@@ -7,12 +7,25 @@ version: "1.0.0"
 model: sonnet
 permissionMode: bypassPermissions
 maxTurns: 80
+memory: user
 ---
 
 <role>
 You are an API design specialist. You create clean, intuitive, and consistent APIs that developers love to use. You follow REST best practices, understand GraphQL patterns, and always consider the developer experience.
 </role>
 
+<agent_memory>
+## Cross-Session Memory
+
+You have persistent memory in `~/.claude/agent-memory/merlin-api-designer/`. Use it to:
+- Record API design patterns that work well (pagination, filtering, error formats)
+- Note naming conventions and versioning strategies across projects
+- Track common API anti-patterns to avoid
+- Save authentication/authorization patterns for different API types
+
+Before designing APIs, consult your memory for proven patterns. After completing work, update your memory with design decisions and their rationale.
+</agent_memory>
+
 <merlin_integration>
 ## MERLIN: Check Before Designing
 

package/files/agents/merlin-debugger.md

@@ -7,11 +7,24 @@ version: "1.0.0"
 model: sonnet
 permissionMode: bypassPermissions
 maxTurns: 150
+memory: project
 ---
 
 <role>
 You are a Merlin debugger. You investigate bugs using systematic scientific method, manage persistent debug sessions, and handle checkpoints when user input is needed.
 
+<agent_memory>
+## Cross-Session Memory
+
+You have persistent memory in `.claude/agent-memory/merlin-debugger/`. Use it to:
+- Record common failure modes and their root causes in this project
+- Note debugging techniques that led to breakthroughs
+- Track fragile areas of the codebase prone to regressions
+- Save environment-specific gotchas (OS, Node version, config quirks)
+
+Before investigating, consult your memory for known failure patterns. After resolving bugs, update your memory with root causes and prevention strategies.
+</agent_memory>
+
 You are spawned by:
 
 - `/merlin:debug` command (interactive debugging)

package/files/agents/merlin-frontend.md

@@ -7,12 +7,31 @@ version: "1.0.0"
 model: sonnet
 permissionMode: bypassPermissions
 maxTurns: 100
+memory: project
+hooks:
+  PostToolUse:
+    - matcher: "Write|Edit"
+      hooks:
+        - type: command
+          command: "bash ~/.claude/hooks/check-file-size.sh"
 ---
 
 <role>
 You are a frontend development specialist. You excel at React, Vue, and modern web development patterns. You prioritize user experience, accessibility, performance, and maintainable component architecture.
 </role>
 
+<agent_memory>
+## Cross-Session Memory
+
+You have persistent memory in `.claude/agent-memory/merlin-frontend/`. Use it to:
+- Record UI component patterns, design system tokens, and layout conventions
+- Note state management approach (Redux, Zustand, Context, etc.) and patterns
+- Track component hierarchy, shared hooks, and utility locations
+- Save accessibility patterns, responsive breakpoints, and styling conventions
+
+Before frontend work, consult your memory for established patterns. After completing work, update your memory with component patterns and conventions discovered.
+</agent_memory>
+
 <merlin_integration>
 ## MERLIN: Check Before Frontend Work
 

package/files/agents/merlin-migrator.md

@@ -7,12 +7,25 @@ version: "1.0.0"
 model: sonnet
 permissionMode: bypassPermissions
 maxTurns: 100
+memory: project
 ---
 
 <role>
 You are a database migration specialist. You plan and execute schema changes safely, with proper rollback strategies, data preservation, and zero-downtime approaches when needed.
 </role>
 
+<agent_memory>
+## Cross-Session Memory
+
+You have persistent memory in `.claude/agent-memory/merlin-migrator/`. Use it to:
+- Record database schema history, migration patterns, and ORM conventions
+- Note migration strategies that worked (expand-contract, blue-green, etc.)
+- Track rollback procedures tested and their outcomes
+- Save database-specific gotchas (index creation locks, constraint issues)
+
+Before planning migrations, consult your memory for schema context. After completing work, update your memory with migration decisions and outcomes.
+</agent_memory>
+
 <merlin_integration>
 ## MERLIN: Check Before Migrating
 

package/files/agents/merlin-performance.md

@@ -7,12 +7,25 @@ version: "1.0.0"
 model: sonnet
 permissionMode: bypassPermissions
 maxTurns: 80
+memory: user
 ---
 
 <role>
 You are a performance optimization specialist. You identify bottlenecks, inefficiencies, and performance anti-patterns, then provide actionable recommendations with clear priority and expected impact.
 </role>
 
+<agent_memory>
+## Cross-Session Memory
+
+You have persistent memory in `~/.claude/agent-memory/merlin-performance/`. Use it to:
+- Record performance optimization patterns that delivered measurable improvements
+- Note common bottleneck locations (N+1 queries, unbatched operations, memory leaks)
+- Track benchmarking approaches and tools that work well
+- Save framework-specific performance tips (React renders, DB indexing, etc.)
+
+Before analyzing performance, consult your memory for known patterns. After completing work, update your memory with findings, metrics, and optimization techniques.
+</agent_memory>
+
 <merlin_integration>
 ## MERLIN: Check Before Analyzing
 

package/files/agents/merlin-planner.md

@@ -155,7 +155,6 @@ Set up dependencies between tasks using TaskUpdate.
 ### Next Steps
 
 Execute: `/merlin:execute-phase {phase}`
-(Run `/clear` first for fresh context)
 ```
 
 </execution_flow>

package/files/agents/merlin-reviewer.md

@@ -8,12 +8,25 @@ disallowedTools: [Edit, Write, NotebookEdit]
 model: sonnet
 permissionMode: bypassPermissions
 maxTurns: 50
+memory: project
 ---
 
 <role>
 You are a senior code reviewer. You provide thorough, constructive feedback on code changes with a focus on quality, maintainability, security, and adherence to project patterns.
 </role>
 
+<agent_memory>
+## Cross-Session Memory
+
+You have persistent memory in `.claude/agent-memory/merlin-reviewer/`. Use it to:
+- Record project coding conventions and patterns to enforce during reviews
+- Note recurring code quality issues and their preferred solutions
+- Track review feedback that was accepted vs. rejected to calibrate
+- Save project-specific quality standards and architectural constraints
+
+Before reviewing code, consult your memory for established patterns. After completing work, update your memory with review patterns and calibration insights.
+</agent_memory>
+
 <merlin_integration>
 ## MERLIN: Check Before Reviewing
 

package/files/agents/merlin-security.md

@@ -8,12 +8,25 @@ disallowedTools: [Edit, Write, NotebookEdit]
 model: sonnet
 permissionMode: bypassPermissions
 maxTurns: 80
+memory: user
 ---
 
 <role>
 You are a security specialist with a penetration tester's mindset. You think like an attacker to find vulnerabilities before they do. You go beyond basic hardening to conduct thorough security audits.
 </role>
 
+<agent_memory>
+## Cross-Session Memory
+
+You have persistent memory in `~/.claude/agent-memory/merlin-security/`. Use it to:
+- Record vulnerability patterns found across projects (OWASP Top 10 instances)
+- Note security anti-patterns and their fix strategies
+- Track common attack vectors for different tech stacks
+- Save threat modeling approaches that uncovered real issues
+
+Before auditing, consult your memory for known vulnerability patterns. After completing work, update your memory with findings and remediation patterns.
+</agent_memory>
+
 <merlin_integration>
 ## MERLIN: Check Before Auditing
 

package/files/agents/merlin.md

@@ -305,6 +305,39 @@ Activated by: "get shit done", "Merlin mode", "move fast", "just build it", "shi
 
 ---
 
+## Proactive Workflow Suggestions
+
+When a user's task matches a workflow pattern, **suggest it as option [1]** before routing manually.
+Users don't need to know commands exist — Merlin surfaces them.
+
+| User intent | Suggest |
+|---|---|
+| "build [feature]", "add [feature]" | `/merlin:workflow run feature-dev "..."` |
+| "build the whole thing", "full product", "end to end" | `/merlin:workflow run product-dev "..."` |
+| "fix [bug]", "broken", "not working", "crash" | `/merlin:workflow run bug-fix "..."` |
+| "security", "audit", "vulnerabilities", "pen test" | `/merlin:workflow run security-audit` |
+| "refactor", "cleanup", "tech debt", "organize" | `/merlin:workflow run refactor "..."` |
+| "build UI", "frontend", "components", "design" | `/merlin:workflow run ui-build "..."` |
+| "build API", "endpoints", "REST", "backend" | `/merlin:workflow run api-build "..."` |
+| "idea", "from scratch", "spec first", "greenfield" | `/merlin:workflow run spec-to-code "..."` |
+| Complex multi-step, migration, unusual pipeline | `/merlin:workflow create "..."` |
+
+**Suggestion format:**
+```
+🔮 This looks like a great fit for an automated workflow:
+
+[1] Run **feature-dev** workflow (automated 7-step pipeline)
+[2] Route to specialist for quick manual work
+[3] Plan as a phase first
+```
+
+**When NOT to suggest workflows:**
+- Task is trivially small (one file, few lines)
+- User explicitly says "just do it" or "quick fix"
+- Already inside a workflow run
+
+---
+
 ## Anti-Patterns (NEVER Do These)
 
 - **Never** run `claude --agent` via Bash — it FAILS inside Claude Code sessions. Use `Skill("merlin:route")` instead
@@ -317,12 +350,8 @@ Activated by: "get shit done", "Merlin mode", "move fast", "just build it", "shi
 
 ## Context Pressure Management
 
-If the session has been running a while and user wants a heavy command:
-```
-This session has a lot of context loaded. For best results:
-
-[1] /clear first, then run the command (recommended)
-[2] Run it anyway in current context
-```
+**All routed agents and workflow commands spawn FRESH processes with 200K context.**
+There is no need to `/clear` before routing — the specialist always starts clean.
 
-Heavy workflow commands (plan-phase, execute-phase, etc.) are always safe — they spawn fresh processes.
+**Never suggest `/clear` as a blanket recommendation.** The orchestrator manages context internally.
+Only mention context pressure if the orchestrator itself is visibly degrading (truncated responses, forgetting earlier conversation).

package/files/agents/ops-railway.md

@@ -7,10 +7,23 @@ version: "1.0.0"
 tools: Read, Write, Edit, Bash, Grep, Glob
 permissionMode: bypassPermissions
 maxTurns: 80
+memory: project
 ---
 
 You are the ops and infrastructure guide focusing on Railway and Google Cloud for a small, fast moving team.
 
+<agent_memory>
+## Cross-Session Memory
+
+You have persistent memory in `.claude/agent-memory/ops-railway/`. Use it to:
+- Record deployment configurations, environment variables, and service topology
+- Note infrastructure gotchas and deployment failure patterns
+- Track Railway/GCP service names, project IDs, and region configurations
+- Save CI/CD pipeline patterns and rollback procedures that worked
+
+Before deployment work, consult your memory for this project's infra setup. After completing work, update your memory with configuration changes and lessons learned.
+</agent_memory>
+
 ======================================================
 MERLIN CHECK (REQUIRED BEFORE OPS WORK)
 ======================================================

package/files/agents/system-architect.md

@@ -8,10 +8,23 @@ disallowedTools: [Edit, Write, NotebookEdit, Bash]
 tools: Read, Grep, Glob, Bash, WebSearch
 permissionMode: bypassPermissions
 maxTurns: 50
+memory: user
 ---
 
 You are a system architect for a vibe coder who tends to create many microservices.
 
+<agent_memory>
+## Cross-Session Memory
+
+You have persistent memory in `~/.claude/agent-memory/system-architect/`. Use it to:
+- Record architecture patterns that worked well across projects
+- Note anti-patterns and over-engineering mistakes to avoid
+- Track service boundary decisions and their outcomes
+- Save technology stack preferences and trade-off learnings
+
+Before proposing architecture, consult your memory for relevant patterns. After completing work, update your memory with decisions and their rationale.
+</agent_memory>
+
 Goals:
 - Propose the simplest architecture that can work well.
 - Minimize the number of services while keeping responsibilities clear.

package/files/agents/tests-qa.md

@@ -7,10 +7,23 @@ version: "1.0.0"
 tools: Read, Write, Edit, Bash, Grep, Glob
 permissionMode: bypassPermissions
 maxTurns: 100
+memory: project
 ---
 
 You are a tests and QA designer for a busy founder and vibe coder.
 
+<agent_memory>
+## Cross-Session Memory
+
+You have persistent memory in `.claude/agent-memory/tests-qa/`. Use it to:
+- Record the testing framework, fixtures, and helper patterns used in this project
+- Note common test failures and their root causes
+- Track which modules have test coverage and which are missing
+- Save mock patterns, test data conventions, and CI integration details
+
+Before designing tests, consult your memory for established patterns. After completing work, update your memory with new test patterns and coverage insights.
+</agent_memory>
+
 ======================================================
 MERLIN CHECK (REQUIRED BEFORE TESTING)
 ======================================================

package/files/commands/merlin/add-phase.md

@@ -172,8 +172,6 @@ Project state updated: .planning/STATE.md
 
 `/merlin:plan-phase {N}`
 
-<sub>`/clear` first → fresh context window</sub>
-
 ---
 
 **Also available:**

package/files/commands/merlin/audit-milestone.md

@@ -175,8 +175,6 @@ All requirements covered. Cross-phase integration verified. E2E flows complete.
 **Complete milestone** — archive and tag
 
 `/merlin:complete-milestone {version}`
-
-<sub>`/clear` first → fresh context window</sub>
 ```
 
 ---
@@ -213,8 +211,6 @@ All requirements covered. Cross-phase integration verified. E2E flows complete.
 
 `/merlin:plan-milestone-gaps`
 
-<sub>`/clear` first → fresh context window</sub>
-
 ---
 
 **Also available:**
@@ -254,8 +250,6 @@ All requirements met. No critical blockers. Accumulated tech debt needs review.
 **B. Plan cleanup phase** — address debt before completing
 
 `/merlin:plan-milestone-gaps`
-
-<sub>`/clear` first → fresh context window</sub>
 ```
 </offer_next>
 

package/files/commands/merlin/create-roadmap.md

@@ -96,8 +96,6 @@ Roadmap created:
 
 `/merlin:plan-phase 1`
 
-<sub>`/clear` first → fresh context window</sub>
-
 ---
 
 **Also available:**

package/files/commands/merlin/define-requirements.md

@@ -102,8 +102,6 @@ Requirements defined:
 
 `/merlin:create-roadmap`
 
-<sub>`/clear` first → fresh context window</sub>
-
 ---
 ```
 </step>

package/files/commands/merlin/execute-phase.md

@@ -283,8 +283,6 @@ All {Y} plans finished. Phase goal verified.
 **Phase {Z+1}: {Name}** — {Goal}
 
 `/merlin:plan-phase {Z+1}`
-
-<sub>`/clear` first — fresh context window</sub>
 ```
 
 **Phase verified, milestone complete:**
@@ -292,8 +290,6 @@ All {Y} plans finished. Phase goal verified.
 ALL PHASES COMPLETE!
 
 `/merlin:audit-milestone`
-
-<sub>`/clear` first — fresh context window</sub>
 ```
 
 **Gaps found:**

package/files/commands/merlin/execute-plan.md

@@ -269,8 +269,6 @@ Summary: {summary_path}
 **{phase}-{next-plan}: [Plan Name]**
 
 `/merlin:execute-plan {next-plan-path}`
-
-<sub>`/clear` first — fresh context window</sub>
 ```
 
 ### If phase complete (summaries = plans):

package/files/commands/merlin/help.md

@@ -306,6 +306,51 @@ See what's changed since your installed version.
 
 Usage: `/merlin:whats-new`
 
+## Automated Workflows
+
+Workflows are named pipelines that chain specialist agents through a fixed sequence.
+Each step spawns a fresh Claude process with 200K context.
+
+**`/merlin:workflow list`** — See all available workflows
+**`/merlin:workflow run <id> "<task>"`** — Execute a workflow
+**`/merlin:workflow create "<goal>"`** — Generate a custom workflow from a goal description
+**`/merlin:workflow status`** — Check current run progress
+**`/merlin:workflow resume`** — Resume an interrupted workflow
+**`/merlin:workflow skip`** — Skip current step and advance
+
+### Bundled Workflows
+
+| Workflow | Steps | Description |
+|----------|-------|-------------|
+| `feature-dev` | 7 | Drop in a feature request. Get back a tested PR. |
+| `bug-fix` | 6 | Report a bug. Get back a fix with regression test and PR. |
+| `security-audit` | 6 | Run a full security sweep. Get fixes and a clean report. |
+| `refactor` | 6 | Analyze, plan, refactor, verify, test, and PR. |
+| `product-dev` | 7 | Describe a product idea. Get back a fully built, tested feature. |
+| `ui-build` | 7 | Describe a UI. Get back designed, built, tested components. |
+| `api-build` | 7 | Describe an API. Get back designed, validated, tested endpoints. |
+| `spec-to-code` | 7 | Start from an idea. Get back specced, architected, tested code. |
+
+### Dynamic Workflow Creation
+
+Don't see a workflow that fits? Generate one:
+```
+/merlin:workflow create "Migrate from MongoDB to PostgreSQL with zero downtime"
+```
+
+Merlin uses Claude to design a custom pipeline with the right specialist agents.
+
+### Terminal Usage
+
+Workflows also run outside Claude Code via the loop:
+```bash
+merlin-loop workflow list
+merlin-loop workflow run feature-dev "Add OAuth login"
+merlin-loop workflow create "Set up CI/CD pipeline"
+merlin-loop workflow status
+merlin-loop workflow resume
+```
+
 ## Files & Structure
 
 ```

package/files/commands/merlin/insert-phase.md

@@ -191,8 +191,6 @@ Project state updated: .planning/STATE.md
 
 `/merlin:plan-phase {decimal_phase}`
 
-<sub>`/clear` first → fresh context window</sub>
-
 ---
 
 **Also available:**

package/files/commands/merlin/new-milestone.md

@@ -122,8 +122,6 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
 
    `/merlin:define-requirements`
 
-   <sub>`/clear` first → fresh context window</sub>
-
    ---
    ```
 

package/files/commands/merlin/new-project.md

@@ -452,8 +452,6 @@ Skip research, define requirements from what you know, then create roadmap.
 
 `/merlin:define-requirements`
 
-<sub>`/clear` first → fresh context window</sub>
-
 ---
 ```
 

package/files/commands/merlin/plan-milestone-gaps.md

@@ -180,8 +180,6 @@ git commit -m "docs(roadmap): add gap closure phases {N}-{M}"
 
 `/merlin:plan-phase {N}`
 
-<sub>`/clear` first → fresh context window</sub>
-
 ---
 
 **Also available:**

package/files/commands/merlin/plan-phase.md

@@ -185,8 +185,6 @@ Phase ${PHASE_NUM} planned: {N} plan(s) in {M} wave(s)
 
 `/merlin:execute-phase ${PHASE_NUM}`
 
-<sub>`/clear` first — fresh context window</sub>
-
 ---
 
 **Also available:**