cleveragents-core/docs/adr/ADR-049-cli-communication-pattern.md

ADR-049: CLI Communication Pattern

Status: Accepted Date: 2026-04-16 Issues: #9899, #9859

Context

The CleverAgents CLI is the primary user-facing interface for the platform. It is implemented in the Presentation layer and communicates with the Application layer to execute commands.

Current State: Direct Import Pattern

The current CLI implementation uses direct Python imports to call Application-layer services:

# Current pattern (Presentation layer)
from cleveragents.application.plan_service import PlanService
from cleveragents.application.project_service import ProjectService

def plan_execute(plan_id: str):
    service = PlanService()
    service.execute(plan_id)

This creates a reverse dependency: the Presentation layer directly imports from the Application layer, bypassing the A2A protocol boundary defined in ADR-001 (Layered Architecture) and ADR-047 (A2A Standard Adoption).

The A2A Specification

ADR-047 establishes that all client-server interaction must flow through A2A. The A2A protocol is the sole communication contract between the Presentation and Application layers. In server mode, this is already enforced -- CLI commands route through A2A over HTTP. In local mode, the intent is for CLI commands to route through A2A over stdio (via A2aLocalFacade).

The Problem

The direct import pattern creates several issues:

1. Architectural violation: The Presentation layer has a compile-time dependency on the Application layer, violating the layered boundary defined in ADR-001.
2. Import-linter failures: The import-linter tool flags these imports as boundary violations in CI.
3. Reverse dependency: If the Application layer changes its internal API, the CLI breaks -- even if the A2A contract is unchanged.
4. Testing complexity: CLI tests must mock Application-layer internals rather than the A2A protocol boundary.
5. Inconsistency: Server-mode CLI correctly uses A2A; local-mode CLI bypasses it.

Decision

Immediate: Local CLI Exemption

The direct import pattern is permitted under a documented local CLI exemption until M9 (v3.8.0). This exemption is granted because:

• The full A2A migration requires significant refactoring across all CLI command handlers.
• The local-mode A2A transport (A2aLocalFacade over stdio) is not yet fully implemented.
• The performance impact of routing all local CLI commands through A2A needs measurement.

Exemption Rules:

1. The exemption applies only to the local (non-server) CLI execution path.
2. All server-mode CLI commands must route through A2A (already enforced; no exemption granted).
3. The import-linter configuration is updated to explicitly allow the exempted imports with a # cli-exemption: local-only annotation in the import-linter config file.
4. No new direct imports may be added without a corresponding issue tracking the M9 migration.
5. All exempted imports must be documented in docs/adr/ADR-049-cli-communication-pattern.md (this document).

Import-Linter Configuration:

[importlinter:contract:cli-to-application]
name = CLI must not import Application layer directly
type = forbidden
source_modules = cleveragents.cli
forbidden_modules = cleveragents.application
ignore_imports =
    # cli-exemption: local-only -- tracked for M9 migration
    cleveragents.cli.commands.plan:cleveragents.application.plan_service
    cleveragents.cli.commands.project:cleveragents.application.project_service
    cleveragents.cli.commands.actor:cleveragents.application.actor_service
    cleveragents.cli.commands.resource:cleveragents.application.resource_service
    cleveragents.cli.commands.action:cleveragents.application.action_service
    cleveragents.cli.commands.invariant:cleveragents.application.invariant_service
    cleveragents.cli.commands.session:cleveragents.application.session_service
    cleveragents.cli.commands.config:cleveragents.application.config_service
    cleveragents.cli.commands.skill:cleveragents.application.skill_service
    cleveragents.cli.commands.tool:cleveragents.application.tool_service
    cleveragents.cli.commands.validation:cleveragents.application.validation_service
    cleveragents.cli.commands.automation_profile:cleveragents.application.automation_profile_service
    cleveragents.cli.commands.lsp:cleveragents.application.lsp_service

M9 Migration: Full A2A Adoption

In M9 (v3.8.0), the CLI will be fully migrated to use A2aLocalFacade for all local-mode commands:

# Target pattern (M9)
from cleveragents.cli.a2a_local_facade import A2aLocalFacade

def plan_execute(plan_id: str):
    facade = A2aLocalFacade()
    facade.call("_cleveragents/plan.execute", {"plan_id": plan_id})

Migration Steps:

1. Implement A2aLocalFacade with full coverage of all _cleveragents/ extension methods.
2. Measure performance overhead of local A2A routing (target: < 5ms per command).
3. Replace all direct service imports in CLI command handlers with facade.call().
4. Remove all # cli-exemption: local-only annotations from import-linter config.
5. Remove the ignore_imports block from the import-linter contract.
6. Validate with full CLI integration test suite.
7. Update this ADR status to "Superseded" and reference the M9 implementation PR.

Consequences

Positive

• Architectural consistency: Local and server-mode CLI use the same protocol boundary.
• Testability: CLI tests mock the A2A facade rather than Application-layer internals.
• Decoupling: Application-layer internal API changes do not break the CLI as long as the A2A contract is preserved.
• Import-linter clean: No boundary violations in CI after M9 migration.

Negative

• Performance overhead: Routing through A2A adds latency (estimated < 5ms for local stdio transport). Acceptable for interactive CLI use.
• Migration effort: All CLI command handlers must be refactored in M9.
• Temporary inconsistency: Until M9, local-mode CLI bypasses the A2A boundary while server-mode enforces it.

Neutral

• The exemption is explicitly documented and tracked, preventing silent accumulation of additional violations.
• The import-linter configuration makes the exemption visible in CI output.

References

• ADR-001: Layered Architecture
• ADR-047: A2A Standard Adoption
• ADR-048: Server Application Architecture
• Spec: M7 CLI Communication Pattern Migration
• Issue #9899: Invariant reconciliation multi-phase enforcement
• Issue #9859: ACMS thread-safety model documentation