agent-skill-kit 3.9.135

package/.agent/scripts/skill-audit.ts

@@ -0,0 +1,255 @@
+// @ts-nocheck
+/**
+ * Skill Audit — PikaKit
+ * Validates ALL skills against SKILL_DESIGN_GUIDE.md checklist.
+ *
+ * Usage:
+ *   npx tsx skill-audit.ts                    # Audit all skills
+ *   npx tsx skill-audit.ts react-pro          # Audit specific skill
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const SKILLS_DIR = path.resolve(__dirname, '../skills');
+
+const args = process.argv.slice(2);
+const targetSkill = args.find(a => !a.startsWith('--'));
+
+interface CheckResult {
+  name: string;
+  passed: number;
+  total: number;
+  issues: string[];
+}
+
+function auditSkill(skillName: string): CheckResult {
+  const skillDir = path.join(SKILLS_DIR, skillName);
+  const issues: string[] = [];
+  let checks = 0;
+  let passed = 0;
+
+  // === CHECK 1: SKILL.md exists ===
+  checks++;
+  const skillMdPath = path.join(skillDir, 'SKILL.md');
+  if (fs.existsSync(skillMdPath)) {
+    passed++;
+  } else {
+    issues.push('Missing SKILL.md');
+    return { name: skillName, passed, total: checks, issues };
+  }
+
+  let content = fs.readFileSync(skillMdPath, 'utf-8');
+  // Strip UTF-8 BOM if present
+  if (content.charCodeAt(0) === 0xFEFF) content = content.slice(1);
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+
+  // === CHECK 2: YAML frontmatter exists ===
+  checks++;
+  if (fmMatch) {
+    passed++;
+  } else {
+    issues.push('Missing YAML frontmatter');
+    return { name: skillName, passed, total: checks, issues };
+  }
+
+  const fm = fmMatch[1];
+
+  // === CHECK 3: name field ===
+  checks++;
+  if (fm.match(/^name:\s*.+/m)) {
+    passed++;
+  } else {
+    issues.push('Missing `name` in frontmatter');
+  }
+
+  // === CHECK 4: description field ===
+  checks++;
+  const hasDesc = fm.match(/description:\s*>-/) || fm.match(/description:\s*.+/);
+  if (hasDesc) {
+    passed++;
+  } else {
+    issues.push('Missing `description` in frontmatter');
+  }
+
+  // === CHECK 5: Description has WHAT + WHEN + NOT FOR ===
+  checks++;
+  let desc = '';
+  const multiDesc = fm.match(/description:\s*>-\s*\r?\n((?:\s+.*\r?\n)*)/);
+  if (multiDesc) {
+    desc = multiDesc[1].trim();
+  } else {
+    const singleDesc = fm.match(/description:\s*(.+)/);
+    if (singleDesc) desc = singleDesc[1].trim();
+  }
+
+  const hasTrigger = /Use when|Use for|Use before|Use at|Triggers on/i.test(desc);
+  const hasNegative = /NOT for/i.test(desc);
+  if (hasTrigger && hasNegative) {
+    passed++;
+  } else {
+    if (!hasTrigger) issues.push('Description missing trigger phrase ("Use when/for/before")');
+    if (!hasNegative) issues.push('Description missing negative trigger ("NOT for")');
+  }
+
+  // === CHECK 6: Description length <= 1024 chars ===
+  checks++;
+  if (desc.length <= 1024) {
+    passed++;
+  } else {
+    issues.push(`Description too long (${desc.length} > 1024 chars)`);
+  }
+
+  // === CHECK 7: metadata block ===
+  checks++;
+  if (fm.match(/metadata:/)) {
+    passed++;
+  } else {
+    issues.push('Missing `metadata` block');
+  }
+
+  // === CHECK 8: metadata.triggers ===
+  checks++;
+  if (fm.match(/triggers:/)) {
+    passed++;
+  } else {
+    issues.push('Missing `metadata.triggers`');
+  }
+
+  // === CHECK 9: metadata.coordinates_with ===
+  checks++;
+  if (fm.match(/coordinates_with:/)) {
+    passed++;
+  } else {
+    issues.push('Missing `metadata.coordinates_with`');
+  }
+
+  // === CHECK 10: metadata.version ===
+  checks++;
+  if (fm.match(/version:/)) {
+    passed++;
+  } else {
+    issues.push('Missing `metadata.version`');
+  }
+
+  // Determine skill type
+  const rulesDir = path.join(skillDir, 'rules');
+  const hasRules = fs.existsSync(rulesDir);
+  const ruleFiles = hasRules
+    ? fs.readdirSync(rulesDir).filter(f => f.endsWith('.md') && !f.startsWith('_'))
+    : [];
+  const isTypeA = hasRules && ruleFiles.length > 0;
+
+  if (isTypeA) {
+    // === CHECK 11: AGENTS.md for Type A ===
+    checks++;
+    if (fs.existsSync(path.join(skillDir, 'AGENTS.md'))) {
+      passed++;
+    } else {
+      issues.push('Type A skill missing AGENTS.md');
+    }
+
+    // === CHECK 12: _sections.md ===
+    checks++;
+    if (fs.existsSync(path.join(rulesDir, '_sections.md'))) {
+      passed++;
+    } else {
+      issues.push('Missing rules/_sections.md');
+    }
+
+    // === CHECK 13: _template.md ===
+    checks++;
+    if (fs.existsSync(path.join(rulesDir, '_template.md'))) {
+      passed++;
+    } else {
+      issues.push('Missing rules/_template.md');
+    }
+
+    // === CHECK 14: Rule files have YAML frontmatter ===
+    checks++;
+    let allRulesHaveFm = true;
+    for (const rf of ruleFiles) {
+      let rc = fs.readFileSync(path.join(rulesDir, rf), 'utf-8');
+      // Strip UTF-8 BOM if present
+      if (rc.charCodeAt(0) === 0xFEFF) rc = rc.slice(1);
+      if (!rc.match(/^---/)) {
+        allRulesHaveFm = false;
+        issues.push(`Rule ${rf} missing YAML frontmatter`);
+      }
+    }
+    if (allRulesHaveFm) passed++;
+  }
+
+  // === CHECK 15: Body has "When to Apply" or "When to Use" section ===
+  checks++;
+  if (content.match(/## When to (Apply|Use)|## Protocol|## Routing Table|## Trigger Words/)) {
+    passed++;
+  } else {
+    issues.push('Missing "When to Apply/Use" section in body');
+  }
+
+  // === CHECK 16: Body has "System Boundaries" section ===
+  checks++;
+  if (content.match(/## System Boundaries|## Scope|## Integration/)) {
+    passed++;
+  } else {
+    issues.push('Missing "System Boundaries/Scope" section in body');
+  }
+
+  return { name: skillName, passed, total: checks, issues };
+}
+
+// Get skills to audit
+let skills: string[];
+if (targetSkill) {
+  skills = [targetSkill];
+} else {
+  skills = fs.readdirSync(SKILLS_DIR, { withFileTypes: true })
+    .filter(d => d.isDirectory())
+    .map(d => d.name)
+    .sort();
+}
+
+console.log(`\n🔍 PikaKit Skill Audit — SKILL_DESIGN_GUIDE.md Compliance\n`);
+console.log(`Auditing ${skills.length} skills...\n`);
+
+let totalPass = 0;
+let totalFail = 0;
+let totalWarn = 0;
+
+const results: CheckResult[] = [];
+
+for (const skill of skills) {
+  const result = auditSkill(skill);
+  results.push(result);
+
+  const pct = Math.round((result.passed / result.total) * 100);
+  const icon = pct === 100 ? '✅' : pct >= 80 ? '⚠️' : '❌';
+
+  if (pct === 100) totalPass++;
+  else if (pct >= 80) totalWarn++;
+  else totalFail++;
+
+  if (result.issues.length > 0) {
+    console.log(`${icon} ${result.name}: ${result.passed}/${result.total} checks (${pct}%)`);
+    for (const issue of result.issues) {
+      console.log(`   ⤷ ${issue}`);
+    }
+  } else {
+    console.log(`${icon} ${result.name}: ${result.passed}/${result.total} checks (${pct}%)`);
+  }
+}
+
+console.log(`\n${'─'.repeat(60)}`);
+console.log(`📊 Summary: ${totalPass} pass | ${totalWarn} warn | ${totalFail} fail | ${skills.length} total`);
+
+if (totalFail === 0 && totalWarn === 0) {
+  console.log(`\n🎉 All skills pass SKILL_DESIGN_GUIDE compliance!`);
+} else {
+  console.log(`\n⚠️ ${totalWarn + totalFail} skill(s) need attention.`);
+}
+
+console.log('');

package/.agent/scripts/sync_workflows.ts

@@ -0,0 +1,54 @@
+// @ts-nocheck
+/**
+ * Sync Workflows — PikaKit
+ * Injects missing YAML fields, Auto-Learned sections, and Rollback paths.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const dir = 'C:/Users/sofma/Desktop/agent-skill-kit/.agent/workflows';
+const files = fs.readdirSync(dir).filter((f: string) => f.endsWith('.md'));
+
+for (const f of files) {
+  let txt = fs.readFileSync(path.join(dir, f), 'utf8');
+  let changed = false;
+
+  // 1. YAML inject skills and agents
+  if (!/^skills:/m.test(txt)) {
+    const skillsMatch = txt.match(/SKILLS\s*\|\s*`([^`]+)`/g);
+    const skills = new Set<string>();
+    if (skillsMatch) {
+      skillsMatch.forEach((m: string) => {
+        const parts = m.split('|')[1].replace(/`/g, '').split(',').map((s: string) => s.trim());
+        parts.forEach((p: string) => skills.add(p));
+      });
+    }
+    const skillsStr = skills.size > 0 ? Array.from(skills).join(', ') : 'project-planner';
+    txt = txt.replace(/^(---[\s\S]*?)(---)$/m, `$1skills: [${skillsStr}]\nagents: [orchestrator, assessor, recovery]\n$2`);
+    changed = true;
+  }
+
+  // 2. Auto-Learned pattern (Phase 0)
+  if (!/auto-learned|Auto-Learned/i.test(txt)) {
+    txt = txt.replace(
+      /## 🔴 MANDATORY:([^]*?)(### Phase 1)/,
+      `## 🔴 MANDATORY:$1### Phase 0: Pre-flight & Auto-Learned Context\n\n> **Rule 0.5-K:** Auto-learned pattern check.\n\n1. Read \`.agent/skills/auto-learned/patterns/\` for past failures before proceeding.\n2. Trigger \`recovery\` agent to run Checkpoint (\`git commit -m "chore(checkpoint): pre-${f.replace('.md', '')}"\`).\n\n$2`
+    );
+    changed = true;
+  }
+
+  // 3. Rollback section before Output Format
+  if (!/Rollback|recovery/i.test(txt) && !/Rollback Path/i.test(txt)) {
+    txt = txt.replace(
+      /## Output Format/,
+      `## 🔙 Rollback Path\n\nIf the Exit Gates fail and cannot be resolved automatically:\n1. Restore to pre-workflow checkpoint (\`git checkout -- .\`).\n2. Log failure via \`learner\` meta-agent.\n\n## Output Format`
+    );
+    changed = true;
+  }
+
+  if (changed) {
+    fs.writeFileSync(path.join(dir, f), txt, 'utf8');
+    console.log(`Patched ${f}`);
+  }
+}

package/.agent/scripts/utils/colors.ts

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * ANSI Color Utilities - PikaKit
+ * ======================================
+ * Provides terminal color formatting for output.
+ */
+
+export const colors = {
+    header: '\x1b[95m',
+    blue: '\x1b[94m',
+    cyan: '\x1b[96m',
+    green: '\x1b[92m',
+    yellow: '\x1b[93m',
+    red: '\x1b[91m',
+    reset: '\x1b[0m',
+    bold: '\x1b[1m'
+} as const;
+
+export type ColorKey = keyof typeof colors;
+
+/**
+ * Print header with bold cyan styling
+ */
+export function printHeader(text: string): void {
+    const width = 70;
+    const separator = '='.repeat(width);
+    console.log(`\n${colors.bold}${colors.cyan}${separator}${colors.reset}`);
+    console.log(`${colors.bold}${colors.cyan}${text.padStart((width + text.length) / 2).padEnd(width)}${colors.reset}`);
+    console.log(`${colors.bold}${colors.cyan}${separator}${colors.reset}\n`);
+}
+
+/**
+ * Print step indicator (in progress)
+ */
+export function printStep(text: string): void {
+    console.log(`${colors.bold}${colors.blue}🔄 ${text}${colors.reset}`);
+}
+
+/**
+ * Print success message
+ */
+export function printSuccess(text: string): void {
+    console.log(`${colors.green}✅ ${text}${colors.reset}`);
+}
+
+/**
+ * Print warning message
+ */
+export function printWarning(text: string): void {
+    console.log(`${colors.yellow}⚠️  ${text}${colors.reset}`);
+}
+
+/**
+ * Print error message
+ */
+export function printError(text: string): void {
+    console.log(`${colors.red}❌ ${text}${colors.reset}`);
+}

