beadboard/docs/plans/2026-02-20-swarm-view-remake-design.md

Swarm View Remake - Product Requirements Document (PRD)

Overview

The goal is to completely remake the Beadboard "Swarm" view (/view=swarm) into a powerful, command-center style workspace. The current flat grid of mission cards will be replaced with a deep, context-aware interface that integrates with the Gastown/Beads orchestration model, introducing the concepts of Agent Archetypes and Swarm Templates.

This document serves as the comprehensive technical specification for implementation.

---

1. Core Concepts & Data Models

1.1 Agent Archetypes

Archetypes define specialized roles that worker agents (Polecats) can adopt.

• Storage Path: .beads/archetypes/*.json (Git-tracked alongside the project).
• Seeding: The application must check for the existence of this directory on startup (or via a specific API route). If empty, it must create the directory and write default archetypes (e.g., architect.json, reviewer.json, implementer.json).
• Data Interface (src/lib/types-swarm.ts):

  export interface AgentArchetype {
    id: string; // The filename without .json (e.g., 'architect')
    name: string; // Display name (e.g., 'Software Architect')
    description: string;
    systemPrompt: string; // The core behavioral instructions
    capabilities: string[]; // e.g., ['planning', 'code_review']
    color: string; // e.g., 'primary', 'destructive', 'warn', etc.
    createdAt: string; // ISO timestamp
    updatedAt: string; // ISO timestamp
    isBuiltIn: boolean; // True if seeded by default, false if user-created
  }
  

1.2 Swarm Templates

Templates define mission blueprints—a preset team composition and standard workflow.

• Storage Path: .beads/templates/*.json.
• Seeding: Similar to archetypes, provide robust defaults (e.g., feature-sprint.json, bug-blitz.json).
• Data Interface (src/lib/types-swarm.ts):

  export interface SwarmTemplate {
    id: string; // The filename without .json
    name: string; // Display name
    description: string;
    team: {
      archetypeId: string; // Must match an AgentArchetype.id
      count: number;
    }[];
    protoFormula?: string; // Optional: Maps to a `bd` formula name (e.g., 'release')
    createdAt: string;
    updatedAt: string;
    isBuiltIn: boolean;
  }
  

---

2. API Contracts & Backend Architecture

The UI needs a robust Next.js API layer to manage these new files and interface with the CLI. All routes should be under src/app/api/swarm/.

2.1 Archetypes API (/api/swarm/archetypes)

• GET: Returns AgentArchetype[]. Reads all .json files from .beads/archetypes/.
• POST: Creates a new archetype. Validates payload, writes to .beads/archetypes/{id}.json.
• PUT /🆔 Updates an existing archetype.
• DELETE /🆔 Deletes an archetype (prevent deletion if isBuiltIn is true).

2.2 Templates API (/api/swarm/templates)

• GET: Returns SwarmTemplate[]. Reads from .beads/templates/.
• POST, PUT, DELETE: Standard CRUD mirroring Archetypes.

2.3 Orchestration API (/api/swarm/orchestration)

• POST /launch:
  • Payload: { templateId: string, missionName: string, projectRoot: string }
  • Action: Reads the template. If protoFormula exists, executes bd mol pour <protoFormula> --title <missionName>. If no formula, executes bd create epic <missionName>. Then executes gt sling or equivalent to assign the specific roster to the new Epic.
  • Response: The new Epic ID to immediately select in the UI.

---

3. Frontend Architecture & Component Structure

The current src/components/swarm/swarm-page.tsx will be completely replaced. The new architecture pushes state down into specialized components.

3.1 Shell Integration (src/components/shared/unified-shell.tsx)

The UnifiedShell must dynamically alter its layout based on the active view.

• When view === 'swarm':
  • Left Panel: Do NOT render the standard Epic Tree. Render <SwarmMissionPicker />.
  • Middle Column: Render <SwarmWorkspace />.
  • Right Panel: Remain as the <ActivityPanel /> (Agent pool monitor).

3.2 The Swarm Workspace (src/components/swarm/swarm-workspace.tsx)

The main container for the middle column. Manages the active sub-tab state.

// State: activeTab: 'operations' | 'archetypes' | 'templates'
<div className="swarm-workspace">
  <SwarmWorkspaceNav activeTab={activeTab} onTabChange={setTab} />
  
  {activeTab === 'operations' && <SwarmOperationsmissionId={selectedMissionId} />}
  {activeTab === 'archetypes' && <ArchetypesArmory />}
  {activeTab === 'templates' && <TemplatesManager />}
</div>

---

4. UI/UX Details by Sub-Tab

4.1 Left Panel: <SwarmMissionPicker />

A dense, scannable list replacing the left panel.

• Fetches epics (like the current useMissionList hook).
• Row Design:
  • [Health Dot] [Mission Title] (ID)
  • A micro-progress bar underneath the title.
• Interaction: Clicking sets the swarmId URL param and automatically switches the SwarmWorkspace to the 'operations' tab.

4.2 Tab 1: <SwarmOperations /> (The Operations Command Center)

This view only renders if a mission (Epic) is selected. It completely replaces the redundant Graph view with a focused, control-oriented dashboard for agent orchestration.

• Header Section:
  • Mission Title, Epic ID, and overall health status.
  • Action Strip: Buttons for "Summon Polecats" (assign agents based on a template), "Halt Swarm", and "Run Debrief".
• Convoy Stepper: The visual orchestration pipeline (Planning -> Deployment -> Execution -> Debrief).
• The Telemetry Grid (Hybrid Layout):
  • Top/Left Pane (Specialized Agent DAG): Unlike the generic global graph, this graph specifically visualizes who is doing what. Nodes should emphasize Agent Avatars and archetype colors. Edges should represent the flow of work between agents (e.g., Coder -> Reviewer) rather than just raw task dependencies.
  • Bottom/Right Pane (Metrics & Attention):
    • Priority Attention (What is blocked?): A highly focused feed of only the blocked beads or beads that require Human-In-The-Loop (HITL) intervention for this specific mission.
    • Mission Roster: A quick summary of active agents.

4.3 Tab 2: <ArchetypesArmory />

• Layout: CSS Grid of archetype cards.
• Card Design: Shows Name, Color badge, Capabilities tags, and truncated description.
• Interaction:
  • Cards are highly interactive. Clicking a card opens a central popup (reusing the app's existing Dialog/Popup pattern) to edit the metadata.
  • Includes a focused text area to edit the raw systemPrompt.
  • A primary "Create New Archetype" button exists at the top.

4.4 Tab 3: <TemplatesManager />

• Layout: List or Grid view of templates.
• Interaction:
  • Cards are highly interactive. Clicking a card opens a central <TemplateEditor /> popup.
  • Key UI Feature: An intuitive interface to build the team array (e.g., click "Add Role", select "Architect" from the Archetypes list, set count to "1").
  • A primary "Create New Template" button exists at the top.

---

5. Engine Integration & Visual Hooks

Raw terminal panes are rejected. Orchestration must feel native to the React application.

5.1 The Convoy Stepper (<ConvoyOrchestrationStepper />)

When <LaunchSwarmDialog /> is submitted, a prominent overlay or banner appears in the Operations view:

• Phase 1: Planning. (Spinning) -> API calls bd mol pour -> (Check)
• Phase 2: Graph Generation. (Spinning) -> UI polls API for new beads -> (Check)
• Phase 3: Deployment. (Spinning) -> API calls gt sling -> (Check)
• The stepper fades out after 3 seconds of full completion, revealing the live DAG.

5.2 Responsive Graph Expansion

The Graph view in the Operations tab must smoothly handle rapid influxes of nodes (which happens when a template is poured). The physics simulation (if applicable) or layout engine should be robust enough to handle ~20-50 nodes appearing simultaneously without throwing errors or causing heavy layout thrashing.

---

6. Implementation Phasing Strategy

To avoid massive, monolithic PRs, implementation should follow this order:

1. Phase 1: Data Layer & API. Implement src/lib/types-swarm.ts, the seed logic, and the CRUD API routes for Archetypes and Templates.
2. Phase 2: Shell Routing & Sub-tabs. Update UnifiedShell to intercept the Swarm view, implement the SwarmMissionPicker for the left panel, and scaffold the empty 3 sub-tabs.
3. Phase 3: Armory & Templates UI. Build out the CRUD interfaces for Archetypes and Templates.
4. Phase 4: The Operations Dashboard. Build the complex detail view, integrating the existing graph components and agent roster.
5. Phase 5: Orchestration (The glue). Hook up the "Launch" button to the new templates, implement the ConvoyStepper, and wire the API to bd and gt.