docs: update orchestrator and structure docs for coordinator agent [doc-updater]

[james-in-a-box]

Update documentation to reflect changes from Add coordinator agent for dynamic pipeline orchestration (#1028) (#1043):

• Added coordinator role section to Multi-Agent Roles in docs/architecture/orchestrator.md, covering coordinator execution model, guardrails, and a link to the coordinator guide
• Added 5 coordinator REST API endpoints and 4 MCP server endpoints to the API Endpoints reference in docs/architecture/orchestrator.md
• Added coordinator_executor.py, mcp_server.py, mcp_tools.py, and routes/coordinator.py to the Orchestrator Structure listing in docs/development/STRUCTURE.md

The coordinator guide (docs/guides/coordinator.md) and docs/index.md reference were already added as part of the original commit.

Issue: none

Test plan:

• Review that the new coordinator role section is accurate against orchestrator/coordinator_executor.py and orchestrator/routes/coordinator.py
• Verify the MCP server endpoint listing matches orchestrator/mcp_server.py
• Verify the new STRUCTURE.md entries match the actual files

Authored-by: egg

[egg-reviewer]

No agent-mode design concerns. This is a documentation-only update that accurately reflects the coordinator agent feature. The documented design aligns with agent-mode principles: the coordinator drives the pipeline dynamically via CLI commands, agents run in sandbox containers, and guardrails are enforced at the orchestrator infrastructure level rather than via prompt-level constraints.

— Authored by egg

[egg-reviewer]

Documentation is accurate. All claims verified against the implementation:

• All 5 coordinator REST API endpoints match orchestrator/routes/coordinator.py exactly
• All 4 MCP server endpoints match orchestrator/mcp_server.py exactly
• MCP port 9850, env var EGG_MCP_SERVER_ENABLED, and coordinator guide link all verified
• File existence confirmed for all 4 new STRUCTURE.md entries
• Coordinator role description (coordinator_enabled gating, execution model, guardrails) matches coordinator_executor.py and models.py

Two minor suggestions:

1. STRUCTURE.md file ordering (non-blocking)

The new .py files (coordinator_executor.py, mcp_server.py, mcp_tools.py) are placed after the health_checks/ subdirectory (line 117-119). The existing convention lists all .py files alphabetically first, then subdirectories (health_checks/, routes/), then config files (Dockerfile, etc.). These should be in their alphabetical positions among the other .py files:

• coordinator_executor.py → after container_spawner.py, near the other con* files
• mcp_server.py and mcp_tools.py → after message_store.py, near metrics.py/models.py

2. STRUCTURE.md coordinator.py description (non-blocking)

The entry reads:

├── coordinator.py      # Coordinator REST API endpoints (spawn, state, phase, escalate)

The file also has a cancel_agent / DELETE endpoint. Should be:

├── coordinator.py      # Coordinator REST API endpoints (spawn, cancel, state, phase, escalate)

— Authored by egg

[james-in-a-box]

Agreed. Both suggestions addressed in e7d64c8:

1. STRUCTURE.md file ordering: Moved coordinator_executor.py after consensus.py, and mcp_server.py/mcp_tools.py before message_store.py — all .py files now appear in alphabetical order before subdirectories.
2. coordinator.py description: Added "cancel" to the endpoint list.

— Authored by egg

[egg-reviewer]

No agent-mode design concerns. The delta since last review is a documentation ordering fix — no design changes.

— Authored by egg

[egg-reviewer]

Re-review of changes since 6b72c91. The delta is a single commit (e7d64c8) modifying docs/development/STRUCTURE.md only.

Previous feedback — verified addressed:

1. STRUCTURE.md file ordering: coordinator_executor.py moved into the .py files section after consensus.py; mcp_server.py and mcp_tools.py placed between handoffs.py and message_store.py. All three entries are now in the .py section before subdirectories, matching the existing convention. ✓
2. coordinator.py description: "cancel" added to the endpoint list → (spawn, cancel, state, phase, escalate). ✓

Minor observation (non-blocking): The pre-existing con* files are not in strict alphabetical order (container_spawner before container_monitor before concurrent_executor, whereas alphabetically it should be concurrent < consensus < container_m < container_s < coordinator). The new coordinator_executor.py entry is placed after consensus.py rather than after container_spawner.py. Not worth a separate fix — just noting it if someone ever does a full sort pass.

— Authored by egg

[james-in-a-box]

egg is addressing review feedback...

[james-in-a-box]

egg feedback addressed. View run logs

5 previous review(s) hidden.