cognitive-core 0.2.3 → 0.2.4

package/dist/workspace/templates/skill-enrichment.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Skill Enrichment Template
+ *
+ * Agent-in-the-loop step between playbook extraction and skill publishing.
+ * Given a Playbook and its procedurally generated SKILL.md skeleton, an agent
+ * enriches the skill with narrative prose, worked examples, cross-references,
+ * and a trigger-rich description — things a procedural converter cannot produce.
+ *
+ * Complexity routing:
+ * - Simple playbooks (<=3 tactics, low complexity) → heuristic: keep procedural output as-is
+ * - Standard/complex playbooks → agent enrichment
+ */
+import type { Playbook } from '../../types/index.js';
+import type { AgenticTaskTemplate } from '../types.js';
+export interface SkillEnrichmentInput {
+    /** The playbook to enrich into a skill */
+    playbook: Playbook;
+    /** Optional: existing hand-written SKILL.md to use as style reference */
+    styleReference?: string;
+    /** Optional: related skill names for cross-referencing */
+    relatedSkills?: Array<{
+        name: string;
+        description: string;
+    }>;
+    /** Optional: domain context (e.g. "swarmkit ecosystem", "TypeScript tooling") */
+    domainContext?: string;
+}
+export interface SkillEnrichmentOutput {
+    /** Enriched SKILL.md frontmatter description (trigger-rich, under 1024 chars) */
+    description: string;
+    /** Enriched markdown body (replaces the procedural instructions) */
+    instructions: string;
+    /** Worked examples the agent generated */
+    examples: Array<{
+        title: string;
+        scenario: string;
+        steps: string;
+    }>;
+    /** Cross-references to related skills */
+    seeAlso: Array<{
+        name: string;
+        relation: string;
+    }>;
+    /** Agent's assessment of the playbook's completeness */
+    gaps: string[];
+}
+export declare const skillEnrichmentTemplate: AgenticTaskTemplate<SkillEnrichmentInput, SkillEnrichmentOutput>;
+//# sourceMappingURL=skill-enrichment.d.ts.map

package/dist/workspace/templates/skill-enrichment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-enrichment.d.ts","sourceRoot":"","sources":["../../../src/workspace/templates/skill-enrichment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,KAAK,EACV,mBAAmB,EAGpB,MAAM,aAAa,CAAC;AAOrB,MAAM,WAAW,oBAAoB;IACnC,0CAA0C;IAC1C,QAAQ,EAAE,QAAQ,CAAC;IACnB,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,aAAa,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,iFAAiF;IACjF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,QAAQ,EAAE,KAAK,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;KACf,CAAC,CAAC;IACH,yCAAyC;IACzC,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,wDAAwD;IACxD,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAMD,eAAO,MAAM,uBAAuB,EAAE,mBAAmB,CACvD,oBAAoB,EACpB,qBAAqB,CAkNtB,CAAC"}

package/dist/workspace/templates/skill-enrichment.js

