contextos-agents 1.6.1 → 1.7.0

package/.agents/core/skills/interview-me/skill.yaml

@@ -1,4 +1,5 @@
 name: interview-me
+type: instruction-only
 description: Interactive requirements elicitation skill. Interrogates ambiguous, complex, or high-blast-radius tasks one focused question at a time before any plan or code is written.
 tags:
   - workflow
@@ -6,3 +7,6 @@ tags:
   - planning
   - interview
 version: 1.0.0
+resources:
+  - SKILL.md
+  - VALIDATION.json

package/.agents/core/skills/microservices/skill.yaml

@@ -1,6 +1,7 @@
 id: microservices
 name: Microservices
 category: architecture
+type: instruction-only
 tags: [architecture, microservices, distributed, event-driven, cqrs]
 requires: [system-design]
 optional: [docker, security]
@@ -8,3 +9,9 @@ conflicts: []
 weight: 6
 documents:
   - microservices.md
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json
+  - microservices.md

package/.agents/core/skills/minimalist-design/skill.yaml

@@ -1,4 +1,5 @@
 name: minimalist-design
+type: instruction-only
 description: Clean editorial-style interfaces with warm monochrome palettes and flat bento grids.
 tags:
   - ui
@@ -6,3 +7,6 @@ tags:
   - minimalist
   - editorial
 version: 1.0.0
+resources:
+  - SKILL.md
+  - VALIDATION.json

package/.agents/core/skills/nestjs/skill.yaml

@@ -1,6 +1,7 @@
 id: nestjs
 name: NestJS
 category: backend
+type: instruction-only
 tags: [backend, nodejs, typescript, enterprise, di, decorators]
 requires: [typescript, node]
 optional: [postgres, redis, docker, graphql]
@@ -8,3 +9,9 @@ conflicts: [fastapi, express]
 weight: 8
 documents:
   - nestjs.md
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json
+  - nestjs.md

package/.agents/core/skills/nextjs/skill.yaml

@@ -1,6 +1,7 @@
 id: nextjs
 name: Next.js
 category: frontend
+type: instruction-only
 tags: [frontend, ssr, ssg, fullstack, react, app-router]
 requires: [react, typescript]
 optional: [tailwind, prisma, next-auth, react-query]
@@ -8,3 +9,9 @@ conflicts: [vue, angular, remix]
 weight: 9
 documents:
   - nextjs.md
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json
+  - nextjs.md

package/.agents/core/skills/node/skill.yaml

@@ -1,6 +1,7 @@
 id: node
 name: Node.js
 category: backend
+type: instruction-only
 tags: [backend, javascript, runtime, server, express, fastify]
 requires: [typescript]
 optional: [postgres, redis, docker]
@@ -8,3 +9,9 @@ conflicts: []
 weight: 7
 documents:
   - node.md
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json
+  - node.md

package/.agents/core/skills/performance/skill.yaml

@@ -1,6 +1,7 @@
 id: performance
 name: Web Performance
 category: frontend
+type: instruction-only
 tags: [frontend, performance, core-web-vitals, optimization]
 requires: []
 optional: [react, nextjs]
@@ -8,3 +9,9 @@ conflicts: []
 weight: 6
 documents:
   - performance.md
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json
+  - performance.md

package/.agents/core/skills/ponytail-mindset/skill.yaml

@@ -1,4 +1,5 @@
 name: ponytail-mindset
+type: instruction-only
 description: >
   Minimalist coding mindset based on DietrichGebert/ponytail.
   Teaches the AI to write only what is strictly necessary.
@@ -12,3 +13,8 @@ tags:
   - refactoring
 version: 1.0.0
 source: https://github.com/DietrichGebert/ponytail
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

package/.agents/core/skills/react/skill.yaml

@@ -1,6 +1,7 @@
 id: react
 name: React
 category: frontend
+type: instruction-only
 tags: [frontend, spa, jsx, components, hooks]
 requires: [typescript]
 optional: [tailwind, react-query, zustand, next-auth]
@@ -8,3 +9,9 @@ conflicts: [vue, angular, svelte]
 weight: 8
 documents:
   - react.md
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json
+  - react.md

package/.agents/core/skills/react-best-practices/skill.yaml

@@ -1,4 +1,5 @@
 name: react-best-practices
+type: instruction-only
 description: React and Next.js performance optimization guidelines from Vercel Engineering.
 tags:
   - react
@@ -8,3 +9,6 @@ tags:
 version: 1.0.0
 requires:
   - react
+resources:
+  - SKILL.md
+  - VALIDATION.json

package/.agents/core/skills/redesign-audit/skill.yaml

@@ -1,4 +1,5 @@
 name: redesign-audit
+type: instruction-only
 description: Audits and upgrades existing web codebases with high-end typography, color, layout, and interaction polish.
 tags:
   - ui
@@ -6,3 +7,6 @@ tags:
   - audit
   - refactor
 version: 1.0.0
+resources:
+  - SKILL.md
+  - VALIDATION.json

package/.agents/core/skills/security/skill.yaml

@@ -1,6 +1,7 @@
 id: security
 name: Application Security
 category: backend
+type: instruction-only
 tags: [backend, security, auth, owasp, jwt, encryption]
 requires: []
 optional: [node, fastapi, nestjs]
@@ -8,3 +9,9 @@ conflicts: []
 weight: 9
 documents:
   - security.md
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json
+  - security.md

