aigroup-workflow 2.1.2 → 2.2.0

package/skills/infra/mcp-developer/references/typescript-sdk.md

@@ -0,0 +1,350 @@
+# TypeScript SDK Implementation
+
+## Installation
+
+```bash
+npm install @modelcontextprotocol/sdk zod
+```
+
+## Basic Server Setup
+
+```typescript
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+
+// Create server instance
+const server = new Server(
+  {
+    name: "example-server",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      resources: {},
+      tools: {},
+      prompts: {},
+    },
+  }
+);
+
+// Handle tools/list request
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "get_weather",
+        description: "Get current weather for a location",
+        inputSchema: {
+          type: "object",
+          properties: {
+            location: {
+              type: "string",
+              description: "City name or zip code",
+            },
+            units: {
+              type: "string",
+              enum: ["celsius", "fahrenheit"],
+              default: "celsius",
+            },
+          },
+          required: ["location"],
+        },
+      },
+    ],
+  };
+});
+
+// Handle tools/call request
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name === "get_weather") {
+    const location = String(request.params.arguments?.location);
+    const units = String(request.params.arguments?.units ?? "celsius");
+
+    // Your tool logic here
+    const weatherData = await fetchWeather(location, units);
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Weather in ${location}: ${weatherData.temp}°${units === "celsius" ? "C" : "F"}`,
+        },
+      ],
+    };
+  }
+
+  throw new Error(`Unknown tool: ${request.params.name}`);
+});
+
+// Start server with stdio transport
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("MCP Server running on stdio");
+}
+
+main().catch(console.error);
+```
+
+## Resource Provider
+
+```typescript
+import {
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+// List resources
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  return {
+    resources: [
+      {
+        uri: "file:///config/settings.json",
+        name: "Application Settings",
+        description: "Current application configuration",
+        mimeType: "application/json",
+      },
+      {
+        uri: "db://users/schema",
+        name: "User Schema",
+        description: "Database schema for users table",
+        mimeType: "text/plain",
+      },
+    ],
+  };
+});
+
+// Read resource content
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const uri = request.params.uri;
+
+  if (uri === "file:///config/settings.json") {
+    const settings = await loadSettings();
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "application/json",
+          text: JSON.stringify(settings, null, 2),
+        },
+      ],
+    };
+  }
+
+  if (uri.startsWith("db://users/")) {
+    const schema = await getDatabaseSchema("users");
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "text/plain",
+          text: schema,
+        },
+      ],
+    };
+  }
+
+  throw new Error(`Resource not found: ${uri}`);
+});
+```
+
+## Prompt Templates
+
+```typescript
+import {
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+  return {
+    prompts: [
+      {
+        name: "code_review",
+        description: "Generate code review comments",
+        arguments: [
+          {
+            name: "language",
+            description: "Programming language",
+            required: true,
+          },
+          {
+            name: "code",
+            description: "Code to review",
+            required: true,
+          },
+        ],
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+  if (request.params.name === "code_review") {
+    const language = String(request.params.arguments?.language);
+    const code = String(request.params.arguments?.code);
+
+    return {
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Review this ${language} code and provide feedback:\n\n${code}`,
+          },
+        },
+      ],
+    };
+  }
+
+  throw new Error(`Unknown prompt: ${request.params.name}`);
+});
+```
+
+## Input Validation with Zod
+
+```typescript
+import { z } from "zod";
+
+// Define schemas for validation
+const WeatherArgsSchema = z.object({
+  location: z.string().min(1),
+  units: z.enum(["celsius", "fahrenheit"]).default("celsius"),
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name === "get_weather") {
+    // Validate and parse arguments
+    const args = WeatherArgsSchema.parse(request.params.arguments);
+
+    const weatherData = await fetchWeather(args.location, args.units);
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Temperature: ${weatherData.temp}°${args.units === "celsius" ? "C" : "F"}`,
+        },
+      ],
+    };
+  }
+
+  throw new Error(`Unknown tool: ${request.params.name}`);
+});
+```
+
+## Error Handling
+
+```typescript
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  try {
+    // Validate input
+    if (!request.params.arguments?.location) {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        "location parameter is required"
+      );
+    }
+
+    const result = await executeTool(request.params.name, request.params.arguments);
+    return { content: [{ type: "text", text: result }] };
+
+  } catch (error) {
+    if (error instanceof McpError) {
+      throw error; // Re-throw MCP errors
+    }
+
+    // Wrap other errors
+    throw new McpError(
+      ErrorCode.InternalError,
+      `Tool execution failed: ${error.message}`
+    );
+  }
+});
+```
+
+## Basic Client Setup
+
+```typescript
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const client = new Client(
+  {
+    name: "example-client",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {},
+  }
+);
+
+// Connect to server
+const transport = new StdioClientTransport({
+  command: "node",
+  args: ["./server.js"],
+});
+
+await client.connect(transport);
+
+// List available tools
+const toolsResponse = await client.request(
+  { method: "tools/list" },
+  ListToolsResultSchema
+);
+
+console.log("Available tools:", toolsResponse.tools);
+
+// Call a tool
+const result = await client.request(
+  {
+    method: "tools/call",
+    params: {
+      name: "get_weather",
+      arguments: { location: "San Francisco" },
+    },
+  },
+  CallToolResultSchema
+);
+
+console.log("Result:", result.content);
+```
+
+## Notifications
+
+```typescript
+// Server sends notification
+server.notification({
+  method: "notifications/resources/updated",
+  params: {
+    uri: "file:///config/settings.json",
+  },
+});
+
+// Client handles notifications
+client.setNotificationHandler((notification) => {
+  if (notification.method === "notifications/resources/updated") {
+    console.log("Resource updated:", notification.params.uri);
+  }
+});
+```
+
+## Best Practices
+
+1. **Type Safety**: Use Zod for runtime validation
+2. **Error Handling**: Always wrap errors in McpError
+3. **Async/Await**: Use async/await throughout
+4. **Logging**: Log to stderr, not stdout (stdio transport)
+5. **Cleanup**: Handle graceful shutdown
+6. **Testing**: Use unit tests with mock transports
+7. **Performance**: Cache expensive operations
+8. **Security**: Validate all inputs, sanitize outputs

package/skills/infra/monitoring-expert/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: monitoring-expert
+description: Configures monitoring systems, implements structured logging pipelines, creates Prometheus/Grafana dashboards, defines alerting rules, and instruments distributed tracing. Implements Prometheus/Grafana stacks, conducts load testing, performs application profiling, and plans infrastructure capacity. Use when setting up application monitoring, adding observability to services, debugging production issues with logs/metrics/traces, running load tests with k6 or Artillery, profiling CPU/memory bottlenecks, or forecasting capacity needs.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.0"
+  domain: devops
+  triggers: monitoring, observability, logging, metrics, tracing, alerting, Prometheus, Grafana, DataDog, APM, performance testing, load testing, profiling, capacity planning, bottleneck
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: devops-engineer, debugging-wizard, architecture-designer
+---
+
+# Monitoring Expert
+
+Observability and performance specialist implementing comprehensive monitoring, alerting, tracing, and performance testing systems.
+
+## Core Workflow
+
+1. **Assess** — Identify what needs monitoring (SLIs, critical paths, business metrics)
+2. **Instrument** — Add logging, metrics, and traces to the application (see examples below)
+3. **Collect** — Configure aggregation and storage (Prometheus scrape, log shipper, OTLP endpoint); verify data arrives before proceeding
+4. **Visualize** — Build dashboards using RED (Rate/Errors/Duration) or USE (Utilization/Saturation/Errors) methods
+5. **Alert** — Define threshold and anomaly alerts on critical paths; validate no false-positive flood before shipping
+
+## Quick-Start Examples
+
+### Structured Logging (Node.js / Pino)
+```js
+import pino from 'pino';
+
+const logger = pino({ level: 'info' });
+
+// Good — structured fields, includes correlation ID
+logger.info({ requestId: req.id, userId: req.user.id, durationMs: elapsed }, 'order.created');
+
+// Bad — string interpolation, no correlation
+console.log(`Order created for user ${userId}`);
+```
+
+### Prometheus Metrics (Node.js)
+```js
+import { Counter, Histogram, register } from 'prom-client';
+
+const httpRequests = new Counter({
+  name: 'http_requests_total',
+  help: 'Total HTTP requests',
+  labelNames: ['method', 'route', 'status'],
+});
+
+const httpDuration = new Histogram({
+  name: 'http_request_duration_seconds',
+  help: 'HTTP request latency',
+  labelNames: ['method', 'route'],
+  buckets: [0.05, 0.1, 0.3, 0.5, 1, 2, 5],
+});
+
+// Instrument a route
+app.use((req, res, next) => {
+  const end = httpDuration.startTimer({ method: req.method, route: req.path });
+  res.on('finish', () => {
+    httpRequests.inc({ method: req.method, route: req.path, status: res.statusCode });
+    end();
+  });
+  next();
+});
+
+// Expose scrape endpoint
+app.get('/metrics', async (req, res) => {
+  res.set('Content-Type', register.contentType);
+  res.end(await register.metrics());
+});
+```
+
+### OpenTelemetry Tracing (Node.js)
+```js
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { trace } from '@opentelemetry/api';
+
+const sdk = new NodeSDK({
+  traceExporter: new OTLPTraceExporter({ url: 'http://jaeger:4318/v1/traces' }),
+});
+sdk.start();
+
+// Manual span around a critical operation
+const tracer = trace.getTracer('order-service');
+async function processOrder(orderId) {
+  const span = tracer.startSpan('order.process');
+  span.setAttribute('order.id', orderId);
+  try {
+    const result = await db.saveOrder(orderId);
+    span.setStatus({ code: SpanStatusCode.OK });
+    return result;
+  } catch (err) {
+    span.recordException(err);
+    span.setStatus({ code: SpanStatusCode.ERROR });
+    throw err;
+  } finally {
+    span.end();
+  }
+}
+```
+
+### Prometheus Alerting Rule
+```yaml
+groups:
+  - name: api.rules
+    rules:
+      - alert: HighErrorRate
+        expr: |
+          rate(http_requests_total{status=~"5.."}[5m])
+          / rate(http_requests_total[5m]) > 0.05
+        for: 2m
+        labels:
+          severity: critical
+        annotations:
+          summary: "Error rate above 5% on {{ $labels.route }}"
+```
+
+### k6 Load Test
+```js
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+
+export const options = {
+  stages: [
+    { duration: '1m', target: 50 },   // ramp up
+    { duration: '5m', target: 50 },   // sustained load
+    { duration: '1m', target: 0 },    // ramp down
+  ],
+  thresholds: {
+    http_req_duration: ['p(95)<500'],  // 95th percentile < 500 ms
+    http_req_failed:   ['rate<0.01'],  // error rate < 1%
+  },
+};
+
+export default function () {
+  const res = http.get('https://api.example.com/orders');
+  check(res, { 'status is 200': (r) => r.status === 200 });
+  sleep(1);
+}
+```
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Logging | `references/structured-logging.md` | Pino, JSON logging |
+| Metrics | `references/prometheus-metrics.md` | Counter, Histogram, Gauge |
+| Tracing | `references/opentelemetry.md` | OpenTelemetry, spans |
+| Alerting | `references/alerting-rules.md` | Prometheus alerts |
+| Dashboards | `references/dashboards.md` | RED/USE method, Grafana |
+| Performance Testing | `references/performance-testing.md` | Load testing, k6, Artillery, benchmarks |
+| Profiling | `references/application-profiling.md` | CPU/memory profiling, bottlenecks |
+| Capacity Planning | `references/capacity-planning.md` | Scaling, forecasting, budgets |
+
+## Constraints
+
+### MUST DO
+- Use structured logging (JSON)
+- Include request IDs for correlation
+- Set up alerts for critical paths
+- Monitor business metrics, not just technical
+- Use appropriate metric types (counter/gauge/histogram)
+- Implement health check endpoints
+
+### MUST NOT DO
+- Log sensitive data (passwords, tokens, PII)
+- Alert on every error (alert fatigue)
+- Use string interpolation in logs (use structured fields)
+- Skip correlation IDs in distributed systems

package/skills/infra/monitoring-expert/references/alerting-rules.md

@@ -0,0 +1,141 @@
+# Alerting Rules
+
+## Prometheus Alert Rules
+
+```yaml
+# alerts.yml
+groups:
+  - name: application
+    rules:
+      - alert: HighErrorRate
+        expr: |
+          sum(rate(http_requests_total{status=~"5.."}[5m]))
+          /
+          sum(rate(http_requests_total[5m])) > 0.05
+        for: 5m
+        labels:
+          severity: critical
+        annotations:
+          summary: High error rate detected
+          description: Error rate is {{ $value | humanizePercentage }}
+
+      - alert: HighLatency
+        expr: |
+          histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) > 1
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: High latency detected
+          description: 95th percentile latency is {{ $value }}s
+
+      - alert: ServiceDown
+        expr: up == 0
+        for: 1m
+        labels:
+          severity: critical
+        annotations:
+          summary: Service {{ $labels.instance }} is down
+
+  - name: infrastructure
+    rules:
+      - alert: HighMemoryUsage
+        expr: |
+          (node_memory_MemTotal_bytes - node_memory_MemAvailable_bytes)
+          / node_memory_MemTotal_bytes > 0.9
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: High memory usage on {{ $labels.instance }}
+
+      - alert: HighCPUUsage
+        expr: |
+          100 - (avg by(instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100) > 80
+        for: 10m
+        labels:
+          severity: warning
+        annotations:
+          summary: High CPU usage on {{ $labels.instance }}
+
+      - alert: DiskSpaceLow
+        expr: |
+          (node_filesystem_avail_bytes / node_filesystem_size_bytes) < 0.1
+        for: 5m
+        labels:
+          severity: critical
+        annotations:
+          summary: Disk space low on {{ $labels.instance }}
+```
+
+## Alert Design Principles
+
+```yaml
+# Good alert: Actionable, specific
+- alert: DatabaseConnectionPoolExhausted
+  expr: db_pool_available_connections == 0
+  for: 2m
+  annotations:
+    runbook_url: https://wiki.example.com/runbooks/db-pool
+
+# Bad alert: Too noisy, not actionable
+- alert: AnyError
+  expr: errors_total > 0  # Will always fire
+```
+
+## Severity Levels
+
+| Severity | Response | Example |
+|----------|----------|---------|
+| `critical` | Page immediately | Service down, data loss |
+| `warning` | Investigate soon | High latency, low disk |
+| `info` | Check in morning | Unusual traffic pattern |
+
+## Alertmanager Configuration
+
+```yaml
+# alertmanager.yml
+global:
+  slack_api_url: 'https://hooks.slack.com/...'
+
+route:
+  receiver: 'slack-notifications'
+  group_by: ['alertname', 'severity']
+  group_wait: 30s
+  group_interval: 5m
+  repeat_interval: 4h
+
+  routes:
+    - match:
+        severity: critical
+      receiver: 'pagerduty'
+    - match:
+        severity: warning
+      receiver: 'slack-notifications'
+
+receivers:
+  - name: 'slack-notifications'
+    slack_configs:
+      - channel: '#alerts'
+        send_resolved: true
+
+  - name: 'pagerduty'
+    pagerduty_configs:
+      - service_key: 'your-key'
+```
+
+## Quick Reference
+
+| Field | Purpose |
+|-------|---------|
+| `expr` | PromQL query |
+| `for` | Duration before firing |
+| `labels` | Classification (severity) |
+| `annotations` | Human-readable info |
+
+| Threshold | Use |
+|-----------|-----|
+| Error rate > 5% | Critical |
+| p95 latency > 1s | Warning |
+| Disk < 10% | Critical |
+| Memory > 90% | Warning |