beadboard/docs/plans/2026-02-12-beadboard-implementation-plan.md

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