create-merlin-brain 3.8.2 → 3.10.0

package/files/commands/merlin/loop-recipes.md

@@ -0,0 +1,73 @@
+---
+name: merlin:loop-recipes
+description: Show pre-built /loop patterns for common Merlin workflows
+---
+
+<objective>
+Display pre-built `/loop` recipes for common Merlin workflows.
+
+Output ONLY the reference content below. Do NOT add:
+
+- Project-specific analysis
+- Git status or file context
+- Next-step suggestions
+- Any commentary beyond the reference
+</objective>
+
+<reference>
+# Merlin Loop Recipes
+
+Pre-built `/loop` patterns for common Merlin workflows. Copy and use directly.
+
+## Development Monitoring
+
+- `/loop 5m /merlin:progress` — Check project progress every 5 minutes
+- `/loop 2m check build status and report any failures` — CI monitoring
+- `/loop 10m /merlin:standup` — Running standup summary
+- `/loop 15m check if any new errors appeared in the logs` — Log monitoring
+
+## Code Quality
+
+- `/loop 30m scan for files over 400 lines and list them` — File size monitoring
+- `/loop 1h review recent changes for security issues` — Security patrol
+- `/loop 4h check if documentation is up to date with recent code changes` — Doc freshness
+- `/loop 2h scan for duplicate code or functions that do the same thing` — DRY check
+
+## Sights & Context
+
+- `/loop 30m merlin_get_context("current work progress")` — Keep Sights context warm
+- `/loop 1h merlin_lite_refresh()` — Refresh local Sights analysis
+- `/loop 6h run /merlin:map-codebase to keep codebase index fresh` — Index freshness
+
+## Deployment
+
+- `/loop 2m check Railway deployment status` — Deploy monitoring
+- `/loop 5m check if PR checks have passed` — PR monitoring
+- `/loop 10m check if the staging environment is healthy` — Staging health
+
+## Planning & Todos
+
+- `/loop 1h /merlin:check-todos and summarize what's pending` — Todo awareness
+- `/loop 24h /merlin:standup and create a brief daily summary` — Daily digest
+
+## Usage
+
+Just copy any recipe above and paste it into Claude Code. Customize the interval and prompt as needed.
+
+```
+/loop 5m /merlin:progress
+```
+
+Native `/loop` features:
+- Supports natural language intervals (e.g., "every 5 minutes", "5m", "2h")
+- Default interval: 10 minutes
+- Auto-expires after 3 days
+- Session-scoped (lives in your active session)
+- Can run any slash command or natural language prompt
+
+## Tips
+
+- Combine with `/merlin:progress` for a live project dashboard
+- Use shorter intervals (2-5m) during active deploys, longer (1h+) for background monitoring
+- Chain recipes: let one loop inform what the next one checks
+</reference>

package/files/hooks/agent-sync.sh

@@ -1,6 +1,9 @@
 #!/usr/bin/env bash
 # Merlin Hook: Agent Sync (SessionStart, background)
 # Checks installed agents freshness and updates from cloud. Max once/hour.
+#
+# ASYNC: This hook should be registered as async (non-blocking)
+# Claude Code supports async hooks — register this one as background
 set -euo pipefail
 trap 'echo "{}"; exit 0' ERR
 

package/files/hooks/check-file-size.sh

@@ -4,9 +4,21 @@
 # Checks if the modified file exceeds the 400-line convention.
 # Exits with code 2 to inject feedback when file is too large.
 #
+# Agent-type awareness: docs-keeper and merlin-verifier agents are exempt
+# from the 400-line limit (they work with doc/verification files).
+#
 set -euo pipefail
 trap 'echo "{}"; exit 0' ERR
 
+# Check agent type — skip enforcement for non-implementation agents
+AGENT_TYPE="${CLAUDE_AGENT_TYPE:-${CLAUDE_CODE_AGENT_TYPE:-main}}"
+case "$AGENT_TYPE" in
+  docs-keeper|merlin-verifier)
+    echo '{}'
+    exit 0
+    ;;
+esac
+
 # Read tool input from stdin (Claude Code pipes JSON)
 input=""
 if [ ! -t 0 ]; then