package/.agent/scripts/utils/process-manager.ts

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * Process Manager - PikaKit
+ * ==================================
+ * Cross-platform process management (PID files, process detection, termination)
+ */
+
+import { readFile, writeFile, unlink } from 'fs/promises';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+
+/**
+ * Save PID to file
+ */
+export async function savePid(pidFile: string, pid: number): Promise<void> {
+    await writeFile(pidFile, pid.toString(), 'utf-8');
+}
+
+/**
+ * Load PID from file
+ */
+export async function loadPid(pidFile: string): Promise<number | null> {
+    try {
+        const content = await readFile(pidFile, 'utf-8');
+        const pid = parseInt(content.trim(), 10);
+        return isNaN(pid) ? null : pid;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Delete PID file
+ */
+export async function deletePidFile(pidFile: string): Promise<void> {
+    try {
+        await unlink(pidFile);
+    } catch {
+        // Ignore if file doesn't exist
+    }
+}
+
+/**
+ * Check if process is running
+ */
+export function isRunning(pid: number): boolean {
+    try {
+        // Sending signal 0 checks existence without killing
+        process.kill(pid, 0);
+        return true;
+    } catch (err: unknown) {
+        // ESRCH = No such process
+        return (err as NodeJS.ErrnoException).code !== 'ESRCH';
+    }
+}
+
+/**
+ * Kill process with signal
+ */
+export async function killProcess(pid: number, signal: NodeJS.Signals = 'SIGTERM'): Promise<void> {
+    return new Promise<void>((resolvePromise) => {
+        try {
+            if (!isRunning(pid)) {
+                resolvePromise();
+                return;
+            }
+
+            process.kill(pid, signal);
+
+            // Wait for process to die
+            const checkInterval = setInterval(() => {
+                if (!isRunning(pid)) {
+                    clearInterval(checkInterval);
+                    resolvePromise();
+                }
+            }, 100);
+
+            // Timeout after 5 seconds, force kill
+            setTimeout(() => {
+                clearInterval(checkInterval);
+                try {
+                    if (isRunning(pid)) {
+                        process.kill(pid, 'SIGKILL');
+                    }
+                } catch {
+                    // Process already dead
+                }
+                resolvePromise();
+            }, 5000);
+
+        } catch (err: unknown) {
+            if ((err as NodeJS.ErrnoException).code === 'ESRCH') {
+                // Process already dead
+                resolvePromise();
+            } else {
+                // Still resolve — best effort
+                resolvePromise();
+            }
+        }
+    });
+}
+
+/**
+ * Kill process tree using platform-specific commands
+ */
+export async function killProcessTree(pid: number): Promise<void> {
+    if (process.platform === 'win32') {
+        // Windows: Use taskkill with /T (tree) flag
+        try {
+            await execAsync(`taskkill /F /T /PID ${pid}`);
+        } catch {
+            // Ignore errors (process might already be dead)
+        }
+    } else {
+        // Unix: Kill process group
+        try {
+            process.kill(-pid, 'SIGTERM');
+
+            // Wait 2s then SIGKILL if still alive
+            await new Promise<void>(resolve => setTimeout(resolve, 2000));
+
+            if (isRunning(pid)) {
+                process.kill(-pid, 'SIGKILL');
+            }
+        } catch {
+            // Ignore errors
+        }
+    }
+}

package/.agent/scripts/utils/reporter.ts

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * Reporter - PikaKit
+ * ===========================
+ * Result formatting utilities (JSON, summary tables)
+ */
+
+import { colors } from './colors.ts';
+
+export interface CheckResult {
+    name: string;
+    passed: boolean;
+    skipped?: boolean;
+    duration?: number;
+    output?: string;
+    error?: string;
+    category?: string;
+}
+
+interface ReportOutput {
+    version: string;
+    timestamp: string;
+    project_path: string;
+    url: string | null;
+    summary: {
+        total: number;
+        passed: number;
+        failed: number;
+        skipped: number;
+        duration: number;
+    };
+    results: Array<{
+        name: string;
+        passed: boolean;
+        skipped: boolean;
+        duration: number;
+        output: string;
+        error: string;
+    }>;
+}
+
+/**
+ * Format validation results as JSON
+ */
+export function formatJsonOutput(
+    results: CheckResult[],
+    projectPath: string,
+    url: string | null,
+    startTime: Date
+): string {
+    const totalDuration = (Date.now() - startTime.getTime()) / 1000;
+
+    const output: ReportOutput = {
+        version: '3.2.0',
+        timestamp: new Date().toISOString(),
+        project_path: projectPath,
+        url: url || null,
+        summary: {
+            total: results.length,
+            passed: results.filter(r => r.passed && !r.skipped).length,
+            failed: results.filter(r => !r.passed && !r.skipped).length,
+            skipped: results.filter(r => r.skipped).length,
+            duration: Math.round(totalDuration * 100) / 100
+        },
+        results: results.map(r => ({
+            name: r.name,
+            passed: r.passed,
+            skipped: r.skipped || false,
+            duration: r.duration || 0,
+            output: r.output || '',
+            error: r.error || ''
+        }))
+    };
+
+    return JSON.stringify(output, null, 2);
+}
+
+/**
+ * Print summary of validation results
+ */
+export function printSummary(results: CheckResult[]): boolean {
+    console.log(`\n${colors.bold}${colors.cyan}${'='.repeat(60)}${colors.reset}`);
+    console.log(`${colors.bold}${colors.cyan}${'📊 CHECKLIST SUMMARY'.padStart(38)}${colors.reset}`);
+    console.log(`${colors.bold}${colors.cyan}${'='.repeat(60)}${colors.reset}\n`);
+
+    const passedCount = results.filter(r => r.passed && !r.skipped).length;
+    const failedCount = results.filter(r => !r.passed && !r.skipped).length;
+    const skippedCount = results.filter(r => r.skipped).length;
+
+    console.log(`Total Checks: ${results.length}`);
+    console.log(`${colors.green}✅ Passed: ${passedCount}${colors.reset}`);
+    console.log(`${colors.red}❌ Failed: ${failedCount}${colors.reset}`);
+    console.log(`${colors.yellow}⏭️  Skipped: ${skippedCount}${colors.reset}\n`);
+
+    // Detailed results
+    for (const r of results) {
+        let status: string;
+        if (r.skipped) {
+            status = `${colors.yellow}⏭️ ${colors.reset}`;
+        } else if (r.passed) {
+            status = `${colors.green}✅${colors.reset}`;
+        } else {
+            status = `${colors.red}❌${colors.reset}`;
+        }
+        console.log(`${status} ${r.name}`);
+    }
+
+    console.log();
+
+    if (failedCount > 0) {
+        console.log(`${colors.red}❌ ${failedCount} check(s) FAILED - Please fix before proceeding${colors.reset}`);
+        return false;
+    } else {
+        console.log(`${colors.green}✅ All checks PASSED ✨${colors.reset}`);
+        return true;
+    }
+}
+
+/**
+ * Print comprehensive final report with category breakdown
+ */
+export function printFinalReport(results: CheckResult[], startTime: Date): boolean {
+    const totalDuration = (Date.now() - startTime.getTime()) / 1000;
+
+    console.log(`\n${colors.bold}${colors.cyan}${'='.repeat(70)}${colors.reset}`);
+    console.log(`${colors.bold}${colors.cyan}${'📊 FULL VERIFICATION REPORT'.padStart(48)}${colors.reset}`);
+    console.log(`${colors.bold}${colors.cyan}${'='.repeat(70)}${colors.reset}\n`);
+
+    // Statistics
+    const total = results.length;
+    const passed = results.filter(r => r.passed && !r.skipped).length;
+    const failed = results.filter(r => !r.passed && !r.skipped).length;
+    const skipped = results.filter(r => r.skipped).length;
+
+    console.log(`Total Duration: ${totalDuration.toFixed(1)}s`);
+    console.log(`Total Checks: ${total}`);
+    console.log(`${colors.green}✅ Passed: ${passed}${colors.reset}`);
+    console.log(`${colors.red}❌ Failed: ${failed}${colors.reset}`);
+    console.log(`${colors.yellow}⏭️  Skipped: ${skipped}${colors.reset}\n`);
+
+    // Category breakdown
+    console.log(`${colors.bold}Results by Category:${colors.reset}`);
+    let currentCategory: string | null = null;
+
+    for (const r of results) {
+        // Print category header if changed
+        if (r.category && r.category !== currentCategory) {
+            currentCategory = r.category;
+            console.log(`\n${colors.bold}${colors.cyan}${currentCategory}:${colors.reset}`);
+        }
+
+        // Print result
+        let status: string;
+        if (r.skipped) {
+            status = `${colors.yellow}⏭️ ${colors.reset}`;
+        } else if (r.passed) {
+            status = `${colors.green}✅${colors.reset}`;
+        } else {
+            status = `${colors.red}❌${colors.reset}`;
+        }
+
+        const durationStr = !r.skipped && r.duration ? ` (${r.duration.toFixed(1)}s)` : '';
+        console.log(`  ${status} ${r.name}${durationStr}`);
+    }
+
+    console.log();
+
+    // Failed checks detail
+    if (failed > 0) {
+        console.log(`${colors.bold}${colors.red}❌ FAILED CHECKS:${colors.reset}`);
+        for (const r of results) {
+            if (!r.passed && !r.skipped) {
+                console.log(`\n${colors.red}✗ ${r.name}${colors.reset}`);
+                if (r.error) {
+                    const errorPreview = r.error.substring(0, 200);
+                    console.log(`  Error: ${errorPreview}`);
+                }
+            }
+        }
+        console.log();
+    }
+
+    // Final verdict
+    if (failed > 0) {
+        console.log(`${colors.red}❌ VERIFICATION FAILED - ${failed} check(s) need attention${colors.reset}`);
+        console.log(`\n${colors.yellow}💡 Tip: Fix critical (security, lint) issues first${colors.reset}\n`);
+        return false;
+    } else {
+        console.log(`${colors.green}✨ ALL CHECKS PASSED - Ready for deployment! ✨${colors.reset}\n`);
+        return true;
+    }
+}