agentic-mobile-control/openspec/specs/multi-agent-collaboration/spec.md

multi-agent-collaboration Specification

Purpose

TBD - created by archiving change multi-agent-runtime. Update Purpose after archive.

Requirements

Requirement: Handoff protocol data contracts

The system SHALL define Observation, VerificationVerdict, ReflectionOutcome, and ReflectionAction as plain dataclasses with to_dict()/from_dict() methods, forming the stable, spec'd contract passed between the Observer, Verifier, and Reflector roles, independent of any single role's internal implementation.

Scenario: Handoff dataclasses round-trip through serialization

• WHEN an Observation, VerificationVerdict, or ReflectionOutcome instance is serialized via to_dict() and then reconstructed via from_dict()
• THEN the reconstructed instance is equal to the original instance

Requirement: Observer produces an Observation from available device state

The system SHALL provide an Observer role that produces an Observation summarizing current device state, using SemanticScene and WorldState when available and falling back to the raw Scene/PlannedStep/StepResult when either or both are absent.

Scenario: Observation succeeds with SemanticScene and WorldState present

• WHEN Observer.observe(...) is called and both SemanticScene and WorldState are available
• THEN it returns an Observation incorporating both as context

Scenario: Observation degrades gracefully when semantic state is absent

• WHEN Observer.observe(...) is called and SemanticScene and/or WorldState is None
• THEN it returns an Observation built from the raw Scene/PlannedStep/StepResult instead of raising an exception

Requirement: Verifier checks whether an executed step achieved its intended effect

The system SHALL provide a Verifier role that, after a PlannedStep has already been executed by the existing Executor, compares a pre-step and post-step Observation against the step's stated intent and produces a VerificationVerdict indicating whether the intended effect was actually achieved, distinct from and running after the Executor's own low-level tool-call retry.

Scenario: Verifier confirms an achieved effect

• WHEN Verifier.verify(...) is called with a pre-step Observation, a post-step Observation, the executed PlannedStep, and its StepResult, and the post-step Observation reflects the step's stated intent
• THEN it returns a VerificationVerdict marking the step as achieved

Scenario: Verifier flags a mechanically-successful but semantically-failed step

• WHEN the StepResult reports mechanical success but the post-step Observation does not reflect the step's stated intent
• THEN Verifier.verify(...) returns a VerificationVerdict marking the step as not achieved

Requirement: Reflector proposes bounded recovery, never a blind re-issue

The system SHALL invoke a Reflector role only when the Verifier produces a not-achieved VerificationVerdict, and the Reflector SHALL analyze the Observation/PlannedStep/StepResult/verdict to produce a ReflectionOutcome carrying either a bounded, distinct recovery ReflectionAction or a replan request back to the Planner, never an outcome that simply re-issues the identical failed step.

Scenario: Reflector proposes a distinct recovery action

• WHEN Reflector.reflect(...) is invoked following a not-achieved VerificationVerdict and a distinct corrective action is identifiable
• THEN it returns a ReflectionOutcome carrying a ReflectionAction that differs from the originally failed PlannedStep

Scenario: Reflector requests a replan when no bounded recovery action applies

• WHEN Reflector.reflect(...) is invoked and no bounded corrective action is identifiable from the available Observation/PlannedStep/StepResult/verdict
• THEN it returns a ReflectionOutcome carrying a replan request rather than re-issuing the failed step

Requirement: Reflection-driven recovery is bounded by an explicit ceiling

The system SHALL enforce a configurable maximum number of Reflector-triggered recovery attempts per task, tracked independently of and in addition to the Executor's own max_retries, so that a persistently-failing step cannot loop indefinitely between the Verifier and Reflector.

Scenario: Reflection loop stops once the ceiling is reached

• WHEN a task's Verifier-Reflector loop reaches the configured maximum reflection-recovery attempts without a step being verified as achieved
• THEN the CollaborativeTaskRunner stops attempting further reflection-driven recovery for that task and surfaces the failure instead of continuing the loop

Requirement: Multi-agent collaboration composes existing Planner/Executor without modifying them

The system SHALL provide a CollaborativeTaskRunner that composes the existing Planner, Executor, and TaskRunner (agent-runtime) by import, without modifying runtime/planner.py, runtime/executor.py, or runtime/task.py, and SHALL default to disabled so that applying this capability does not alter any existing task's behavior, latency, or cost unless explicitly enabled.

Scenario: Collaboration disabled by default leaves existing task behavior unchanged

• WHEN a task is run without explicitly enabling multi-agent collaboration
• THEN it executes exactly as runtime/task.py's existing TaskRunner.run() today, with no Observer/Verifier/Reflector invoked

Scenario: Enabling collaboration does not require changes to Planner or Executor

• WHEN a task is run with multi-agent collaboration explicitly enabled via CollaborativeTaskRunner
• THEN the existing Planner.plan() and Executor.execute() are invoked unchanged, with the Observer/Verifier/Reflector roles composed around them