Documentation

adrs/055-agent-teams-integration.md

ADR 055: Agent Teams Integration

Status

Accepted

Context

The Dynaplex Cortex system originally provided agent coordination through a custom-built stack:

  • Messaging: SQLite-backed agent-to-agent inbox/outbox messaging with MCP tools
  • Reservations: File/path locking system to prevent edit conflicts
  • Memory: Session persistence, diary entries, and playbook rules
  • Identity: SQLite-backed identity claim/release with heartbeat monitoring

This system was implemented as three separate .NET projects (messaging, memory, server) with ~21 MCP tools, ~12 database tables, and associated CLI commands, hooks, and UI pages.

Claude Code now provides Agent Teams, a native orchestration feature where a lead agent can spawn teammates who work within the same worktree. This overlaps significantly with our custom coordination system.

Decision

Replace the custom Cortex messaging, reservations, and memory systems with:

  1. Claude Code Agent Teams for intra-session multi-agent coordination
  2. File-based identity management via .dplx/config.json with filesystem state tracking
  3. Sibling worktrees (../acsis-core-{name}-worktree/) managed by dplx session new and dplx session clean
  4. Simplified hooks reduced from 5 to 3 (SessionStart, PreCompact, SessionEnd)

Consequences

Positive

  • Removed ~12,500 lines of custom coordination code
  • Eliminated 21 MCP tools, 12 database tables, and 2 SQLite databases
  • Session startup is near-instant (no dotnet tool invocations)
  • Native Agent Teams integration provides better orchestration than custom messaging
  • Simpler mental model: identity is a config file, "in use" is a directory check
  • Linear is the single source of truth for persistent cross-session tracking

Negative

  • Historical messaging data in ~/.dynaplex/ SQLite files is orphaned (not deleted, just unused)
  • Agent Teams is still an experimental Claude Code feature (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)
  • No more structured agent-to-agent messaging for cross-session communication (Linear fills this gap)

Neutral

  • The Cortex web UI is retained for identity management and documentation portal
  • The dplx CLI tool is retained for identity commands and the web server