Skip to content

Guided tour

FabrCore 2.0 · Release and package availability

These guides track the current 2.0 source. Stable 2.0.0 publication is pending; package commands show the release target. Until it is published, follow the source quick start or use a matching available prerelease set. Release migration · Runtime modes

MODULE 07 · LESSON 7.3

Coordinate a Surface squad

Coordinate a squad when the application owns the workflow.

Lesson 41 of 86 · FabrCore 2.0

Overview

A Surface squad is a blueprint-defined operating model with an orchestrator and task agents. The host coordinates the work; a harness lets a model manage its own plan. A squad member can still use a harness internally without confusing who owns the overall task state.

A squad adds a coordination model

A Surface squad describes members and how their work is coordinated. An orchestrator-centered squad and a task-oriented squad have different operating semantics, so choose the type that fits the workflow instead of copying arbitrary member lists. The Surface blueprint expander turns that extension into runtime definitions the Host can provision.

The extension must survive every editor

A generic blueprint editor may understand the agents array but not every squad field. Preserve unknown extension JSON when exporting, cloning or saving; otherwise a routine edit can silently remove the coordination contract. A preview needs the installed expander to describe the resulting members before deployment.

Define the cooperating squad

  1. Add a squads extension using a supported squad type and explicit member definitions. Preserve the rest of the canonical blueprint.
  2. Apply with the Surface expander registered and inspect its effect-free preview. Open the squad workspace to observe task state and results.
  3. Exercise a failed member and cancellation, then inspect how the orchestrator reports partial completion.
surface-blueprint-squads-example.json 
{
  "name": "support-workspace",
  "version": "2026-06-08",
  "agents": [],
  "squads": [
    {
      "squadType": "task",
      "name": "Ops Desk",
      "description": "Coordinates operational support work.",
      "orchestratorModel": "default",
      "forceReconfigure": false,
      "taskOptions": {
        "workerModelName": "default",
        "delegationTimeoutSeconds": 120,
        "maxLoopIterations": 10
      },
      "agents": [
        {
          "name": "data-intel",
          "agentType": "data-intel-agent",
          "models": "default",
          "description": "Answers data questions for the squad.",
          "role": "executor",
          "plugins": [],
          "tools": []
        }
      ]
    }
  ]
}

Inspect the expanded members and one failure

  1. Preview the supplied squad definition with the Surface extension registered. Identify the coordinator/member handles produced by expansion before applying it.
  2. Open the squad workspace and run a fixture investigation. Observe which member owns each step and how its result reaches the coordinator or task view.
  3. Make one member fail in a test. Confirm the squad reports partial work and retains the member failure instead of turning the remaining members' success into an unconditional “complete.”

The useful outcome is visible coordination with attributable member results. The squad is more than a visual grouping of agents.

If the result is different

A collection of agents is not automatically a squad. Verify the extension, type and registration rather than assuming a harness roster creates squad UI.

Go deeper

Explore the related documentation.