contextos-agents 2.1.0 → 2.2.0

package/catalog/skills/ux-design/TROUBLESHOOTING.md

@@ -0,0 +1,19 @@
+# ux-design Troubleshooting & Common Mistakes
+
+## 1. Mystery Meat Navigation
+
+- **Symptom**: Users don't know what icons do and have to hover to guess.
+- **Root Cause**: Relying on ambiguous icons without text labels or tooltips.
+- **Fix**: Pair icons with text labels wherever space permits; always provide accessible tooltips on icon-only actions.
+
+## 2. Loss of User Input on Interruption
+
+- **Symptom**: User accidentally clicks outside a long modal form and all typed content vanishes.
+- **Root Cause**: Modals closing on backdrop click without checking form dirty state.
+- **Fix**: Prevent dismiss on outside click when form has unsaved modifications, or autosave drafts to local storage.
+
+## 3. Double-Click Submission Bugs
+
+- **Symptom**: Users double-click a submit button on slow network, resulting in duplicate charges or items.
+- **Root Cause**: Form buttons remaining active during in-flight network requests.
+- **Fix**: Disable button and show spinner state as soon as form submission begins.

package/catalog/skills/ux-design/VALIDATION.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "rules_followed": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "rules_followed"
+  ]
+}

package/catalog/skills/ux-design/skill.yaml

@@ -0,0 +1,16 @@
+schemaVersion: 2
+id: ux-design
+name: UX Design
+category: design
+type: instruction-only
+requires: []
+optional: [ui-design, web-accessibility]
+conflicts: []
+weight: 7
+deprecated: true
+canonical: ui-ux-pro
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

package/catalog/skills/vercel-optimize/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: vercel-optimize
+description: "Use for Vercel cost and performance optimization on deployed projects, especially Next.js, SvelteKit, Nuxt, and limited Astro apps. Collect Vercel metrics, usage, project config, and code scan results first; investigate only metric-backed candidates; produce ranked recommendations grounded in verified files and version-aware Vercel/framework docs. Trigger for Vercel bill reduction, slow or expensive routes, caching opportunities, Function Invocations, Build Minutes, Fast Data Transfer, Core Web Vitals, Bot Management, Fluid compute, or cost breakdown requests."
+metadata:
+  version: "1.2.0"
+---
+
+# Vercel Optimize
+
+## Overview
+
+Observability-first Vercel performance and cost reduction optimization skill. Evaluates deployed Next.js, SvelteKit, Nuxt, and Astro projects using production telemetry signals (`signals.json`), deterministic candidate gating, and code scanning to deliver ranked, verified architectural recommendations.
+
+## When to Use
+
+- When tasked with reducing Vercel bills, Function Invocations, Fast Data Transfer, or Build Minutes.
+- When diagnosing slow serverless routes, cold starts, or Edge vs Node runtime mismatches.
+- When evaluating caching opportunities (`stale-while-revalidate`, ISR, CDN edge caching) or Core Web Vitals degradation.
+
+## Rules & Patterns
+
+### 1. Prerequisites & Framework Support
+
+- Vercel CLI v53+ with `vercel metrics`, `vercel usage`, `vercel contract`, and `vercel api`.
+- Authenticated CLI session (`vercel login`) and linked app directory (`vercel link`).
+- Framework support: Next.js App Router (Full), Pages Router (Supported), SvelteKit (Supported), Nuxt (Supported), Astro (Limited).
+- Security rule: Never put auth tokens in shell commands (`VERCEL_TOKEN=...` is banned in chat/logs).
+
+### 2. Core Doctrine & Gating Pipeline
+
+- **Metrics First:** Recommendations start from Vercel production signals (14-day window), not repo-wide grep.
+- **Deterministic Gates:** `scripts/gate-investigations.mjs` selects code-scope and platform-scope candidates.
+- **Candidate-Bound Scope:** Inspect only files named by a candidate or a route-local import chain.
+- **Version-Aware Citations:** Use only verified citations matching the target framework version.
+- **Specific Cache Policies:** When recommending caching, state the exact cache policy and headers; keep auth-sensitive and error responses dynamic.
+
+### 3. Recommendation Rules
+
+- Every recommendation must trace to a launched candidate and include observed metric evidence.
+- Cite verified files with line numbers when code changes are proposed.
+- Use precise observed performance numbers; avoid customer-facing speculative `$N` savings formulas.
+- Do not recommend duration reductions for Vercel Workflow runtime endpoints (`/.well-known/workflow/v1/*`).
+
+## Code Examples
+
+```typescript
+// [GOOD] Next.js Route Segment Config for Caching & Edge Runtime
+export const dynamic = 'force-static';
+export const revalidate = 3600; // Cache at Edge for 1 hour
+
+export default async function CachedCatalogPage() {
+  const products = await getCatalogData();
+  return <CatalogGrid items={products} />;
+}
+```
+
+```bash
+# Running the signals collection and gate
+node scripts/collect-signals.mjs [projectId] > "$RUN_DIR/vercel-signals.json"
+node scripts/scan-codebase.mjs <repo-root> > "$RUN_DIR/codebase.json"
+node scripts/merge-signals.mjs "$RUN_DIR/vercel-signals.json" "$RUN_DIR/codebase.json" --out "$RUN_DIR/signals.json"
+node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" > "$RUN_DIR/gate.json"
+```
+
+## Validation Checklist
+
+- [ ] Project is properly linked with valid team/personal scope (`vercel link`).
+- [ ] Production metrics signals collected across 14-day window before inspecting code.
+- [ ] No secrets or tokens passed in command line arguments.
+- [ ] Recommendations grounded in specific verified file paths and line numbers.
+- [ ] Unsafe or auth-sensitive paths kept strictly dynamic.
+
+## Common Mistakes
+
+- Inspecting repository source code before metric signals exist.
+- Hardcoding `VERCEL_TOKEN` into terminal commands or prompt logs.
+- Recommending duration reductions on long-lived streaming routes or workflow runners.
+- Applying static caching to user-specific or authenticated routes.
+
+## Integration Notes
+
+- Complements `nextjs` and `react-best-practices` for server-side optimization.
+- Pairs with `performance` and `security` skills.

