feat: create subagent definitions for deepagents library

[avoidwork]

What

Implemented a full subagent definition framework for the deepagents library, adding 8 specialized agents with focused tool access and system prompts.

Changes

New Files (34 files, +1939 lines)

Agent Definitions:

• src/agent/agentRegistry.js — AgentRegistry class with addAgent, getAgent, listAgents, validateAgent, clear
• src/agent/agents/ — 8 agent definition files:
  • search.js — Multi-source search with synthesis
  • debug.js — Error tracing and fix proposals
  • code-review.js — Structured code reviews with severity ratings
  • research.js — Multi-step research with source tracking
  • testing.js — Test generation and gap analysis
  • documentation.js — Documentation updates and generation
  • security-audit.js — Security scanning and vulnerability detection
  • performance.js — Performance benchmarking and optimization
• src/agent/agents/index.js — Agent registry index with getAllAgents()

Orchestrator Integration:

• src/agent/deepAgents.js — Updated createDeepAgentsOrchestrator() with subagent definitions, tool filtering, and agent invocation logging

Tool Classification:

• src/tools/index.js — Added TOOL_CLASSIFICATIONS mapping tools to agent types, getToolsForAgentTypes() filtering function, exported TOOLS const

Tests:

• tests/unit/agentRegistry.test.js — 16 tests for registry CRUD and validation
• tests/unit/agentDefinitions.test.js — 24 tests for agent structure, output formats, tool classification

Documentation:

• README.md — Added subagent documentation section with agent table and tool access mappings

OpenSpec:

• openspec/changes/create-subagent-definitions-deepagents/ — Full change proposal, design, tasks, and spec deltas (now archived)
• openspec/specs/ — 11 spec files created/updated (agent-registry, code-review-agent, debug-agent, documentation-agent, performance-agent, research-agent, search-agent, security-audit-agent, subagent-definitions, testing-agent, tool-classification)

Capabilities Added

• subagent-definitions — Framework for defining specialized subagents with focused tool access
• agent-registry — Registry pattern for loading and validating subagent definitions
• tool-classification — Tool filtering system that categorizes tools by agent type
• 8 specialized agents: search, debug, code-review, research, testing, documentation, security-audit, performance

Testing

• 1037 tests pass (all existing + 40 new)
• Lint clean (oxlint: 0 warnings, 0 errors)
• App starts and responds correctly

Notes

• subAgent tool routing (task 1.3) deferred — handled by deepagents library natively
• Parallel execution (task 10.2) deferred — handled by deepagents library
• Integration tests for parallel execution (task 11.3) deferred — library handles internally

[avoidwork]

Implementation Audit: create-subagent-definitions-deepagents

Goal Fulfillment

Goal 1: Subagent Definition Framework

Status: ✅ Complete

• AgentRegistry class in src/agent/agentRegistry.js with addAgent, getAgent, listAgents, validateAgent, clear
• getAllAgents() in src/agent/agents/index.js returns all 8 agent definitions
• Each agent has name, description, and systemPrompt with structured output format

Goal 2: Eight Agents Across Three Tiers

Status: ✅ Complete

• High Priority: Search, Debug, Code Review, Research — all implemented with system prompts and tool access
• Medium Priority: Testing, Documentation — implemented with system prompts and tool access
• Lower Priority: Security Audit, Performance — implemented with system prompts and tool access

Goal 3: Tool Filtering via TOOL_CLASSIFICATIONS

Status: ✅ Complete

• TOOL_CLASSIFICATIONS in src/tools/index.js maps each tool to agent type classifications
• getToolsForAgentTypes() filters tools by agent type
• createSubagentDefinitions() in deepAgents.js applies filtering per agent

Goal 4: Orchestrator Integration

Status: ✅ Complete

• createDeepAgentsOrchestrator() in src/agent/deepAgents.js wires all agents with filtered tool sets
• Agent invocation logging via logger.info() for each agent's tool set
• Three filesystem backends: core, context, DMZ

Goal 5: Tests

Status: ✅ Complete

• tests/unit/agentRegistry.test.js — 16 tests for registry CRUD and validation
• tests/unit/agentDefinitions.test.js — 24 tests for agent structure, output formats, tool classification

Goal 6: Documentation

Status: ✅ Complete

• JSDoc on all public functions and classes
• README.md updated with subagent documentation section
• All new files have proper documentation

Spec Compliance

Proposal.md

• All proposed capabilities implemented
• All impact areas addressed
• No deviations from original plan

Design.md

• Registry pattern decision implemented correctly
• Tool filtering via TOOL_CLASSIFICATIONS implemented
• Output format contracts via system prompts implemented
• Parallel execution support deferred to deepagents library (acceptable)

Tasks.md

• 1.1 ✅ — AgentRegistry created
• 1.2 ✅ — TOOL_CLASSIFICATIONS updated
• 1.3 ⏸️ — Deferred (routing handled by deepagents library)
• 2.x ✅ — Search agent complete
• 3.x ✅ — Debug agent complete
• 4.x ✅ — Code review agent complete
• 5.x ✅ — Research agent complete
• 6.x ✅ — Testing agent complete
• 7.x ✅ — Documentation agent complete
• 8.x ✅ — Security audit agent complete
• 9.x ✅ — Performance agent complete
• 10.x ✅ — Orchestrator integration complete
• 11.1 ✅ — AgentRegistry tests
• 11.2 ⏸️ — Deferred (no separate subAgent tool exists)
• 11.3 ⏸️ — Deferred (parallel execution handled by deepagents library)
• 11.4 ✅ — Agent definition tests
• 12.1 ✅ — README updated
• 12.2 ✅ — JSDoc added
• 12.3 ✅ — Tests pass, lint clean

Quality Check

Code Quality

• All files follow project conventions (2-space indent, camelCase, JSDoc)
• No hardcoded secrets, no console.log, no eval
• Error handling present in AgentRegistry (throw on duplicate, validate required fields)
• Clean imports, no unused variables

Test Coverage

• 1037 tests pass (all existing + 40 new)
• AgentRegistry: 16 tests covering add, get, list, validate, clear
• AgentDefinitions: 24 tests covering structure, output formats, tool classification
• No test failures

Lint & Formatting

• oxlint: 0 warnings, 0 errors
• oxfmt: all files formatted correctly

Deferred Items (Acceptable)

1. 1.3 — subAgent tool routing: The deepagents library handles subagent invocation natively. A separate subAgent tool is not needed — the orchestrator routes automatically.
2. 11.2 — subAgent tool tests: No separate subAgent tool exists; routing is handled by the deepagents library.
3. 11.3 — Integration tests for parallel execution: Parallel execution is handled by the deepagents library's internal orchestration.

Verdict

Implementation is complete and ready for archive. All core goals fulfilled, specs matched, tests pass, lint clean. Deferred items are justified by the deepagents library architecture.