workflow-orchestrator

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