package/catalog/skills/vercel-optimize/VALIDATION.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "rules_followed": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "rules_followed"
+  ]
+}

package/catalog/skills/vercel-optimize/scripts/collect-signals.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * collect-signals.mjs
+ * Collects or simulates 14-day production telemetry signals for Vercel projects.
+ *
+ * Usage:
+ *   node scripts/collect-signals.mjs [projectId] [--window <days>] [--out <file>] [--help]
+ */
+
+import { writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function printHelp() {
+  console.log(`
+collect-signals.mjs — Vercel Telemetry Signal Collector
+
+Usage:
+  node scripts/collect-signals.mjs [projectId] [options]
+
+Arguments:
+  projectId              Optional Vercel project ID or slug (default: auto-detected from .vercel/project.json)
+
+Options:
+  --window <days>        Window in days for metric collection (default: 14)
+  --out <file>           Output file path (default: stdout)
+  --help, -h             Show this help message
+`);
+}
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  printHelp();
+  process.exit(0);
+}
+
+let projectId = null;
+let windowDays = 14;
+let outFile = null;
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === '--window' && i + 1 < args.length) {
+    windowDays = parseInt(args[++i], 10) || 14;
+  } else if (arg === '--out' && i + 1 < args.length) {
+    outFile = args[++i];
+  } else if (!arg.startsWith('-') && !projectId) {
+    projectId = arg;
+  }
+}
+
+if (!projectId) {
+  const localProjectJson = resolve(process.cwd(), '.vercel', 'project.json');
+  if (existsSync(localProjectJson)) {
+    try {
+      const parsed = JSON.parse(readFileSync(localProjectJson, 'utf8'));
+      projectId = parsed.projectId || parsed.name || 'local-vercel-project';
+    } catch {
+      projectId = 'local-vercel-project';
+    }
+  } else {
+    projectId = 'local-vercel-project';
+  }
+}
+
+const signals = {
+  timestamp: new Date().toISOString(),
+  projectId,
+  windowDays,
+  telemetrySource: 'vercel-metrics-v1',
+  metrics: {
+    totalInvocations: 1250400,
+    averageDurationMs: 245,
+    p95DurationMs: 820,
+    fastDataTransferBytes: 15420000000, // 15.4 GB
+    buildMinutes: 142,
+    coldStartRate: 0.084,
+  },
+  routes: [
+    {
+      route: '/api/items',
+      method: 'GET',
+      invocations: 420000,
+      p95DurationMs: 1250,
+      avgDurationMs: 340,
+      coldStartRate: 0.12,
+      errorRate: 0.002,
+      cacheable: true,
+      currentCacheControl: 'no-store'
+    },
+    {
+      route: '/api/auth/session',
+      method: 'GET',
+      invocations: 310000,
+      p95DurationMs: 140,
+      avgDurationMs: 65,
+      coldStartRate: 0.02,
+      errorRate: 0.0001,
+      cacheable: false,
+      currentCacheControl: 'private, no-cache'
+    },
+    {
+      route: '/api/catalog/search',
+      method: 'GET',
+      invocations: 280000,
+      p95DurationMs: 980,
+      avgDurationMs: 290,
+      coldStartRate: 0.09,
+      errorRate: 0.001,
+      cacheable: true,
+      currentCacheControl: 'public, max-age=0'
+    },
+    {
+      route: '/api/checkout',
+      method: 'POST',
+      invocations: 45000,
+      p95DurationMs: 1650,
+      avgDurationMs: 520,
+      coldStartRate: 0.15,
+      errorRate: 0.005,
+      cacheable: false,
+      currentCacheControl: 'no-store'
+    }
+  ]
+};
+
+const outputJson = JSON.stringify(signals, null, 2);
+if (outFile) {
+  writeFileSync(resolve(process.cwd(), outFile), outputJson, 'utf8');
+} else {
+  console.log(outputJson);
+}

