beadboard/docs/plans/2026-02-12-beadboard-prd.md

BeadBoard Product Requirements Document (PRD)

Version: 1.1
Date: February 12, 2026
License: MIT

1. Product Summary

BeadBoard is a Windows-native web dashboard for Beads that provides a unified interface for Kanban planning, dependency visualization, timeline auditing, and agent-session tracking across multiple projects.

The app must run without WSL and without Unix-only shell assumptions. It reads Beads data directly from .beads/issues.jsonl and performs all mutations through bd.exe.

2. Problem Statement

Current Beads ecosystem tools are often Unix/macOS oriented, creating friction for Windows-native development flows. Users need:

• Native Windows path support (C:\..., D:\...)
• Multi-project visibility in one dashboard
• Real-time monitoring of agent activity
• A strict read/write boundary that preserves Beads/Dolt consistency

3. Goals

• Build a modern dashboard on Next.js 15 + React 19 + TypeScript
• Use .beads/issues.jsonl as source of truth for reads
• Use bd.exe exclusively for writes (create, update, close, comment, reopen)
• Provide real-time updates via file watching + SSE
• Support multi-project workflows across Windows-native paths

4. Non-Negotiable Constraints

• Stack: Next.js 15, React 19, TypeScript (strict)
• Platform: Windows native (no WSL assumptions)
• Reads: parse .beads/issues.jsonl directly
• Writes: must route through bd.exe via child_process.execFile
• Never write directly to issues.jsonl
• License: MIT

5. Architecture

5.1 Frontend

• React 19 UI with Tailwind
• Views: Kanban, Dependency Graph, Timeline, Agent Sessions
• State: React Query (server/cache) + Zustand (UI state, optimistic UI state coordination)

5.2 Backend (Next.js App Router API)

• Read layer: Node fs + JSONL parser
• Watch layer: chokidar on project .beads files
• Transport: Server-Sent Events (SSE) for one-way real-time updates
• Write layer: child_process.execFile wrapper over bd.exe

5.3 Path and Project Handling

• Project root for this repo: C:\Users\Zenchant\codex\beadboard
• User project registry stored in profile path: %USERPROFILE%\\.beadboard\\projects.json
• Normalize paths with Windows-safe utilities before comparison/storage
• Display paths in readable normalized form while preserving canonical behavior

6. Approved Product Decisions

• Graph library: React Flow (faster delivery for interactive DAG use cases)
• Mutation scope in phase 1: include comments and reopen in addition to create/update/close
• Demo clip is reference-only (not a runtime mode)
• Auto-scan policy:
  • Default: auto-scan %USERPROFILE% and user-added roots
  • Optional: explicit “scan all drives” action for broader discovery

7. Core Functional Requirements

7.1 Kanban Board

• Status columns: open, in_progress, blocked, deferred, closed
• Card metadata: id, priority, type, labels, assignee, dependency count
• Detail panel with full bead metadata
• Search/filter by text, type, priority, label

7.2 Multi-Project Support

• Register/remove project roots
• Discover .beads directories under approved scan roots
• Switch between per-project and aggregate views

7.3 Real-Time Updates

• Watch issues.jsonl changes with debounce
• Publish change events via SSE
• Client auto-reconnect and query invalidation on relevant updates

7.4 Dependency Graph

• Parse dependency edges (blocks, parent, relates_to, duplicates, supersedes)
• Render interactive graph with pan/zoom/select
• Highlight blocked chains and flag cycles/anomalies

7.5 Timeline / Activity Feed

• Derive timeline events from snapshots + updates
• Group chronologically
• Filter by project, agent/session, and event type

7.6 Agent Session View

• Group issues by closed_by_session, assignee, created_by
• Display claimed/completed/open outcomes per session

7.7 CLI Write-Back

• Mutations must execute bd.exe in target project CWD
• Supported operations:
  • Create bead
  • Update bead fields/status
  • Close bead with reason
  • Reopen bead
  • Add comment
• Optimistic UI updates with rollback on CLI failure

8. Data Handling Requirements

• Input format: JSONL (one object per line)
• Ignore blank lines
• Skip malformed JSON lines safely
• Apply defaults:
  • status = open when absent
  • issue_type = task when absent
  • priority = 2 when absent (0 is valid and must be preserved)
• Exclude tombstone from standard views unless explicitly requested

9. Quality, Reliability, and Safety

• Strict read/write boundary tests must verify no direct JSONL write path exists
• Graceful handling for:
  • File locks/transient read failures
  • Missing bd.exe
  • Command failures with actionable errors
• All logic must remain Windows-safe and avoid Unix-only assumptions

10. Performance Targets

• Startup/render readiness target: < 2s (local dev expectation)
• Parse performance target: < 100ms for 1000 beads
• Live update propagation target: < 500ms from file change to UI refresh
• Scan performance: practical defaults with bounded recursion and ignore rules

11. Scope by Priority

P0

• Foundation, schema/types, path normalization
• JSONL read layer and API
• Registry + scanner
• Watcher + SSE

P1

• Kanban UI
• CLI mutation bridge and APIs (including comments/reopen)
• Optimistic update/rollback
• Hardening + test coverage for boundaries

P2

• Timeline
• Dependency Graph
• Agent Session views

12. Out of Scope (Initial Release)

• Full-drive auto-scan by default
• WebSocket transport
• Direct DB replacement for JSONL source of truth
• Any direct write to .beads/issues.jsonl

13. Risks and Mitigations

• Risk: stale/partial views during rapid CLI writes
  Mitigation: debounce + SSE invalidation + eventual re-read reconciliation
• Risk: path mismatch across different Windows forms
  Mitigation: centralized normalization and canonical path keys
• Risk: CLI output format drift
  Mitigation: tolerant parsing and startup version checks

14. Acceptance Criteria (System-Level)

• Runs natively on Windows PowerShell/CMD without WSL
• Reads from .beads/issues.jsonl successfully for registered projects
• All writes performed via bd.exe and reflected back via watcher/SSE
• Kanban, Timeline, Graph, and Agent Session views function against real bead data
• No direct issues.jsonl write implementation exists in app code