feat: Squads — multi-agent routing with leader delegation

[OneStepAt4time]

Squads — Multi-Agent Routing with Leader Delegation

Why

Teams want to assign work to groups, not individuals. @FrontendTeam instead of picking an agent manually. The leader agent decides who picks it up based on availability and expertise. This is the #1 feature Multica has that we do not.

Concept

• A Squad is a group of agents (+ optional humans) under a leader agent
• Work is assigned to the squad, not to an individual agent
• The leader agent receives the assignment and delegates to the best-fit member
• Squad members can be agents or humans (human members get notified)
• Squads have their own instructions/context for the leader

DB Schema

CREATE TABLE squad (
  id TEXT PRIMARY KEY,
  workspace_id TEXT NOT NULL,
  name TEXT NOT NULL,
  description TEXT NOT NULL DEFAULT '',
  instructions TEXT NOT NULL DEFAULT '',  -- leader agent instructions
  leader_agent_key TEXT NOT NULL,  -- references agent config key
  created_at TEXT NOT NULL DEFAULT (datetime('now')),
  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
  UNIQUE(workspace_id, name)
);

CREATE TABLE squad_member (
  id TEXT PRIMARY KEY,
  squad_id TEXT NOT NULL REFERENCES squad(id) ON DELETE CASCADE,
  member_type TEXT NOT NULL CHECK(member_type IN ('agent', 'user')),
  member_id TEXT NOT NULL,
  role TEXT NOT NULL DEFAULT '',
  created_at TEXT NOT NULL DEFAULT (datetime('now')),
  UNIQUE(squad_id, member_type, member_id)
);

Dispatch Flow

1. User assigns issue/task to squad
2. Leader agent receives prompt: "You are the leader of squad [name]. Members: [list]. A new task arrived: [description]. Which member should handle this?"
3. Leader responds with member selection + rationale
4. System dispatches task to selected member agent
5. Member executes, reports back
6. Leader can re-assign if member fails

API Endpoints

• GET /v1/squads — list squads
• POST /v1/squads — create squad
• GET /v1/squads/:id — get squad details
• PUT /v1/squads/:id — update squad
• DELETE /v1/squads/:id — delete squad
• POST /v1/squads/:id/members — add member
• DELETE /v1/squads/:id/members/:memberId — remove member
• POST /v1/squads/:id/dispatch — assign work to squad (triggers leader delegation)

Frontend

• Squads page: list view with name, leader, member count, status
• Squad detail page: members list, instructions editor, dispatch history
• Create squad dialog: pick leader agent, add members
• Assignment integration: squad appears in assignee picker alongside agents

Acceptance Criteria

• CRUD API for squads and members
• Dispatch endpoint that triggers leader delegation
• Leader agent prompt construction with squad context
• Member selection and task forwarding
• Dashboard squads page with list/detail/create views
• Squad appears as assignee option in session/issue workflows
• Tests for dispatch flow
• npm run gate passes

Reference

Competitive analysis: references/multica-competitive-analysis.md §2.1
Inspired by Multica Squads (concepts only, our own implementation)

[OneStepAt4time]

🚧 Blocked by: #3970 (Task Queue) — foundational state machine required before this feature can be implemented.