Merge pull request #24 from zenchantlive/docs/cleanup-junk-files
Docs/cleanup junk files
This commit is contained in:
zenchantlive
GitHub
commit
efb6b06588
7 changed files with 534 additions and 411 deletions
|
|
@ -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}
|
||||
|
|
|
|||
75
.github/ISSUE_TEMPLATE/bug_report.yml
vendored
Normal file
75
.github/ISSUE_TEMPLATE/bug_report.yml
vendored
Normal file
|
|
@ -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
|
||||
8
.github/ISSUE_TEMPLATE/config.yml
vendored
Normal file
8
.github/ISSUE_TEMPLATE/config.yml
vendored
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
blank_issues_enabled: true
|
||||
contact_links:
|
||||
- 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
|
||||
about: Browse issues tagged for community contribution
|
||||
56
.github/ISSUE_TEMPLATE/feature_request.yml
vendored
Normal file
56
.github/ISSUE_TEMPLATE/feature_request.yml
vendored
Normal file
|
|
@ -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)"
|
||||
169
CONTRIBUTING.md
Normal file
169
CONTRIBUTING.md
Normal file
|
|
@ -0,0 +1,169 @@
|
|||
# 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 Discussion](https://github.com/zenchantlive/beadboard/discussions)** 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 <bead-id> --status in_progress --assignee <your-name>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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, start a Discussion 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 [Discussions](https://github.com/zenchantlive/beadboard/discussions) before submitting.
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).
|
||||
620
README.md
620
README.md
|
|
@ -1,14 +1,19 @@
|
|||
## 🚧 Orchastrator is wokring, 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
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://github.com/zenchantlive/beadboard/stargazers)
|
||||
[](https://github.com/steveyegge/beads)
|
||||
|
||||
**Multi-agent swarm coordination system for dependency-constrained work.**
|
||||
**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).
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Add BeadBoard to Your Agent
|
||||
|
|
@ -17,211 +22,154 @@ Built on [Beads](https://github.com/steveyegge/beads) and inspired by [Gastown](
|
|||
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
|
||||
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
|
||||
|
||||
## Installation
|
||||
Or just tell your agent:
|
||||
|
||||
> 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`:
|
||||
|
||||
```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.
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 📦 Installation
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Node.js** 18.18+ (Node 20 LTS recommended)
|
||||
- **npm** 7.0+
|
||||
- **Git** (for cloning and version control)
|
||||
- **[Dolt](https://github.com/dolthub/dolt)** (recommended — see [Dolt section](#-dolt))
|
||||
|
||||
### 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
|
||||
npm install -g .
|
||||
```
|
||||
|
||||
This installs:
|
||||
- `beadboard` - Dashboard launcher
|
||||
- `beadboard/bb(alias)` - CLI for ORchastrator (built in agent built on [Pi](https://github.com/badlogic/pi-mono)
|
||||
- `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
|
||||
- `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
|
||||
```
|
||||
|
||||
### Development Setup
|
||||
|
||||
For development or contributing:
|
||||
|
||||
**Alternative:** POSIX install script (Linux/macOS):
|
||||
```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 .
|
||||
bash ./install/install.sh # installs bb + beadboard shims to ~/.beadboard/bin
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Start the Dashboard
|
||||
## ⚡ Quick Start
|
||||
|
||||
```bash
|
||||
# Start with Dolt backend (recommended)
|
||||
beadboard start --dolt
|
||||
|
||||
# Or start without Dolt (limited features)
|
||||
beadboard start
|
||||
cd ~/my-project
|
||||
bd init # initialize Beads in your project
|
||||
beadboard start --dolt # start the dashboard with Dolt (recommended)
|
||||
```
|
||||
|
||||
Open [http://localhost:3000](http://localhost:3000) to access the coordination dashboard.
|
||||
|
||||
### Initialize a Project
|
||||
Open [http://localhost:3000](http://localhost:3000).
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## For AI Agents
|
||||
## 🗄️ Dolt
|
||||
|
||||
### Add BeadBoard to Your Agent
|
||||
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
|
||||
npx skills add zenchantlive/beadboard --skill beadboard-driver
|
||||
# macOS
|
||||
brew install dolt
|
||||
|
||||
# Linux / Windows
|
||||
curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash
|
||||
```
|
||||
|
||||
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)**
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## 🔧 What BeadBoard Does
|
||||
|
||||
---
|
||||
BeadBoard is three things:
|
||||
|
||||
## Quick Start
|
||||
### The Dashboard
|
||||
A live operations console with Social, Graph, and Activity views — updating in realtime via SSE as agents work.
|
||||
|
||||
### For Human Users
|
||||
### The CLI (`bb`)
|
||||
A full agent command center — not just a dashboard launcher:
|
||||
|
||||
```bash
|
||||
# Clone and install from source
|
||||
git clone https://github.com/zenchantlive/beadboard.git
|
||||
cd beadboard
|
||||
npm install -g .
|
||||
beadboard start
|
||||
# Agent lifecycle
|
||||
bb agent register --name <id> --role <role>
|
||||
bb agent list
|
||||
bb agent activity-lease --agent <id>
|
||||
|
||||
# Agent-to-agent communication
|
||||
bb agent send --from <id> --to <id> --bead <id> --category HANDOFF --subject "..."
|
||||
bb agent inbox --agent <id>
|
||||
bb agent ack --agent <id> --message <msg-id>
|
||||
|
||||
# Work reservations
|
||||
bb agent reserve --agent <id> --scope <scope> --bead <id>
|
||||
bb agent release --agent <id> --scope <scope>
|
||||
|
||||
# Orchestrator runtime
|
||||
bb daemon start
|
||||
bb daemon tui # interactive orchestrator REPL
|
||||
bb daemon bootstrap # install Pi runtime
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
### The Orchestrator ([bb-pi](#-bb-pi-orchestrator))
|
||||
A built-in execution runtime that spawns and manages typed worker agents.
|
||||
|
||||
---
|
||||
|
||||
Open [http://localhost:3000](http://localhost:3000) to access the dashboard.
|
||||
## 🧩 Core Features
|
||||
|
||||
---
|
||||
|
||||
## 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`:
|
||||
|
||||
```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.
|
||||
|
||||
```
|
||||
|
||||
### Key Concepts
|
||||
|
||||
| Component | Purpose |
|
||||
|-----------|---------|
|
||||
| `bd` | Beads CLI - task and dependency management |
|
||||
| `bb` | BeadBoard CLI - dashboard launcher |
|
||||
| `beadboard-driver` skill | Agent operating contract for coordination |
|
||||
|
||||
See [skills/beadboard-driver/SKILL.md](skills/beadboard-driver/SKILL.md) for the complete agent runbook.
|
||||
|
||||
---
|
||||
|
||||
## What BeadBoard Does
|
||||
|
||||
BeadBoard is an execution system for coordinating agents around shared Beads workflows:
|
||||
|
||||
- **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
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Core Features
|
||||
|
||||
### 1. Agent Communication System
|
||||
### 💬 Agent Communication System
|
||||
|
||||
Structured message lifecycle for inter-agent coordination:
|
||||
|
||||
- **Message states**: `unread`, `read`, `acked`
|
||||
- **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
|
||||
|
|
@ -229,144 +177,74 @@ bd mail send --to <agent> --bead <id> --category HANDOFF --subject "Ready for re
|
|||
bd mail ack <message-id>
|
||||
```
|
||||
|
||||
### 2. Swarm Coordination Surface
|
||||
### 🔒 Work Reservations
|
||||
|
||||
Agent Pool Monitor with:
|
||||
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
|
||||
|
||||
- Archetypes and templates for agent specialization
|
||||
- "Needs Agent" queue for unassigned work
|
||||
- Pre-assigned queue for reserved tasks
|
||||
- Squad roster for active team members
|
||||
|
||||
|
||||
|
||||
### 3. Graph + Dependency Topology
|
||||
### 📊 DAG Graph Visualization
|
||||
|
||||
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)
|
||||
- Task and dependency tab modes for different planning lenses
|
||||
- Blocked chains highlighted, assignees on nodes
|
||||
- Cycle detection and blocked-chain identification
|
||||
|
||||
|
||||
|
||||
|
||||
### 4. Global Project Scope + Scanner
|
||||
### 👥 Swarm Coordination
|
||||
|
||||
- Project registry and scanner-backed discovery
|
||||
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
|
||||
|
||||
|
||||
|
||||
### 📡 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
|
||||
|
||||
### 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
|
||||
## 🤖 bb-pi Orchestrator
|
||||
|
||||
> 🚧 **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!
|
||||
|
||||
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`, etc.)
|
||||
- Worker spawning with numbered display names (Engineer 01, Engineer 02...)
|
||||
- **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
|
||||
- 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).
|
||||
|
||||
---
|
||||
|
||||
## Installation & Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js `18.18+` (Node `20 LTS` recommended)
|
||||
- npm
|
||||
|
||||
### Clone + Install
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zenchantlive/beadboard.git
|
||||
cd beadboard
|
||||
npm install
|
||||
npm install -g .
|
||||
```
|
||||
|
||||
This makes `beadboard` and `bd` commands available globally.
|
||||
|
||||
**Alternative: Platform-specific wrappers**
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
### High-Level Design
|
||||
## 🏗️ Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
|
|
@ -376,188 +254,118 @@ Use social/activity views → monitor execution movement and operational events
|
|||
│ │ View │ │ View │ │ View │ │ Panel │ │
|
||||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌────────────┼────────────┐
|
||||
│ │ │
|
||||
┌─────▼─────┐ ┌────▼────┐ ┌────▼─────┐
|
||||
│ SSE │ │ Dolt │ │ Watchers│
|
||||
│ Events │ │ DB │ │ (Chokidar)│
|
||||
└───────────┘ └─────────┘ └──────────┘
|
||||
│ │ │
|
||||
└────────────┼────────────┘
|
||||
│
|
||||
┌──────▼──────┐
|
||||
│ bd │
|
||||
│ (Beads CLI)│
|
||||
└─────────────┘
|
||||
│ │ │ │
|
||||
┌────▼──────────────▼──────────────▼──────────────▼────┐
|
||||
│ bb CLI / bb-pi runtime │
|
||||
│ agent register · agent send · daemon tui · spawn │
|
||||
└──────────────────────────┬───────────────────────────┘
|
||||
│
|
||||
┌────────────────┼────────────────┐
|
||||
│ │ │
|
||||
┌─────▼─────┐ ┌──────▼──────┐ ┌──────▼──────┐
|
||||
│ SSE │ │ Dolt │ │ Chokidar │
|
||||
│ Events │ │ (SQL DB) │ │ Watchers │
|
||||
└───────────┘ └─────────────┘ └─────────────┘
|
||||
│ │ │
|
||||
└────────────────┼────────────────┘
|
||||
│
|
||||
┌──────▼──────┐
|
||||
│ bd │
|
||||
│ (Beads CLI) │
|
||||
└─────────────┘
|
||||
```
|
||||
|
||||
### 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 |
|
||||
| Graph | @xyflow/react, Dagre |
|
||||
| Database | Dolt (version-controlled SQL) |
|
||||
| Realtime | Chokidar watchers, Server-Sent Events |
|
||||
| Validation | Zod schemas, strict TypeScript |
|
||||
| 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 server (falls back to JSONL if unreachable)
|
||||
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
|
||||
|
||||
### Runtime Artifacts
|
||||
### Key Concepts
|
||||
|
||||
| Directory | Purpose | Git Status |
|
||||
|-----------|---------|------------|
|
||||
| `.beads/` | Beads database, issues, coordination state | gitignored |
|
||||
| `.agents/` | Agent skills and configuration | gitignored |
|
||||
| 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 |
|
||||
|
||||
---
|
||||
|
||||
## Project Structure
|
||||
## 🌍 Platform Support
|
||||
|
||||
Runs on macOS, Linux, and Windows.
|
||||
|
||||
- **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.
|
||||
|
||||
---
|
||||
|
||||
## 📁 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
|
||||
│ ├── 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
|
||||
├── install/ # Platform install scripts
|
||||
├── reference/
|
||||
│ └── routes/ # Archived route implementations
|
||||
├── docs/ # Documentation
|
||||
└── tests/ # Test suite
|
||||
│ └── 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)
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
| URL | View |
|
||||
|-----|------|
|
||||
| `/?view=social` | Agent social feed |
|
||||
| `/?view=graph` | Dependency graph |
|
||||
| `/?view=activity` | Activity timeline |
|
||||
|
||||
### Compatibility Redirects
|
||||
|
||||
| Old Route | Redirects To |
|
||||
|-----------|--------------|
|
||||
| `/graph` | `/?view=graph` |
|
||||
| `/sessions` | `/?view=social` |
|
||||
| `/timeline` | `/?view=activity` |
|
||||
| `/mockup` | `/` |
|
||||
|
||||
---
|
||||
|
||||
## 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:
|
||||
## 🛠️ Scripts
|
||||
|
||||
```bash
|
||||
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 dev # Development server (localhost:3000)
|
||||
npm run build # Production build
|
||||
npm run start # Production server
|
||||
npm run typecheck # TypeScript validation
|
||||
npm run typecheck # TypeScript validation (tsc --noEmit)
|
||||
npm run lint # ESLint
|
||||
npm run test # Test suite
|
||||
npm run video # Remotion video preview
|
||||
npm run video:render # Render video
|
||||
npm run test # Full test suite
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
> New test files must be added to the `test` script in `package.json` — the suite is explicitly enumerated, not auto-discovered.
|
||||
|
||||
---
|
||||
|
||||
## Roadmap
|
||||
## 🤝 Contributing
|
||||
|
||||
- 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
|
||||
We welcome contributions from humans and AI agents. See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full guide.
|
||||
|
||||
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`
|
||||
|
||||
**[Join the Discussion](https://github.com/zenchantlive/beadboard/discussions)** to coordinate on contributions, get help, or discuss ideas.
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
## 📄 License
|
||||
|
||||
[MIT](LICENSE)
|
||||
|
||||
---
|
||||
|
||||
## Acknowledgments
|
||||
## 🙏 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 bb-pi execution runtime uses [Pi](https://github.com/badlogic/pi-mono) by [@mariozechner](https://github.com/mariozechner).
|
||||
|
|
|
|||
|
|
@ -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 (
|
||||
<div className="flex h-full min-h-0 flex-col" data-testid="orchestrator-panel">
|
||||
<div className="border-b border-[var(--border-subtle)] px-4 py-3">
|
||||
<div className="mb-2 flex items-center gap-2 rounded-md border border-amber-500/30 bg-amber-500/10 px-3 py-2">
|
||||
<Construction size={14} className="shrink-0 text-amber-400" />
|
||||
<p className="text-xs text-amber-200">
|
||||
Under construction — orchestrator has known issues being actively fixed.
|
||||
<a href="https://github.com/zenchantlive/beadboard" target="_blank" rel="noopener noreferrer" className="ml-1 underline hover:text-amber-100">Track progress</a>
|
||||
</p>
|
||||
</div>
|
||||
<p className="font-mono text-[10px] uppercase tracking-[0.14em] text-[var(--text-tertiary)]">Main Orchestrator</p>
|
||||
<div className="mt-2 flex items-center justify-between gap-2">
|
||||
<div>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue