Team Expansion (Recursive Workspaces)

When a workspace is expanded into a team, it gains sub-workspaces while its own agent remains as the team lead (coordinator). This is recursive — sub-workspaces can themselves be expanded into teams, infinitely deep.

How It Works

When Developer PM is expanded into a team:

Business Core
   |
   +-- Developer PM (agent stays, becomes coordinator)
          |
          +-- Frontend Agent (sub-workspace, private scope)
          +-- Backend Agent  (sub-workspace, private scope)
          +-- QA Agent       (sub-workspace, private scope)

• Developer PM's agent still exists and acts as coordinator
• Developer PM receives incoming A2A messages from Business Core
• Developer PM's agent decides how to delegate to sub-workspaces
• Sub-workspaces talk to Developer PM and to each other (same level)
• Sub-workspaces cannot talk to Business Core or any workspace outside the team

Communication Rules

The team lead (Developer PM) is the only bridge between the team's internal world and the outside.

Scoped Registry

Sub-workspaces register in the platform registry but with a private scope. The registry knows about them but enforces access control.

Registry:
  Business Core      :8001   scope: public
  Developer PM       :8002   scope: public
  Frontend Agent     :8010   scope: private, parent=Developer PM
  Backend Agent      :8011   scope: private, parent=Developer PM
  QA Agent           :8012   scope: private, parent=Developer PM

• The platform can always discover any workspace (for provisioning, monitoring)
• The parent workspace can discover its sub-workspaces
• Sub-workspaces can discover their siblings (same parent)
• Outside workspaces get a 403 Forbidden if they try to discover a private sub-workspace

How to Expand

Expansion is triggered via POST /workspaces/:id/expand. The platform reads the sub_workspaces list from the workspace's config and provisions each one. On the canvas, users right-click a workspace node and select "Expand into team."

Collapsing is the inverse: POST /workspaces/:id/collapse. Sub-workspaces are stopped and removed.

What Happens on Expansion

When Developer PM is expanded into a team, the hierarchy changes but the outside view doesn't. Business Core's parent/child relationship to Developer PM is unaffected — Developer PM still responds to the same A2A endpoint.

The events fired:

• WORKSPACE_EXPANDED with the new sub_workspace_ids in the payload
• WORKSPACE_PROVISIONING for each new sub-workspace
• WORKSPACE_ONLINE for each sub-workspace as they come up

Communication rules are automatically derived from the new hierarchy — no manual wiring needed.

Canvas Behavior

• Children render as embedded mini-cards (TeamMemberChip) inside the parent node, not as separate canvas nodes
• Each mini-card shows full status: gradient bar, name, tier badge, skills pills, active tasks, descendant count
• Recursive rendering up to 3 levels deep (MAX_NESTING_DEPTH = 3) — sub-cards can contain their own "Team" sections
• Parent node dynamically resizes: 210-280px (no children), 320-450px (children), 400-560px (grandchildren)
• Eject button (sky-blue arrow icon) on hover extracts a child from the team
• "Extract from Team" also available in the right-click context menu
• Double-click a team node to zoom/fit to the parent area
• The parent workspace node shows a badge with total descendant count

Collapsing a Team

The inverse of expansion, triggered via POST /workspaces/:id/collapse:

1. Each sub-workspace agent wraps up current work and writes a handoff document to memory
2. Sub-workspaces are stopped and removed
3. The team lead's agent goes back to handling everything directly
4. A WORKSPACE_COLLAPSED event fires

Sub-workspace memory is cleaned up based on backend (see Memory — Cleanup).

Deleting a Team Workspace

When a team workspace is deleted:

1. Platform shows a warning listing all sub-workspaces that will be deleted
2. User can drag sub-workspaces out of the team before confirming (promotes them to the parent level)
3. On confirmation, cascade delete removes the parent and all remaining sub-workspaces
4. WORKSPACE_REMOVED events fire for each deleted workspace

Related Docs

• Communication Rules — Full access control model
• Core Concepts — Workspace fundamentals
• System Prompt Structure — How peer capabilities are injected
• Provisioner — How sub-workspaces are deployed
• Registry & Heartbeat — How registration works
• Event Log — Events fired during expansion
• Canvas UI — Visual behavior of teams