cognitive-core 0.1.0 → 0.2.0

package/docs/DESIGN-team-extraction-pipeline.md

@@ -0,0 +1,1369 @@
+# Design: Team Knowledge Extraction Pipeline
+
+## Overview
+
+This document describes the pipeline that transforms raw multi-agent team execution data into reusable knowledge. It builds on the research findings in `RESEARCH-team-trajectory-learning.md` and the team-aware learning proposal in `PROPOSAL-team-aware-learning.md`.
+
+The pipeline mirrors the existing individual learning pipeline (`LearningPipeline.processTrajectory()` → `TrajectoryAnalyzer` → `PlaybookExtractor`), but operates on a **graph of interconnected trajectories** rather than a single linear trajectory, and uses **agentic analysis** rather than direct LLM calls.
+
+---
+
+## Core Design Decisions
+
+### 1. Team trajectory as a graph, not a flat event stream
+
+A team trajectory is a set of individual `Trajectory` objects (nodes) connected by `AgentInteraction` edges. Individual trajectories are the existing type, unchanged. The interactions form a causal DAG overlaid on the linear trajectories.
+
+### 2. Agentic analysis, not raw LLM calls
+
+The analysis phases spawn full agents (via the existing `AgentManager`) with filesystem workspaces, tool access, and injected knowledge. This allows iterative, tool-assisted analysis rather than single-prompt extraction. The analysis agents' own trajectories are captured for meta-learning.
+
+### 3. Three playbook types emerge from team analysis
+
+- **Role playbooks**: How to be effective in a specific team role (surfaced to agents when assigned roles)
+- **Team coordination playbooks**: How to compose and coordinate a team (surfaced during team formation)
+- **Meta-learning signals**: Observations about team formation decisions and analysis quality (fed back into routing and future analysis)
+
+### 4. Compression and critical step identification combined
+
+A single computational pass reduces the data before expensive agentic analysis. Simple structural methods first (pattern stripping, step folding), LLM summarization only as fallback.
+
+---
+
+## Phase 1-2: Ingest, Compress, Prepare Workspace
+
+### Input
+
+The entry point receives individual trajectories tagged with interaction metadata at runtime by OpenTeams:
+
+```typescript
+interface TeamTrajectoryInput {
+  /** High-level objective */
+  objective: string;
+  domain: string;
+  complexity: 'simple' | 'moderate' | 'complex' | 'epic';
+
+  /** Team structure snapshot */
+  teamName: string;
+  templateName: string;
+  topologyType: 'hierarchical' | 'flat' | 'wave' | 'custom';
+  enforcement: 'strict' | 'permissive' | 'audit';
+
+  /** Individual trajectories with interaction tags in step metadata */
+  memberTrajectories: {
+    agentId: string;
+    role: string;
+    trajectory: Trajectory;  // existing type, unchanged
+  }[];
+
+  /** Declared expected interaction patterns from team.yaml */
+  expectedPatterns?: ExpectedInteractionPattern[];
+
+  /** Team-level outcome */
+  outcome: TeamOutcome;
+}
+```
+
+Runtime interaction tagging ensures each cross-agent step has metadata:
+
+```typescript
+// Present in step.metadata when the step involves another agent
+interface InteractionTag {
+  interactionId: string;           // shared ID linking source + target
+  interactionType: InteractionType;
+  counterpartAgentId: string;
+  stepRole: 'source' | 'target';
+  channel?: string;                // for signal interactions
+  signal?: string;                 // for signal interactions
+}
+
+type InteractionType =
+  | 'delegation'
+  | 'result_return'
+  | 'message'
+  | 'signal'
+  | 'spawn'
+  | 'escalation';
+```
+
+### Processing
+
+This phase is entirely computational — no LLM calls.
+
+```typescript
+class TeamTrajectoryIngester {
+  /**
+   * Build graph, compress, identify critical moments, prepare workspace.
+   * Combines what was previously Phases 1-3 into a single pass.
+   */
+  async ingest(input: TeamTrajectoryInput): Promise<AnalysisWorkspace> {
+
+    // 1. BUILD INTERACTION GRAPH
+    //    - Extract interaction tags from all member step metadata
+    //    - Group by interactionId, link source step to target step
+    //    - Validate: no dangling edges, timestamps monotonic
+    //    - Flag interactions as expected vs emergent
+    //      (compare to input.expectedPatterns)
+
+    // 2. COMPUTE STRUCTURAL METRICS
+    //    - Per-agent: step count, tool calls, tokens, outcome
+    //    - Per-interaction: latency, content length, type distribution
+    //    - Graph-level: interaction density, max in/out degree,
+    //      bottleneck detection, parallelism ratio
+
+    // 3. COMPRESS PER-AGENT TRAJECTORIES
+    //    - Identify interaction boundary steps (tagged with interactionId)
+    //      → always preserve at full fidelity
+    //    - Between boundaries, fold internal steps:
+    //      structural first (strip verbose output, collapse consecutive
+    //      non-key steps), LLM fallback only if still over budget
+    //    - Remove token waste: repeated failed attempts (keep first + last),
+    //      full file contents in observations, long stack traces
+
+    // 4. SCORE STEPS AND INTERACTIONS
+    //    - Step scores: promise (position-based) + progress (action type)
+    //      + interaction bonus (boundary steps score higher)
+    //    - Interaction scores: downstream success + latency penalty
+    //      + expected pattern bonus + information density
+    //    - Mark top ~20% as critical
+
+    // 5. PREPARE WORKSPACE FILESYSTEM
+    //    - Write compressed trajectories, interaction graph, metrics,
+    //      team config, outcome, and critical moment annotations
+    //      to a temporary workspace directory
+
+    return workspace;
+  }
+}
+```
+
+### Output: The Analysis Workspace
+
+The workspace is a filesystem directory that the analysis agent will use as its working environment:
+
+```
+/tmp/team-analysis-{id}/
+├── input/                          # Read-only context for the agent
+│   ├── objective.md                # Team objective + domain + complexity
+│   ├── team-config.json            # Topology, roles, expected patterns,
+│   │                               #   enforcement mode
+│   ├── outcome.json                # Team outcome + per-member outcomes
+│   ├── structural-metrics.json     # Graph-level metrics computed above
+│   ├── critical-moments.json       # Annotated critical steps/interactions
+│   │                               #   with scores
+│   ├── trajectories/
+│   │   ├── planner.json            # Compressed trajectory for planner
+│   │   ├── executor-1.json         # Compressed trajectory for executor-1
+│   │   ├── executor-2.json         # etc.
+│   │   └── verifier.json
+│   └── interactions/
+│       ├── graph.json              # Interaction edges with timing, content,
+│       │                           #   expected/emergent flags
+│       └── timeline.json           # Same interactions in chronological order
+│
+├── workspace/                      # Agent's scratch space (read-write)
+│   └── (agent creates notes, intermediate analysis, etc.)
+│
+└── output/                         # Agent writes structured results here
+    ├── agent-credits.json          # Per-agent contribution assessment
+    ├── interaction-credits.json    # Per-interaction value assessment
+    ├── coordination-assessment.json # Overall pattern analysis
+    ├── role-lessons/               # Per-role insights
+    │   ├── planner.json
+    │   ├── executor.json
+    │   └── verifier.json
+    ├── team-lessons.json           # Team-level coordination insights
+    └── meta-observations.json      # Observations about team formation
+```
+
+### Key Types
+
+```typescript
+interface AnalysisWorkspace {
+  /** Workspace root directory */
+  path: string;
+
+  /** The built team trajectory (full graph structure) */
+  teamTrajectory: TeamTrajectory;
+
+  /** Compression statistics */
+  compressionStats: {
+    originalTokens: number;
+    compressedTokens: number;
+    ratio: number;
+    stepsPreserved: number;
+    stepsFolded: number;
+  };
+
+  /** Critical moment annotations */
+  criticalMoments: {
+    criticalSteps: Map<string, CriticalStep[]>;
+    criticalInteractions: CriticalInteraction[];
+    totalSteps: number;
+    criticalRatio: number;
+  };
+}
+
+interface TeamTrajectory {
+  id: string;
+  objective: string;
+  domain: string;
+  complexity: 'simple' | 'moderate' | 'complex' | 'epic';
+
+  teamName: string;
+  templateName: string;
+  topologyType: 'hierarchical' | 'flat' | 'wave' | 'custom';
+
+  members: MemberTrajectory[];
+  interactions: AgentInteraction[];
+  expectedPatterns: ExpectedInteractionPattern[];
+
+  outcome: TeamOutcome;
+  structuralMetrics: StructuralMetrics;
+
+  timestamp: Date;
+  metadata: Record<string, unknown>;
+}
+
+interface MemberTrajectory {
+  agentId: string;
+  role: string;
+  trajectory: Trajectory;  // existing cognitive-core type
+}
+
+interface AgentInteraction {
+  id: string;
+  type: InteractionType;
+  from: { agentId: string; role: string; stepIndex: number };
+  to: { agentId: string; role: string; stepIndex: number };
+  content: string;
+  channel?: string;
+  signal?: string;
+  timestamp: Date;
+  latencyMs?: number;
+  wasExpected: boolean;
+}
+
+interface StructuralMetrics {
+  teamSize: number;
+  totalSteps: number;
+  totalInteractions: number;
+  interactionDensity: number;       // interactions / steps
+  maxInDegree: { agentId: string; count: number };
+  maxOutDegree: { agentId: string; count: number };
+  parallelismRatio: number;
+  totalWallTimeSeconds: number;
+  totalTokens: number;
+}
+
+interface CriticalStep {
+  agentId: string;
+  role: string;
+  stepIndex: number;
+  step: Step;
+  scores: {
+    promise: number;
+    progress: number;
+    interactionBonus: number;
+    total: number;
+  };
+}
+
+interface CriticalInteraction {
+  interaction: AgentInteraction;
+  scores: {
+    downstreamSuccess: number;
+    latencyPenalty: number;
+    expectedBonus: number;
+    informationDensity: number;
+    total: number;
+  };
+}
+```
+
+### Compression Configuration
+
+```typescript
+interface CompressionConfig {
+  /** Max tokens per agent trajectory after compression */
+  maxTokensPerAgent: number;  // default: 5000
+
+  /** Always preserve steps at interaction boundaries */
+  preserveInteractionBoundaries: boolean;  // default: true
+
+  /** Max consecutive non-interaction steps before folding */
+  foldThreshold: number;  // default: 5
+
+  /** Patterns to strip from observations (verbose tool output, etc.) */
+  stripPatterns: RegExp[];  // default: common verbose patterns
+
+  /** Fraction of steps to mark as critical */
+  maxCriticalRatio: number;  // default: 0.25
+
+  /** Minimum score threshold for critical steps */
+  criticalStepThreshold: number;  // default: 0.3
+
+  /** Minimum score threshold for critical interactions */
+  criticalInteractionThreshold: number;  // default: 0.3
+}
+```
+
+---
+
+## Phase 3: Agentic Analysis
+
+### Design Philosophy
+
+Instead of `llmClient.complete(prompt)` returning structured JSON, we spawn a full agent via the existing `AgentManager`. The analysis agent gets:
+
+- A **filesystem workspace** with the trajectory data as files it can selectively read
+- **Tool access** to search, read, write, and compute — the same tools any Claude Code agent has
+- **Injected knowledge** from past team analysis (team playbooks, analysis meta-playbooks, similar team experiences)
+- **Trajectory capture** — the agent's own execution is recorded and fed through the individual learning pipeline, producing meta-learning about how to analyze teams
+
+This uses the exact same infrastructure as task-solving agents. The only difference is the "task" is analysis rather than implementation.
+
+### Agent Spawn Configuration
+
+Maps directly to the existing `AgentSpawnConfig`:
+
+```typescript
+function buildAnalysisSpawnConfig(
+  workspace: AnalysisWorkspace,
+  injectedKnowledge: MemoryQueryResultV2
+): AgentSpawnConfig {
+  return {
+    agentType: 'claude-code',
+
+    task: {
+      id: `team-analysis-${workspace.teamTrajectory.id}`,
+      domain: 'team-analysis',
+      description: ANALYSIS_TASK_PROMPT,  // see below
+      context: {
+        teamTrajectoryId: workspace.teamTrajectory.id,
+        objective: workspace.teamTrajectory.objective,
+        teamSize: workspace.teamTrajectory.members.length,
+        topologyType: workspace.teamTrajectory.topologyType,
+        outcome: workspace.teamTrajectory.outcome,
+        compressionRatio: workspace.compressionStats.ratio,
+        criticalRatio: workspace.criticalMoments.criticalRatio,
+      },
+    },
+
+    cwd: workspace.path,
+    injectedKnowledge,
+    captureToolCalls: true,
+    timeout: 300_000,  // 5 minutes for analysis
+  };
+}
+```
+
+### Analysis Task Prompt
+
+The agent receives a task description that explains the workspace layout and expected output:
+
+```typescript
+const ANALYSIS_TASK_PROMPT = `
+Analyze a multi-agent team execution and extract learning signals.
+
+## Workspace Layout
+
+input/                          - Read-only team execution data
+  objective.md                  - What the team was trying to accomplish
+  team-config.json              - Team structure and expected interaction patterns
+  outcome.json                  - Team and per-member outcomes
+  structural-metrics.json       - Pre-computed graph metrics
+  critical-moments.json         - Steps and interactions flagged as high-impact
+  trajectories/                 - Per-agent compressed execution traces
+  interactions/
+    graph.json                  - Interaction edges between agents
+    timeline.json               - Chronological interaction sequence
+
+workspace/                      - Your scratch space for notes and analysis
+
+output/                         - Write your structured analysis here
+
+## Your Task
+
+1. Read the objective, outcome, and team config to understand the context.
+
+2. Examine the interaction graph and structural metrics to identify
+   coordination patterns, bottlenecks, and communication efficiency.
+
+3. Read the critical moments annotations, then selectively read the
+   relevant compressed trajectories to understand what happened at
+   each critical step.
+
+4. For each agent/role, assess their contribution to the team outcome.
+   Write per-agent credit assessments to output/agent-credits.json.
+
+5. For each critical interaction, assess whether it was helpful, neutral,
+   or harmful. Write to output/interaction-credits.json.
+
+6. Identify coordination patterns (both designed and emergent) and
+   anti-patterns. Write to output/coordination-assessment.json.
+
+7. Extract role-specific lessons — what each role did well and what
+   could improve. Write to output/role-lessons/{role}.json.
+
+8. Extract team-level lessons about composition and coordination.
+   Write to output/team-lessons.json.
+
+9. Record observations about the team formation decision itself.
+   Write to output/meta-observations.json.
+
+Use the workspace/ directory for any intermediate notes or analysis.
+Refer to critical-moments.json to focus your analysis on the steps
+and interactions that most influenced the outcome.
+`;
+```
+
+### Knowledge Injection
+
+The analysis agent receives three types of injected knowledge:
+
+```typescript
+async function getAnalysisKnowledge(
+  memory: MemorySystem,
+  teamMemory: TeamMemorySystem,
+  workspace: AnalysisWorkspace
+): Promise<MemoryQueryResultV2> {
+
+  // 1. Team playbooks for similar task types
+  //    So the agent knows what "good" team coordination looks like
+  const teamPlaybooks = await teamMemory.findMatchingTeamPlaybooks({
+    taskType: workspace.teamTrajectory.objective,
+    domain: workspace.teamTrajectory.domain,
+    topology: workspace.teamTrajectory.topologyType,
+  });
+
+  // 2. Past team analysis experiences
+  //    So the agent can see how similar teams were analyzed before
+  const pastAnalyses = await teamMemory.findSimilarTeamExperiences({
+    objective: workspace.teamTrajectory.objective,
+    domain: workspace.teamTrajectory.domain,
+  });
+
+  // 3. Analysis meta-playbooks
+  //    Playbooks about HOW to analyze (learned from past analysis agents)
+  //    These live in the regular playbook library under domain "team-analysis"
+  const analysisPlaybooks = await memory.queryV2(
+    'analyze multi-agent team execution extract learning signals',
+    { domains: ['team-analysis'] }
+  );
+
+  return mergeKnowledge(teamPlaybooks, pastAnalyses, analysisPlaybooks);
+}
+```
+
+The agent's system prompt includes both task-specific team playbooks and analysis meta-playbooks:
+
+```markdown
+## Atlas Knowledge
+
+### Applicable Team Playbooks
+#### wave-parallel-feature-development (78% match)
+**Composition:** planner + executors + verifier in wave topology
+**Key Patterns:**
+  - plan-then-execute: Planner creates all tasks before executors start
+  - direct-verifier-subscription: Verifier subscribes to executor output
+**Success Indicators:**
+  - coordination overhead < 25%
+  - all wave tasks complete before next wave
+
+### Analysis Guidance
+#### team-bottleneck-detection (92% confidence)
+**Strategy:** For teams with >4 agents, check interaction graph
+  in-degree first to identify bottleneck agents
+**Tactics:**
+  - Read structural-metrics.json maxInDegree before trajectories
+  - Compare actual interaction patterns to expected patterns
+  - Bottleneck agents often have >40% of inbound interactions
+```
+
+### The Meta-Learning Feedback Loop
+
+The analysis agent's own trajectory is captured via the existing `DefaultTrajectoryExtractor` and fed through the individual `LearningPipeline`:
+
+```
+Analysis agent executes
+    │
+    ├─ AgentManager.spawn() → AgentSession
+    ├─ DefaultTrajectoryExtractor.extract() → Trajectory
+    │     (domain: "team-analysis")
+    │
+    ├─ LearningPipeline.processTrajectory()
+    │     → TrajectoryAnalyzer.analyze()
+    │     → ExperienceMemory.store()
+    │     → accumulate for batch learning
+    │
+    └─ Eventually: PlaybookExtractor.extract()
+          → Playbooks in domain "team-analysis"
+          → Injected into FUTURE analysis agents
+```
+
+Over time, the system learns how to analyze teams better:
+
+- "Reading structural-metrics.json before trajectories leads to faster bottleneck identification"
+- "Writing notes in workspace/notes.md before producing output improves analysis quality"
+- "For large teams (>5 agents), focus on interaction graph topology before individual trajectories"
+
+These become playbooks in the "team-analysis" domain, surfaced via the existing `SkillLibrary` to future analysis agents.
+
+### Output Schema
+
+The analysis agent writes JSON files to the `output/` directory. The pipeline reads and validates them after the agent completes.
+
+```typescript
+// output/agent-credits.json
+interface AgentCreditOutput {
+  credits: AgentCredit[];
+}
+
+interface AgentCredit {
+  agentId: string;
+  role: string;
+  /** Overall contribution to team outcome, 0-1 */
+  contributionScore: number;
+  /** Natural language assessment of this agent's performance */
+  assessment: string;
+  /** Per-critical-step attribution with reasoning */
+  stepAttributions: {
+    stepIndex: number;
+    attribution: number;  // -1 to 1
+    reasoning: string;
+  }[];
+  /** Was this role necessary for this task? */
+  roleAssessment: 'essential' | 'helpful' | 'neutral' | 'redundant';
+}
+
+// output/interaction-credits.json
+interface InteractionCreditOutput {
+  credits: InteractionCredit[];
+}
+
+interface InteractionCredit {
+  interactionId: string;
+  type: InteractionType;
+  fromRole: string;
+  toRole: string;
+  /** Was this interaction helpful, neutral, or harmful? */
+  value: 'helpful' | 'neutral' | 'harmful';
+  /** Credit score, -1 to 1 */
+  creditScore: number;
+  /** Natural language explanation */
+  reasoning: string;
+  /** Was this interaction necessary? */
+  necessity: 'critical' | 'useful' | 'unnecessary' | 'harmful';
+  /** How well-specified was the exchanged information? 0-1 */
+  contentQuality: number;
+}
+
+// output/coordination-assessment.json
+interface CoordinationAssessmentOutput {
+  /** Overall coordination quality */
+  quality: 'excellent' | 'good' | 'acceptable' | 'poor';
+  /** Coordination patterns observed */
+  observedPatterns: {
+    name: string;
+    description: string;
+    roles: string[];
+    interactionIds: string[];
+    correlatedWithSuccess: boolean;
+  }[];
+  /** Anti-patterns observed */
+  observedAntiPatterns: {
+    name: string;
+    description: string;
+    roles: string[];
+    interactionIds: string[];
+    impact: string;
+    suggestedFix: string;
+  }[];
+  /** Comparison to expected patterns from team.yaml */
+  patternComparison: {
+    expected: string;
+    observed: 'followed' | 'deviated' | 'absent';
+    impact: string;
+  }[];
+  /** Emergent coordination not declared but observed */
+  emergentCoordination: {
+    description: string;
+    wasHelpful: boolean;
+    shouldBeFormalized: boolean;
+  }[];
+  /** 2-3 paragraph narrative summary */
+  narrative: string;
+}
+
+// output/role-lessons/{role}.json
+interface RoleLessonOutput {
+  role: string;
+  agentId: string;
+  /** What this role did well */
+  strengths: string[];
+  /** What this role could improve */
+  improvements: string[];
+  /** Role necessity for this type of task */
+  roleAssessment: 'essential' | 'helpful' | 'neutral' | 'redundant';
+  /** How this role interacted with other roles */
+  interactionAssessment: {
+    withRole: string;
+    interactionType: InteractionType;
+    quality: 'effective' | 'adequate' | 'poor';
+    observation: string;
+    recommendation: string;
+  }[];
+  /** Evidence from the trajectory */
+  evidence: {
+    stepIndex: number;
+    description: string;
+  }[];
+}
+
+// output/team-lessons.json
+interface TeamLessonsOutput {
+  /** Lessons about team composition */
+  compositionLessons: {
+    category: 'role-necessity' | 'team-size' | 'topology' | 'model-selection';
+    lesson: string;
+    evidence: string;
+    confidence: number;
+  }[];
+  /** Lessons about coordination */
+  coordinationLessons: {
+    category: 'delegation' | 'communication' | 'synchronization' | 'escalation';
+    lesson: string;
+    evidence: string;
+    confidence: number;
+  }[];
+  /** What the team should do differently */
+  recommendations: string[];
+}
+
+// output/meta-observations.json
+interface TeamMetaObservationOutput {
+  /** Was the team formation effective? */
+  formation: {
+    wasEffective: boolean;
+    reasoning: string;
+  };
+  /** Was the composition right? */
+  composition: {
+    roleUtilization: Record<string, number>;
+    missingRoles: string[];
+    redundantRoles: string[];
+    teamSizeAssessment: 'too-small' | 'right-sized' | 'too-large';
+  };
+  /** Was the coordination approach right? */
+  coordination: {
+    topologyAssessment: 'effective' | 'neutral' | 'hindering';
+    enforcementAssessment: 'too-strict' | 'appropriate' | 'too-loose';
+    emergentPatterns: string[];
+  };
+  /** Suggestions for future team formation */
+  formationSuggestions: string[];
+  coordinationSuggestions: string[];
+}
+```
+
+---
+
+## Phase 4: Collect, Store, Accumulate
+
+After the analysis agent completes, the pipeline reads the output files, validates them, and stores the results.
+
+```typescript
+class TeamAnalysisCollector {
+  async collect(
+    workspace: AnalysisWorkspace,
+    analysisAgentResult: AgentResult
+  ): Promise<TeamAnalysisResult> {
+
+    // 1. READ AND VALIDATE agent output files
+    const agentCredits = await this.readAndValidate<AgentCreditOutput>(
+      `${workspace.path}/output/agent-credits.json`
+    );
+    const interactionCredits = await this.readAndValidate<InteractionCreditOutput>(
+      `${workspace.path}/output/interaction-credits.json`
+    );
+    const coordination = await this.readAndValidate<CoordinationAssessmentOutput>(
+      `${workspace.path}/output/coordination-assessment.json`
+    );
+    const roleLessons = await this.readRoleLessons(
+      `${workspace.path}/output/role-lessons/`
+    );
+    const teamLessons = await this.readAndValidate<TeamLessonsOutput>(
+      `${workspace.path}/output/team-lessons.json`
+    );
+    const metaObs = await this.readAndValidate<TeamMetaObservationOutput>(
+      `${workspace.path}/output/meta-observations.json`
+    );
+
+    // 2. ASSEMBLE into TeamAnalysisResult
+    const result: TeamAnalysisResult = {
+      teamTrajectoryId: workspace.teamTrajectory.id,
+      agentCredits: agentCredits.credits,
+      interactionCredits: interactionCredits.credits,
+      coordinationAssessment: coordination,
+      roleLessons,
+      teamLessons,
+      metaObservation: metaObs,
+      analysisMetrics: {
+        analysisTokens: analysisAgentResult.metrics.tokenEstimate ?? 0,
+        analysisTimeMs: analysisAgentResult.metrics.totalTime,
+        analysisToolCalls: analysisAgentResult.metrics.toolCallCount,
+      },
+    };
+
+    // 3. STORE in TeamExperienceMemory
+    await this.teamMemory.storeTeamExperience({
+      teamTrajectory: workspace.teamTrajectory,
+      analysis: result,
+    });
+
+    // 4. RECORD TeamMetaObservation
+    await this.teamMemory.recordMetaObservation({
+      teamTrajectoryId: workspace.teamTrajectory.id,
+      ...metaObs,
+      outcome: {
+        success: workspace.teamTrajectory.outcome.success,
+        quality: this.assessQuality(workspace.teamTrajectory.outcome),
+      },
+      timestamp: new Date(),
+    });
+
+    // 5. ACCUMULATE lessons for batch playbook extraction
+    this.accumulated.push({
+      teamTrajectoryId: workspace.teamTrajectory.id,
+      objective: workspace.teamTrajectory.objective,
+      domain: workspace.teamTrajectory.domain,
+      topologyType: workspace.teamTrajectory.topologyType,
+      outcome: workspace.teamTrajectory.outcome,
+      roleLessons,
+      teamLessons,
+      coordinationAssessment: coordination,
+      agentCredits: agentCredits.credits,
+    });
+
+    // 6. PROCESS ANALYSIS AGENT'S OWN TRAJECTORY
+    //    through existing individual learning pipeline
+    await this.individualPipeline.processTrajectory(
+      analysisAgentResult.trajectory
+    );
+
+    // 7. CLEANUP workspace
+    await this.cleanupWorkspace(workspace.path);
+
+    return result;
+  }
+}
+```
+
+---
+
+## Phase 5: Batch Playbook Distillation
+
+Triggered when enough team lessons have accumulated (configurable threshold, default 5). This phase also uses agentic analysis — a playbook extraction agent examines the batch and produces/updates playbooks.
+
+### Three Playbook Types
+
+#### Type 1: Role-Specific Playbooks
+
+*"How to be effective in this role within this type of team."*
+
+These are distinct from individual task playbooks (which are about solving problems alone) and from team coordination playbooks (which are about team composition). Role playbooks capture **teamwork behavior from a single agent's perspective**.
+
+```typescript
+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: {
+    topologies: ('hierarchical' | 'flat' | 'wave' | 'custom')[];
+    teamSizeRange: { min: number; max: number };
+    taskTypes: string[];
+    domains: string[];
+  };
+
+  // === ROLE GUIDANCE ===
+  guidance: {
+    /** Core responsibilities when playing this role */
+    responsibilities: string[];
+
+    /** How to interact with each other role */
+    interactionGuidance: RoleInteractionGuidance[];
+
+    /** Decision frameworks specific to this role */
+    decisionFrameworks: {
+      name: string;
+      when: string;
+      guidance: string;
+    }[];
+
+    /** Common mistakes in this role */
+    antiPatterns: string[];
+  };
+
+  // === EVOLUTION ===
+  evolution: {
+    version: string;
+    createdFrom: string[];  // team trajectory IDs
+    refinements: Refinement[];
+    successCount: number;
+    failureCount: number;
+    lastUsed?: Date;
+  };
+  confidence: number;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+interface RoleInteractionGuidance {
+  /** Which other role */
+  withRole: string;
+  /** What type of interaction */
+  interactionType: InteractionType;
+  /** How to do it effectively */
+  guidance: string;
+  /** Concrete examples from successful executions */
+  examples: string[];
+  /** What NOT to do */
+  antiPatterns: string[];
+}
+```
+
+**Example:**
+
+```yaml
+name: effective-wave-executor
+role: executor
+teamContext:
+  topologies: [wave]
+  teamSizeRange: { min: 3, max: 6 }
+  taskTypes: [full-stack-feature, multi-component-feature]
+
+guidance:
+  responsibilities:
+    - "Implement assigned vertical slice independently"
+    - "Signal completion on execution_events channel immediately"
+    - "Include test results in result_return to verifier"
+
+  interactionGuidance:
+    - withRole: planner
+      interactionType: result_return
+      guidance: >
+        When returning results, include: (1) files changed with brief
+        description, (2) test results summary, (3) any deviations from
+        the delegated spec and why.
+      examples:
+        - "Completed login form. Changed: src/components/LoginForm.tsx
+           (new), src/api/auth.ts (modified). Tests: 4/4 passing.
+           Deviation: used react-hook-form instead of controlled
+           inputs for better validation UX."
+      antiPatterns:
+        - "Sending just 'done' without artifact details"
+
+    - withRole: verifier
+      interactionType: signal
+      guidance: >
+        Signal TASK_DONE on execution_events as soon as tests pass.
+        Don't wait for planner acknowledgment. Verifier subscribes
+        directly and can begin review immediately.
+      antiPatterns:
+        - "Only signaling after planner confirms receipt"
+
+  decisionFrameworks:
+    - name: blocked-decision
+      when: "Blocked on unclear spec or missing context"
+      guidance: >
+        If blocked for <2 minutes of reasoning, make a reasonable
+        assumption and document it in result_return. If blocked on
+        fundamental ambiguity (e.g., which API to use), escalate
+        immediately rather than guessing.
+
+  antiPatterns:
+    - "Asking planner for clarification on every detail"
+    - "Implementing beyond the delegated scope"
+    - "Not including test evidence in completion signal"
+```
+
+**How role playbooks are surfaced:**
+
+When an agent is assigned a team role, role playbooks are injected alongside individual task playbooks. The agent's system prompt gains a "Team Role Guidance" section:
+
+```typescript
+// Extension to AgentManager for team member spawning
+async spawnTeamMember(config: TeamMemberSpawnConfig): Promise<AgentResult> {
+  // Individual task playbooks (existing SkillLibrary)
+  const taskKnowledge = await this.memory.queryV2(config.task.description, {
+    domains: [config.task.domain],
+  });
+
+  // Role playbooks (new RolePlaybookLibrary)
+  const rolePlaybooks = await this.rolePlaybookLibrary.findMatching({
+    role: config.role,
+    topology: config.teamTopology,
+    taskType: config.taskType,
+    domain: config.task.domain,
+  });
+
+  // Format both into system prompt
+  const systemPrompt = [
+    this.injector.format(taskKnowledge, config.agentType),
+    this.formatRoleGuidance(rolePlaybooks, config.role),
+  ].join('\n\n');
+
+  return this.spawn({
+    ...config,
+    systemPromptAdditions: systemPrompt,
+  });
+}
+```
+
+Rendered in the agent's system prompt as:
+
+```markdown
+## Task Skills
+### fix-typescript-errors (90% confidence)
+**Strategy:** Use dynamic analysis to trace type errors...
+
+## Team Role Guidance
+### effective-wave-executor (82% confidence)
+**Your Role:** executor in wave-parallel team
+**Responsibilities:**
+  - Implement assigned vertical slice independently
+  - Signal completion immediately on execution_events
+**Working with planner:**
+  - When returning results, include files changed + test results...
+**Working with verifier:**
+  - Signal TASK_DONE as soon as tests pass, don't wait for planner...
+**Avoid:**
+  - Asking planner for clarification on every detail
+  - Implementing beyond the delegated scope
+```
+
+#### Type 2: Team Coordination Playbooks
+
+These are the `TeamPlaybook` type from `PROPOSAL-team-aware-learning.md` — unchanged. They describe how to compose and coordinate a team for a given task type. Surfaced when `atlas.recommendTeam()` is called during team formation.
+
+#### Type 3: Team Meta-Observations and Meta-Strategies
+
+Team meta-learning parallels the existing individual `MetaLearner` → `MetaStrategy` pattern. It observes patterns about team formation decisions and produces strategies that adjust future team recommendations.
+
+```typescript
+interface TeamMetaObservation {
+  id: string;
+  teamTrajectoryId: string;
+
+  /** Formation decision assessment */
+  formation: {
+    playbookUsed?: string;
+    formationMethod: 'template' | 'playbook' | 'manual' | 'adaptive';
+    wasEffective: boolean;
+    reasoning: string;
+  };
+
+  /** Composition effectiveness */
+  composition: {
+    roleUtilization: Record<string, number>;
+    missingRoles: string[];
+    redundantRoles: string[];
+    teamSizeAssessment: 'too-small' | 'right-sized' | 'too-large';
+  };
+
+  /** Coordination effectiveness */
+  coordination: {
+    topologyAssessment: 'effective' | 'neutral' | 'hindering';
+    enforcementAssessment: 'too-strict' | 'appropriate' | 'too-loose';
+    emergentPatterns: string[];
+  };
+
+  /** Outcome */
+  outcome: {
+    success: boolean;
+    quality: 'excellent' | 'good' | 'acceptable' | 'poor';
+    speedupEstimate: number;
+    costEfficiency: number;
+  };
+
+  /** Lessons */
+  lessons: {
+    formationSuggestions: string[];
+    coordinationSuggestions: string[];
+    roleSuggestions: string[];
+  };
+
+  timestamp: Date;
+}
+
+interface TeamMetaStrategy {
+  id: string;
+  name: string;
+
+  /** When to apply this meta-strategy */
+  condition: {
+    taskCharacteristics: string[];
+    resourceConstraints: string[];
+    domains: string[];
+  };
+
+  /** What adjustment to make during team formation */
+  adjustment: {
+    topologyBias?: Record<string, number>;
+    teamSizeAdjustment: 'increase' | 'decrease' | 'maintain';
+    roleAdjustments: string[];
+    coordinationHints: string[];
+    enforcementBias?: 'strict' | 'permissive' | 'audit';
+  };
+
+  applicationCount: number;
+  successRate: number;
+  createdAt: Date;
+  updatedAt: Date;
+}
+```
+
+**Meta-strategy generation** follows the same pattern as individual meta-learning:
+
+```
+1. TeamMetaObservations accumulate (threshold: 5)
+2. Periodically analyze:
+   - Which topologies succeed for which task types?
+   - Which team sizes work for which complexity levels?
+   - Which role compositions correlate with success?
+3. Generate TeamMetaStrategies from patterns
+4. Apply during atlas.recommendTeam() to adjust recommendations
+```
+
+### Batch Extraction Agent
+
+Like Phase 3, batch extraction uses an agentic approach:
+
+```typescript
+async runBatchLearning(): Promise<TeamBatchResult> {
+  if (this.accumulated.length < this.config.minTeamTrajectories) {
+    return { ready: false };
+  }
+
+  // Prepare extraction workspace
+  const workspace = await this.prepareExtractionWorkspace(this.accumulated);
+
+  // Get existing playbooks for deduplication
+  const existingTeamPlaybooks = await this.teamMemory.getTeamPlaybooks();
+  const existingRolePlaybooks = await this.teamMemory.getRolePlaybooks();
+
+  // Inject existing playbooks + extraction meta-playbooks
+  const knowledge = await this.getExtractionKnowledge(
+    existingTeamPlaybooks,
+    existingRolePlaybooks
+  );
+
+  // Spawn extraction agent
+  const result = await this.agentManager.spawn({
+    agentType: 'claude-code',
+    task: {
+      id: `team-extraction-${Date.now()}`,
+      domain: 'team-playbook-extraction',
+      description: EXTRACTION_TASK_PROMPT,
+    },
+    cwd: workspace.path,
+    injectedKnowledge: knowledge,
+    captureToolCalls: true,
+  });
+
+  // Read extraction agent's output
+  const newTeamPlaybooks = await this.readPlaybooks(
+    `${workspace.path}/output/team-playbooks/`
+  );
+  const newRolePlaybooks = await this.readPlaybooks(
+    `${workspace.path}/output/role-playbooks/`
+  );
+  const playbookUpdates = await this.readUpdates(
+    `${workspace.path}/output/updates/`
+  );
+  const metaStrategies = await this.readMetaStrategies(
+    `${workspace.path}/output/meta-strategies/`
+  );
+
+  // Store results
+  for (const pb of newTeamPlaybooks) await this.teamMemory.storeTeamPlaybook(pb);
+  for (const pb of newRolePlaybooks) await this.teamMemory.storeRolePlaybook(pb);
+  for (const upd of playbookUpdates) await this.teamMemory.updatePlaybook(upd);
+  for (const ms of metaStrategies) await this.teamMemory.storeMetaStrategy(ms);
+
+  // Process extraction agent's own trajectory for meta-learning
+  await this.individualPipeline.processTrajectory(result.trajectory);
+
+  this.accumulated = [];
+
+  return {
+    ready: true,
+    teamPlaybooksCreated: newTeamPlaybooks.length,
+    rolePlaybooksCreated: newRolePlaybooks.length,
+    playbooksUpdated: playbookUpdates.length,
+    metaStrategiesCreated: metaStrategies.length,
+  };
+}
+```
+
+The extraction workspace contains the batch of accumulated lessons:
+
+```
+/tmp/team-extraction-{id}/
+├── input/
+│   ├── lesson-batches/
+│   │   ├── team-exec-001.json     # Lessons from team execution 1
+│   │   ├── team-exec-002.json     # Lessons from team execution 2
+│   │   └── ...
+│   ├── existing-team-playbooks/
+│   │   └── *.json                 # For deduplication
+│   └── existing-role-playbooks/
+│       └── *.json                 # For deduplication
+│
+├── workspace/                     # Scratch space
+│
+└── output/
+    ├── team-playbooks/            # New team coordination playbooks
+    ├── role-playbooks/            # New role-specific playbooks
+    ├── updates/                   # Updates to existing playbooks
+    └── meta-strategies/           # New team meta-strategies
+```
+
+---
+
+## Full Pipeline Orchestration
+
+The `TeamLearningPipeline` class ties everything together:
+
+```typescript
+class TeamLearningPipeline {
+  private ingester: TeamTrajectoryIngester;
+  private agentManager: AgentManager;
+  private collector: TeamAnalysisCollector;
+  private individualPipeline: LearningPipeline;
+  private teamMemory: TeamMemorySystem;
+  private memory: MemorySystem;
+
+  private accumulated: AccumulatedTeamLessons[] = [];
+
+  /**
+   * Process a single team execution.
+   * Phases 1-4: ingest → agentic analysis → collect.
+   *
+   * Mirrors LearningPipeline.processTrajectory().
+   */
+  async processTeamTrajectory(
+    input: TeamTrajectoryInput
+  ): Promise<TeamProcessResult> {
+
+    // Phase 1-2: Ingest, compress, prepare workspace
+    const workspace = await this.ingester.ingest(input);
+
+    // Phase 3: Agentic analysis
+    const knowledge = await this.getAnalysisKnowledge(workspace);
+    const spawnConfig = buildAnalysisSpawnConfig(workspace, knowledge);
+    const agentResult = await this.agentManager.spawn(spawnConfig);
+
+    // Phase 4: Collect, store, accumulate
+    const analysisResult = await this.collector.collect(
+      workspace, agentResult
+    );
+
+    return {
+      teamTrajectoryId: workspace.teamTrajectory.id,
+      analysis: analysisResult,
+      compressionStats: workspace.compressionStats,
+      analysisMetrics: analysisResult.analysisMetrics,
+    };
+  }
+
+  /**
+   * Run batch playbook extraction on accumulated lessons.
+   * Phase 5.
+   *
+   * Mirrors LearningPipeline.runBatchLearning().
+   */
+  async runBatchLearning(): Promise<TeamBatchResult> {
+    if (this.accumulated.length < this.config.minTeamTrajectories) {
+      return { ready: false };
+    }
+
+    // ... extraction agent workspace + spawn (see Phase 5 above)
+  }
+
+  /**
+   * Check if batch learning is ready.
+   */
+  isBatchReady(): boolean {
+    return this.accumulated.length >= this.config.minTeamTrajectories;
+  }
+
+  /**
+   * Get accumulated lesson count.
+   */
+  getAccumulatedCount(): number {
+    return this.accumulated.length;
+  }
+}
+```
+
+### Configuration
+
+```typescript
+interface TeamLearningConfig {
+  /** Enable team-aware learning */
+  enabled: boolean;  // default: false
+
+  /** Compression settings */
+  compression: CompressionConfig;
+
+  /** Minimum team executions before batch extraction */
+  minTeamTrajectories: number;  // default: 5
+
+  /** Similarity threshold for playbook deduplication */
+  deduplicationThreshold: number;  // default: 0.85
+
+  /** Maximum team experiences to store */
+  maxTeamExperiences: number;  // default: 200
+
+  /** Maximum team playbooks */
+  maxTeamPlaybooks: number;  // default: 50
+
+  /** Maximum role playbooks */
+  maxRolePlaybooks: number;  // default: 100
+
+  /** Analysis agent timeout */
+  analysisTimeout: number;  // default: 300_000 (5 minutes)
+
+  /** Extraction agent timeout */
+  extractionTimeout: number;  // default: 600_000 (10 minutes)
+}
+```
+
+---
+
+## Integration with Atlas
+
+New methods on the `Atlas` class:
+
+```typescript
+class Atlas {
+  // ... existing methods ...
+
+  /**
+   * Process a team trajectory for learning.
+   * Team-level analog of processTrajectory().
+   */
+  async processTeamTrajectory(
+    input: TeamTrajectoryInput
+  ): Promise<TeamProcessResult> {
+    return this.teamPipeline.processTeamTrajectory(input);
+  }
+
+  /**
+   * Recommend a team composition for a given task.
+   * Uses team playbooks + role playbooks + meta-strategies.
+   */
+  async recommendTeam(task: {
+    description: string;
+    domain: string;
+    complexity: 'simple' | 'moderate' | 'complex' | 'epic';
+    constraints?: {
+      maxAgents?: number;
+      maxTokenBudget?: number;
+      preferredTopology?: string;
+    };
+  }): Promise<TeamRecommendation> {
+    // 1. Find matching team playbooks
+    // 2. Apply team meta-strategies
+    // 3. Include relevant role playbooks for each recommended role
+    // 4. Return recommendation with asTeamYaml() export
+  }
+
+  /**
+   * Spawn a team member with both task knowledge and role guidance.
+   */
+  async spawnTeamMember(config: TeamMemberSpawnConfig): Promise<AgentResult> {
+    // 1. Get task playbooks from individual SkillLibrary
+    // 2. Get role playbooks from RolePlaybookLibrary
+    // 3. Inject both into agent's system prompt
+    // 4. Spawn via AgentManager
+    // 5. Capture trajectory with interaction tags
+  }
+
+  /**
+   * Run batch team learning.
+   */
+  async runTeamBatchLearning(): Promise<TeamBatchResult> {
+    return this.teamPipeline.runBatchLearning();
+  }
+}
+```
+
+---
+
+## Storage Layout
+
+```
+.atlas/
+├── experiences/               # Individual agent experiences (existing)
+├── playbooks/                 # Individual task playbooks (existing)
+├── meta-observations/         # Individual meta-observations (existing)
+├── meta-strategies/           # Individual meta-strategies (existing)
+│
+├── team-experiences/          # Team trajectory experiences + analysis
+├── team-playbooks/            # Team coordination playbooks
+├── role-playbooks/            # Role-specific playbooks (new type)
+├── team-meta-observations/    # Team formation observations
+├── team-meta-strategies/      # Team formation meta-strategies
+│
+└── vectors.db                 # Vector store (extended with team embeddings)
+```
+
+---
+
+## The Recursive Learning Architecture
+
+The full system has three learning loops, all using the same infrastructure:
+
+```
+LOOP 1: Individual Learning (existing)
+  Agent solves task → trajectory → playbooks about task-solving
+
+LOOP 2: Team Learning (new)
+  Team executes task → team trajectory → team/role playbooks about coordination
+  Analysis agent analyzes → its trajectory → playbooks about analysis (LOOP 1)
+
+LOOP 3: Meta-Learning (extended)
+  Individual meta-observations → routing meta-strategies (existing)
+  Team meta-observations → formation meta-strategies (new)
+  Analysis meta-observations → analysis improvement (via LOOP 1)
+```
+
+All three loops use the same `AgentManager`, `MemorySystem`, `LearningPipeline`, and `SkillLibrary` infrastructure. The team layer is purely additive — no existing components are modified.
+
+---
+
+## Toward a Reusable Agentic Workspace
+
+The workspace pattern used here — filesystem directory with input/workspace/output structure, agent spawned with tools and injected knowledge, trajectory captured for meta-learning — is not specific to team analysis. It is a general pattern for any cognitive-core analysis task:
+
+- **Playbook extraction**: Input = trajectory batch. Output = new playbooks.
+- **Meta-learning analysis**: Input = observation batch. Output = meta-strategies.
+- **Trajectory evaluation**: Input = trajectory. Output = quality assessment.
+- **Experience curation**: Input = experience store. Output = pruning recommendations.
+
+A reusable `AnalysisWorkspaceManager` could standardize this pattern across all cognitive-core analysis tasks, providing:
+
+1. **Workspace lifecycle**: Create, populate, cleanup temporary directories
+2. **Schema validation**: Validate agent output against expected schemas
+3. **Knowledge injection**: Query appropriate playbooks for the analysis domain
+4. **Trajectory capture**: Automatically route analysis agent trajectories through the learning pipeline
+5. **Error handling**: Retry or fallback if the analysis agent fails to produce valid output
+
+This is discussed further in the agentic workspace design (separate document).