cognitive-core 0.0.2 → 0.1.2

package/src/memory/skill-exporter.ts

@@ -0,0 +1,357 @@
+/**
+ * Skill Exporter - Compile playbooks into the Open Agent Skills format
+ *
+ * Playbooks are the source of truth (rich, evolving, learned from experience).
+ * SKILL.md files are the compiled distribution artifact — portable across 25+
+ * agent platforms (Claude Code, Codex CLI, GitHub Copilot, Cursor, etc.).
+ *
+ * The export preserves playbook-specific knowledge (anti-patterns, refinements,
+ * verification) in the Markdown body, while mapping core fields to the standard
+ * YAML frontmatter schema.
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import type { Playbook } from '../types/index.js';
+import { getPlaybookSuccessRate, hasReliableStats } from '../types/index.js';
+import type { PlaybookLibrary } from './playbook.js';
+
+/**
+ * Options for filtering which playbooks to export
+ */
+export interface SkillExportFilter {
+  /** Minimum confidence to include (default: 0.5) */
+  minConfidence?: number;
+  /** Only include playbooks with at least this many total uses */
+  minUses?: number;
+  /** Only include playbooks from these domains */
+  domains?: string[];
+  /** Only include playbooks with these origins */
+  origins?: Array<'extracted' | 'curated' | 'imported' | 'manual'>;
+}
+
+/**
+ * Options for how the SKILL.md is generated
+ */
+export interface SkillExportOptions {
+  /** Include evolution stats (confidence, success rate) in metadata */
+  includeStats?: boolean;
+  /** Include refinements section in the body */
+  includeRefinements?: boolean;
+  /** Include anti-patterns as a "When NOT to use" section */
+  includeAntiPatterns?: boolean;
+  /** Include verification section */
+  includeVerification?: boolean;
+  /** Custom metadata fields to add to frontmatter */
+  extraMetadata?: Record<string, string>;
+}
+
+const DEFAULT_OPTIONS: Required<SkillExportOptions> = {
+  includeStats: true,
+  includeRefinements: true,
+  includeAntiPatterns: true,
+  includeVerification: true,
+  extraMetadata: {},
+};
+
+/**
+ * Result of an export operation
+ */
+export interface SkillExportResult {
+  exported: number;
+  skipped: number;
+  errors: Array<{ playbook: string; error: string }>;
+  skills: ExportedSkill[];
+}
+
+/**
+ * A single exported skill (before writing to disk)
+ */
+export interface ExportedSkill {
+  name: string;
+  dirName: string;
+  content: string;
+  sourcePlaybookId: string;
+}
+
+/**
+ * Compile a single playbook into SKILL.md content
+ */
+export function compilePlaybookToSkill(
+  playbook: Playbook,
+  options?: SkillExportOptions
+): string {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const sections: string[] = [];
+
+  // === YAML Frontmatter ===
+  sections.push('---');
+  sections.push(`name: ${playbook.name}`);
+  sections.push(`description: >-`);
+  sections.push(`  ${buildDescription(playbook)}`);
+
+  // Metadata block
+  const metadata: Record<string, string> = {
+    version: playbook.evolution.version,
+    complexity: playbook.complexity,
+    ...opts.extraMetadata,
+  };
+
+  if (playbook.provenance?.origin) {
+    metadata['origin'] = playbook.provenance.origin;
+  }
+  if (playbook.provenance?.curatedBy) {
+    metadata['author'] = playbook.provenance.curatedBy;
+  }
+  if (opts.includeStats) {
+    metadata['confidence'] = playbook.confidence.toFixed(2);
+    if (hasReliableStats(playbook)) {
+      metadata['success-rate'] = getPlaybookSuccessRate(playbook).toFixed(2);
+    }
+  }
+
+  sections.push('metadata:');
+  for (const [key, value] of Object.entries(metadata)) {
+    sections.push(`  ${key}: "${value}"`);
+  }
+
+  // Compatibility — express domains as environment context
+  if (playbook.applicability.domains.length > 0) {
+    sections.push(
+      `compatibility: Applicable to ${playbook.applicability.domains.join(', ')} projects`
+    );
+  }
+
+  sections.push('---');
+  sections.push('');
+
+  // === Markdown Body ===
+
+  // Strategy (the core guidance)
+  sections.push(`## Strategy`);
+  sections.push('');
+  sections.push(playbook.guidance.strategy);
+  sections.push('');
+
+  // Tactics
+  if (playbook.guidance.tactics.length > 0) {
+    sections.push('## Tactics');
+    sections.push('');
+    for (const tactic of playbook.guidance.tactics) {
+      sections.push(`- ${tactic}`);
+    }
+    sections.push('');
+  }
+
+  // Concrete steps
+  if (playbook.guidance.steps && playbook.guidance.steps.length > 0) {
+    sections.push('## Steps');
+    sections.push('');
+    for (let i = 0; i < playbook.guidance.steps.length; i++) {
+      sections.push(`${i + 1}. ${playbook.guidance.steps[i]}`);
+    }
+    sections.push('');
+  }
+
+  // Code example
+  if (playbook.guidance.codeExample) {
+    sections.push('## Example');
+    sections.push('');
+    sections.push('```');
+    sections.push(playbook.guidance.codeExample);
+    sections.push('```');
+    sections.push('');
+  }
+
+  // Anti-patterns — "when NOT to use this"
+  if (opts.includeAntiPatterns && playbook.applicability.antiPatterns.length > 0) {
+    sections.push('## When NOT to use this');
+    sections.push('');
+    for (const ap of playbook.applicability.antiPatterns) {
+      sections.push(`- ${ap}`);
+    }
+    sections.push('');
+  }
+
+  // Triggers — concrete signals that this skill applies
+  if (playbook.applicability.triggers.length > 0) {
+    sections.push('## Triggers');
+    sections.push('');
+    sections.push(
+      'This skill applies when you encounter any of the following:'
+    );
+    sections.push('');
+    for (const trigger of playbook.applicability.triggers) {
+      sections.push(`- ${trigger}`);
+    }
+    sections.push('');
+  }
+
+  // Verification
+  if (opts.includeVerification) {
+    const { successIndicators, failureIndicators, rollbackStrategy } =
+      playbook.verification;
+    if (successIndicators.length > 0 || failureIndicators.length > 0) {
+      sections.push('## Verification');
+      sections.push('');
+      if (successIndicators.length > 0) {
+        sections.push('**Success looks like:**');
+        for (const si of successIndicators) {
+          sections.push(`- ${si}`);
+        }
+        sections.push('');
+      }
+      if (failureIndicators.length > 0) {
+        sections.push('**Failure looks like:**');
+        for (const fi of failureIndicators) {
+          sections.push(`- ${fi}`);
+        }
+        sections.push('');
+      }
+      if (rollbackStrategy) {
+        sections.push(`**Rollback:** ${rollbackStrategy}`);
+        sections.push('');
+      }
+    }
+  }
+
+  // Refinements — context-specific notes learned from experience
+  if (opts.includeRefinements && playbook.evolution.refinements.length > 0) {
+    sections.push('## Context-specific notes');
+    sections.push('');
+    for (const ref of playbook.evolution.refinements) {
+      sections.push(`- **${ref.context}:** ${ref.addition}`);
+    }
+    sections.push('');
+  }
+
+  return sections.join('\n');
+}
+
+/**
+ * Build the description field from playbook applicability.
+ * The description is critical for skill discovery — agents use it to
+ * decide whether to load the skill.
+ */
+function buildDescription(playbook: Playbook): string {
+  const parts = [
+    ...playbook.applicability.situations,
+    ...playbook.applicability.triggers.slice(0, 2),
+  ];
+  const desc = parts.join('. ');
+  const domains = playbook.applicability.domains.join(', ');
+  // YAML multiline: use >- for long descriptions
+  const full = `${desc}. Domains: ${domains}.`;
+  // Truncate to 1024 chars per spec
+  if (full.length > 1024) {
+    return full.slice(0, 1021) + '...';
+  }
+  return full;
+}
+
+/**
+ * Export playbooks from a library to a directory of SKILL.md files
+ */
+export async function exportPlaybooksAsSkills(
+  library: PlaybookLibrary,
+  outputDir: string,
+  filter?: SkillExportFilter,
+  options?: SkillExportOptions
+): Promise<SkillExportResult> {
+  const result: SkillExportResult = {
+    exported: 0,
+    skipped: 0,
+    errors: [],
+    skills: [],
+  };
+
+  let playbooks = await library.getAll();
+
+  // Apply filters
+  if (filter?.minConfidence !== undefined) {
+    playbooks = playbooks.filter((p) => p.confidence >= filter.minConfidence!);
+  }
+  if (filter?.minUses !== undefined) {
+    playbooks = playbooks.filter(
+      (p) =>
+        p.evolution.successCount + p.evolution.failureCount >= filter.minUses!
+    );
+  }
+  if (filter?.domains && filter.domains.length > 0) {
+    playbooks = playbooks.filter((p) =>
+      p.applicability.domains.some((d) => filter.domains!.includes(d))
+    );
+  }
+  if (filter?.origins && filter.origins.length > 0) {
+    playbooks = playbooks.filter(
+      (p) =>
+        p.provenance?.origin !== undefined &&
+        filter.origins!.includes(p.provenance.origin)
+    );
+  }
+
+  // Ensure output directory exists
+  if (!existsSync(outputDir)) {
+    await mkdir(outputDir, { recursive: true });
+  }
+
+  for (const playbook of playbooks) {
+    try {
+      const content = compilePlaybookToSkill(playbook, options);
+      const dirName = playbook.name;
+      const skillDir = join(outputDir, dirName);
+
+      // Create skill directory
+      if (!existsSync(skillDir)) {
+        await mkdir(skillDir, { recursive: true });
+      }
+
+      // Write SKILL.md
+      await writeFile(join(skillDir, 'SKILL.md'), content, 'utf-8');
+
+      const skill: ExportedSkill = {
+        name: playbook.name,
+        dirName,
+        content,
+        sourcePlaybookId: playbook.id,
+      };
+
+      result.skills.push(skill);
+      result.exported++;
+    } catch (error) {
+      result.errors.push({
+        playbook: playbook.name,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Export a single playbook to a SKILL.md file
+ */
+export async function exportPlaybookAsSkill(
+  playbook: Playbook,
+  outputDir: string,
+  options?: SkillExportOptions
+): Promise<ExportedSkill> {
+  const content = compilePlaybookToSkill(playbook, options);
+  const dirName = playbook.name;
+  const skillDir = join(outputDir, dirName);
+
+  if (!existsSync(skillDir)) {
+    await mkdir(skillDir, { recursive: true });
+  }
+
+  await writeFile(join(skillDir, 'SKILL.md'), content, 'utf-8');
+
+  return {
+    name: playbook.name,
+    dirName,
+    content,
+    sourcePlaybookId: playbook.id,
+  };
+}