package/.agents/core/skills/soft-design/skill.yaml

@@ -1,4 +1,5 @@
 name: soft-design
+type: instruction-only
 description: High-end agency-grade UI architecture, haptic micro-aesthetics, and fluid spring motion choreography.
 tags:
   - ui
@@ -6,3 +7,6 @@ tags:
   - premium
   - motion
 version: 1.0.0
+resources:
+  - SKILL.md
+  - VALIDATION.json

package/.agents/core/skills/state-management/skill.yaml

@@ -2,6 +2,7 @@ name: state-management
 description: Client and server state management standards using Zustand and TanStack Query. Enforces minimal global state, optimistic updates, and clean query invalidation.
 version: 1.0.0
 category: frontend
+type: instruction-only
 requires:
   - react
   - typescript
@@ -20,3 +21,8 @@ triggers:
     - "optimistic"
     - "mutation"
     - "cache"
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

package/.agents/core/skills/subagent-orchestrator/SKILL.md

@@ -44,6 +44,22 @@ Before delegating any subagent task:
 
 ### 3. Context Hand-off Specification
 
+Every subagent dispatch must be backed by an immutable `TaskBrief`:
+
+```ts
+type TaskBrief = Readonly<{
+  taskId: string;
+  baseSha: string;
+  objective: string;
+  writeScope: readonly string[];
+  testCommand: string;
+  expectedResult: string;
+  maxAttempts: number;
+}>;
+```
+
+Create the brief once before dispatch. Agents and retry loops must reuse it without
+changing the base commit, scope, verification command, or acceptance result.
 Every subagent dispatch prompt must contain:
 
 1. **Target Objective**: Single, verifiable deliverable.
@@ -79,6 +95,7 @@ Every subagent dispatch prompt must contain:
 ## Validation Checklist
 
 - [ ] All delegated tasks have disjoint, non-overlapping file sets.
+- [ ] Every worker received an immutable `TaskBrief` tied to the original `baseSha`.
 - [ ] Every subagent prompt has explicit read vs write boundaries.
 - [ ] Subagent results verified individually before merging.
 - [ ] Global regression suite executed across the entire repository after all subagents finish.

package/.agents/core/skills/subagent-orchestrator/skill.yaml

@@ -1,4 +1,5 @@
 name: subagent-orchestrator
+type: runtime
 description: Subagent delegation and parallel coordination skill. Implements task decomposition, context hand-offs, blast-radius boundary isolation, and conflict-free merge synthesis.
 tags:
   - subagents
@@ -6,3 +7,6 @@ tags:
   - multi-agent
   - workflow
 version: 1.0.0
+resources:
+  - SKILL.md
+  - VALIDATION.json

package/.agents/core/skills/system-design/skill.yaml

@@ -1,4 +1,5 @@
 name: system-design
+type: instruction-only
 description: >
   Architecture and system design skill based on donnemartin's System Design Primer.
   Teaches scalable architecture thinking: load balancers, caching, DB partitioning,
@@ -11,3 +12,9 @@ tags:
   - microservices
 version: 1.0.0
 source: https://github.com/donnemartin/system-design-primer
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json
+  - system-design.md

package/.agents/core/skills/testing/skill.yaml

@@ -2,6 +2,7 @@ name: testing
 description: Vitest, React Testing Library, and Playwright testing standards. Enforces TDD/BDD, test pyramid, zero brittle mocks, and complete assertion coverage.
 version: 1.0.0
 category: engineering
+type: instruction-only
 requires:
   - engineering-workflow
   - typescript
@@ -24,3 +25,8 @@ triggers:
     - "mock"
     - "assert"
     - "coverage"
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

package/.agents/core/skills/typescript/skill.yaml

@@ -1,6 +1,7 @@
 id: typescript
 name: TypeScript
 category: frontend
+type: instruction-only
 tags: [frontend, backend, types, static-analysis]
 requires: []
 optional: [zod, prisma]
@@ -8,3 +9,9 @@ conflicts: []
 weight: 9
 documents:
   - typescript.md
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json
+  - typescript.md

package/.agents/core/skills/ui-design/skill.yaml

@@ -1,6 +1,7 @@
 id: ui-design
 name: UI Design
 category: design
+type: instruction-only
 tags: [design, ui, components, design-system, visual]
 requires: []
 optional: [react, tailwind, web-accessibility]
@@ -8,3 +9,9 @@ conflicts: []
 weight: 7
 documents:
   - ui.md
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json
+  - ui.md

package/.agents/core/skills/ui-ux-pro/skill.yaml

@@ -1,4 +1,5 @@
 name: ui-ux-pro
+type: instruction-only
 description: >
   Professional UI/UX design skill with strict anti-pattern enforcement.
   Prevents AI slop design, enforces accessibility standards, semantic
@@ -11,3 +12,8 @@ tags:
   - frontend
 version: 1.0.0
 source: https://github.com/nextlevelbuilder/ui-ux-pro-max-skill
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

package/.agents/core/skills/ux-design/skill.yaml

@@ -1,6 +1,7 @@
 id: ux-design
 name: UX Design
 category: design
+type: instruction-only
 tags: [design, ux, user-flows, usability, information-architecture]
 requires: []
 optional: [ui-design, web-accessibility]
@@ -8,3 +9,9 @@ conflicts: []
 weight: 7
 documents:
   - ux.md
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json
+  - ux.md

package/.agents/core/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/.agents/core/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);
+}