@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/general/guardrails/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: guardrails
+description: Three-point agent guardrails for pre, mid, and post execution validation
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate:
+    [guardrail, safety-check, pre-check, post-check, validation-boundary]
+---
+
+# 3-Point Guardrails
+
+Three-checkpoint validation system ensuring agents operate within bounds and produce quality outputs. Inspired by Agno's guardrail pattern.
+
+## The 3 Checkpoints
+
+### Pre-Execution (preCheck)
+
+Validates before dispatch:
+
+- Agent exists in the 15-agent roster
+- Task has required fields (id, description)
+- Referenced file paths exist on disk
+- Agent has appropriate tools for the task type
+
+**Outcome:** PASS (dispatch proceeds) or BLOCK (dispatch prevented)
+
+### Mid-Execution (midCheck)
+
+Monitors during dispatch:
+
+- Elapsed time vs timeout (warns at 90%, aborts at 100%)
+- Output size within limits (500KB default)
+- Error pattern detection (FATAL ERROR, stack overflow, OOM, SIGKILL)
+
+**Outcome:** CONTINUE / WARN / ABORT recommendation
+
+### Post-Execution (postCheck)
+
+Verifies after completion:
+
+- Agent returned success status
+- Output is non-empty and substantive
+- Modified files match expected task files
+- No secrets/credentials leaked in output
+
+**Outcome:** PASS with quality score (0-5) or FAIL with issues
+
+## Security Scanning
+
+Post-check scans output for:
+
+- API keys and secrets in `key=value` patterns
+- Cloud provider credentials (AWS, Azure, GCP)
+- Private key blocks (RSA, EC)
+
+Any secret detection is a CRITICAL severity issue.
+
+## Command Safety Analysis
+
+Before executing any bash command, classify it using this 3-tier system.
+Apply to the **entire pipeline** — if any command in a chain is DANGEROUS,
+the whole pipeline is DANGEROUS.
+
+### SAFE — Auto-approve, log only
+
+Read-only operations with no side effects:
+
+```
+ls, cat, head, tail, grep, find, locate, which, type
+echo, printf, pwd, whoami, id, env, printenv
+git status, git log, git diff, git show, git branch, git remote
+git stash list, git tag --list
+node --version, npm --version, python --version
+npm list, pip list, cargo tree
+curl -X GET (read-only, no auth headers with secrets)
+```
+
+### CAUTION — Notify user, interruptible (5 min timeout)
+
+Write operations or network calls that modify state:
+
+```
+git checkout, git switch, git merge, git rebase
+git stash, git stash pop
+npm install, pip install, cargo add, go get
+mkdir, touch, cp, mv (within project)
+curl -X POST/PUT/PATCH/DELETE
+ssh (connections to external hosts)
+docker build, docker pull
+File writes (any > redirect or Write tool)
+```
+
+### DANGEROUS — Block + require explicit human approval
+
+Destructive, irreversible, or high-blast-radius operations:
+
+```
+rm -rf, del /f /s, rmdir /s
+git push --force, git push -f
+git reset --hard, git clean -f, git checkout -- .
+DROP TABLE, DELETE FROM (without WHERE), TRUNCATE
+kill -9, killall, pkill
+chmod 777, chown -R
+curl [url] | bash, curl [url] | sh     ← pipe-to-shell pattern
+wget [url] | bash
+sudo [any command]
+> /dev/sda, dd if=... (disk operations)
+Any command containing $USER_INPUT without sanitization
+```
+
+### Pipeline & Redirection Rules
+
+| Pattern                       | Escalation              |
+| ----------------------------- | ----------------------- |
+| `safe_cmd \| dangerous_cmd`   | Escalates to DANGEROUS  |
+| `cmd > file` or `cmd >> file` | Escalates to CAUTION    |
+| `cmd > /dev/null`             | Stays at SAFE (discard) |
+| `dangerous_cmd \|\| fallback` | Stays DANGEROUS         |
+| `safe_cmd && safe_cmd`        | Stays SAFE              |
+
+### When a DANGEROUS command is needed
+
+1. Show the command to the user explicitly
+2. Explain what it does and why it's needed
+3. Offer a safer alternative if one exists
+4. Wait for explicit approval: "yes, run it" / "confirmed" / "go ahead"
+5. Never infer approval from context or previous approvals
+
+## Integration
+
+GuardrailEngine integrates with:
+
+- **GateEvaluator** via `guardrails_passed` check type
+- **SubagentDispatcher** for pre/post dispatch validation
+- **ParallelMonitor** for mid-execution stall detection
+- **Approval System** — CAUTION maps to MEDIUM stake, DANGEROUS maps to HIGH stake
+
+## Configuration
+
+- `maxOutputSize`: Maximum output bytes (default 500KB)
+- `defaultTimeout`: Default per-agent timeout (default 5 min)
+- All thresholds configurable via constructor config

