@caoscompanybr/merlin 3.5.0

package/.merlin-core/schemas/skill-schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "skill-schema.json",
+  "title": "Merlin Skill Definition Schema (v3 — Agent Skills Standard)",
+  "description": "Validates SKILL.md frontmatter. V3 moves auto_activate, tool_reminders, file_triggers into metadata block for Agent Skills Standard compliance. Parser reads both top-level (legacy) and metadata.* (v3).",
+  "type": "object",
+  "required": ["frontmatter"],
+  "properties": {
+    "frontmatter": {
+      "type": "object",
+      "required": ["name", "description"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+          "maxLength": 64,
+          "description": "Skill identifier. Lowercase, hyphens only, max 64 chars. Must match parent directory name."
+        },
+        "description": {
+          "type": "string",
+          "minLength": 10,
+          "maxLength": 1024,
+          "description": "What the skill does and when to use it. Be specific."
+        },
+        "license": {
+          "type": "string",
+          "description": "License name (e.g., Apache-2.0, MIT)"
+        },
+        "compatibility": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "Environment requirements (e.g., claude-code)"
+        },
+        "metadata": {
+          "type": "object",
+          "description": "Arbitrary key-value map. V3 canonical location for Merlin-specific fields.",
+          "properties": {
+            "author": { "type": "string" },
+            "version": { "type": "string" },
+            "auto_activate": {
+              "type": "array",
+              "items": { "type": "string" },
+              "maxItems": 6,
+              "description": "Keywords that trigger skill auto-activation. Max 6 per policy."
+            },
+            "tool_reminders": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Safety/procedural reminders shown when skill is active."
+            },
+            "file_triggers": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "File glob patterns that trigger activation (e.g., *.ts, *.tsx)."
+            },
+            "allowed_tools": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Tools pre-approved when skill is active."
+            },
+            "imported": {
+              "type": "string",
+              "enum": ["true", "false"],
+              "description": "Set by skill-importer when importing external skills."
+            },
+            "imported-at": {
+              "type": "string",
+              "description": "ISO timestamp of import."
+            }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/.merlin-core/schemas/workflow-schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "workflow-schema.json",
+  "title": "Merlin Workflow Schema",
+  "description": "Validates workflow YAML files in .merlin-core/development/workflows/",
+  "type": "object",
+  "required": ["workflow"],
+  "properties": {
+    "workflow": {
+      "type": "object",
+      "required": ["id", "name", "phases"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+        "name": { "type": "string" },
+        "version": { "type": "string" },
+        "description": { "type": "string" },
+        "phases": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "name"],
+            "properties": {
+              "id": { "type": "string" },
+              "name": { "type": "string" },
+              "description": { "type": "string" },
+              "agents": { "type": ["object", "array"] },
+              "commands": { "type": "array", "items": { "type": "string" } },
+              "output": { "type": "object" },
+              "success_criteria": { "type": "object" }
+            }
+          },
+          "minItems": 1
+        },
+        "transitions": { "type": "object" }
+      }
+    }
+  }
+}

package/.merlin-core/skills/README.md

