# How Breezing Parallel Execution Mode Works with Sub-Agents in claude-code-harness

> Discover how the breezing parallel execution mode in claude-code-harness leverages sub-agents like Lead, Worker, and Advisor to concurrently execute tasks and merge results efficiently.

- Repository: [Chachamaru/claude-code-harness](https://github.com/Chachamaru127/claude-code-harness)
- Tags: internals
- Published: 2026-05-28

---

**Breezing parallel execution mode orchestrates Lead, Worker, Advisor, and Reviewer sub-agents to decompose tasks into independent file groups, execute them concurrently, and merge results through a structured sprint-contract workflow.**

The `claude-code-harness` repository implements a sophisticated **breezing parallel execution mode** that transforms sequential coding tasks into parallelized workflows. This mode leverages specialized sub-agents to handle complex codebases efficiently by distributing work across multiple Workers while maintaining quality through Advisors and Reviewers.

## Architecture of Breezing Parallel Execution

The breezing mode wraps the core `harness-work` skill and operates as a team-execution framework with four distinct agent roles.

### The Lead Orchestrator

The Lead agent serves as the central orchestrator defined in [`skills/breezing/SKILL.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/skills/breezing/SKILL.md) (lines 2-12). It runs with `role: orchestrator` and `base: harness-work`, forwarding all CLI arguments to `harness-work` while enforcing a rigid team mode hierarchy: **Lead → Worker → Reviewer**.

The Lead parses [`Plans.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/Plans.md) to identify task dependencies, builds sprint-contracts, and manages the entire execution lifecycle. It remains the single point of contact for the user while delegating implementation details to sub-agents.

### Worker Sub-Agents

**Worker agents** (`claude-code-harness:worker`) handle the actual implementation of assigned file groups. According to [`agents/worker.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/agents/worker.md) (lines 4-15 and 92-98), each Worker receives a JSON payload containing:

- Task description and permitted files
- Contract path and validation commands  
- Execution mode identifier (`breezing`)

Workers operate under strict constraints: they cannot spawn additional agents (`disallowedTools: [Agent]`) and must return either a `worker-report.v1` upon completion or an `advisor-request.v1` when encountering complex rule violations (such as embedded git repositories or required architectural spikes).

### Advisor and Reviewer Sub-Agents

The **Advisor** (`claude-code-harness:advisor`) functions as a read-only consultant defined in [`agents/advisor.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/agents/advisor.md). It only activates when a Worker explicitly returns an `advisor-request.v1`, responding with `advisor-response.v1` containing one of three directives: **PLAN**, **CORRECTION**, or **STOP**.

The **Reviewer** (`claude-code-harness:reviewer`) operates serially after each Worker finishes, as documented in [`docs/team-composition.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/docs/team-composition.md) (lines 94-100). It returns a `review-result.v1`; an **APPROVE** verdict triggers the Lead to cherry-pick the Worker commit onto `main`, while rejections generate corrective `SendMessage` commands back to the originating Worker.

## Execution Phases

The breezing parallel execution mode progresses through four distinct phases, with parallelization occurring specifically during the delegation phase.

### Phase 0 – Planning Discussion (Optional)

Before execution, the Lead conducts a sanity-check discussion defined in [`SKILL.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/SKILL.md) (lines 63-68). It poses three questions regarding scope definition, dependency mapping, and risk flag identification. Users can bypass this phase by passing the `--no-discuss` flag.

### Phase A – Pre-delegate

During pre-delegation ([`SKILL.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/SKILL.md) lines 82-89), the Lead decomposes selected tasks into a **sprint-contract** and calculates optimal Worker allocation. The system analyzes [`Plans.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/Plans.md) to identify independent file groups, spawning between one and three Workers based on the dependency graph (see the "worker-数の決め方" table in [`docs/team-composition.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/docs/team-composition.md)).

### Phase B – Delegate

This phase implements the actual **parallel execution**. Each Worker simultaneously implements its assigned file group, runs pre-flight checks, and may request Advisor intervention. Upon completion, Workers return `worker-report.v1`, triggering the Lead to spawn a Reviewer for quality validation. While Workers run in parallel, Reviewers execute serially to ensure deterministic quality gates.

### Phase C – Post-delegate

In the final phase ([`SKILL.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/SKILL.md) lines 52-60), the Lead aggregates progress across all Workers, updates [`Plans.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/Plans.md) with completion status, cherry-picks approved commits onto the `main` branch, and emits a comprehensive completion report detailing successes, failures, and violations detected.

## Parallelism Constraints and Error Handling

True parallelism in breezing mode comes with specific constraints designed to prevent merge conflicts and ensure code quality.

### Worker Count Determination

The Lead determines Worker count by analyzing file dependencies in [`Plans.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/Plans.md). Only **non-overlapping file groups** qualify for parallel execution, with a hard maximum of three concurrent Workers. This constraint prevents race conditions on shared resources while maximizing throughput for isolated changes.

### Stall Detection and Recovery

According to [`agents/worker.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/agents/worker.md) (lines 33-45), the Lead implements a 10-minute silence threshold for Worker monitoring (requires CC 2.1.113+). When a Worker stalls, the Lead may respawn it once; a second stall triggers automatic task escalation to prevent indefinite blocking of the parallel pipeline.

### Universal Violation Injection

The system maintains an in-memory array of **universal violations** discovered by Reviewers ([`SKILL.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/SKILL.md) lines 85-106). These "gotchas" are automatically prefixed to subsequent Worker briefings, ensuring that once a pattern violation is identified, all remaining Workers receive immediate notification to prevent repetition of the same error within the breezing session.

## Command-Line Usage

Invoke breezing parallel execution mode through the `/breezing` command with optional parallelism flags:

```bash

# Execute with two parallel Workers using Codex for implementation

/breezing --parallel 2 --codex all

# Skip planning discussion and process specific tasks

/breezing --no-discuss 3-6

# Enable auto-mode for backward-compatible sessions

/breezing --auto-mode all

```

The `--codex` flag delegates actual implementation to the Codex CLI via [`scripts/codex-companion.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/scripts/codex-companion.sh), while Workers remain logically present in the orchestration flow. The `--parallel` flag accepts values from 1 to 3, though the Lead may spawn fewer Workers if the dependency graph does not support full parallelism.

## Summary

- **Breezing parallel execution mode** uses a Lead orchestrator to manage up to three concurrent Worker sub-agents processing independent file groups.
- **Worker constraints** prevent nested agent spawning (`disallowedTools: [Agent]`), while Advisors and Reviewers maintain quality through serial validation gates.
- **Execution phases** follow a strict Pre-delegate → Delegate → Post-delegate workflow, with optional Phase 0 planning discussions.
- **Error resilience** includes 10-minute stall detection, universal violation injection, and automatic cherry-picking of approved commits onto `main`.

## Frequently Asked Questions

### How many Workers can breezing spawn simultaneously?

The breezing parallel execution mode supports a maximum of **three concurrent Workers** determined by analyzing independent file groups in [`Plans.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/Plans.md). The Lead calculates the optimal count (1-3) during Phase A based on task dependencies to prevent file contention.

### What happens when a Worker encounters a rule violation?

When a Worker detects complex scenarios like embedded git repositories or required architectural spikes, it returns an `advisor-request.v1` to the Lead. The Lead then spawns an **Advisor** sub-agent that returns a directive (PLAN, CORRECTION, or STOP) guiding the Worker toward resolution without interrupting other parallel Workers.

### How does the Lead handle long-running Worker processes?

The Lead monitors Workers for **10 minutes of silence** (CC 2.1.113+). If a Worker stalls, the Lead may respawn it once; a second stall results in task escalation. For sessions exceeding 30 minutes, consult [`docs/long-running-harness.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/docs/long-running-harness.md) to enable 1-hour prompt cache optimization.

### Can breezing mode integrate with Codex CLI?

Yes. Passing the `--codex` flag delegates implementation to the Codex CLI via [`scripts/codex-companion.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/scripts/codex-companion.sh). The Lead and Worker sub-agents remain logically active in the orchestration flow, but the heavy implementation lifting transfers to Codex, allowing the breezing parallel structure to manage Codex-generated outputs.