feat: cross-machine and cross-team orchestration via phoenix-flow MCP

[JustAGhosT]

Summary

retort run --watch handles local file-based orchestration via RuntimeStateManager (#486). This issue tracks the next layer: cross-machine agent handoffs and human+agent cross-team coordination.

Problem

When agents run on different machines (e.g., a remote GitHub Actions runner spawning Claude Code, or a human engineer handing off a task to an AI team), file-watching over .claude/state/tasks/ doesn't work — there's no shared filesystem. We need a remote-accessible coordination layer.

Proposed Architecture

Local orchestration (same machine)
  retort run --watch
      └─ watches .claude/state/tasks/   ← RuntimeStateManager (fast, #486)

Remote / cross-team orchestration
  retort run --watch --remote
      └─ polls phoenix-flow MCP (task graph)
              │
              ├─ Human team creates/assigns tasks on Kanban board
              ├─ Agent team picks up tasks via MCP tool calls
              ├─ Task lifecycle: todo → inprogress → done
              └─ Syncs back to org-meta (YAML, version-controlled)

Key decisions

Why phoenix-flow (not mcp-org, not cognitive-mesh, not sluice)

Repo	Role	Verdict
phoenix-flow	Shared task graph — human + agent, MCP server, bidirectional YAML sync	Primary integration target
mcp-org	Org-level task mirror + project health (read-mostly)	Audit/visibility layer only
cognitive-mesh	Enterprise AI governance + reasoning platform	Too heavyweight; internal to CM agents
sluice	OpenAI-compatible LLM gateway	Model routing, not orchestration
docket	FinOps / AOAI cost tracking	Cost visibility, tangential
codeflow	Python AutoPR engine	Another CLI retort run dispatches to

phoenix-flow is already the designated shared task graph between humans and agents in this org — Portfolio → Project → Task hierarchy with MCP read/write and YAML version control.

Implementation sketch

retort run --remote flag

retort run claude --task T-123 --remote phoenix-flow

1. Fetches task T-123 from phoenix-flow MCP (get_task)
2. Spawns target CLI with task context injected
3. On completion, writes result back to phoenix-flow (update_task, add_agent_message)
4. Optionally logs to mcp-org audit trail (log_agent_message)

.retortconfig extension (builds on #488)

remote:
  provider: phoenix-flow
  endpoint: ${PHOENIX_FLOW_URL}
  secret: ${PHOENIX_FLOW_MCP_SECRET}
  fallback: local   # fall back to file-watching if remote unreachable

Callback protocol for remote CLIs

When a remote agent (e.g., codeflow AutoPR on a runner) completes work:

1. Agent writes task status update to phoenix-flow MCP (update_task status=done)
2. retort run --watch --remote polls phoenix-flow for status changes (or receives webhook if phoenix-flow supports it)
3. Next agent in chain is dispatched with the updated task context

Human↔agent handoff

• Human moves task card on Kanban → phoenix-flow writes status to DB → retort run --watch --remote picks it up → spawns designated agent CLI
• Agent completes → updates task → human sees it on board immediately

Acceptance criteria

• retort run --remote flag reads task from phoenix-flow MCP before dispatch
• Task status is written back to phoenix-flow on completion/failure
• .retortconfig remote: block supported (feat(config): extend .retortconfig schema with cli-routing, mcp-servers, and worktree settings #488 prerequisite)
• Works across machines (no shared filesystem assumption)
• Human Kanban assignments trigger agent dispatch (phoenix-flow → retort run)
• Fallback to local file-watching when --remote provider is unreachable

Dependencies

• feat(engine): add RuntimeStateManager class — orchestrator state and task lifecycle #486 — RuntimeStateManager (local task state, prerequisite)
• feat(cli): add retort run — multi-CLI team dispatch with .retortconfig routing #487 — retort run CLI dispatch (prerequisite)
• feat(config): extend .retortconfig schema with cli-routing, mcp-servers, and worktree settings #488 — .retortconfig schema extension (prerequisite)
• phoenixvc/phoenix-flow — MCP server must expose update_task + add_agent_message (already present)

Out of scope

• Phoenix-flow internal task graph changes (tracked separately in that repo)
• Cognitive-mesh agent orchestration (CM manages its own agent graph internally)
• Real-time streaming (polling is sufficient for v1; webhooks are a follow-up)

[blocksorg]

Mention Blocks like a regular teammate with your question or request:

@blocks can you add technical details to this issue?
@blocks make the following changes ...
@blocks create an issue from what was mentioned in the following comment ...
@blocks explain the following code ...
@blocks are there any security or performance concerns?

Run @blocks /help for more information.

Workspace settings | Disable this message