package/files/hooks/config-change.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+#
+# Merlin Hook: ConfigChange
+# Purpose: Validate Merlin MCP key still works after config change.
+# Also logs config changes to Sights for enterprise audit trail.
+#
+# Always exits 0 — never blocks Claude Code.
+#
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source shared libs if available
+[ -f "${HOOK_DIR}/lib/analytics.sh" ] && . "${HOOK_DIR}/lib/analytics.sh"
+
+MERLIN_API_KEY="${MERLIN_API_KEY:-}"
+AGENT_ID="${CLAUDE_AGENT_ID:-unknown}"
+AGENT_TYPE="${CLAUDE_AGENT_TYPE:-main}"
+
+# Log config change event if analytics available
+if declare -f log_event >/dev/null 2>&1; then
+  log_event "config_change" "$(printf '{"agent_id":"%s","agent_type":"%s","has_key":"%s"}' "$AGENT_ID" "$AGENT_TYPE" "$([ -n "$MERLIN_API_KEY" ] && echo true || echo false)")"
+fi
+
+if [ -z "$MERLIN_API_KEY" ]; then
+  echo "Merlin: No API key configured after config change" >&2
+  echo '{}'
+  exit 0
+fi
+
+# Quick validation — check key format (valid prefixes: mrln_ or ccw_)
+case "$MERLIN_API_KEY" in
+  mrln_*|ccw_*)
+    # Valid prefix — no-op
+    ;;
+  *)
+    echo "Merlin: API key has unexpected format after config change" >&2
+    ;;
+esac
+
+echo '{}'
+exit 0

package/files/hooks/instructions-loaded.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+#
+# Merlin Hook: InstructionsLoaded
+# Purpose: Pre-warm Merlin Sights connection when CLAUDE.md loads.
+# Fires BEFORE session-start, giving us a head start on context loading.
+#
+# Always exits 0 — never blocks Claude Code startup.
+#
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source shared libs if available
+# shellcheck source=lib/analytics.sh
+[ -f "${HOOK_DIR}/lib/analytics.sh" ] && . "${HOOK_DIR}/lib/analytics.sh"
+# shellcheck source=lib/sights-check.sh
+[ -f "${HOOK_DIR}/lib/sights-check.sh" ] && . "${HOOK_DIR}/lib/sights-check.sh"
+
+# Log agent context if available
+AGENT_ID="${CLAUDE_AGENT_ID:-unknown}"
+AGENT_TYPE="${CLAUDE_AGENT_TYPE:-main}"
+
+# Log the instructions-loaded event if analytics is available
+if declare -f log_event >/dev/null 2>&1; then
+  log_event "instructions_loaded" "$(printf '{"agent_id":"%s","agent_type":"%s","cwd":"%s"}' "$AGENT_ID" "$AGENT_TYPE" "${PWD:-}")"
+fi
+
+# Signal that Merlin instructions were loaded
+# The MCP server will handle actual Sights connection
+echo "Merlin instructions loaded — Sights pre-warming (agent: ${AGENT_TYPE})" >&2
+
+echo '{}'
+exit 0

package/files/hooks/session-start.sh

@@ -1,9 +1,10 @@
 #!/usr/bin/env bash
 #
 # Merlin Hook: SessionStart (consolidated)
-# Does three things in a single hook (avoids 3x "success" messages):
+# Does four things in a single hook (avoids multiple "success" messages):
 #   1. Analytics: initialize session, log start event
 #   2. Agent sync: refresh agent files from cloud (background, max once/hour)
+#   2.5. Auto-update: check npm for new Merlin version (background, max once/24h)
 #   3. Context injection: output additionalContext for the session
 #
 # Always exits 0 — never blocks Claude Code startup.
@@ -75,9 +76,13 @@ _merlin_cleanup_stale &
 # shellcheck source=lib/sights-check.sh
 . "${HOOKS_DIR}/lib/sights-check.sh"
 
+# Log agent context if available
+AGENT_ID="${CLAUDE_AGENT_ID:-unknown}"
+AGENT_TYPE="${CLAUDE_AGENT_TYPE:-main}"
+
 ensure_session_file
 cwd="${PWD:-$(pwd)}"
-log_event "session_start" "$(printf '{"cwd":"%s"}' "$cwd")"
+log_event "session_start" "$(printf '{"cwd":"%s","agent_id":"%s","agent_type":"%s"}' "$cwd" "$AGENT_ID" "$AGENT_TYPE")"
 
 # Warm up Sights context in background
 if command -v merlin >/dev/null 2>&1; then
