cognitive-core 0.2.4 → 0.3.1

package/src/types/team-meta.ts

@@ -1,212 +0,0 @@
-/**
- * Team Meta-Learning Types
- *
- * Types for meta-learning about team formation and coordination.
- * Observes patterns about which team configurations work for which contexts.
- * The team-level analog of MetaObservation and MetaStrategy.
- */
-
-/**
- * TeamMetaObservation - Records team formation decisions and outcomes.
- * The team-level analog of MetaObservation.
- */
-export interface TeamMetaObservation {
-  id: string;
-  /** Source team trajectory */
-  teamTrajectoryId: string;
-
-  // === FORMATION DECISION ===
-  formation: FormationObservation;
-
-  // === COMPOSITION EFFECTIVENESS ===
-  compositionEffectiveness: CompositionObservation;
-
-  // === COORDINATION EFFECTIVENESS ===
-  coordinationEffectiveness: CoordinationObservation;
-
-  // === OUTCOME ===
-  outcome: TeamOutcomeObservation;
-
-  // === LESSONS ===
-  lessons: TeamLessonsLearned;
-
-  timestamp: Date;
-}
-
-/**
- * How the team was formed and why.
- */
-export interface FormationObservation {
-  /** Was a team playbook used to form this team? */
-  playbookUsed?: string;
-  /** Was the team formed from a template or ad-hoc? */
-  formationMethod: 'template' | 'playbook' | 'manual' | 'adaptive';
-  /** Confidence in the formation decision */
-  confidence: number;
-  /** Reasoning for formation choice */
-  reasoning: string;
-  /** Whether the formation was effective (DESIGN doc field) */
-  wasEffective?: boolean;
-  /** Topology type used (stored for reliable extraction in meta-learner) */
-  topologyUsed?: 'hierarchical' | 'flat' | 'wave' | 'custom';
-  /** Domain of the task */
-  domain?: string;
-}
-
-/**
- * How effective was the team composition?
- */
-export interface CompositionObservation {
-  /** Were all roles utilized? */
-  roleUtilization: Record<string, number>; // role → 0-1 utilization
-  /** Were any roles missing that would have helped? */
-  missingRoles: string[];
-  /** Were any roles redundant? */
-  redundantRoles: string[];
-  /** Was team size appropriate? */
-  teamSizeAssessment: 'too-small' | 'right-sized' | 'too-large';
-  /** Was the topology appropriate? */
-  topologyAssessment: 'effective' | 'neutral' | 'hindering';
-}
-
-/**
- * How effective was the coordination?
- */
-export interface CoordinationObservation {
-  /** Was enforcement mode appropriate? */
-  enforcementAssessment: 'too-strict' | 'appropriate' | 'too-loose';
-  /** Were communication channels well-defined? */
-  channelEffectiveness: 'helpful' | 'neutral' | 'noisy';
-  /** Were there coordination bottlenecks? */
-  bottlenecks: string[];
-  /** Actual coordination overhead ratio */
-  coordinationOverhead: number;
-}
-
-/**
- * Team outcome assessment.
- */
-export interface TeamOutcomeObservation {
-  success: boolean;
-  quality: 'excellent' | 'good' | 'acceptable' | 'poor';
-  /** Was this faster than a single agent would have been? (estimated) */
-  speedupEstimate: number; // >1 means team was faster
-  /** Cost efficiency: quality / tokens */
-  costEfficiency: number;
-}
-
-/**
- * Lessons about team formation and coordination.
- */
-export interface TeamLessonsLearned {
-  /** What team patterns worked */
-  whatWorked: string[];
-  /** What team patterns didn't work */
-  whatFailed: string[];
-  /** Suggestions for future team formation */
-  formationSuggestions: string[];
-  /** Suggestions for future coordination */
-  coordinationSuggestions: string[];
-  /** Role-specific suggestions (DESIGN doc field) */
-  roleSuggestions?: string[];
-}
-
-/**
- * TeamMetaStrategy - Learned patterns about team formation.
- * The team-level analog of MetaStrategy.
- */
-export interface TeamMetaStrategy {
-  id: string;
-  name: string;
-
-  /** When to apply this team meta-strategy */
-  condition: TeamMetaCondition;
-
-  /** What formation/coordination adjustments to make */
-  adjustment: TeamMetaAdjustment;
-
-  /** Track effectiveness */
-  applicationCount: number;
-  successRate: number;
-
-  createdAt: Date;
-  updatedAt: Date;
-}
-
-/**
- * Conditions for applying a team meta-strategy.
- */
-export interface TeamMetaCondition {
-  /** Task characteristics that trigger this strategy */
-  taskCharacteristics: string[];
-  /** Available resources */
-  resourceConstraints: string[];
-  /** Domain context */
-  domains: string[];
-}
-
-/**
- * Adjustments to team formation and coordination.
- */
-export interface TeamMetaAdjustment {
-  /** Topology recommendation */
-  topologyBias?: Record<string, number>;
-  /** Team size adjustment */
-  teamSizeAdjustment: 'increase' | 'decrease' | 'maintain';
-  /** Role adjustments */
-  roleAdjustments: string[];
-  /** Coordination hints */
-  coordinationHints: string[];
-  /** Enforcement mode recommendation */
-  enforcementBias?: 'strict' | 'permissive' | 'audit';
-}
-
-// ============================================================
-// Factory functions
-// ============================================================
-
-/**
- * Create a new team meta-observation.
- */
-export function createTeamMetaObservation(params: {
-  id?: string;
-  teamTrajectoryId: string;
-  formation: FormationObservation;
-  compositionEffectiveness: CompositionObservation;
-  coordinationEffectiveness: CoordinationObservation;
-  outcome: TeamOutcomeObservation;
-  lessons: TeamLessonsLearned;
-}): TeamMetaObservation {
-  return {
-    id: params.id ?? crypto.randomUUID(),
-    teamTrajectoryId: params.teamTrajectoryId,
-    formation: params.formation,
-    compositionEffectiveness: params.compositionEffectiveness,
-    coordinationEffectiveness: params.coordinationEffectiveness,
-    outcome: params.outcome,
-    lessons: params.lessons,
-    timestamp: new Date(),
-  };
-}
-
-/**
- * Create a new team meta-strategy.
- */
-export function createTeamMetaStrategy(params: {
-  id?: string;
-  name: string;
-  condition: TeamMetaCondition;
-  adjustment: TeamMetaAdjustment;
-}): TeamMetaStrategy {
-  const now = new Date();
-  return {
-    id: params.id ?? crypto.randomUUID(),
-    name: params.name,
-    condition: params.condition,
-    adjustment: params.adjustment,
-    applicationCount: 0,
-    successRate: 0,
-    createdAt: now,
-    updatedAt: now,
-  };
-}