@@ -0,0 +1,16 @@
+# Skills System
+
+The skills module implements a composable skills system for Merlin's extensible capabilities. Built-in skills are provided in the general/ directory, while the domain/ directory allows users to define and extend domain-specific skills for their particular workflows and requirements.
+
+## Contents
+
+- **general/** - Built-in skills: file operations, git, testing, deployment, analysis
+- **domain/** - User-extensible domain-specific skills for custom workflows
+- **skill-registry.json** - Centralized skill discovery and metadata
+- **skill-loader.js** - Dynamic skill loading and initialization
+
+## Related
+
+- [Commands](../commands/README.md)
+- [Development](../development/README.md)
+- [Schemas](../schemas/README.md)

package/.merlin-core/skills/domain/azure-cloud/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: azure-cloud
+description: Comprehensive Azure cloud platform skill — deployment pipelines (azd, Bicep, Terraform), Key Vault encryption, Entra ID/SSO, RBAC least-privilege, compliance audits, diagnostics, storage, cost optimization, observability, and resource management. Activates when working on any Azure-integrated project. Based on Microsoft's official github-copilot-for-azure skills (v1.0.x, MIT license).
+license: MIT
+metadata:
+  author: Microsoft (adapted for Merlin by merlin-framework)
+  version: "1.0.0"
+  source: "github.com/microsoft/github-copilot-for-azure"
+  auto_activate: [azure, key-vault, entra-id, azd-deploy, bicep-template, azure-monitoring]
+  file_triggers: [azure.yaml, *.bicep, **/.azure/**, **/infra/**/*.bicep, **/infra/**/*.tf, azure-pipelines.yml]
+  tool_reminders: [Azure deployments (azd up, azd deploy, terraform apply) are HIGH-stake actions — require explicit human approval, NEVER change .azure/plan.md status to Validated yourself — only azure-validate can set this, Always use managed identity over connection strings for Azure service authentication, Key Vault operations that create/modify keys are HIGH-stake — confirm with user first, Before any deployment, verify azure-prepare → azure-validate → azure-deploy pipeline order]
+references:
+  - github.com/microsoft/github-copilot-for-azure
+  - learn.microsoft.com/en-us/azure
+  - learn.microsoft.com/en-us/cli/azure
+---
+
+## Azure Cloud — Domain Skill
+
+Expert knowledge for Azure cloud infrastructure, deployment, security, and operations. Curated from Microsoft's official 22-skill Azure collection, filtered to what's production-relevant.
+
+### When This Activates
+
+This skill activates when working on Azure-integrated projects. Current ecosystem:
+
+- **An example SaaS project** — Azure Key Vault (client data encryption), Entra ID (SSO), Docker on VPS
+- **Any future Azure project** — Bicep/Terraform infrastructure, managed identity, RBAC
+
+### Architecture Context
+
+```
+Merlin Core (this skill = KNOWLEDGE)
+    ↓ teaches agents Azure best practices
+Project repos (RUNTIME)
+    ├── .azure/plan.md         (deployment plan)
+    ├── infra/*.bicep           (infrastructure as code)
+    ├── azure.yaml              (azd configuration)
+    └── src/services/azure-*    (SDK integrations)
+```
+
+### Deployment Pipeline (Mandatory Order)
+
+```
+azure-prepare  →  azure-validate  →  azure-deploy
+   (plan)            (check)           (execute)
+```
+
+**NEVER skip steps.** The `azure-deploy` reference will reject execution without a validated plan.
+
+---
+
+## Installed Skills (13) — Reference Files
+
+### Tier 1: Core Deployment Pipeline
+
+| Skill              | Reference                                                    | Purpose                                                                                              |
+| ------------------ | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
+| **azure-prepare**  | [references/azure-prepare.md](references/azure-prepare.md)   | Create infrastructure (Bicep/Terraform), azure.yaml, Dockerfiles. Use for new apps or modernization. |
+| **azure-validate** | [references/azure-validate.md](references/azure-validate.md) | Pre-deployment validation — config, infrastructure, permissions, prerequisites.                      |
+| **azure-deploy**   | [references/azure-deploy.md](references/azure-deploy.md)     | Execute `azd up`, `azd deploy`, `terraform apply`. Requires validated plan.                          |
+
+### Tier 2: Security & Identity
+
+| Skill                      | Reference                                                                    | Purpose                                                                               |
+| -------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| **azure-rbac**             | [references/azure-rbac.md](references/azure-rbac.md)                         | Find least-privilege roles, generate CLI/Bicep for role assignments.                  |
+| **azure-compliance**       | [references/azure-compliance.md](references/azure-compliance.md)             | Security auditing, Key Vault expiration monitoring, best practices assessment (azqr). |
+| **entra-app-registration** | [references/entra-app-registration.md](references/entra-app-registration.md) | Microsoft Entra ID (Azure AD) app registration, OAuth 2.0, MSAL integration.          |
+
+### Tier 3: Operations & Observability
+
+| Skill                           | Reference                                                                              | Purpose                                                                 |
+| ------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| **azure-diagnostics**           | [references/azure-diagnostics.md](references/azure-diagnostics.md)                     | Debug Container Apps, Function Apps — log analysis, KQL, health checks. |
+| **appinsights-instrumentation** | [references/appinsights-instrumentation.md](references/appinsights-instrumentation.md) | Application Insights telemetry — SDK setup for Node.js, Python, .NET.   |
+| **azure-storage**               | [references/azure-storage.md](references/azure-storage.md)                             | Blob, File Shares, Queue, Table, Data Lake — access tiers, lifecycle.   |
+
+### Tier 4: Resource Management & Cost
+
+| Skill                         | Reference                                                                          | Purpose                                                                             |
+| ----------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| **azure-cost-optimization**   | [references/azure-cost-optimization.md](references/azure-cost-optimization.md)     | Find orphaned resources, rightsize VMs, analyze spending, generate savings reports. |
+| **azure-resource-lookup**     | [references/azure-resource-lookup.md](references/azure-resource-lookup.md)         | List, find, inventory resources across subscriptions via Resource Graph.            |
+| **azure-resource-visualizer** | [references/azure-resource-visualizer.md](references/azure-resource-visualizer.md) | Generate Mermaid architecture diagrams from live Azure resource groups.             |
+| **azure-quotas**              | [references/azure-quotas.md](references/azure-quotas.md)                           | Check service limits, current usage, request quota increases, capacity planning.    |
+
+---
+
+## Not Installed (9) — When to Add
+
+These skills are available at `github.com/microsoft/github-copilot-for-azure` but not installed because they don't match current production needs. Install them when the use case arises:
+
+| Skill                        | Install When                                                 | Description                                                                      |
+| ---------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------- |
+| **azure-ai**                 | Using Azure AI Search, Speech, OpenAI, Document Intelligence | SDK guides for search, vector/hybrid search, speech-to-text, OCR                 |
+| **azure-aigateway**          | Setting up API Management as AI Gateway                      | APIM policies for semantic caching, token limits, content safety, load balancing |
+| **azure-messaging**          | Using Event Hubs or Service Bus                              | SDK troubleshooting for AMQP, event processing, dead letter queues               |
+| **azure-kusto**              | Using Azure Data Explorer (ADX)                              | KQL queries for log analytics, telemetry, time series, anomaly detection         |
+| **azure-compute**            | Provisioning Azure VMs or VMSS                               | VM size recommendations, pricing API, autoscaling, GPU selection                 |
+| **azure-cloud-migrate**      | Migrating from AWS/GCP to Azure                              | Assessment reports, code conversion (Lambda→Functions, S3→Blob, etc.)            |
+| **azure-hosted-copilot-sdk** | Building GitHub Copilot SDK apps                             | Scaffold, deploy, and configure Copilot-powered applications on Azure            |
+| **azure-upgrade**            | Upgrading Azure service tiers                                | Assess and automate upgrades between plans/SKUs (e.g., Consumption→Flex)         |
+| **microsoft-foundry**        | Using Microsoft Foundry for AI agents                        | Deploy, evaluate, and manage Foundry agents — Docker build, ACR push, batch eval |
+
+### How to Install Additional Skills
+
+1. Fetch the SKILL.md from GitHub: `plugin/skills/{name}/SKILL.md`
+2. Strip YAML frontmatter, save to `references/{name}.md`
+3. Also fetch any `references/` subdirectory files the skill uses
+4. Add entry to the table above → move from "Not Installed" to the appropriate tier
+5. Run keyword collision test: `node --test .merlin-core/core/orchestration/skill-dispatcher.test.js`
+
+---
+
+## Production Context: Example Project
+
+### Current Azure Integration
+
+| Service          | Status                     | Implementation                                                |
+| ---------------- | -------------------------- | ------------------------------------------------------------- |
+| **Key Vault**    | Code ready, deploy pending | `src/services/keyvault.service.ts` — AES-256 DEK management   |
+| **Entra ID**     | Partially configured       | Firebase Microsoft auth provider enabled                      |
+| **Graph Client** | Installed, not active      | `@microsoft/microsoft-graph-client` in functions/package.json |
+
+### Key Vault Architecture
+
+```
+Client Browser
+    ↓ getEncryptionKey({scope: "client:abc123"})
+Cloud Function (Firebase)
+    ↓ Azure credentials
+Azure Key Vault
+    ↓ DEK (Data Encryption Key)
+Cloud Function
+    ↓ raw key
+Client Browser
+    ↓ Web Crypto API (AES-256)
+Firestore (encrypted data only)
+```
+
+**Packages:**
+
+```json
+"@azure/identity": "^4.13.0"
+"@azure/keyvault-keys": "^4.10.0"
+"@microsoft/microsoft-graph-client": "^3.0.7"
+```
+
+### Deployment Targets
+
+| Component       | Where              | How                                             |
+| --------------- | ------------------ | ----------------------------------------------- |
+| Frontend        | Firebase Hosting   | `firebase deploy --only hosting`                |
+| Cloud Functions | Firebase Functions | `firebase deploy --only functions`              |
+| Agent Backend   | VPS (<vps-ip>)     | Docker Swarm + Traefik → <agent-backend-domain> |
+| PostgreSQL      | VPS (internal)     | Docker container, pgvector, internal port       |
+
+### Pending Azure Work
+
+1. **Deploy Key Vault functions** — `getEncryptionKey`, `unwrapEncryptionKey` (blocked by Firebase quota)
+2. **Complete Entra ID SSO** — Full Azure AD configuration, not just Firebase provider
+3. **Security audit** — Migrate any inline secrets to Key Vault
+4. **Graph API activation** — SharePoint/OneDrive integration for client documents
+
+---
+
+## Azure SDK Quick Reference
+
+### Authentication (Always use managed identity when possible)
+
+```typescript
+// DefaultAzureCredential — tries managed identity first, falls back to CLI
+import { DefaultAzureCredential } from "@azure/identity";
+const credential = new DefaultAzureCredential();
+```
+
+```python
+# Python equivalent
+from azure.identity import DefaultAzureCredential
+credential = DefaultAzureCredential()
+```
+
+### Key Vault Keys
+
+```typescript
+import { KeyClient } from "@azure/keyvault-keys";
+const client = new KeyClient("https://vault-name.vault.azure.net", credential);
+const key = await client.getKey("key-name");
+```
+
+### MCP Tools Available
+
+When Azure MCP is configured:
+
+| Tool                              | Purpose                              |
+| --------------------------------- | ------------------------------------ |
+| `mcp_azure_mcp_subscription_list` | List available subscriptions         |
+| `mcp_azure_mcp_group_list`        | List resource groups                 |
+| `mcp_azure_mcp_azd`               | Execute Azure Developer CLI commands |
+
+---
+
+## Critical Rules
+
+1. **Deployment pipeline is sequential** — prepare → validate → deploy. Never skip.
+2. **Managed identity over connection strings** — Always. No exceptions for production.
+3. **Key Vault for all secrets** — API keys, connection strings, certificates. Never in code or env files.
+4. **Least-privilege RBAC** — Use `azure-rbac` reference to find the minimal role.
+5. **azd up is destructive** — It creates/modifies Azure resources. Always confirm with user.
+6. **Bicep over ARM templates** — Bicep is the modern IaC for Azure. ARM JSON is legacy.
+7. **Cost awareness** — Check `azure-cost-optimization` reference before provisioning new resources.

