cognitive-core 0.2.3 → 0.2.4

package/src/workspace/templates/skill-enrichment.ts

@@ -0,0 +1,275 @@
+/**
+ * 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 { WorkspaceHandle } from 'agent-workspace';
+import type { Playbook } from '../../types/index.js';
+import { convertPlaybookToSkill } from '../../surfacing/skill-publisher.js';
+import type {
+  AgenticTaskTemplate,
+  AnalysisComplexity,
+  ResourceSpec,
+} from '../types.js';
+import type { ComputeRequirements } from '../../runtime/compute-provider.js';
+
+// ============================================================
+// Input / Output Types
+// ============================================================
+
+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[];
+}
+
+// ============================================================
+// Template Implementation
+// ============================================================
+
+export const skillEnrichmentTemplate: AgenticTaskTemplate<
+  SkillEnrichmentInput,
+  SkillEnrichmentOutput
+> = {
+  taskType: 'skill-enrichment',
+  domain: 'skill-publishing',
+  description: 'Enrich a procedurally generated SKILL.md with narrative prose, examples, and cross-references',
+
+  assessComplexity(input: SkillEnrichmentInput): AnalysisComplexity {
+    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: SkillEnrichmentInput): Promise<SkillEnrichmentOutput> {
+    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: SkillEnrichmentInput,
+    handle: WorkspaceHandle,
+  ): Promise<void> {
+    // 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: SkillEnrichmentInput): string {
+    const parts: string[] = [
+      `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: SkillEnrichmentInput): ResourceSpec[] {
+    const resources: ResourceSpec[] = [];
+    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' as const,
+        required: true,
+        description: 'Enriched skill content with description, instructions, examples, cross-refs, and gaps',
+      },
+    ],
+  },
+
+  async collectOutput(handle: WorkspaceHandle): Promise<SkillEnrichmentOutput> {
+    const raw = await handle.readJson('output', 'enrichment.json') as Record<string, unknown>;
+
+    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 as Array<Record<string, unknown>>).map((e) => ({
+          title: String(e.title ?? ''),
+          scenario: String(e.scenario ?? ''),
+          steps: String(e.steps ?? ''),
+        }))
+        : [],
+      seeAlso: Array.isArray(raw.seeAlso)
+        ? (raw.seeAlso as Array<Record<string, unknown>>).map((s) => ({
+          name: String(s.name ?? ''),
+          relation: String(s.relation ?? ''),
+        }))
+        : [],
+      gaps: Array.isArray(raw.gaps)
+        ? (raw.gaps as Array<unknown>).map(String)
+        : [],
+    };
+  },
+
+  async processOutput(): Promise<void> {
+    // Caller handles merging the enriched output back into the Skill
+    // and publishing via SkillPublisher.
+  },
+
+  computeRequirements: {
+    mode: 'local',
+    complexity: 'standard',
+  },
+
+  getComputeRequirements(
+    _input: SkillEnrichmentInput,
+    complexity: AnalysisComplexity,
+  ): ComputeRequirements {
+    return {
+      mode: 'local',
+      complexity,
+      timeout: complexity === 'thorough' ? 300_000 : 180_000,
+    };
+  },
+
+  agentType: 'claude-code',
+  timeout: 180_000,
+  captureToolCalls: true,
+};

package/tests/surfacing/skill-publisher.test.ts

@@ -77,10 +77,73 @@ describe('SkillPublisher', () => {
       const playbook = createSamplePlaybook();
       const skill = convertPlaybookToSkill(playbook);
 
-      expect(skill.description).toBe('TypeScript import fails with TS2307');
+      expect(skill.description).toContain('TypeScript import fails with TS2307');
       expect(skill.instructions).toContain('TypeScript import fails with TS2307');
     });
 
+    it('should surface trigger phrases inline in description for lightweight matching', () => {
+      const playbook = createSamplePlaybook();
+      const skill = convertPlaybookToSkill(playbook);
+
+      // Lead situation still present.
+      expect(skill.description).toContain('TypeScript import fails with TS2307');
+      // Explicit "Use when" clause listing each trigger phrase, quoted.
+      expect(skill.description).toContain('Use when');
+      expect(skill.description).toContain('"TS2307"');
+      expect(skill.description).toContain('"Cannot find module"');
+    });
+
+    it('should omit trigger clause when no triggers are declared', () => {
+      const playbook = createSamplePlaybook({
+        applicability: {
+          situations: ['Some situation'],
+          triggers: [],
+          antiPatterns: [],
+          domains: [],
+        },
+      });
+      const skill = convertPlaybookToSkill(playbook);
+
+      expect(skill.description).toBe('Some situation.');
+      expect(skill.description).not.toContain('Use when');
+    });
+
+    it('should cap description at 1024 chars', () => {
+      const playbook = createSamplePlaybook({
+        applicability: {
+          situations: ['X'.repeat(500)],
+          // Many long triggers would push past 1024 chars combined.
+          triggers: Array.from({ length: 20 }, (_, i) => 'trigger-phrase-' + 'y'.repeat(50) + `-${i}`),
+          antiPatterns: [],
+          domains: [],
+        },
+      });
+      const skill = convertPlaybookToSkill(playbook);
+
+      expect(skill.description.length).toBeLessThanOrEqual(1024);
+      expect(skill.description).toMatch(/\.\.\.$/);
+    });
+
+    it('should use provenance.curatedBy as author when set', () => {
+      const playbook = createSamplePlaybook({
+        provenance: {
+          origin: 'curated',
+          curatedBy: 'swarmkit-skills',
+          recordedAt: new Date(),
+        },
+      });
+      const skill = convertPlaybookToSkill(playbook);
+
+      expect(skill.author).toBe('swarmkit-skills');
+    });
+
+    it('should fall back to cognitive-core as author when provenance.curatedBy is absent', () => {
+      const playbook = createSamplePlaybook();
+      const skill = convertPlaybookToSkill(playbook);
+
+      expect(skill.author).toBe('cognitive-core');
+    });
+
     it('should build instructions from strategy, tactics, and steps', () => {
       const playbook = createSamplePlaybook();
       const skill = convertPlaybookToSkill(playbook);
@@ -92,15 +155,25 @@ describe('SkillPublisher', () => {
       expect(skill.instructions).toContain('Verify with tsc --noEmit');
     });
 
-    it('should include verification and notes in instructions', () => {
+    it('should include structured verification, when-to-use, and when-not-to-use sections', () => {
       const playbook = createSamplePlaybook();
       const skill = convertPlaybookToSkill(playbook);
 
-      expect(skill.instructions).toContain('Build passes');
-      expect(skill.instructions).toContain('Do NOT use when:');
-      expect(skill.instructions).toContain('Watch for:');
-      expect(skill.instructions).toContain('Refinements:');
+      // Verification indicators rendered as bulleted lists
+      expect(skill.instructions).toContain('Success:\n- Build passes');
+      expect(skill.instructions).toContain('Failure:\n- Same error persists');
       expect(skill.instructions).toContain('Rollback:');
+
+      // Anti-patterns now live in their own section, not in Notes
+      expect(skill.instructions).toContain('## When not to use');
+      expect(skill.instructions).toContain('- Module genuinely does not exist');
+
+      // Situations get their own section
+      expect(skill.instructions).toContain('## When to use');
+      expect(skill.instructions).toContain('- TypeScript import fails with TS2307');
+
+      // Refinements remain in Notes
+      expect(skill.instructions).toContain('Refinements:');
     });
 
     it('should compute metrics from evolution data', () => {
@@ -277,12 +350,12 @@ describe('SkillPublisher', () => {
       expect(result.error).toContain('not found');
     });
 
-    it('should preserve existing notes when deprecating', async () => {
+    it('should preserve existing content when deprecating', async () => {
       const publisher = new SkillPublisher(storage);
       await publisher.publishPlaybook(createSamplePlaybook({ id: 'notes-1' }));
 
       const before = await storage.getSkill('notes-1');
-      expect(before!.instructions).toContain('Do NOT use when:');
+      expect(before!.instructions).toContain('## When not to use');
 
       await publisher.deprecateSkill('notes-1', 'Superseded');