Implement deterministic state-based routing for multi-tier agent orchestration

[sven1103-agent]

Problem Statement

The current multi-tier agent setup (orchestrator → planner → implementer → code-reviewer) relies on LLM-based routing decisions, causing non-deterministic handoffs. Specifically:

• Scenario A: needs_changes from code-reviewer — routing back to implementer vs planner is inconsistent
• Scenario D: Initial task classification (simple vs complex) — heuristic-based and unreliable

Converged Solution

Externalize routing state to JSON files. Orchestrator owns state transitions; subagents only produce results. Always use multi-tier workflow (no "simple" fast-path).

State Machine

IDLE → PLANNING → READY_FOR_IMPLEMENTATION → IMPLEMENTING → READY_FOR_REVIEW → REVIEWING → [APPROVED | NEEDS_FIXES]
                                    ↑______________________________________________________________|
BLOCKED (terminal — requires human intervention)

Files to Create

1. .opencode/schemas/state.schema.json — Session state format with history tracking
2. .opencode/schemas/coding-workflow-transitions.json — Event-based transition rules
3. Update orchestrator agent prompt — Add state management instructions

Key Design Decisions

• ✅ Event-based transitions (state + result → next state)
• ✅ Explicit routing in transition rules (route_to field)
• ✅ Always multi-tier (no initial classification)
• ✅ Blocked state = human intervention required
• ⏸️ Deferred: "same vs new implementer" for fix loops
• ⏸️ Deferred: Recovery paths from BLOCKED

Transition Rules Summary

From State	Event/Result	To State	Route To
IDLE	task_received	PLANNING	planner
PLANNING	impl_summary.done	READY_FOR_IMPLEMENTATION	implementer
PLANNING	blocked	BLOCKED	human
IMPLEMENTING	impl_summary.done	READY_FOR_REVIEW	code-reviewer
IMPLEMENTING	blocked	BLOCKED	human
REVIEWING	review_result.approve	APPROVED	complete
REVIEWING	review_result.needs_changes	NEEDS_FIXES	implementer
REVIEWING	blocked	BLOCKED	human
NEEDS_FIXES	any	IMPLEMENTING	implementer

Acceptance Criteria

• state.schema.json created and validated
• coding-workflow-transitions.json created with all transitions
• Orchestrator prompt updated to read/write state
• Test: Run sample workflow, verify state transitions correctly
• Documentation: Update AGENTS.md with new orchestration contract

Reference

• See converged design discussion for full schema definitions and prompt updates