Update orchestrator skills to use MCP tools and v3 events

[williamthorsen]

Parent

Part of #74 (MCP server for run data + v3 event-sourced format) — PR 4 of 4.

Dependencies

• Blocked by Create packages/mcp server with run-data tools #85 (MCP server must exist and be registered)
• Independent of Migrate Factory imports to @codeassembly/run-data #86 (Factory migration)

Scope

Rewrite orchestrator skill instructions to use MCP tools instead of Read/Write on JSON files. Formalize subagent return contracts. Add get_run_state calls for cumulative state decisions.

Deliverables

1. Rewrite orchestrate/SKILL.md — replace all run-index.json Read/Write operations with MCP tool calls (init_run, emit_event, register_artifact, complete_run)
2. Rewrite orchestrate/modules/review-cycle.md — replace all state transition writes with emit_event calls for the review cycle's ~8 event types
3. Formalize return contracts (from Replace LLM-driven run-index.json assembly with MCP orchestration tools and structured return contracts #83) — make subagent return protocols strict (no fallback parsing), remove parseWarning concept, add "MUST include all fields" instruction to all 7 subagent prompts
4. Add get_run_state for flow control (from Replace LLM-driven run-index.json assembly with MCP orchestration tools and structured return contracts #83) — 5 specific decision points where the orchestrator reads authoritative state instead of relying on conversation memory
5. Update _data/artifact-conventions.md — document v3 format specification

Files to modify

• packages/agents/content/skills/orchestrate/SKILL.md
• packages/agents/content/skills/orchestrate/modules/review-cycle.md
• packages/agents/content/skills/_data/artifact-conventions.md
• packages/agents/content/subagents/orchestrated-architect.md
• packages/agents/content/subagents/orchestrated-planner.md
• packages/agents/content/subagents/orchestrated-coder.md
• packages/agents/content/subagents/orchestrated-reviewer.md
• packages/agents/content/subagents/aspect-code-reviewer.md
• packages/agents/content/subagents/aspect-silent-failure-reviewer.md
• packages/agents/content/subagents/aspect-test-reviewer.md

Acceptance criteria

• Orchestrate skill contains zero direct Read/Write/Edit operations on run-index.json
• All phase boundaries emit appropriate events via MCP tools
• All subagent return protocols are strict — no fallback to artifact file parsing
• All cumulative state decisions read from get_run_state, not conversation memory
• End-to-end: orchestrated run produces v3 run-index.json (header-only) + run-log.jsonl with events for all state transitions
• Factory displays v3 runs correctly via event folding

See #74 implementation plan, Step 4 for full details.

[williamthorsen]

Insight from orchestrated run (20260302-185950Z)

The external plan (Step 4 of #74) had 6 significant assumption mismatches with the actual MCP server implementation. The architecture phase caught all of them:

1. Event discriminant field: event not type
2. Non-existent event types: batch_completed and review_cycle_completed don't exist in the schema
3. Run ID format: init_run generates its own run ID ({projectSlug}.{yyyymmdd}-{hhmmss}Z), not caller-provided
4. Path convention: MCP server hardcodes {projectRoot}/.ai/runs/ vs the plan's assumed {base_dir}/projects/.../
5. Phase name enum: EventPhaseName uses shortened names (review, simplifier, holistic)
6. Artifact registration: register_artifact replaces all artifact array appends

Takeaway: Running the architecture phase on external plans is essential — plans authored before implementation often embed assumptions about APIs that diverge from what was actually built.