CLAUDE

CLAUDE.md — Agent System (engine/src/agents/)

This file provides guidance to Claude Code (claude.ai/code) when working on the COSMO 2.3 agent subsystem.

---

Overview

Every agent is a subclass of BaseAgent (base-agent.js). AgentExecutor (agent-executor.js) is the single point of control for spawning, executing, and integrating agent results. AgentRegistry (agent-registry.js) tracks live and historical state. AgentResultsQueue (results-queue.js) persists results to coordinator/results_queue.jsonl.

---

Agent Executor — Spawn Flow

spawnAgent(missionSpec) is the single entry point. Returns agent.agentId immediately; execution is async.

Check sequence:

1. Concurrency guard: registry.canSpawnMore(maxConcurrent). Strategic/urgent goals bypass this.
2. Goal dedup: registry.isGoalBeingPursued(goalId) — rejects if already active.
3. SpawnGate evaluation: Memory similarity (≥0.9 cosine) and results queue similarity (≥0.55 Jaccard). See spawn-gate details below.
4. IDE-First routing: When config.ideFirst.enabled, all types except research and consistency are remapped to ide.
5. Agent class lookup: Unregistered type logs error with all registered keys, returns null.
6. Mission enrichment: enrichMissionWithArtifacts() discovers predecessor task artifacts.
7. Resource injection: memory, goals, messageQueue, mcp, pathResolver, frontierGate, capabilities, clusterStateStore.
8. Fire-and-forget execution: executeAgentAsync(agent) — not awaited.

agent.run() lifecycle (BaseAgent):

1. Status → running, emit start
2. onStart() hook
3. Promise.race([execute(), timeoutPromise(maxDuration)]) — default 5 min
4. On success: status → completed, onComplete(), buildFinalResults()
5. assessAccomplishment() — if zero substantive output, status → completed_unproductive

---

Complete Agent Catalog

Agent Class	Type Key	Purpose
ResearchAgent	research	Web search, code analysis via MCP, synthesizes findings. NOT remapped by IDE-First.
AnalysisAgent	analysis	Multi-perspective deep analysis; randomly selects 3 of 13 frameworks per run
SynthesisAgent	synthesis	Writes structured synthesis reports; handles final deliverable assembly when isFinalSynthesis
ExplorationAgent	exploration	Creative lateral thinking; 3 exploration vectors + cross-vector connections
PlanningAgent	planning	Decomposes goals into 3–7 sub-goals with topological sort
IntegrationAgent	integration	Finds patterns/contradictions across recent agent work (4-hour lookback)
QualityAssuranceAgent	qualityassurance	Validates agent outputs before memory integration. Never QA-checks itself.
IDEAgent	ide	Multi-turn agentic LLM loop with tool calls. COSMO's "motor cortex."
CodeCreationAgent	codecreation	Generates code files; plan-mode by default; local or container execution
CodeExecutionAgent	codeexecution	Runs Python in containers or locally; persistent validation tracking
CodebaseExplorationAgent	codebaseexploration	READ-ONLY codebase audit: architecture, deps, quality, patterns
DocumentCreationAgent	documentcreation	Business/technical docs; 25+ templates; Markdown/HTML output
DocumentAnalysisAgent	documentanalysis	Document comparison, evolution tracking, metadata extraction
DocumentCompilerAgent	documentcompiler	Dual-substrate compilation: narrative + technical specification
SpecializedBinaryAgent	specializedbinary	Text extraction from PDF, DOCX, XLSX, .gz files
ConsistencyAgent	consistency	Branch divergence evaluation. NOT remapped by IDE-First.
ExperimentalAgent	experimental	Local OS autonomy; requires user approval; hard limits: 900s/200 actions (Deprecated — replaced by AutomationAgent)
CompletionAgent	completion	Oversight and completion validation; human-in-the-loop review
DataAcquisitionAgent	dataacquisition	Web scraping, API consumption, file downloading, feed ingestion. CLI-first, tool-composing.
DataPipelineAgent	datapipeline	ETL, database creation (SQLite/DuckDB), validation, export. Transforms raw data into structured knowledge.
InfrastructureAgent	infrastructure	Container management, service setup, environment provisioning. Docker, compose, venv, nvm.
AutomationAgent	automation	General-purpose OS automation, file operations, process management. Graduated safety model. Replaces ExperimentalAgent.