@@ -0,0 +1,175 @@
+/**
+ * Skill Enrichment Template
+ *
+ * Agent-in-the-loop step between playbook extraction and skill publishing.
+ * Given a Playbook and its procedurally generated SKILL.md skeleton, an agent
+ * enriches the skill with narrative prose, worked examples, cross-references,
+ * and a trigger-rich description — things a procedural converter cannot produce.
+ *
+ * Complexity routing:
+ * - Simple playbooks (<=3 tactics, low complexity) → heuristic: keep procedural output as-is
+ * - Standard/complex playbooks → agent enrichment
+ */
+import { convertPlaybookToSkill } from '../../surfacing/skill-publisher.js';
+// ============================================================
+// Template Implementation
+// ============================================================
+export const skillEnrichmentTemplate = {
+    taskType: 'skill-enrichment',
+    domain: 'skill-publishing',
+    description: 'Enrich a procedurally generated SKILL.md with narrative prose, examples, and cross-references',
+    assessComplexity(input) {
+        const pb = input.playbook;
+        const tacticCount = pb.guidance.tactics.length;
+        const hasSteps = (pb.guidance.steps?.length ?? 0) > 0;
+        const isComplex = pb.complexity === 'complex';
+        if (tacticCount <= 3 && !hasSteps && !isComplex)
+            return 'heuristic';
+        if (isComplex || tacticCount > 8)
+            return 'thorough';
+        return 'standard';
+    },
+    async heuristicFallback(input) {
+        const skill = convertPlaybookToSkill(input.playbook);
+        return {
+            description: skill.description,
+            instructions: skill.instructions,
+            examples: [],
+            seeAlso: (input.relatedSkills ?? []).map((r) => ({
+                name: r.name,
+                relation: `Related: ${r.description}`,
+            })),
+            gaps: [],
+        };
+    },
+    async prepareWorkspace(input, handle) {
+        // Write the playbook as structured JSON
+        await handle.writeJson('input', 'playbook.json', {
+            name: input.playbook.name,
+            applicability: input.playbook.applicability,
+            guidance: input.playbook.guidance,
+            verification: input.playbook.verification,
+            complexity: input.playbook.complexity,
+            confidence: input.playbook.confidence,
+            evolution: {
+                version: input.playbook.evolution.version,
+                successCount: input.playbook.evolution.successCount,
+                failureCount: input.playbook.evolution.failureCount,
+                refinements: input.playbook.evolution.refinements,
+            },
+            provenance: input.playbook.provenance,
+            userInvocable: input.playbook.userInvocable,
+            publishMetadata: input.playbook.publishMetadata,
+        });
+        // Write the procedural skeleton for the agent to improve upon
+        const skill = convertPlaybookToSkill(input.playbook);
+        await handle.writeRaw('input', 'skeleton.md', skill.instructions);
+        await handle.writeRaw('input', 'skeleton-description.txt', skill.description);
+        // Style reference (if provided)
+        if (input.styleReference) {
+            await handle.writeRaw('input', 'style-reference.md', input.styleReference);
+        }
+        // Related skills for cross-referencing
+        if (input.relatedSkills && input.relatedSkills.length > 0) {
+            await handle.writeJson('input', 'related-skills.json', input.relatedSkills);
+        }
+        // Domain context
+        if (input.domainContext) {
+            await handle.writeRaw('input', 'domain-context.txt', input.domainContext);
+        }
+    },
+    buildTaskPrompt(input) {
+        const parts = [
+            `Enrich the skill "${input.playbook.name}" into a high-quality SKILL.md that an AI agent will load and follow.`,
+            '',
+            '## Inputs',
+            '',
+            '- `input/playbook.json` — the structured playbook (applicability, guidance, verification)',
+            '- `input/skeleton.md` — procedurally generated markdown body (your starting point)',
+            '- `input/skeleton-description.txt` — procedurally generated frontmatter description',
+        ];
+        if (input.styleReference) {
+            parts.push('- `input/style-reference.md` — a hand-written SKILL.md to match in tone and structure');
+        }
+        if (input.relatedSkills && input.relatedSkills.length > 0) {
+            parts.push('- `input/related-skills.json` — related skills to cross-reference');
+        }
+        if (input.domainContext) {
+            parts.push('- `input/domain-context.txt` — domain context for accurate terminology');
+        }
+        parts.push('', '## What to produce', '', 'Read all inputs, then write `output/enrichment.json` with this schema:', '', '```json', '{', '  "description": "Trigger-rich frontmatter description, under 1024 chars. Structure: [What it does] + [Use when ...trigger phrases...]. Include concrete phrases users would say.",', '  "instructions": "Full markdown body. Must include:\\n- ## When to use (bulleted)\\n- ## When not to use (bulleted)\\n- ## Workflow (numbered tactics expanded into full prose — explain WHY each step matters, not just WHAT to do)\\n- ## Inputs / ## Outputs\\n- ## Verification (bulleted success/failure indicators)\\n- ## Edge cases (narrative, with recovery paths)\\n- ## Examples (2-3 worked scenarios with concrete commands)\\n- ## See also (cross-references)",', '  "examples": [{"title": "...", "scenario": "...", "steps": "..."}],', '  "seeAlso": [{"name": "skill-name", "relation": "why it is related"}],', '  "gaps": ["anything missing from the playbook that the skill should cover but cannot without more data"]', '}', '```', '', '## Guidelines', '', '- The skeleton is your starting point — improve it, do not discard it.', '- Expand each tactic in the Workflow section into a paragraph that explains the rationale, not just the command.', '- Generate 2-3 realistic examples with concrete tool calls (MCP tools, CLI commands, or library calls as appropriate for the domain).', '- Cross-reference related skills by name in the See Also section.', '- Flag gaps honestly — if the playbook is missing triggers, anti-patterns, or verification criteria, say so in the gaps array.', '- Keep the description under 1024 characters. It must include trigger phrases users would actually say.', '- Do not invent capabilities the playbook does not describe. Enrich what is there; do not fabricate.');
+        if (input.styleReference) {
+            parts.push('- Match the tone, section structure, and level of detail from the style reference.');
+        }
+        return parts.join('\n');
+    },
+    getSkills() { return []; },
+    getResources(input) {
+        const resources = [];
+        if (input.domainContext) {
+            resources.push({
+                type: 'file',
+                path: 'domain-context.txt',
+                source: input.domainContext,
+                description: 'Domain context for accurate terminology',
+            });
+        }
+        return resources;
+    },
+    outputConfig: {
+        files: [
+            {
+                path: 'enrichment.json',
+                format: 'json',
+                required: true,
+                description: 'Enriched skill content with description, instructions, examples, cross-refs, and gaps',
+            },
+        ],
+    },
+    async collectOutput(handle) {
+        const raw = await handle.readJson('output', 'enrichment.json');
+        return {
+            description: typeof raw.description === 'string'
+                ? raw.description.slice(0, 1024)
+                : '',
+            instructions: typeof raw.instructions === 'string'
+                ? raw.instructions
+                : '',
+            examples: Array.isArray(raw.examples)
+                ? raw.examples.map((e) => ({
+                    title: String(e.title ?? ''),
+                    scenario: String(e.scenario ?? ''),
+                    steps: String(e.steps ?? ''),
+                }))
+                : [],
+            seeAlso: Array.isArray(raw.seeAlso)
+                ? raw.seeAlso.map((s) => ({
+                    name: String(s.name ?? ''),
+                    relation: String(s.relation ?? ''),
+                }))
+                : [],
+            gaps: Array.isArray(raw.gaps)
+                ? raw.gaps.map(String)
+                : [],
+        };
+    },
+    async processOutput() {
+        // Caller handles merging the enriched output back into the Skill
+        // and publishing via SkillPublisher.
+    },
+    computeRequirements: {
+        mode: 'local',
+        complexity: 'standard',
+    },
+    getComputeRequirements(_input, complexity) {
+        return {
+            mode: 'local',
+            complexity,
+            timeout: complexity === 'thorough' ? 300_000 : 180_000,
+        };
+    },
+    agentType: 'claude-code',
+    timeout: 180_000,
+    captureToolCalls: true,
+};
+//# sourceMappingURL=skill-enrichment.js.map

