@meyverick/agentic 5.0.2 → 5.1.0

package/skills/create-skill/scripts/{scaffold-skill.mjs → scaffold-skill.ts}

@@ -1,46 +1,64 @@
-#!/usr/bin/env node
+#!/usr/bin/env bun
 /**
- * scaffold-skill.mjs — Create skill directory structure with SKILL.md skeleton
- * Usage: node scaffold-skill.mjs <skill-name> [output-dir]
+ * scaffold-skill.ts — Create skill directory structure with SKILL.md skeleton
+ * Usage: bun scaffold-skill.ts <skill-name> [output-dir]
  * Output: JSON with created path
  */
 
-import { mkdirSync, writeFileSync, existsSync } from 'fs';
-import { join } from 'path';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+interface ScaffoldResult {
+  status: string;
+  path: string;
+  files: string[];
+}
 
 const skillName = process.argv[2];
 const outputDir = process.argv[3] || '.';
 
-if (!skillName) {
-  console.error(JSON.stringify({
-    error: 'Usage: node scaffold-skill.mjs <skill-name> [output-dir]'
-  }));
+if (!skillName || skillName === '-h' || skillName === '--help') {
+  if (skillName === '-h' || skillName === '--help') {
+    console.log('Usage: bun scaffold-skill.ts <skill-name> [output-dir]');
+    process.exit(0);
+  }
+  console.error(
+    JSON.stringify({
+      error: 'Usage: bun scaffold-skill.ts <skill-name> [output-dir]'
+    })
+  );
   process.exit(1);
 }
 
 // Validate skill name format
 if (!/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(skillName)) {
-  console.error(JSON.stringify({
-    error: 'Invalid skill name. Must be lowercase letters, numbers, hyphens only. No leading/trailing hyphens.',
-    name: skillName
-  }));
+  console.error(
+    JSON.stringify({
+      error: 'Invalid skill name. Must be lowercase letters, numbers, hyphens only. No leading/trailing hyphens.',
+      name: skillName
+    })
+  );
   process.exit(1);
 }
 
 if (skillName.length > 64) {
-  console.error(JSON.stringify({
-    error: 'Skill name too long. Maximum 64 characters.',
-    name: skillName,
-    length: skillName.length
-  }));
+  console.error(
+    JSON.stringify({
+      error: 'Skill name too long. Maximum 64 characters.',
+      name: skillName,
+      length: skillName.length
+    })
+  );
   process.exit(1);
 }
 
 if (skillName.includes('--')) {
-  console.error(JSON.stringify({
-    error: 'Skill name contains consecutive hyphens.',
-    name: skillName
-  }));
+  console.error(
+    JSON.stringify({
+      error: 'Skill name contains consecutive hyphens.',
+      name: skillName
+    })
+  );
   process.exit(1);
 }
 
@@ -73,8 +91,7 @@ TODO: List environment-specific facts, common failures, non-obvious behaviors.
 
 writeFileSync(join(skillDir, 'SKILL.md'), skillMd);
 
-// Output JSON
-console.log(JSON.stringify({
+const result: ScaffoldResult = {
   status: 'created',
   path: skillDir,
   files: [
@@ -83,4 +100,7 @@ console.log(JSON.stringify({
     join(skillDir, 'references/'),
     join(skillDir, 'assets/templates/')
   ]
-}));
+};
+
+// Output JSON
+console.log(JSON.stringify(result));

package/skills/create-skill/scripts/validate-routing.ts

@@ -0,0 +1,218 @@
+#!/usr/bin/env bun
+/**
+ * validate-routing.ts — Semantic routing validation for skills
+ * Usage: bun validate-routing.ts <skill-dir>
+ * Output: unified JSON envelope {target, pass, checks:[{id,status,detail}], summary}
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+type CheckStatus = 'PASS' | 'FAIL' | 'WARN' | 'SKIP';
+
+interface CheckEntry {
+  id: string;
+  status: CheckStatus;
+  detail: string;
+}
+
+interface ValidationSummary {
+  total: number;
+  pass: number;
+  fail: number;
+  warn: number;
+  skip: number;
+}
+
+interface ValidationReport {
+  target: string;
+  pass: boolean;
+  checks: CheckEntry[];
+  summary: ValidationSummary;
+}
+
+const skillDir = process.argv[2];
+
+if (!skillDir || skillDir === '-h' || skillDir === '--help') {
+  if (skillDir === '-h' || skillDir === '--help') {
+    console.log('Usage: bun validate-routing.ts <skill-dir>');
+    process.exit(0);
+  }
+  console.error(
+    JSON.stringify({
+      error: 'Usage: bun validate-routing.ts <skill-dir>'
+    })
+  );
+  process.exit(1);
+}
+
+const skillFile = join(skillDir, 'SKILL.md');
+
+if (!existsSync(skillFile)) {
+  const report: ValidationReport = {
+    target: skillDir,
+    pass: false,
+    checks: [{ id: 'routing.skill-file', status: 'FAIL', detail: 'SKILL.md not found' }],
+    summary: { total: 1, pass: 0, fail: 1, warn: 0, skip: 0 }
+  };
+  console.log(JSON.stringify(report));
+  process.exit(1);
+}
+
+const skillMd = readFileSync(skillFile, 'utf-8');
+const checks: CheckEntry[] = [];
+
+function add(id: string, passed: boolean, detail: string): void {
+  checks.push({ id, status: passed ? 'PASS' : 'FAIL', detail });
+}
+
+// Extract frontmatter
+const frontmatterMatch = skillMd.match(/^---\n([\s\S]*?)\n---/);
+const frontmatter = frontmatterMatch ? frontmatterMatch[1] : '';
+
+// Extract body (everything after frontmatter)
+const bodyStart = skillMd.indexOf('---', 3);
+const body = bodyStart !== -1 ? skillMd.slice(bodyStart + 3) : skillMd;
+
+// Extract description
+const descMatch = frontmatter.match(/^description:\s*([\s\S]*?)(?=\n\w+:|\n---)/m);
+const description = descMatch ? descMatch[1].replace(/^>\s*\n?/, '').trim() : '';
+
+// CHECK 1: positive_triggers coverage (min 3 entries)
+const ptMatch = frontmatter.match(/^positive_triggers:\s*\n((?:\s+-\s+.+\n?)*)/m);
+let ptCount = 0;
+if (ptMatch) {
+  const triggers = ptMatch[1].split('\n').filter((l) => l.trim().startsWith('-'));
+  ptCount = triggers.length;
+}
+add(
+  'routing.positive-triggers',
+  ptCount >= 3,
+  `${ptCount} entries found (minimum 3 required) — improves semantic routing accuracy`
+);
+
+// CHECK 2: anti_triggers coverage (min 2 entries)
+const atMatch = frontmatter.match(/^anti_triggers:\s*\n((?:\s+-\s+.+\n?)*)/m);
+let atCount = 0;
+if (atMatch) {
+  const triggers = atMatch[1].split('\n').filter((l) => l.trim().startsWith('-'));
+  atCount = triggers.length;
+}
+add(
+  'routing.anti-triggers',
+  atCount >= 2,
+  `${atCount} entries found (minimum 2 required) — boosts routing precision by 31.8%`
+);
+
+// CHECK 3: Description contains "Use when" phrasing
+const hasUseWhen = /use when/i.test(description);
+add(
+  'routing.use-when',
+  hasUseWhen,
+  hasUseWhen
+    ? 'Found "Use when" phrasing'
+    : 'Missing "Use when" phrasing in description — imperative phrasing helps agents decide activation'
+);
+
+// CHECK 4: Description contains "Do NOT use when" phrasing
+const hasNotUse = /do not use when|don't use when/i.test(description);
+add(
+  'routing.negative-scope',
+  hasNotUse,
+  hasNotUse
+    ? 'Found "Do NOT use when" phrasing'
+    : 'Missing negative scope in description — prevents over-firing on similar-domain queries'
+);
+
+// CHECK 5: Description-body alignment (keywords in description appear in body)
+let alignmentScore = 0;
+let alignmentTotal = 0;
+if (description) {
+  const stopWords = new Set([
+    'the',
+    'and',
+    'for',
+    'with',
+    'this',
+    'that',
+    'when',
+    'not',
+    'use',
+    'from',
+    'are',
+    'was',
+    'have',
+    'has',
+    'will',
+    'can',
+    'should',
+    'does',
+    'its'
+  ]);
+  const words = description
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .split(/\s+/)
+    .filter((w) => w.length > 3 && !stopWords.has(w));
+
+  const uniqueWords = [...new Set(words)];
+  alignmentTotal = Math.min(uniqueWords.length, 10);
+
+  for (const word of uniqueWords.slice(0, 10)) {
+    if (body.toLowerCase().includes(word)) {
+      alignmentScore++;
+    }
+  }
+}
+
+const alignmentRatio = alignmentTotal > 0 ? alignmentScore / alignmentTotal : 0;
+add(
+  'routing.alignment',
+  alignmentRatio >= 0.5,
+  `${alignmentScore}/${alignmentTotal} description keywords found in body (${Math.round(
+    alignmentRatio * 100
+  )}% alignment) — frontmatter-only indexing loses 29-44% recall`
+);
+
+// CHECK 6: Single-responsibility verification
+let singleResponsibility = true;
+let srDetail = 'Single atomic intent detected';
+if (description) {
+  const compoundMarkers = /\b(and also\b|\badditionally\b|\bas well as\b)/i;
+  if (compoundMarkers.test(description)) {
+    singleResponsibility = false;
+    srDetail = 'Compound intent detected. Description contains multiple operations joined by "and also" or "additionally".';
+  }
+
+  const actionVerbs = description.match(
+    /\b(?:create|delete|update|modify|analyze|generate|process|manage|handle|configure|deploy|monitor)\b/gi
+  );
+  if (actionVerbs && new Set(actionVerbs.map((v) => v.toLowerCase())).size > 2) {
+    singleResponsibility = false;
+    srDetail = `Multiple distinct action verbs detected (${[
+      ...new Set(actionVerbs.map((v) => v.toLowerCase()))
+    ].join(', ')}). Consider splitting into separate skills.`;
+  }
+}
+add(
+  'routing.atomic-intent',
+  singleResponsibility,
+  `${srDetail} — multi-domain descriptions cause trigger dilution`
+);
+
+// Unified envelope
+const passCount = checks.filter((c) => c.status === 'PASS').length;
+const report: ValidationReport = {
+  target: skillDir,
+  pass: passCount === checks.length,
+  checks,
+  summary: {
+    total: checks.length,
+    pass: passCount,
+    fail: checks.filter((c) => c.status === 'FAIL').length,
+    warn: checks.filter((c) => c.status === 'WARN').length,
+    skip: checks.filter((c) => c.status === 'SKIP').length
+  }
+};
+
+console.log(JSON.stringify(report));

package/skills/create-skill/scripts/{validate-structure.mjs → validate-structure.ts}

@@ -1,39 +1,71 @@
-#!/usr/bin/env node
+#!/usr/bin/env bun
 /**
- * validate-structure.mjs — Check skill directory structure and SKILL.md compliance
- * Usage: node validate-structure.mjs <skill-dir>
+ * validate-structure.ts — Check skill directory structure and SKILL.md compliance
+ * Usage: bun validate-structure.ts <skill-dir>
  * Output: unified JSON envelope {target, pass, checks:[{id,status,detail}], summary}
  */
 
-import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
-import { join, basename } from 'path';
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join, basename } from 'node:path';
+
+type CheckStatus = 'PASS' | 'FAIL' | 'WARN' | 'SKIP';
+
+interface CheckEntry {
+  id: string;
+  status: CheckStatus;
+  detail: string;
+}
+
+interface ValidationSummary {
+  total: number;
+  pass: number;
+  fail: number;
+  warn: number;
+  skip: number;
+}
+
+interface ValidationReport {
+  target: string;
+  pass: boolean;
+  name?: string;
+  description_length?: number;
+  checks: CheckEntry[];
+  summary: ValidationSummary;
+}
 
 const skillDir = process.argv[2];
 
-if (!skillDir) {
-  console.error(JSON.stringify({
-    error: 'Usage: node validate-structure.mjs <skill-dir>'
-  }));
+if (!skillDir || skillDir === '-h' || skillDir === '--help') {
+  if (skillDir === '-h' || skillDir === '--help') {
+    console.log('Usage: bun validate-structure.ts <skill-dir>');
+    process.exit(0);
+  }
+  console.error(
+    JSON.stringify({
+      error: 'Usage: bun validate-structure.ts <skill-dir>'
+    })
+  );
   process.exit(1);
 }
 
-const checks = [];
+const checks: CheckEntry[] = [];
 
-function add(id, severity, detail) {
+function add(id: string, severity: CheckStatus, detail: string): void {
   checks.push({ id, status: severity, detail });
 }
-const fail = (id, detail) => add(id, 'FAIL', detail);
-const warn = (id, detail) => add(id, 'WARN', detail);
-const pass = (id, detail) => add(id, 'PASS', detail);
+const fail = (id: string, detail: string): void => add(id, 'FAIL', detail);
+const warn = (id: string, detail: string): void => add(id, 'WARN', detail);
+const pass = (id: string, detail: string): void => add(id, 'PASS', detail);
 
 // Check SKILL.md exists
 if (!existsSync(join(skillDir, 'SKILL.md'))) {
-  console.log(JSON.stringify({
+  const report: ValidationReport = {
     target: skillDir,
     pass: false,
     checks: [{ id: 'structure.skill-file', status: 'FAIL', detail: 'SKILL.md not found' }],
     summary: { total: 1, pass: 0, fail: 1, warn: 0, skip: 0 }
-  }));
+  };
+  console.log(JSON.stringify(report));
   process.exit(1);
 }
 
@@ -57,7 +89,10 @@ const name = nameMatch ? nameMatch[1].replace(/"/g, '').trim() : '';
 if (!name) {
   fail('structure.name', "Missing required 'name' field in frontmatter");
 } else if (!/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(name)) {
-  fail('structure.name', `Invalid name format: '${name}'. Must be lowercase letters, numbers, hyphens only. No leading/trailing hyphens.`);
+  fail(
+    'structure.name',
+    `Invalid name format: '${name}'. Must be lowercase letters, numbers, hyphens only. No leading/trailing hyphens.`
+  );
 } else if (name.length > 64) {
   fail('structure.name', `Name too long: ${name.length} chars. Maximum 64 characters.`);
 } else if (name.includes('--')) {
@@ -69,7 +104,10 @@ if (!name) {
 // Check name matches directory
 const dirName = basename(skillDir);
 if (name && name !== dirName) {
-  warn('structure.name-dir-match', `Name '${name}' does not match directory name '${dirName}'. Pi allows this, but the Agent Skills standard requires matching.`);
+  warn(
+    'structure.name-dir-match',
+    `Name '${name}' does not match directory name '${dirName}'. Pi allows this, but the Agent Skills standard requires matching.`
+  );
 }
 
 // Check description field (handles both single-line and multi-line YAML)
@@ -113,40 +151,58 @@ if (desc && !/do not use when|don't use when/i.test(desc)) {
 if (desc) {
   const compoundMarkers = /\b(and also\b|\badditionally\b|\bas well as\b)/i;
   if (compoundMarkers.test(desc)) {
-    warn('structure.compound-intent', "Description may contain compound intent (multiple operations). Consider splitting into separate skills.");
+    warn(
+      'structure.compound-intent',
+      'Description may contain compound intent (multiple operations). Consider splitting into separate skills.'
+    );
   }
 }
 
 // positive_triggers array (min 3 entries)
 const ptMatch = frontmatter.match(/^positive_triggers:\s*\n((?:\s+-\s+.+\n?)*)/m);
 if (ptMatch) {
-  const triggers = ptMatch[1].split('\n').filter(l => l.trim().startsWith('-'));
+  const triggers = ptMatch[1].split('\n').filter((l) => l.trim().startsWith('-'));
   if (triggers.length < 3) {
-    warn('structure.positive-triggers', `positive_triggers has ${triggers.length} entries. Minimum 3 recommended for routing accuracy.`);
+    warn(
+      'structure.positive-triggers',
+      `positive_triggers has ${triggers.length} entries. Minimum 3 recommended for routing accuracy.`
+    );
   } else {
     pass('structure.positive-triggers', `${triggers.length} entries`);
   }
 } else {
-  warn('structure.positive-triggers', "Missing 'positive_triggers' array in frontmatter. Recommended minimum 3 entries for semantic routing.");
+  warn(
+    'structure.positive-triggers',
+    "Missing 'positive_triggers' array in frontmatter. Recommended minimum 3 entries for semantic routing."
+  );
 }
 
 // anti_triggers array (min 2 entries)
 const atMatch = frontmatter.match(/^anti_triggers:\s*\n((?:\s+-\s+.+\n?)*)/m);
 if (atMatch) {
-  const triggers = atMatch[1].split('\n').filter(l => l.trim().startsWith('-'));
+  const triggers = atMatch[1].split('\n').filter((l) => l.trim().startsWith('-'));
   if (triggers.length < 2) {
-    warn('structure.anti-triggers', `anti_triggers has ${triggers.length} entries. Minimum 2 recommended for precision (+31.8%).`);
+    warn(
+      'structure.anti-triggers',
+      `anti_triggers has ${triggers.length} entries. Minimum 2 recommended for precision (+31.8%).`
+    );
   } else {
     pass('structure.anti-triggers', `${triggers.length} entries`);
   }
 } else {
-  warn('structure.anti-triggers', "Missing 'anti_triggers' array in frontmatter. Anti-triggers boost routing precision by 31.8%.");
+  warn(
+    'structure.anti-triggers',
+    "Missing 'anti_triggers' array in frontmatter. Anti-triggers boost routing precision by 31.8%."
+  );
 }
 
-// Runtime contract when scripts exist
+// Runtime contract when scripts exist (.ts, .mjs, .js, .py, .sh)
 const scriptsDir = join(skillDir, 'scripts');
+const SCRIPT_EXTENSIONS = ['.ts', '.mjs', '.js', '.py', '.sh'];
 if (existsSync(scriptsDir)) {
-  const scriptFiles = readdirSync(scriptsDir).filter(f => f.endsWith('.mjs') || f.endsWith('.js') || f.endsWith('.py') || f.endsWith('.sh'));
+  const scriptFiles = readdirSync(scriptsDir).filter((f) =>
+    SCRIPT_EXTENSIONS.some((ext) => f.endsWith(ext))
+  );
   if (scriptFiles.length > 0) {
     if (!frontmatter.includes('runtime:') && !frontmatter.includes('timeout_seconds')) {
       warn('structure.runtime-contract', 'Scripts exist but no runtime contract declared in frontmatter (runtime:, timeout_seconds:)');
@@ -158,7 +214,9 @@ if (existsSync(scriptsDir)) {
 
 // Hardcoded absolute paths in script files
 if (existsSync(scriptsDir)) {
-  const scriptFiles = readdirSync(scriptsDir).filter(f => f.endsWith('.mjs') || f.endsWith('.js') || f.endsWith('.py') || f.endsWith('.sh'));
+  const scriptFiles = readdirSync(scriptsDir).filter((f) =>
+    SCRIPT_EXTENSIONS.some((ext) => f.endsWith(ext))
+  );
   for (const file of scriptFiles) {
     const content = readFileSync(join(scriptsDir, file), 'utf-8');
     const absPathPatterns = [
@@ -177,7 +235,7 @@ if (existsSync(scriptsDir)) {
       fail(`structure.portability.${file}`, `Harness-specific directory reference detected in scripts/${file}. Scripts must be portable across harnesses.`);
     }
   }
-  if (!checks.some(c => c.id.startsWith('structure.portability.') && c.status === 'FAIL') && scriptFiles.length > 0) {
+  if (!checks.some((c) => c.id.startsWith('structure.portability.') && c.status === 'FAIL') && scriptFiles.length > 0) {
     pass('structure.portability', 'No hardcoded/harness-specific paths in scripts');
   }
 }
@@ -199,15 +257,15 @@ for (const line of lines) {
     const ref = refMatch[1];
     if (ref && !ref.startsWith('http') && !ref.startsWith('#') && !ref.startsWith('mailto:')) {
       if (!existsSync(join(skillDir, ref))) {
-        warn(`structure.reference`, `File reference not found: ${ref}`);
+        warn('structure.reference', `File reference not found: ${ref}`);
       }
     }
   }
 }
 
 // Unified envelope
-const fails = checks.filter(c => c.status === 'FAIL').length;
-console.log(JSON.stringify({
+const fails = checks.filter((c) => c.status === 'FAIL').length;
+const report: ValidationReport = {
   target: skillDir,
   pass: fails === 0,
   name,
@@ -215,9 +273,12 @@ console.log(JSON.stringify({
   checks,
   summary: {
     total: checks.length,
-    pass: checks.filter(c => c.status === 'PASS').length,
+    pass: checks.filter((c) => c.status === 'PASS').length,
     fail: fails,
-    warn: checks.filter(c => c.status === 'WARN').length,
-    skip: checks.filter(c => c.status === 'SKIP').length
+    warn: checks.filter((c) => c.status === 'WARN').length,
+    skip: checks.filter((c) => c.status === 'SKIP').length
   }
-}));
+};
+
+console.log(JSON.stringify(report));
+process.exit(fails > 0 ? 1 : 0);

package/skills/okf-docs/SKILL.md

@@ -67,7 +67,7 @@ Set `status: draft` on creation. Flip to `stable` after human review (`verified:
 ### 5. Validate Before Delivery
 
 ```bash
-bun scripts/validate-frontmatter.mjs <document.md>
+bun scripts/validate-frontmatter.ts <document.md>
 ```
 
 Envelope must read `pass: true`. Fix named FAIL entries; re-run until clean.

package/skills/okf-docs/evals/evals.json

@@ -4,7 +4,7 @@
     {
       "id": 1,
       "prompt": "Write an ADR documenting our decision to adopt PostgreSQL as the central datastore.",
-      "expected_output": "Skill activates; authored document carries OKF v0.2 frontmatter (type: Architecture Decision Record, generated actor-convention provenance, sources list) and passes scripts/validate-frontmatter.mjs before delivery.",
+      "expected_output": "Skill activates; authored document carries OKF v0.2 frontmatter (type: Architecture Decision Record, generated actor-convention provenance, sources list) and passes scripts/validate-frontmatter.ts before delivery.",
       "files": [],
       "assertions": [
         "Frontmatter contains type + generated.by/at in actor convention",
@@ -25,7 +25,7 @@
     {
       "id": 3,
       "prompt": "Add proper frontmatter to this legacy module doc so it passes validation.",
-      "expected_output": "Agent applies OKF v0.2 frontmatter (type per intent, generated provenance, status lifecycle), runs validate-frontmatter.mjs, iterates until pass:true, and leaves body content unaltered beyond attribution footnotes if claims need sourcing.",
+      "expected_output": "Agent applies OKF v0.2 frontmatter (type per intent, generated provenance, status lifecycle), runs validate-frontmatter.ts, iterates until pass:true, and leaves body content unaltered beyond attribution footnotes if claims need sourcing.",
       "files": [],
       "assertions": [
         "Validator run on the updated document",