codeflash-agent/plugin/languages/java/references/team-orchestration.md

# Team Orchestration -- Java Deep Mode

Protocol for creating, dispatching, coordinating, and merging work from domain-specialist agents. The deep agent uses this when the unified target table has a mix of multi-domain and single-domain targets.

## Creating the team

After unified profiling, if dispatching:

```
TeamCreate("deep-session")
TaskCreate("Unified profiling") -- mark completed
TaskCreate("Cross-domain experiments")
TaskCreate("Dispatched: CPU targets")   -- if dispatching CPU agent
TaskCreate("Dispatched: Memory targets") -- if dispatching memory agent
TaskCreate("Dispatched: Async targets")  -- if dispatching async agent
```

## Dispatching domain agents

The key difference from the router dispatching blindly: **you provide cross-domain context the domain agent wouldn't have.**

### CPU specialist example

```
Agent(subagent_type: "codeflash-java-cpu", name: "cpu-specialist",
      team_name: "deep-session", isolation: "worktree", prompt: "
  You are working under the deep optimizer's direction.

  ## Targeted Assignment
  Optimize these specific functions: <list from unified target table>

  ## Cross-Domain Context (from deep profiling)
  - processRecords: 45% CPU, but 40% of that is GC from 120 MiB allocation.
    I've already fixed the allocation in experiment 1. Re-profile -- the CPU
    picture should be cleaner now. Focus on the remaining algorithmic work.
  - serialize: 18% CPU, pure CPU problem -- no memory interaction.
    Likely autoboxing-in-loop or O(n^2) pattern.

  ## Environment
  <setup.md contents: JDK version, build tool, test command, GC algorithm>

  ## Conventions
  <conventions.md contents if exists>

  Work on these targets only. Send results via SendMessage(to: 'deep-lead').
")
```

### Memory specialist example

```
Agent(subagent_type: "codeflash-java-memory", name: "mem-specialist",
      team_name: "deep-session", isolation: "worktree", prompt: "
  You are working under the deep optimizer's direction.

  ## Targeted Assignment
  Reduce allocations in loadData -- it allocates 500 MiB and triggers
  300ms of G1 mixed collection pauses.

  ## Cross-Domain Context
  - This method is called in a thread pool. Large allocations here
    trigger GC pauses that block all worker threads.
  - The async team will benefit from your memory reduction.
  - Do NOT change the thread pool configuration -- that's the async domain.
  ...")
```

### Async specialist example

```
Agent(subagent_type: "codeflash-java-async", name: "async-specialist",
      team_name: "deep-session", isolation: "worktree", prompt: "
  You are working under the deep optimizer's direction.

  ## Targeted Assignment
  Fix lock contention in CacheManager -- JFR shows 340ms avg monitor wait
  on the synchronized block at CacheManager.java:88.

  ## Cross-Domain Context
  - The memory team is reducing allocation pressure in loadData.
    Once they finish, GC pauses will drop and thread throughput will
    improve even without your fix. But the lock contention is independent.
  ...")
```

## Dispatching a researcher

Spawn a researcher to read ahead on targets while you work on the current one:

```
Agent(subagent_type: "codeflash-researcher", name: "researcher",
      team_name: "deep-session", prompt: "
  Investigate these targets from the deep optimizer's unified target table:
  1. serialize in OutputService.java:88 -- 18% CPU, no memory interaction
  2. validate in Validator.java:12 -- 8% CPU, +15 MiB memory
  For each, identify the specific antipattern and whether there are
  cross-domain interactions I might have missed.
  Send findings to: SendMessage(to: 'deep-lead')
")
```

## Receiving results from dispatched agents

When dispatched agents send results via `SendMessage`:

1. **Integrate findings into unified view.** Update the target table with their results.
2. **Check for cross-domain effects.** If the CPU specialist's fix reduced CPU time, re-profile memory -- did GC behavior change?
3. **Revise strategy.** Dispatched results may shift priorities. A memory specialist reducing allocations by 80% means your CPU targets' profiles are stale -- re-profile.
4. **Track in results.tsv.** Record dispatched results with a note: `dispatched:cpu-specialist` in the description field.

## Parallel dispatch with profiling conflict awareness

Two agents profiling simultaneously experience higher variance from CPU contention. JFR CPU sampling and async-profiler timing modes are affected; JFR allocation event profiling (`jdk.ObjectAllocationInNewTLAB`) is not.

Include in every dispatched agent's prompt: **"You are running in parallel with another optimizer. Expect higher variance -- use 3x re-run confirmation for all results near the keep/discard threshold."**

## Merging dispatched work

When dispatched agents complete:

1. **Collect branches.** `git branch --list 'codeflash/*'` -- each dispatched agent created its own branch in its worktree.
2. **Check for file overlap.** Cross-reference changed files between your branch and dispatched branches. `git diff --name-only main..codeflash/cpu-specialist` vs your branch.
3. **Merge in impact order.** Highest improvement first. If files overlap, check whether changes conflict or complement.
4. **Re-profile after merge.** The combined changes may produce compounding effects -- or regressions. Run the unified profiling script on the merged state.
5. **Record the merged state** in HANDOFF.md and results.tsv.

## Team cleanup

When done (all dispatched agents complete and merged):

```
TeamDelete("deep-session")
```

Preserve `.codeflash/results.tsv`, `.codeflash/HANDOFF.md`, and `.codeflash/learnings.md`.