package/dist/workspace/templates/skill-enrichment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-enrichment.js","sourceRoot":"","sources":["../../../src/workspace/templates/skill-enrichment.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cognitive-core",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "TypeScript-native cognitive core for adaptive learning and abstraction",
   "type": "module",
   "main": "dist/index.js",
@@ -65,7 +65,7 @@
   "author": "Alex Ngai",
   "license": "MIT",
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.8",
+    "@types/better-sqlite3": "^7.6.12",
     "@types/node": "^20.10.0",
     "eslint": "^8.55.0",
     "typescript": "^5.3.0",
@@ -74,7 +74,7 @@
   "dependencies": {
     "acp-factory": "^0.1.14",
     "agent-workspace": "^0.1.5",
-    "better-sqlite3": "^9.0.0",
+    "better-sqlite3": "^12.0.0",
     "minimem": "^0.1.0",
     "sessionlog": "^0.0.4",
     "skill-tree": "^0.1.5",

package/src/surfacing/skill-publisher.ts

@@ -11,6 +11,46 @@ import type { Playbook } from '../types/index.js';
 import type { PublishResult, DeprecateResult } from './publisher.js';
 import { getPlaybookSuccessRate } from '../types/playbook.js';
 
+/**
+ * Maximum length for the generated `description` field.
+ * Claude Code's skill format caps description at 1024 chars, so we truncate
+ * to stay safely within that boundary.
+ */
+const MAX_DESCRIPTION_LENGTH = 1024;
+
+/**
+ * Build the `description` field for a published Skill.
+ *
+ * The description is what lightweight trigger matchers — notably Claude Code's
+ * skill loader — key off to decide whether to load a skill. It needs two things:
+ *
+ * 1. A short "what it does" lead (pulled from the first situation, or the
+ *    strategy if no situation is set).
+ * 2. The concrete trigger phrases, surfaced inline so substring/keyword
+ *    matchers catch them. These live in `applicability.triggers` on the
+ *    playbook but are invisible to downstream consumers unless we lift them.
+ *
+ * Shape: `<lead>. Use when "<t1>", "<t2>", ..., "<tN>".`
+ */
+function buildDescription(playbook: Playbook): string {
+  let lead = playbook.applicability.situations[0]
+    ?? `${playbook.name}: ${playbook.guidance.strategy.slice(0, 100)}`;
+
+  // Ensure a sentence terminator before appending the trigger clause.
+  if (lead.length > 0 && !/[.!?]$/.test(lead)) {
+    lead += '.';
+  }
+
+  const triggers = playbook.applicability.triggers;
+  const triggerClause = triggers.length > 0
+    ? ` Use when ${triggers.map((t) => `"${t}"`).join(', ')}.`
+    : '';
+
+  const full = lead + triggerClause;
+  if (full.length <= MAX_DESCRIPTION_LENGTH) return full;
+  return full.slice(0, MAX_DESCRIPTION_LENGTH - 3) + '...';
+}
+
 /**
  * Convert a Playbook to a Skill
  */
@@ -27,43 +67,69 @@ export function convertPlaybookToSkill(playbook: Playbook): Skill {
     solution += '\n\nSteps:\n' + playbook.guidance.steps.map((s, i) => `${i + 1}. ${s}`).join('\n');
   }
 
-  // Build verification text
-  const verification = playbook.verification.successIndicators.length > 0
-    ? playbook.verification.successIndicators.join('. ')
-    : 'Verify the approach worked as expected.';
+  // Build description for semantic matching and lightweight trigger routing
+  const description = buildDescription(playbook);
 
-  // Build notes from anti-patterns and refinements
-  const notesParts: string[] = [];
+  // Build structured instructions body
+  const instructionParts: string[] = [];
+
+  // --- When to use / When not to use (Change A) ---
+  if (playbook.applicability.situations.length > 0) {
+    instructionParts.push(
+      '## When to use\n\n'
+      + playbook.applicability.situations.map((s) => `- ${s}`).join('\n'),
+    );
+  }
   if (playbook.applicability.antiPatterns.length > 0) {
-    notesParts.push('Do NOT use when: ' + playbook.applicability.antiPatterns.join('; '));
+    instructionParts.push(
+      '## When not to use\n\n'
+      + playbook.applicability.antiPatterns.map((a) => `- ${a}`).join('\n'),
+    );
   }
-  if (playbook.verification.failureIndicators.length > 0) {
-    notesParts.push('Watch for: ' + playbook.verification.failureIndicators.join('; '));
+
+  // --- Solution ---
+  instructionParts.push(`## Solution\n\n${solution}`);
+
+  // --- Verification with bulleted indicators (Change B) ---
+  const verificationParts: string[] = [];
+  if (playbook.verification.successIndicators.length > 0) {
+    verificationParts.push(
+      'Success:\n'
+      + playbook.verification.successIndicators.map((s) => `- ${s}`).join('\n'),
+    );
   }
-  if (playbook.evolution.refinements.length > 0) {
-    notesParts.push('Refinements:\n' + playbook.evolution.refinements.map(
-      r => `- In ${r.context}: ${r.addition}`
-    ).join('\n'));
+  if (playbook.verification.failureIndicators.length > 0) {
+    verificationParts.push(
+      'Failure:\n'
+      + playbook.verification.failureIndicators.map((f) => `- ${f}`).join('\n'),
+    );
   }
   if (playbook.verification.rollbackStrategy) {
-    notesParts.push('Rollback: ' + playbook.verification.rollbackStrategy);
+    verificationParts.push(`Rollback: ${playbook.verification.rollbackStrategy}`);
+  }
+  if (verificationParts.length > 0) {
+    instructionParts.push(`## Verification\n\n${verificationParts.join('\n\n')}`);
+  } else {
+    instructionParts.push('## Verification\n\nVerify the approach worked as expected.');
   }
 
-  // Build description for semantic matching
-  const description = playbook.applicability.situations[0]
-    ?? `${playbook.name}: ${playbook.guidance.strategy.slice(0, 100)}`;
-
-  // Build instructions as structured markdown combining all content
-  const instructionParts: string[] = [];
-  instructionParts.push(`## Problem\n${playbook.applicability.situations.join('. ')}`);
-  instructionParts.push(`## Solution\n${solution}`);
-  instructionParts.push(`## Verification\n${verification}`);
+  // --- Notes (refinements only — anti-patterns now in their own section) ---
+  const notesParts: string[] = [];
+  if (playbook.evolution.refinements.length > 0) {
+    notesParts.push(
+      'Refinements:\n'
+      + playbook.evolution.refinements.map((r) => `- In ${r.context}: ${r.addition}`).join('\n'),
+    );
+  }
   if (notesParts.length > 0) {
-    instructionParts.push(`## Notes\n${notesParts.join('\n\n')}`);
+    instructionParts.push(`## Notes\n\n${notesParts.join('\n\n')}`);
   }
+
+  // --- Example ---
   if (playbook.guidance.codeExample) {
-    instructionParts.push(`## Example\n\`\`\`\n${playbook.guidance.codeExample}\n\`\`\``);
+    instructionParts.push(`## Example\n\n\`\`\`\n${playbook.guidance.codeExample}\n\`\`\``);
   }
+
   const instructions = instructionParts.join('\n\n');
 
   // Estimate tokens (rough: 4 chars per token)
@@ -75,7 +141,7 @@ export function convertPlaybookToSkill(playbook: Playbook): Skill {
     version: playbook.evolution.version,
     description,
     instructions,
-    author: 'cognitive-core',
+    author: playbook.provenance?.curatedBy ?? 'cognitive-core',
     tags: playbook.applicability.domains,
     status: 'active',
     metrics: {

package/src/types/playbook.ts

@@ -35,6 +35,19 @@ export interface Playbook {
   embedding?: number[]; // For semantic search
   createdAt: Date;
   updatedAt: Date;
+
+  // === PUBLISH HINTS (optional, used by SkillPublisher) ===
+  /**
+   * Whether end-users can invoke this skill directly (e.g. via /slash-command).
+   * Propagated into the published SKILL.md frontmatter as `user-invocable`.
+   */
+  userInvocable?: boolean;
+  /**
+   * Arbitrary key-value metadata propagated verbatim into the published
+   * SKILL.md frontmatter `metadata:` block. Use for ecosystem-specific
+   * fields (audience, component, ecosystem) without changing the core schema.
+   */
+  publishMetadata?: Record<string, unknown>;
 }
 
 /**
@@ -159,6 +172,8 @@ export function createPlaybook(
     complexity: input.complexity ?? 'moderate',
     estimatedEffort: input.estimatedEffort ?? 3,
     embedding: input.embedding,
+    userInvocable: input.userInvocable,
+    publishMetadata: input.publishMetadata,
     createdAt: input.createdAt ?? now,
     updatedAt: input.updatedAt ?? now,
   };

package/src/workspace/templates/index.ts

@@ -86,3 +86,10 @@ export {
   type PlaybookLifecycleReviewOutput,
   type LifecycleRecommendation,
 } from './playbook-lifecycle-review.js';
+
+// Skill Enrichment (publish pipeline — agent-enriched SKILL.md generation)
+export {
+  skillEnrichmentTemplate,
+  type SkillEnrichmentInput,
+  type SkillEnrichmentOutput,
+} from './skill-enrichment.js';