Orchestrator Instructions¶

def route_to_next_phase(state: WorkflowState) -> str:
    """Determine next phase based on current state"""

    # Check if workflow complete
    if state.phase6Complete and all_quality_gates_passed(state):
        return "complete"

    # Phase transitions (only if quality gate passed)
    if not state.phase1Complete:
        return "research_agent"

    if not state.phase2Complete:
        if quality_gate_passed(state, "phase1"):
            return "strategy_agent"
        else:
            return "research_agent"  # Retry

    if not state.phase3Complete:
        if quality_gate_passed(state, "phase2"):
            return "solution_agent"
        else:
            return "strategy_agent"  # Retry

    if not state.phase4Complete:
        if quality_gate_passed(state, "phase3"):
            return "ui_agent"
        else:
            return "solution_agent"  # Retry

    if not state.phase5Complete:
        if quality_gate_passed(state, "phase4"):
            return "critique_agent"
        else:
            return "ui_agent"  # Retry

    if not state.phase6Complete:
        if quality_gate_passed(state, "phase5"):
            return "polish_agent"
        else:
            return "critique_agent"  # Retry

    return "complete"

def validate_quality_gate(state: WorkflowState, phase: str) -> QualityGateResult:
    """Validate phase output meets requirements"""

    failures = []

    if phase == "phase1":
        # Research Agent outputs
        if len(state.artifacts.personas) < 2:
            failures.append("FAIL: Need at least 2 personas")
        if len(state.artifacts.jtbdStatements) < 3:
            failures.append("FAIL: Need at least 3 JTBD statements")
        if len(state.artifacts.contextScenarios) < 2:
            failures.append("FAIL: Need at least 2 context scenarios")
        for jtbd in state.artifacts.jtbdStatements:
            if not jtbd.matches_format("When..., I want to..., So I can..."):
                failures.append(f"FAIL: JTBD not in correct format: {jtbd}")

    elif phase == "phase2":
        # Strategy Agent outputs
        if not state.artifacts.problemStatement:
            failures.append("FAIL: Missing problem statement")
        if len(state.artifacts.successMetrics) < 3:
            failures.append("FAIL: Need at least 3 success metrics")
        if len(state.artifacts.hmwQuestions) < 5:
            failures.append("FAIL: Need at least 5 HMW questions")
        for metric in state.artifacts.successMetrics:
            if not metric.is_measurable():
                failures.append(f"FAIL: Metric not measurable: {metric}")

    elif phase == "phase3":
        # Solution Agent outputs
        if len(state.artifacts.solutionHypotheses) < 3:
            failures.append("FAIL: Need at least 3 solution options explored")
        if len(state.artifacts.userFlows) < 1:
            failures.append("FAIL: Need at least 1 user flow")
        if not state.artifacts.informationArchitecture:
            failures.append("FAIL: Missing information architecture")
        if not any(s.selected for s in state.artifacts.solutionHypotheses):
            failures.append("FAIL: No solution selected with rationale")

    elif phase == "phase4":
        # UI Agent outputs
        if len(state.artifacts.componentSpecs) < 1:
            failures.append("FAIL: Missing component specifications")
        if len(state.artifacts.layoutSpecs) < 1:
            failures.append("FAIL: Missing layout specifications")
        for spec in state.artifacts.componentSpecs:
            if spec.uses_hardcoded_values():
                failures.append(f"FAIL: Hardcoded values found in {spec.name}")
        for spec in state.artifacts.layoutSpecs:
            if not spec.has_responsive_behavior():
                failures.append(f"FAIL: Missing responsive spec for {spec.name}")

    elif phase == "phase5":
        # Critique Agent outputs
        if not state.artifacts.accessibilityAudit:
            failures.append("FAIL: Missing accessibility audit")
        if not state.artifacts.heuristicEvaluation:
            failures.append("FAIL: Missing heuristic evaluation")
        critical_issues = [i for i in state.artifacts.issueList if i.severity == "critical"]
        if len(critical_issues) > 0:
            failures.append(f"FAIL: {len(critical_issues)} critical issues unresolved")

    elif phase == "phase6":
        # Polish Agent outputs
        major_issues = [i for i in state.artifacts.issueList if i.severity in ["critical", "major"] and not i.resolved]
        if len(major_issues) > 0:
            failures.append(f"FAIL: {len(major_issues)} major issues unresolved")
        if not state.artifacts.implementationGuide:
            failures.append("FAIL: Missing implementation guide")

    return QualityGateResult(
        passed=len(failures) == 0,
        failures=failures,
        phase=phase,
        timestamp=datetime.now()
    )

MAX_RETRIES_PER_PHASE = 3

def handle_quality_gate_failure(state: WorkflowState, phase: str, failures: list[str]) -> Command:
    """Handle failed quality gate"""

    retry_count = count_retries(state, phase)

    if retry_count >= MAX_RETRIES_PER_PHASE:
        # Escalate to human
        return Command(
            action="escalate",
            reason=f"Phase {phase} failed {MAX_RETRIES_PER_PHASE} times",
            failures=failures,
            state_snapshot=state
        )

    # Provide specific feedback for retry
    feedback = generate_retry_feedback(failures)

    return Command(
        action="retry",
        phase=phase,
        feedback=feedback,
        retry_count=retry_count + 1
    )

def generate_retry_feedback(failures: list[str]) -> str:
    """Generate actionable feedback from failures"""
    return f"""
    QUALITY GATE FAILED. Please address:

    {chr(10).join(f'• {f}' for f in failures)}

    Revise your output to address these issues and resubmit.
    """

def save_checkpoint(state: WorkflowState, phase: str) -> Checkpoint:
    """Save state before phase transition"""
    return Checkpoint(
        id=generate_checkpoint_id(),
        phase=phase,
        timestamp=datetime.now(),
        state=deep_copy(state),
        artifacts=deep_copy(state.artifacts)
    )

def restore_checkpoint(checkpoint_id: str) -> WorkflowState:
    """Restore state from checkpoint"""
    checkpoint = load_checkpoint(checkpoint_id)
    return checkpoint.state

async def run_workflow(project_brief: str) -> WorkflowState:
    """Execute complete UI design workflow"""

    # Initialize state
    state = WorkflowState(
        projectBrief=project_brief,
        currentPhase=1
    )

    # Create orchestrator
    orchestrator = Orchestrator(model=llm)

    # Run until complete
    while state.currentPhase != "complete":
        # Save checkpoint
        checkpoint = save_checkpoint(state, f"phase{state.currentPhase}_start")

        # Route to next agent
        next_agent = route_to_next_phase(state)

        if next_agent == "complete":
            break

        # Invoke agent
        try:
            result = await invoke_agent(next_agent, state)
            state = update_state(state, result)

            # Validate quality gate
            gate_result = validate_quality_gate(state, f"phase{state.currentPhase}")

            if gate_result.passed:
                state.currentPhase += 1
                save_checkpoint(state, f"phase{state.currentPhase - 1}_complete")
            else:
                command = handle_quality_gate_failure(state, f"phase{state.currentPhase}", gate_result.failures)
                if command.action == "escalate":
                    return await escalate_to_human(state, command)
                # Otherwise retry (loop continues)

        except Exception as e:
            # Restore from checkpoint and retry
            state = restore_checkpoint(checkpoint.id)
            logger.error(f"Phase {state.currentPhase} failed: {e}")

    return state