From fabd7488333b46015b1ecda56ee614a8568965b3 Mon Sep 17 00:00:00 2001 From: zenchantlive Date: Tue, 24 Mar 2026 20:33:15 -0500 Subject: [PATCH 1/6] docs: rewrite README + add under-construction banner to orchestrator panel README.md: - Remove duplicate sections, stale info, and broken markdown - Add bb-pi orchestrator section with honest WIP status and known issues - Clarify bd vs bb/beadboard CLI distinction - Add cross-platform support section (Windows, macOS, Linux) - Note Dolt as optional, document JSONL fallback - Reference Pi SDK and community tools listing orchestrator-panel.tsx: - Add amber "Under construction" banner with link to track progress - Visible on every orchestrator panel render Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 621 +++++-------------- src/components/shared/orchestrator-panel.tsx | 9 +- 2 files changed, 172 insertions(+), 458 deletions(-) diff --git a/README.md b/README.md index b5b779b..e2460f6 100644 --- a/README.md +++ b/README.md @@ -1,226 +1,105 @@ -## 🚧 Fixing issues as we speak! Will be up and running again soon 🚧 - # BeadBoard [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -[![GitHub stars](https://img.shields.io/github/stars/zenchantlive/beadboard?style=social)](https://github.com/zenchantlive/beadboard/stargazers) -**Multi-agent swarm coordination system for dependency-constrained work.** +**Local dashboard and multi-agent orchestration system built on [Beads](https://github.com/steveyegge/beads).** -Built on [Beads](https://github.com/steveyegge/beads) and inspired by [Gastown](https://github.com/steveyegge/gastown). - ---- - -## πŸš€ Add BeadBoard to Your Agent - -```bash -npx skills add zenchantlive/beadboard --skill beadboard-driver -``` - -This one command installs the BeadBoard driver skill, enabling your AI agents to: -- Coordinate work through dependency-constrained task graphs -- Communicate with other agents via structured message passing -- Track progress with real-time updates and activity streams -- Manage work state through the `bd` CLI - -## Installation - -### Prerequisites - -- **Node.js** 18.18+ (Node 20 LTS recommended) -- **npm** 7.0+ -- **Git** (for cloning and version control) - -### Install from Source - -BeadBoard is installed by cloning the repository and installing locally: - -```bash -# Clone the repository -git clone https://github.com/zenchantlive/beadboard.git -cd beadboard - -# Install globally (makes `beadboard` and `bd` commands available) -npm install -g . -``` - -This installs: -- `beadboard` - Dashboard launcher -- `bd` - Beads CLI for task management - -> **Note**: BeadBoard is not published to npm yet. We may publish it in the future if there's demand. For now, install from source as shown above. - -### Verify Installation - -```bash -beadboard --version -bd --version -``` - -### Development Setup - -For development or contributing: - -```bash -git clone https://github.com/zenchantlive/beadboard.git -cd beadboard -npm install -npm run dev -``` - -### Update Installation - -```bash -cd beadboard -git pull origin main -npm install -g . -``` +BeadBoard reads `.beads/issues.jsonl` files directly from your repos and renders them as an agent-first operations console: a unified shell with Social, Graph, and Activity lenses for monitoring multi-agent work, managing swarms, and intervening on blockers. Found us via the [Beads community tools list](https://github.com/steveyegge/beads/blob/main/docs/COMMUNITY_TOOLS.md)? You're in the right place. --- ## Quick Start -### Start the Dashboard +**Prerequisites:** Node.js 18.18+ (Node 20 LTS recommended), npm 7+ ```bash -# Start with Dolt backend (recommended) -beadboard start --dolt +# Clone and install +git clone https://github.com/zenchantlive/beadboard.git +cd beadboard +npm install +npm install -g . +``` -# Or start without Dolt (limited features) +This installs: +- `beadboard` β€” Dashboard launcher +- `bb` β€” Alias for `beadboard`, also the CLI for the built-in orchestrator agent (built on [Pi](https://github.com/badlogic/pi-mono)) +- `bd` β€” Beads CLI for task management (also available standalone via `npm install -g @beads/bd`) + +```bash +# Initialize Beads in your project +cd ~/my-project +bd init + +# Start the dashboard beadboard start ``` -Open [http://localhost:3000](http://localhost:3000) to access the coordination dashboard. +Open [http://localhost:3000](http://localhost:3000). -### Initialize a Project - -```bash -# Create a new project -mkdir my-project -cd my-project -bd init - -# Create your first task -bd create --title "My first task" --type task --priority 0 -``` +> **Dolt is optional.** BeadBoard reads `.beads/issues.jsonl` directly when Dolt is not running. Install Dolt for version-controlled SQL history β€” recommended for multi-agent workflows but not required to get started. --- ## For AI Agents -### Add BeadBoard to Your Agent +Install the `beadboard-driver` skill to give your agent the operating contract for BeadBoard coordination: ```bash npx skills add zenchantlive/beadboard --skill beadboard-driver ``` -This command installs the BeadBoard driver skill, enabling your AI agents to: -- Coordinate work through dependency-constrained task graphs -- Communicate with other agents via structured message passing -- Track progress with real-time updates and activity streams -- Manage work state through the `bd` CLI - -**[β†’ Full Agent Integration Guide](#agent-integration)** - ---- - - ---- - -## Quick Start - -### For Human Users - -```bash -# Clone and install from source -git clone https://github.com/zenchantlive/beadboard.git -cd beadboard -npm install -g . -beadboard start -``` - -Open [http://localhost:3000](http://localhost:3000) to access the coordination dashboard. - -### For Agent Developers - -```bash -# Install the skill to your project -npx skills add zenchantlive/beadboard --skill beadboard-driver - -# Or install globally for all your projects -npx skills add zenchantlive/beadboard --skill beadboard-driver --global -``` - -Then add to your project's `AGENTS.md`: - -```markdown -## BeadBoard Integration - -- Working directory: Run all `bd` commands from project root -- Source of truth: `bd` CLI manages all work state -- Evidence required: Never claim done without verification gates -``` - ---- - -Open [http://localhost:3000](http://localhost:3000) to access the dashboard. - ---- - -## Agent Integration - -BeadBoard is designed for AI agent coordination. Agents work in their own project repositories while humans observe and coordinate through the BeadBoard UI. - -### Configuration - -Add the following to your project's `AGENTS.md` or `CLAUDE.md`: +Then add to your project's `AGENTS.md` or `CLAUDE.md`: ```markdown ## BeadBoard -You have access to the **beadboard-driver** skill. [page:22] - -- Always use beadboard-driver as your entrypoint for coordination work (tasks, context, status) instead of inventing your own workflow. -- Use it to read and update Beads via `bd`, keep work state consistent with the BeadBoard UI, and obey the verification rules described in this repo. -- When in doubt about what to do next or how to record progress, call beadboard-driver and follow its guidance rather than editing markdown ad‑hoc. +You have access to the **beadboard-driver** skill. +- Use beadboard-driver as your entrypoint for all coordination work (tasks, context, status). +- Use it to read and update Beads via `bd`, keep work state consistent with the BeadBoard UI, + and follow the verification rules described in this repo. +- When in doubt about what to do next or how to record progress, call beadboard-driver and + follow its guidance rather than editing markdown ad hoc. ``` -### Key Concepts +The full agent operating manual is at [AGENTS.md](AGENTS.md). The skill runbook is at [skills/beadboard-driver/SKILL.md](skills/beadboard-driver/SKILL.md). -| Component | Purpose | -|-----------|---------| -| `bd` | Beads CLI - task and dependency management | -| `bb` | BeadBoard CLI - dashboard launcher | -| `beadboard-driver` skill | Agent operating contract for coordination | +**Two CLIs, one system:** -See [skills/beadboard-driver/SKILL.md](skills/beadboard-driver/SKILL.md) for the complete agent runbook. +| Command | What it is | +|---------|-----------| +| `bd` | Beads CLI β€” task/dependency management. Also available via `npm install -g @beads/bd` | +| `bb` / `beadboard` | BeadBoard CLI β€” dashboard launcher + orchestrator | --- -## What BeadBoard Does +## Features -BeadBoard is an execution system for coordinating agents around shared Beads workflows: +### Social View β€” grouped task cards with agent context -- **Agent-to-agent communication** with explicit categories (`HANDOFF`, `BLOCKED`, `DECISION`, `INFO`) -- **Conversation threads** merged from activity events, agent messages, and local interactions -- **Graph/topology context** for deciding what should move next -- **Global project scope switching** across single and aggregate workspaces -- **Swarm orchestration** with archetypes/templates and assignment controls +Task cards organized by status, with dependency chains, thread context, and agent assignment surfaced inline. Built for scanning active work across a swarm at a glance. -![BeadBoard Dashboard - Multi-agent coordination interface showing task graph, agent pool, and activity stream](docs/screenshots/image-9.png) +![Social view showing grouped task cards with agent threads and dependency context](docs/screenshots/image-9.png) ---- +### Graph View β€” dependency topology -## Core Features +DAG visualization of your task graph using XYFlow and Dagre layout. Shows blocked chains, execution order, and assignees on nodes. Drives assignment decisions from topology rather than gut feel. -### 1. Agent Communication System +![Dependency graph view showing task DAG with blocker highlighting](docs/screenshots/image-8.png) -Structured message lifecycle for inter-agent coordination: +### Activity View β€” realtime operations feed -- **Message states**: `unread`, `read`, `acked` -- **Required acknowledgment** for high-signal categories (`HANDOFF`, `BLOCKED`) -- **Per-task threads** combining activity events, agent mail, and local interactions +Live activity stream integrating session events, state transitions, and agent mail. Updates via file watchers and Server-Sent Events β€” no polling, no manual refresh. + +### Swarm Coordination + +Agent pool monitor with archetypes, assignment queues, and squad roster. "Needs Agent" and pre-assigned queues let you drive work assignment without leaving the dashboard. + +![Swarm coordination panel showing agent pool, archetypes, and assignment queues](docs/screenshots/image-7.png) + +### Agent Mail + +Structured inter-agent messaging with categories (`HANDOFF`, `BLOCKED`, `DECISION`, `INFO`). High-signal categories require explicit acknowledgment. Per-task threads merge activity events, agent mail, and local interactions. ```bash bd mail inbox @@ -228,326 +107,156 @@ bd mail send --to --bead --category HANDOFF --subject "Ready for re bd mail ack ``` -### 2. Swarm Coordination Surface +### Multi-Project Scope -Agent Pool Monitor with: - -- Archetypes and templates for agent specialization -- "Needs Agent" queue for unassigned work -- Pre-assigned queue for reserved tasks -- Squad roster for active team members - -![Swarm Coordination Panel - Agent pool monitor showing archetypes, assignment queues, and squad roster](docs/screenshots/image-7.png) - -### 3. Graph + Dependency Topology - -DAG-oriented workspace for execution decisions: - -- Task/dependency tab modes for different planning lenses -- Blocker/unblock context surfaced in task cards -- Graph analysis support (cycle detection, blocked-chain identification) - -![Dependency Graph View - DAG visualization showing task dependencies and execution order](docs/screenshots/image-8.png) - -### 4. Global Project Scope + Scanner - -- Project registry and scanner-backed discovery -- Single-project and aggregate modes -- Runtime scope switching without leaving the workspace - -### 5. Realtime Operations Layer - -- Live updates via file watchers + Server-Sent Events -- Activity stream integration with session/task context -- Mutation/writeback feedback integrated into the operational surface +Project registry with scanner-backed discovery. Switch between single-project and aggregate modes at runtime without leaving the workspace. --- -## Installation & Setup +## bb-pi Orchestrator -### Prerequisites +> **UNDER CONSTRUCTION** β€” The orchestrator is working but new. Use your own coding agent alongside BeadBoard for now, or help us improve it! -- Node.js `18.18+` (Node `20 LTS` recommended) -- npm +`bb-pi` is BeadBoard's embedded execution runtime. It uses [Pi](https://github.com/badlogic/pi-mono) ([@mariozechner/pi-coding-agent](https://www.npmjs.com/package/@mariozechner/pi-coding-agent)) as the execution substrate and exposes a long-lived orchestrator per project that can spawn typed worker agents. -### Clone + Install +**What works today (Phases 1-3 complete):** -```bash -git clone https://github.com/zenchantlive/beadboard.git -cd beadboard -npm install -npm install -g . -``` +- Embedded orchestrator with BeadBoard-aware tools (`bb_spawn_worker`, `bb_worker_status`, `bb_create`, `bb_close`, etc.) +- Worker spawning with numbered display names (Engineer 01, Engineer 02...) +- Agent types with capability-gated tool access (architect, engineer, reviewer, tester, investigator, shipper) +- Template-based team spawning (`bb_spawn_team`) +- Bead-required workflow β€” every worker task claims a bead, updates progress, closes with evidence +- Async worker coordination β€” non-blocking spawn with status polling and result reads +- Chat-style orchestrator transcript in the left panel with realtime telemetry -This makes `beadboard` and `bd` commands available globally. +**Known issues being actively fixed:** -**Alternative: Platform-specific wrappers** +- Double-reply rendering in orchestrator chat +- Silent failures β€” errors not surfaced to UI +- Session race condition under rapid use +- Phases 4-7 (launch-anywhere UX, agent presence in views, hardening, test coverage) are not done -If you prefer not to install globally via npm, you can use the platform-specific wrappers. - -POSIX (Linux/macOS): -```bash -bash ./install/install.sh -### Development Setup - -```bash -npm run dev -``` - -Open [http://localhost:3000](http://localhost:3000) - -### Production Deployment - -```bash -npm run build -npm run start -``` - ---- - -## Usage & Examples - -### CLI Commands - -```bash -# Start BeadBoard dashboard -beadboard start - -# Start with Dolt database -beadboard start --dolt - -# Open dashboard in browser -beadboard open - -# Check status -beadboard status -``` - -### Workflow Example - -```bash -# 1. Navigate to your project -cd ~/my-project - -# 2. Start Dolt (if using version-controlled data) -bd dolt start - -# 3. Start BeadBoard -beadboard start --dolt - -# 4. Open dashboard -beadboard open -``` - -### Common Patterns - -**Coordinate through Graph + Pool:** -``` -Open /?view=graph β†’ inspect dependency topology β†’ drive assignment from pool panel -``` - -**Communicate in Context:** -``` -Open task thread β†’ read merged conversation β†’ process message acknowledgments -``` - -**Switch Scope:** -``` -Use registry/scanner controls β†’ move between local and aggregate project scope -``` - -**Track Live Signal:** -``` -Use social/activity views β†’ monitor execution movement and operational events -``` +See [docs/plans/2026-03-05-embedded-pi-roadmap.md](docs/plans/2026-03-05-embedded-pi-roadmap.md) for the full status breakdown. --- ## Architecture -### High-Level Design +### Data flow ``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ BeadBoard UI β”‚ -β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ -β”‚ β”‚ Social β”‚ β”‚ Graph β”‚ β”‚ Activity β”‚ β”‚ Swarm β”‚ β”‚ -β”‚ β”‚ View β”‚ β”‚ View β”‚ β”‚ View β”‚ β”‚ Panel β”‚ β”‚ -β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ β”‚ β”‚ - β”Œβ”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β–Όβ”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β” - β”‚ SSE β”‚ β”‚ Dolt β”‚ β”‚ Watchersβ”‚ - β”‚ Events β”‚ β”‚ DB β”‚ β”‚ (Chokidar)β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ β”‚ β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - β”Œβ”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β” - β”‚ bd β”‚ - β”‚ (Beads CLI)β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +.beads/issues.jsonl <-- bd CLI (sole write interface) + | + +-- Chokidar watcher (file + WAL + .last_touched) + | | + | IssuesEventBus + | | + | SSE endpoint --> browser (live updates) + | + +-- Aggregate read --> Dolt SQL (primary, if running) + issues.jsonl (fallback) ``` -### Tech Stack +1. `bd` commands write to `.beads/issues.jsonl`. Never write to this file directly. +2. The parser (`src/lib/parser.ts`) normalizes JSONL into `BeadIssue` objects. +3. `IssuesWatchManager` (Chokidar) watches for changes, coalesces events, and emits through the event bus. +4. The SSE endpoint (`/api/events`) streams changes to the browser. +5. The read path prefers Dolt SQL when available and falls back to JSONL. + +### Tech stack | Layer | Technologies | |-------|-------------| -| Frontend | Next.js 15, React 19, TypeScript | +| Frontend | Next.js 15 (App Router), React 19, TypeScript (strict) | | Styling | Tailwind CSS, Radix UI, Framer Motion | -| Graph | XYFlow, Dagre | -| Database | Dolt (version-controlled SQL) | -| Realtime | Chokidar watchers, Server-Sent Events | -| Validation | Zod schemas, strict TypeScript | +| Graph | @xyflow/react, Dagre | +| Realtime | Chokidar, Server-Sent Events | +| Database | Dolt (optional, version-controlled SQL) | +| Agent runtime | @mariozechner/pi-coding-agent (bb-pi, under construction) | +| Video | Remotion | -### Data Flow +### View routing -1. **Write Path**: `bd` commands write to `.beads/issues.jsonl` and Dolt DB -2. **Read Path**: UI queries Dolt SQL server (falls back to JSONL if unreachable) -3. **Realtime**: `bd` touches `.beads/last-touched` β†’ Chokidar fires β†’ SSE event β†’ UI update - -### Runtime Artifacts - -| Directory | Purpose | Git Status | -|-----------|---------|------------| -| `.beads/` | Beads database, issues, coordination state | gitignored | -| `.agents/` | Agent skills and configuration | gitignored | - ---- - -## Project Structure - -```text -beadboard/ -β”œβ”€β”€ src/ -β”‚ β”œβ”€β”€ app/ -β”‚ β”‚ β”œβ”€β”€ page.tsx # Active runtime route -β”‚ β”‚ └── api/ # Runtime API routes -β”‚ β”œβ”€β”€ components/ -β”‚ β”‚ β”œβ”€β”€ shared/ # Reusable UI components -β”‚ β”‚ β”œβ”€β”€ graph/ # Dependency graph components -β”‚ β”‚ β”œβ”€β”€ social/ # Social/activity views -β”‚ β”‚ β”œβ”€β”€ swarm/ # Swarm coordination panel -β”‚ β”‚ └── sessions/ # Agent session components -β”‚ β”œβ”€β”€ hooks/ # React hooks -β”‚ └── lib/ # Core domain logic -β”œβ”€β”€ skills/ -β”‚ └── beadboard-driver/ # Agent skill package -β”œβ”€β”€ install/ # Platform install scripts -β”œβ”€β”€ reference/ -β”‚ └── routes/ # Archived route implementations -β”œβ”€β”€ docs/ # Documentation -└── tests/ # Test suite -``` - -### Key Files - -| File | Purpose | -|------|---------| -| `src/app/page.tsx` | Main dashboard entry point | -| `src/lib/` | Core domain: Beads model, graph builders, coordination | -| `skills/beadboard-driver/SKILL.md` | Agent operating contract | -| `AGENTS.md` | Agent operating manual for this repo | -| `next.config.ts` | Route redirects and Next.js config | - ---- - -## Routes - -### Active Route - -- `/` - Main dashboard (query-driven) - -### View Modes +All active views live at `/` with query-param switching. Legacy routes redirect: | URL | View | |-----|------| -| `/?view=social` | Agent social feed | +| `/?view=social` | Social feed | | `/?view=graph` | Dependency graph | | `/?view=activity` | Activity timeline | +| `/graph`, `/sessions`, `/timeline` | Redirect to unified shell equivalents | -### Compatibility Redirects +--- -| Old Route | Redirects To | -|-----------|--------------| -| `/graph` | `/?view=graph` | -| `/sessions` | `/?view=social` | -| `/timeline` | `/?view=activity` | -| `/mockup` | `/` | +## CLI Reference + +### bd (Beads CLI) + +```bash +bd init # initialize Beads in a project +bd create --title "Task title" --type task -p 1 # create a task bead +bd ready # list unblocked work +bd show # show bead detail +bd update --status in_progress # update a bead +bd close --reason "Done" # close a bead +bd dep relate --type parent-child +bd mail inbox +bd mail send --to --bead --category HANDOFF --subject "..." +bd dolt start # start Dolt server +bd dolt pull && bd dolt push # sync with Dolt remote +``` + +### bb / beadboard (BeadBoard CLI) + +```bash +beadboard start # start the dashboard server +beadboard start --dolt # start with Dolt backend +beadboard open # open dashboard in browser +beadboard status # check runtime status +``` + +### npm scripts (development) + +```bash +npm run dev # Next.js dev server (localhost:3000) +npm run build # production build +npm run typecheck # tsc --noEmit +npm run lint # eslint +npm run test # full test suite +``` + +Run a single test file: + +```bash +node --import tsx --test tests/lib/parser.test.ts +``` + +> New test files must be added to the `test` script in `package.json` β€” the suite is explicitly enumerated, not auto-discovered. + +--- + +## Cross-Platform Support + +BeadBoard runs on Windows, macOS, and Linux. + +- **macOS / Linux**: Use `install/install.sh` to install `beadboard` and `bb` shims to `~/.beadboard/bin`. +- **Windows**: Path handling canonicalizes drive letter casing and backslash normalization. Mixed WSL2 + Windows setups require mirrored networking β€” see [AGENTS.md](AGENTS.md). +- **Dolt**: Optional on all platforms. The dashboard reads `.beads/issues.jsonl` directly when Dolt is unavailable. --- ## Contributing -### Development Workflow - -1. Fork the repository -2. Create a feature branch: `git checkout -b feature/my-feature` -3. Make changes following existing patterns -4. Run quality gates: +1. Fork the repo and create a feature branch. +2. Run quality gates before submitting: ```bash -npm run typecheck -npm run lint -npm run test +npm run typecheck && npm run lint && npm run test ``` -5. Submit a pull request - -### Code Guidelines - -- Keep active runtime pages minimal in `src/app` -- Promote reusable logic to `src/lib`, `src/components`, `src/hooks` -- Archive experimental routes in `reference/routes` -- Follow existing TypeScript and React patterns -- Add tests for new functionality - -### Code of Conduct - -- Be respectful and inclusive -- Focus on constructive feedback -- Support newcomers to the project - ---- - -## Scripts - -```bash -npm run dev # Development server -npm run build # Production build -npm run start # Production server -npm run typecheck # TypeScript validation -npm run lint # ESLint -npm run test # Test suite -npm run video # Remotion video preview -npm run video:render # Render video -``` - ---- - -## Changelog - -### v0.1.0 (Current) - -- Initial release -- Multi-agent coordination system -- Graph-based dependency visualization -- Real-time updates via SSE -- Agent mail and communication system -- Swarm coordination panel -- Global project scope switching - ---- - -## Roadmap - -- Cross-view assignment controls in all major views -- Enhanced swarm UX and terminology -- Expanded global project configuration workflows -- Witness enforcement layer for agent liveness -- Additional graph analysis features +3. Keep active runtime pages minimal under `src/app`. Promote shared logic to `src/lib`, `src/components`, `src/hooks`. +4. New tests must be registered in the `test` script in `package.json`. +5. Submit a pull request against `main`. --- @@ -555,8 +264,6 @@ npm run video:render # Render video [MIT](LICENSE) ---- - ## Acknowledgments -Built on [Beads](https://github.com/steveyegge/beads) and inspired by [Gastown](https://github.com/steveyegge/gastown). Thanks [Steve Yegge](https://github.com/steveyegge)! +Built on [Beads](https://github.com/steveyegge/beads) by [Steve Yegge](https://github.com/steveyegge), inspired by [Gastown](https://github.com/steveyegge/gastown). The embedded Pi execution runtime uses [@mariozechner](https://github.com/mariozechner)'s [Pi SDK](https://github.com/badlogic/pi-mono). diff --git a/src/components/shared/orchestrator-panel.tsx b/src/components/shared/orchestrator-panel.tsx index 73d8f62..46f3e64 100644 --- a/src/components/shared/orchestrator-panel.tsx +++ b/src/components/shared/orchestrator-panel.tsx @@ -1,7 +1,7 @@ 'use client'; import { useEffect, useMemo, useState } from 'react'; -import { Send } from 'lucide-react'; +import { Construction, Send } from 'lucide-react'; import type { RuntimeInstance } from '../../lib/embedded-runtime'; import type { OrchestratorChatMessage } from '../../lib/orchestrator-chat'; @@ -55,6 +55,13 @@ export function OrchestratorPanel({ orchestrator, thread, projectRoot }: Orchest return (
+
+ +

+ Under construction β€” orchestrator has known issues being actively fixed. + Track progress +

+

Main Orchestrator

From 5537e22174bf7dcedcc89fabfbdb3f2d3b267b99 Mon Sep 17 00:00:00 2001 From: zenchantlive Date: Tue, 24 Mar 2026 20:37:32 -0500 Subject: [PATCH 2/6] =?UTF-8?q?docs:=20sharpen=20README=20=E2=80=94=20lead?= =?UTF-8?q?=20with=20the=20problem,=20frame=20Dolt=20as=20recommended?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Hero screenshot + "who's watching your agents" hook at top - Dolt promoted from optional footnote to recommended with install commands - bb-pi section leads with vision before construction status - Agent-first framing moved higher - Trimmed to 248 lines, no duplicates, no filler Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 275 +++++++++++++++++++++++++----------------------------- 1 file changed, 127 insertions(+), 148 deletions(-) diff --git a/README.md b/README.md index e2460f6..5c43359 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,134 @@ # BeadBoard +**A live operations console for multi-agent work. See what every agent is doing, what's blocked, and where to intervene.** + [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Built on Beads](https://img.shields.io/badge/built%20on-Beads-blue)](https://github.com/steveyegge/beads) -**Local dashboard and multi-agent orchestration system built on [Beads](https://github.com/steveyegge/beads).** +![BeadBoard social view β€” grouped task cards with agent context and dependency chains](docs/screenshots/image-9.png) -BeadBoard reads `.beads/issues.jsonl` files directly from your repos and renders them as an agent-first operations console: a unified shell with Social, Graph, and Activity lenses for monitoring multi-agent work, managing swarms, and intervening on blockers. Found us via the [Beads community tools list](https://github.com/steveyegge/beads/blob/main/docs/COMMUNITY_TOOLS.md)? You're in the right place. +--- + +Your agents are doing work. Who's watching? + +BeadBoard gives you eyes on multi-agent swarms: which tasks are in flight, which are blocked and why, what the dependency topology looks like, and where you need to step in. It reads [Beads](https://github.com/steveyegge/beads) issue files from your repos and renders them as a unified shell β€” Social, Graph, and Activity lenses β€” that updates in realtime as agents work. + +It's designed agents-first. Agents use the `bd` CLI to claim tasks, post progress, and send structured mail to each other. You watch from the dashboard and intervene when needed. --- ## Quick Start -**Prerequisites:** Node.js 18.18+ (Node 20 LTS recommended), npm 7+ +**Prerequisites:** Node.js 20 LTS, npm 7+ ```bash -# Clone and install git clone https://github.com/zenchantlive/beadboard.git cd beadboard npm install npm install -g . -``` - -This installs: -- `beadboard` β€” Dashboard launcher -- `bb` β€” Alias for `beadboard`, also the CLI for the built-in orchestrator agent (built on [Pi](https://github.com/badlogic/pi-mono)) -- `bd` β€” Beads CLI for task management (also available standalone via `npm install -g @beads/bd`) - -```bash -# Initialize Beads in your project cd ~/my-project bd init - -# Start the dashboard beadboard start ``` Open [http://localhost:3000](http://localhost:3000). -> **Dolt is optional.** BeadBoard reads `.beads/issues.jsonl` directly when Dolt is not running. Install Dolt for version-controlled SQL history β€” recommended for multi-agent workflows but not required to get started. +--- + +## Dolt (recommended) + +BeadBoard works with [Dolt](https://github.com/dolthub/dolt) for version-controlled issue history, SQL queries across projects, and reliable multi-agent sync. It's the right backend for real work. + +```bash +# macOS +brew install dolt + +# Linux / Windows +go install github.com/dolthub/dolt/go/cmd/dolt@latest +# or: curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash +``` + +Then start the dashboard with Dolt: + +```bash +beadboard start --dolt +# or manage Dolt separately: +bd dolt start +``` + +Without Dolt, BeadBoard reads `.beads/issues.jsonl` directly β€” enough to explore, but you'll want Dolt for anything serious. + +--- + +## Features + +### Social View β€” your swarm at a glance + +Task cards organized by status, with dependency chains, thread context, and agent assignments surfaced inline. Built for scanning active work across many agents without losing the thread. + +![Social view showing grouped task cards with agent threads and dependency context](docs/screenshots/image-9.png) + +### Graph View β€” see the blockers before they block you + +DAG visualization of your task graph using XYFlow and Dagre layout. Blocked chains are highlighted. Assignees appear on nodes. Use topology to drive assignment decisions, not gut feel. + +![Dependency graph showing task DAG with blocker highlighting](docs/screenshots/image-8.png) + +### Activity View β€” realtime operations feed + +Live stream of session events, state transitions, and agent mail. Updates via file watchers and Server-Sent Events β€” no polling, no manual refresh. + +### Swarm Coordination β€” agent pools and assignment queues + +Monitor your agent pool with archetypes and a squad roster. "Needs Agent" and pre-assigned queues let you drive work assignment from the dashboard. + +![Swarm coordination panel showing agent pool, archetypes, and assignment queues](docs/screenshots/image-7.png) + +### Agent Mail β€” structured inter-agent messaging + +`HANDOFF`, `BLOCKED`, `DECISION`, `INFO` categories. High-signal categories require explicit acknowledgment. Per-task threads merge activity events, agent mail, and manual notes. + +```bash +bd mail inbox +bd mail send --to --bead --category HANDOFF --subject "Ready for review" +bd mail ack +``` + +### Multi-Project Scope + +Scanner-backed project registry. Switch between single-project and aggregate views at runtime without leaving the workspace. + +--- + +## bb-pi Orchestrator + +> **Under active construction.** The orchestrator works, but it's new and has rough edges. For now: run your own coding agent alongside BeadBoard and use the dashboard to coordinate. Help improving it is welcome. + +BeadBoard doesn't just watch your agents β€” it can run them. + +`bb-pi` is BeadBoard's embedded execution runtime, built on [Pi](https://github.com/badlogic/pi-mono). It exposes a long-lived orchestrator per project that spawns typed worker agents, tracks their bead claims, and streams a live transcript into the left panel. + +**Working today (Phases 1-3):** +- Embedded orchestrator with BeadBoard-aware tools (`bb_spawn_worker`, `bb_worker_status`, `bb_create`, `bb_close`, and more) +- Worker spawning with numbered display names (Engineer 01, Engineer 02...) +- Capability-gated agent types: architect, engineer, reviewer, tester, investigator, shipper +- Template-based team spawning (`bb_spawn_team`) +- Bead-required workflow β€” every worker task claims a bead, posts progress, closes with evidence +- Async coordination β€” non-blocking spawn with status polling and result reads +- Chat-style orchestrator transcript with realtime telemetry + +**Known issues being fixed:** +- Double-reply rendering in orchestrator chat +- Silent failures β€” errors not yet surfaced to UI +- Session race condition under rapid use + +**Phases 4-7** (launch-anywhere UX, agent presence in views, hardening, full test coverage) are on the roadmap. See [docs/plans/2026-03-05-embedded-pi-roadmap.md](docs/plans/2026-03-05-embedded-pi-roadmap.md). --- ## For AI Agents -Install the `beadboard-driver` skill to give your agent the operating contract for BeadBoard coordination: +BeadBoard is designed to be operated by agents, not just watched by humans. Give your agent the operating contract: ```bash npx skills add zenchantlive/beadboard --skill beadboard-driver @@ -55,115 +141,36 @@ Then add to your project's `AGENTS.md` or `CLAUDE.md`: You have access to the **beadboard-driver** skill. -- Use beadboard-driver as your entrypoint for all coordination work (tasks, context, status). -- Use it to read and update Beads via `bd`, keep work state consistent with the BeadBoard UI, - and follow the verification rules described in this repo. -- When in doubt about what to do next or how to record progress, call beadboard-driver and - follow its guidance rather than editing markdown ad hoc. +Use it as your entrypoint for all coordination work: claiming tasks, posting progress, +reading context, and following verification rules. When in doubt about what to do next +or how to record state, call beadboard-driver rather than editing markdown ad hoc. ``` -The full agent operating manual is at [AGENTS.md](AGENTS.md). The skill runbook is at [skills/beadboard-driver/SKILL.md](skills/beadboard-driver/SKILL.md). +Full operating manual: [AGENTS.md](AGENTS.md). Skill runbook: [skills/beadboard-driver/SKILL.md](skills/beadboard-driver/SKILL.md). -**Two CLIs, one system:** - -| Command | What it is | -|---------|-----------| -| `bd` | Beads CLI β€” task/dependency management. Also available via `npm install -g @beads/bd` | -| `bb` / `beadboard` | BeadBoard CLI β€” dashboard launcher + orchestrator | - ---- - -## Features - -### Social View β€” grouped task cards with agent context - -Task cards organized by status, with dependency chains, thread context, and agent assignment surfaced inline. Built for scanning active work across a swarm at a glance. - -![Social view showing grouped task cards with agent threads and dependency context](docs/screenshots/image-9.png) - -### Graph View β€” dependency topology - -DAG visualization of your task graph using XYFlow and Dagre layout. Shows blocked chains, execution order, and assignees on nodes. Drives assignment decisions from topology rather than gut feel. - -![Dependency graph view showing task DAG with blocker highlighting](docs/screenshots/image-8.png) - -### Activity View β€” realtime operations feed - -Live activity stream integrating session events, state transitions, and agent mail. Updates via file watchers and Server-Sent Events β€” no polling, no manual refresh. - -### Swarm Coordination - -Agent pool monitor with archetypes, assignment queues, and squad roster. "Needs Agent" and pre-assigned queues let you drive work assignment without leaving the dashboard. - -![Swarm coordination panel showing agent pool, archetypes, and assignment queues](docs/screenshots/image-7.png) - -### Agent Mail - -Structured inter-agent messaging with categories (`HANDOFF`, `BLOCKED`, `DECISION`, `INFO`). High-signal categories require explicit acknowledgment. Per-task threads merge activity events, agent mail, and local interactions. - -```bash -bd mail inbox -bd mail send --to --bead --category HANDOFF --subject "Ready for review" -bd mail ack -``` - -### Multi-Project Scope - -Project registry with scanner-backed discovery. Switch between single-project and aggregate modes at runtime without leaving the workspace. - ---- - -## bb-pi Orchestrator - -> **UNDER CONSTRUCTION** β€” The orchestrator is working but new. Use your own coding agent alongside BeadBoard for now, or help us improve it! - -`bb-pi` is BeadBoard's embedded execution runtime. It uses [Pi](https://github.com/badlogic/pi-mono) ([@mariozechner/pi-coding-agent](https://www.npmjs.com/package/@mariozechner/pi-coding-agent)) as the execution substrate and exposes a long-lived orchestrator per project that can spawn typed worker agents. - -**What works today (Phases 1-3 complete):** - -- Embedded orchestrator with BeadBoard-aware tools (`bb_spawn_worker`, `bb_worker_status`, `bb_create`, `bb_close`, etc.) -- Worker spawning with numbered display names (Engineer 01, Engineer 02...) -- Agent types with capability-gated tool access (architect, engineer, reviewer, tester, investigator, shipper) -- Template-based team spawning (`bb_spawn_team`) -- Bead-required workflow β€” every worker task claims a bead, updates progress, closes with evidence -- Async worker coordination β€” non-blocking spawn with status polling and result reads -- Chat-style orchestrator transcript in the left panel with realtime telemetry - -**Known issues being actively fixed:** - -- Double-reply rendering in orchestrator chat -- Silent failures β€” errors not surfaced to UI -- Session race condition under rapid use -- Phases 4-7 (launch-anywhere UX, agent presence in views, hardening, test coverage) are not done - -See [docs/plans/2026-03-05-embedded-pi-roadmap.md](docs/plans/2026-03-05-embedded-pi-roadmap.md) for the full status breakdown. +| Command | Role | +|---------|------| +| `bd` | Beads CLI β€” task and dependency management. Also: `npm install -g @beads/bd` | +| `bb` / `beadboard` | BeadBoard CLI β€” dashboard launcher and orchestrator interface | --- ## Architecture -### Data flow - ``` .beads/issues.jsonl <-- bd CLI (sole write interface) | - +-- Chokidar watcher (file + WAL + .last_touched) + +-- Chokidar watcher (JSONL + WAL + .last_touched) | | | IssuesEventBus | | - | SSE endpoint --> browser (live updates) + | SSE /api/events --> browser (live) | +-- Aggregate read --> Dolt SQL (primary, if running) issues.jsonl (fallback) ``` -1. `bd` commands write to `.beads/issues.jsonl`. Never write to this file directly. -2. The parser (`src/lib/parser.ts`) normalizes JSONL into `BeadIssue` objects. -3. `IssuesWatchManager` (Chokidar) watches for changes, coalesces events, and emits through the event bus. -4. The SSE endpoint (`/api/events`) streams changes to the browser. -5. The read path prefers Dolt SQL when available and falls back to JSONL. - -### Tech stack +All views live at `/` with query-param switching (`?view=social|graph|activity`). The `bd` CLI is the only write path β€” BeadBoard never writes to `.beads/issues.jsonl` directly. | Layer | Technologies | |-------|-------------| @@ -171,20 +178,8 @@ See [docs/plans/2026-03-05-embedded-pi-roadmap.md](docs/plans/2026-03-05-embedde | Styling | Tailwind CSS, Radix UI, Framer Motion | | Graph | @xyflow/react, Dagre | | Realtime | Chokidar, Server-Sent Events | -| Database | Dolt (optional, version-controlled SQL) | +| Database | Dolt (recommended, version-controlled SQL) | | Agent runtime | @mariozechner/pi-coding-agent (bb-pi, under construction) | -| Video | Remotion | - -### View routing - -All active views live at `/` with query-param switching. Legacy routes redirect: - -| URL | View | -|-----|------| -| `/?view=social` | Social feed | -| `/?view=graph` | Dependency graph | -| `/?view=activity` | Activity timeline | -| `/graph`, `/sessions`, `/timeline` | Redirect to unified shell equivalents | --- @@ -202,20 +197,20 @@ bd close --reason "Done" # close a bead bd dep relate --type parent-child bd mail inbox bd mail send --to --bead --category HANDOFF --subject "..." -bd dolt start # start Dolt server -bd dolt pull && bd dolt push # sync with Dolt remote +bd dolt start +bd dolt pull && bd dolt push ``` -### bb / beadboard (BeadBoard CLI) +### bb / beadboard (Dashboard CLI) ```bash -beadboard start # start the dashboard server +beadboard start # start the dashboard beadboard start --dolt # start with Dolt backend -beadboard open # open dashboard in browser +beadboard open # open in browser beadboard status # check runtime status ``` -### npm scripts (development) +### Development ```bash npm run dev # Next.js dev server (localhost:3000) @@ -225,38 +220,24 @@ npm run lint # eslint npm run test # full test suite ``` -Run a single test file: - -```bash -node --import tsx --test tests/lib/parser.test.ts -``` - -> New test files must be added to the `test` script in `package.json` β€” the suite is explicitly enumerated, not auto-discovered. - --- -## Cross-Platform Support +## Platform Support -BeadBoard runs on Windows, macOS, and Linux. +Runs on macOS, Linux, and Windows. -- **macOS / Linux**: Use `install/install.sh` to install `beadboard` and `bb` shims to `~/.beadboard/bin`. -- **Windows**: Path handling canonicalizes drive letter casing and backslash normalization. Mixed WSL2 + Windows setups require mirrored networking β€” see [AGENTS.md](AGENTS.md). -- **Dolt**: Optional on all platforms. The dashboard reads `.beads/issues.jsonl` directly when Dolt is unavailable. +- **macOS / Linux:** Use `install/install.sh` to install `beadboard` and `bb` shims to `~/.beadboard/bin`. +- **Windows:** Path handling canonicalizes drive letter casing and backslash normalization. Mixed WSL2 + Windows setups require mirrored networking β€” see [AGENTS.md](AGENTS.md). --- ## Contributing -1. Fork the repo and create a feature branch. -2. Run quality gates before submitting: - ```bash npm run typecheck && npm run lint && npm run test ``` -3. Keep active runtime pages minimal under `src/app`. Promote shared logic to `src/lib`, `src/components`, `src/hooks`. -4. New tests must be registered in the `test` script in `package.json`. -5. Submit a pull request against `main`. +Run that before submitting. Keep new features in `src/lib`, `src/components`, and `src/hooks` β€” not in `src/app` unless it's a route. New test files must be registered in the `test` script in `package.json` (the suite is explicit, not auto-discovered). PR against `main`. --- @@ -264,6 +245,4 @@ npm run typecheck && npm run lint && npm run test [MIT](LICENSE) -## Acknowledgments - -Built on [Beads](https://github.com/steveyegge/beads) by [Steve Yegge](https://github.com/steveyegge), inspired by [Gastown](https://github.com/steveyegge/gastown). The embedded Pi execution runtime uses [@mariozechner](https://github.com/mariozechner)'s [Pi SDK](https://github.com/badlogic/pi-mono). +Built on [Beads](https://github.com/steveyegge/beads) by [Steve Yegge](https://github.com/steveyegge), inspired by [Gastown](https://github.com/steveyegge/gastown). Embedded execution runtime uses [@mariozechner](https://github.com/mariozechner)'s [Pi SDK](https://github.com/badlogic/pi-mono). From 078acd6b57ba7aad5304172dea7b94ce4fd75767 Mon Sep 17 00:00:00 2001 From: zenchantlive Date: Tue, 24 Mar 2026 21:10:39 -0500 Subject: [PATCH 3/6] =?UTF-8?q?docs:=20comprehensive=20README=20rewrite=20?= =?UTF-8?q?=E2=80=94=20keep=20everything=20good,=20fix=20dupes,=20add=20mi?= =?UTF-8?q?ssing=20pieces?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Starting from Jordan's edited version on main: - Fixed 3 duplicate sections (Quick Start, Add to Agent, Install) - Fixed broken markdown (unclosed code block) - Fixed orchestrator banner typos - Added full bb CLI commands (agent register/send/inbox/reserve/release, daemon tui) - Added work reservation system with liveness-aware conflict resolution - Added templates (feature-dev, bug-fix, full-squad, greenfield, etc.) - Added capability-gated agent types - Added bb-pi orchestrator section with honest WIP status - Added Dolt section framed as recommended - Added cross-platform support - Added human-sounding agent instructions - Added emojis for section scanning - Updated architecture diagram to show bb CLI layer - Described beadboard-driver as 9-step operating contract Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 397 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 259 insertions(+), 138 deletions(-) diff --git a/README.md b/README.md index 5c43359..31ae9ef 100644 --- a/README.md +++ b/README.md @@ -1,92 +1,173 @@ +## 🚧 Orchestrator is working but new β€” use your own coding agent for now (unless you want to help!) 🚧 + # BeadBoard -**A live operations console for multi-agent work. See what every agent is doing, what's blocked, and where to intervene.** - [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![GitHub stars](https://img.shields.io/github/stars/zenchantlive/beadboard?style=social)](https://github.com/zenchantlive/beadboard/stargazers) [![Built on Beads](https://img.shields.io/badge/built%20on-Beads-blue)](https://github.com/steveyegge/beads) -![BeadBoard social view β€” grouped task cards with agent context and dependency chains](docs/screenshots/image-9.png) +**Multi-agent orchestration and communication system built on [Beads](https://github.com/steveyegge/beads).** + +Agents claim tasks, send structured mail to each other, track dependencies, and close work with evidence. BeadBoard is the coordination layer β€” a dashboard that shows it all happening live, a CLI (`bb`) that hosts the orchestrator and manages agent communication, and a built-in execution runtime ([bb-pi](#-bb-pi-orchestrator)) that can spawn and manage agent workers directly. + +Built on [Beads](https://github.com/steveyegge/beads) and inspired by [Gastown](https://github.com/steveyegge/gastown). + +![BeadBoard Dashboard](docs/screenshots/image-9.png) --- -Your agents are doing work. Who's watching? +## πŸš€ Add BeadBoard to Your Agent -BeadBoard gives you eyes on multi-agent swarms: which tasks are in flight, which are blocked and why, what the dependency topology looks like, and where you need to step in. It reads [Beads](https://github.com/steveyegge/beads) issue files from your repos and renders them as a unified shell β€” Social, Graph, and Activity lenses β€” that updates in realtime as agents work. +```bash +npx skills add zenchantlive/beadboard --skill beadboard-driver +``` -It's designed agents-first. Agents use the `bd` CLI to claim tasks, post progress, and send structured mail to each other. You watch from the dashboard and intervene when needed. +This installs the [beadboard-driver](skills/beadboard-driver/SKILL.md) skill β€” a 9-step operating contract that gives your agent: +- πŸ“‹ Task coordination through dependency-constrained graphs +- πŸ’¬ Structured agent-to-agent messaging (`HANDOFF`, `BLOCKED`, `DECISION`, `INFO`) +- πŸ”’ Scope-based work reservations with liveness-aware conflict resolution +- πŸ“‘ Realtime progress tracking via heartbeats and activity streams +- βœ… Evidence-required workflow β€” agents can't close work without verification gates + +Or just tell your agent: + +> Install the beadboard-driver skill from https://github.com/zenchantlive/beadboard and use it to coordinate your work. Run `npx skills add zenchantlive/beadboard --skill beadboard-driver` then follow the SKILL.md runbook. + +Then add to your project's `AGENTS.md` or `CLAUDE.md`: + +```markdown +## BeadBoard + +You have access to the **beadboard-driver** skill. + +- Always use beadboard-driver as your entrypoint for coordination work (tasks, context, status) + instead of inventing your own workflow. +- Use it to read and update Beads via `bd`, keep work state consistent with the BeadBoard UI, + and obey the verification rules described in this repo. +- When in doubt about what to do next or how to record progress, call beadboard-driver and + follow its guidance rather than editing markdown ad hoc. +``` + +See [skills/beadboard-driver/SKILL.md](skills/beadboard-driver/SKILL.md) for the complete agent runbook. --- -## Quick Start +## πŸ“¦ Installation -**Prerequisites:** Node.js 20 LTS, npm 7+ +### Prerequisites + +- **Node.js** 18.18+ (Node 20 LTS recommended) +- **npm** 7.0+ +- **[Dolt](https://github.com/dolthub/dolt)** (recommended β€” see [Dolt section](#-dolt)) + +### Install from Source ```bash git clone https://github.com/zenchantlive/beadboard.git cd beadboard npm install npm install -g . +``` + +This installs: +- `beadboard` / `bb` β€” BeadBoard CLI: dashboard, orchestrator host, agent communication commands +- `bd` β€” Beads CLI for task management (also available standalone: `npm install -g @beads/bd`) + +```bash +beadboard --version +bd --version +``` + +**Alternative:** POSIX install script (Linux/macOS): +```bash +bash ./install/install.sh # installs bb + beadboard shims to ~/.beadboard/bin +``` + +--- + +## ⚑ Quick Start + +```bash cd ~/my-project -bd init -beadboard start +bd init # initialize Beads in your project +beadboard start --dolt # start the dashboard with Dolt (recommended) ``` Open [http://localhost:3000](http://localhost:3000). +```bash +bd create --title "My first task" --type task --priority 0 +``` + --- -## Dolt (recommended) +## πŸ—„οΈ Dolt -BeadBoard works with [Dolt](https://github.com/dolthub/dolt) for version-controlled issue history, SQL queries across projects, and reliable multi-agent sync. It's the right backend for real work. +BeadBoard uses [Dolt](https://github.com/dolthub/dolt) β€” a version-controlled SQL database β€” as its primary backend. Dolt gives you: +- Full version history of every issue state change +- SQL queries across all your issues and projects +- `bd dolt pull` / `bd dolt push` for multi-agent sync across machines +- Branch-based workflows ```bash # macOS brew install dolt # Linux / Windows -go install github.com/dolthub/dolt/go/cmd/dolt@latest -# or: curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash +curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash ``` -Then start the dashboard with Dolt: - -```bash -beadboard start --dolt -# or manage Dolt separately: -bd dolt start -``` - -Without Dolt, BeadBoard reads `.beads/issues.jsonl` directly β€” enough to explore, but you'll want Dolt for anything serious. +Without Dolt, BeadBoard falls back to reading `.beads/issues.jsonl` directly. This is enough to poke around, but you'll want Dolt for real work. --- -## Features +## πŸ”§ What BeadBoard Does -### Social View β€” your swarm at a glance +BeadBoard is three things: -Task cards organized by status, with dependency chains, thread context, and agent assignments surfaced inline. Built for scanning active work across many agents without losing the thread. +### The Dashboard +A live operations console with Social, Graph, and Activity views β€” updating in realtime via SSE as agents work. -![Social view showing grouped task cards with agent threads and dependency context](docs/screenshots/image-9.png) +### The CLI (`bb`) +A full agent command center β€” not just a dashboard launcher: -### Graph View β€” see the blockers before they block you +```bash +# Agent lifecycle +bb agent register --name --role +bb agent list +bb agent activity-lease --agent -DAG visualization of your task graph using XYFlow and Dagre layout. Blocked chains are highlighted. Assignees appear on nodes. Use topology to drive assignment decisions, not gut feel. +# Agent-to-agent communication +bb agent send --from --to --bead --category HANDOFF --subject "..." +bb agent inbox --agent +bb agent ack --agent --message -![Dependency graph showing task DAG with blocker highlighting](docs/screenshots/image-8.png) +# Work reservations +bb agent reserve --agent --scope --bead +bb agent release --agent --scope -### Activity View β€” realtime operations feed +# Orchestrator runtime +bb daemon start +bb daemon tui # interactive orchestrator REPL +bb daemon bootstrap # install Pi runtime +``` -Live stream of session events, state transitions, and agent mail. Updates via file watchers and Server-Sent Events β€” no polling, no manual refresh. +### The Orchestrator ([bb-pi](#-bb-pi-orchestrator)) +A built-in execution runtime that spawns and manages typed worker agents. -### Swarm Coordination β€” agent pools and assignment queues +--- -Monitor your agent pool with archetypes and a squad roster. "Needs Agent" and pre-assigned queues let you drive work assignment from the dashboard. +## 🧩 Core Features -![Swarm coordination panel showing agent pool, archetypes, and assignment queues](docs/screenshots/image-7.png) +### πŸ’¬ Agent Communication System -### Agent Mail β€” structured inter-agent messaging +Structured message lifecycle for inter-agent coordination: -`HANDOFF`, `BLOCKED`, `DECISION`, `INFO` categories. High-signal categories require explicit acknowledgment. Per-task threads merge activity events, agent mail, and manual notes. +- **Message categories**: `HANDOFF`, `BLOCKED`, `DECISION`, `INFO` +- **Required acknowledgment** for high-signal categories (`HANDOFF`, `BLOCKED`) +- **Broadcast & role-based routing** β€” send to all agents or by role (`role:tester`) +- **Per-task threads** combining activity events, agent mail, and local interactions +- **Message states**: `unread` β†’ `read` β†’ `acked` ```bash bd mail inbox @@ -94,28 +175,63 @@ bd mail send --to --bead --category HANDOFF --subject "Ready for re bd mail ack ``` -### Multi-Project Scope +### πŸ”’ Work Reservations -Scanner-backed project registry. Switch between single-project and aggregate views at runtime without leaving the workspace. +Agents can lock scopes (file paths, task regions) to prevent conflicting work: +- TTL-based reservations (default 120 min) +- Liveness-aware conflict resolution β€” stale agents (15min no heartbeat) can be taken over +- File-based mutex prevents race conditions + +### πŸ“Š DAG Graph Visualization + +DAG-oriented workspace for execution decisions: + +- Task and dependency tab modes for different planning lenses +- Blocked chains highlighted, assignees on nodes +- Cycle detection and blocked-chain identification + +![Dependency Graph View](docs/screenshots/image-8.png) + +### πŸ‘₯ Swarm Coordination + +Agent pool monitor with: + +- **Archetypes** β€” typed agent roles (architect, engineer, reviewer, tester, investigator, shipper) +- **Templates** β€” preset team compositions (`feature-dev`, `bug-fix`, `full-squad`, `greenfield`, `research-and-discovery`) +- "Needs Agent" queue for unassigned work +- Pre-assigned queue and squad roster + +![Swarm Coordination Panel](docs/screenshots/image-7.png) + +### πŸ“‘ Realtime Operations + +- Live updates via Chokidar file watchers + Server-Sent Events +- Activity stream with session/task context +- Agent heartbeat and liveness tracking (active β†’ stale β†’ evicted) + +### 🌐 Multi-Project Scope + +- Project registry with scanner-backed discovery +- Single-project and aggregate modes +- Runtime scope switching without leaving the workspace --- -## bb-pi Orchestrator +## πŸ€– bb-pi Orchestrator -> **Under active construction.** The orchestrator works, but it's new and has rough edges. For now: run your own coding agent alongside BeadBoard and use the dashboard to coordinate. Help improving it is welcome. +> 🚧 **Under active construction.** The orchestrator works but has known issues being fixed. Use your own coding agent alongside BeadBoard for now, or help us improve it! -BeadBoard doesn't just watch your agents β€” it can run them. - -`bb-pi` is BeadBoard's embedded execution runtime, built on [Pi](https://github.com/badlogic/pi-mono). It exposes a long-lived orchestrator per project that spawns typed worker agents, tracks their bead claims, and streams a live transcript into the left panel. +bb-pi is BeadBoard's embedded execution runtime, built on [Pi](https://github.com/badlogic/pi-mono) ([@mariozechner/pi-coding-agent](https://www.npmjs.com/package/@mariozechner/pi-coding-agent)). It runs a long-lived orchestrator per project that spawns typed worker agents, tracks their bead claims, and streams a live transcript. **Working today (Phases 1-3):** -- Embedded orchestrator with BeadBoard-aware tools (`bb_spawn_worker`, `bb_worker_status`, `bb_create`, `bb_close`, and more) +- Embedded orchestrator with BeadBoard-aware tools (`bb_spawn_worker`, `bb_worker_status`, `bb_create`, `bb_close`, etc.) - Worker spawning with numbered display names (Engineer 01, Engineer 02...) -- Capability-gated agent types: architect, engineer, reviewer, tester, investigator, shipper -- Template-based team spawning (`bb_spawn_team`) -- Bead-required workflow β€” every worker task claims a bead, posts progress, closes with evidence +- **Capability-gated agent types** β€” architects/reviewers get read-only tools, engineers/testers get full code edit/write/bash +- **Template-based team spawning** via `bb_spawn_team` β€” spin up a full squad from a preset +- Bead-required workflow β€” every worker claims a bead, posts progress, closes with evidence - Async coordination β€” non-blocking spawn with status polling and result reads - Chat-style orchestrator transcript with realtime telemetry +- Interactive orchestrator REPL via `bb daemon tui` **Known issues being fixed:** - Double-reply rendering in orchestrator chat @@ -126,123 +242,128 @@ BeadBoard doesn't just watch your agents β€” it can run them. --- -## For AI Agents - -BeadBoard is designed to be operated by agents, not just watched by humans. Give your agent the operating contract: - -```bash -npx skills add zenchantlive/beadboard --skill beadboard-driver -``` - -Then add to your project's `AGENTS.md` or `CLAUDE.md`: - -```markdown -## BeadBoard - -You have access to the **beadboard-driver** skill. - -Use it as your entrypoint for all coordination work: claiming tasks, posting progress, -reading context, and following verification rules. When in doubt about what to do next -or how to record state, call beadboard-driver rather than editing markdown ad hoc. -``` - -Full operating manual: [AGENTS.md](AGENTS.md). Skill runbook: [skills/beadboard-driver/SKILL.md](skills/beadboard-driver/SKILL.md). - -| Command | Role | -|---------|------| -| `bd` | Beads CLI β€” task and dependency management. Also: `npm install -g @beads/bd` | -| `bb` / `beadboard` | BeadBoard CLI β€” dashboard launcher and orchestrator interface | - ---- - -## Architecture +## πŸ—οΈ Architecture ``` -.beads/issues.jsonl <-- bd CLI (sole write interface) - | - +-- Chokidar watcher (JSONL + WAL + .last_touched) - | | - | IssuesEventBus - | | - | SSE /api/events --> browser (live) - | - +-- Aggregate read --> Dolt SQL (primary, if running) - issues.jsonl (fallback) +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ BeadBoard UI β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Social β”‚ β”‚ Graph β”‚ β”‚ Activity β”‚ β”‚ Swarm β”‚ β”‚ +β”‚ β”‚ View β”‚ β”‚ View β”‚ β”‚ View β”‚ β”‚ Panel β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ β”‚ β”‚ + β”Œβ”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β” + β”‚ bb CLI / bb-pi runtime β”‚ + β”‚ agent register Β· agent send Β· daemon tui Β· spawn β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ β”‚ β”‚ + β”Œβ”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β” + β”‚ SSE β”‚ β”‚ Dolt β”‚ β”‚ Chokidar β”‚ + β”‚ Events β”‚ β”‚ (SQL DB) β”‚ β”‚ Watchers β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β” + β”‚ bd β”‚ + β”‚ (Beads CLI) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` -All views live at `/` with query-param switching (`?view=social|graph|activity`). The `bd` CLI is the only write path β€” BeadBoard never writes to `.beads/issues.jsonl` directly. +### Tech Stack | Layer | Technologies | |-------|-------------| | Frontend | Next.js 15 (App Router), React 19, TypeScript (strict) | | Styling | Tailwind CSS, Radix UI, Framer Motion | | Graph | @xyflow/react, Dagre | -| Realtime | Chokidar, Server-Sent Events | -| Database | Dolt (recommended, version-controlled SQL) | -| Agent runtime | @mariozechner/pi-coding-agent (bb-pi, under construction) | +| Database | Dolt (version-controlled SQL) | +| Realtime | Chokidar watchers, Server-Sent Events | +| Agent Runtime | @mariozechner/pi-coding-agent (bb-pi) | + +### Data Flow + +1. **Write path**: `bd` commands write to `.beads/issues.jsonl` and Dolt DB +2. **Read path**: UI queries Dolt SQL (falls back to JSONL when Dolt is unavailable) +3. **Realtime**: `bd` touches `.beads/last-touched` β†’ Chokidar fires β†’ SSE event β†’ UI update + +### Key Concepts + +| Component | Purpose | +|-----------|---------| +| `bd` | Beads CLI β€” task and dependency management | +| `bb` / `beadboard` | BeadBoard CLI β€” dashboard, orchestrator host, agent commands | +| `bb-pi` | Embedded Pi execution runtime (under construction) | +| `beadboard-driver` | Agent skill β€” operating contract for coordination | --- -## CLI Reference - -### bd (Beads CLI) - -```bash -bd init # initialize Beads in a project -bd create --title "Task title" --type task -p 1 # create a task bead -bd ready # list unblocked work -bd show # show bead detail -bd update --status in_progress # update a bead -bd close --reason "Done" # close a bead -bd dep relate --type parent-child -bd mail inbox -bd mail send --to --bead --category HANDOFF --subject "..." -bd dolt start -bd dolt pull && bd dolt push -``` - -### bb / beadboard (Dashboard CLI) - -```bash -beadboard start # start the dashboard -beadboard start --dolt # start with Dolt backend -beadboard open # open in browser -beadboard status # check runtime status -``` - -### Development - -```bash -npm run dev # Next.js dev server (localhost:3000) -npm run build # production build -npm run typecheck # tsc --noEmit -npm run lint # eslint -npm run test # full test suite -``` - ---- - -## Platform Support +## 🌍 Platform Support Runs on macOS, Linux, and Windows. -- **macOS / Linux:** Use `install/install.sh` to install `beadboard` and `bb` shims to `~/.beadboard/bin`. -- **Windows:** Path handling canonicalizes drive letter casing and backslash normalization. Mixed WSL2 + Windows setups require mirrored networking β€” see [AGENTS.md](AGENTS.md). +- **macOS / Linux**: `bash ./install/install.sh` installs shims to `~/.beadboard/bin` +- **Windows**: Path handling canonicalizes drive letter casing and backslash normalization. Mixed WSL2 + Windows setups require mirrored networking. --- -## Contributing +## πŸ“ Project Structure + +```text +beadboard/ +β”œβ”€β”€ src/ +β”‚ β”œβ”€β”€ app/ # Next.js App Router pages + API routes +β”‚ β”œβ”€β”€ components/ # UI: shared, graph, social, swarm, agents, sessions +β”‚ β”œβ”€β”€ hooks/ # React hooks (subscriptions, URL state, etc.) +β”‚ β”œβ”€β”€ lib/ # Core domain logic (parser, types, mail, registry, etc.) +β”‚ └── tui/ # Orchestrator TUI + agent tools +β”œβ”€β”€ skills/ +β”‚ └── beadboard-driver/ # Agent skill package (runbook + scripts + tests) +β”œβ”€β”€ install/ # Platform install scripts +β”œβ”€β”€ docs/ # PRDs, roadmaps, ADRs, screenshots +└── tests/ # Test suite (explicitly enumerated in package.json) +``` + +--- + +## πŸ› οΈ Scripts + +```bash +npm run dev # Development server (localhost:3000) +npm run build # Production build +npm run start # Production server +npm run typecheck # TypeScript validation (tsc --noEmit) +npm run lint # ESLint +npm run test # Full test suite +``` + +> New test files must be added to the `test` script in `package.json` β€” the suite is explicitly enumerated, not auto-discovered. + +--- + +## 🀝 Contributing + +1. Fork the repository +2. Create a feature branch: `git checkout -b feature/my-feature` +3. Run quality gates before submitting: ```bash npm run typecheck && npm run lint && npm run test ``` -Run that before submitting. Keep new features in `src/lib`, `src/components`, and `src/hooks` β€” not in `src/app` unless it's a route. New test files must be registered in the `test` script in `package.json` (the suite is explicit, not auto-discovered). PR against `main`. +4. Submit a pull request against `main` --- -## License +## πŸ“„ License [MIT](LICENSE) -Built on [Beads](https://github.com/steveyegge/beads) by [Steve Yegge](https://github.com/steveyegge), inspired by [Gastown](https://github.com/steveyegge/gastown). Embedded execution runtime uses [@mariozechner](https://github.com/mariozechner)'s [Pi SDK](https://github.com/badlogic/pi-mono). +--- + +## πŸ™ Acknowledgments + +Built on [Beads](https://github.com/steveyegge/beads) by [Steve Yegge](https://github.com/steveyegge), inspired by [Gastown](https://github.com/steveyegge/gastown). The bb-pi execution runtime uses [Pi](https://github.com/badlogic/pi-mono) by [@mariozechner](https://github.com/mariozechner). From 4c9a1786dbc01a9f7103ab57153947ebedab9ed0 Mon Sep 17 00:00:00 2001 From: zenchantlive <103866469+zenchantlive@users.noreply.github.com> Date: Tue, 24 Mar 2026 21:24:06 -0500 Subject: [PATCH 4/6] Fix formatting and clarify installation instructions --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 31ae9ef..2424eee 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ This installs the [beadboard-driver](skills/beadboard-driver/SKILL.md) skill β€” Or just tell your agent: -> Install the beadboard-driver skill from https://github.com/zenchantlive/beadboard and use it to coordinate your work. Run `npx skills add zenchantlive/beadboard --skill beadboard-driver` then follow the SKILL.md runbook. +> Install Beadboard, and the beadboard-driver skill from https://github.com/zenchantlive/beadboard and use it to coordinate your work. Run `npx skills add zenchantlive/beadboard --skill beadboard-driver` then follow the SKILL.md runbook. Then add to your project's `AGENTS.md` or `CLAUDE.md`: From f29c0e3cba39beac32f41e499f6dcaf0902108f4 Mon Sep 17 00:00:00 2001 From: zenchantlive Date: Wed, 25 Mar 2026 00:22:47 -0500 Subject: [PATCH 5/6] feat: add CONTRIBUTING.md, GitHub Issue templates, contrib:open label convention CONTRIBUTING.md: - Two tracks: humans (GitHub flow) and agents (beadboard-driver + bd) - Copy-pasteable agent instructions for quick setup - PR size guidelines (under 100 lines preferred, 200+ needs issue first) - Quality gates, claim workflow, professional conduct expectations - beadboard-driver and bd setup for agent contributors GitHub Issue templates: - Bug report: structured fields (steps, platform, Dolt status, versions) - Feature request: problem/proposal/area, opt-in to implement - Config: links to Discord and contrib:open issue filter contrib:open labels: - Tagged 4 orchestrator beads for community contribution - Left session race condition (beadboard-4v7) as internal README: - Updated banner to link to CONTRIBUTING.md - Updated Contributing section with Discord link and contrib:open workflow Co-Authored-By: Claude Opus 4.6 (1M context) --- .beads/issues.jsonl | 8 +- .github/ISSUE_TEMPLATE/bug_report.yml | 75 +++++++++ .github/ISSUE_TEMPLATE/config.yml | 9 ++ .github/ISSUE_TEMPLATE/feature_request.yml | 56 +++++++ CONTRIBUTING.md | 170 +++++++++++++++++++++ README.md | 17 ++- 6 files changed, 323 insertions(+), 12 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 CONTRIBUTING.md diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 8525e2d..d51d0bd 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -262,11 +262,11 @@ {"id":"bb-6aj.4","title":"Implement aggregate project issue context model","description":"Define normalized project identity payload attached to every issue for cross-project Kanban, timeline, and session views.","acceptance_criteria":"Aggregated read output always includes stable project metadata.","status":"closed","priority":1,"issue_type":"task","assignee":"zenchantlive","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T01:11:52Z","created_by":"zenchantlive","updated_at":"2026-02-12T03:45:22Z","closed_at":"2026-02-12T03:45:22Z","close_reason":"Added project context model and attached to read issues.","labels":["aggregation","data-model"],"dependencies":[{"issue_id":"bb-6aj.4","depends_on_id":"bb-6aj","type":"parent-child","created_at":"2026-02-12T01:11:52Z","created_by":"zenchantlive","metadata":"{}"},{"issue_id":"bb-6aj.4","depends_on_id":"bb-6aj.2","type":"blocks","created_at":"2026-02-12T01:12:28Z","created_by":"zenchantlive","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0} {"id":"bb-92d.4.1","title":"Add parser tests for priority=0, tombstone filtering, and dependency parsing","description":"Create focused tests that protect parser behavior for critical edge cases and dependency structures used by graph/timeline views.","acceptance_criteria":"Tests fail before implementation and pass after parser is complete.","status":"closed","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T01:11:45Z","created_by":"zenchantlive","updated_at":"2026-02-12T01:26:37Z","closed_at":"2026-02-12T01:26:37Z","close_reason":"Added parser behavior tests for defaults, malformed lines, tombstones, and priority=0.","labels":["parser","tests"],"dependencies":[{"issue_id":"bb-92d.4.1","depends_on_id":"bb-92d.4","type":"parent-child","created_at":"2026-02-12T01:11:45Z","created_by":"zenchantlive","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0} {"id":"bb-92d.2","title":"Add MIT license and baseline repository docs","description":"Add LICENSE and baseline docs that state Windows-native support, read/write boundaries, and required runtime dependencies.","acceptance_criteria":"MIT license present and docs describe core architecture constraints.","status":"closed","priority":1,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-12T01:11:43Z","created_by":"zenchantlive","updated_at":"2026-02-12T01:23:51Z","closed_at":"2026-02-12T01:23:51Z","close_reason":"Added MIT license and baseline repository documentation with architecture boundary rules.","labels":["docs","license"],"dependencies":[{"issue_id":"bb-92d.2","depends_on_id":"bb-92d","type":"parent-child","created_at":"2026-02-12T01:11:43Z","created_by":"zenchantlive","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0} -{"id":"beadboard-28z","title":"Bug: unbounded event array in embedded-daemon","description":"EmbeddedPiDaemon stores RuntimeConsoleEvents in an array per project with no eviction policy. A long-running server accumulates events without bound, leading to memory growth. Add a cap (e.g. 1000 events) with oldest-first eviction.","status":"open","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-03-25T00:03:11Z","created_by":"zenchantlive","updated_at":"2026-03-25T00:03:11Z","labels":["bug","orchestrator"],"dependency_count":0,"dependent_count":0,"comment_count":0} -{"id":"beadboard-bnx","title":"Cleanup: remove hardcoded clawdbot path from pi-runtime-detection","description":"pi-runtime-detection.ts line 50 has a hardcoded fallback path '/home/clawdbot/npm-global/lib/node_modules/@mariozechner/pi-coding-agent' β€” a WSL-specific remnant from dev. It's inert by default (allowLinkedPi=false) but should be removed before shipping to external users.","status":"open","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-03-25T00:03:08Z","created_by":"zenchantlive","updated_at":"2026-03-25T00:03:08Z","labels":["cleanup","orchestrator"],"dependency_count":0,"dependent_count":0,"comment_count":0} +{"id":"beadboard-28z","title":"Bug: unbounded event array in embedded-daemon","description":"EmbeddedPiDaemon stores RuntimeConsoleEvents in an array per project with no eviction policy. A long-running server accumulates events without bound, leading to memory growth. Add a cap (e.g. 1000 events) with oldest-first eviction.","status":"open","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-03-25T00:03:11Z","created_by":"zenchantlive","updated_at":"2026-03-25T00:03:11Z","labels":["bug","contrib:open","orchestrator"],"dependency_count":0,"dependent_count":0,"comment_count":0} +{"id":"beadboard-bnx","title":"Cleanup: remove hardcoded clawdbot path from pi-runtime-detection","description":"pi-runtime-detection.ts line 50 has a hardcoded fallback path '/home/clawdbot/npm-global/lib/node_modules/@mariozechner/pi-coding-agent' β€” a WSL-specific remnant from dev. It's inert by default (allowLinkedPi=false) but should be removed before shipping to external users.","status":"open","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-03-25T00:03:08Z","created_by":"zenchantlive","updated_at":"2026-03-25T00:03:08Z","labels":["cleanup","contrib:open","orchestrator"],"dependency_count":0,"dependent_count":0,"comment_count":0} {"id":"beadboard-4v7","title":"Bug: session race condition in pi-daemon-adapter","description":"getOrCreateSession in pi-daemon-adapter.ts is not async-safe. If two prompts arrive before the first Pi SDK session resolves, both hit the creation branch and two sessions get created. The second overwrites the first in activeSessions map, leaking the first session. Fix: add a session creation lock/promise cache per project root.","status":"open","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-03-25T00:03:04Z","created_by":"zenchantlive","updated_at":"2026-03-25T00:03:04Z","labels":["bug","orchestrator"],"dependency_count":0,"dependent_count":0,"comment_count":0} -{"id":"beadboard-cho","title":"Bug: silent failures in orchestrator UX","description":"Launch failure, bootstrap failure on mount, and prompt fetch failures are all silently caught with empty catch blocks. User sees nothing happen when things fail. Surface errors via runtime console events or error state in the UI. Key locations: unified-shell.tsx bootstrapRuntime catch, handleAskOrchestrator catch, orchestrator-panel.tsx submit catch.","status":"open","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-03-25T00:03:01Z","created_by":"zenchantlive","updated_at":"2026-03-25T00:03:01Z","labels":["bug","orchestrator"],"dependency_count":0,"dependent_count":0,"comment_count":0} -{"id":"beadboard-sen","title":"Bug: orchestrator double-reply rendering","description":"pi-daemon-adapter.ts emits both text_delta and text_done as 'Orchestrator Reply' events, causing every assistant message to appear twice in the chat UI. The text_done handler re-emits the full concatenated text that was already streamed via deltas. Fix: suppress the duplicate text_done emission or deduplicate by content hash.","status":"open","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-03-25T00:02:58Z","created_by":"zenchantlive","updated_at":"2026-03-25T00:02:58Z","labels":["bug","orchestrator"],"dependency_count":0,"dependent_count":0,"comment_count":0} +{"id":"beadboard-cho","title":"Bug: silent failures in orchestrator UX","description":"Launch failure, bootstrap failure on mount, and prompt fetch failures are all silently caught with empty catch blocks. User sees nothing happen when things fail. Surface errors via runtime console events or error state in the UI. Key locations: unified-shell.tsx bootstrapRuntime catch, handleAskOrchestrator catch, orchestrator-panel.tsx submit catch.","status":"open","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-03-25T00:03:01Z","created_by":"zenchantlive","updated_at":"2026-03-25T00:03:01Z","labels":["bug","contrib:open","orchestrator"],"dependency_count":0,"dependent_count":0,"comment_count":0} +{"id":"beadboard-sen","title":"Bug: orchestrator double-reply rendering","description":"pi-daemon-adapter.ts emits both text_delta and text_done as 'Orchestrator Reply' events, causing every assistant message to appear twice in the chat UI. The text_done handler re-emits the full concatenated text that was already streamed via deltas. Fix: suppress the duplicate text_done emission or deduplicate by content hash.","status":"open","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-03-25T00:02:58Z","created_by":"zenchantlive","updated_at":"2026-03-25T00:02:58Z","labels":["bug","contrib:open","orchestrator"],"dependency_count":0,"dependent_count":0,"comment_count":0} {"id":"bb-1d1","title":"test-swarm-2","status":"open","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-16T07:56:22Z","created_by":"zenchantlive","updated_at":"2026-02-16T07:56:22Z","labels":["gt:agent","swarm:test-swarm-1"],"dependency_count":0,"dependent_count":0,"comment_count":0} {"id":"bb-zzr","title":"test-swarm-3","status":"open","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-16T07:56:22Z","created_by":"zenchantlive","updated_at":"2026-02-16T07:56:22Z","labels":["gt:agent","swarm:test-swarm-1"],"dependency_count":0,"dependent_count":0,"comment_count":0} {"id":"bb-5pw","title":"test-swarm-1","status":"open","priority":2,"issue_type":"task","owner":"jordanlive121@gmail.com","created_at":"2026-02-16T07:56:16Z","created_by":"zenchantlive","updated_at":"2026-02-16T07:56:16Z","labels":["gt:agent","swarm:test-swarm-1"],"dependency_count":0,"dependent_count":0,"comment_count":0} diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..613155c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,75 @@ +name: Bug Report +description: Something is broken +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for reporting! A maintainer will create a corresponding bead to track this. + + - type: input + id: summary + attributes: + label: What happened? + description: One sentence. + placeholder: "Dashboard crashes when opening graph view with no Dolt running" + validations: + required: true + + - type: textarea + id: steps + attributes: + label: Steps to reproduce + description: What did you do to hit this? + placeholder: | + 1. Clone repo, npm install + 2. Run `beadboard start` (no Dolt) + 3. Click Graph tab + 4. See error in console + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected behavior + description: What should have happened? + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual behavior + description: What happened instead? Include error messages if any. + validations: + required: true + + - type: input + id: platform + attributes: + label: Platform + description: OS and version + placeholder: "macOS 15.3 / Windows 11 / Ubuntu 24.04" + validations: + required: true + + - type: input + id: versions + attributes: + label: Versions + description: "Output of: node -v, bd --version, beadboard --version" + placeholder: "Node 20.11, bd 0.61.0, beadboard 0.1.0" + validations: + required: false + + - type: dropdown + id: dolt + attributes: + label: Dolt installed? + options: + - "Yes, running" + - "Yes, not running" + - "No" + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..8d9abb9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,9 @@ +blank_issues_enabled: true +contact_links: + - name: Discord + # TODO: replace with actual Discord invite link + url: https://discord.gg/YOUR_INVITE + about: Chat with the community, coordinate on contributions, get help + - name: Available work + url: https://github.com/zenchantlive/beadboard/issues?q=is%3Aissue+is%3Aopen+label%3Acontrib%3Aopen + about: Browse issues tagged for community contribution diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..5a9d3c7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,56 @@ +name: Feature Request +description: Suggest something new +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Got an idea? Describe it below. If it's approved, we'll create a bead and tag it `contrib:open` if it's available for community work. + + - type: input + id: summary + attributes: + label: What do you want? + description: One sentence. + placeholder: "A public 'contribute' view in the dashboard showing contrib:open beads" + validations: + required: true + + - type: textarea + id: problem + attributes: + label: What problem does this solve? + description: Why do you need this? What's the pain without it? + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: How should it work? + description: Describe the behavior you're imagining. Doesn't need to be detailed β€” just enough to understand the idea. + validations: + required: false + + - type: dropdown + id: area + attributes: + label: Area + options: + - Dashboard (UI/views) + - CLI (bb/beadboard) + - Orchestrator (bb-pi) + - Agent communication (mail/reservations) + - Beads integration (bd) + - beadboard-driver skill + - Documentation + - Other + validations: + required: true + + - type: checkboxes + id: contribution + attributes: + label: Would you like to work on this? + options: + - label: "I'd like to implement this myself (or have my agent do it)" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ec749de --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,170 @@ +# Contributing to BeadBoard + +We welcome contributions β€” from humans, AI agents, or both working together. This guide covers how to contribute well regardless of how you write your code. + + +**[Join the Discord](https://discord.gg/YOUR_INVITE)** if you want to discuss ideas, coordinate on larger work, or just say hi. + +--- + +## Finding work + +There are two ways to find things to work on: + +**GitHub Issues** β€” the public-facing list. Browse [open issues](https://github.com/zenchantlive/beadboard/issues) for bugs, feature requests, and help-wanted items. + +**Beads** β€” if you have `bd` installed, you can see work tagged for community contribution: + +```bash +bd list --label contrib:open +``` + +These are curated tasks that are scoped, unblocked, and ready for someone to pick up. If you want to work on one, comment on the linked GitHub Issue (or open one if there isn't one) so we know you're on it. + +--- + +## Before you start + +### Quality gates + +Every PR must pass these before review: + +```bash +npm run typecheck && npm run lint && npm run test +``` + +If these fail, fix them. PRs with failing gates will be closed without review. + +### Claim your work + +Comment on the GitHub Issue before starting. This prevents two people from working on the same thing. If you're using `bd`: + +```bash +bd update --status in_progress --assignee +``` + +--- + +## PR guidelines + +### Keep PRs small and focused + +- **Under ~100 lines** β€” merge fast, review easy, everyone's happy +- **One issue per PR** β€” don't bundle unrelated changes +- **Over ~200 lines** β€” open an issue first to discuss the approach. Large unsolicited PRs are hard to review and often get closed + +### What makes a good PR + +- Clear title that says what changed (not "fix stuff" or "update code") +- Reference the GitHub Issue: `Fixes #22` or `Relates to #15` +- Tests for new functionality +- Don't break existing tests +- If you changed behavior, say why + +### What will get your PR closed + +- Failing quality gates +- Unrelated changes bundled together +- Reformatting code you didn't otherwise change +- No description or context +- Ignoring review feedback + +--- + +## For AI agents + +We're an agent-first project β€” AI-assisted contributions are not just tolerated, they're the point. Here's how to set up properly: + +### Option 1: Use beadboard-driver (recommended) + +```bash +npx skills add zenchantlive/beadboard --skill beadboard-driver +``` + +This gives your agent the full operating contract: environment validation, bead workflow, mail coordination, verification gates. The [SKILL.md runbook](skills/beadboard-driver/SKILL.md) walks through the 9-step session lifecycle. + +### Option 2: Just use bd + the gates + +```bash +npm install -g @beads/bd +cd beadboard +bd list --label contrib:open # find available work +# ... do the work ... +npm run typecheck && npm run lint && npm run test +``` + +### Tell your agent + +You can paste this into your agent's context: + +> You're contributing to BeadBoard (https://github.com/zenchantlive/beadboard), a multi-agent orchestration system built on Beads. Clone the repo, run `npm install`, then check `bd list --label contrib:open` for available work. Install the beadboard-driver skill with `npx skills add zenchantlive/beadboard --skill beadboard-driver` and follow the SKILL.md runbook. Run `npm run typecheck && npm run lint && npm run test` before submitting. Keep PRs under 100 lines and reference the GitHub Issue. + +### Agent-specific notes + +- Your agent should be able to run the quality gates and fix failures autonomously +- If your agent creates a PR, you (the human) are responsible for it β€” check that it makes sense before submitting +- Agent PRs follow the same size guidelines as human PRs +- If you want your agent to take on larger work, join the Discord and coordinate with us first + +--- + +## Bead labels for contributors + +| Label | Meaning | +|-------|---------| +| `contrib:open` | Available for community contribution β€” scoped, unblocked, ready | +| `bug` | Something is broken | +| `cleanup` | Code quality, dead code, refactoring | +| `orchestrator` | Related to bb-pi (under construction β€” help welcome!) | + +--- + +## Development setup + +```bash +git clone https://github.com/zenchantlive/beadboard.git +cd beadboard +npm install +npm run dev # http://localhost:3000 +``` + +### Install Dolt (recommended) + +```bash +brew install dolt # macOS +# or: curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash +``` + +### Run a single test + +```bash +node --import tsx --test tests/lib/parser.test.ts +``` + +New test files must be added to the `test` script in `package.json` β€” the suite is explicitly enumerated. + +--- + +## Code guidelines + +- Keep runtime pages minimal in `src/app` β€” promote logic to `src/lib`, `src/components`, `src/hooks` +- Follow existing TypeScript and React patterns in the codebase +- Don't refactor code you're not otherwise changing +- Don't add comments, docstrings, or type annotations to untouched code + +--- + +## Be professional + +This is an open source project maintained by volunteers. That means: + +- Respond to review feedback. If a maintainer asks you to change something, change it or explain why not. +- Don't argue with rejections. If your PR is closed, it's not personal. +- Don't open the same PR twice after it's been closed. +- If you're stuck or unsure, ask in the Discord before submitting. + +--- + +## License + +By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE). diff --git a/README.md b/README.md index 44aa826..673e58d 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -## 🚧 Orchestrator is working but new β€” use your own coding agent for now (unless you want to help!) 🚧 +## 🚧 The bb-pi orchestrator is under construction β€” [help us build it!](CONTRIBUTING.md) Use your own coding agent alongside BeadBoard for now. 🚧 # BeadBoard @@ -348,15 +348,16 @@ npm run test # Full test suite ## 🀝 Contributing -1. Fork the repository -2. Create a feature branch: `git checkout -b feature/my-feature` -3. Run quality gates before submitting: +We welcome contributions from humans and AI agents. See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full guide. -```bash -npm run typecheck && npm run lint && npm run test -``` +Quick version: +1. Find work: check [GitHub Issues](https://github.com/zenchantlive/beadboard/issues) or run `bd list --label contrib:open` +2. Small PRs preferred (under ~100 lines). For larger changes, open an issue first. +3. Run the gates: `npm run typecheck && npm run lint && npm run test` +4. PR against `main` -4. Submit a pull request against `main` + +**[Join the Discord](https://discord.gg/YOUR_INVITE)** to discuss contributions, get help, or coordinate on larger work. --- From 2125431ab82153461a2d9b5095b1991009aa331c Mon Sep 17 00:00:00 2001 From: zenchantlive Date: Wed, 25 Mar 2026 00:48:04 -0500 Subject: [PATCH 6/6] chore: swap Discord for GitHub Discussions Co-Authored-By: Claude Opus 4.6 (1M context) --- .github/ISSUE_TEMPLATE/config.yml | 5 ++--- CONTRIBUTING.md | 7 +++---- README.md | 3 +-- 3 files changed, 6 insertions(+), 9 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 8d9abb9..d8721be 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,8 +1,7 @@ blank_issues_enabled: true contact_links: - - name: Discord - # TODO: replace with actual Discord invite link - url: https://discord.gg/YOUR_INVITE + - name: Discussions + url: https://github.com/zenchantlive/beadboard/discussions about: Chat with the community, coordinate on contributions, get help - name: Available work url: https://github.com/zenchantlive/beadboard/issues?q=is%3Aissue+is%3Aopen+label%3Acontrib%3Aopen diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ec749de..a2d3d4b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,8 +2,7 @@ We welcome contributions β€” from humans, AI agents, or both working together. This guide covers how to contribute well regardless of how you write your code. - -**[Join the Discord](https://discord.gg/YOUR_INVITE)** if you want to discuss ideas, coordinate on larger work, or just say hi. +**[Join the Discussion](https://github.com/zenchantlive/beadboard/discussions)** if you want to discuss ideas, coordinate on larger work, or just say hi. --- @@ -104,7 +103,7 @@ You can paste this into your agent's context: - Your agent should be able to run the quality gates and fix failures autonomously - If your agent creates a PR, you (the human) are responsible for it β€” check that it makes sense before submitting - Agent PRs follow the same size guidelines as human PRs -- If you want your agent to take on larger work, join the Discord and coordinate with us first +- If you want your agent to take on larger work, start a Discussion and coordinate with us first --- @@ -161,7 +160,7 @@ This is an open source project maintained by volunteers. That means: - Respond to review feedback. If a maintainer asks you to change something, change it or explain why not. - Don't argue with rejections. If your PR is closed, it's not personal. - Don't open the same PR twice after it's been closed. -- If you're stuck or unsure, ask in the Discord before submitting. +- If you're stuck or unsure, ask in [Discussions](https://github.com/zenchantlive/beadboard/discussions) before submitting. --- diff --git a/README.md b/README.md index 673e58d..fca0b8f 100644 --- a/README.md +++ b/README.md @@ -356,8 +356,7 @@ Quick version: 3. Run the gates: `npm run typecheck && npm run lint && npm run test` 4. PR against `main` - -**[Join the Discord](https://discord.gg/YOUR_INVITE)** to discuss contributions, get help, or coordinate on larger work. +**[Join the Discussion](https://github.com/zenchantlive/beadboard/discussions)** to coordinate on contributions, get help, or discuss ideas. ---