cognitive-core 0.1.0 → 0.2.0

package/src/types/team-meta.ts

@@ -0,0 +1,212 @@
+/**
+ * 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

@@ -0,0 +1,384 @@
+/**
+ * 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;
+}