package/src/types/team-playbook.ts

@@ -1,384 +0,0 @@
-/**
- * Team Playbook Types
- *
- * TeamPlaybook - Learned coordination patterns extracted from successful
- * team trajectories. The team-level analog of Playbook.
- *
- * RolePlaybook - How to be effective in a specific team role.
- * Distinct from individual task playbooks (about solving problems alone)
- * and team coordination playbooks (about team composition).
- */
-
-// ============================================================
-// Team Coordination Playbook
-// ============================================================
-
-/**
- * TeamPlaybook - Learned coordination pattern.
- * Answers: "Given this type of task, how should a team be organized and coordinated?"
- */
-export interface TeamPlaybook {
-  id: string;
-  name: string; // kebab-case, e.g. "wave-parallel-refactoring"
-
-  // === APPLICABILITY (when to use this team pattern) ===
-  applicability: TeamPlaybookApplicability;
-
-  // === COMPOSITION (what team to build) ===
-  composition: TeamCompositionGuidance;
-
-  // === COORDINATION (how the team should work together) ===
-  coordination: TeamCoordinationGuidance;
-
-  // === VERIFICATION ===
-  verification: TeamPlaybookVerification;
-
-  // === EVOLUTION ===
-  evolution: TeamPlaybookEvolution;
-
-  // === METADATA ===
-  confidence: number; // 0-1
-  complexity: 'simple' | 'moderate' | 'complex' | 'epic';
-  createdAt: Date;
-  updatedAt: Date;
-
-  // === CROSS-POLLINATION ===
-  /** Links to individual playbooks suggested for each role */
-  rolePlaybookReferences?: RolePlaybookReference[];
-}
-
-/**
- * When to use this team pattern.
- */
-export interface TeamPlaybookApplicability {
-  /** Task types this pattern works for */
-  taskTypes: string[];
-  /** Scale indicators */
-  teamSizeRange: { min: number; max: number };
-  /** Complexity levels this pattern handles */
-  complexityLevels: Array<'simple' | 'moderate' | 'complex' | 'epic'>;
-  /** Domains where this pattern has been proven */
-  domains: string[];
-  /** When NOT to use this pattern */
-  antiPatterns: string[];
-}
-
-/**
- * How to compose the team.
- */
-export interface TeamCompositionGuidance {
-  /** Recommended topology */
-  topology: 'hierarchical' | 'flat' | 'wave' | 'custom';
-  /** Role specifications */
-  roles: TeamRoleSpec[];
-  /** Spawn rules: which roles can spawn which */
-  spawnRules: Record<string, string[]>;
-  /** Recommended enforcement mode */
-  enforcement: 'strict' | 'permissive' | 'audit';
-}
-
-/**
- * Specification for a role within the team pattern.
- */
-export interface TeamRoleSpec {
-  /** Role name */
-  role: string;
-  /** Why this role is needed */
-  rationale: string;
-  /** Required capabilities */
-  capabilities: string[];
-  /** Whether this role is essential or optional */
-  optional: boolean;
-  /** Recommended model tier */
-  modelTier?: 'fast' | 'balanced' | 'capable';
-  /** Recommended spawn position */
-  spawnAs: 'root' | 'companion' | 'on-demand';
-}
-
-/**
- * How team members should coordinate.
- */
-export interface TeamCoordinationGuidance {
-  /** Execution model */
-  executionModel: 'sequential' | 'wave-parallel' | 'fully-parallel' | 'pipeline';
-  /** Communication channels to establish */
-  channels: TeamChannelSpec[];
-  /** Key interaction patterns */
-  interactionPatterns: InteractionPattern[];
-  /** Task delegation strategy */
-  delegationStrategy: string;
-  /** Checkpoint protocol */
-  checkpoints?: string[];
-}
-
-/**
- * Specification for a communication channel.
- */
-export interface TeamChannelSpec {
-  name: string;
-  signals: string[];
-  subscribers: string[]; // roles
-  emitters: string[]; // roles
-}
-
-/**
- * A learned interaction pattern between roles.
- */
-export interface InteractionPattern {
-  /** Short name */
-  name: string;
-  /** Description of when/how this pattern occurs */
-  description: string;
-  /** Roles involved */
-  roles: string[];
-  /** Frequency: how often this pattern should occur */
-  frequency: 'once' | 'per-task' | 'continuous';
-  /** Whether this pattern was correlated with success */
-  correlatedWithSuccess: boolean;
-}
-
-/**
- * How to verify the team pattern worked.
- */
-export interface TeamPlaybookVerification {
-  /** Metrics that indicate success */
-  successIndicators: string[];
-  /** Metrics that indicate failure */
-  failureIndicators: string[];
-  /** How to restructure if the pattern isn't working */
-  restructuringStrategy?: string;
-}
-
-/**
- * Evolution tracking for team playbooks.
- */
-export interface TeamPlaybookEvolution {
-  version: string;
-  /** Source team trajectory IDs */
-  createdFrom: string[];
-  /** Refinements from experience */
-  refinements: TeamRefinement[];
-  successCount: number;
-  failureCount: number;
-  lastUsed?: Date;
-  /** Average metrics across successful uses */
-  avgMetrics?: {
-    coordinationOverhead: number;
-    parallelismRatio: number;
-    timeToFirstOutput: number;
-  };
-}
-
-/**
- * Context-specific refinement to team coordination.
- */
-export interface TeamRefinement {
-  context: string;
-  adjustment: string;
-  source: 'failure' | 'success' | 'manual';
-  addedAt: Date;
-}
-
-/**
- * Cross-reference from team playbook to individual playbooks for a role.
- */
-export interface RolePlaybookReference {
-  role: string;
-  suggestedPlaybookIds: string[];
-}
-
-// ============================================================
-// Role-Specific Playbook
-// ============================================================
-
-/**
- * RolePlaybook - How to be effective in a specific team role.
- * Captures teamwork behavior from a single agent's perspective.
- */
-export interface RolePlaybook {
-  id: string;
-  name: string; // e.g., "effective-wave-planner"
-
-  // === APPLICABILITY ===
-  /** Which role this applies to */
-  role: string;
-  /** Team contexts where this guidance is relevant */
-  teamContext: RoleTeamContext;
-
-  // === ROLE GUIDANCE ===
-  guidance: RoleGuidance;
-
-  // === EVOLUTION ===
-  evolution: RolePlaybookEvolution;
-
-  // === METADATA ===
-  confidence: number; // 0-1
-  createdAt: Date;
-  updatedAt: Date;
-
-  // === CROSS-POLLINATION ===
-  /** Cross-references to individual task playbooks effective for this role */
-  relatedTaskPlaybooks?: RelatedTaskPlaybook[];
-}
-
-/**
- * Team context where a role playbook applies.
- */
-export interface RoleTeamContext {
-  topologies: Array<'hierarchical' | 'flat' | 'wave' | 'custom'>;
-  teamSizeRange: { min: number; max: number };
-  taskTypes: string[];
-  domains: string[];
-}
-
-/**
- * Guidance for a specific role.
- */
-export interface RoleGuidance {
-  /** Core responsibilities when playing this role */
-  responsibilities: string[];
-  /** How to interact with each other role */
-  interactionGuidance: RoleInteractionGuidance[];
-  /** Decision frameworks specific to this role */
-  decisionFrameworks: RoleDecisionFramework[];
-  /** Common mistakes in this role */
-  antiPatterns: string[];
-}
-
-/**
- * How to interact with a specific other role.
- */
-export interface RoleInteractionGuidance {
-  /** Which other role */
-  withRole: string;
-  /** What type of interaction */
-  interactionType: string;
-  /** How to do it effectively */
-  guidance: string;
-  /** Concrete examples from successful executions */
-  examples: string[];
-  /** What NOT to do */
-  antiPatterns: string[];
-}
-
-/**
- * Decision framework for a specific role context.
- */
-export interface RoleDecisionFramework {
-  name: string;
-  when: string;
-  guidance: string;
-}
-
-/**
- * Evolution tracking for role playbooks.
- */
-export interface RolePlaybookEvolution {
-  version: string;
-  createdFrom: string[]; // team trajectory IDs
-  refinements: TeamRefinement[];
-  successCount: number;
-  failureCount: number;
-  lastUsed?: Date;
-}
-
-/**
- * Cross-reference from role playbook to individual task playbooks.
- */
-export interface RelatedTaskPlaybook {
-  playbookId: string;
-  playbookName: string;
-  applicableToTask: string;
-  rationale: string;
-}
-
-// ============================================================
-// Factory functions
-// ============================================================
-
-/**
- * Create a new team playbook with defaults.
- */
-export function createTeamPlaybook(
-  input: Partial<TeamPlaybook> & {
-    name: string;
-    applicability: TeamPlaybookApplicability;
-    composition: TeamCompositionGuidance;
-    coordination: TeamCoordinationGuidance;
-  }
-): TeamPlaybook {
-  const now = new Date();
-  return {
-    id: input.id ?? `team-playbook-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
-    name: input.name,
-    applicability: input.applicability,
-    composition: input.composition,
-    coordination: input.coordination,
-    verification: input.verification ?? {
-      successIndicators: [],
-      failureIndicators: [],
-    },
-    evolution: input.evolution ?? {
-      version: '1.0.0',
-      createdFrom: [],
-      refinements: [],
-      successCount: 0,
-      failureCount: 0,
-    },
-    confidence: input.confidence ?? 0.3,
-    complexity: input.complexity ?? 'moderate',
-    createdAt: input.createdAt ?? now,
-    updatedAt: input.updatedAt ?? now,
-    rolePlaybookReferences: input.rolePlaybookReferences,
-  };
-}
-
-/**
- * Create a new role playbook with defaults.
- */
-export function createRolePlaybook(
-  input: Partial<RolePlaybook> & {
-    name: string;
-    role: string;
-    teamContext: RoleTeamContext;
-    guidance: RoleGuidance;
-  }
-): RolePlaybook {
-  const now = new Date();
-  return {
-    id: input.id ?? `role-playbook-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
-    name: input.name,
-    role: input.role,
-    teamContext: input.teamContext,
-    guidance: input.guidance,
-    evolution: input.evolution ?? {
-      version: '1.0.0',
-      createdFrom: [],
-      refinements: [],
-      successCount: 0,
-      failureCount: 0,
-    },
-    confidence: input.confidence ?? 0.3,
-    createdAt: input.createdAt ?? now,
-    updatedAt: input.updatedAt ?? now,
-    relatedTaskPlaybooks: input.relatedTaskPlaybooks,
-  };
-}
-
-/**
- * Get team playbook success rate.
- */
-export function getTeamPlaybookSuccessRate(playbook: TeamPlaybook): number {
-  const total = playbook.evolution.successCount + playbook.evolution.failureCount;
-  if (total === 0) return 0;
-  return playbook.evolution.successCount / total;
-}
-
-/**
- * Get role playbook success rate.
- */
-export function getRolePlaybookSuccessRate(playbook: RolePlaybook): number {
-  const total = playbook.evolution.successCount + playbook.evolution.failureCount;
-  if (total === 0) return 0;
-  return playbook.evolution.successCount / total;
-}