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:
FAQ
workflow-orchestrator is a Claude Code plugin with hand-picked skills for development work, indexed on Flowy. Install it with the command on its page. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
> /plugin marketplace add barkain/claude-code-workflow-orchestration
Repo: barkain/claude-code-workflow-orchestration
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:
โก 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.
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.
/workflow-orchestrator:delegate. Subagents immune. Nudge counter resets each turn and zeros when delegation runs.TeamCreate + Agent(team_name=...) + SendMessage for peer-to-peer collaboration, shared task lists, and coordinated multi-agent workflowsThe system uses a two-stage execution pipeline:
Stage 0: Planning & Analysis (native plan mode)
Stage 1: Execution
DONE|{path}. Context-efficient, optimal for most workflows.TeamCreate + Agent(team_name=...). Teammates share context, communicate via SendMessage, and self-coordinate through shared task lists. Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.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.
curl -LsSf https://astral.sh/uv/install.sh | sh
curl -fsSL https://bun.com/install | bash
# macOS
brew install jq
# Linux
sudo apt install jq
Python 3.12+ is required. All hooks use cross-platform Python scripts.
Python: https://www.python.org/downloads/
python --versionpowershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
powershell -c "irm bun.sh/install.ps1 | iex"
# Using Chocolatey
choco install jq
# Or download from https://jqlang.github.io/jq/download/
Note: The hook system uses Python scripts for cross-platform compatibility. Ensure python is available in your PATH.
This project provides a comprehensive delegation system for Claude Code with multi-agent orchestration. Choose your preferred installation method:
The easiest way to install is via Claude Code's plugin system:
# Add the marketplace
claude plugin marketplace add barkain/claude-code-workflow-orchestration
# Install the plugin
claude plugin install workflow-orchestrator@barkain-plugins # user-level
# or
claude plugin install workflow-orchestrator@barkain-plugins --scope project # project-level
Benefits:
Optional Settings:
/workflow-orchestrator:add-statusline after installation to enable workflow status displaytechnical-adaptive output style optimized for workflow orchestration. To select it, configure outputStyle in your Claude Code settings (project or user level)Note: Changing the output style requires restarting your Claude Code session for the change to take effect.
For development or custom configurations:
# Clone the repository
git clone https://github.com/barkain/claude-code-workflow-orchestration.git
For project-isolated configurations or version-controlled delegation setups:
cd path/to/project
path/to/repo/install.sh # follow the installation instructions
Windows users: The install.sh script requires bash (Git Bash or WSL). For Windows, we recommend using the Plugin Installation method above, which works natively on all platforms.
Once installed, the delegation hook is automatically active. Simply use Claude Code normally (Opus 4.5 is preferred):
# Multi-step workflow - enable orchestration for context passing
claude
and then prompt claude with:
> create a simple calculator app with basic math operations.
add a nice UI and use NextJS/Tailwind to build this out.
the backend should be implemented in python as a modern uv project.
add verification steps after each phase.
What happens:
The main agent enters native plan mode (EnterPlanMode) to decompose the request, assign specialized agents via keyword matching, schedule waves, and select an execution mode. Mode selection is one rule: if TeamCreate is available (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1), it picks team mode; otherwise parallel subagents.

After ExitPlanMode approval, a dependency graph is rendered showing the parallel waves and the agents assigned to each phase:

In team mode, the lead calls TeamCreate once and then spawns each phase as a persistent teammate via Agent(team_name=...). Teammates run concurrently in the swarm session and self-coordinate via SendMessage. Open the swarm view with tmux -L claude-swarm-<id> a to watch them work in real time:

As each wave completes, downstream phases unblock automatically. A final integration/verification phase confirms end-to-end correctness, then the team shuts down cleanly:

