agentic-mobile-control/openspec/changes/archive/2026-07-06-multi-agent-runtime/tasks.md

1. Package scaffolding

• 1.1 Create the agents/ package (__init__.py, models.py, observer.py, verifier.py, reflector.py, collab_runner.py, config.py)
• 1.2 Add an agents* entry to [tool.setuptools.packages.find].include in pyproject.toml (no new third-party dependency)
• 1.3 Add collaboration configuration: enabled/disabled flag (default disabled) and max-reflection-recovery-attempts ceiling, sourced from a single place agents/config.py reads from
• 1.4 Extend the project's smoke test (that imports every package) to import agents

2. Handoff protocol data models (capability: multi-agent-collaboration)

• 2.1 Implement agents/models.py: Observation, VerificationVerdict, ReflectionOutcome, and ReflectionAction dataclasses with to_dict()/from_dict(), mirroring the style of core/models.py
• 2.2 Write unit tests for each dataclass round-tripping through to_dict()/from_dict()

3. Observer role (capability: multi-agent-collaboration)

• 3.1 Implement agents/observer.py: Observer.observe(...) -> Observation, perceiving current device state via SemanticScene/WorldState when available
• 3.2 Make Observer.observe(...) work when SemanticScene and/or WorldState are None, falling back to the raw Scene/PlannedStep/StepResult
• 3.3 Write unit tests for Observer.observe(...) covering: both SemanticScene/WorldState present, both absent, and each present individually

4. Verifier role (capability: multi-agent-collaboration)

• 4.1 Implement agents/verifier.py: Verifier.verify(pre_observation, post_observation, planned_step, step_result) -> VerificationVerdict, comparing pre-step and post-step Observations against the PlannedStep's stated intent
• 4.2 Wire Verifier to reuse semantic/llm_client.py's existing LLM client abstraction (injectable/mockable) rather than a new client
• 4.3 Write unit tests for Verifier.verify(...) against a fake client covering: verified-achieved, verified-not-achieved, and client-failure degrade cases

5. Reflector role (capability: multi-agent-collaboration)

• 5.1 Implement agents/reflector.py: Reflector.reflect(observation, planned_step, step_result, verdict) -> ReflectionOutcome, invoked only on a Verifier-flagged not-achieved verdict
• 5.2 Ensure Reflector.reflect(...) never returns an outcome that simply re-issues the identical failed PlannedStep; it returns either a distinct ReflectionAction or a replan request
• 5.3 Write unit tests for Reflector.reflect(...) covering: recovery-action outcome, replan-request outcome, and client-failure degrade case

6. CollaborativeTaskRunner and handoff loop (capability: multi-agent-collaboration)

• 6.1 Implement agents/collab_runner.py: CollaborativeTaskRunner, composing the existing Planner, Executor, and runtime/task.py's TaskRunner strictly by import
• 6.2 Implement the handoff loop: Observer → Planner → Executor → Verifier → (Reflector only on a Verifier-flagged failure) → back to Observer
• 6.3 Implement the reflection-recovery ceiling: a configurable max-attempts counter, independent of and layered on top of Executor.max_retries, that stops further reflection-driven recovery once exhausted and surfaces the failure
• 6.4 Write unit tests for CollaborativeTaskRunner covering: a task that completes without any Verifier-flagged failure, a task recovered via one Reflector-proposed action, and a task that exhausts the reflection-recovery ceiling

7. Config wiring and opt-in behavior (capability: multi-agent-collaboration)

• 7.1 Confirm collaboration is disabled by default: constructing/running a task without explicitly enabling it behaves exactly as plain TaskRunner.run() today
• 7.2 Write a unit test asserting runtime/planner.py's Planner, runtime/executor.py's Executor, and runtime/task.py's TaskRunner are unmodified/unaffected by this change (no accidental coupling introduced from agents/)

8. End-to-end validation

• 8.1 Write an end-to-end test simulating a full collaborative task run against a mocked Driver/Scene/SemanticScene/WorldState and a mocked LLM client, asserting the loop completes normally whether verification succeeds or triggers reflection-driven recovery
• 8.2 Write an integration test (skippable without network/API credentials, following the existing apex-agent-mvp skippable-integration-test pattern) exercising Verifier/Reflector against the real LLM client
• 8.3 Confirm multi-agent collaboration stays disabled by default after applying this change (no existing task's behavior, latency, or cost changes unless a caller explicitly opts in)
• 8.4 Run the full test suite (pytest) and confirm no existing test in tests/ needed a behavior change, only additive new tests