Motivation
Three-layer decoupling says each layer knows only the layer below it. The common way to break it is quiet: the orchestrator builds its squads' agents. It imports none of them; it lists their names, fills an agent registry and hands that to a squad loader. Import checks pass, yet every change to a squad's team means editing the orchestrator.
The Squad Layer pattern gives agent construction to the layer that owns the team. The entry point builds the squad loader once; orchestrators load squads by YAML file and id; the loader builds the agents each squad's YAML names. Squad-level behaviour lives in one application class, instantiated per squad.
Structure
- Squad YAML names the squad's agents and flow
- The entry point builds the squad loader (SquadLoader.from_agents) once and passes it to every orchestrator
- The orchestrator calls self.squads.load_one(squad_yaml, squad_id) — squads only
- The squad loader resolves each named agent from its own YAML (class + module) and builds it
- One <App>Squad(BaseSquad) per application carries squad-level behaviour (before_step)