The delegation system uses adaptive nudges instead of hard blocks:
# 1st direct tool call (imperative STOP)
Read test.py
# stderr: "STOP. This tool call bypasses delegation. Abandon this step and run: /workflow-orchestrator:delegate <your task>"
# 2nd direct tool call (imperative STOP, 2nd-call phrasing)
Read other.py
# stderr: "STOP. 2nd direct tool call this turn. The main agent does not execute work tools. Run: /workflow-orchestrator:delegate <your task>"
# 3rd direct tool call (strong reminder โ explains what's being lost)
Edit file.py
# stderr: "STOP. 3 direct tool calls bypassing delegation. You are losing planning, parallelization, and context isolation. Abandon the current plan and run: /workflow-orchestrator:delegate <your task>"
# 4th+ direct tool calls keep the same strong reminder with the updated count
Bash command.sh
# stderr: "STOP. 4 direct tool calls bypassing delegation. ..."
# Delegation resets the counter (state clean)
/workflow-orchestrator:delegate "Create feature"
# Counter zeros. Next turn starts fresh.
Counter resets each user turn and zeros when /workflow-orchestrator:delegate runs. Subagents are immune. Use /workflow-orchestrator:bypass for emergency access without restarting.
The system supports several environment variables for configuration and debugging:
Tasks API Configuration:
CLAUDE_CODE_ENABLE_TASKS=true # Enable Tasks API (default: true)
CLAUDE_CODE_TASK_LIST_ID=list_id # Share task list across sessions
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 # Disable async background tasks
Agent Teams (Experimental):
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 # Enable Agent Teams dual-mode execution
Token Efficiency:
CLAUDE_TOKEN_EFFICIENCY=1 # Enable token-efficient CLI output (default: 1)
Debug & Control:
DEBUG_DELEGATION_HOOK=1 # Enable hook debug logging
DELEGATION_HOOK_DISABLE=1 # Emergency bypass (disable enforcement)
CLAUDE_MAX_CONCURRENT=8 # Max parallel agents per batch (default 8)
CHECK_RUFF=0 # Skip Ruff validation in PostToolUse
CHECK_PYRIGHT=0 # Skip Pyright validation in PostToolUse
CLAUDE_SKIP_PYTHON_VALIDATION=1 # Skip all Python validation
See Environment Variables for detailed configuration.
The plugin-hooks.json configures the delegation enforcement hooks using cross-platform Python scripts:
Note: All hooks use uv run --no-project --script for cross-platform compatibility (Windows, macOS, Linux). The --no-project flag allows execution without requiring a pyproject.toml, and --script directly runs Python scripts using uv's managed interpreter.
Hook Events (6 lifecycle points, 14 hooks):
| Event | Scripts | Purpose |
|---|---|---|
| PreToolUse | validate_task_graph_compliance.py (advisory), require_delegation.py (soft nudge), token_rewrite_hook.py (Bash only) | Validate task graph (skip in team mode); adaptive per-turn nudges on work-tool calls; rewrite Bash for token efficiency |
| PostToolUse | python_posttooluse_hook.py (blocking), remind_skill_continuation.py, validate_task_graph_depth.py (advisory), remind_todo_after_task.py (async) | Python validation (Ruff/Pyright โ only hard-blocking hook); workflow continuation + zero nudge counter on /workflow-orchestrator:delegate; depth-3 advisory; task reminders |
| UserPromptSubmit | clear-delegation-sessions.py | Reset per-turn nudge counter, clear delegation/team state |
| SessionStart | inject_all.py | Consolidated injection: orchestrator stub (~1.1KB) + optional token-efficient CLI guide (gated by env var). Output style loaded natively from plugin.json. |
| SubagentStop | remind_todo_update.py (async), trigger_verification.py | Remind to update tasks, suggest verification |
| Stop | python_stop_hook.py | Turn duration tracking, workflow continuation |
The inject_all.py hook consolidates 3 SessionStart hooks into 1 Python script:
On startup/resume (all sessions):
orchestrator_stub.md, ~1.1KB): points the main agent at /workflow-orchestrator:delegate for multi-step work. Minimal overhead (~200 tokens).token_efficient_cli.md, ~1.9KB, gated by CLAUDE_TOKEN_EFFICIENCY=1 env var). Teaches compact flags and command patterns.outputStyles field (no injection required). Saves ~1.5K tokens.On first delegation (lazy load):
commands/delegate.md and is loaded only when /workflow-orchestrator:delegate runs.Net savings: ~6.6K tokens off session startup. Sessions pay the orchestration tax only when delegation is actually used.
What this enables:
hooks/PreToolUse/require_delegation.py)Soft enforcement: nudges (never blocks) when main agent uses work-doing tools directly. Tracks 8 stable primitives: Bash, Edit, Write, Read, Glob, Grep, MultiEdit, NotebookEdit. New Claude Code tools never trigger nudges.
Allowed tools (no nudge):
AskUserQuestion, Skill, SlashCommand - Explicit queries and commandsTaskCreate, TaskUpdate, TaskList, TaskGet - Task tracking (structured metadata)Agent, SubagentTask, AgentTask - Delegation mechanismTeamCreate, SendMessage - Agent Teams (when CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)ToolSearch - Tool discoveryWork tools (tracked for nudges, not blocked):
Bash, Edit, Write, Read, Glob, Grep, MultiEdit, NotebookEditNudge escalation by violation count (per turn):
delegate? (~2 tokens)nudge: use /workflow-orchestrator:delegate for multi-step work (~12 tokens)WARNING: N direct tool calls bypassing delegation... (~25 tokens)Note: TaskOutput is prohibited (context exhaustion). Agents write to $CLAUDE_SCRATCHPAD_DIR and return DONE|{path} only. Counter resets each turn; subagents (via CLAUDE_PARENT_SESSION_ID) are exempt.
agents/)8 specialized agents for different task types:
Note: The delegation-orchestrator agent has been deprecated. Its orchestration and routing functionality is now provided by native plan mode (EnterPlanMode/ExitPlanMode), which handles both planning and execution orchestration directly within the main agent.
commands/delegate.md)The /workflow-orchestrator:delegate command provides intelligent task delegation with integrated planning:
/workflow-orchestrator:delegate <task description>
How it works:
commands/delegate.md)The /workflow-orchestrator:delegate slash command loads the full orchestrator logic on demand: multi-step detection, plan-mode instructions, agent catalog, wave scheduling, and team-mode execution. Works in conjunction with native plan mode (EnterPlanMode/ExitPlanMode).
Activate via: Simply start a Claude code session
claude
Multi-step detection patterns:
Unified Planning & Execution: Native plan mode (EnterPlanMode/ExitPlanMode) handles both planning and execution orchestration:
Execution mode decision logic:
Complete workflow process:
The framework supports a second execution mode that uses Claude Code's native Agent Teams feature for real-time inter-agent collaboration. When enabled, agents can communicate with each other via SendMessage, share task lists, and self-coordinate -- rather than running as isolated subagents.
Set the environment variable before starting Claude Code:
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
No other configuration is required. Plan mode automatically evaluates whether a given task benefits from team-based execution.
During planning, plan mode checks tool availability:
ONE RULE: If TeamCreate is in your available tools โ execution_mode: "team". Otherwise โ "subagent".
This is detected by attempting to use the tool. Setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 makes TeamCreate available, enabling team mode. Without it, only subagent mode is available.
| Aspect | Subagent Mode (default) | Team Mode (experimental) |
|---|---|---|
| Execution | Isolated Agent(...) per phase | Agent(team_name=...) per phase |
| Communication | None (agents are isolated) | SendMessage for peer-to-peer messaging |
| Task list | Framework-managed via TaskCreate/Update | Shared task list, teammates self-claim |
| Coordination | Main agent orchestrates waves | Teammates self-coordinate |
| Context sharing | Via output files (DONE|{path}) | Shared context + messaging |
| Best for | Most workflows, context-efficient | Complex collaborative tasks, review cycles |
The key difference is one parameter: Agent(team_name="x") makes a teammate; Agent() makes an isolated subagent.
Simple team -- a single AGENT TEAM phase with multiple teammates exploring in parallel. Used for multi-perspective exploration tasks.
> explore the authentication system from different angles
This creates one team phase where each teammate explores a different perspective (e.g., security, performance, architecture), then results are synthesized.
Complex team -- multiple individual phases across waves, all executed as teammates with Agent(team_name=...). Used for collaborative implementation tasks.
> implement the payment service. tasks should be collaborative
All phases run as teammates sharing context and messaging, even though each has a distinct assignment.
> explore the codebase from different angles
> design the API with a team of specialists
> implement the feature collaboratively
> use a team to review and refactor the auth module
> brainstorm together on the CLI design
Before creating a team, the framework presents the team plan and asks for confirmation:
Team mode creates two additional state files (automatically cleaned up on completion or next user prompt):
| File | Purpose |
|---|---|
.claude/state/team_mode_active | Signals hooks that team mode is active |
.claude/state/team_config.json | Active team configuration (name, teammates, role mappings) |
| Limitation | Details |
|---|---|
| No session resumption | /resume and /rewind don't restore teammates |
| Task status can lag | Teammates may fail to mark tasks completed |
| Shutdown can be slow | Teammates finish current request before stopping |
| One team per session | Cannot create multiple teams in one session |
| No nested teams | Teammates cannot spawn their own teams |
| Lead is fixed | Cannot promote a teammate or transfer leadership |
| Permissions set at spawn | Teammates inherit lead's permission mode |
| Split panes need tmux/iTerm2 | Not supported in VS Code terminal or Windows Terminal |
The framework minimizes command output to reduce context consumption and preserve tokens for meaningful work. Token efficiency is enabled by default (CLAUDE_TOKEN_EFFICIENCY=1).
Behavioral Guidance โ The token_efficient_cli.md system prompt (injected via SessionStart) teaches compact flag usage:
git status -sb (short branch format)pytest -q --tb=short (quiet mode, short tracebacks)npm test -- -q (quiet test output)--help parsing and targeted commandsOutput Compression โ The token_rewrite_hook.py PreToolUse hook rewrites matching Bash commands through compact_run.py, which compresses git/test/log output post-execution:
push, pull, commit, merge, rebase, status, etc.pytest, cargo test, npm/pnpm/yarn/bun test, vitest, jest, mocha, etc.docker logs, kubectl logs, make outputeslint, next, tsccd && command pattern supportConditional System Prompt Injection โ The orchestrator is injected conditionally:
To temporarily disable token-efficient output:
export CLAUDE_TOKEN_EFFICIENCY=0
This disables both the behavioral guidance and output compression layers.
We welcome contributions to the Claude Code Workflow Orchestration System! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.
Found a bug or have a feature request? Please open a GitHub Issue with:
Fork the repository and create a feature branch:
git checkout -b feature/your-feature-name
Make your changes following our code style guidelines (see below)
Run quality checks (if applicable) before submitting:
# Format code
uvx ruff format .
# Lint code
uvx ruff check --no-fix .
# Type checking
uvx pyright .
# Run tests
uv run pytest
All checks must pass before submission.
Commit with clear messages:
git commit -m "feat: description of your changes"
Use conventional commit format: feat:, fix:, docs:, refactor:, etc.
Push to your fork and submit a Pull Request to the main branch with a clear description of changes
list[str], str | None)Always run quality checks locally before submitting to catch issues early.
The project includes a comprehensive test suite covering hooks, token efficiency, and integration:
# Run all tests
uv run pytest
# Run with verbose output and coverage
uv run pytest -v --cov=hooks --cov=scripts --cov=system-prompts
# Run specific test file
uv run pytest tests/test_token_rewrite_hook.py -v
# Run tests matching a pattern
uv run pytest -k "token_efficiency" -v
Test files:
tests/test_token_rewrite_hook.py - Token rewriting hook teststests/test_inject_token_efficiency.py - Token efficiency injection teststests/test_compact_run.py - Compact output runner teststests/test_integration.py - End-to-end integration teststests/conftest.py - Test fixtures and configurationThank you for contributing to making Claude Code workflows even better!
.claude-plugin/
marketplace.json
plugin.json
.github/
workflows/
ci.yml
claude-code-review.yml
claude.yml
.gitignore
agents/
code-cleanup-optimizer.md
code-reviewer.md
codebase-context-analyzer.md
dependency-manager.md
devops-experience-architect.md
documentation-expert.md
task-completion-verifier.md
tech-lead-architect.md
assets/
img_plan_mode.png
img_team_complete.png
img_team_graph.png
img_team_swarm.png
workflow-demo.gif
CHANGELOG.md
CLAUDE.md
commands/
add-statusline.md
delegate.md
docs/
ARCHITECTURE_PHILOSOPHY.md
ARCHITECTURE_QUICK_REFERENCE.md
design/
workflow_state_system.md
environment-variables.md
hook-debugging.md
plan-explore-parallel-processing.md
python-coding-standards.md
README.md
semantic_validation.md
statusline-system.md
validation-schema.md
hooks/
compact_run.py
plugin-hooks.json
PostToolUse/
python_posttooluse_hook.py
remind_skill_continuation.py
remind_todo_after_task.py
validate_task_graph_depth.py
PreToolUse/
require_delegation.py
token_rewrite_hook.py
validate_task_graph_compliance.py
SessionStart/
inject_all.py
stop/
python_stop_hook.py
SubagentStop/
remind_todo_update.py
trigger_verification.py
UserPromptSubmit/
clear-delegation-sessions.py
install.sh
LICENSE
output-styles/
technical-adaptive.md
pytest.ini
README.md
scripts/
statusline.py
statusline.sh
settings.json
system-prompts/
orchestrator_stub.md
token_efficient_cli.md
tests/
conftest.py
test_compact_run.py
test_integration.py
test_require_delegation.py
test_token_rewrite_hook.pyยฉ 2026 Flowy ยท Free and open source
Built for Claude Code ยท Not affiliated with Anthropic