feat(swarm): implement Swarm View remake with Operations, Archetypes, and Templates

This commit includes the new SwarmWorkspace with its 3 sub-tabs, the LeftPanel mission picker, and the comprehensive Operations Command Dashboard featuring the live interactive DAG telemetry and task assignment prep flow.
2026-02-20 22:19:38 -08:00 · 2026-02-20 22:19:38 -08:00 · dfaf523029
commit dfaf523029
parent 409a7e7256
74 changed files with 11066 additions and 2046 deletions
--- a/docs/plans/2026-02-19-swarm-page-redesign.md
+++ b/docs/plans/2026-02-19-swarm-page-redesign.md
@ -0,0 +1,224 @@
+# 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:**
+```bash
+bd swarm create <epic-id>
+```
+Creates a **molecule bead** with `issue_type: "molecule"` and `mol_type: "swarm"`:
+```json
+{
+  "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):**
+```bash
+bd swarm status <epic-or-swarm-id> --json
+```
+Returns:
+```json
+{
+  "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:**
+```bash
+bd swarm list --json
+```
+Returns:
+```json
+{
+  "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:**
+```bash
+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=<epic-id>
+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
--- a/docs/plans/2026-02-19-visual-truth-spec.md
+++ b/docs/plans/2026-02-19-visual-truth-spec.md
@ -0,0 +1,96 @@
+# Visual Truth Spec (Command Grid + Thread Takeover)
+
+## Source Of Truth
+- Target A: Command Grid shell screenshot.
+- Target B: Open thread takeover screenshot.
+- Current app screenshots are validation artifacts only.
+
+## Geometry Contract (Desktop)
+- App viewport composition:
+  - Top bar height: `60px`
+  - Main region: `calc(100vh - 60px)`
+- Columns:
+  - Left rail: `256px`
+  - Center: fluid
+  - Right rail: `332px`
+- Dividers:
+  - 1px hard separators between rails/center.
+- Center content max width:
+  - `1080px` on 1920 viewport.
+  - `960px` on 1440 viewport.
+
+## Top Bar Contract (Target A)
+- Left brand block:
+  - Icon tile `32x32`, label stack (`COMMAND GRID`, version line).
+- Metric tiles (equal height, hard borders):
+  - `TOTAL TASKS`, `CRITICAL ALERTS`, `IDLE`, `BUSY`.
+- Primary actions:
+  - `BLOCKED ITEMS` outlined red pill.
+  - `NEW TASK` filled green pill.
+- No tab switcher in top bar.
+
+## Left Rail Contract (Target A)
+- Header text: `NAVIGATION / EPICS` mono smallcaps.
+- Epic tree rows:
+  - 36px row rhythm.
+  - Nested children at +16px indent.
+- Footer user identity block anchored bottom.
+
+## Center Feed Contract (Target A)
+- Section headers:
+  - `READY`, `IN PROGRESS`, `BLOCKED`, mono uppercase with count chips.
+- Cards:
+  - Radius `14px`, panel fill darker than shell.
+  - Header row: status chip, priority, title, id.
+  - Summary text 2-3 lines.
+  - Dependency sub-panel for `BLOCKED BY` / `UNBLOCKS`.
+  - Assignee row with avatar.
+  - Footer with stage text + compact actions.
+
+## Right Rail Contract (Target A)
+- Upper block:
+  - `AGENT POOL MONITOR` with compact rows.
+- Lower block:
+  - `ACTIVITY / BLOCKERS FEED` timeline rows.
+- Single vertical divider between center and rail.
+
+## Thread Takeover Contract (Target B)
+- Center takeover frame:
+  - Max width `1120px`, radius `12px`.
+- Header strip:
+  - Task id, status, title, edit/close actions.
+- Summary row:
+  - Summary text + assignee + due date columns.
+- Conversation area:
+  - Left incoming / right outgoing bubbles.
+- Composer bar:
+  - Sticky bottom, rounded input + send CTA.
+
+## Palette / Type Contract
+- Base backgrounds:
+  - app `#070d16`
+  - shell `#0c1420`
+  - panel `#111c2a`
+  - card `#1a2431`
+- Text:
+  - primary `#e8edf5`
+  - muted `#8f9caf`
+- Accents:
+  - ready `#35d98f`
+  - blocked `#ff4c72`
+  - warning `#ffb24a`
+  - info `#35c9ff`
+- Font stack:
+  - Sans: `Inter, Segoe UI, system-ui, sans-serif`
+  - Mono: `JetBrains Mono, Cascadia Code, monospace`
+
+## Breakpoint Contract
+- Desktop: `>= 1280px` full 3-column shell.
+- Tablet: `768px-1279px` collapsible rails.
+- Mobile: `< 768px` bottom nav + full-screen takeover.
+
+## Acceptance
+- Pixel-close to target hierarchy and rhythm at:
+  - `1920x1080`
+  - `1440x1024`
+  - `390x844`
--- a/docs/plans/2026-02-20-swarm-view-remake-design.md
+++ b/docs/plans/2026-02-20-swarm-view-remake-design.md
@ -120,23 +120,24 @@ This view only renders if a mission (Epic) is selected. It completely replaces t
    *   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 (Replacing the DAG):**
-    *   **Card 1: Active Roster (Who is here?):** A list of all agents currently assigned to tasks within this epic. Displays their Name, Avatar (colored by Archetype), current Bead ID, and status (e.g., "Writing Code", "Waiting for API").
-    *   **Card 2: Priority Attention (What is blocked?):** A focused feed of *only* the `blocked` beads or beads that require Human-In-The-Loop (HITL) intervention for this specific mission.
-    *   **Card 3: Mission Metrics:** Simple burn-down stats or a mini-feed of the last 5 completed tasks to show velocity.
+*   **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 `<ArchetypeEditor />` sheet/modal to edit the metadata.
+    * 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 `<TemplateEditor />` sheet/modal.
+    * 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.