From f29c0e3cba39beac32f41e499f6dcaf0902108f4 Mon Sep 17 00:00:00 2001 From: zenchantlive Date: Wed, 25 Mar 2026 00:22:47 -0500 Subject: [PATCH] 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. ---