Claude Code Workflow Orchestration System
A hook-based framework for Claude Code that enforces task delegation to specialized agents, enabling structured workflows and expert-level task handling through intelligent orchestration.
See the delegation system in action:
🆕 What's New
🤝 Agent Teams Integration — Native dual-mode execution: workflows automatically select between isolated subagents and collaborative Agent Teams (via TeamCreate + Agent(team_name=...) + SendMessage) based on task complexity scoring. Teammates communicate in real-time, share task lists, and self-coordinate. Enable with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
⚡ Statusline Performance — Cold start optimized from ~28s to <0.1s through merged API calls and non-blocking background cache refresh.
Overview
This system uses Claude Code's hook mechanism to create a delegation-enforced workflow architecture that routes tasks to specialized agents for expert-level execution.
Key Features
- Enforced Delegation - PreToolUse hooks block direct tool usage, forcing delegation to specialized agents
- 8 Specialized Agents - Each agent has domain expertise (code cleanup, testing, architecture, DevOps, etc.)
- Native Plan Mode - Built-in plan mode (EnterPlanMode/ExitPlanMode) handles planning, agent selection, and execution orchestration
- Intelligent Multi-Step Workflows - Sequential execution for dependent phases, parallel for independent phases
- Dual-Mode Execution - Isolated subagent sessions (default) or collaborative Agent Teams with real-time inter-agent communication (experimental)
- Agent Teams Integration - Native
TeamCreate+Agent(team_name=...)+SendMessagefor peer-to-peer collaboration, shared task lists, and coordinated multi-agent workflows - Tasks API Integration - Native task tracking via TaskCreate, TaskUpdate, TaskList, TaskGet with structured metadata
- Structured Task Metadata - Wave assignments, phase IDs, agent assignments, and dependencies encoded in task metadata
- Async Hook Support - Non-blocking background tasks for reminders and cleanup operations
- Stateful Session Management - Fresh delegation enforcement per user message with session registry
- Smart Dependency Analysis - Automatically analyzes phase dependencies to determine optimal execution mode
- Parallel Execution Support - Executes independent phases concurrently with automatic wave synchronization
- Visualization & Debugging - Comprehensive logging and debug tools for understanding delegation decisions
Execution Model
The system uses a two-stage execution pipeline:
Stage 0: Planning & Analysis (native plan mode)
- Analyzes task complexity (single-step vs multi-step)
- Decomposes complex tasks into atomic phases
- Performs dependency analysis to determine execution mode
- Assigns specialized agents via keyword matching
- Creates wave assignments for parallel/sequential execution
- Creates tasks via TaskCreate with structured metadata
Stage 1: Execution
- Single-Step Tasks: Hook blocks tools → Delegates to specialized agent → Agent executes → Results returned
- Multi-Step Workflows:
- Subagent mode (default): Isolated parallel Agent instances per wave. Agents return
DONE|{path}. Context-efficient, optimal for most workflows. - Team mode (experimental): Native Agent Teams via
TeamCreate+Agent(team_name=...). Teammates share context, communicate viaSendMessage, and self-coordinate through shared task lists. RequiresCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
- Subagent mode (default): Isolated parallel Agent instances per wave. Agents return
- Results consolidated and summary provided
Execution Mode Selection: Plan mode calculates a team_mode_score to choose between subagent mode (isolated, context-efficient) and team mode (collaborative, real-time communication). For subagent mode, it further selects sequential (context preservation, dependencies) or parallel (time savings, independence) based on phase dependency analysis.
Quick Start
Prerequisites
macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
curl -fsSL https://bun.com/install | bash
- jq: JSON processor for parallel workflow state tracking.
# macOS
brew install jq
# Linux
sudo apt install jq
Windows
Python 3.12+ is required. All hooks use cross-platform Python scripts.
-
Python: https://www.python.org/downloads/
- During installation, ensure "Add Python to PATH" is checked
- Verify installation:
python --version
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
powershell -c "irm bun.sh/install.ps1 | iex"