beadboard/docs/plans/2026-02-19-swarm-page-redesign.md

Swarm Page Redesign

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Replace label-based swarm grouping with proper bd swarm orchestration UI showing epic-level work coordination.

Architecture: Query bd swarm list/status/validate directly via new API routes. Swarm cards show computed progress from epic DAGs. Activity panel filters to selected swarm's epic children.

Tech Stack: Next.js API routes, existing BD CLI, reuse ActivityPanel and card patterns.

---

Background: How bd swarm Actually Works

NOT Labels

The current UI incorrectly uses swarm:* labels to group agents. bd swarm does NOT use labels.

How It Actually Works

Create:

bd swarm create <epic-id>

Creates a molecule bead with issue_type: "molecule" and mol_type: "swarm":

{
  "id": "codex-f4r",
  "title": "Swarm: Test Epic",
  "issue_type": "molecule",
  "mol_type": "swarm",
  "dependencies": [{ "id": "codex-dq9", "dependency_type": "relates-to" }]
}

Status (computed, not stored):

bd swarm status <epic-or-swarm-id> --json

Returns:

{
  "epic_id": "codex-dq9",
  "epic_title": "Test Epic",
  "completed": [...],
  "active": [...],    // in_progress issues
  "ready": [...],     // unblocked, open issues
  "blocked": [...],   // waiting on dependencies
  "progress_percent": 40
}

List:

bd swarm list --json

Returns:

{
  "swarms": [{
    "id": "codex-f4r",
    "title": "Swarm: Test Epic",
    "epic_id": "codex-dq9",
    "epic_title": "Test Epic",
    "status": "open",
    "coordinator": "",
    "total_issues": 5,
    "completed_issues": 2,
    "active_issues": 1,
    "progress_percent": 40
  }]
}

Validate:

bd swarm validate <epic-id> --verbose

Returns DAG quality, ready fronts, max parallelism.

---

Data Contract

GET /api/swarm/list

Returns bd swarm list --json output directly.

GET /api/swarm/status?epic=

Returns bd swarm status <epic> --json output.

POST /api/swarm/create

Body: { "epicId": "codex-dq9", "coordinator": "witness" (optional) } Returns created swarm molecule.

POST /api/swarm/close

Body: { "swarmId": "codex-f4r" } Closes the swarm molecule.

---

Page Layout

Existing structure (unified-shell.tsx) - no changes to layout:

┌─────────────────────────────────────────────────────────────────────┐
│  TOP BAR                                                            │
├──────────────┬────────────────────────────────┬─────────────────────┤
│  LEFT PANEL  │  MIDDLE CONTENT                │  RIGHT PANEL        │
│  (filters)   │  (SwarmPage cards)             │  (ActivityPanel)    │
│              │                                │  ← filter by swarm  │
│              │  [swarm cards grid]            │                     │
│              │                                │                     │
├──────────────┴────────────────────────────────┴─────────────────────┤
│  MOBILE NAV                                                         │
└─────────────────────────────────────────────────────────────────────┘

SwarmPage:

• Header with title + "Create Swarm" button
• Responsive cards grid (1-4 columns)
• Click card → sets swarmId in URL → right panel filters to that swarm

---

Swarm Card Design

┌─────────────────────────────────────┐
│  🐝 Swarm: Feature Auth             │  ← title from swarm molecule
│  codex-f4r                          │  ← swarm molecule ID
│  ─────────────────────────────────  │
│  Progress ████████░░░░ 40%          │  ← progress_percent
│  Epic: codex-dq9                    │  ← linked epic ID
│  ─────────────────────────────────  │
│  ✓ 2 completed                      │  ← completed count
│  ▶ 1 active                         │  ← in_progress count
│  ⏳ 2 ready                         │  ← unblocked, open
│  ⚠ 1 blocked                        │  ← waiting on deps
│  ─────────────────────────────────  │
│  Coordinator: (none)                │  ← optional coordinator
│  Last: 5 minutes ago                │  ← most recent update
└─────────────────────────────────────┘

Mini-DAG (optional, expandable):

• Show just the ready/front nodes as clickable badges
• "Ready to pick up: Task A, Task B"

---

Implementation Phases

Phase 1: API Layer

Files to create:

• src/app/api/swarm/list/route.ts - wraps bd swarm list --json
• src/app/api/swarm/status/route.ts - wraps bd swarm status <epic> --json
• src/app/api/swarm/create/route.ts - wraps bd swarm create <epic>
• src/app/api/swarm/close/route.ts - wraps bd close <swarm-id>

Pattern: Follow existing /api/beads/... routes. Use runBdCommand from src/lib/bridge.ts.

Phase 2: UI Layer

Files to modify:

• src/lib/swarm-cards.ts → replace with API calls or repurpose
• src/components/swarm/swarm-page.tsx → fetch from API, add create button
• src/components/swarm/swarm-card.tsx → new layout with status metrics

Files to create:

• src/components/swarm/create-swarm-dialog.tsx - form to create new swarm

Phase 3: Activity Filter

Files to modify:

• src/components/activity/activity-panel.tsx - add filterByEpicId?: string prop
• src/components/shared/unified-shell.tsx - pass epicId when swarm selected

Logic: When swarmId is set, look up the swarm's epic_id and pass to ActivityPanel.

Phase 4: Create Flow

Entry points:

1. Swarm page empty state → "Create Swarm" button
2. (Future) Epic detail page → "Create Swarm" action

Dialog:

• Dropdown to select epic (from bd list --type=epic)
• Optional: assign coordinator (from agent list)
• Submit → POST /api/swarm/create

---

Files Summary

New Files

• src/app/api/swarm/list/route.ts
• src/app/api/swarm/status/route.ts
• src/app/api/swarm/create/route.ts
• src/app/api/swarm/close/route.ts
• src/components/swarm/create-swarm-dialog.tsx

Modified Files

• src/lib/swarm-cards.ts - refactor for API data or deprecate
• src/components/swarm/swarm-page.tsx - use API, add create
• src/components/swarm/swarm-card.tsx - new card layout
• src/components/activity/activity-panel.tsx - add filter prop
• src/components/shared/unified-shell.tsx - wire epic filter

Tests

• tests/app/api/swarm/*.test.ts
• Update tests/components/swarm/*.test.tsx
• Update tests/lib/swarm-cards.test.ts

---

Success Criteria

1. Swarm page shows swarms from bd swarm list (not labels)
2. Cards display progress, active/ready/blocked counts
3. Clicking swarm filters ActivityPanel to epic children
4. "Create Swarm" dialog works from empty state
5. Existing tests updated, new tests for API routes
6. No swarm:* label usage in swarm page logic