cognitive-core 0.0.2 → 0.1.2

package/src/surfacing/team-skill-library.ts

@@ -0,0 +1,610 @@
+/**
+ * Team Skill Library
+ *
+ * Tiered surfacing of team playbooks and role playbooks for
+ * team formation decisions and agent role guidance injection.
+ *
+ * The team-level analog of SkillLibrary.
+ *
+ * Responsibilities:
+ * - Rank team playbooks by relevance, confidence, and success rate
+ * - Rank role playbooks for each role in a recommended team
+ * - Format role guidance for injection into agent system prompts
+ * - Record team outcome feedback to update playbook evolution
+ * - Tier management: promote/demote team playbooks based on track record
+ */
+
+import type {
+  TeamPlaybook,
+  RolePlaybook,
+} from '../types/index.js';
+import { getTeamPlaybookSuccessRate, getRolePlaybookSuccessRate } from '../types/team-playbook.js';
+import type { TeamExperienceMemory } from '../memory/team-experience.js';
+
+// ============================================================
+// Configuration
+// ============================================================
+
+export interface TeamSkillLibraryConfig {
+  /** Promotion criteria for core team playbooks */
+  promotion: {
+    minConfidence: number;
+    minSuccessCount: number;
+    minSuccessRate: number;
+  };
+  /** Maximum items to surface */
+  limits: {
+    maxCoreTeamPlaybooks: number;
+    maxRolePlaybooksPerRole: number;
+    maxTokensForGuidance: number;
+  };
+  /** Demotion criteria */
+  demotion: {
+    failureThreshold: number;
+    minConfidenceToRetain: number;
+  };
+}
+
+const DEFAULT_CONFIG: TeamSkillLibraryConfig = {
+  promotion: {
+    minConfidence: 0.7,
+    minSuccessCount: 3,
+    minSuccessRate: 0.7,
+  },
+  limits: {
+    maxCoreTeamPlaybooks: 10,
+    maxRolePlaybooksPerRole: 3,
+    maxTokensForGuidance: 3000,
+  },
+  demotion: {
+    failureThreshold: 3,
+    minConfidenceToRetain: 0.4,
+  },
+};
+
+// ============================================================
+// Output Types
+// ============================================================
+
+/**
+ * A team playbook with ranking scores.
+ */
+export interface RankedTeamPlaybook {
+  playbook: TeamPlaybook;
+  relevanceScore: number;
+  successRate: number;
+  /** Combined ranking score */
+  rankScore: number;
+}
+
+/**
+ * A role playbook with ranking scores.
+ */
+export interface RankedRolePlaybook {
+  playbook: RolePlaybook;
+  relevanceScore: number;
+  successRate: number;
+  rankScore: number;
+}
+
+/**
+ * Team outcome feedback for the evolution loop.
+ */
+export interface TeamOutcomeFeedback {
+  /** Which team playbook was used */
+  playbookId: string;
+  /** Team trajectory ID (optional) */
+  teamTrajectoryId?: string;
+  /** Whether the team succeeded */
+  success: boolean;
+  /** Quality of the outcome */
+  quality: 'excellent' | 'good' | 'acceptable' | 'poor';
+  /** Optional notes */
+  notes?: string;
+  /** Observed metrics */
+  metrics?: {
+    coordinationOverhead?: number;
+    parallelismRatio?: number;
+    timeToFirstOutput?: number;
+  };
+}
+
+/**
+ * Role outcome feedback.
+ */
+export interface RoleOutcomeFeedback {
+  /** Which role playbook was used */
+  playbookId: string;
+  /** Whether the role was effective */
+  success: boolean;
+  /** Quality assessment */
+  quality: 'excellent' | 'good' | 'acceptable' | 'poor';
+}
+
+/**
+ * Team skills organized for injection.
+ */
+export interface TeamAgentSkills {
+  /** Core team playbooks (highest confidence, always surfaced) */
+  coreTeamPlaybooks: TeamPlaybook[];
+  /** Matched team playbooks for this specific task */
+  matchedTeamPlaybooks: TeamPlaybook[];
+  /** Role playbooks organized by role */
+  rolePlaybooks: Map<string, RolePlaybook[]>;
+  /** Estimated token count */
+  totalTokenEstimate: number;
+}
+
+// ============================================================
+// Team Skill Library
+// ============================================================
+
+export class TeamSkillLibrary {
+  private memory: TeamExperienceMemory;
+  private config: TeamSkillLibraryConfig;
+
+  // Cached promoted team playbooks
+  private coreTeamPlaybooks: TeamPlaybook[] = [];
+  private lastRefresh: Date | null = null;
+  private consecutiveFailures: Map<string, number> = new Map();
+
+  constructor(
+    memory: TeamExperienceMemory,
+    config?: Partial<TeamSkillLibraryConfig>
+  ) {
+    this.memory = memory;
+    this.config = {
+      promotion: { ...DEFAULT_CONFIG.promotion, ...config?.promotion },
+      limits: { ...DEFAULT_CONFIG.limits, ...config?.limits },
+      demotion: { ...DEFAULT_CONFIG.demotion, ...config?.demotion },
+    };
+  }
+
+  // === TIER MANAGEMENT ===
+
+  /**
+   * Refresh core team playbook tiers based on current state.
+   */
+  async refreshTiers(): Promise<{
+    promoted: string[];
+    demoted: string[];
+    coreCount: number;
+  }> {
+    const allPlaybooks = await this.memory.getTeamPlaybooks();
+    const previousCoreIds = new Set(this.coreTeamPlaybooks.map((p) => p.id));
+
+    // Find promotion candidates
+    const candidates = allPlaybooks
+      .filter((p) => this.meetsPromotionCriteria(p))
+      .sort((a, b) => {
+        const scoreA = a.confidence * getTeamPlaybookSuccessRate(a);
+        const scoreB = b.confidence * getTeamPlaybookSuccessRate(b);
+        return scoreB - scoreA;
+      });
+
+    // Check for demotions
+    const demotionIds = new Set(
+      this.coreTeamPlaybooks
+        .filter((p) => this.meetsDemotionCriteria(p))
+        .map((p) => p.id)
+    );
+
+    // Update core list
+    this.coreTeamPlaybooks = candidates
+      .filter((p) => !demotionIds.has(p.id))
+      .slice(0, this.config.limits.maxCoreTeamPlaybooks);
+
+    const newCoreIds = new Set(this.coreTeamPlaybooks.map((p) => p.id));
+    const promoted = [...newCoreIds].filter((id) => !previousCoreIds.has(id));
+    const demoted = [...previousCoreIds].filter((id) => !newCoreIds.has(id));
+
+    this.lastRefresh = new Date();
+
+    return {
+      promoted,
+      demoted,
+      coreCount: this.coreTeamPlaybooks.length,
+    };
+  }
+
+  private meetsPromotionCriteria(playbook: TeamPlaybook): boolean {
+    const { minConfidence, minSuccessCount, minSuccessRate } = this.config.promotion;
+    const successRate = getTeamPlaybookSuccessRate(playbook);
+
+    return (
+      playbook.confidence >= minConfidence &&
+      playbook.evolution.successCount >= minSuccessCount &&
+      successRate >= minSuccessRate
+    );
+  }
+
+  private meetsDemotionCriteria(playbook: TeamPlaybook): boolean {
+    const { failureThreshold, minConfidenceToRetain } = this.config.demotion;
+    const failures = this.consecutiveFailures.get(playbook.id) ?? 0;
+
+    return (
+      failures >= failureThreshold ||
+      playbook.confidence < minConfidenceToRetain
+    );
+  }
+
+  // === RETRIEVAL ===
+
+  /**
+   * Find and rank team playbooks for a task.
+   */
+  async findMatchingTeamPlaybooks(query: {
+    taskType?: string;
+    domain?: string;
+    topology?: string;
+    complexity?: string;
+    k?: number;
+  }): Promise<RankedTeamPlaybook[]> {
+    const matches = await this.memory.findMatchingTeamPlaybooks({
+      taskType: query.taskType,
+      domain: query.domain,
+      topology: query.topology,
+      complexity: query.complexity,
+      k: query.k ?? 5,
+    });
+
+    return matches.map(({ playbook, score }) => ({
+      playbook,
+      relevanceScore: score,
+      successRate: getTeamPlaybookSuccessRate(playbook),
+      rankScore: this.computeRankScore(score, playbook.confidence, getTeamPlaybookSuccessRate(playbook)),
+    })).sort((a, b) => b.rankScore - a.rankScore);
+  }
+
+  /**
+   * Find and rank role playbooks for a specific role.
+   */
+  async findRolePlaybooks(
+    role: string,
+    context: {
+      topology?: string;
+      taskType?: string;
+      domain?: string;
+    }
+  ): Promise<RankedRolePlaybook[]> {
+    const matches = await this.memory.findMatchingRolePlaybooks({
+      role,
+      topology: context.topology,
+      taskType: context.taskType,
+      domain: context.domain,
+      k: this.config.limits.maxRolePlaybooksPerRole,
+    });
+
+    return matches.map(({ playbook, score }) => ({
+      playbook,
+      relevanceScore: score,
+      successRate: getRolePlaybookSuccessRate(playbook),
+      rankScore: this.computeRankScore(score, playbook.confidence, getRolePlaybookSuccessRate(playbook)),
+    })).sort((a, b) => b.rankScore - a.rankScore);
+  }
+
+  /**
+   * Get team skills organized for agent context.
+   */
+  async getSkillsForTeam(query: {
+    description: string;
+    domain: string;
+    complexity?: string;
+    roles: string[];
+    topology?: string;
+  }): Promise<TeamAgentSkills> {
+    const result: TeamAgentSkills = {
+      coreTeamPlaybooks: [...this.coreTeamPlaybooks],
+      matchedTeamPlaybooks: [],
+      rolePlaybooks: new Map(),
+      totalTokenEstimate: 0,
+    };
+
+    // Find matched team playbooks
+    const matched = await this.findMatchingTeamPlaybooks({
+      taskType: query.description,
+      domain: query.domain,
+      complexity: query.complexity,
+      topology: query.topology,
+    });
+
+    // Exclude core playbooks from matched
+    const coreIds = new Set(this.coreTeamPlaybooks.map((p) => p.id));
+    result.matchedTeamPlaybooks = matched
+      .filter((m) => !coreIds.has(m.playbook.id))
+      .map((m) => m.playbook);
+
+    // Find role playbooks for each role
+    for (const role of query.roles) {
+      const roleMatches = await this.findRolePlaybooks(role, {
+        topology: query.topology,
+        taskType: query.description,
+        domain: query.domain,
+      });
+      result.rolePlaybooks.set(
+        role,
+        roleMatches.map((m) => m.playbook)
+      );
+    }
+
+    // Estimate tokens
+    result.totalTokenEstimate = this.estimateTokens(result);
+
+    return result;
+  }
+
+  // === FORMATTING ===
+
+  /**
+   * Format role guidance for injection into an agent's system prompt.
+   */
+  formatRoleGuidance(role: string, rolePlaybooks: RolePlaybook[]): string {
+    if (rolePlaybooks.length === 0) return '';
+
+    const sections: string[] = [];
+    sections.push(`## Team Role Guidance: ${role}\n`);
+
+    for (const playbook of rolePlaybooks) {
+      const confidencePercent = Math.round(playbook.confidence * 100);
+      sections.push(`### ${playbook.name} (${confidencePercent}% confidence)`);
+      sections.push(`**Your Role:** ${role} in ${playbook.teamContext.topologies.join('/')} team\n`);
+
+      // Responsibilities
+      if (playbook.guidance.responsibilities.length > 0) {
+        sections.push('**Responsibilities:**');
+        for (const resp of playbook.guidance.responsibilities) {
+          sections.push(`  - ${resp}`);
+        }
+        sections.push('');
+      }
+
+      // Interaction guidance
+      for (const ig of playbook.guidance.interactionGuidance) {
+        sections.push(`**Working with ${ig.withRole}:**`);
+        sections.push(`  - ${ig.guidance}`);
+        for (const ap of ig.antiPatterns) {
+          sections.push(`  - Avoid: ${ap}`);
+        }
+        sections.push('');
+      }
+
+      // Decision frameworks
+      for (const df of playbook.guidance.decisionFrameworks) {
+        sections.push(`**${df.name}:** When ${df.when}`);
+        sections.push(`  ${df.guidance}`);
+      }
+
+      // Anti-patterns
+      if (playbook.guidance.antiPatterns.length > 0) {
+        sections.push('**Avoid:**');
+        for (const ap of playbook.guidance.antiPatterns) {
+          sections.push(`  - ${ap}`);
+        }
+      }
+
+      sections.push('');
+    }
+
+    return sections.join('\n');
+  }
+
+  /**
+   * Format team playbook summary for team formation context.
+   */
+  formatTeamPlaybookSummary(playbooks: TeamPlaybook[]): string {
+    if (playbooks.length === 0) return '';
+
+    const sections: string[] = [];
+    sections.push('## Team Coordination Patterns\n');
+
+    for (const playbook of playbooks) {
+      const confidencePercent = Math.round(playbook.confidence * 100);
+      const successRate = getTeamPlaybookSuccessRate(playbook);
+      const successPercent = Math.round(successRate * 100);
+
+      sections.push(`### ${playbook.name} (${confidencePercent}% confidence, ${successPercent}% success rate)`);
+      sections.push(`**Topology:** ${playbook.composition.topology}`);
+      sections.push(`**Execution Model:** ${playbook.coordination.executionModel}`);
+      sections.push(`**Domains:** ${playbook.applicability.domains.join(', ')}`);
+
+      sections.push('**Roles:**');
+      for (const role of playbook.composition.roles) {
+        const optional = role.optional ? ' (optional)' : '';
+        sections.push(`  - ${role.role}${optional}: ${role.rationale}`);
+      }
+
+      if (playbook.coordination.interactionPatterns.length > 0) {
+        sections.push('**Key Patterns:**');
+        for (const pattern of playbook.coordination.interactionPatterns.slice(0, 3)) {
+          sections.push(`  - ${pattern.name}: ${pattern.description}`);
+        }
+      }
+
+      if (playbook.evolution.refinements.length > 0) {
+        sections.push('**Refinements:**');
+        for (const ref of playbook.evolution.refinements.slice(0, 2)) {
+          sections.push(`  - In ${ref.context}: ${ref.adjustment}`);
+        }
+      }
+
+      sections.push('');
+    }
+
+    return sections.join('\n');
+  }
+
+  // === OUTCOME FEEDBACK ===
+
+  /**
+   * Record team playbook outcome feedback.
+   * Updates evolution stats and recalculates confidence.
+   */
+  async recordTeamOutcome(feedback: TeamOutcomeFeedback): Promise<void> {
+    // Get all team playbooks to find the one
+    const allPlaybooks = await this.memory.getTeamPlaybooks();
+    const playbook = allPlaybooks.find((p) => p.id === feedback.playbookId);
+    if (!playbook) return;
+
+    // Update evolution counts
+    if (feedback.success) {
+      playbook.evolution.successCount++;
+      this.consecutiveFailures.set(feedback.playbookId, 0);
+    } else {
+      playbook.evolution.failureCount++;
+      const currentFailures = this.consecutiveFailures.get(feedback.playbookId) ?? 0;
+      this.consecutiveFailures.set(feedback.playbookId, currentFailures + 1);
+    }
+
+    playbook.evolution.lastUsed = new Date();
+
+    // Update average metrics if provided
+    if (feedback.metrics && feedback.success) {
+      playbook.evolution.avgMetrics = this.updateAvgMetrics(
+        playbook.evolution.avgMetrics,
+        feedback.metrics,
+        playbook.evolution.successCount
+      );
+    }
+
+    // Recalculate confidence based on track record
+    playbook.confidence = this.recalculateConfidence(playbook);
+    playbook.updatedAt = new Date();
+
+    // Store updated playbook
+    await this.memory.storeTeamPlaybook(playbook);
+  }
+
+  /**
+   * Record role playbook outcome feedback.
+   */
+  async recordRoleOutcome(feedback: RoleOutcomeFeedback): Promise<void> {
+    const allRolePlaybooks = await this.memory.getRolePlaybooks();
+    const playbook = allRolePlaybooks.find((p) => p.id === feedback.playbookId);
+    if (!playbook) return;
+
+    if (feedback.success) {
+      playbook.evolution.successCount++;
+    } else {
+      playbook.evolution.failureCount++;
+    }
+
+    playbook.evolution.lastUsed = new Date();
+    playbook.confidence = this.recalculateRoleConfidence(playbook);
+    playbook.updatedAt = new Date();
+
+    await this.memory.storeRolePlaybook(playbook);
+  }
+
+  // === ACCESSORS ===
+
+  getCoreTeamPlaybooks(): TeamPlaybook[] {
+    return [...this.coreTeamPlaybooks];
+  }
+
+  getLastRefresh(): Date | null {
+    return this.lastRefresh;
+  }
+
+  getStats(): {
+    coreTeamPlaybookCount: number;
+    lastRefresh: Date | null;
+    consecutiveFailures: Record<string, number>;
+  } {
+    const failureRecord: Record<string, number> = {};
+    for (const [id, count] of this.consecutiveFailures) {
+      if (count > 0) failureRecord[id] = count;
+    }
+
+    return {
+      coreTeamPlaybookCount: this.coreTeamPlaybooks.length,
+      lastRefresh: this.lastRefresh,
+      consecutiveFailures: failureRecord,
+    };
+  }
+
+  // === Private helpers ===
+
+  private computeRankScore(
+    relevance: number,
+    confidence: number,
+    successRate: number
+  ): number {
+    // Weighted combination: relevance 40%, confidence 30%, success rate 30%
+    return relevance * 0.4 + confidence * 0.3 + successRate * 0.3;
+  }
+
+  private recalculateConfidence(playbook: TeamPlaybook): number {
+    const total = playbook.evolution.successCount + playbook.evolution.failureCount;
+    if (total === 0) return playbook.confidence;
+
+    const successRate = playbook.evolution.successCount / total;
+    // Blend original confidence with observed success rate
+    // Weight observed data more as total increases
+    const observedWeight = Math.min(total / 10, 0.8);
+    return playbook.confidence * (1 - observedWeight) + successRate * observedWeight;
+  }
+
+  private recalculateRoleConfidence(playbook: RolePlaybook): number {
+    const total = playbook.evolution.successCount + playbook.evolution.failureCount;
+    if (total === 0) return playbook.confidence;
+
+    const successRate = playbook.evolution.successCount / total;
+    const observedWeight = Math.min(total / 10, 0.8);
+    return playbook.confidence * (1 - observedWeight) + successRate * observedWeight;
+  }
+
+  private updateAvgMetrics(
+    existing: TeamPlaybook['evolution']['avgMetrics'],
+    newMetrics: NonNullable<TeamOutcomeFeedback['metrics']>,
+    totalSuccesses: number
+  ): NonNullable<TeamPlaybook['evolution']['avgMetrics']> {
+    if (!existing || totalSuccesses <= 1) {
+      return {
+        coordinationOverhead: newMetrics.coordinationOverhead ?? 0,
+        parallelismRatio: newMetrics.parallelismRatio ?? 0,
+        timeToFirstOutput: newMetrics.timeToFirstOutput ?? 0,
+      };
+    }
+
+    // Running average
+    const n = totalSuccesses;
+    return {
+      coordinationOverhead:
+        newMetrics.coordinationOverhead !== undefined
+          ? ((existing.coordinationOverhead * (n - 1)) + newMetrics.coordinationOverhead) / n
+          : existing.coordinationOverhead,
+      parallelismRatio:
+        newMetrics.parallelismRatio !== undefined
+          ? ((existing.parallelismRatio * (n - 1)) + newMetrics.parallelismRatio) / n
+          : existing.parallelismRatio,
+      timeToFirstOutput:
+        newMetrics.timeToFirstOutput !== undefined
+          ? ((existing.timeToFirstOutput * (n - 1)) + newMetrics.timeToFirstOutput) / n
+          : existing.timeToFirstOutput,
+    };
+  }
+
+  private estimateTokens(skills: TeamAgentSkills): number {
+    let tokens = 0;
+
+    // Team playbooks: ~200 tokens each
+    tokens += (skills.coreTeamPlaybooks.length + skills.matchedTeamPlaybooks.length) * 200;
+
+    // Role playbooks: ~150 tokens each
+    for (const playbooks of skills.rolePlaybooks.values()) {
+      tokens += playbooks.length * 150;
+    }
+
+    return tokens;
+  }
+}
+
+/**
+ * Create a TeamSkillLibrary instance.
+ */
+export function createTeamSkillLibrary(
+  memory: TeamExperienceMemory,
+  config?: Partial<TeamSkillLibraryConfig>
+): TeamSkillLibrary {
+  return new TeamSkillLibrary(memory, config);
+}