contextos-agents 2.0.0 → 2.1.1

package/catalog/skills/ui-ux-pro/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/ui-ux-pro/skill.yaml

@@ -0,0 +1,14 @@
+schemaVersion: 2
+name: ui-ux-pro
+category: design
+type: instruction-only
+description: >
+  Professional UI/UX design skill with strict anti-pattern enforcement.
+  Prevents AI slop design, enforces accessibility standards, semantic
+  color palettes, proper spacing, and bans overused design clichés.
+version: 1.0.0
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

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

@@ -0,0 +1,36 @@
+# ux-design Examples - Anti-patterns vs ContextOS Standard
+
+## Example 1: Destructive Actions
+
+### Anti-pattern: Instant Deletion Without Confirmation or Recovery
+
+```tsx
+// BAD: Immediate delete on click, no confirmation, irreversible data loss
+<button onClick={() => deleteProject(project.id)}>Delete</button>
+```
+
+### Best practice: ContextOS Standard (Two-Step Confirmation or Undo Toast)
+
+```tsx
+// GOOD: Clear confirmation dialog stating exact item name and non-reversible impact
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button variant="destructive">Delete Project</Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
+      <AlertDialogDescription>
+        This action cannot be undone. This will permanently delete <strong>{project.name}</strong>
+        and all associated API keys.
+      </AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancel</AlertDialogCancel>
+      <AlertDialogAction onClick={handleDelete} className="bg-destructive">
+        Delete permanently
+      </AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```

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

@@ -0,0 +1,116 @@
+---
+name: UX Design
+description: >
+  ContextOS skill for UX Design
+---
+
+# UX Design
+
+## Overview
+
+User experience and interaction design standard. Enforces progressive disclosure, predictable user flows, designed empty/loading/error states, form usability, and keyboard navigation ergonomics.
+
+## When to Use
+
+Activate when designing complex multi-step workflows, onboarding funnels, form validation feedback, error recovery flows, and user journeys.
+
+## Rules & Patterns
+<!-- Source: ux.md -->
+
+## UX Design - Best Practices
+
+## Information Architecture
+
+- **Mental models** - organize content the way users think, not the way your code is structured
+- **Card sorting** - group features into logical categories
+- **Navigation structure** - no more than 3 clicks to any page
+- **Naming** - use user's language, not internal jargon
+
+## User Flows
+
+### Design every state
+
+Every screen has 5 states. Design ALL of them:
+
+1. **Empty state** - first visit, no data yet. Include CTA to get started
+2. **Loading state** - skeleton screens > spinners
+3. **Partial state** - some data, not complete
+4. **Ideal state** - normal usage with data
+5. **Error state** - what went wrong and how to fix it
+
+### Reduce cognitive load
+
+- **Progressive disclosure** - show only what's needed now
+- **Sensible defaults** - pre-fill what you can
+- **Inline help** - tooltips and contextual guidance
+- **Confirmation for destructive actions** - but NOT for every action
+
+## Forms UX
+
+- Show progress for multi-step forms
+- Validate inline (on blur), not on submit
+- Show password requirements as the user types
+- Auto-focus the first input
+- Use appropriate input types (email, tel, date)
+- Disable submit button only when form is submitting, never as "validation"
+
+## Onboarding
+
+- **Quick win** - let users see value within 30 seconds
+- **Minimal signup** - only ask for what's absolutely needed
+- **Progressive onboarding** - teach features as users encounter them
+- **Skip option** - always let users skip tutorials
+
+## Feedback
+
+- Every action needs feedback (success, error, pending)
+- Use toast notifications for non-blocking feedback
+- Use inline messages for form validation
+- Loading states should be < 300ms before showing (avoid flash)
+- Optimistic UI for fast-perceived actions
+
+## Mobile UX
+
+- Touch targets: minimum 44x44px
+- Thumb zones - place primary actions within easy reach
+- Bottom navigation for core actions
+- Pull-to-refresh for content lists
+- Haptic feedback for important actions
+
+## Psychology Principles
+
+- **Fitts's Law** - make important targets large and close
+- **Hick's Law** - reduce choices to reduce decision time
+- **Jakob's Law** - users prefer familiar patterns
+- **Peak-End Rule** - make the last interaction great
+- **Aesthetic-Usability Effect** - beautiful things are perceived as easier to use
+
+## Usability Heuristics (Nielsen)
+
+1. Visibility of system status
+2. Match between system and real world
+3. User control and freedom (undo, escape)
+4. Consistency and standards
+5. Error prevention
+6. Recognition rather than recall
+7. Flexibility and efficiency of use
+8. Aesthetic and minimalist design
+9. Help users recognize and recover from errors
+10. Help and documentation
+
+
+## Code Examples
+
+See `EXAMPLES.md` for detailed code examples.
+
+## Validation Checklist
+
+What to verify during the review phase before completing the task.
+
+## Common Mistakes
+
+Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
+
+## Integration Notes
+
+How this skill interacts with other skills.

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);
+}