cognitive-core 0.2.3 → 0.2.5

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.5",
   "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,10 +74,10 @@
   "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",
+    "skill-tree": "^0.2.0",
     "sqlite-vec": "^0.1.6",
     "yaml": "^2.8.2",
     "zod": "^3.22.0"

package/src/surfacing/skill-publisher.ts

@@ -6,64 +6,130 @@
  * conversion at the publish boundary.
  */
 
-import type { Skill, StorageAdapter } from 'skill-tree';
-import type { Playbook } from '../types/index.js';
-import type { PublishResult, DeprecateResult } from './publisher.js';
-import { getPlaybookSuccessRate } from '../types/playbook.js';
+import type { Skill, StorageAdapter } from "skill-tree";
+import type { Playbook } from "../types/index.js";
+import type { PublishResult, DeprecateResult } from "./publisher.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
  */
 export function convertPlaybookToSkill(playbook: Playbook): Skill {
-  const totalUses = playbook.evolution.successCount + playbook.evolution.failureCount;
-  const successRate = getPlaybookSuccessRate(playbook);
-
   // Build solution text from guidance
   let solution = playbook.guidance.strategy;
   if (playbook.guidance.tactics.length > 0) {
-    solution += '\n\nTactics:\n' + playbook.guidance.tactics.map((t, i) => `${i + 1}. ${t}`).join('\n');
+    solution +=
+      "\n\nTactics:\n" +
+      playbook.guidance.tactics.map((t, i) => `${i + 1}. ${t}`).join("\n");
   }
   if (playbook.guidance.steps?.length) {
-    solution += '\n\nSteps:\n' + playbook.guidance.steps.map((s, i) => `${i + 1}. ${s}`).join('\n');
+    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,23 +141,19 @@ 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: {
-      usageCount: totalUses,
-      successRate,
-      lastUsed: playbook.evolution.lastUsed,
-      feedbackScores: [],
-      averageConfidence: playbook.confidence,
-    },
+    status: "active",
     source: {
-      type: 'extracted',
+      type: "extracted",
       sessionId: playbook.evolution.createdFrom[0],
       importedAt: playbook.createdAt,
     },
     serving: {
-      summary: description.length > 150 ? description.slice(0, 147) + '...' : description,
+      summary:
+        description.length > 150
+          ? description.slice(0, 147) + "..."
+          : description,
       tokenEstimate,
     },
     createdAt: playbook.createdAt,
@@ -152,15 +214,20 @@ export class SkillPublisher {
   /**
    * Deprecate a skill in storage
    */
-  async deprecateSkill(skillId: string, reason: string): Promise<DeprecateResult> {
+  async deprecateSkill(
+    skillId: string,
+    reason: string,
+  ): Promise<DeprecateResult> {
     try {
       const existing = await this.storage.getSkill(skillId);
       if (!existing) {
-        return { deprecated: false, skillId, error: 'Skill not found' };
+        return { deprecated: false, skillId, error: "Skill not found" };
       }
 
-      existing.status = 'deprecated';
-      existing.description = (existing.description ? existing.description + ' ' : '') + `[Deprecated: ${reason}]`;
+      existing.status = "deprecated";
+      existing.description =
+        (existing.description ? existing.description + " " : "") +
+        `[Deprecated: ${reason}]`;
       existing.updatedAt = new Date();
       await this.storage.saveSkill(existing);
 

package/src/surfacing/sqlite-storage-adapter.ts

@@ -23,7 +23,6 @@ interface SkillRow {
   author: string | null;
   status: string;
   tags: string;
-  metrics: string;
   source: string;
   serving: string;
   related: string;
@@ -44,8 +43,8 @@ interface VersionRow {
  * SQLite-backed StorageAdapter for skill-tree.
  *
  * Stores skills in a `skills` table with JSON columns for nested objects
- * (tags, metrics, triggerConditions, etc.). Version history is tracked in
- * a separate `skill_versions` table. Dates are stored as ISO strings.
+ * (tags, namespace, taxonomy, lineage, etc.). Version history is tracked
+ * in a separate `skill_versions` table. Dates are stored as ISO strings.
  */
 export class SqliteStorageAdapter implements StorageAdapter {
   private db: Database.Database;
@@ -79,6 +78,16 @@ export class SqliteStorageAdapter implements StorageAdapter {
       )
     `);
 
+    // Backwards-compat: drop the legacy metrics column on existing
+    // installs. skill-tree 0.2 dropped Skill.metrics; the column is no
+    // longer read or written. SQLite >= 3.35 supports DROP COLUMN; older
+    // versions silently fail and leave the column as harmless dead weight.
+    try {
+      this.db.exec('ALTER TABLE skills DROP COLUMN metrics');
+    } catch {
+      // Column already absent or SQLite version doesn't support DROP COLUMN.
+    }
+
     this.db.exec(`
       CREATE TABLE IF NOT EXISTS skill_versions (
         skill_id TEXT NOT NULL,
@@ -113,10 +122,10 @@ export class SqliteStorageAdapter implements StorageAdapter {
       const stmt = this.db.prepare(`
         INSERT OR REPLACE INTO skills
           (id, name, version, description, instructions,
-           author, status, tags, metrics, source,
+           author, status, tags, source,
            serving, related, created_at, updated_at)
         VALUES
-          (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `);
 
       stmt.run(
@@ -128,7 +137,6 @@ export class SqliteStorageAdapter implements StorageAdapter {
         skill.author ?? null,
         skill.status,
         JSON.stringify(skill.tags ?? []),
-        JSON.stringify(skill.metrics ?? {}),
         JSON.stringify(skill.source ?? {}),
         JSON.stringify(skill.serving ?? {}),
         JSON.stringify(skill.related ?? []),
@@ -237,8 +245,6 @@ export class SqliteStorageAdapter implements StorageAdapter {
    * Convert a database row to a Skill object, parsing JSON columns and dates.
    */
   private rowToSkill(row: SkillRow): Skill {
-    const metrics = JSON.parse(row.metrics);
-
     return {
       id: row.id,
       name: row.name,
@@ -249,10 +255,6 @@ export class SqliteStorageAdapter implements StorageAdapter {
       status: row.status as Skill['status'],
       tags: JSON.parse(row.tags),
       related: JSON.parse(row.related),
-      metrics: {
-        ...metrics,
-        lastUsed: metrics.lastUsed ? new Date(metrics.lastUsed) : undefined,
-      },
       source: JSON.parse(row.source),
       serving: JSON.parse(row.serving),
       createdAt: new Date(row.created_at),

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';