workflow-router

mehdic's avatarfrom mehdic

Determine next agent based on state machine rules. Use AFTER receiving any BAZINGA agent response to decide what to do next.

⭐2stars🔀0forks📁View on GitHub🕐Updated Jan 3, 2026⬇️1downloads

When & Why to Use This Skill

The Workflow Router skill is a sophisticated orchestration engine designed for multi-agent systems. It utilizes state machine logic to dynamically determine the next step in a complex AI workflow, managing transitions between specialized agents based on status codes, escalation rules, and security protocols. By automating the decision-making process for agent handoffs, it ensures robust, scalable, and efficient autonomous task execution.

Use Cases

  • Automated Agent Handoffs: Seamlessly routing a task from a 'Developer' agent to a 'QA Expert' once code is ready, or to a 'Tech Lead' after passing tests.
  • Intelligent Escalation: Automatically redirecting tasks to senior-level agents (SSE) when a specific number of failures or retries is detected in the standard workflow.
  • Conditional Testing Workflows: Dynamically skipping or enforcing QA phases based on the environment's testing mode (full, minimal, or disabled).
  • Security-Critical Routing: Enforcing security overrides to ensure that high-risk tasks are handled exclusively by specialized security agents.
  • Parallel Task Management: Coordinating the simultaneous spawning of multiple developer groups for large-scale project requirements.
nameworkflow-router
descriptionDetermine next agent based on state machine rules. Use AFTER receiving any BAZINGA agent response to decide what to do next.
version1.0.0
authorBAZINGA Team
tags[orchestration, routing, workflow]
allowed-tools[Bash]

Workflow Router Skill

You are the workflow-router skill. Your role is to determine the next action in the BAZINGA workflow by calling workflow_router.py, which reads from the state machine configuration.

Overview

This skill determines what to do after receiving an agent response by:

  • Reading transitions from database (seeded from transitions.json)
  • Applying testing mode rules (skip QA if disabled/minimal)
  • Applying escalation rules (escalate to SSE after N failures)
  • Applying security rules (force SSE for security tasks)
  • Returning JSON with next action

Prerequisites

  • Database must be initialized (bazinga/bazinga.db exists)
  • Config must be seeded (run config-seeder skill at session start)

When to Invoke This Skill

  • AFTER receiving any agent response
  • When orchestrator needs to decide what to do next based on agent's status code
  • Examples:
    • Developer returned "READY_FOR_QA" → Route to QA Expert
    • QA returned "PASS" → Route to Tech Lead
    • Tech Lead returned "APPROVED" → Check phase, maybe route to PM

Your Task

When invoked, you must:

Step 1: Extract Parameters

Parse from the agent's response and current state:

  • current_agent: Agent that just responded (developer, qa_expert, tech_lead, etc.)
  • status: Status code from response (READY_FOR_QA, PASS, APPROVED, etc.)
  • session_id: Current session ID
  • group_id: Current group ID
  • testing_mode: full, minimal, or disabled

Step 2: Call the Python Script

python3 .claude/skills/workflow-router/scripts/workflow_router.py \
  --current-agent "{current_agent}" \
  --status "{status}" \
  --session-id "{session_id}" \
  --group-id "{group_id}" \
  --testing-mode "{testing_mode}"

Step 3: Parse and Return Result

The script outputs JSON:

{
  "success": true,
  "current_agent": "developer",
  "response_status": "READY_FOR_QA",
  "next_agent": "qa_expert",
  "action": "spawn",
  "model": "sonnet",
  "group_id": "AUTH",
  "session_id": "bazinga_xxx",
  "include_context": ["dev_output", "test_results"]
}

Return this JSON to the orchestrator.

Actions Explained

Action What Orchestrator Should Do
spawn Use prompt-builder, then spawn single agent
respawn Re-spawn same agent type with feedback
spawn_batch Spawn multiple developers for groups_to_spawn
validate_then_end Invoke bazinga-validator skill, then route based on verdict
pause_for_user Surface clarification question to user
end_session Mark session complete, no more spawns

Validator Workflow

When PM sends BAZINGA, the orchestrator invokes bazinga-validator. After validator returns:

Orchestrator calls workflow-router skill:

workflow-router, determine next action:
Current agent: validator
Status: ACCEPT  # or REJECT
Session ID: {session_id}

Then invoke: Skill(command: "workflow-router")

Note: Validator is session-scoped - omit group_id (not needed for routing).

Transitions defined in workflow/transitions.json → validator section:

  • ACCEPT → end_session action → Complete shutdown protocol
  • REJECT → spawn action with next_agent: project_manager → PM fixes issues

🔴 CRITICAL: After validator REJECT, orchestrator MUST spawn PM with the rejection details. Do NOT stop!

Special Flags in Result

Flag Meaning
groups_to_spawn Array of group IDs to spawn in parallel
escalation_applied True if escalated to SSE due to failures
escalation_reason Why escalation happened
skip_reason Why QA was skipped (testing mode)
phase_check "continue" or "complete" after merge
security_override True if security task forced SSE
bypass_qa True if QA should be skipped (RE tasks)

Output Format

JSON object with routing decision. Parse and execute the action.

Error Handling

Error Meaning
success: false Unknown transition - check fallback_action
Unknown status Route to Tech Lead for manual handling
Database not found Cannot route - needs config seeding

If routing fails, use the fallback_action in the error response.