@@ -126,6 +131,51 @@ _merlin_sync_agents() {
 }
 _merlin_sync_agents &
 
+# ── 2.5. Auto-update check (background, max once/24h) ─────────
+# Proactively upgrades Merlin when a new version is published.
+# Runs silently in background — never blocks session startup.
+_merlin_auto_update() {
+  local merlin_dir="${HOME}/.claude/merlin"
+  local last_check="${merlin_dir}/.last-update-check"
+  local version_file="${merlin_dir}/VERSION"
+  local check_interval=86400  # 24 hours
+
+  [ -d "${merlin_dir}" ] || return 0
+
+  # Skip if checked within the last 24 hours
+  if [ -f "${last_check}" ]; then
+    local last
+    last=$(cat "${last_check}" 2>/dev/null || echo "0")
+    [ $(($(date +%s) - last)) -lt ${check_interval} ] && return 0
+  fi
+
+  # Record check time immediately (prevents parallel checks)
+  date +%s > "${last_check}"
+
+  # Read installed version
+  local installed="0.0.0"
+  [ -f "${version_file}" ] && installed=$(cat "${version_file}" 2>/dev/null || echo "0.0.0")
+
+  # Determine channel from version string
+  local channel="latest"
+  echo "${installed}" | grep -q "beta" && channel="beta"
+
+  # Check npm for latest version (5s timeout)
+  local available
+  available=$(npm view "create-merlin-brain@${channel}" version 2>/dev/null) || return 0
+  [ -z "${available}" ] && return 0
+
+  # Compare versions (simple: if they differ and available is newer)
+  [ "${installed}" = "${available}" ] && return 0
+
+  # Version differs — run the upgrade
+  echo "merlin: updating ${installed} → ${available} ..." >&2
+  if npx "create-merlin-brain@${channel}" --yes 2>/dev/null; then
+    echo "merlin: updated to v${available}. Restart Claude Code for full effect." >&2
+  fi
+}
+_merlin_auto_update &
+
 # ── 3. Context injection (the only stdout output) ──────────────
 # Output additionalContext JSON for Claude to see at session start.
 # Full boot instructions are in CLAUDE.md — this is a lightweight nudge.

package/files/hooks/worktree-create.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+#
+# Merlin Hook: WorktreeCreate
+# Purpose: Propagate .merlin/ config into git worktrees so sub-agents
+# spawned in worktrees have Sights access.
+#
+# Always exits 0 — never blocks Claude Code.
+#
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source shared libs if available
+[ -f "${HOOK_DIR}/lib/analytics.sh" ] && . "${HOOK_DIR}/lib/analytics.sh"
+
+WORKTREE_PATH="${CLAUDE_WORKTREE_PATH:-}"
+AGENT_ID="${CLAUDE_AGENT_ID:-unknown}"
+AGENT_TYPE="${CLAUDE_AGENT_TYPE:-main}"
+
+if [ -z "$WORKTREE_PATH" ]; then
+  echo '{}'
+  exit 0
+fi
+
+# Copy Merlin config to worktree
+if [ -d ".merlin" ]; then
+  cp -r .merlin "$WORKTREE_PATH/.merlin" 2>/dev/null || true
+fi
+
+# Copy project CLAUDE.md to worktree if not already present
+if [ -f "CLAUDE.md" ] && [ ! -f "$WORKTREE_PATH/CLAUDE.md" ]; then
+  cp CLAUDE.md "$WORKTREE_PATH/CLAUDE.md" 2>/dev/null || true
+fi
+
+# Log event if analytics available
+if declare -f log_event >/dev/null 2>&1; then
+  log_event "worktree_create" "$(printf '{"path":"%s","agent_id":"%s","agent_type":"%s"}' "$WORKTREE_PATH" "$AGENT_ID" "$AGENT_TYPE")"
+fi
+
+echo "Merlin: propagated config to worktree ${WORKTREE_PATH} (agent: ${AGENT_TYPE})" >&2
+
+echo '{}'
+exit 0

