cognitive-core 0.1.0 → 0.2.0

package/docs/PROPOSAL-team-aware-learning.md

@@ -0,0 +1,1080 @@
+# Team-Aware Learning for OpenTeams + cognitive-core
+
+## Problem Statement
+
+**cognitive-core** learns how individual agents solve problems (trajectories, playbooks, meta-strategies). **OpenTeams** defines how agents are organized into teams (topology, roles, communication channels). Neither system currently learns about *teamwork itself*:
+
+- Which team compositions work for which types of tasks?
+- Which communication topologies minimize overhead and maximize throughput?
+- Which role assignments produce the best collective outcomes?
+- What coordination patterns should be reused, and which are anti-patterns?
+
+This proposal introduces **team-aware learning** — extending both systems so that teams learn how to work together, not just how individuals solve problems.
+
+---
+
+## Architecture Overview
+
+Three new learning layers, mirroring cognitive-core's existing individual learning:
+
+| Individual (existing)     | Team (proposed)                         |
+| ------------------------- | --------------------------------------- |
+| Trajectory (agent steps)  | **TeamTrajectory** (team events)        |
+| Playbook (task patterns)  | **TeamPlaybook** (coordination patterns)|
+| MetaObservation (routing) | **TeamMetaObservation** (composition)   |
+
+The design principle: **team learning is structurally parallel to individual learning**, using the same extract → store → match → evolve cycle, but operating on team-level signals instead of agent-level ReAct steps.
+
+---
+
+## Layer 1: Team Trajectories
+
+### What It Records
+
+A `TeamTrajectory` captures the full lifecycle of a team executing a collective task. Where an individual trajectory records `thought → action → observation`, a team trajectory records **events** across all members.
+
+### Type Definitions
+
+```typescript
+// src/types/team-trajectory.ts
+
+/**
+ * A single event in a team's execution history.
+ * These are the "steps" of team-level learning.
+ */
+export interface TeamEvent {
+  /** When this event occurred */
+  timestamp: Date;
+  /** Which event type */
+  type: TeamEventType;
+  /** Which agent produced this event */
+  agentId: string;
+  /** Role of the agent at event time */
+  role: string;
+  /** Event-specific payload */
+  payload: Record<string, unknown>;
+}
+
+export type TeamEventType =
+  | 'agent_spawned'       // New member joined
+  | 'agent_shutdown'      // Member left
+  | 'task_delegated'      // Work assigned to a member
+  | 'task_completed'      // Member finished assigned work
+  | 'task_failed'         // Member failed assigned work
+  | 'signal_emitted'      // Signal sent on a channel
+  | 'message_sent'        // Direct message between members
+  | 'message_broadcast'   // Broadcast to entire team
+  | 'plan_proposed'       // A plan was proposed for approval
+  | 'plan_approved'       // A plan was approved
+  | 'plan_rejected'       // A plan was rejected
+  | 'checkpoint_reached'  // Execution checkpoint (GSD-style)
+  | 'role_changed'        // Agent's role was modified
+  | 'escalation';         // Work escalated to different role
+
+/**
+ * Interaction edge in the team communication graph.
+ * Built from events during analysis.
+ */
+export interface InteractionEdge {
+  /** Sender role */
+  from: string;
+  /** Receiver role */
+  to: string;
+  /** Number of interactions */
+  count: number;
+  /** Types of interactions */
+  types: TeamEventType[];
+  /** Average latency between send and response (ms) */
+  avgResponseLatencyMs?: number;
+}
+
+/**
+ * Coordination metrics computed from team events.
+ */
+export interface CoordinationMetrics {
+  /** Total wall time for the team execution */
+  totalWallTimeSeconds: number;
+  /** Time from team creation to first task completion */
+  timeToFirstOutputSeconds: number;
+  /** Fraction of total tokens spent on coordination vs. production */
+  coordinationOverheadRatio: number;
+  /** Agent with most inbound messages (potential bottleneck) */
+  bottleneckAgent?: string;
+  /** Number of communication cycles (back-and-forth exchanges) */
+  communicationCycles: number;
+  /** Maximum task dependency chain length executed */
+  maxDependencyDepth: number;
+  /** Number of tasks that were re-delegated after failure */
+  reDelegationCount: number;
+  /** Parallelism efficiency: tasks completed concurrently / total tasks */
+  parallelismRatio: number;
+}
+
+/**
+ * Per-member outcome within the team trajectory.
+ */
+export interface MemberOutcome {
+  agentId: string;
+  role: string;
+  tasksAssigned: number;
+  tasksCompleted: number;
+  tasksFailed: number;
+  llmCalls: number;
+  totalTokens: number;
+  /** Link to individual trajectory if available */
+  trajectoryId?: string;
+}
+
+/**
+ * TeamTrajectory - Complete record of a team's collective execution.
+ * The team-level analog of Trajectory.
+ */
+export interface TeamTrajectory {
+  id: string;
+
+  // === TEAM IDENTITY ===
+  /** Team name (from OpenTeams) */
+  teamName: string;
+  /** Template that defined this team */
+  templateName: string;
+
+  // === TEAM STRUCTURE (snapshot at execution time) ===
+  /** Topology type used */
+  topologyType: 'hierarchical' | 'flat' | 'wave' | 'custom';
+  /** Roles that participated */
+  roles: string[];
+  /** Number of agents */
+  teamSize: number;
+  /** Communication enforcement mode */
+  enforcement: 'strict' | 'permissive' | 'audit';
+
+  // === TASK ===
+  /** High-level description of what the team was trying to accomplish */
+  objective: string;
+  /** Domain of the work */
+  domain: string;
+  /** Task complexity estimate */
+  complexity: 'simple' | 'moderate' | 'complex' | 'epic';
+
+  // === EVENTS (the "steps") ===
+  events: TeamEvent[];
+
+  // === DERIVED STRUCTURE ===
+  /** Communication graph (built from events) */
+  interactionGraph: InteractionEdge[];
+  /** Coordination metrics (computed from events) */
+  metrics: CoordinationMetrics;
+
+  // === OUTCOMES ===
+  /** Per-member outcomes */
+  memberOutcomes: MemberOutcome[];
+  /** Collective outcome */
+  outcome: TeamOutcome;
+
+  /** When the trajectory was recorded */
+  timestamp: Date;
+  /** Additional metadata */
+  metadata: Record<string, unknown>;
+}
+
+/**
+ * Collective team outcome.
+ */
+export interface TeamOutcome {
+  success: boolean;
+  /** 0-1 score for partial success */
+  partialScore: number;
+  /** Quality assessment */
+  quality: 'excellent' | 'good' | 'acceptable' | 'poor';
+  /** Total LLM calls across all members */
+  totalLlmCalls: number;
+  /** Total tokens across all members */
+  totalTokens: number;
+  /** Total wall time */
+  totalWallTimeSeconds: number;
+  /** Optional error information */
+  errorInfo?: string;
+}
+```
+
+### How It Integrates
+
+**Recording** happens in OpenTeams. The signal event log already captures emissions; we extend it to produce `TeamTrajectory` objects:
+
+```
+┌─────────────────────────────────────────────────┐
+│  OpenTeams (runtime)                            │
+│                                                 │
+│  signal_events table ──► TeamTrajectoryBuilder  │
+│  messages table      ──►   (new component)      │
+│  tasks table         ──►                        │
+│  members table       ──►      │                 │
+│                               ▼                 │
+│                        TeamTrajectory           │
+│                               │                 │
+└───────────────────────────────┼─────────────────┘
+                                │
+                    export via CLI or API
+                                │
+                                ▼
+┌─────────────────────────────────────────────────┐
+│  cognitive-core                                 │
+│                                                 │
+│  TeamLearningPipeline.processTeamTrajectory()   │
+│       │                                         │
+│       ├── store in TeamExperienceMemory          │
+│       ├── analyze with TeamTrajectoryAnalyzer    │
+│       └── accumulate for batch learning          │
+│                                                 │
+└─────────────────────────────────────────────────┘
+```
+
+**OpenTeams additions:**
+- New `TeamTrajectoryBuilder` service that aggregates existing tables into `TeamTrajectory`
+- New CLI command: `openteams team export-trajectory <team-name>` to export team trajectory as JSON
+- Hook into team lifecycle: automatically build trajectory when team shuts down
+
+**cognitive-core additions:**
+- New `TeamExperienceMemory` store (parallel to `ExperienceMemory`)
+- New `TeamTrajectoryAnalyzer` (parallel to `TrajectoryAnalyzer`)
+- Extend `MemorySystem` with `teamExperiences` field
+
+---
+
+## Layer 2: Team Playbooks
+
+### What They Capture
+
+Team Playbooks are coordination patterns extracted from successful team trajectories. They answer: *"Given this type of task, how should a team be organized and coordinated?"*
+
+### Type Definitions
+
+```typescript
+// src/types/team-playbook.ts
+
+/**
+ * TeamPlaybook - Learned coordination pattern.
+ * The team-level analog of Playbook.
+ */
+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';
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * When to use this team pattern.
+ */
+export interface TeamPlaybookApplicability {
+  /** Task types this pattern works for */
+  taskTypes: string[];
+  // e.g. "full-stack feature", "large refactoring", "bug triage"
+
+  /** 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[];
+  // e.g. "single-file changes", "time-critical hotfixes"
+}
+
+/**
+ * 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;
+  // e.g. "vertical-slice decomposition", "layer-based splitting"
+
+  /** Checkpoint protocol */
+  checkpoints?: string[];
+  // e.g. "verify after planning", "human-review before merge"
+}
+
+/**
+ * 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[];
+  // e.g. "coordination overhead < 30%", "all tasks completed", "no re-delegations"
+
+  /** Metrics that indicate failure */
+  failureIndicators: string[];
+  // e.g. "bottleneck agent with >50% messages", "parallelism ratio < 0.3"
+
+  /** 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;
+  // e.g. "monorepo with >10 packages", "greenfield project"
+  adjustment: string;
+  // e.g. "add a dedicated package-coordinator role"
+  source: 'failure' | 'success' | 'manual';
+  addedAt: Date;
+}
+```
+
+### Extraction Pipeline
+
+Team playbooks are extracted from batches of successful team trajectories, following the same pattern as individual playbook extraction:
+
+```
+TeamTrajectories (batch of 5+)
+       │
+       ▼
+TeamPlaybookExtractor
+       │
+       ├── Group by task type + domain
+       │
+       ├── For each group:
+       │     ├── Identify common topology patterns
+       │     ├── Extract successful role compositions
+       │     ├── Detect effective communication patterns
+       │     ├── Compute average coordination metrics
+       │     └── Identify anti-patterns from failures
+       │
+       ├── Deduplicate against existing team playbooks
+       │
+       └── Output: new TeamPlaybooks + updates to existing ones
+```
+
+### Team Playbook Examples
+
+**Example 1: Wave-Parallel Feature Development**
+```yaml
+name: wave-parallel-feature-development
+applicability:
+  taskTypes: ["full-stack feature", "multi-component feature"]
+  teamSizeRange: { min: 3, max: 6 }
+  complexityLevels: [moderate, complex]
+  domains: [web, fullstack]
+  antiPatterns: ["single-file change", "documentation-only"]
+
+composition:
+  topology: wave
+  roles:
+    - role: planner
+      rationale: "Decomposes feature into vertical slices"
+      capabilities: [planning, decomposition, architecture]
+      optional: false
+      modelTier: capable
+      spawnAs: root
+    - role: executor
+      rationale: "Implements individual slices"
+      capabilities: [code.write, code.test, file.read]
+      optional: false
+      modelTier: balanced
+      spawnAs: on-demand
+    - role: verifier
+      rationale: "Validates integration and quality"
+      capabilities: [code.review, exec.test, quality.check]
+      optional: false
+      modelTier: capable
+      spawnAs: companion
+  enforcement: permissive
+
+coordination:
+  executionModel: wave-parallel
+  delegationStrategy: "vertical-slice decomposition"
+  channels:
+    - name: planning_events
+      signals: [PLAN_READY, WAVE_COMPLETE]
+      subscribers: [executor, verifier]
+      emitters: [planner]
+    - name: execution_events
+      signals: [TASK_DONE, TASK_FAILED, NEED_HELP]
+      subscribers: [planner, verifier]
+      emitters: [executor]
+  interactionPatterns:
+    - name: plan-then-execute
+      description: "Planner creates all tasks before any executor starts"
+      roles: [planner, executor]
+      frequency: once
+      correlatedWithSuccess: true
+    - name: direct-verifier-subscription
+      description: "Verifier subscribes directly to executor output, not via planner"
+      roles: [executor, verifier]
+      frequency: continuous
+      correlatedWithSuccess: true
+
+verification:
+  successIndicators:
+    - "coordination overhead < 25%"
+    - "all wave tasks complete before next wave"
+    - "verifier catches issues before integration"
+  failureIndicators:
+    - "executors blocked waiting for planner"
+    - "verifier not triggered until all work done"
+
+evolution:
+  version: "1.0.0"
+  createdFrom: ["team-traj-001", "team-traj-002", "team-traj-005"]
+  refinements: []
+  successCount: 5
+  failureCount: 1
+  avgMetrics:
+    coordinationOverhead: 0.22
+    parallelismRatio: 0.65
+    timeToFirstOutput: 45
+```
+
+**Example 2: Bottleneck Anti-Pattern**
+```yaml
+name: avoid-orchestrator-bottleneck
+applicability:
+  taskTypes: ["any"]
+  teamSizeRange: { min: 4, max: 999 }
+  complexityLevels: [moderate, complex, epic]
+  antiPatterns: ["teams with < 4 members"]
+
+composition:
+  # This is an anti-pattern playbook — it describes what NOT to do
+  topology: hierarchical  # the problematic topology
+
+coordination:
+  interactionPatterns:
+    - name: orchestrator-relay
+      description: "All communication routed through orchestrator creates bottleneck"
+      roles: [orchestrator]
+      frequency: continuous
+      correlatedWithSuccess: false  # anti-pattern!
+
+verification:
+  failureIndicators:
+    - "orchestrator receives >50% of all messages"
+    - "response latency increases with team size"
+    - "executors idle waiting for orchestrator response"
+  restructuringStrategy: >
+    Replace hub-and-spoke with direct peer routes for operational signals.
+    Keep orchestrator for lifecycle events only (spawn, shutdown, phase transitions).
+    Establish topic-based channels for work coordination.
+```
+
+---
+
+## Layer 3: Team Meta-Learning
+
+### What It Observes
+
+Team meta-learning observes patterns about team *formation and composition* decisions — learning which team configurations work for which contexts.
+
+### Type Definitions
+
+```typescript
+// src/types/team-meta.ts
+
+/**
+ * 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;
+}
+
+/**
+ * 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[];
+}
+
+/**
+ * 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[];
+  // e.g. "cross-cutting concern", "large codebase", "tight deadline"
+
+  /** Available resources */
+  resourceConstraints: string[];
+  // e.g. "limited token budget", "max 3 agents"
+
+  /** Domain context */
+  domains: string[];
+}
+
+/**
+ * Adjustments to team formation and coordination.
+ */
+export interface TeamMetaAdjustment {
+  /** Topology recommendation */
+  topologyBias?: Record<string, number>;
+  // e.g. { "wave": 0.8, "hierarchical": -0.3 }
+
+  /** Team size adjustment */
+  teamSizeAdjustment: 'increase' | 'decrease' | 'maintain';
+
+  /** Role adjustments */
+  roleAdjustments: string[];
+  // e.g. "add dedicated verifier for complex tasks"
+
+  /** Coordination hints */
+  coordinationHints: string[];
+  // e.g. "use direct peer routes instead of hub-and-spoke"
+
+  /** Enforcement mode recommendation */
+  enforcementBias?: 'strict' | 'permissive' | 'audit';
+}
+```
+
+---
+
+## Integration Architecture
+
+### Where Code Lives
+
+```
+cognitive-core/
+  src/
+    types/
+      team-trajectory.ts    ← NEW: TeamTrajectory, TeamEvent, etc.
+      team-playbook.ts      ← NEW: TeamPlaybook, composition/coordination guidance
+      team-meta.ts          ← NEW: TeamMetaObservation, TeamMetaStrategy
+      index.ts              ← MODIFIED: export new team types
+      config.ts             ← MODIFIED: add TeamLearningConfig
+
+    memory/
+      team-experience.ts    ← NEW: TeamExperienceMemory (stores team trajectories)
+      team-playbook.ts      ← NEW: TeamPlaybookLibrary
+      team-meta.ts          ← NEW: TeamMetaMemory
+      system.ts             ← MODIFIED: add team memory fields
+
+    learning/
+      team-pipeline.ts      ← NEW: TeamLearningPipeline
+      team-analyzer.ts      ← NEW: TeamTrajectoryAnalyzer (credit assignment for roles)
+      team-playbook-extractor.ts  ← NEW: Extract team playbooks from trajectories
+      team-meta-learner.ts  ← NEW: Learn about team formation
+
+    search/
+      team-router.ts        ← NEW: Recommend team composition for a task
+
+    surfacing/
+      team-skill-library.ts ← NEW: Surface team playbooks for team formation
+
+    atlas.ts                ← MODIFIED: add team-aware methods
+
+openteams/
+  src/
+    services/
+      trajectory-service.ts ← NEW: Build TeamTrajectory from DB state
+    cli/
+      trajectory.ts         ← NEW: CLI commands for trajectory export
+```
+
+### Data Flow
+
+```
+                    ┌───────────────────────────────┐
+                    │  OPENTEAMS (team runtime)      │
+                    │                               │
+                    │  Team executes tasks...        │
+                    │    signals emitted             │
+                    │    tasks delegated/completed   │
+                    │    messages exchanged           │
+                    │                               │
+                    │  On team shutdown:             │
+                    │    TrajectoryService.build()   │
+                    │    → TeamTrajectory JSON       │
+                    └──────────────┬────────────────┘
+                                   │
+                    ┌──────────────▼────────────────┐
+                    │  COGNITIVE-CORE               │
+                    │                               │
+                    │  atlas.processTeamTrajectory() │
+                    │       │                       │
+                    │       ├─► TeamExperienceMemory │
+                    │       ├─► TeamAnalyzer         │
+                    │       └─► accumulate           │
+                    │                               │
+                    │  When batch ready:             │
+                    │    TeamPlaybookExtractor       │
+                    │    TeamMetaLearner             │
+                    │       │                       │
+                    │       ▼                       │
+                    │  TeamPlaybook stored           │
+                    │  TeamMetaStrategy stored       │
+                    │                               │
+                    └──────────────┬────────────────┘
+                                   │
+                    ┌──────────────▼────────────────┐
+                    │  NEXT TEAM FORMATION          │
+                    │                               │
+                    │  atlas.recommendTeam(task)     │
+                    │       │                       │
+                    │       ├─► match TeamPlaybooks  │
+                    │       ├─► apply TeamMetaStrats │
+                    │       └─► return TeamPlan      │
+                    │                               │
+                    │  TeamPlan → openteams template │
+                    │  openteams team create ...     │
+                    └───────────────────────────────┘
+```
+
+### OpenTeams Schema Extensions
+
+The OpenTeams `team.yaml` schema gains optional fields to support learning feedback:
+
+```yaml
+# team.yaml additions (all optional, backwards-compatible)
+learning:
+  # Enable trajectory recording for this team
+  record_trajectory: true
+
+  # Link to cognitive-core instance for team learning
+  cognitive_core_endpoint: "http://localhost:3100"
+
+  # Team playbook this team was formed from (provenance)
+  source_playbook: "wave-parallel-feature-development"
+
+  # Objective description for trajectory recording
+  objective: "Implement user authentication with OAuth2"
+```
+
+**JSON Schema addition** (`schema/team.schema.json`):
+```json
+{
+  "learning": {
+    "type": "object",
+    "properties": {
+      "record_trajectory": { "type": "boolean", "default": false },
+      "cognitive_core_endpoint": { "type": "string", "format": "uri" },
+      "source_playbook": { "type": "string" },
+      "objective": { "type": "string" }
+    },
+    "additionalProperties": false
+  }
+}
+```
+
+---
+
+## Key APIs
+
+### cognitive-core Atlas Extensions
+
+```typescript
+// New methods on Atlas class
+
+class Atlas {
+  // ... existing methods ...
+
+  /**
+   * Process a team trajectory for learning.
+   * Team-level analog of processTrajectory().
+   */
+  async processTeamTrajectory(trajectory: TeamTrajectory): Promise<TeamProcessResult>;
+
+  /**
+   * Recommend a team composition for a given task.
+   * Uses team playbooks and meta-strategies.
+   */
+  async recommendTeam(task: {
+    description: string;
+    domain: string;
+    complexity: 'simple' | 'moderate' | 'complex' | 'epic';
+    constraints?: {
+      maxAgents?: number;
+      maxTokenBudget?: number;
+      preferredTopology?: string;
+    };
+  }): Promise<TeamRecommendation>;
+
+  /**
+   * Query team memory for coordination patterns.
+   */
+  async queryTeamMemory(
+    query: string,
+    options?: {
+      domains?: string[];
+      includeExperiences?: boolean;
+      includePlaybooks?: boolean;
+    }
+  ): Promise<TeamMemoryQueryResult>;
+
+  /**
+   * Run batch learning on accumulated team trajectories.
+   */
+  async runTeamBatchLearning(): Promise<TeamBatchResult>;
+}
+
+/**
+ * Recommendation for team composition.
+ */
+interface TeamRecommendation {
+  /** Matched team playbook (if any) */
+  playbook?: TeamPlaybook;
+  /** Recommended composition */
+  composition: TeamCompositionGuidance;
+  /** Recommended coordination */
+  coordination: TeamCoordinationGuidance;
+  /** Confidence in this recommendation */
+  confidence: number;
+  /** Reasoning */
+  reasoning: string;
+  /** Applied meta-strategies */
+  appliedMetaStrategies: string[];
+  /** Exportable as OpenTeams team.yaml */
+  asTeamYaml(): string;
+}
+```
+
+### OpenTeams CLI Extensions
+
+```bash
+# Export team trajectory after execution
+openteams trajectory export <team-name> --format json --output trajectory.json
+
+# View team coordination metrics
+openteams trajectory metrics <team-name>
+
+# Create team from cognitive-core recommendation
+openteams team create-from-recommendation --endpoint http://localhost:3100 \
+  --task "implement OAuth2 authentication" \
+  --domain "web" \
+  --complexity "complex"
+
+# Record team outcome for learning feedback
+openteams trajectory record-outcome <team-name> \
+  --success true \
+  --quality good \
+  --notes "completed with minimal coordination overhead"
+```
+
+---
+
+## Configuration
+
+New section in `AtlasConfig`:
+
+```typescript
+export const TeamLearningConfigSchema = z.object({
+  /** Enable team-aware learning */
+  enabled: z.boolean().default(false),
+
+  /** Minimum team trajectories before batch learning */
+  minTrajectories: z.number().default(5),
+
+  /** Similarity threshold for team playbook deduplication */
+  deduplicationThreshold: z.number().min(0).max(1).default(0.85),
+
+  /** Weight given to coordination metrics vs. outcome in evaluation */
+  metricsWeight: z.number().min(0).max(1).default(0.3),
+
+  /** Maximum team experiences to store */
+  maxExperiences: z.number().default(200),
+
+  /** Maximum team playbooks to store */
+  maxPlaybooks: z.number().default(50),
+});
+
+// Added to AtlasConfigSchema:
+// teamLearning: TeamLearningConfigSchema.default({})
+```
+
+---
+
+## Storage Layout
+
+```
+.atlas/
+├── experiences/           # Individual agent experiences (existing)
+├── playbooks/             # Individual playbooks (existing)
+├── meta-observations/     # Individual meta-observations (existing)
+├── meta-strategies/       # Individual meta-strategies (existing)
+│
+├── team-experiences/      # NEW: Team trajectory experiences
+├── team-playbooks/        # NEW: Team coordination playbooks
+├── team-meta-observations/ # NEW: Team formation observations
+├── team-meta-strategies/  # NEW: Team formation meta-strategies
+│
+└── vectors.db             # Vector store (extended with team embeddings)
+```
+
+---
+
+## Implementation Phases
+
+### Phase 1: Types + Recording (Foundation)
+- Define all team types (`team-trajectory.ts`, `team-playbook.ts`, `team-meta.ts`)
+- Implement `TeamTrajectoryBuilder` in OpenTeams
+- Implement `TeamExperienceMemory` in cognitive-core
+- Add `processTeamTrajectory()` to Atlas
+- CLI: `openteams trajectory export`
+
+### Phase 2: Extraction + Storage (Learning)
+- Implement `TeamTrajectoryAnalyzer` (coordination metrics computation, role credit assignment)
+- Implement `TeamPlaybookExtractor` (pattern extraction from team trajectory batches)
+- Implement `TeamPlaybookLibrary` (storage + matching)
+- Implement `TeamLearningPipeline` (orchestration)
+- CLI: `openteams trajectory metrics`
+
+### Phase 3: Recommendation + Meta-Learning (Application)
+- Implement `TeamRouter` (recommend team composition for a task)
+- Implement `TeamMetaLearner` (learn about formation decisions)
+- Implement `recommendTeam()` on Atlas
+- Implement `asTeamYaml()` export for seamless OpenTeams integration
+- CLI: `openteams team create-from-recommendation`
+
+### Phase 4: Surfacing + Feedback Loop (Maturity)
+- Implement `TeamSkillLibrary` (tiered team playbook surfacing)
+- Implement outcome recording feedback loop
+- Implement team playbook evolution (version bumps, refinements)
+- Cross-pollination: individual playbooks reference team context, team playbooks reference individual capabilities
+
+---
+
+## Design Decisions + Rationale
+
+**1. Structural parallelism with individual learning**
+Every team construct mirrors an individual one (TeamTrajectory ↔ Trajectory, TeamPlaybook ↔ Playbook, TeamMetaObservation ↔ MetaObservation). This means the same learning patterns (extract → store → match → evolve) work at both levels, and developers familiar with one level immediately understand the other.
+
+**2. Loose coupling between OpenTeams and cognitive-core**
+The integration point is the `TeamTrajectory` JSON format. OpenTeams exports it; cognitive-core imports it. Neither depends on the other at the code level. This preserves OpenTeams as a standalone standard while cognitive-core as a standalone learning system.
+
+**3. Team playbooks output OpenTeams-compatible YAML**
+The `asTeamYaml()` method on `TeamRecommendation` generates valid OpenTeams `team.yaml` manifests. This closes the loop: learn from teams → recommend teams → create teams using the same standard.
+
+**4. Coordination metrics over raw events**
+Rather than pattern-matching on raw event sequences (brittle), we compute derived metrics (coordination overhead, parallelism ratio, bottleneck detection) and learn patterns from those. This is more robust to variations in team execution order.
+
+**5. Backwards-compatible schema extensions**
+All OpenTeams schema additions are optional. Existing team manifests continue to work without modification. The `learning` field is purely additive.
+
+---
+
+## Open Questions
+
+1. **Cross-team learning**: Should team playbooks be shared across organizations/projects, or scoped to a single deployment? (Likely configurable via storage namespacing.)
+
+2. **Real-time adaptation**: Should a running team be able to query cognitive-core mid-execution to adapt its coordination? (Phase 4+ consideration — start with post-hoc learning.)
+
+3. **Individual ↔ Team interaction**: When a team playbook recommends a "verifier" role, should it reference individual playbooks that work well for verification tasks? (Yes, but as a Phase 4 cross-reference, not a hard dependency.)
+
+4. **Evaluation methodology**: How do we assess team playbook quality? Individual playbook confidence is based on success/failure counts. For teams, should we also weight coordination efficiency, token cost, and speedup over single-agent execution?