Skip to content
Back to search

claude-code-workflow-orchestration

Claude Code plugin for multi-step workflow orchestration — automatic task decomposition, parallel agent execution, and specialized agent delegation with native plan mode integration.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/barkain--claude-code-workflow-orchestration/badge.svg)](/listings/barkain--claude-code-workflow-orchestration)

HTML

<a href="/listings/barkain--claude-code-workflow-orchestration"><img src="/api/listings/barkain--claude-code-workflow-orchestration/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Prerequisites

macOS / Linux

- uv: https://docs.astral.sh/uv/getting-started/installation/

curl -LsSf https://astral.sh/uv/install.sh | sh

- bun: https://bun.com/docs/installation

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`

- uv: https://docs.astral.sh/uv/getting-started/installation/

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

- bun: https://bun.sh/docs/installation

powershell -c "irm bun.sh/install.ps1 | iex"

- jq (optional, for advanced parallel workflow features):

# 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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 32 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "barkain-plugins",
  3. "owner": {
  4. "name": "Nadav Barkai"
  5. },
  6. "plugins": [
  7. {
  8. "name": "workflow-orchestrator",
  9. "source": "./",
  10. "description": "Delegation system with workflow orchestration, specialized agents, and parallel execution for Claude Code",
  11. "version": "2.1.1",
  12. "author": {
  13. "name": "Nadav Barkai"
  14. },
  15. "repository": "https://github.com/barkain/claude-code-workflow-orchestration",
  16. "license": "MIT",
  17. "keywords": ["delegation", "workflow", "orchestration", "agents"],
  18. "category": "productivity"
  19. },
  20. {
  21. "name": "madrox",
  22. "description": "MCP server that orchestrates multiple Claude CLI instances as parallel workers with a real-time dashboard",
  23. "version": "1.9.1",
  24. "source": {
  25. "source": "github",
  26. "repo": "barkain/madrox"
  27. },
  28. "category": "productivity",
  29. "homepage": "https://github.com/barkain/madrox"
  30. }
  31. ]
  32. }
README.md · README · 608 lines · 2 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Claude Code Workflow Orchestration System
  2. 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.
  3. See the delegation system in action:
  4. <img src="./assets/workflow-demo.gif" alt="Workflow Demo" width="800">
  5. ## 🆕 What's New
  6. ⚡ **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.
  7. 🤝 **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`.
  8. ## Overview
  9. 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.
  10. ### Key Features
  11. - **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.
  12. - **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.
  13. - **8 Specialized Agents** - Each agent has domain expertise (code cleanup, testing, architecture, DevOps, etc.)
  14. - **Native Plan Mode** - Built-in plan mode (EnterPlanMode/ExitPlanMode) handles planning, agent selection, and execution orchestration
  15. - **Intelligent Multi-Step Workflows** - Sequential execution for dependent phases, parallel for independent phases
  16. - **Dual-Mode Execution** - Isolated subagent sessions (default) or collaborative Agent Teams with real-time inter-agent communication (experimental)
  17. - **Agent Teams Integration** - Native `TeamCreate` + `Agent(team_name=...)` + `SendMessage` for peer-to-peer collaboration, shared task lists, and coordinated multi-agent workflows
  18. - **Tasks API Integration** - Native task tracking via TaskCreate, TaskUpdate, TaskList, TaskGet with structured metadata
  19. - **Structured Task Metadata** - Wave assignments, phase IDs, agent assignments, and dependencies encoded in task metadata
  20. - **Async Hook Support** - Non-blocking background tasks for reminders and cleanup operations
  21. - **Stateful Session Management** - Fresh delegation enforcement per user message with per-turn nudge counter
  22. - **Smart Dependency Analysis** - Automatically analyzes phase dependencies to determine optimal execution mode
  23. - **Parallel Execution Support** - Executes independent phases concurrently with automatic wave synchronization
  24. - **Visualization & Debugging** - Comprehensive logging and debug tools for understanding delegation decisions
  25. ### Execution Model
  26. The system uses a two-stage execution pipeline:
  27. **Stage 0: Planning & Analysis (native plan mode)**
  28. - Analyzes task complexity (single-step vs multi-step)
  29. - Decomposes complex tasks into atomic phases
  30. - Performs dependency analysis to determine execution mode
  31. - Assigns specialized agents via keyword matching
  32. - Creates wave assignments for parallel/sequential execution
  33. - Creates tasks via TaskCreate with structured metadata
  34. **Stage 1: Execution**
  35. - **Single-Step Tasks:** Hook blocks tools → Delegates to specialized agent → Agent executes → Results returned
  36. - **Multi-Step Workflows:**
  37. - **Subagent mode (default):** Isolated parallel Agent instances per wave. Agents return `DONE|{path}`. Context-efficient, optimal for most workflows.
  38. - **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`.
  39. - Results consolidated and summary provided
  40. **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.
  41. ## Quick Start
  42. ### Prerequisites
  43. #### macOS / Linux
  44. - uv: https://docs.astral.sh/uv/getting-started/installation/
  45. ```bash
  46. curl -LsSf https://astral.sh/uv/install.sh | sh
  47. ```
  48. - bun: https://bun.com/docs/installation
  49. ```bash
  50. curl -fsSL https://bun.com/install | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 70 on GitHub
  51. ```
  52. - jq: JSON processor for parallel workflow state tracking.
  53. ```bash
  54. # macOS
  55. brew install jq
  56. # Linux
  57. sudo apt install jq
  58. ```
  59. #### Windows
  60. **Python 3.12+** is required. All hooks use cross-platform Python scripts.
  61. - Python: https://www.python.org/downloads/
  62. - During installation, ensure "Add Python to PATH" is checked
  63. - Verify installation: `python --version`
  64. - uv: https://docs.astral.sh/uv/getting-started/installation/
  65. ```powershell
  66. powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  67. ```
  68. - bun: https://bun.sh/docs/installation
  69. ```powershell
  70. powershell -c "irm bun.sh/install.ps1 | iex"
  71. ```
  72. - jq (optional, for advanced parallel workflow features):
  73. ```powershell
  74. # Using Chocolatey
  75. choco install jq
  76. # Or download from https://jqlang.github.io/jq/download/
  77. ```
  78. **Note:** The hook system uses Python scripts for cross-platform compatibility. Ensure `python` is available in your PATH.
  79. ## Installation
  80. This project provides a comprehensive delegation system for Claude Code with multi-agent orchestration. Choose your preferred installation method:
  81. ### 🔌 Plugin Installation (Recommended)
  82. The easiest way to install is via Claude Code's plugin system:
  83. ```bash
  84. # Add the marketplace
  85. claude plugin marketplace add barkain/claude-code-workflow-orchestration
  86. # Install the plugin
  87. claude plugin install workflow-orchestrator@barkain-plugins # user-level
  88. # or
  89. claude plugin install workflow-orchestrator@barkain-plugins --scope project # project-level
  90. ```
  91. **Benefits:**
  92. - Automatic setup and configuration
  93. - Easy updates via plugin manager
  94. - No manual file copying required
  95. **Optional Settings:**
  96. - Run `/workflow-orchestrator:add-statusline` after installation to enable workflow status display
  97. - The plugin includes a `technical-adaptive` output style optimized for workflow orchestration. To select it, configure `outputStyle` in your Claude Code settings (project or user level)
  98. **Note:** Changing the output style requires restarting your Claude Code session for the change to take effect.
  99. ### 🔨 Manual Installation
  100. For development or custom configurations:
  101. ```bash
  102. # Clone the repository
  103. git clone https://github.com/barkain/claude-code-workflow-orchestration.git
  104. ```
  105. #### Project-Specific Installation (Recommended)
  106. For project-isolated configurations or version-controlled delegation setups:
  107. ```bash
  108. cd path/to/project
  109. path/to/repo/install.sh # follow the installation instructions
  110. ```
  111. **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.
  112. ## Example Usage - Multi-Step Workflow
  113. Once installed, the delegation hook is automatically active. Simply use Claude Code normally (Opus 4.5 is preferred):
  114. ```bash
  115. # Multi-step workflow - enable orchestration for context passing
  116. claude
  117. ```
  118. and then prompt claude with:
  119. ```text
  120. > create a simple calculator app with basic math operations.
  121. add a nice UI and use NextJS/Tailwind to build this out.
  122. the backend should be implemented in python as a modern uv project.
  123. add verification steps after each phase.
  124. ```
  125. **What happens:**
  126. 1. 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**.
  127. ![plan mode](assets/img_plan_mode.png)
  128. 2. After `ExitPlanMode` approval, a dependency graph is rendered showing the parallel waves and the agents assigned to each phase:
  129. ![dependency graph](assets/img_team_graph.png)
  130. 3. 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:
  131. ![team swarm running](assets/img_team_swarm.png)
  132. 4. As each wave completes, downstream phases unblock automatically. A final integration/verification phase confirms end-to-end correctness, then the team shuts down cleanly:
  133. ![team complete](assets/img_team_complete.png)
  134. ### Soft Enforcement in Action
  135. The delegation system uses adaptive nudges instead of hard blocks:
  136. ```bash
  137. # 1st direct tool call (imperative STOP)
  138. Read test.py
  139. # stderr: "STOP. This tool call bypasses delegation. Abandon this step and run: /workflow-orchestrator:delegate <your task>"
  140. # 2nd direct tool call (imperative STOP, 2nd-call phrasing)
  141. Read other.py
  142. # stderr: "STOP. 2nd direct tool call this turn. The main agent does not execute work tools. Run: /workflow-orchestrator:delegate <your task>"
  143. # 3rd direct tool call (strong reminder — explains what's being lost)
  144. Edit file.py
  145. # 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>"
  146. # 4th+ direct tool calls keep the same strong reminder with the updated count
  147. Bash command.sh
  148. # stderr: "STOP. 4 direct tool calls bypassing delegation. ..."
  149. # Delegation resets the counter (state clean)
  150. /workflow-orchestrator:delegate "Create feature"
  151. # Counter zeros. Next turn starts fresh.
  152. ```
  153. Counter resets each user turn and zeros when `/workflow-orchestrator:delegate` runs. Subagents are immune. Use `/workflow-orchestrator:bypass` for emergency access without restarting.
  154. ## Environment Variables
  155. The system supports several environment variables for configuration and debugging:
  156. **Tasks API Configuration:**
  157. ```bash
  158. CLAUDE_CODE_ENABLE_TASKS=true # Enable Tasks API (default: true)
  159. CLAUDE_CODE_TASK_LIST_ID=list_id # Share task list across sessions
  160. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 # Disable async background tasks
  161. ```
  162. **Agent Teams (Experimental):**
  163. ```bash
  164. CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 # Enable Agent Teams dual-mode execution
  165. ```
  166. **Token Efficiency:**
  167. ```bash
  168. CLAUDE_TOKEN_EFFICIENCY=1 # Enable token-efficient CLI output (default: 1)
  169. ```
  170. **Debug & Control:**
  171. ```bash
  172. DEBUG_DELEGATION_HOOK=1 # Enable hook debug logging
  173. DELEGATION_HOOK_DISABLE=1 # Emergency bypass (disable enforcement)
  174. CLAUDE_MAX_CONCURRENT=8 # Max parallel agents per batch (default 8)
  175. CHECK_RUFF=0 # Skip Ruff validation in PostToolUse
  176. CHECK_PYRIGHT=0 # Skip Pyright validation in PostToolUse
  177. CLAUDE_SKIP_PYTHON_VALIDATION=1 # Skip all Python validation
  178. ```
  179. See [Environment Variables](./docs/environment-variables.md) for detailed configuration.
  180. ## Setup Details
  181. ### Hook Configuration
  182. The `plugin-hooks.json` configures the delegation enforcement hooks using cross-platform Python scripts:
  183. **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.
  184. **Hook Events (6 lifecycle points, 14 hooks):**
  185. | Event | Scripts | Purpose |
  186. |-------|---------|---------|
  187. | **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 |
  188. | **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 |
  189. | **UserPromptSubmit** | `clear-delegation-sessions.py` | Reset per-turn nudge counter, clear delegation/team state |
  190. | **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. |
  191. | **SubagentStop** | `remind_todo_update.py` (async), `trigger_verification.py` | Remind to update tasks, suggest verification |
  192. | **Stop** | `python_stop_hook.py` | Turn duration tracking, workflow continuation |
  193. ### SessionStart Injection (Lean & On-Demand)
  194. The `inject_all.py` hook consolidates 3 SessionStart hooks into 1 Python script:
  195. **On startup/resume (all sessions):**
  196. - Injects orchestrator routing stub (`orchestrator_stub.md`, ~1.1KB): points the main agent at `/workflow-orchestrator:delegate` for multi-step work. Minimal overhead (~200 tokens).
  197. - Optionally injects token-efficient CLI guide (`token_efficient_cli.md`, ~1.9KB, gated by `CLAUDE_TOKEN_EFFICIENCY=1` env var). Teaches compact flags and command patterns.
  198. - Output style loaded natively from plugin.json `outputStyles` field (no injection required). Saves ~1.5K tokens.
  199. **On first delegation (lazy load):**
  200. - Full orchestrator logic (planning instructions, agent catalog, wave scheduling, team-mode execution) lives inline in `commands/delegate.md` and is loaded only when `/workflow-orchestrator:delegate` runs.
  201. **Net savings:** ~6.6K tokens off session startup. Sessions pay the orchestration tax only when delegation is actually used.
  202. **What this enables:**
  203. - Multi-step task detection via pattern matching
  204. - Dependency analysis for execution mode selection
  205. - Context passing between workflow phases
  206. - Tasks API integration for progress tracking
  207. - Wave synchronization for parallel execution
  208. ## Core Components
  209. ### 1. Delegation Hook (`hooks/PreToolUse/require_delegation.py`)
  210. 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.
  211. **Allowed tools (no nudge):**
  212. - `AskUserQuestion`, `Skill`, `SlashCommand` - Explicit queries and commands
  213. - `TaskCreate`, `TaskUpdate`, `TaskList`, `TaskGet` - Task tracking (structured metadata)
  214. - `Agent`, `SubagentTask`, `AgentTask` - Delegation mechanism
  215. - `TeamCreate`, `SendMessage` - Agent Teams (when `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`)
  216. - `ToolSearch` - Tool discovery
  217. - New Claude Code tools (by definition, never tracked)
  218. **Work tools (tracked for nudges, not blocked):**
  219. - `Bash`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `MultiEdit`, `NotebookEdit`
  220. **Nudge escalation by violation count (per turn):**
  221. - 0 violations: silent
  222. - 1 violation: `delegate?` (~2 tokens)
  223. - 2 violations: `nudge: use /workflow-orchestrator:delegate for multi-step work` (~12 tokens)
  224. - 3-4 violations: `WARNING: N direct tool calls bypassing delegation...` (~25 tokens)
  225. - 5+ violations: Strong reminder (~55 tokens)
  226. **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.
  227. ### 2. Specialized Agents (`agents/`)
  228. 8 specialized agents for different task types:
  229. - **tech-lead-architect** - Solution design, architecture, research
  230. - **codebase-context-analyzer** - Code exploration, architecture analysis
  231. - **task-completion-verifier** - Validation, testing, quality assurance
  232. - **code-cleanup-optimizer** - Refactoring, technical debt reduction
  233. - **code-reviewer** - Code review for best practices
  234. - **devops-experience-architect** - Infrastructure, deployment, CI/CD
  235. - **documentation-expert** - Documentation creation and maintenance
  236. - **dependency-manager** - Dependency management and updates
  237. **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.
  238. ### 3. Delegation Command (`commands/delegate.md`)
  239. The `/workflow-orchestrator:delegate` command provides intelligent task delegation with integrated planning:
  240. ```bash
  241. /workflow-orchestrator:delegate <task description>
  242. ```
  243. **How it works:**
  244. 1. Enters native plan mode (EnterPlanMode) for unified planning and orchestration
  245. 2. Plan mode analyzes task complexity and decomposes into phases
  246. 3. Performs dependency analysis to determine execution mode (sequential or parallel)
  247. 4. Assigns specialized agents via keyword matching (>=2 match threshold)
  248. 5. Creates wave assignments and execution plan
  249. 6. Creates task list via TaskCreate
  250. 7. Exits plan mode (ExitPlanMode) and executes phases as directed by the plan
  251. ### 4. Orchestrator Command (`commands/delegate.md`)
  252. 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).
  253. **Activate via:**
  254. Simply start a Claude code session
  255. ```bash
  256. claude
  257. ```
  258. **Multi-step detection patterns:**
  259. - Sequential connectors: "and then", "after that", "next"
  260. - Compound indicators: "with [noun]", "including [noun]"
  261. - Multiple verbs: "create X and test Y"
  262. **Unified Planning & Execution:**
  263. Native plan mode (EnterPlanMode/ExitPlanMode) handles both planning and execution orchestration:
  264. 1. **Task Decomposition** - Breaks complex tasks into atomic phases
  265. 2. **Dependency Analysis** - Analyzes phase dependencies to determine optimal execution mode
  266. 3. **Intelligent Execution Mode Selection** - Chooses between sequential and parallel execution
  267. 4. **Sequential Execution** - Dependent phases execute one at a time with context passing
  268. 5. **Parallel Execution** - Independent phases execute concurrently in waves
  269. 6. **Progress Tracking** - Tasks API maintains visible task list throughout
  270. 7. **State Management** - Wave synchronization ensures proper completion order
  271. **Execution mode decision logic:**
  272. - **Sequential:** When phases have data dependencies, file conflicts, or state conflicts requiring ordered execution
  273. - **Parallel:** When phases are independent with no data dependencies, enabling time-efficient concurrent execution
  274. - **Conservative fallback:** Sequential is chosen when dependencies are uncertain
  275. **Complete workflow process:**
  276. 1. User submits multi-step task (detected by workflow_orchestrator patterns)
  277. 2. Native plan mode entered (EnterPlanMode) to decompose and plan execution
  278. 3. Task list created via TaskCreate with all phases
  279. 4. Phase dependencies analyzed to determine execution mode
  280. 5. **Sequential Mode:** Phases execute one at a time with context passing
  281. 6. **Parallel Mode:** Independent phases grouped into waves and executed concurrently
  282. 7. Wave synchronization ensures proper completion order
  283. 8. Results consolidated with absolute file paths and summary provided
  284. ## Agent Teams (Experimental)
  285. 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.
  286. ### Enabling Agent Teams
  287. Set the environment variable before starting Claude Code:
  288. ```bash
  289. export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
  290. ```
  291. No other configuration is required. Plan mode automatically evaluates whether a given task benefits from team-based execution.
  292. ### How Mode Selection Works
  293. During planning, plan mode checks tool availability:
  294. **ONE RULE:** If `TeamCreate` is in your available tools → `execution_mode: "team"`. Otherwise → `"subagent"`.
  295. 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.
  296. ### Subagent Mode vs Team Mode
  297. | Aspect | Subagent Mode (default) | Team Mode (experimental) |
  298. |-------------------|-----------------------------------------|---------------------------------------------|
  299. | Execution | Isolated `Agent(...)` per phase | `Agent(team_name=...)` per phase |
  300. | Communication | None (agents are isolated) | `SendMessage` for peer-to-peer messaging |
  301. | Task list | Framework-managed via TaskCreate/Update | Shared task list, teammates self-claim |
  302. | Coordination | Main agent orchestrates waves | Teammates self-coordinate |
  303. | Context sharing | Via output files (`DONE\|{path}`) | Shared context + messaging |
  304. | Best for | Most workflows, context-efficient | Complex collaborative tasks, review cycles |
  305. The key difference is **one parameter**: `Agent(team_name="x")` makes a teammate; `Agent()` makes an isolated subagent.
  306. ### Two Team Workflow Patterns
  307. **Simple team** -- a single AGENT TEAM phase with multiple teammates exploring in parallel. Used for multi-perspective exploration tasks.
  308. ```text
  309. > explore the authentication system from different angles
  310. ```
  311. This creates one team phase where each teammate explores a different perspective (e.g., security, performance, architecture), then results are synthesized.
  312. **Complex team** -- multiple individual phases across waves, all executed as teammates with `Agent(team_name=...)`. Used for collaborative implementation tasks.
  313. ```text
  314. > implement the payment service. tasks should be collaborative
  315. ```
  316. All phases run as teammates sharing context and messaging, even though each has a distinct assignment.
  317. ### Example Prompts That Trigger Team Mode
  318. ```text
  319. > explore the codebase from different angles
  320. > design the API with a team of specialists
  321. > implement the feature collaboratively
  322. > use a team to review and refactor the auth module
  323. > brainstorm together on the CLI design
  324. ```
  325. ### User Approval
  326. Before creating a team, the framework presents the team plan and asks for confirmation:
  327. - Team name, execution mode, number of phases, wave structure
  328. - If declined, execution falls back to subagent mode automatically
  329. ### State Files
  330. Team mode creates two additional state files (automatically cleaned up on completion or next user prompt):
  331. | File | Purpose |
  332. |------------------------------------|----------------------------------------------------------------------|
  333. | `.claude/state/team_mode_active` | Signals hooks that team mode is active |
  334. | `.claude/state/team_config.json` | Active team configuration (name, teammates, role mappings) |
  335. ### Known Limitations
  336. | Limitation | Details |
  337. |---------------------------------|--------------------------------------------------------------|
  338. | No session resumption | `/resume` and `/rewind` don't restore teammates |
  339. | Task status can lag | Teammates may fail to mark tasks completed |
  340. | Shutdown can be slow | Teammates finish current request before stopping |
  341. | One team per session | Cannot create multiple teams in one session |
  342. | No nested teams | Teammates cannot spawn their own teams |
  343. | Lead is fixed | Cannot promote a teammate or transfer leadership |
  344. | Permissions set at spawn | Teammates inherit lead's permission mode |
  345. | Split panes need tmux/iTerm2 | Not supported in VS Code terminal or Windows Terminal |
  346. ## Token-Efficient CLI Usage
  347. 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`).
  348. ### Multi-Layer Approach
  349. 1. **Behavioral Guidance** — The `token_efficient_cli.md` system prompt (injected via SessionStart) teaches compact flag usage:
  350. - `git status -sb` (short branch format)
  351. - `pytest -q --tb=short` (quiet mode, short tracebacks)
  352. - `npm test -- -q` (quiet test output)
  353. - Encourages `--help` parsing and targeted commands
  354. 2. **Output Compression** — The `token_rewrite_hook.py` PreToolUse hook rewrites matching Bash commands through `compact_run.py`, which compresses git/test/log output post-execution:
  355. - Git: `push`, `pull`, `commit`, `merge`, `rebase`, `status`, etc.
  356. - Test runners: `pytest`, `cargo test`, `npm/pnpm/yarn/bun test`, `vitest`, `jest`, `mocha`, etc.
  357. - Logs: `docker logs`, `kubectl logs`, `make` output
  358. - Build tools: `eslint`, `next`, `tsc`
  359. - Command chaining: `cd && command` pattern support
  360. 3. **Conditional System Prompt Injection** — The orchestrator is injected conditionally:
  361. - On session startup: Stub version (~200 tokens) provides minimal direction
  362. - On first plan mode entry (via /workflow-orchestrator:delegate or detected multi-step): Full version (~11K tokens) for complete planning capability
  363. - Saves tokens for single-step and read-only tasks
  364. ### Disable Token Efficiency
  365. To temporarily disable token-efficient output:
  366. ```bash
  367. export CLAUDE_TOKEN_EFFICIENCY=0
  368. ```
  369. This disables both the behavioral guidance and output compression layers.
  370. ## Contributing
  371. We welcome contributions to the Claude Code Workflow Orchestration System! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.
  372. ### Reporting Issues
  373. Found a bug or have a feature request? Please open a GitHub Issue with:
  374. - Clear description of the issue or feature request
  375. - Steps to reproduce (for bugs)
  376. - Expected vs. actual behavior
  377. - Your environment (Windows/macOS/Linux, Claude Code version, Python version, etc.)
  378. - The used claude code model
  379. - Relevant logs or screenshots if applicable
  380. ### Submitting Pull Requests
  381. 1. **Fork the repository** and create a feature branch:
  382. ```bash
  383. git checkout -b feature/your-feature-name
  384. ```
  385. 2. **Make your changes** following our code style guidelines (see below)
  386. 3. **Run quality checks (if applicable)** before submitting:
  387. ```bash
  388. # Format code
  389. uvx ruff format .
  390. # Lint code
  391. uvx ruff check --no-fix .
  392. # Type checking
  393. uvx pyright .
  394. # Run tests
  395. uv run pytest
  396. ```
  397. All checks must pass before submission.
  398. 4. **Commit with clear messages:**
  399. ```bash
  400. git commit -m "feat: description of your changes"
  401. ```
  402. Use conventional commit format: `feat:`, `fix:`, `docs:`, `refactor:`, etc.
  403. 5. **Push to your fork** and **submit a Pull Request** to the main branch with a clear description of changes
  404. ### Python Code Style Expectations
  405. - **Python 3.12+** with modern syntax (e.g., `list[str]`, `str | None`)
  406. - **Type hints** on all functions and variables
  407. - **No print statements** - use structured logging with logger calls
  408. - **Comprehensive docstrings** with examples for public APIs
  409. - **Clear variable and function names** that reflect intent
  410. - Automatic enforcement via Ruff (formatting), Pyright (types), and Pytest (tests)
  411. Always run quality checks locally before submitting to catch issues early.
  412. ### Test Suite
  413. The project includes a comprehensive test suite covering hooks, token efficiency, and integration:
  414. ```bash
  415. # Run all tests
  416. uv run pytest
  417. # Run with verbose output and coverage
  418. uv run pytest -v --cov=hooks --cov=scripts --cov=system-prompts
  419. # Run specific test file
  420. uv run pytest tests/test_token_rewrite_hook.py -v
  421. # Run tests matching a pattern
  422. uv run pytest -k "token_efficiency" -v
  423. ```
  424. Test files:
  425. - `tests/test_token_rewrite_hook.py` - Token rewriting hook tests
  426. - `tests/test_inject_token_efficiency.py` - Token efficiency injection tests
  427. - `tests/test_compact_run.py` - Compact output runner tests
  428. - `tests/test_integration.py` - End-to-end integration tests
  429. - `tests/conftest.py` - Test fixtures and configuration
  430. ### We Value
  431. - Clear, well-documented code
  432. - Tests for new functionality
  433. - Documentation updates for new features
  434. - Constructive feedback and collaboration
  435. - Diverse perspectives and creative solutions
  436. Thank you for contributing to making Claude Code workflows even better!

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.