viktor/beadboard
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

chore: initialize beadboard baseline

Browse source
This commit is contained in:
zenchantlive 2026-02-11 17:42:51 -08:00
commit 292a72f861
30 changed files with 2983 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

260
docs/plans/2026-02-12-beadboard-implementation-plan.md Normal file
View file

@ -0,0 +1,260 @@
# BeadBoard Implementation Plan
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
**Goal:** Build a Windows-native Beads dashboard that reads `.beads/issues.jsonl` directly and performs all mutations through `bd.exe`.
**Architecture:** The app uses Next.js App Router APIs for filesystem reads, project scanning, watcher lifecycle, SSE broadcasting, and CLI mutation bridging. Frontend uses React Query for server-state synchronization and Zustand for UI-local state plus optimistic transition coordination. Windows path normalization is centralized and enforced at all boundaries to prevent cross-drive and casing inconsistencies.
**Tech Stack:** Next.js 15, React 19, TypeScript (strict), Tailwind CSS, Zustand, TanStack Query, chokidar, React Flow, `child_process.execFile`.
---
### Task 1: Repository Bootstrap and Runtime Guardrails
**Files:**
- Create: `package.json`
- Create: `tsconfig.json`
- Create: `next.config.ts`
- Create: `LICENSE`
- Create: `src/app/layout.tsx`
- Create: `src/app/page.tsx`
**Step 1: Write failing environment checks**
- Add a smoke test placeholder for app boot and runtime config verification.
**Step 2: Run verification to confirm missing implementation**
- Run: `npm run test` (expected to fail before setup).
**Step 3: Implement minimal app bootstrap**
- Initialize Next.js 15 + React 19 + TypeScript strict setup.
- Add MIT license file.
**Step 4: Re-run checks**
- Run: `npm run lint` and `npm run typecheck`.
**Step 5: Commit**
- Commit message: `chore: bootstrap beadboard foundation`
### Task 2: Canonical Types and JSONL Parser
**Files:**
- Create: `src/lib/types.ts`
- Create: `src/lib/parser.ts`
- Create: `tests/lib/parser.test.ts`
**Step 1: Write failing parser tests**
- Cover defaults, malformed lines, tombstone filtering, `priority=0` preservation.
**Step 2: Run targeted test**
- Run: `npm run test -- tests/lib/parser.test.ts` (expected fail).
**Step 3: Implement parser + DTO normalization**
- Parse one JSON object per line, skip malformed lines, apply defaults.
**Step 4: Run tests**
- Run parser tests and full typecheck.
**Step 5: Commit**
- Commit message: `feat: add beads schema and robust jsonl parser`
### Task 3: Windows Pathing + Project Registry
**Files:**
- Create: `src/lib/pathing.ts`
- Create: `src/lib/projects-registry.ts`
- Create: `src/app/api/projects/route.ts`
- Test: `tests/lib/pathing.test.ts`
**Step 1: Write failing path tests**
- Validate canonicalization for `C:\` and `D:\`, stable key generation.
**Step 2: Implement path utility + registry persistence**
- Use `%USERPROFILE%\\.beadboard\\projects.json` as registry location.
**Step 3: Implement API route**
- Support add/list/remove with validation and normalized identity.
**Step 4: Verify**
- Run path tests + API handler tests.
**Step 5: Commit**
- Commit message: `feat: add windows path normalization and project registry`
### Task 4: Read API and Multi-Project Aggregation
**Files:**
- Create: `src/app/api/beads/route.ts`
- Create: `src/lib/read-service.ts`
- Test: `tests/api/beads-route.test.ts`
**Step 1: Write failing API tests**
- Single project read, aggregate read, filter params, error behavior.
**Step 2: Implement read service**
- Read `.beads/issues.jsonl` directly via `fs`.
**Step 3: Implement route layer**
- Query support for project, status, type, priority, assignee, label.
**Step 4: Verify**
- Run route tests and typecheck.
**Step 5: Commit**
- Commit message: `feat: add beads read api for single and aggregate views`
### Task 5: Scanner and Discovery Controls
**Files:**
- Create: `src/lib/scanner.ts`
- Create: `src/app/api/scan/route.ts`
- Test: `tests/lib/scanner.test.ts`
**Step 1: Write failing scanner tests**
- Depth limits, ignore patterns, profile-root default behavior.
**Step 2: Implement scanner**
- Default root `%USERPROFILE%`, plus user-added roots.
- Add explicit full-drive mode action.
**Step 3: Implement scan API**
- Trigger scan + return discovered project candidates.
**Step 4: Verify**
- Run scanner tests.
**Step 5: Commit**
- Commit message: `feat: add windows-safe project scanner and scan api`
### Task 6: Watcher + SSE Event Bus
**Files:**
- Create: `src/lib/watcher.ts`
- Create: `src/lib/sse-bus.ts`
- Create: `src/app/api/events/route.ts`
- Test: `tests/lib/watcher.test.ts`
**Step 1: Write failing watcher tests**
- Debounced change emission, lock retry behavior, multi-project handling.
**Step 2: Implement watcher manager**
- Chokidar watchers for registered projects.
**Step 3: Implement SSE endpoint**
- Heartbeat, reconnect-safe events, project-scoped payloads.
**Step 4: Verify**
- Run watcher/event tests.
**Step 5: Commit**
- Commit message: `feat: add live file watching and sse updates`
### Task 7: bd.exe Mutation Bridge + API
**Files:**
- Create: `src/lib/bd-bridge.ts`
- Create: `src/app/api/mutate/route.ts`
- Test: `tests/lib/bd-bridge.test.ts`
**Step 1: Write failing bridge tests**
- Command invocation, cwd routing, stdout/stderr error mapping.
**Step 2: Implement execFile bridge**
- Resolve `bd.exe` from PATH, enforce project CWD, parse outputs.
**Step 3: Implement mutate API**
- `create`, `update`, `close`, `reopen`, `comment` actions.
**Step 4: Verify**
- Run bridge tests and mutation route tests.
**Step 5: Commit**
- Commit message: `feat: add bd cli mutation bridge and api`
### Task 8: Frontend State and Realtime Sync
**Files:**
- Create: `src/lib/query-client.ts`
- Create: `src/lib/store.ts`
- Create: `src/lib/sse-client.ts`
- Modify: `src/app/layout.tsx`
**Step 1: Write failing state tests**
- Query invalidation + optimistic rollback cases.
**Step 2: Implement Query + Zustand providers**
- Distinguish server cache from UI-local state.
**Step 3: Implement SSE client integration**
- Auto reconnect and scoped invalidation for changed projects.
**Step 4: Verify**
- Run state/integration tests.
**Step 5: Commit**
- Commit message: `feat: wire react-query zustand and realtime invalidation`
### Task 9: Feature Views (Kanban, Graph, Timeline, Sessions)
**Files:**
- Create: `src/components/kanban/*`
- Create: `src/components/graph/*`
- Create: `src/components/timeline/*`
- Create: `src/components/agents/*`
- Create: `src/app/graph/page.tsx`
- Create: `src/app/timeline/page.tsx`
- Create: `src/app/agents/page.tsx`
**Step 1: Write failing UI tests**
- Column rendering, card detail open, graph node interaction, timeline grouping.
**Step 2: Implement Kanban baseline**
- Columns, card metadata, details panel, filters/stats.
**Step 3: Implement Graph with React Flow**
- Edges from dependencies, pan/zoom/select, blocked-chain highlighting.
**Step 4: Implement Timeline + Session views**
- Derived activity and session grouping/metrics.
**Step 5: Verify**
- Run component tests and visual smoke check.
**Step 6: Commit**
- Commit message: `feat: deliver dashboard views for kanban graph timeline and sessions`
### Task 10: Quality Gates and Boundary Enforcement
**Files:**
- Create: `tests/guards/no-direct-jsonl-write.test.ts`
- Create: `docs/architecture/read-write-boundary.md`
- Modify: `package.json`
**Step 1: Write failing guard test**
- Detect direct writes to `.beads/issues.jsonl` in application code.
**Step 2: Implement boundary guard tooling**
- Add CI script and local verification command.
**Step 3: Add performance checks**
- Parser benchmark and SSE latency smoke measurements.
**Step 4: Verify full pipeline**
- Run `npm run lint && npm run typecheck && npm run test`.
**Step 5: Commit**
- Commit message: `chore: enforce read-write boundaries and quality gates`
## Execution Sequence and Parallelization
- Sequential core chain: Task 1 -> Task 2 -> Task 3 -> Task 4 -> Task 6 -> Task 7 -> Task 8
- Parallel branch A (after Task 3): Task 5
- Parallel branch B (after Task 4 and Task 8): Task 9
- Final gate: Task 10
## Completion Criteria
- Windows-native workflow validated in PowerShell/CMD
- Reads from JSONL only
- Mutations executed only via `bd.exe`
- Real-time updates delivered via SSE
- Kanban, Graph, Timeline, Agent Session views functional
- Boundary guard test prevents direct JSONL writes

162
docs/plans/2026-02-12-beadboard-prd.md Normal file
View 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

226
docs/plans/2026-02-12-parallel-agent-dispatch.md Normal file
View file

@ -0,0 +1,226 @@
# BeadBoard Parallel Agent Dispatch Plan
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
**Goal:** Run the next BeadBoard implementation phase in parallel with low merge risk, while preserving strict read/write boundaries (`issues.jsonl` read-only, writes only through `bd.exe`).
**Architecture:** Split work by subsystem with clear file ownership: registry persistence + API, scanner, and Kanban UI baseline. Keep each agent on dependency-safe beads and synchronize through an integration lead at checkpoints.
**Tech Stack:** Next.js 15, React 19, TypeScript strict, Node `fs`, Windows path utilities, React Query, Zustand.
---
## Parallelization Model
### Agent Roles
1. **Agent A (Registry/API Track)**
- Primary beads: `bb-6aj.1`, then `bb-6aj.2`
- Scope: profile-scoped project registry + API endpoints for add/remove/list
- Files expected:
- `src/lib/registry.ts`
- `src/app/api/projects/route.ts`
- tests under `tests/lib/` and `tests/api/`
2. **Agent B (Kanban UI Track)**
- Primary beads: `bb-trz.1`, then `bb-trz.2`, then `bb-trz.3`, then `bb-trz.4`
- Scope: tracer bullet 1 Kanban baseline (demo-inspired UI with production typing)
- Files expected:
- `src/app/page.tsx`
- `src/components/kanban/*`
- `src/components/shared/*`
- UI tests under `tests/`
3. **Agent C (Scanner Track)**
- Primary beads: `bb-6aj.3`, then `bb-6aj.3.1` (optional if time remains)
- Scope: bounded scanner rooted at `%USERPROFILE%` with explicit full-drive opt-in mode
- Files expected:
- `src/lib/scanner.ts`
- `src/app/api/scan/route.ts` (if created in this phase)
- tests under `tests/lib/`
4. **Lead Agent (Integrator/Verifier)**
- No primary feature bead; owns integration + verification
- Scope: merges, resolves small conflicts, runs checks, updates bead states
---
## Dependency Rules (Do Not Break)
1. `bb-6aj.2` must start only after `bb-6aj.1` is complete (hard dependency).
2. `bb-6aj.3` depends on `bb-6aj.1` (hard dependency).
3. `bb-trz.2` depends on `bb-trz.1`.
4. `bb-trz.3` and `bb-trz.4` depend on `bb-trz.2`.
5. No direct writes to `.beads/issues.jsonl` under any condition.
---
## Checkpoint Sequence
### Checkpoint 0: Branch Preparation
1. Create feature branches from current baseline:
- `feat/registry-api`
- `feat/kanban-baseline`
- `feat/scanner`
2. Each agent works only in its branch.
### Checkpoint 1: Foundation Delivery
1. Agent A finishes `bb-6aj.1`.
2. Agent B finishes `bb-trz.1`.
3. Agent C remains blocked until `bb-6aj.1` closes, then starts `bb-6aj.3`.
4. Lead verifies:
- `npm run typecheck`
- `npm run test`
### Checkpoint 2: Mid-Phase Delivery
1. Agent A completes `bb-6aj.2`.
2. Agent B completes `bb-trz.2`.
3. Agent C completes `bb-6aj.3`.
4. Lead rebases/merges and reruns:
- `npm run typecheck`
- `npm run test`
- `npm run dev` (startup sanity)
### Checkpoint 3: Tracer-1 Completion
1. Agent B completes `bb-trz.3` and `bb-trz.4`.
2. Lead runs manual UI smoke for Kanban baseline.
3. Lead optionally uses browser automation for verification once app is up.
---
## Agent Prompt Pack
### Prompt: Agent A (Registry/API)
```text
You are Agent A on BeadBoard.
Mission:
1) Complete bb-6aj.1
2) Complete bb-6aj.2
Constraints:
- Windows-native paths only
- Persist registry at %USERPROFILE%\.beadboard\projects.json
- Normalize paths safely (no Unix assumptions)
- No direct writes to .beads/issues.jsonl
- Maintain strict TS types and add tests
Deliverables:
- src/lib/registry.ts (or equivalent)
- src/app/api/projects/route.ts with add/remove/list
- tests covering malformed paths, duplicate normalization, lazy file creation
- bead updates with concise implementation notes
Verification before close:
- npm run typecheck
- npm run test
```
### Prompt: Agent B (Kanban Baseline)
```text
You are Agent B on BeadBoard.
Mission:
1) Complete bb-trz.1
2) Complete bb-trz.2
3) Complete bb-trz.3
4) Complete bb-trz.4
Constraints:
- Rebuild demo style as production Next.js/TS components
- Use real parser data path, no sample-data-only architecture
- Preserve status ordering: open, in_progress, blocked, deferred, closed
- Read boundary only; all writes are future bd bridge work
- Keep components modular and typed
Deliverables:
- Kanban columns
- Card component with id/priority/type/labels/assignee/dep count
- Detail panel with timestamps/dependencies
- Search/filter/stats controls
- tests for rendering and filtering behavior
Verification before close:
- npm run typecheck
- npm run test
- npm run dev (manual check of kanban page)
```
### Prompt: Agent C (Scanner)
```text
You are Agent C on BeadBoard.
Mission:
1) Complete bb-6aj.3
2) Optionally complete bb-6aj.3.1 if time permits
Constraints:
- Default scan root is %USERPROFILE%, not full-drive crawl
- Implement bounded recursion and ignore patterns
- Explicit full-drive scan must be opt-in only
- Windows-safe path normalization throughout
- No shell-specific assumptions
Deliverables:
- src/lib/scanner.ts
- optional scan API route if needed for invoking scanner
- tests for depth limit, ignore behavior, and root selection
Verification before close:
- npm run typecheck
- npm run test
```
### Prompt: Lead Agent (Integration)
```text
You are Lead Agent for BeadBoard integration.
Mission:
1) Integrate outputs from Agent A/B/C at checkpoints
2) Keep bead statuses accurate
3) Run verification and capture failures with file-level notes
Rules:
- Do not mask failing tests
- Resolve merge conflicts without changing boundary contracts
- Ensure no direct writes to .beads/issues.jsonl
Verification gates:
- npm run typecheck
- npm run test
- npm run dev startup check
Completion condition:
- Tracer bullet 1 Kanban baseline visible and functional
- Registry + scanner foundations merged and passing checks
```
---
## First Task to Start Now
1. Start **Agent A** on `bb-6aj.1` (unblocks both `bb-6aj.2` and `bb-6aj.3`).
2. In parallel, start **Agent B** on `bb-trz.1`.
3. Start **Agent C** only after `bb-6aj.1` is closed.
---
## Run Commands (Lead)
```powershell
# show ready tasks
bd ready
# claim task
bd update bb-6aj.1 --claim
# run verification
npm run typecheck
npm run test
npm run dev
```