package/.merlin-core/skills/domain/azure-cloud/references/appinsights-instrumentation.md

@@ -0,0 +1,63 @@
+# AppInsights Instrumentation Guide
+
+This skill provides **guidance and reference material** for instrumenting webapps with Azure Application Insights.
+
+> **ADDING COMPONENTS?**
+>
+> If the user wants to **add App Insights to their app**, invoke **azure-prepare** instead.
+> This skill provides reference material—azure-prepare orchestrates the actual changes.
+
+## When to Use This Skill
+
+- User asks **how** to instrument (guidance, patterns, examples)
+- User needs SDK setup instructions
+- azure-prepare invokes this skill during research phase
+- User wants to understand App Insights concepts
+
+## When to Use azure-prepare Instead
+
+- User says "add telemetry to my app"
+- User says "add App Insights"
+- User wants to modify their project
+- Any request to change/add components
+
+## Prerequisites
+
+The app in the workspace must be one of these kinds
+
+- An ASP.NET Core app hosted in Azure
+- A Node.js app hosted in Azure
+
+## Guidelines
+
+### Collect context information
+
+Find out the (programming language, application framework, hosting) tuple of the application the user is trying to add telemetry support in. This determines how the application can be instrumented. Read the source code to make an educated guess. Confirm with the user on anything you don't know. You must always ask the user where the application is hosted (e.g. on a personal computer, in an Azure App Service as code, in an Azure App Service as container, in an Azure Container App, etc.).
+
+### Prefer auto-instrument if possible
+
+If the app is a C# ASP.NET Core app hosted in Azure App Service, use [AUTO guide](references/auto.md) to help user auto-instrument the app.
+
+### Manually instrument
+
+Manually instrument the app by creating the AppInsights resource and update the app's code.
+
+#### Create AppInsights resource
+
+Use one of the following options that fits the environment.
+
+- Add AppInsights to existing Bicep template. See [examples/appinsights.bicep](examples/appinsights.bicep) for what to add. This is the best option if there are existing Bicep template files in the workspace.
+- Use Azure CLI. See [scripts/appinsights.ps1](scripts/appinsights.ps1) for what Azure CLI command to execute to create the App Insights resource.
+
+No matter which option you choose, recommend the user to create the App Insights resource in a meaningful resource group that makes managing resources easier. A good candidate will be the same resource group that contains the resources for the hosted app in Azure.
+
+#### Modify application code
+
+- If the app is an ASP.NET Core app, see [ASPNETCORE guide](references/aspnetcore.md) for how to modify the C# code.
+- If the app is a Node.js app, see [NODEJS guide](references/nodejs.md) for how to modify the JavaScript/TypeScript code.
+- If the app is a Python app, see [PYTHON guide](references/python.md) for how to modify the Python code.
+
+## SDK Quick References
+
+- **OpenTelemetry Distro**: [Python](references/sdk/azure-monitor-opentelemetry-py.md) | [TypeScript](references/sdk/azure-monitor-opentelemetry-ts.md)
+- **OpenTelemetry Exporter**: [Python](references/sdk/azure-monitor-opentelemetry-exporter-py.md) | [Java](references/sdk/azure-monitor-opentelemetry-exporter-java.md)