package/.merlin-core/skills/general/image-gen/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: image-gen
+description: AI image generation for hero images, banners, icons, and illustrations. Requires image generation MCP server.
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate:
+    [generate-image, hero-image, ai-image, visual-asset, illustration]
+  tool_reminders:
+    [
+      Image generation requires MEDIUM approval — confirm with user before generating,
+      Always include alt text for accessibility when placing generated images,
+    ]
+---
+
+## Image Generation Protocol
+
+### 1. Prompt Engineering
+
+Before generating, create a detailed prompt:
+
+- **Subject**: What is the image of?
+- **Style**: Photorealistic, illustration, flat design, 3D render, etc.
+- **Mood**: Professional, playful, dramatic, minimal, etc.
+- **Colors**: Match the project's design system palette
+- **Dimensions**: Specify aspect ratio (16:9 for hero, 1:1 for icons, etc.)
+
+### 2. Approval
+
+- Image generation requires **MEDIUM** approval
+- Always describe the intended image to the user before generating
+- Respect the Design System skill if active (match palette and style)
+
+### 3. Accessibility
+
+Every generated image MUST include:
+
+- `alt` text describing the image content
+- Appropriate `role` attributes if decorative
+- Sufficient contrast if text overlays are planned
+
+### 4. Graceful Degradation
+
+If image generation MCP is not available:
+
+- Suggest stock photo sources (Unsplash, Pexels)
+- Provide SVG/CSS alternatives for icons and simple graphics
+- Describe the desired image for manual creation

