create-merlin-brain 3.8.1 → 3.9.0

package/files/loop/merlin-session.sh

@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+# DEPRECATED: Use Claude Code's native /loop command instead.
+# See /merlin:loop-recipes for pre-built patterns.
+# This script is kept for backward compatibility only.
 #
 # ╔═══════════════════════════════════════════════════════════════════════════╗
 # ║  MERLIN SESSION - Interactive Deterministic Orchestrator                  ║

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-merlin-brain",
-  "version": "3.8.1",
+  "version": "3.9.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",
@@ -44,6 +44,7 @@
     "bin/",
     "dist/",
     "files/",
+    "rules/",
     "README.md"
   ],
   "dependencies": {

package/rules/go.md

@@ -0,0 +1,38 @@
+# Go Coding Rules
+
+## Error Handling
+- Handle every error explicitly — never discard with `_` unless truly safe (log a comment why)
+- Return errors to the caller; only wrap with `fmt.Errorf("context: %w", err)` at boundaries
+- Use `errors.Is` / `errors.As` for error inspection — never string comparison
+- Sentinel errors as package-level `var ErrFoo = errors.New("...")` for exported error types
+
+## Function Design
+- Accept interfaces, return structs — keeps callers flexible, keeps implementations concrete
+- Context (`context.Context`) as the first parameter on every I/O and long-running function
+- Short variable names in small scopes (`i`, `r`, `w`); descriptive names at package scope
+- No named return values except for `(err error)` in defer-based cleanup
+
+## Testing
+- Table-driven tests for all non-trivial functions:
+  ```go
+  tests := []struct{ name string; input X; want Y }{...}
+  for _, tt := range tests { t.Run(tt.name, func(t *testing.T) {...}) }
+  ```
+- Use `testify/assert` or standard `t.Errorf` — avoid panics in tests
+- Test files in the same package (white-box) for internals, `_test` package for public API
+
+## Concurrency
+- No global mutable state — pass dependencies explicitly or use struct fields
+- `sync.Mutex` for shared state; channels for signalling and work queues
+- Always check for goroutine leaks: every goroutine must have a clear exit path
+- Use `errgroup` for structured goroutine coordination
+
+## Code Organisation
+- One package per directory; package name matches directory name (no `util`, `common` packages)
+- Interfaces defined in the consuming package, not the implementing one
+- Constants grouped with `iota` enums; avoid magic numbers inline
+
+## Style
+- `gofmt` always (enforced in CI)
+- Comments on all exported identifiers — start with the identifier name
+- Struct field tags are valid JSON-serializable when used with encoding/json

package/rules/java.md

@@ -0,0 +1,36 @@
+# Java Coding Rules
+
+## Modern Java (16+)
+- `record` for immutable data classes — eliminates boilerplate getters/equals/hashCode
+- Sealed classes (`sealed interface`) for exhaustive type hierarchies
+- Pattern matching (`instanceof Foo f`) over manual casts
+- `switch` expressions with arrow syntax for concise pattern dispatch
+- Text blocks for multi-line strings (SQL, JSON templates)
+
+## Collections & Streams
+- Stream API for transforming collections — avoid imperative loops when streams are clearer
+- `Collectors.toUnmodifiableList/Map()` for defensive copies
+- Prefer `List.of()`, `Map.of()` for small literals (immutable)
+- `Optional<T>` for nullable return values — never return `null` from public methods
+
+## Null Safety
+- `Optional<T>` for methods that legitimately have no result
+- `@Nullable` / `@NonNull` annotations on all public API parameters and returns
+- Fail fast with `Objects.requireNonNull()` in constructors
+
+## Object Design
+- Builder pattern for types with >3 constructor parameters (use Lombok `@Builder` or manual)
+- Dependency injection via constructor — no field injection (`@Autowired` on fields)
+- Interfaces for all service contracts; `Impl` suffix only for the concrete class
+- Immutable by default: `final` fields, no setters on domain objects
+
+## Error Handling
+- Checked exceptions for recoverable errors callers must handle
+- Unchecked (`RuntimeException`) for programming errors and unrecoverable failures
+- Never swallow exceptions with empty catch blocks
+- Wrap and rethrow with context: `throw new ServiceException("failed to save user", cause)`
+
+## Testing
+- JUnit 5 with `@DisplayName` for descriptive test names
+- `@ParameterizedTest` with `@MethodSource` for table-driven tests
+- Mockito for mocking dependencies; assert interactions with `verify()`

package/rules/python.md

@@ -0,0 +1,38 @@
+# Python Coding Rules
+
+## Type Hints
+- Type hints on all function signatures — parameters and return types
+- Use `from __future__ import annotations` for forward references
+- Prefer concrete types (`list[str]`) over generic aliases (`List[str]`) for Python 3.9+
+- `Optional[X]` → `X | None` (Python 3.10+ union syntax preferred)
+
+## Data Structures
+- Dataclasses (`@dataclass`) for plain data containers — avoid raw dicts for structured data
+- Pydantic for validated data (API payloads, configs) — use `model_validator` not `__init__`
+- No mutable default arguments: `def foo(items=None): items = items or []` pattern
+- Prefer `TypedDict` over plain `dict` when shape is known and Pydantic is overkill
+
+## Strings & Output
+- f-strings for all string interpolation — never `%` formatting or `.format()` for new code
+- Multi-line strings: use triple-quoted f-strings, not concatenation
+- `str.join()` for building strings from lists — avoid `+=` in loops
+
+## File & Resource Handling
+- `pathlib.Path` for all filesystem paths — never `os.path.join` in new code
+- Context managers (`with`) for files, network connections, locks — never manual `.close()`
+- `tempfile` module for temporary files — never hardcode `/tmp/`
+
+## Functions & Classes
+- Single responsibility per function; >20 lines is a signal to refactor
+- Class methods that don't use `self` should be `@staticmethod` or module-level functions
+- `__slots__` on data classes where performance matters
+- Abstract base classes (`ABC`) to define interfaces; avoid duck-typing where contracts matter
+
+## Error Handling
+- Specific exceptions over `except Exception` — catch the narrowest type possible
+- Custom exception classes for domain errors (inherit from `Exception` with a clear name)
+- `logging` module, not `print()` — use structured log fields
+
+## Async
+- `asyncio.gather()` for concurrent coroutines — avoid sequential `await` in a loop
+- Mark I/O-bound functions `async def`; CPU-bound code stays sync (use `ProcessPoolExecutor`)

package/rules/rust.md

@@ -0,0 +1,34 @@
+# Rust Coding Rules
+
+## Ownership & Borrowing
+- Ownership over reference counting — prefer passing values or borrows over `Rc`/`Arc`
+- `Arc<Mutex<T>>` for shared mutable state across threads; document why sharing is needed
+- Avoid cloning in hot paths — profile before adding `.clone()` calls
+- Return owned values from functions that create data; accept borrows in functions that read
+
+## Error Handling
+- `Result<T, E>` for all fallible operations — never panic in library code
+- Custom error types with `thiserror` for libraries; `anyhow` for application binaries
+- `?` operator for propagation — avoid `unwrap()` in production code; prefer `expect("reason")`
+- Map errors at boundaries: `map_err(|e| MyError::Database(e))`
+
+## Types & Traits
+- Derive traits liberally: `#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]`
+- `impl` blocks immediately after their `struct`/`enum` definition in the same file
+- Prefer `&str` over `String` in function parameters (accepts both literals and owned strings)
+- `Into<T>` / `From<T>` for ergonomic conversions; implement `Display` for user-facing types
+
+## Structs & Enums
+- Exhaustive `match` on enums — no `_ =>` catch-all unless truly irrelevant variants exist
+- Newtype pattern (`struct UserId(u64)`) to prevent mixing domain IDs
+- Builder pattern for structs with many optional fields (derive with `typed-builder`)
+
+## Async
+- `tokio` for async runtime; `async-trait` for async in trait methods
+- `tokio::join!` / `tokio::try_join!` for concurrent futures
+- Avoid blocking calls inside async context — use `tokio::task::spawn_blocking`
+
+## Safety
+- No `unsafe` without a `// SAFETY:` comment explaining the invariant
+- Keep `unsafe` blocks as small as possible; encapsulate behind a safe API
+- Prefer `Vec` and slices over raw pointer arithmetic

package/rules/swift.md

@@ -0,0 +1,35 @@
+# Swift Coding Rules
+
+## Concurrency (Swift 6)
+- `async`/`await` for all asynchronous operations — no completion handler callbacks in new code
+- Actors for shared mutable state: `actor MyService { ... }`
+- `@MainActor` on UI-bound types and functions
+- `Sendable` conformance required for types crossing actor boundaries — use `@unchecked Sendable` sparingly with a justification comment
+- `async let` for independent concurrent work; `withTaskGroup` for dynamic concurrency
+
+## Types & Values
+- Value types (`struct`, `enum`) by default — use `class` only when reference semantics are required (identity, inheritance, Obj-C interop)
+- Protocol-oriented design: define capabilities as protocols, extend with default implementations
+- `enum` with associated values for discriminated unions instead of subclassing
+- Avoid `@objc` and `NSObject` subclasses unless required for interoperability
+
+## Optionals & Safety
+- `guard` for early returns when preconditions fail — keeps happy path unindented
+- Never force-unwrap (`!`) except in tests or `@IBOutlet` — use `guard let` or `if let`
+- `??` for default values on optionals; avoid chained optionals deeper than 2 levels
+- Mark parameters optional (`T?`) only when absence carries meaning; prefer overloads otherwise
+
+## Memory Management
+- `weak` references to break retain cycles (delegates, closures capturing self)
+- `unowned` only when the object is guaranteed to outlive the reference — prefer `weak` when uncertain
+- Use `[weak self]` captures in closures stored beyond the current scope
+
+## Protocols & Extensions
+- Small, focused protocols (Interface Segregation) — prefer many narrow protocols over one wide one
+- Extensions to add protocol conformances, keeping the type definition clean
+- `Codable` for serialisable types; `CodingKeys` enum to map non-Swift naming
+
+## Style
+- `let` by default; `var` only when mutation is needed
+- 4-space indentation, Allman-style braces
+- Prefer named parameters at call sites for clarity

package/rules/typescript.md

@@ -0,0 +1,38 @@
+# TypeScript Coding Rules
+
+## Type Safety
+- Enable strict mode — no `any` without an explicit justification comment
+- Prefer `unknown` over `any` for values of uncertain type; narrow with type guards
+- Use `satisfies` operator for type-safe literal assignments
+- Avoid type assertions (`as Foo`) unless interfacing with untyped third-party code
+
+## Variables & Functions
+- `const` by default, `let` only when reassignment is necessary — never `var`
+- `async`/`await` over raw Promise chains; avoid `.then()` chains longer than 2 steps
+- Explicit return types on exported functions; internal functions may infer
+- Exhaustive switch/case: add a `default` that asserts `never` to catch future enum additions
+
+## Interfaces & Types
+- `interface` for object shapes (extendable, declaration-merged)
+- `type` for unions, intersections, primitives, and mapped types
+- No empty interfaces (`interface Foo {}`); use `Record<never, never>` or a comment
+
+## Error Handling
+- Typed errors: extend `Error` with named subclasses for domain errors
+- No bare `catch (e) {}` — always log or rethrow with context
+- Use `Result<T, E>` patterns for expected failure paths (avoid throw-for-control-flow)
+- Wrap third-party calls in try/catch at the boundary, not deep in business logic
+
+## Imports & Modules
+- Use named exports; avoid default exports (harder to rename/trace)
+- Group imports: external packages → internal modules → relative paths (blank line between)
+- Barrel files (`index.ts`) only at module boundaries, not within a feature folder
+
+## Async & Concurrency
+- `Promise.all` for independent async operations (don't serialize what can parallelize)
+- Avoid `async` functions that never `await` anything
+- Always handle rejected promises — no floating promise anti-pattern
+
+## Null Safety
+- Prefer optional chaining (`?.`) and nullish coalescing (`??`) over manual null checks
+- Avoid optional properties (`foo?: string`) on data types; use `| null` for explicitness