cognitive-core 0.1.0 → 0.2.0

package/docs/DESIGN-agentic-workspace.md

@@ -0,0 +1,2057 @@
+# Design: Agentic Analysis Workspace
+
+## Problem
+
+cognitive-core has ~12 analysis points that transform execution data into learning signals. Most are implemented as brittle heuristics (word overlap, regex matching, exponential decay) when they should use semantic understanding. A few already use LLM calls or spawn agents, but each does it differently with no shared infrastructure.
+
+| Analysis Point | Current | Should Be |
+|---|---|---|
+| Credit assignment (`analyzer.ts`) | Exponential decay / outcome-based | Semantic causal reasoning |
+| Key step identification (`analyzer.ts`) | Score threshold | Counterfactual reasoning |
+| Error pattern detection (`analyzer.ts`) | Regex matching | Semantic classification |
+| Playbook extraction (`playbook-extractor.ts`) | Action normalization + frequency | Semantic pattern recognition |
+| LLM playbook extraction (`llm-extractor.ts`) | Single LLM call | Iterative agentic extraction |
+| Meta-learning reflection (`meta-learner.ts`) | Word overlap heuristics | Semantic reflection |
+| Usage inference (`usage-inference.ts`) | Word overlap matching | Semantic matching |
+| Solution evaluation (`evaluator.ts`) | Tier 2: agent, Tier 3: heuristic | Workspace-based analysis |
+| Routing decision (`router.ts`) | Threshold-based rules | Reasoned strategy selection |
+| Effectiveness tracking (`effectiveness.ts`) | Counting / aggregation | OK as heuristic (pure metrics) |
+| Refinement strategy (`refinement-loop.ts`) | Issue listing + retry | Root cause analysis |
+| **Team analysis** (new) | N/A | Agentic workspace |
+| **Team playbook extraction** (new) | N/A | Agentic workspace |
+
+The pattern is the same across all of these:
+
+1. Prepare structured input data
+2. An agent (or LLM) analyzes it with semantic understanding
+3. Structured output is validated and stored
+4. The analysis agent's own execution is captured for meta-learning
+
+This document designs a **reusable agentic workspace** that standardizes this pattern.
+
+---
+
+## Design Overview
+
+Three components:
+
+1. **`AgenticTaskTemplate<TInput, TOutput>`** — a declarative recipe for an analysis task (what goes in, what comes out, what skills are available, what output shape is expected)
+2. **`WorkspaceManager`** — creates, populates, validates, and cleans up filesystem workspaces
+3. **`AgenticTaskRunner`** — orchestrates the full lifecycle: workspace → agent spawn → output collection → meta-learning
+
+```
+AgenticTaskTemplate           WorkspaceManager
+(declarative recipe)          (filesystem lifecycle)
+        │                            │
+        └──────────┬─────────────────┘
+                   │
+                   ▼
+          AgenticTaskRunner
+          (orchestration)
+                   │
+        ┌──────────┼──────────────┐
+        │          │              │
+        ▼          ▼              ▼
+  AgentManager   Output       LearningPipeline
+  (spawn agent)  Validation   (meta-learning from
+                              analysis trajectory)
+```
+
+### Workspace Directory Structure
+
+Every workspace follows a standard layout:
+
+```
+{workspace}/
+├── input/                     # Prepared input data
+│   ├── context.md             # YAML frontmatter + markdown body
+│   ├── trajectories/          # JSONL files (one step per line)
+│   │   ├── agent-a.jsonl
+│   │   └── agent-b.jsonl
+│   └── ...task-specific data...
+├── resources/                 # Configurable supplementary data
+│   ├── codebase/              # Optional codebase snapshot
+│   ├── docs/                  # Optional reference docs
+│   └── ...per-template...
+├── skills/                    # Agent Skills (open standard format)
+│   ├── trajectory-analysis/
+│   │   └── SKILL.md
+│   └── ...
+├── workspace/                 # Agent scratch space (notes, temp files)
+└── output/                    # Structured results per outputConfig
+    ├── output.json            # Primary output (with schema validation)
+    ├── SKILL.md               # If task produces skills
+    └── ...
+```
+
+### Data Format Conventions
+
+| Data Type | Format | Rationale |
+|---|---|---|
+| Trajectories | **JSONL** (`.jsonl`) | One step per line. Greppable, streamable, works with `head`/`tail`/`wc -l`. Agent can search with standard tools. |
+| Text-heavy content | **Markdown + YAML frontmatter** | Context docs, lessons, assessments. Structured metadata in frontmatter, readable prose in body. |
+| Structured data | **JSON** | Configs, schemas, structured results. Validated against Zod schemas. |
+| Skills | **SKILL.md** (Agent Skills open standard) | Portable skill format. Converter between Playbook ↔ Skill assumed. |
+
+### Raw Data First Principle
+
+Early pipeline agents receive **raw data** (full trajectories, original task descriptions). Later pipeline agents receive **derivative data** from previous analysis (credits, annotations, extracted patterns). This ensures early agents can discover novel patterns that preprocessed summaries might obscure.
+
+---
+
+## AgenticTaskTemplate
+
+A template defines everything about a specific type of analysis task. Different analysis tasks (trajectory analysis, playbook extraction, team analysis) are different templates.
+
+```typescript
+/**
+ * Declarative recipe for an agentic analysis task.
+ *
+ * TInput: the typed input data for this analysis
+ * TOutput: the typed output the agent produces
+ */
+interface AgenticTaskTemplate<TInput, TOutput> {
+  /** Unique identifier for this task type */
+  taskType: string;
+  // e.g., 'trajectory-analysis', 'playbook-extraction', 'team-analysis'
+
+  /** Domain for knowledge injection and meta-learning.
+   *  Analysis playbooks accumulate in this domain. */
+  domain: string;
+  // e.g., 'trajectory-analysis' → playbooks about how to analyze trajectories
+
+  /** Human-readable description */
+  description: string;
+
+  // === WORKSPACE SETUP ===
+
+  /**
+   * Prepare the workspace filesystem from typed input.
+   * Writes input files (JSONL trajectories, markdown context docs, etc.)
+   * that the agent will read using standard tools.
+   */
+  prepareWorkspace(input: TInput, workspacePath: string): Promise<void>;
+
+  /**
+   * Build the task description for the agent.
+   * This is the natural language prompt explaining what to do,
+   * what files to read, and what output to produce.
+   */
+  buildTaskPrompt(input: TInput): string;
+
+  // === SKILLS ===
+
+  /**
+   * Skills to load into the workspace skills/ directory.
+   * These are SKILL.md files in the Agent Skills open standard format.
+   * Playbooks from memory are converted to skills via the converter.
+   */
+  getSkills(input: TInput): AgentSkillSpec[];
+
+  // === RESOURCES ===
+
+  /**
+   * Supplementary resources to load into the workspace resources/ directory.
+   * Configurable per task — codebase snapshots, reference docs, etc.
+   */
+  getResources(input: TInput): ResourceSpec[];
+
+  // === KNOWLEDGE ===
+
+  /**
+   * Additional memory queries to inject domain-specific knowledge.
+   * Beyond the automatic domain-scoped query, templates can request
+   * additional knowledge based on the input.
+   */
+  getAdditionalKnowledge?(
+    input: TInput,
+    memory: MemorySystem
+  ): Promise<MemoryQueryResultV2>;
+
+  // === OUTPUT ===
+
+  /**
+   * Configuration defining the expected output shape.
+   * Different tasks produce different outputs — JSON with schema,
+   * SKILL.md files, markdown reports, etc.
+   */
+  outputConfig: OutputConfig;
+
+  /**
+   * Read and validate agent output from workspace.
+   * Validates against outputConfig schema if applicable.
+   * Returns typed output or throws if validation fails.
+   */
+  collectOutput(workspacePath: string): Promise<TOutput>;
+
+  /**
+   * Process the validated output — store results, accumulate
+   * for batch learning, update memory, etc.
+   */
+  processOutput(
+    output: TOutput,
+    input: TInput,
+    context: ProcessingContext
+  ): Promise<void>;
+
+  // === COMPLEXITY ASSESSMENT ===
+
+  /**
+   * Assess whether this input needs agentic analysis or can
+   * use a heuristic fallback. This controls cost — simple inputs
+   * don't need a full agent spawn.
+   */
+  assessComplexity(input: TInput): AnalysisComplexity;
+
+  /**
+   * Heuristic fallback for simple cases.
+   * If assessComplexity returns 'heuristic', this is called
+   * instead of spawning an agent.
+   */
+  heuristicFallback?(input: TInput): Promise<TOutput>;
+
+  // === CONFIGURATION ===
+
+  /** Agent type to spawn */
+  agentType?: string;  // default: 'claude-code'
+
+  /** Timeout for the analysis agent */
+  timeout?: number;  // default: 120_000 (2 minutes)
+
+  /** Whether to capture detailed tool calls */
+  captureToolCalls?: boolean;  // default: true
+}
+
+/**
+ * Output configuration — defines what shape of output the agent produces.
+ */
+interface OutputConfig {
+  /** Primary output file(s) the agent must produce */
+  files: OutputFileSpec[];
+}
+
+interface OutputFileSpec {
+  /** Path relative to output/ directory */
+  path: string;
+  /** File format */
+  format: 'json' | 'jsonl' | 'markdown' | 'skill-md';
+  /** Zod schema for JSON/JSONL validation (optional) */
+  schema?: ZodSchema;
+  /** Whether this file is required or optional */
+  required: boolean;
+  /** Description shown to the agent */
+  description: string;
+}
+
+/**
+ * Skill to load into workspace skills/ directory.
+ */
+interface AgentSkillSpec {
+  /** Skill directory name */
+  name: string;
+  /** SKILL.md content (Agent Skills open standard format) */
+  content: string;
+  /** Source — converted from a Playbook, or loaded from curated skills */
+  source: 'playbook-conversion' | 'curated' | 'extracted';
+}
+
+/**
+ * Supplementary resource to load into workspace resources/ directory.
+ */
+interface ResourceSpec {
+  /** Path relative to resources/ directory */
+  path: string;
+  /** How to populate this resource */
+  type: 'directory' | 'file' | 'symlink';
+  /** Source path (for symlink/copy) or content (for file) */
+  source: string;
+  /** Description for the agent */
+  description?: string;
+}
+
+type AnalysisComplexity =
+  | 'heuristic'     // Use heuristicFallback(), no agent needed
+  | 'lightweight'   // Agent with small budget, simple workspace
+  | 'standard'      // Agent with moderate budget, full workspace
+  | 'thorough';     // Agent with large budget, full workspace, more time
+
+interface ProcessingContext {
+  memory: MemorySystem;
+  teamMemory?: TeamMemorySystem;
+  learningPipeline: LearningPipeline;
+}
+```
+
+---
+
+## WorkspaceManager
+
+Handles filesystem lifecycle — creating the directory structure, populating inputs, validating outputs, cleanup.
+
+```typescript
+class WorkspaceManager {
+  private baseDir: string;  // default: os.tmpdir()
+
+  /**
+   * Create a workspace directory with standard structure.
+   */
+  async create(taskType: string): Promise<WorkspaceHandle> {
+    const id = `${taskType}-${Date.now()}-${randomId()}`;
+    const path = join(this.baseDir, 'atlas-workspaces', id);
+
+    await mkdir(join(path, 'input'), { recursive: true });
+    await mkdir(join(path, 'resources'), { recursive: true });
+    await mkdir(join(path, 'skills'), { recursive: true });
+    await mkdir(join(path, 'workspace'), { recursive: true });
+    await mkdir(join(path, 'output'), { recursive: true });
+
+    return {
+      id,
+      path,
+      inputDir: join(path, 'input'),
+      resourcesDir: join(path, 'resources'),
+      skillsDir: join(path, 'skills'),
+      workspaceDir: join(path, 'workspace'),
+      outputDir: join(path, 'output'),
+      createdAt: new Date(),
+    };
+  }
+
+  // === INPUT WRITERS ===
+
+  /**
+   * Write a JSON file to the input directory.
+   */
+  async writeInputJson(
+    handle: WorkspaceHandle,
+    filename: string,
+    data: unknown
+  ): Promise<void> {
+    const filePath = join(handle.inputDir, filename);
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, JSON.stringify(data, null, 2));
+  }
+
+  /**
+   * Write a JSONL file to the input directory.
+   * Each item becomes one line — ideal for trajectories (one step per line).
+   * Agents can search with grep, count with wc -l, peek with head/tail.
+   */
+  async writeInputJsonl(
+    handle: WorkspaceHandle,
+    filename: string,
+    items: unknown[]
+  ): Promise<void> {
+    const filePath = join(handle.inputDir, filename);
+    await mkdir(dirname(filePath), { recursive: true });
+    const lines = items.map(item => JSON.stringify(item));
+    await writeFile(filePath, lines.join('\n') + '\n');
+  }
+
+  /**
+   * Write a markdown file with YAML frontmatter to the input directory.
+   * Used for text-heavy content: context docs, lessons, assessments.
+   */
+  async writeInputMarkdown(
+    handle: WorkspaceHandle,
+    filename: string,
+    frontmatter: Record<string, unknown>,
+    body: string
+  ): Promise<void> {
+    const filePath = join(handle.inputDir, filename);
+    await mkdir(dirname(filePath), { recursive: true });
+    const yaml = this.toYamlFrontmatter(frontmatter);
+    await writeFile(filePath, `---\n${yaml}---\n\n${body}`);
+  }
+
+  /**
+   * Write a raw file (any format) to the input directory.
+   */
+  async writeInputRaw(
+    handle: WorkspaceHandle,
+    filename: string,
+    content: string
+  ): Promise<void> {
+    const filePath = join(handle.inputDir, filename);
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, content);
+  }
+
+  // === SKILLS ===
+
+  /**
+   * Write a SKILL.md file to the skills directory.
+   * Agent Skills open standard format.
+   */
+  async writeSkill(
+    handle: WorkspaceHandle,
+    skill: AgentSkillSpec
+  ): Promise<void> {
+    const skillDir = join(handle.skillsDir, skill.name);
+    await mkdir(skillDir, { recursive: true });
+    await writeFile(join(skillDir, 'SKILL.md'), skill.content);
+  }
+
+  /**
+   * Write multiple skills to the workspace.
+   */
+  async writeSkills(
+    handle: WorkspaceHandle,
+    skills: AgentSkillSpec[]
+  ): Promise<void> {
+    await Promise.all(skills.map(s => this.writeSkill(handle, s)));
+  }
+
+  // === RESOURCES ===
+
+  /**
+   * Populate a resource in the resources directory.
+   */
+  async writeResource(
+    handle: WorkspaceHandle,
+    resource: ResourceSpec
+  ): Promise<void> {
+    const targetPath = join(handle.resourcesDir, resource.path);
+    await mkdir(dirname(targetPath), { recursive: true });
+
+    switch (resource.type) {
+      case 'file':
+        await writeFile(targetPath, resource.source);
+        break;
+      case 'symlink':
+        await symlink(resource.source, targetPath);
+        break;
+      case 'directory':
+        await cp(resource.source, targetPath, { recursive: true });
+        break;
+    }
+  }
+
+  /**
+   * Write multiple resources to the workspace.
+   */
+  async writeResources(
+    handle: WorkspaceHandle,
+    resources: ResourceSpec[]
+  ): Promise<void> {
+    await Promise.all(resources.map(r => this.writeResource(handle, r)));
+  }
+
+  // === OUTPUT READERS ===
+
+  /**
+   * Read and parse a JSON output file.
+   * Returns null if file doesn't exist.
+   */
+  async readOutputJson<T>(
+    handle: WorkspaceHandle,
+    filename: string,
+    schema?: ZodSchema<T>
+  ): Promise<T | null> {
+    const filePath = join(handle.outputDir, filename);
+    try {
+      const raw = await readFile(filePath, 'utf-8');
+      const parsed = JSON.parse(raw);
+      return schema ? schema.parse(parsed) : parsed;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Read a JSONL output file as an array of parsed items.
+   */
+  async readOutputJsonl<T>(
+    handle: WorkspaceHandle,
+    filename: string,
+    schema?: ZodSchema<T>
+  ): Promise<T[]> {
+    const filePath = join(handle.outputDir, filename);
+    try {
+      const raw = await readFile(filePath, 'utf-8');
+      const lines = raw.trim().split('\n').filter(l => l.length > 0);
+      const items = lines.map(line => JSON.parse(line));
+      return schema ? items.map(item => schema.parse(item)) : items;
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Read a markdown output file (returns raw content).
+   */
+  async readOutputMarkdown(
+    handle: WorkspaceHandle,
+    filename: string
+  ): Promise<string | null> {
+    const filePath = join(handle.outputDir, filename);
+    try {
+      return await readFile(filePath, 'utf-8');
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Read all files in an output subdirectory.
+   */
+  async readOutputDir<T>(
+    handle: WorkspaceHandle,
+    dirName: string,
+    schema?: ZodSchema<T>
+  ): Promise<Map<string, T>> {
+    const dirPath = join(handle.outputDir, dirName);
+    const results = new Map<string, T>();
+    try {
+      const files = await readdir(dirPath);
+      for (const file of files) {
+        if (file.endsWith('.json')) {
+          const data = await this.readOutputJson<T>(
+            handle,
+            join(dirName, file),
+            schema
+          );
+          if (data) results.set(file.replace('.json', ''), data);
+        }
+      }
+    } catch {
+      // directory doesn't exist
+    }
+    return results;
+  }
+
+  /**
+   * Validate that all required output files exist per OutputConfig.
+   */
+  async validateOutput(
+    handle: WorkspaceHandle,
+    config: OutputConfig
+  ): Promise<{ valid: boolean; missing: string[] }> {
+    const missing: string[] = [];
+    for (const file of config.files) {
+      if (file.required) {
+        const filePath = join(handle.outputDir, file.path);
+        try {
+          await access(filePath);
+        } catch {
+          missing.push(file.path);
+        }
+      }
+    }
+    return { valid: missing.length === 0, missing };
+  }
+
+  // === LIFECYCLE ===
+
+  /**
+   * Cleanup workspace directory.
+   */
+  async cleanup(handle: WorkspaceHandle): Promise<void> {
+    await rm(handle.path, { recursive: true, force: true });
+  }
+
+  /**
+   * List active workspaces (for monitoring/debugging).
+   */
+  async listActive(): Promise<WorkspaceHandle[]> {
+    // scan baseDir/atlas-workspaces/ for directories
+  }
+
+  /**
+   * Cleanup workspaces older than maxAge.
+   */
+  async pruneStale(maxAgeMs: number): Promise<number> {
+    // remove workspaces older than maxAge
+  }
+
+  // === HELPERS ===
+
+  private toYamlFrontmatter(data: Record<string, unknown>): string {
+    // Simple YAML serialization for frontmatter
+    // Handles strings, numbers, booleans, arrays, dates
+    return Object.entries(data)
+      .map(([key, value]) => {
+        if (Array.isArray(value)) {
+          return `${key}:\n${value.map(v => `  - ${v}`).join('\n')}`;
+        }
+        if (value instanceof Date) {
+          return `${key}: ${value.toISOString()}`;
+        }
+        return `${key}: ${value}`;
+      })
+      .join('\n') + '\n';
+  }
+}
+
+interface WorkspaceHandle {
+  id: string;
+  path: string;
+  inputDir: string;
+  resourcesDir: string;
+  skillsDir: string;
+  workspaceDir: string;
+  outputDir: string;
+  createdAt: Date;
+}
+```
+
+---
+
+## AgenticTaskRunner
+
+The orchestrator that ties templates, workspaces, and agent spawning together.
+
+```typescript
+class AgenticTaskRunner {
+  constructor(
+    private workspaceManager: WorkspaceManager,
+    private agentManager: AgentManager,
+    private memory: MemorySystem,
+    private learningPipeline: LearningPipeline,
+    private config: AgenticTaskRunnerConfig
+  ) {}
+
+  /**
+   * Run an agentic analysis task.
+   *
+   * This is the main entry point. It:
+   * 1. Checks complexity — uses heuristic fallback for simple inputs
+   * 2. Creates workspace and populates input files
+   * 3. Populates input data (JSONL trajectories, markdown context, etc.)
+   * 4. Loads skills (converted from playbooks + curated SKILL.md files)
+   * 5. Loads resources (codebase snapshots, docs, etc.)
+   * 6. Queries knowledge for injection
+   * 7. Spawns agent with workspace as cwd
+   * 8. Validates output against outputConfig
+   * 9. Collects and validates output
+   * 10. Processes output (store, accumulate, etc.)
+   * 11. Routes analysis agent's trajectory through learning pipeline
+   * 12. Cleans up workspace
+   */
+  async run<TInput, TOutput>(
+    template: AgenticTaskTemplate<TInput, TOutput>,
+    input: TInput
+  ): Promise<AgenticTaskResult<TOutput>> {
+
+    // Step 1: Complexity assessment
+    const complexity = template.assessComplexity(input);
+
+    if (complexity === 'heuristic' && template.heuristicFallback) {
+      const output = await template.heuristicFallback(input);
+      return {
+        output,
+        method: 'heuristic',
+        metrics: { totalTimeMs: 0, tokensUsed: 0, toolCalls: 0 },
+      };
+    }
+
+    // Step 2: Create workspace
+    const workspace = await this.workspaceManager.create(template.taskType);
+
+    try {
+      // Step 3: Populate input files
+      await template.prepareWorkspace(input, workspace.path);
+
+      // Step 4: Populate skills (converted from playbooks + curated)
+      const skills = template.getSkills(input);
+      await this.workspaceManager.writeSkills(workspace, skills);
+
+      // Step 5: Populate resources (codebase snapshots, docs, etc.)
+      const resources = template.getResources(input);
+      await this.workspaceManager.writeResources(workspace, resources);
+
+      // Step 6: Query knowledge
+      const knowledge = await this.getKnowledge(template, input);
+
+      // Step 7: Spawn agent
+      const agentResult = await this.agentManager.spawn({
+        agentType: template.agentType ?? 'claude-code',
+        task: {
+          id: `${template.taskType}-${workspace.id}`,
+          domain: template.domain,
+          description: template.buildTaskPrompt(input),
+        },
+        cwd: workspace.path,
+        injectedKnowledge: knowledge,
+        captureToolCalls: template.captureToolCalls ?? true,
+        timeout: this.getTimeout(template, complexity),
+      });
+
+      // Step 8: Validate output against outputConfig
+      const validation = await this.workspaceManager.validateOutput(
+        workspace, template.outputConfig
+      );
+      if (!validation.valid) {
+        // Agent may not have finished writing — retry or error
+        throw new AgenticTaskOutputError(
+          template.taskType,
+          new Error(`Missing required output files: ${validation.missing.join(', ')}`)
+        );
+      }
+
+      // Step 9: Collect and validate output
+      const output = await this.collectWithRetry(
+        template, workspace, agentResult
+      );
+
+      // Step 10: Process output
+      const context: ProcessingContext = {
+        memory: this.memory,
+        learningPipeline: this.learningPipeline,
+      };
+      await template.processOutput(output, input, context);
+
+      // Step 11: Meta-learning — route analysis agent's own trajectory
+      //         through the individual learning pipeline
+      await this.learningPipeline.processTrajectory(
+        agentResult.trajectory
+      );
+
+      return {
+        output,
+        method: 'agentic',
+        agentTrajectoryId: agentResult.trajectory.id,
+        metrics: {
+          totalTimeMs: agentResult.metrics.totalTime,
+          tokensUsed: agentResult.metrics.tokenEstimate ?? 0,
+          toolCalls: agentResult.metrics.toolCallCount,
+        },
+      };
+
+    } finally {
+      // Step 12: Cleanup
+      if (this.config.cleanupWorkspaces) {
+        await this.workspaceManager.cleanup(workspace);
+      }
+    }
+  }
+
+  /**
+   * Query knowledge for the analysis agent.
+   * Combines domain-scoped query + template-specific additional queries.
+   */
+  private async getKnowledge<TInput, TOutput>(
+    template: AgenticTaskTemplate<TInput, TOutput>,
+    input: TInput
+  ): Promise<MemoryQueryResultV2> {
+    // Always query for playbooks in the template's domain
+    // (these are playbooks about HOW to do this type of analysis)
+    const domainKnowledge = await this.memory.queryV2(
+      template.description,
+      { domains: [template.domain] }
+    );
+
+    // Template-specific additional knowledge
+    let additionalKnowledge: MemoryQueryResultV2 | undefined;
+    if (template.getAdditionalKnowledge) {
+      additionalKnowledge = await template.getAdditionalKnowledge(
+        input, this.memory
+      );
+    }
+
+    return mergeKnowledge(domainKnowledge, additionalKnowledge);
+  }
+
+  /**
+   * Collect output with retry on validation failure.
+   * If the agent produced invalid output, we can optionally
+   * send a follow-up message asking it to fix the output.
+   */
+  private async collectWithRetry<TInput, TOutput>(
+    template: AgenticTaskTemplate<TInput, TOutput>,
+    workspace: WorkspaceHandle,
+    agentResult: AgentResult,
+    maxRetries: number = 1
+  ): Promise<TOutput> {
+    try {
+      return await template.collectOutput(workspace.path);
+    } catch (validationError) {
+      if (maxRetries > 0 && agentResult.session.state === 'completed') {
+        // Could send follow-up message to fix output
+        // For now, throw
+      }
+      throw new AgenticTaskOutputError(
+        template.taskType,
+        validationError as Error
+      );
+    }
+  }
+
+  /**
+   * Get timeout based on template default and complexity.
+   */
+  private getTimeout<TInput, TOutput>(
+    template: AgenticTaskTemplate<TInput, TOutput>,
+    complexity: AnalysisComplexity
+  ): number {
+    const base = template.timeout ?? 120_000;
+    switch (complexity) {
+      case 'lightweight': return Math.min(base, 60_000);
+      case 'standard': return base;
+      case 'thorough': return base * 2;
+      default: return base;
+    }
+  }
+}
+
+interface AgenticTaskResult<TOutput> {
+  output: TOutput;
+  method: 'heuristic' | 'agentic';
+  agentTrajectoryId?: string;
+  metrics: {
+    totalTimeMs: number;
+    tokensUsed: number;
+    toolCalls: number;
+  };
+}
+
+interface AgenticTaskRunnerConfig {
+  /** Cleanup workspaces after completion */
+  cleanupWorkspaces: boolean;  // default: true
+
+  /** Keep workspaces for failed tasks (for debugging) */
+  keepFailedWorkspaces: boolean;  // default: true
+
+  /** Maximum concurrent analysis agents */
+  maxConcurrentAgents: number;  // default: 3
+
+  /** Stale workspace cleanup threshold */
+  staleWorkspaceMaxAgeMs: number;  // default: 3600_000 (1 hour)
+}
+```
+
+---
+
+## Concrete Templates
+
+### Template 1: Trajectory Analysis
+
+Replaces the heuristic `TrajectoryAnalyzer` with semantic analysis for complex trajectories.
+
+```typescript
+const trajectoryAnalysisTemplate: AgenticTaskTemplate<
+  TrajectoryAnalysisInput,
+  AnalysisResult
+> = {
+  taskType: 'trajectory-analysis',
+  domain: 'trajectory-analysis',
+  description: 'Analyze agent trajectory for credit assignment and pattern detection',
+
+  outputConfig: {
+    files: [
+      {
+        path: 'analysis.json',
+        format: 'json',
+        schema: AnalysisResultSchema,
+        required: true,
+        description: 'Credit assignment, error patterns, and abstractability assessment',
+      },
+    ],
+  },
+
+  assessComplexity(input) {
+    // Short, successful trajectories → heuristic is fine
+    if (input.trajectory.steps.length <= 5 && input.trajectory.outcome.success) {
+      return 'heuristic';
+    }
+    // Failed trajectories or complex ones → agent analysis
+    if (!input.trajectory.outcome.success || input.trajectory.steps.length > 20) {
+      return 'standard';
+    }
+    return 'lightweight';
+  },
+
+  heuristicFallback(input) {
+    // Existing TrajectoryAnalyzer logic — exponential decay + regex patterns
+    const analyzer = new TrajectoryAnalyzer(input.creditStrategy);
+    return analyzer.analyze(input.trajectory);
+  },
+
+  getSkills(input) {
+    // Convert any relevant playbooks about trajectory analysis into SKILL.md
+    return convertPlaybooksToSkills(input.analysisPlaybooks ?? []);
+  },
+
+  getResources(input) {
+    // No supplementary resources needed for trajectory analysis
+    return [];
+  },
+
+  async prepareWorkspace(input, workspacePath) {
+    const wm = this.workspaceManager;
+    const handle = { inputDir: join(workspacePath, 'input') } as WorkspaceHandle;
+
+    // Raw trajectory as JSONL — one step per line, agent can grep/head/tail
+    await wm.writeInputJsonl(handle, 'trajectories/execution.jsonl',
+      input.trajectory.steps.map(step => ({
+        ...step,
+        // Flatten for greppability
+        _action_summary: step.action.slice(0, 200),
+      }))
+    );
+
+    // Task context as markdown with YAML frontmatter
+    await wm.writeInputMarkdown(handle, 'context.md', {
+      taskId: input.trajectory.task.id,
+      domain: input.trajectory.task.domain,
+      outcome: input.trajectory.outcome.success ? 'success' : 'failure',
+      stepCount: input.trajectory.steps.length,
+      wallTimeSeconds: input.trajectory.wallTimeSeconds,
+    }, `# Task\n\n${input.trajectory.task.description}\n\n` +
+       `# Outcome\n\n${input.trajectory.outcome.success ? 'Success' : 'Failure'}\n` +
+       (input.trajectory.outcome.errorInfo
+         ? `\n**Error:** ${input.trajectory.outcome.errorInfo}\n` : '')
+    );
+  },
+
+  buildTaskPrompt(input) {
+    return `
+Analyze the agent trajectory in this workspace.
+
+## Input Files
+- input/context.md — Task description, outcome, and metadata (YAML frontmatter)
+- input/trajectories/execution.jsonl — Full trajectory (one step per line, use grep to search)
+
+## Available Skills
+- Check skills/ directory for analysis guidance
+
+## Instructions
+1. Read the context to understand what task was attempted and whether it succeeded.
+2. Read the trajectory JSONL. Use grep to find error patterns, key actions, etc.
+3. For each step, assess its causal contribution to the outcome.
+   Write reasoning about WHY each step mattered or didn't.
+4. Identify error patterns — not just by regex, but by understanding
+   what went wrong and why.
+5. Determine if this trajectory contains abstractable patterns
+   worth extracting into playbooks.
+
+## Output
+Write your analysis to output/analysis.json matching the required schema.
+Use workspace/ for intermediate notes.
+    `;
+  },
+
+  async collectOutput(workspacePath) {
+    // Read and validate output/analysis.json against AnalysisResult schema
+  },
+
+  async processOutput(output, input, context) {
+    // Apply attribution scores to trajectory steps
+    // Store in experience memory
+  },
+};
+```
+
+**Workspace layout:**
+```
+input/
+  context.md                   # YAML frontmatter: taskId, domain, outcome, stepCount
+  trajectories/
+    execution.jsonl            # One step per line — raw trajectory data
+skills/
+  trajectory-analysis/
+    SKILL.md                   # Converted from analysis playbooks
+resources/                     # (empty for this template)
+workspace/                     # Agent scratch space
+output/
+  analysis.json                # AnalysisResult (validated against schema)
+```
+
+### Template 2: Playbook Extraction
+
+Replaces both `PlaybookExtractor` (heuristic) and `LLMPlaybookExtractor` (single-call) with iterative agentic extraction.
+
+```typescript
+const playbookExtractionTemplate: AgenticTaskTemplate<
+  PlaybookExtractionInput,
+  ExtractedPlaybooks
+> = {
+  taskType: 'playbook-extraction',
+  domain: 'playbook-extraction',
+  description: 'Extract reusable playbooks from trajectory batch',
+  timeout: 300_000,  // 5 minutes — analyzing multiple trajectories
+
+  outputConfig: {
+    files: [
+      {
+        path: 'playbooks/',
+        format: 'json',
+        required: false,  // May find no new playbooks
+        description: 'Newly extracted playbooks (one JSON per playbook)',
+      },
+      {
+        path: 'skills/',
+        format: 'skill-md',
+        required: false,
+        description: 'Newly extracted skills in SKILL.md format',
+      },
+      {
+        path: 'updates/',
+        format: 'json',
+        required: false,
+        description: 'Updates to existing playbooks',
+      },
+      {
+        path: 'extraction-summary.json',
+        format: 'json',
+        required: true,
+        description: 'Summary of extraction results: counts, patterns found, confidence',
+      },
+    ],
+  },
+
+  assessComplexity(input) {
+    // Small batches with clear patterns → heuristic
+    if (input.trajectories.length <= 3) return 'heuristic';
+    // Large diverse batches → thorough agent analysis
+    if (input.trajectories.length > 10) return 'thorough';
+    return 'standard';
+  },
+
+  heuristicFallback(input) {
+    // Existing PlaybookExtractor logic
+    const extractor = new PlaybookExtractor();
+    return extractor.extract(input.trajectories, input.analyses, input.existingPlaybooks);
+  },
+
+  getSkills(input) {
+    return convertPlaybooksToSkills(input.extractionPlaybooks ?? []);
+  },
+
+  getResources(input) {
+    // No supplementary resources typically needed
+    return [];
+  },
+
+  async prepareWorkspace(input, workspacePath) {
+    const wm = this.workspaceManager;
+    const handle = { inputDir: join(workspacePath, 'input') } as WorkspaceHandle;
+
+    // Batch summary as markdown with frontmatter
+    await wm.writeInputMarkdown(handle, 'summary.md', {
+      batchSize: input.trajectories.length,
+      domains: [...new Set(input.trajectories.map(t => t.task.domain))],
+      successRate: input.trajectories.filter(t => t.outcome.success).length / input.trajectories.length,
+      dateRange: {
+        earliest: input.trajectories[0]?.metadata?.timestamp,
+        latest: input.trajectories[input.trajectories.length - 1]?.metadata?.timestamp,
+      },
+    }, `# Trajectory Batch Summary\n\nThis batch contains ${input.trajectories.length} trajectories for pattern extraction.`);
+
+    // Each trajectory as JSONL — raw data, agent can grep across all
+    for (const trajectory of input.trajectories) {
+      await wm.writeInputJsonl(handle,
+        `trajectories/${trajectory.id}.jsonl`,
+        trajectory.steps
+      );
+    }
+
+    // Analyses as derivative data (from previous pipeline stage)
+    for (const analysis of input.analyses) {
+      await wm.writeInputJson(handle,
+        `analyses/${analysis.trajectoryId}.json`,
+        analysis
+      );
+    }
+
+    // Existing playbooks for deduplication
+    for (const playbook of input.existingPlaybooks) {
+      await wm.writeInputJson(handle,
+        `existing-playbooks/${playbook.name}.json`,
+        playbook
+      );
+    }
+  },
+
+  buildTaskPrompt(input) {
+    return `
+Extract reusable playbooks from the trajectory batch in this workspace.
+
+## Input Files
+- input/summary.md — Batch overview with metadata (YAML frontmatter)
+- input/trajectories/*.jsonl — Raw trajectories (one step per line, use grep across all)
+- input/analyses/*.json — Analysis results from previous pipeline stage (derivative data)
+- input/existing-playbooks/*.json — Current playbooks for deduplication
+
+## Available Skills
+- Check skills/ directory for extraction guidance
+
+## Instructions
+1. Read the summary for batch overview.
+2. Read analyses for each trajectory — these contain credit assignments and patterns.
+3. Grep across raw trajectories to identify recurring action patterns.
+4. Identify common patterns across successful trajectories:
+   - Recurring strategies (not just action sequences — semantic patterns)
+   - Error recovery approaches that worked
+   - Domain-specific techniques
+5. Check against existing playbooks — if a pattern matches, generate an update.
+6. For each new playbook, provide:
+   - Clear name, situations, triggers
+   - Strategy and tactics (actionable, not generic)
+   - Verification criteria
+   - Confidence based on evidence strength
+
+## Output
+- Write new playbooks to output/playbooks/ (JSON)
+- Write new skills to output/skills/ (SKILL.md format)
+- Write updates to output/updates/ (JSON)
+- Write extraction summary to output/extraction-summary.json (required)
+- Use workspace/ for notes and pattern analysis.
+    `;
+  },
+
+  async collectOutput(workspacePath) {
+    // Read output/playbooks/*.json, output/skills/*/SKILL.md, output/updates/*.json
+  },
+
+  async processOutput(output, input, context) {
+    // Add new playbooks to PlaybookLibrary
+    // Convert new SKILL.md files to playbooks (or store as skills)
+    // Apply updates to existing playbooks
+  },
+};
+```
+
+**Workspace layout:**
+```
+input/
+  summary.md                   # YAML frontmatter: batchSize, domains, successRate
+  trajectories/
+    traj-001.jsonl             # Raw trajectory — one step per line
+    traj-002.jsonl
+    ...
+  analyses/                    # Derivative data from prior analysis
+    traj-001.json
+    traj-002.json
+    ...
+  existing-playbooks/
+    *.json
+skills/
+  playbook-extraction/
+    SKILL.md                   # Guidance on how to extract playbooks
+resources/                     # (empty for this template)
+workspace/                     # Agent scratch space
+output/
+  playbooks/                   # New playbooks (JSON)
+  skills/                      # New skills (SKILL.md format)
+  updates/                     # Updates to existing playbooks
+  extraction-summary.json      # Required summary of results
+```
+
+### Template 3: Meta-Learning Reflection
+
+Replaces the heuristic `MetaLearner.generateReflection()` with semantic analysis.
+
+```typescript
+const metaReflectionTemplate: AgenticTaskTemplate<
+  MetaReflectionInput,
+  MetaObservation
+> = {
+  taskType: 'meta-reflection',
+  domain: 'meta-reflection',
+  description: 'Reflect on task execution to generate meta-learning observations',
+
+  outputConfig: {
+    files: [
+      {
+        path: 'meta-observation.json',
+        format: 'json',
+        schema: MetaObservationSchema,
+        required: true,
+        description: 'Reflection observations: what worked, what failed, lessons learned',
+      },
+    ],
+  },
+
+  assessComplexity(input) {
+    // Simple successful tasks with clear routing → heuristic
+    if (input.trajectory.outcome.success &&
+        input.routingDecision.confidence > 0.8) {
+      return 'heuristic';
+    }
+    // Failed tasks or uncertain routing → agent reflection
+    return 'lightweight';
+  },
+
+  heuristicFallback(input) {
+    // Existing MetaLearner logic
+  },
+
+  getSkills(input) {
+    return convertPlaybooksToSkills(input.reflectionPlaybooks ?? []);
+  },
+
+  getResources(input) {
+    return [];
+  },
+
+  async prepareWorkspace(input, workspacePath) {
+    const wm = this.workspaceManager;
+    const handle = { inputDir: join(workspacePath, 'input') } as WorkspaceHandle;
+
+    // Raw trajectory as JSONL
+    await wm.writeInputJsonl(handle, 'trajectories/execution.jsonl',
+      input.trajectory.steps
+    );
+
+    // Context with routing decision and injected playbooks
+    await wm.writeInputMarkdown(handle, 'context.md', {
+      taskId: input.trajectory.task.id,
+      domain: input.trajectory.task.domain,
+      outcome: input.trajectory.outcome.success ? 'success' : 'failure',
+      routingStrategy: input.routingDecision.strategy,
+      routingConfidence: input.routingDecision.confidence,
+      playbooksInjected: input.playbooksUsed.map(p => p.name),
+    }, `# Task\n\n${input.trajectory.task.description}\n\n` +
+       `# Routing Decision\n\n` +
+       `Strategy: ${input.routingDecision.strategy}\n` +
+       `Reasoning: ${input.routingDecision.reasoning}\n\n` +
+       `# Injected Playbooks\n\n` +
+       input.playbooksUsed.map(p =>
+         `- **${p.name}**: ${p.guidance.strategy}`
+       ).join('\n')
+    );
+  },
+
+  buildTaskPrompt(input) {
+    return `
+Reflect on the task execution to understand what worked and what didn't.
+
+## Input Files
+- input/context.md — Task, routing decision, and injected playbooks (YAML frontmatter)
+- input/trajectories/execution.jsonl — Full trajectory (one step per line)
+
+## Instructions
+1. Read the context — was the chosen strategy appropriate for this task?
+2. Review which playbooks were injected — were they actually helpful?
+   Did the agent follow the guidance? Was the guidance relevant?
+3. Analyze the trajectory — identify execution patterns:
+   - Was decomposition used? Was it effective?
+   - Were there refinement iterations? Were they productive?
+   - Was there backtracking or wasted effort?
+4. Assess the outcome quality relative to the effort expended.
+5. Generate concrete lessons: what worked, what failed, what to change next time.
+
+## Output
+Write your reflection to output/meta-observation.json.
+    `;
+  },
+
+  async collectOutput(workspacePath) {
+    // Read output/meta-observation.json
+  },
+
+  async processOutput(output, input, context) {
+    // Store in MetaMemory
+    // Check if strategy generation threshold reached
+  },
+};
+```
+
+### Template 4: Usage Inference
+
+Replaces the heuristic `PlaybookUsageInference` with semantic matching.
+
+```typescript
+const usageInferenceTemplate: AgenticTaskTemplate<
+  UsageInferenceInput,
+  PlaybookUsageResult[]
+> = {
+  taskType: 'usage-inference',
+  domain: 'usage-inference',
+  description: 'Determine which injected playbooks were actually followed',
+
+  outputConfig: {
+    files: [
+      {
+        path: 'usage-results.json',
+        format: 'json',
+        schema: PlaybookUsageResultArraySchema,
+        required: true,
+        description: 'Per-playbook usage assessment: followed, partially, not followed, helpfulness',
+      },
+    ],
+  },
+
+  assessComplexity(input) {
+    // No playbooks injected → trivial
+    if (input.injectedPlaybooks.length === 0) return 'heuristic';
+    // Few playbooks, short trajectory → heuristic word matching is OK
+    if (input.injectedPlaybooks.length <= 2 &&
+        input.trajectory.steps.length <= 10) {
+      return 'heuristic';
+    }
+    return 'lightweight';
+  },
+
+  heuristicFallback(input) {
+    // Existing PlaybookUsageInference logic
+    const inference = new PlaybookUsageInference();
+    return inference.inferUsage(input.trajectory, input.injectedPlaybooks);
+  },
+
+  getSkills(input) {
+    return convertPlaybooksToSkills(input.inferencePlaybooks ?? []);
+  },
+
+  getResources(input) {
+    return [];
+  },
+
+  async prepareWorkspace(input, workspacePath) {
+    const wm = this.workspaceManager;
+    const handle = { inputDir: join(workspacePath, 'input') } as WorkspaceHandle;
+
+    // Raw trajectory as JSONL
+    await wm.writeInputJsonl(handle, 'trajectories/execution.jsonl',
+      input.trajectory.steps
+    );
+
+    // Each injected playbook as its own markdown file
+    for (const playbook of input.injectedPlaybooks) {
+      await wm.writeInputMarkdown(handle, `playbooks/${playbook.name}.md`, {
+        playbookId: playbook.id,
+        name: playbook.name,
+        confidence: playbook.confidence,
+        domains: playbook.applicability.domains,
+      }, `# ${playbook.name}\n\n` +
+         `## Strategy\n${playbook.guidance.strategy}\n\n` +
+         `## Tactics\n${playbook.guidance.tactics.map(t => `- ${t}`).join('\n')}\n\n` +
+         (playbook.guidance.steps
+           ? `## Steps\n${playbook.guidance.steps.map((s, i) => `${i+1}. ${s}`).join('\n')}\n`
+           : '')
+      );
+    }
+  },
+
+  buildTaskPrompt(input) {
+    return `
+Determine which injected playbooks were actually followed during the trajectory.
+
+## Input Files
+- input/trajectories/execution.jsonl — Full trajectory (one step per line)
+- input/playbooks/*.md — Each injected playbook (YAML frontmatter + guidance)
+
+## Instructions
+For each playbook:
+1. Read its strategy, tactics, and steps from the markdown file.
+2. Grep the trajectory for evidence of following the guidance.
+   Look for semantic alignment, not just keyword matching.
+3. Assess confidence: clearly followed, partially followed, or not followed?
+4. If followed, was it helpful to the outcome?
+
+## Output
+Write results to output/usage-results.json.
+    `;
+  },
+
+  async collectOutput(workspacePath) {
+    // Read output/usage-results.json
+  },
+
+  async processOutput(output, input, context) {
+    // Update playbook success/failure counts in SkillLibrary
+    // Feed into effectiveness tracker
+  },
+};
+```
+
+### Template 5: Solution Evaluation
+
+Enhances the existing `evaluator.ts` Tier 2 with a workspace.
+
+```typescript
+const solutionEvaluationTemplate: AgenticTaskTemplate<
+  SolutionEvaluationInput,
+  EvaluationResult
+> = {
+  taskType: 'solution-evaluation',
+  domain: 'solution-evaluation',
+  description: 'Evaluate solution quality from trajectory',
+
+  outputConfig: {
+    files: [
+      {
+        path: 'evaluation.json',
+        format: 'json',
+        schema: EvaluationResultSchema,
+        required: true,
+        description: 'Quality assessment: meets requirements, edge cases, overall rating',
+      },
+    ],
+  },
+
+  assessComplexity(input) {
+    // Has programmatic verification → use that, skip agent
+    if (input.task.verification) return 'heuristic';
+    // Short successful trajectory → lightweight check
+    if (input.trajectory.outcome.success &&
+        input.trajectory.steps.length <= 10) {
+      return 'lightweight';
+    }
+    return 'standard';
+  },
+
+  heuristicFallback(input) {
+    // Existing Tier 1 (verification) + Tier 3 (heuristic) logic
+  },
+
+  getSkills(input) {
+    return convertPlaybooksToSkills(input.evaluationPlaybooks ?? []);
+  },
+
+  getResources(input) {
+    // For code evaluation, include codebase snapshot if available
+    if (input.codebasePath) {
+      return [{
+        path: 'codebase',
+        type: 'symlink' as const,
+        source: input.codebasePath,
+        description: 'Codebase snapshot for verifying solution against actual code',
+      }];
+    }
+    return [];
+  },
+
+  async prepareWorkspace(input, workspacePath) {
+    const wm = this.workspaceManager;
+    const handle = { inputDir: join(workspacePath, 'input') } as WorkspaceHandle;
+
+    // Raw trajectory as JSONL
+    await wm.writeInputJsonl(handle, 'trajectories/execution.jsonl',
+      input.trajectory.steps
+    );
+
+    // Task and solution context
+    await wm.writeInputMarkdown(handle, 'context.md', {
+      taskId: input.task.id,
+      domain: input.task.domain,
+      outcome: input.trajectory.outcome.success ? 'success' : 'failure',
+      hasSolution: input.solution !== undefined,
+    }, `# Task\n\n${input.task.description}\n\n` +
+       `# Solution\n\n\`\`\`\n${JSON.stringify(input.solution, null, 2)}\n\`\`\`\n`
+    );
+  },
+
+  buildTaskPrompt(input) {
+    return `
+Evaluate the quality of the solution produced by the agent.
+
+## Input Files
+- input/context.md — Task description and solution (YAML frontmatter)
+- input/trajectories/execution.jsonl — Full trajectory (one step per line)
+${input.codebasePath ? '- resources/codebase/ — Codebase snapshot for verification' : ''}
+
+## Instructions
+1. Read the original task and its success criteria from context.md.
+2. Grep the trajectory for key decision points and the approach taken.
+3. Assess:
+   - Does the solution meet the stated requirements?
+   - Are there edge cases or failure modes?
+   - Is the approach efficient or over-engineered?
+   - What is the overall quality (excellent/good/acceptable/poor)?
+4. If codebase is available, verify the solution against actual code.
+
+## Output
+Write evaluation to output/evaluation.json.
+    `;
+  },
+
+  async collectOutput(workspacePath) {
+    // Read output/evaluation.json
+  },
+
+  async processOutput(output, input, context) {
+    // Return to refinement loop if needed
+  },
+};
+```
+
+### Template 6: Team Analysis
+
+The team-specific template from `DESIGN-team-extraction-pipeline.md`, now using the standard workspace infrastructure.
+
+```typescript
+const teamAnalysisTemplate: AgenticTaskTemplate<
+  TeamAnalysisInput,
+  TeamAnalysisResult
+> = {
+  taskType: 'team-analysis',
+  domain: 'team-analysis',
+  description: 'Analyze multi-agent team execution and extract learning signals',
+  timeout: 300_000,
+
+  outputConfig: {
+    files: [
+      {
+        path: 'agent-credits.json',
+        format: 'json',
+        required: true,
+        description: 'Per-agent credit assignment based on causal contribution',
+      },
+      {
+        path: 'interaction-credits.json',
+        format: 'json',
+        required: true,
+        description: 'Per-interaction credit assignment',
+      },
+      {
+        path: 'coordination-assessment.md',
+        format: 'markdown',
+        required: true,
+        description: 'Overall coordination quality assessment',
+      },
+      {
+        path: 'lessons.json',
+        format: 'json',
+        required: true,
+        description: 'Role-specific and team-level lessons extracted',
+      },
+    ],
+  },
+
+  assessComplexity(input) {
+    // Small teams with clear outcomes → lightweight
+    if (input.members.length <= 2) return 'lightweight';
+    // Large teams or complex failures → thorough
+    if (input.members.length > 5 || !input.outcome.success) return 'thorough';
+    return 'standard';
+  },
+
+  // No heuristic fallback — team analysis always needs semantic understanding
+
+  getSkills(input) {
+    return convertPlaybooksToSkills(input.teamAnalysisPlaybooks ?? []);
+  },
+
+  getResources(input) {
+    // For coding teams, include codebase snapshot
+    if (input.codebasePath) {
+      return [{
+        path: 'codebase',
+        type: 'symlink' as const,
+        source: input.codebasePath,
+        description: 'Codebase for verifying team code contributions',
+      }];
+    }
+    return [];
+  },
+
+  async prepareWorkspace(input, workspacePath) {
+    const wm = this.workspaceManager;
+    const handle = { inputDir: join(workspacePath, 'input') } as WorkspaceHandle;
+
+    // Team context as markdown with frontmatter
+    await wm.writeInputMarkdown(handle, 'context.md', {
+      objective: input.objective,
+      teamSize: input.members.length,
+      roles: input.members.map(m => m.role),
+      outcome: input.outcome.success ? 'success' : 'failure',
+      totalInteractions: input.interactions.length,
+    }, `# Team Objective\n\n${input.objective}\n\n` +
+       `# Team Composition\n\n` +
+       input.members.map(m => `- **${m.role}** (${m.agentType}): ${m.description ?? 'N/A'}`).join('\n') +
+       `\n\n# Outcome\n\n${input.outcome.success ? 'Success' : 'Failure'}` +
+       (input.outcome.errorInfo ? `\n\n**Error:** ${input.outcome.errorInfo}` : '')
+    );
+
+    // Each agent's trajectory as JSONL — raw data
+    for (const member of input.members) {
+      await wm.writeInputJsonl(handle,
+        `trajectories/${member.role}.jsonl`,
+        member.trajectory.steps
+      );
+    }
+
+    // Interaction graph and timeline as JSON (structured data)
+    await wm.writeInputJson(handle, 'interactions/graph.json', input.interactionGraph);
+    await wm.writeInputJson(handle, 'interactions/timeline.json', input.interactions);
+
+    // Structural metrics (pre-computed, lightweight)
+    await wm.writeInputJson(handle, 'structural-metrics.json', input.structuralMetrics);
+  },
+
+  buildTaskPrompt(input) {
+    return `
+Analyze this multi-agent team execution to extract learning signals.
+
+## Input Files
+- input/context.md — Team objective, composition, and outcome (YAML frontmatter)
+- input/trajectories/*.jsonl — Per-agent raw trajectories (one step per line)
+- input/interactions/graph.json — Interaction graph (nodes = agents, edges = interactions)
+- input/interactions/timeline.json — Chronological interaction sequence
+- input/structural-metrics.json — Pre-computed structural metrics
+${input.codebasePath ? '- resources/codebase/ — Codebase snapshot' : ''}
+
+## Available Skills
+- Check skills/ directory for team analysis guidance
+
+## Instructions
+1. Read context.md for team overview and outcome.
+2. Grep across per-agent trajectories for cross-references and coordination patterns.
+3. Analyze the interaction graph for communication bottlenecks, delegation chains.
+4. Assess each agent's causal contribution to the team outcome (credit assignment).
+5. Evaluate coordination quality: was delegation effective? Were handoffs clean?
+6. Extract role-specific and team-level lessons.
+
+## Output
+- output/agent-credits.json — Per-agent credit scores with reasoning
+- output/interaction-credits.json — Per-interaction effectiveness scores
+- output/coordination-assessment.md — Qualitative coordination assessment
+- output/lessons.json — Extracted lessons (role-specific + team-level)
+    `;
+  },
+
+  async getAdditionalKnowledge(input, memory) {
+    // Query for team playbooks matching this task type
+    // Query for past team analysis experiences
+  },
+
+  async collectOutput(workspacePath) {
+    // Read all output files
+  },
+
+  async processOutput(output, input, context) {
+    // Store in TeamExperienceMemory
+    // Record TeamMetaObservation
+    // Accumulate for batch playbook extraction
+  },
+};
+```
+
+### Template 7: Team Playbook Extraction
+
+```typescript
+const teamPlaybookExtractionTemplate: AgenticTaskTemplate<
+  TeamPlaybookExtractionInput,
+  ExtractedTeamPlaybooks
+> = {
+  taskType: 'team-playbook-extraction',
+  domain: 'team-playbook-extraction',
+  description: 'Extract team coordination and role playbooks from lesson batch',
+  timeout: 600_000,
+
+  outputConfig: {
+    files: [
+      {
+        path: 'team-playbooks/',
+        format: 'json',
+        required: false,
+        description: 'Team coordination playbooks',
+      },
+      {
+        path: 'role-playbooks/',
+        format: 'json',
+        required: false,
+        description: 'Role-specific playbooks',
+      },
+      {
+        path: 'team-skills/',
+        format: 'skill-md',
+        required: false,
+        description: 'Team coordination skills in SKILL.md format',
+      },
+      {
+        path: 'role-skills/',
+        format: 'skill-md',
+        required: false,
+        description: 'Role-specific skills in SKILL.md format',
+      },
+      {
+        path: 'updates/',
+        format: 'json',
+        required: false,
+        description: 'Updates to existing team/role playbooks',
+      },
+      {
+        path: 'meta-strategies/',
+        format: 'json',
+        required: false,
+        description: 'Meta-level team formation strategies',
+      },
+      {
+        path: 'extraction-summary.json',
+        format: 'json',
+        required: true,
+        description: 'Summary of what was extracted and why',
+      },
+    ],
+  },
+
+  assessComplexity(input) {
+    // Always agentic — this is complex semantic work
+    if (input.lessonBatches.length > 10) return 'thorough';
+    return 'standard';
+  },
+
+  getSkills(input) {
+    return convertPlaybooksToSkills(input.extractionPlaybooks ?? []);
+  },
+
+  getResources(input) {
+    return [];
+  },
+
+  async prepareWorkspace(input, workspacePath) {
+    const wm = this.workspaceManager;
+    const handle = { inputDir: join(workspacePath, 'input') } as WorkspaceHandle;
+
+    // Batch overview
+    await wm.writeInputMarkdown(handle, 'summary.md', {
+      batchCount: input.lessonBatches.length,
+      totalLessons: input.lessonBatches.reduce((acc, b) => acc + b.lessons.length, 0),
+      roles: [...new Set(input.lessonBatches.flatMap(b => b.roles))],
+      existingTeamPlaybooks: input.existingTeamPlaybooks.length,
+      existingRolePlaybooks: input.existingRolePlaybooks.length,
+    }, `# Team Playbook Extraction Batch\n\n` +
+       `Extracting team coordination and role-specific playbooks from ` +
+       `${input.lessonBatches.length} lesson batches.`
+    );
+
+    // Lesson batches — derivative data from prior team analysis
+    for (let i = 0; i < input.lessonBatches.length; i++) {
+      const batch = input.lessonBatches[i];
+      await wm.writeInputMarkdown(handle, `lesson-batches/batch-${i}.md`, {
+        teamObjective: batch.objective,
+        teamOutcome: batch.outcome,
+        roles: batch.roles,
+        lessonCount: batch.lessons.length,
+      }, `# Lessons from: ${batch.objective}\n\n` +
+         batch.lessons.map(l =>
+           `## ${l.type === 'role' ? `Role: ${l.role}` : 'Team'}\n\n${l.content}\n`
+         ).join('\n')
+      );
+    }
+
+    // Existing playbooks for deduplication
+    for (const pb of input.existingTeamPlaybooks) {
+      await wm.writeInputJson(handle, `existing/team/${pb.name}.json`, pb);
+    }
+    for (const pb of input.existingRolePlaybooks) {
+      await wm.writeInputJson(handle, `existing/role/${pb.name}.json`, pb);
+    }
+  },
+
+  buildTaskPrompt(input) {
+    return `
+Extract team coordination and role playbooks from the lesson batches.
+
+## Input Files
+- input/summary.md — Batch overview (YAML frontmatter)
+- input/lesson-batches/*.md — Lessons from prior team analyses (derivative data)
+- input/existing/team/*.json — Existing team coordination playbooks
+- input/existing/role/*.json — Existing role-specific playbooks
+
+## Available Skills
+- Check skills/ directory for extraction guidance
+
+## Instructions
+1. Read the summary for an overview of what's available.
+2. Read each lesson batch — identify recurring patterns across batches.
+3. Extract three types of knowledge:
+   - **Role playbooks**: How to play a specific role effectively (delegation patterns,
+     communication styles, when to escalate)
+   - **Team coordination playbooks**: How to compose and coordinate teams
+     (formation patterns, interaction protocols, handoff strategies)
+   - **Meta-strategies**: Higher-level patterns about team formation itself
+     (when to use hub-and-spoke vs mesh, team size guidelines)
+4. Check against existing playbooks for deduplication and updates.
+5. Output both JSON playbooks and SKILL.md format skills.
+
+## Output
+- output/team-playbooks/ — Team coordination playbooks (JSON)
+- output/role-playbooks/ — Role-specific playbooks (JSON)
+- output/team-skills/ — Team coordination skills (SKILL.md format)
+- output/role-skills/ — Role-specific skills (SKILL.md format)
+- output/updates/ — Updates to existing playbooks
+- output/meta-strategies/ — Meta-level team formation strategies
+- output/extraction-summary.json — Required summary of extraction results
+    `;
+  },
+
+  async collectOutput(workspacePath) {
+    // Read all output directories
+  },
+
+  async processOutput(output, input, context) {
+    // Store new playbooks
+    // Convert SKILL.md outputs to playbooks (or store as skills)
+    // Apply updates
+    // Store meta-strategies
+  },
+};
+```
+
+---
+
+## Playbook ↔ Skill Conversion
+
+The system stores knowledge as Playbooks internally but presents it to workspace agents as Skills (SKILL.md, Agent Skills open standard format). A bidirectional converter handles the translation:
+
+```typescript
+/**
+ * Convert Playbooks to Agent Skills for workspace loading.
+ */
+function convertPlaybooksToSkills(playbooks: Playbook[]): AgentSkillSpec[] {
+  return playbooks.map(playbook => ({
+    name: playbook.name,
+    source: 'playbook-conversion' as const,
+    content: generateSkillMd(playbook),
+  }));
+}
+
+/**
+ * Generate SKILL.md content from a Playbook.
+ */
+function generateSkillMd(playbook: Playbook): string {
+  const sections = [
+    `# ${playbook.name}`,
+    '',
+    `## When to Use`,
+    ...playbook.applicability.situations.map(s => `- ${s}`),
+    '',
+    `## Triggers`,
+    ...playbook.applicability.triggers.map(t => `- ${t}`),
+    '',
+    `## Strategy`,
+    playbook.guidance.strategy,
+    '',
+    `## Tactics`,
+    ...playbook.guidance.tactics.map(t => `- ${t}`),
+  ];
+
+  if (playbook.guidance.steps?.length) {
+    sections.push('', '## Steps');
+    playbook.guidance.steps.forEach((step, i) => {
+      sections.push(`${i + 1}. ${step}`);
+    });
+  }
+
+  if (playbook.guidance.codeExample) {
+    sections.push('', '## Example', '```', playbook.guidance.codeExample, '```');
+  }
+
+  sections.push(
+    '', '## Verification',
+    ...playbook.verification.successIndicators.map(s => `- ✓ ${s}`),
+    ...playbook.verification.failureIndicators.map(f => `- ✗ ${f}`),
+  );
+
+  return sections.join('\n');
+}
+
+/**
+ * Parse SKILL.md output back into a Playbook.
+ */
+function parseSkillMdToPlaybook(skillMd: string, skillName: string): Playbook {
+  // Parse markdown sections → populate Playbook fields
+  // Used when agents produce SKILL.md outputs
+}
+```
+
+This approach means:
+- **Input side**: Agents receive domain-appropriate SKILL.md files — a standard format they can read naturally
+- **Output side**: Agents can produce either JSON playbooks or SKILL.md files — both are accepted
+- **Storage**: Everything is stored as Playbooks internally for consistency with the existing evolution/confidence tracking
+
+---
+
+## Integration with Existing Pipeline
+
+### Before: Direct calls to heuristic analyzers
+
+```typescript
+// Current LearningPipeline.processTrajectory()
+async processTrajectory(trajectory: Trajectory): Promise<ProcessResult> {
+  await this.memory.storeTrajectory(trajectory);
+  const analysis = await this.analyzer.analyze(trajectory);     // heuristic
+  this.accumulated.push({ trajectory, analysis });
+  return { stored: true, analysis, abstractable: analysis.abstractable };
+}
+
+// Current LearningPipeline.runBatchLearning()
+async runBatchLearning(): Promise<BatchResult> {
+  const extracted = this.extractor.extract(                     // heuristic
+    this.accumulated.map(a => a.trajectory),
+    this.accumulated.map(a => a.analysis),
+    existingPlaybooks
+  );
+  // ...
+}
+```
+
+### After: Route through AgenticTaskRunner
+
+```typescript
+// Updated LearningPipeline.processTrajectory()
+async processTrajectory(trajectory: Trajectory): Promise<ProcessResult> {
+  await this.memory.storeTrajectory(trajectory);
+
+  // Agentic analysis (with heuristic fallback for simple cases)
+  const { output: analysis } = await this.taskRunner.run(
+    trajectoryAnalysisTemplate,
+    { trajectory, creditStrategy: this.config.creditStrategy }
+  );
+
+  this.accumulated.push({ trajectory, analysis });
+  return { stored: true, analysis, abstractable: analysis.abstractable };
+}
+
+// Updated LearningPipeline.runBatchLearning()
+async runBatchLearning(): Promise<BatchResult> {
+  const { output: extracted } = await this.taskRunner.run(
+    playbookExtractionTemplate,
+    {
+      trajectories: this.accumulated.map(a => a.trajectory),
+      analyses: this.accumulated.map(a => a.analysis),
+      existingPlaybooks,
+    }
+  );
+  // ...
+}
+```
+
+The calling code barely changes. The `AgenticTaskRunner` handles all workspace lifecycle, knowledge injection, and meta-learning internally. The `assessComplexity` check means simple trajectories still use the fast heuristic path.
+
+### Updated Atlas Integration
+
+```typescript
+class Atlas {
+  private taskRunner: AgenticTaskRunner;
+
+  constructor(config: AtlasConfig) {
+    const workspaceManager = new WorkspaceManager(config.workspaceBaseDir);
+    this.taskRunner = new AgenticTaskRunner(
+      workspaceManager,
+      this.agentManager,
+      this.memory,
+      this.learningPipeline,
+      config.agenticTasks
+    );
+
+    // Inject runner into pipelines
+    this.learningPipeline.setTaskRunner(this.taskRunner);
+    this.teamPipeline.setTaskRunner(this.taskRunner);
+  }
+
+  // Existing methods work as before — the runner is internal
+  async solve(task: Task): Promise<SolveResult> { /* unchanged */ }
+
+  // Team methods use the same runner
+  async processTeamTrajectory(input: TeamTrajectoryInput) {
+    return this.taskRunner.run(teamAnalysisTemplate, input);
+  }
+
+  async runTeamBatchLearning() {
+    return this.taskRunner.run(teamPlaybookExtractionTemplate, this.teamAccumulated);
+  }
+}
+```
+
+---
+
+## Cost Management
+
+The `assessComplexity` method on each template is the primary cost control. Not every analysis needs a full agent:
+
+```
+           ┌───────────────────────────────────────────────────┐
+           │              COMPLEXITY ASSESSMENT                │
+           │                                                   │
+           │  Input characteristics          Execution path    │
+           │  ─────────────────────          ──────────────     │
+           │                                                   │
+           │  Simple, clear outcome  ──────► heuristic         │
+           │  (5 steps, success)             (existing code)   │
+           │                                 ~0 tokens         │
+           │                                                   │
+           │  Moderate complexity    ──────► lightweight agent  │
+           │  (10-20 steps)                  ~2K tokens         │
+           │                                 60s timeout        │
+           │                                                   │
+           │  Complex / failed       ──────► standard agent    │
+           │  (20+ steps, failure)           ~5K tokens         │
+           │                                 120s timeout       │
+           │                                                   │
+           │  Large batch / team     ──────► thorough agent    │
+           │  (10+ trajectories)             ~10K tokens        │
+           │                                 300s timeout       │
+           └───────────────────────────────────────────────────┘
+```
+
+Estimates for a typical workflow:
+
+| Event | Template | Likely Complexity | Cost |
+|-------|----------|-------------------|------|
+| Simple task completed | trajectory-analysis | heuristic | ~0 |
+| Complex task failed | trajectory-analysis | standard | ~5K tokens |
+| Playbook usage check (2 playbooks) | usage-inference | heuristic | ~0 |
+| Playbook usage check (5 playbooks) | usage-inference | lightweight | ~2K tokens |
+| Post-task reflection (clear success) | meta-reflection | heuristic | ~0 |
+| Post-task reflection (ambiguous failure) | meta-reflection | lightweight | ~2K tokens |
+| Batch of 10 trajectories | playbook-extraction | standard | ~8K tokens |
+| Team execution (3 agents) | team-analysis | lightweight | ~4K tokens |
+| Team execution (6 agents, failure) | team-analysis | thorough | ~15K tokens |
+| Team lesson batch (5 executions) | team-playbook-extraction | standard | ~10K tokens |
+
+Most individual task completions hit the heuristic path. Agent analysis is reserved for cases where semantic understanding matters: failures, complex trajectories, batch extraction.
+
+---
+
+## Meta-Learning Across All Templates
+
+Every agentic analysis produces a trajectory that feeds through the individual learning pipeline. Over time, each analysis domain accumulates its own playbooks:
+
+```
+Domain: trajectory-analysis
+  Playbooks about how to analyze trajectories effectively
+  → Injected into future trajectory analysis agents
+
+Domain: playbook-extraction
+  Playbooks about how to extract playbooks effectively
+  → Injected into future extraction agents
+
+Domain: meta-reflection
+  Playbooks about how to reflect on executions effectively
+  → Injected into future reflection agents
+
+Domain: team-analysis
+  Playbooks about how to analyze team executions effectively
+  → Injected into future team analysis agents
+
+Domain: team-playbook-extraction
+  Playbooks about how to extract team playbooks effectively
+  → Injected into future team extraction agents
+```
+
+This is the recursive loop: the system learns how to learn. The `AgenticTaskRunner` makes this automatic — every template domain accumulates analysis expertise through the existing learning pipeline, without any template-specific meta-learning code.
+
+---
+
+## Migration Path
+
+### Phase 1: Infrastructure
+- Implement `WorkspaceManager`
+- Implement `AgenticTaskRunner`
+- Define `AgenticTaskTemplate` interface
+- Wire into Atlas constructor
+
+### Phase 2: First Template (team analysis)
+- Implement `teamAnalysisTemplate` (new, no existing code to replace)
+- Implement `teamPlaybookExtractionTemplate` (new)
+- Validates the infrastructure end-to-end
+
+### Phase 3: Migrate Existing Analysis
+- `trajectoryAnalysisTemplate` replacing `TrajectoryAnalyzer` (keep as heuristic fallback)
+- `playbookExtractionTemplate` replacing `PlaybookExtractor` + `LLMPlaybookExtractor`
+- `metaReflectionTemplate` replacing `MetaLearner.generateReflection()`
+- `usageInferenceTemplate` replacing `PlaybookUsageInference`
+- `solutionEvaluationTemplate` enhancing `evaluator.ts` Tier 2
+
+Each migration preserves the existing heuristic as `heuristicFallback` — no functionality is lost, and simple cases stay fast.
+
+### Phase 4: Tuning
+- Calibrate `assessComplexity` thresholds based on real usage
+- Monitor cost vs. quality tradeoffs per template
+- Refine task prompts based on accumulated analysis playbooks
+- Prune unnecessary agentic invocations where heuristics are sufficient