chore: initialize beadboard baseline
This commit is contained in:
zenchantlive
commit
292a72f861
30 changed files with 2983 additions and 0 deletions
162
docs/plans/2026-02-12-beadboard-prd.md
Normal file
162
docs/plans/2026-02-12-beadboard-prd.md
Normal file
|
|
@ -0,0 +1,162 @@
|
|||
# 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue