External Brigade

External Brigade

Use this utility when a bounded set of external helper runs should launch in parallel instead of being described piecemeal inside ad hoc lead notes.

Workflow economy projection

Apply the binding shared Workflow economy (binding) rule. An external brigade is off by default and may launch only for an explicit user request, enabled configuration, or a documented risk trigger; it does not manufacture optional review or progress artifacts.

When to use

• More than one independent external helper lane is ready at the same time.
• The task needs a mix of advisory, worker-side, or review-side external artifacts in one bounded batch.
• The same external provider may need to be reused across multiple disjoint slices or admitted artifacts.
• Internal native slot limits would otherwise slow clearly eligible external work.

Do not use

• For owner lanes such as $lead or $product-manager.
• For overlapping write surfaces.
• For one vague request like "ask externals to help with everything."
• When one ordinary external helper invocation is enough.

Brigade item contract

Each brigade item must name:

• execution role: consultant, external-worker, or external-reviewer
• assigned / replaced internal role, or none for pure advisory
• lane classification
• goal and expected artifact
• approved inputs
• allowed tools
• scope and out of scope
• allowed change surface
• must-not-break surfaces when code or docs may change
• provider selection: explicit provider or auto
• whether the item is required or explicitly optional

One brigade item equals one helper instance, one admitted artifact, and one gate.

Routing rules

1. Read and normalize .agents/.agents-mode.yaml before trusting any flags.
2. Honor the current external routing fields, including:
   • consultantMode (allowed: external | internal | disabled; default: disabled)
   • parallelMode (allowed: manual | auto | force; default: auto)
   • externalProvider
   • externalPriorityProfile
   • reserveResolver
   • externalPriorityProfiles
   • externalOpinionCounts
   • externalCodexWorkdirMode
   • externalClaudeWorkdirMode
   • externalModelMode
   • externalCodexProfile
   • externalClaudeProfile
3. Reject unsupported owner routes before provider resolution.
4. Keep parallelMode as the general helper fan-out rule. Brigade launch is an explicit bounded overlay on top of that rule, not a second general concurrency model.
5. Keep externalOpinionCounts scoped to same-lane distinct-opinion requirements. It does not cap how many same-provider brigade items may run in parallel across different disjoint lanes or slices.
6. Allow repeated same-provider fan-out when each brigade item owns a different admitted artifact or disjoint slice and the provider runtime supports concurrent non-interactive execution.
7. If a brigade item itself requires 2+ same-lane opinions, satisfy that distinct-provider requirement first or fail that item closed.
8. When a brigade advisory/review item reaches reserve, bind it through reserveResolver; worker-side brigade items must not use reserve.
9. Do not silently downgrade external items to internal execution inside the brigade.

Return exactly one artifact

Return one brigade report with:

1. Brigade summary
2. Launch table
3. Aggregated artifact / findings pointers
4. Open blockers or shortfalls
5. Gate: PASS | REVISE | BLOCKED:dependency

The launch table must keep these columns explicit:

Gate rules

• PASS only when every required brigade item produced its required artifact.
• REVISE when at least one required item returned REVISE and no required item is blocked.
• BLOCKED:dependency when a required item cannot run, when a same-lane distinct-opinion count cannot be satisfied, or when the requested brigade is structurally invalid.
• Optional items may be skipped only when the approved brief marks them optional explicitly.

Non-goals

• Not a new specialist role.
• Not a replacement for $lead.
• Not a way to hide overlapping write scopes.
• Not a way to collapse multiple unrelated artifacts into one vague helper request.