162 lines
6.3 KiB
Markdown
162 lines
6.3 KiB
Markdown
# 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
|