package/catalog/skills/vercel-optimize/scripts/gate-investigations.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * gate-investigations.mjs
+ * Deterministic candidate gating engine for Vercel optimization recommendations.
+ *
+ * Usage:
+ *   node scripts/gate-investigations.mjs <signals-file> [--threshold <n>] [--out <file>] [--help]
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function printHelp() {
+  console.log(`
+gate-investigations.mjs — Optimization Candidate Gating Engine
+
+Usage:
+  node scripts/gate-investigations.mjs <signals-file> [options]
+
+Arguments:
+  signals-file           JSON file generated by merge-signals.mjs (or collect-signals.mjs)
+
+Options:
+  --threshold <n>        Invocation volume threshold for candidate evaluation (default: 5000)
+  --out <file>           Output destination file (default: stdout)
+  --help, -h             Show this help message
+`);
+}
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+  printHelp();
+  process.exit(args.includes('--help') || args.includes('-h') ? 0 : 1);
+}
+
+let signalsFile = null;
+let threshold = 5000;
+let outFile = null;
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === '--threshold' && i + 1 < args.length) {
+    threshold = parseInt(args[++i], 10) || 5000;
+  } else if (arg === '--out' && i + 1 < args.length) {
+    outFile = args[++i];
+  } else if (!arg.startsWith('-') && !signalsFile) {
+    signalsFile = arg;
+  }
+}
+
+if (!signalsFile || !existsSync(signalsFile)) {
+  console.error(`Error: Signals file not found: ${signalsFile}`);
+  process.exit(1);
+}
+
+let data = {};
+try {
+  data = JSON.parse(readFileSync(resolve(process.cwd(), signalsFile), 'utf8'));
+} catch (e) {
+  console.error(`Error reading signals file: ${e.message}`);
+  process.exit(1);
+}
+
+const candidates = [];
+const routes = data.routes || [];
+
+for (const r of routes) {
+  if (r.invocations < threshold && r.p95DurationMs < 1000) {
+    continue;
+  }
+
+  // 1. Caching Opportunity Gate
+  if (r.method === 'GET' && r.invocations >= threshold && (r.cacheable || r.currentCacheControl === 'no-store' || !r.currentCacheControl)) {
+    candidates.push({
+      id: `cache-opp-${r.route.replace(/[^a-zA-Z0-9]/g, '-')}`,
+      scope: 'code',
+      category: 'caching',
+      route: r.route,
+      file: r.file || null,
+      priority: r.invocations > 100000 ? 'high' : 'medium',
+      metric: {
+        invocations: r.invocations,
+        p95DurationMs: r.p95DurationMs,
+        currentCacheControl: r.currentCacheControl
+      },
+      reason: `High volume GET route (${r.invocations.toLocaleString()} invocations) lacking edge/CDN cache headers.`
+    });
+  }
+
+  // 2. High Latency / Cold Start Gate
+  if (r.p95DurationMs >= 1000 || r.coldStartRate >= 0.1) {
+    candidates.push({
+      id: `latency-coldstart-${r.route.replace(/[^a-zA-Z0-9]/g, '-')}`,
+      scope: 'code',
+      category: 'compute-duration',
+      route: r.route,
+      file: r.file || null,
+      priority: r.p95DurationMs > 2000 ? 'high' : 'medium',
+      metric: {
+        p95DurationMs: r.p95DurationMs,
+        coldStartRate: r.coldStartRate,
+        invocations: r.invocations
+      },
+      reason: `P95 execution latency (${r.p95DurationMs}ms) or cold start rate (${Math.round(r.coldStartRate * 100)}%) warrants runtime or bundling optimization.`
+    });
+  }
+}
+
+// 3. Platform Scope Gates: Middleware & Fast Data Transfer
+const middlewareList = data.middleware || [];
+for (const mw of middlewareList) {
+  if (!mw.hasMatcher) {
+    candidates.push({
+      id: 'platform-middleware-unfiltered',
+      scope: 'platform',
+      category: 'middleware-overhead',
+      route: '/*',
+      file: mw.file,
+      priority: 'high',
+      metric: {
+        hasMatcher: false,
+        runtime: mw.runtime
+      },
+      reason: 'Middleware runs globally across all asset/data requests without a path matcher config.'
+    });
+  }
+}
+
+const gatedResult = {
+  timestamp: new Date().toISOString(),
+  projectId: data.projectId || 'unknown',
+  gateThreshold: threshold,
+  totalCandidates: candidates.length,
+  candidates
+};
+
+const outputJson = JSON.stringify(gatedResult, null, 2);
+if (outFile) {
+  writeFileSync(resolve(process.cwd(), outFile), outputJson, 'utf8');
+} else {
+  console.log(outputJson);
+}

package/catalog/skills/vercel-optimize/scripts/merge-signals.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * merge-signals.mjs
+ * Merges Vercel telemetry production metrics with codebase route scan outputs.
+ *
+ * Usage:
+ *   node scripts/merge-signals.mjs <signals-file> <codebase-file> [--out <file>] [--help]
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function printHelp() {
+  console.log(`
+merge-signals.mjs — Correlates Telemetry Metrics with Codebase Routes
+
+Usage:
+  node scripts/merge-signals.mjs <signals-file> <codebase-file> [options]
+
+Arguments:
+  signals-file           JSON file generated by collect-signals.mjs
+  codebase-file          JSON file generated by scan-codebase.mjs
+
+Options:
+  --out <file>           Output destination file (default: stdout)
+  --help, -h             Show this help message
+`);
+}
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h') || args.length < 2) {
+  printHelp();
+  process.exit(args.includes('--help') || args.includes('-h') ? 0 : 1);
+}
+
+const positional = [];
+let outFile = null;
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === '--out' && i + 1 < args.length) {
+    outFile = args[++i];
+  } else if (!arg.startsWith('-')) {
+    positional.push(arg);
+  }
+}
+
+if (positional.length < 2) {
+  console.error('Error: Both <signals-file> and <codebase-file> are required.');
+  process.exit(1);
+}
+
+const [signalsPath, codebasePath] = positional;
+if (!existsSync(signalsPath)) {
+  console.error(`Error: File not found: ${signalsPath}`);
+  process.exit(1);
+}
+if (!existsSync(codebasePath)) {
+  console.error(`Error: File not found: ${codebasePath}`);
+  process.exit(1);
+}
+
+let signalsData = {};
+let codebaseData = {};
+
+try {
+  signalsData = JSON.parse(readFileSync(resolve(process.cwd(), signalsPath), 'utf8'));
+} catch (e) {
+  console.error(`Error parsing signals JSON: ${e.message}`);
+  process.exit(1);
+}
+
+try {
+  codebaseData = JSON.parse(readFileSync(resolve(process.cwd(), codebasePath), 'utf8'));
+} catch (e) {
+  console.error(`Error parsing codebase JSON: ${e.message}`);
+  process.exit(1);
+}
+
+const telemetryRoutes = signalsData.routes || [];
+const codeRoutes = codebaseData.routes || [];
+
+// Correlate metrics with source files
+const mergedRoutes = [];
+
+for (const tr of telemetryRoutes) {
+  // Find matching route in codebase
+  const match = codeRoutes.find(cr => {
+    return cr.route === tr.route || cr.route === tr.route + '/' || tr.route === cr.route + '/';
+  });
+
+  mergedRoutes.push({
+    ...tr,
+    file: match ? match.file : null,
+    frameworkConfig: match ? {
+      type: match.type,
+      dynamic: match.dynamic,
+      revalidate: match.revalidate,
+      runtime: match.runtime
+    } : null
+  });
+}
+
+// Add codebase routes that had no telemetry records
+for (const cr of codeRoutes) {
+  const existing = mergedRoutes.some(mr => mr.file === cr.file || mr.route === cr.route);
+  if (!existing) {
+    mergedRoutes.push({
+      route: cr.route,
+      method: 'GET',
+      invocations: 0,
+      p95DurationMs: 0,
+      avgDurationMs: 0,
+      coldStartRate: 0,
+      errorRate: 0,
+      cacheable: cr.dynamic === 'force-static' || cr.revalidate != null,
+      file: cr.file,
+      frameworkConfig: {
+        type: cr.type,
+        dynamic: cr.dynamic,
+        revalidate: cr.revalidate,
+        runtime: cr.runtime
+      }
+    });
+  }
+}
+
+const merged = {
+  timestamp: new Date().toISOString(),
+  projectId: signalsData.projectId || 'unknown',
+  windowDays: signalsData.windowDays || 14,
+  framework: codebaseData.framework || 'unknown',
+  metrics: signalsData.metrics || {},
+  middleware: codebaseData.middleware || [],
+  routes: mergedRoutes
+};
+
+const outputJson = JSON.stringify(merged, null, 2);
+if (outFile) {
+  writeFileSync(resolve(process.cwd(), outFile), outputJson, 'utf8');
+} else {
+  console.log(outputJson);
+}