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

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 (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 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 (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. 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 (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 (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 lines 82-89), the Lead decomposes selected tasks into a sprint-contract and calculates optimal Worker allocation. The system analyzes 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).

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 lines 52-60), the Lead aggregates progress across all Workers, updates 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. 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 (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 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:

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}