package/files/hooks/worktree-remove.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+#
+# Merlin Hook: WorktreeRemove
+# Purpose: Cleanup Merlin state from removed worktrees.
+#
+# Always exits 0 — never blocks Claude Code.
+#
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source shared libs if available
+[ -f "${HOOK_DIR}/lib/analytics.sh" ] && . "${HOOK_DIR}/lib/analytics.sh"
+
+WORKTREE_PATH="${CLAUDE_WORKTREE_PATH:-}"
+AGENT_ID="${CLAUDE_AGENT_ID:-unknown}"
+AGENT_TYPE="${CLAUDE_AGENT_TYPE:-main}"
+
+if [ -z "$WORKTREE_PATH" ]; then
+  echo '{}'
+  exit 0
+fi
+
+# Remove Merlin artifacts from worktree (if still present)
+rm -rf "$WORKTREE_PATH/.merlin" 2>/dev/null || true
+
+# Log event if analytics available
+if declare -f log_event >/dev/null 2>&1; then
+  log_event "worktree_remove" "$(printf '{"path":"%s","agent_id":"%s","agent_type":"%s"}' "$WORKTREE_PATH" "$AGENT_ID" "$AGENT_TYPE")"
+fi
+
+echo "Merlin: cleaned up worktree ${WORKTREE_PATH} (agent: ${AGENT_TYPE})" >&2
+
+echo '{}'
+exit 0

package/files/loop/lib/agents.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 Loop - Agent Profiles & Routing
 # Task → Agent mapping based on keywords

package/files/loop/lib/blend-handoff.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.
 #
 # ╔═══════════════════════════════════════════════════════════════════════════╗
 # ║  BLEND ENGINE — Stage 3: Structured Handoffs                              ║

package/files/loop/lib/blend-learn.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.
 #
 # ╔═══════════════════════════════════════════════════════════════════════════╗
 # ║  BLEND ENGINE — Stage 4: Blend Learning                                  ║

package/files/loop/lib/blend-parallel.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.
 #
 # ╔═══════════════════════════════════════════════════════════════════════════╗
 # ║  BLEND ENGINE — Stage 2: Parallel Agent Execution                         ║

package/files/loop/lib/blend-verify.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.
 #
 # ╔═══════════════════════════════════════════════════════════════════════════╗
 # ║  BLEND ENGINE — Stage 1: True Independent Verification                   ║

package/files/loop/lib/blend.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 BLEND ENGINE - Dynamic Agent Fusion                               ║

package/files/loop/lib/boot.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 Loop - Boot Sequence
 # The 5-phase Merlin Pro boot sequence that runs before every task

package/files/loop/lib/context.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 Loop - Smart Context Management
 # Intelligent context loading and memory retrieval

package/files/loop/lib/discuss.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 Loop - Discussion Mode
 # Spawns a fresh Claude session for conversation without losing loop state

package/files/loop/lib/modes.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 Loop - Mode Management
 # Handles automated, interactive, and hybrid loop modes

package/files/loop/lib/progress.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 Loop - Progress Tracking
 # Visual progress, time estimates, and reporting

package/files/loop/lib/safety.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 Loop - Safety Controls
 # Rate limiting, circuit breakers, and budget management

package/files/loop/lib/session-end.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 Loop - Session End Protocol
 # Enforces commit + sync + checkpoint at every task end

package/files/loop/lib/sights.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 Loop - Sights Integration
 # Fetches recent changes, trajectory, and records commits

package/files/loop/lib/state.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 Loop - State Management
 # Local state + cloud sync to merlin.build

package/files/loop/lib/teams.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 Loop - Agent Teams Integration
 # Enables parallel specialist execution using Claude Code Agent Teams.

package/files/loop/lib/timeout.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 Loop - Timeout Handling
 # Provides timeout with countdown for pause points, enabling AFK operation

package/files/loop/lib/tui.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 Loop - Interactive TUI
 # Beautiful terminal interface for pause/continue control

package/files/loop/lib/workflow-gen.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 WORKFLOW ENGINE — Dynamic Workflow Generation                    ║

package/files/loop/lib/workflow-run.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 WORKFLOW ENGINE — Run, Resume, Status, CLI                       ║

package/files/loop/lib/workflow.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 WORKFLOW ENGINE - Core Engine                                    ║

package/files/loop/merlin-loop.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 LOOP - Autonomous AI Development Orchestrator                     ║

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.2",
+  "version": "3.10.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()`