Skip to content

Pipeline Plan 45

Jump to bottom
Seth Ford edited this page Feb 13, 2026 · 2 revisions

The plan.md file is write-protected by the pipeline system. Here's the complete implementation plan:

Dashboard Mission Control — Implementation Plan

Overview

Add a comprehensive mission control view to the Shipwright dashboard that lets users drill into any pipeline and see real-time team composition, individual agent terminals, file activity, and stage orchestration — powered by live tmux pane capture streamed over WebSocket.

Architecture Decisions

Terminal streaming: Use Bun's spawn to run tmux capture-pane at 500ms intervals and stream diffs over WebSocket. No xterm.js or node-pty dependency — keeps the zero-npm-dependency architecture. Frontend uses a lightweight ANSI-to-HTML converter.

Team discovery: Extend heartbeat JSON with role and pane_id fields. Server discovers team members by reading heartbeat files filtered by issue + cross-referencing tmux pane data via tmux list-panes.

No new dependencies: All changes use Bun built-ins. Frontend stays vanilla JS/CSS/HTML.

Files to Modify

File Changes
scripts/sw-heartbeat.sh Add --role and --pane-id options, include in JSON output
scripts/sw-pipeline.sh Pass --role and --pane-id when writing heartbeats
dashboard/server.ts New types (TeamMember, TeamTree, FileHeatmapEntry), new functions (getTeamTree, captureTmuxPane, getFileHeatmap), 3 new API routes, WebSocket subscription protocol, extend Pipeline with agentCount
dashboard/public/index.html Mission control overlay panel with team tree, terminal, stage bar, file heatmap, keyboard hints
dashboard/public/app.js ansiToHtml(), renderMissionControl(), renderTeamTree(), renderTerminal(), renderStageOrchestration(), renderFileHeatmap(), keyboard handler, fleet overview agent count badges
dashboard/public/styles.css Mission control grid layout, ANSI color classes, team tree, terminal, stage bar, file heatmap, keyboard hint bar
scripts/sw-heartbeat-test.sh Test cases for new --role and --pane-id options

Implementation Steps (16 steps)

Step 1: Extend heartbeat schema — add --role and --pane-id to sw-heartbeat.sh cmd_write()

Step 2: Server types + getTeamTree(issue) — reads heartbeats filtered by issue, enriches with role/pane, falls back to tmux pane discovery

Step 3: Server terminal capture — captureTmuxPane(paneId) using Bun.spawn(["tmux", "capture-pane", "-p", "-t", paneId]), plus streaming infra with Map<paneId, Set<WebSocket>>

Step 4: Server file heatmap — getFileHeatmap(issue) parses build logs for Edit/Write/Read patterns

Step 5: Server API routes — GET /api/pipeline/:issue/team, /terminal/:paneId, /files

Step 6: WebSocket protocol extension — client sends subscribe-terminal/unsubscribe-terminal/subscribe-team, server pushes terminal-data and team-update

Step 7: Extend fleet state — add agentCount to Pipeline interface and getFleetState()

Step 8: Frontend ANSI-to-HTML — supports SGR 30-37/40-47/90-97/100-107, bold/dim/underline, 256-color, reset

Step 9: Mission control HTML — full-page overlay with grid layout (stage bar top, team tree left, terminal center, file heatmap bottom, keyboard hints footer)

Step 10: Team tree component — vertical list with role icons, status dots, activity text, click-to-select

Step 11: Terminal viewer — tab bar per agent, ANSI-rendered content, auto-scroll with lock toggle, WebSocket subscription management on tab switch

Step 12: Stage orchestration bar — horizontal nodes (green=done, pulsing cyan=active, gray=pending, red=failed)

Step 13: File heatmap — compact badge row sorted by touch count, heat-gradient coloring

Step 14: Keyboard navigation — Esc (back), Tab (cycle agents), Enter (fullscreen), 1-9 (switch pipelines), p (pause), / (search)

Step 15: Fleet overview integration — agent count badges on pipeline cards, click opens mission control instead of side panel

Step 16: CSS — grid layout, ANSI colors, team tree connectors, terminal dark bg, stage pulse animation, heatmap gradient, keyboard hint bar

Task Checklist

  • Task 1: Extend sw-heartbeat.sh with --role and --pane-id options
  • Task 2: Add TeamMember/TeamTree/FileHeatmapEntry types and getTeamTree() to server.ts
  • Task 3: Add captureTmuxPane() + terminal streaming infra with WebSocket subscription management
  • Task 4: Add getFileHeatmap() function that parses build logs
  • Task 5: Add 3 REST API routes for team, terminal, and files
  • Task 6: Extend WebSocket protocol for terminal/team subscriptions
  • Task 7: Extend Pipeline interface and getFleetState() with agentCount
  • Task 8: Implement ANSI-to-HTML renderer in app.js
  • Task 9: Add mission control HTML structure to index.html
  • Task 10: Implement renderMissionControl(), renderTeamTree(), renderTerminal(), renderStageOrchestration(), renderFileHeatmap()
  • Task 11: Add keyboard navigation handler
  • Task 12: Modify fleet overview to show agent count and open mission control on click
  • Task 13: Add all mission control CSS styles
  • Task 14: Write heartbeat test cases in sw-heartbeat-test.sh
  • Task 15: Manual integration test end-to-end

Testing Approach

  1. Unit: Heartbeat test verifies --role/--pane-id write to JSON correctly
  2. API: Hit /api/pipeline/:issue/team, /terminal/:paneId, /files with running pipeline
  3. WebSocket: Verify terminal streaming updates on drill-down, tab switching unsubscribes/resubscribes
  4. Keyboard: All 6 shortcuts work in mission control view
  5. Regression: npm test passes all 22 existing suites

Definition of Done

  • Fleet overview shows agent count per pipeline
  • Click pipeline → full mission control drill-down
  • Team tree with roles, status, activity per agent
  • Live terminal per agent with ANSI color rendering
  • Stage orchestration bar with timing
  • File heatmap showing agent file touches
  • Keyboard shortcuts (Esc, Tab, Enter, 1-9)
  • Heartbeat extended with role/pane_id
  • 3 new API routes working
  • WebSocket terminal streaming
  • All existing tests pass
  • New heartbeat tests pass

Clone this wiki locally