package/.merlin-core/skills/general/learning-capture/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: learning-capture
+description: Recognizes learning-worthy moments during agent work and guides structured knowledge capture with rich metadata for cross-agent retrieval.
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate: [capture-learning, gotcha, pitfall, TIL, heads-up]
+---
+
+# Learning Capture — Domain Knowledge Preservation
+
+Agents constantly discover domain-specific knowledge while working — API quirks,
+system constraints, useful patterns, team conventions. This skill helps agents
+recognize these moments and capture them as structured learnings with the right
+metadata so other agents working in the same area can benefit.
+
+## When to Capture
+
+Trigger learning capture at these moments:
+
+1. **Unexpected behavior** — "This API returns 404 for empty arrays, not 200 with []"
+2. **Hard-won discovery** — Took significant debugging to figure out
+3. **Pattern recognition** — "Every service in this project uses the same retry pattern"
+4. **Convention identification** — "The team always uses kebab-case for API routes"
+5. **Constraint discovery** — "The DB connection pool maxes at 10 concurrent connections"
+6. **Workaround application** — "The connection pool must be capped at 10 or the DB rejects new clients under load"
+7. **User explicit request** — User says "save this", "remember this", "capture this learning"
+
+## When NOT to Capture
+
+- **Session state** — Use handoff instead (what's in progress, what's next)
+- **Action items** — Use reminder instead (things that need to happen)
+- **Goals** — Use objective instead (multi-session targets)
+- **Major decisions** — Use decision (ADR) instead (formal with alternatives/rationale)
+- **Deep analysis** — Use research instead (exploratory, multi-page)
+- **Obvious/generic knowledge** — Don't capture "JavaScript uses semicolons"
+
+## The Capture Protocol
+
+### Step 1: Recognize the Moment
+
+Ask yourself: "Would another agent working in this area benefit from knowing this?"
+
+If yes, and it's a **specific, actionable fact** (not a vague observation), proceed.
+
+### Step 2: Distill the Insight
+
+Reduce to 1-3 sentences. The insight should be:
+
+- **Specific** — not "the API is tricky" but "the API returns paginated results with max 50 items, no header indicates total count"
+- **Actionable** — the reader knows what to do differently
+- **Scoped** — clear about when/where this applies
+
+### Step 3: Assign Metadata
+
+This is the critical step. Rich metadata enables area-of-action matching:
+
+**domain** (required) — What broad area does this fall under?
+
+- `database`, `auth`, `api`, `build`, `frontend`, `backend`, `deployment`,
+  `infra`, `testing`, `devops`, `electron`, `react`, `node`, or any
+  project-specific domain
+
+**category** (required) — What kind of knowledge is this?
+| Category | Use When |
+|----------|----------|
+| `gotcha` | Something that traps you, fails silently, or behaves unexpectedly |
+| `pattern` | A reusable approach that works well in this codebase |
+| `convention` | A team/project norm that should be followed consistently |
+| `constraint` | A hard limit, system boundary, or non-negotiable requirement |
+| `insight` | A deeper understanding of how/why something works the way it does |
+| `workaround` | A temporary fix or bypass — should include the ideal solution too |
+
+**tags** (important) — Granular keywords. Think: "what would an agent search for?"
+
+- Include technology names, API names, file names, error messages, concepts
+- The more specific the tags, the better the retrieval
+
+**applies_to** (important) — Specific files, directories, or modules
+
+- e.g., `[src/<module>/, src/shared/<file>.ts]`
+- These become keywords in the index, enabling path-based matching
+
+**confidence** — How sure are you?
+
+- `observed` — Seen once (default, honest starting point)
+- `verified` — Confirmed across multiple instances or sessions
+- `assumed` — Inferred but not directly tested (flag for verification)
+
+### Step 4: Save
+
+Invoke `/capture-learning` with the structured metadata, or write directly to
+`thoughts/shared/learnings/YYYY-MM-DD-{slug}.md`.
+
+## Confidence Upgrade Path
+
+Learnings start as `observed` and can be upgraded:
+
+```
+assumed → observed → verified
+   ↑                    ↓
+   └── contradicted ────┘ (supersedes old learning)
+```
+
+When you encounter a learning during work and confirm it's still accurate,
+update its confidence to `verified`. If you find it's wrong, create a new
+learning with `supersedes` pointing to the old one.
+
+## Contradiction Handling
+
+When creating a learning that contradicts an existing one:
+
+1. **Add `supersedes` to frontmatter** — Set `supersedes: "type:date:slug"` pointing to the old learning's citation ID (e.g., `supersedes: "learning:2026-02-10:db-pool-limit-workaround"`)
+2. **ThoughtsProvider auto-suppresses** — Superseded entries are automatically filtered out of memory hints, so agents only see the latest version
+3. **Don't delete old learnings** — They are historical records; the `supersedes` chain preserves the evolution of understanding
+4. **Update confidence** — New learnings that supersede old ones should start as `observed` (they still need independent verification)
+
+Example frontmatter with supersedes:
+
+```yaml
+---
+type: learning
+date: 2026-03-03
+domain: database
+category: gotcha
+confidence: observed
+supersedes: "learning:2026-02-10:db-pool-default"
+tags: [database, connection-pool, concurrency, timeout]
+applies_to: [src/<module>/]
+---
+```
+
+## Proactive Capture Protocol
+
+Agents SHOULD proactively capture learnings without waiting for explicit user requests. The GuardrailEngine post-check scans agent output for learning indicators.
+
+### Automatic Detection Signals
+
+The following patterns in agent output trigger a learning capture prompt:
+
+- **Error recovery** — Agent hit an error, diagnosed the root cause, and found a fix
+- **Unexpected behavior** — Something worked differently than expected (API quirk, config gotcha)
+- **Multi-step debugging** — Took 3+ attempts to resolve an issue
+- **Environment-specific** — Discovery tied to a specific OS, runtime, or version
+- **Workaround applied** — Agent used a non-obvious approach to bypass a limitation
+
+### Proactive Capture Flow
+
+1. Agent detects a learning-worthy moment during work
+2. Agent emits `[NOTIFY: Learning detected — {one-line summary}]`
+3. Agent continues with primary task (do NOT interrupt the workflow)
+4. At task completion, agent includes a `## Learnings` section in the result with structured captures
+5. GuardrailEngine post-check validates that detected learnings were captured
+
+### Rules
+
+- Proactive capture MUST NOT interrupt the primary task flow
+- Learnings are appended to the result, not emitted mid-task
+- If >3 learnings are detected in a single task, capture the top 3 by impact
+- Each proactive learning follows the same metadata protocol (domain, category, tags, applies_to)
+
+## Integration Points
+
+- `/capture-learning` — Structured capture command
+- `/recall-learnings` — Explicit retrieval with filters
+- ThoughtsProvider — Automatic surfacing via Alkimia memory (keyword + domain + type affinity scoring) with citation IDs and contradiction detection
+- `/handoff` — Reference key learnings discovered during session
+- `/research` — Learnings often emerge during research — capture them
+- GuardrailEngine — Post-check scans for uncaptured learning signals
+
+## Examples of Good Learnings
+
+**Gotcha:**
+
+> "This payments API returns HTTP 200 with an empty body when a charge is still pending,
+> not 202. Callers MUST inspect the `status` field, not rely on the HTTP code."
+
+**Pattern:**
+
+> "All event channels in this project follow the namespace:action pattern (e.g., orders:created,
+> payments:settled). New channels must follow this convention for consistency."
+
+**Constraint:**
+
+> "The native image-processing module must be externalized in the bundler config — bundling it
+> causes runtime errors. The same applies to any other module with prebuilt binaries."
+
+**Workaround:**
+
+> "The CI runner sets a build-tool env var that breaks the local toolchain's API access.
+> Must unset this env var when spawning the toolchain from the CI shell."