package/.merlin-core/skills/domain/azure-cloud/references/azure-compliance.md

@@ -0,0 +1,99 @@
+# Azure Compliance & Security Auditing
+
+## Quick Reference
+
+| Property             | Details                                                                  |
+| -------------------- | ------------------------------------------------------------------------ |
+| Best for             | Compliance scans, security audits, Key Vault expiration checks           |
+| Primary capabilities | Comprehensive Resources Assessment, Key Vault Expiration Monitoring      |
+| MCP tools            | azqr, subscription and resource group listing, Key Vault item inspection |
+
+## When to Use This Skill
+
+- Run azqr or Azure Quick Review for compliance assessment
+- Validate Azure resource configuration against best practices
+- Identify orphaned or misconfigured resources
+- Audit Key Vault keys, secrets, and certificates for expiration
+
+## Skill Activation Triggers
+
+Activate this skill when user wants to:
+
+- Check Azure compliance or best practices
+- Assess Azure resources for configuration issues
+- Run azqr or Azure Quick Review
+- Identify orphaned or misconfigured resources
+- Review Azure security posture
+- "Show me expired certificates/keys/secrets in my Key Vault"
+- "Check what's expiring in the next 30 days"
+- "Audit my Key Vault for compliance"
+- "Find secrets without expiration dates"
+- "Check certificate expiration dates"
+
+## Prerequisites
+
+- Authentication: user is logged in to Azure via `az login`
+- Permissions to read resource configuration and Key Vault metadata
+
+## Assessments
+
+| Assessment                      | Reference                                                                                      |
+| ------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Comprehensive Compliance (azqr) | [references/azure-quick-review.md](references/azure-quick-review.md)                           |
+| Key Vault Expiration            | [references/azure-keyvault-expiration-audit.md](references/azure-keyvault-expiration-audit.md) |
+| Resource Graph Queries          | [references/azure-resource-graph.md](references/azure-resource-graph.md)                       |
+
+## MCP Tools
+
+| Tool                              | Purpose                                      |
+| --------------------------------- | -------------------------------------------- |
+| `mcp_azure_mcp_extension_azqr`    | Run azqr compliance scans                    |
+| `mcp_azure_mcp_subscription_list` | List available subscriptions                 |
+| `mcp_azure_mcp_group_list`        | List resource groups                         |
+| `keyvault_key_list`               | List all keys in vault                       |
+| `keyvault_key_get`                | Get key details including expiration         |
+| `keyvault_secret_list`            | List all secrets in vault                    |
+| `keyvault_secret_get`             | Get secret details including expiration      |
+| `keyvault_certificate_list`       | List all certificates in vault               |
+| `keyvault_certificate_get`        | Get certificate details including expiration |
+
+## Assessment Workflow
+
+1. Select scope (subscription or resource group) for Comprehensive Resources Assessment.
+2. Run azqr and capture output artifacts.
+3. Analyze Scan Results and summarize findings and recommendations.
+4. Review Key Vault Expiration Monitoring output for keys, secrets, and certificates.
+5. Classify issues and propose remediation or fix steps for each finding.
+
+### Priority Classification
+
+| Priority | Guidance                                                |
+| -------- | ------------------------------------------------------- |
+| Critical | Immediate remediation required for high-impact exposure |
+| High     | Resolve within days to reduce risk                      |
+| Medium   | Plan a resolution in the next sprint                    |
+| Low      | Track and fix during regular maintenance                |
+
+## Error Handling
+
+| Error                   | Message        | Remediation                                      |
+| ----------------------- | -------------- | ------------------------------------------------ |
+| Authentication required | "Please login" | Run `az login` and retry                         |
+| Access denied           | "Forbidden"    | Confirm permissions and fix role assignments     |
+| Missing resource        | "Not found"    | Verify subscription and resource group selection |
+
+## Best Practices
+
+- Run compliance scans on a regular schedule (weekly or monthly)
+- Track findings over time and verify remediation effectiveness
+- Separate compliance reporting from remediation execution
+- Keep Key Vault expiration policies documented and enforced
+
+## SDK Quick References
+
+For programmatic Key Vault access, see the condensed SDK guides:
+
+- **Key Vault (Python)**: [Secrets/Keys/Certs](references/sdk/azure-keyvault-py.md)
+- **Secrets**: [TypeScript](references/sdk/azure-keyvault-secrets-ts.md) | [Rust](references/sdk/azure-keyvault-secrets-rust.md) | [Java](references/sdk/azure-security-keyvault-secrets-java.md)
+- **Keys**: [.NET](references/sdk/azure-security-keyvault-keys-dotnet.md) | [Java](references/sdk/azure-security-keyvault-keys-java.md) | [TypeScript](references/sdk/azure-keyvault-keys-ts.md) | [Rust](references/sdk/azure-keyvault-keys-rust.md)
+- **Certificates**: [Rust](references/sdk/azure-keyvault-certificates-rust.md)