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
⚡ Soft Enforcement & Lean Startup — Replaces hard-blocking enforcement with adaptive per-turn nudges (silent → hint → warning → strong reminder). SessionStart injection trimmed ~6.6K tokens: stub orchestrator (~1.1KB) injected on startup, full orchestrator loaded only on first delegation. Output style loaded natively from plugin.json (no injection). Net result: lean sessions with automatic escalation when delegation is needed.
🤝 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 tool availability. Teammates communicate in real-time, share task lists, and self-coordinate. Enable with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
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
- Soft Enforcement via Adaptive Nudges - No hard blocks. PreToolUse hook emits per-turn escalating stderr reminders (silent → hint → warning → strong) when main agent bypasses
/workflow-orchestrator:delegate. Subagents immune. Nudge counter resets each turn and zeros when delegation runs.
- Lean SessionStart Injection - Consolidated 3 hooks into 1 Python script. Stub orchestrator (~1.1KB) on startup + optional token-efficient CLI guide, full orchestrator (~7.5KB) loaded on-demand. Output style loaded natively from plugin.json (no injection). Saves ~6.6K tokens off session start.
- 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=...) + SendMessage for 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 per-turn nudge counter
- 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 via SendMessage, and self-coordinate through shared task lists. Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
- Results consolidated and summary provided
Execution Mode Selection: If TeamCreate is in available tools → execution_mode: "team". Otherwise → "subagent". Tool availability is the only signal (set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 to enable). For subagent mode, plan mode further selects sequential (context preservation, dependencies) or parallel (time savings, independence) based on phase dependency analysis.
Quick Start
Prerequisites
