cognitive-core 0.2.4 → 0.3.1

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

@@ -1,275 +0,0 @@
-/**
- * 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/src/workspace/templates/solution-evaluation.ts

@@ -1,199 +0,0 @@
-/**
- * Solution Evaluation Template
- *
- * Enhances the SolutionEvaluator with workspace-based agentic evaluation
- * for cases where programmatic verification is insufficient.
- *
- * - Tasks with verification spec → heuristic (programmatic verification)
- * - Short successful trajectories → lightweight agent evaluation
- * - Complex or failed cases → standard agent evaluation
- */
-
-import type { WorkspaceHandle } from 'agent-workspace';
-import type { Trajectory, Task } from '../../types/index.js';
-import type { EvaluationResult } from '../../search/refinement-types.js';
-import { createEvaluationResult, scoreToQuality } from '../../search/refinement-types.js';
-import type {
-  AgenticTaskTemplate,
-  AnalysisComplexity,
-  ResourceSpec,
-} from '../types.js';
-import type { ComputeRequirements } from '../../runtime/compute-provider.js';
-
-// ============================================================
-// Input / Output Types
-// ============================================================
-
-export interface SolutionEvaluationInput {
-  trajectory: Trajectory;
-  task: Task;
-  /** Optional path to the codebase for agent to inspect */
-  codebasePath?: string;
-}
-
-// Output: EvaluationResult (reused from search/refinement-types.ts)
-
-// ============================================================
-// Template Implementation
-// ============================================================
-
-export const solutionEvaluationTemplate: AgenticTaskTemplate<
-  SolutionEvaluationInput,
-  EvaluationResult
-> = {
-  taskType: 'solution-evaluation',
-  domain: 'solution-evaluation',
-  description: 'Evaluate solution quality from trajectory',
-
-  assessComplexity(input: SolutionEvaluationInput): AnalysisComplexity {
-    // Programmatic verification available → heuristic path
-    if (input.task.verification) return 'heuristic';
-    // Short successful trajectories → lightweight
-    if (input.trajectory.outcome.success && input.trajectory.steps.length <= 10) {
-      return 'lightweight';
-    }
-    return 'standard';
-  },
-
-  async heuristicFallback(input: SolutionEvaluationInput): Promise<EvaluationResult> {
-    // Simple heuristic evaluation based on trajectory outcome
-    const score = input.trajectory.outcome.success
-      ? Math.max(0.7, input.trajectory.outcome.partialScore)
-      : input.trajectory.outcome.partialScore;
-
-    return createEvaluationResult({
-      quality: scoreToQuality(score),
-      score,
-      acceptable: score >= 0.7,
-      method: 'heuristic',
-    });
-  },
-
-  async prepareWorkspace(
-    input: SolutionEvaluationInput,
-    handle: WorkspaceHandle
-  ): Promise<void> {
-    const { trajectory, task } = input;
-
-    await handle.writeJson('input', 'task.json', {
-      description: task.description,
-      domain: task.domain,
-      verification: task.verification,
-    });
-
-    await handle.writeJson('input', 'trajectory.json', {
-      outcome: trajectory.outcome,
-      stepCount: trajectory.steps.length,
-      wallTimeSeconds: trajectory.wallTimeSeconds,
-      solution: trajectory.outcome.solution,
-    });
-
-    await handle.writeJsonl('input', 'steps.jsonl',
-      trajectory.steps.map((step, i) => ({
-        index: i,
-        action: step.action,
-        observation: step.observation?.slice(0, 300),
-      }))
-    );
-  },
-
-  buildTaskPrompt(input: SolutionEvaluationInput): string {
-    const lines = [
-      `Evaluate the quality of this solution for: "${input.task.description.slice(0, 200)}"`,
-      '',
-      'Read input/task.json for the task requirements.',
-      'Read input/trajectory.json for the outcome and solution.',
-      'Read input/steps.jsonl for execution details.',
-    ];
-
-    if (input.codebasePath) {
-      lines.push('Browse resources/codebase/ to inspect the actual code changes if relevant.');
-    }
-
-    lines.push(
-      '',
-      'Evaluate:',
-      '1. Does the solution address the task requirements?',
-      '2. Are there any issues (incomplete, incorrect, inefficient, errors)?',
-      '3. Overall quality score (0.0 to 1.0)',
-      '',
-      'Write to output/evaluation.json:',
-      '```json',
-      '{',
-      '  "quality": "excellent" | "good" | "needs_work" | "poor",',
-      '  "score": 0.0-1.0,',
-      '  "acceptable": boolean,',
-      '  "issues": [{ "type": "incomplete"|"incorrect"|"inefficient"|"error", "description": "...", "severity": "critical"|"major"|"minor", "suggestion": "..." }]',
-      '}',
-      '```',
-    );
-    return lines.join('\n');
-  },
-
-  getSkills() { return []; },
-
-  getResources(input: SolutionEvaluationInput): ResourceSpec[] {
-    if (!input.codebasePath) return [];
-    return [{
-      path: 'codebase',
-      type: 'symlink',
-      source: input.codebasePath,
-      description: 'Codebase for solution verification',
-    }];
-  },
-
-  outputConfig: {
-    files: [{
-      path: 'evaluation.json',
-      format: 'json' as const,
-      required: true,
-      description: 'Solution quality evaluation',
-    }],
-  },
-
-  async collectOutput(handle: WorkspaceHandle): Promise<EvaluationResult> {
-    const raw = await handle.readJson('output', 'evaluation.json') as Record<string, unknown>;
-
-    const score = typeof raw.score === 'number' ? Math.min(1, Math.max(0, raw.score)) : 0.5;
-    const quality = ['excellent', 'good', 'needs_work', 'poor'].includes(String(raw.quality))
-      ? String(raw.quality) as EvaluationResult['quality']
-      : scoreToQuality(score);
-
-    return createEvaluationResult({
-      quality,
-      score,
-      acceptable: raw.acceptable !== undefined ? Boolean(raw.acceptable) : score >= 0.7,
-      issues: Array.isArray(raw.issues)
-        ? (raw.issues as Record<string, unknown>[]).map(issue => ({
-            type: String(issue.type ?? 'error') as 'incomplete' | 'incorrect' | 'inefficient' | 'error',
-            description: String(issue.description ?? ''),
-            severity: (['critical', 'major', 'minor'].includes(String(issue.severity))
-              ? String(issue.severity) : 'minor') as 'critical' | 'major' | 'minor',
-            suggestion: issue.suggestion ? String(issue.suggestion) : undefined,
-          }))
-        : [],
-      method: 'agent',
-    });
-  },
-
-  async processOutput(): Promise<void> {},
-
-  computeRequirements: {
-    mode: 'local',
-    complexity: 'standard',
-  },
-
-  getComputeRequirements(
-    _input: SolutionEvaluationInput,
-    complexity: AnalysisComplexity
-  ): ComputeRequirements {
-    return {
-      mode: 'local',
-      complexity,
-    };
-  },
-
-  agentType: 'claude-code',
-  timeout: 120_000,
-  captureToolCalls: true,
-};