Skip to content

BEADS.md

Latest commit

 

History

History
149 lines (119 loc) · 6.72 KB

BEADS.md

File metadata and controls

149 lines (119 loc) · 6.72 KB

Optional Beads execution queue

Beads is an open-source dependency-aware issue tracker designed for AI coding agents — it gives an agent a local ready/blocked view of work, a dependency graph, and restart-safe task claims that GitHub Issues alone do not.

This document is optional and additive. The base harness does not assume Beads; if your team has no agent or multi-actor execution concern, GitHub Issues plus the PR template is sufficient and you can skip this doc entirely. Beads is recommended specifically when you are coordinating an LLM agent (or several) against this repo and want dependency planning the public issue tracker does not provide. The README and docs/HARNESS.md references describe Beads as optional infrastructure, not part of the standard contributor flow.

Wherever Beads is used, GitHub Issues remain the external source of truth and the authority for issue closure.

Review of existing GitHub issue guidance

The current harness already treats GitHub as the public planning and merge record:

  • .github/ISSUE_TEMPLATE/bug.md, feature.md, and eval-regression.md define the supported intake paths, and blank issues are disabled in .github/ISSUE_TEMPLATE/config.yml.
  • CONTRIBUTING.md requires one issue per branch, short-lived branches named <type>/<issue-number>-<kebab-title>, and green CI plus review before merge.
  • .github/pull_request_template.md requires What & why, Test plan, Invariants affected, supply-chain surface, Screenshots when relevant, and a linked issue.
  • CLAUDE.md and docs/DEVELOPMENT.md describe the same one-issue, one-branch, develop to main release flow for agent and human operators.
  • docs/TASKS.md is a project-local planning map cross-referenced with GitHub issues and the project board.

There is no Beads-specific policy in the base harness today. Any Beads addition must therefore be additive and must not make GitHub issue state ambiguous.

GitHub Issues vs Beads

System Owns Does not own
GitHub Issues Public backlog, user-facing requirements, labels, project board state, discussion, acceptance criteria, links from PRs, and final issue closure. Local agent claims, transient execution notes, or dependency scheduling that would be noisy in the public issue.
Beads Local execution queue, ready/blocked views, dependency graph, implementation notes, reviewer handoff notes, and restart-safe task claims. The canonical requirement, public status, release notes, or authority to close a GitHub issue.

The rule is simple: GitHub answers what work exists and whether it is externally done; Beads answers what the local execution system should pick up next.

Sync contract

When using Beads with this harness:

  1. Create or confirm the GitHub issue first.
  2. Mirror the issue into Beads with an immutable external reference:
    • GitHub repository owner/name.
    • GitHub issue number.
    • GitHub issue URL.
    • Original issue title.
  3. Use Beads for local status only: ready, in_progress, blocked, review, or done are execution states, not replacements for the GitHub issue state.
  4. Put the Bead id in local notes, branch notes, or PR body when useful, but keep Closes #<issue> pointing at the GitHub issue.
  5. Do not close a GitHub issue because a Bead is marked done. Close only after the PR is merged, required checks are green, any required manual or browser validation is recorded, and a human-readable note has been added to the issue or PR.

If the GitHub issue changes after import, update the Bead from GitHub before continuing. GitHub wins on scope, acceptance criteria, and user-visible status.

Recommended Bead fields

A Bead should carry enough information for a new agent or contributor to resume without reopening every browser tab:

Field Purpose
external_ref GitHub issue URL, for example https://github.com/owner/repo/issues/123.
github_issue Numeric issue id used by branches and PRs.
acceptance The current acceptance criteria copied or summarized from GitHub.
dependencies Other Beads or GitHub issues that must land first.
status Local execution state.
owner Optional local agent or human claim.
evidence Paths or URLs for test output, review notes, screenshots, or deploy checks.
closeout Merge SHA, PR URL, and verification notes once complete.

A short YAML example:

external_ref: https://github.com/owner/repo/issues/123
github_issue: 123
acceptance: |
  /api/v1/echo rejects payloads >1KiB with HTTP 413.
dependencies: [122]   # other Bead ids or GitHub issues
status: ready
owner: agent-a
evidence:
  - tests/test_api.py::test_echo_size_cap
closeout: null

Avoid storing secrets, tokens, credentials, private customer data, or raw production payloads in Beads. Treat Beads data as local operational metadata. Note that .beads/ is gitignored, so anything Beads stores locally — including agent-action audit logs — is wiped by git clean -fdx; commit deliberate summaries to the repo if you need them to survive workspace resets.

PR discipline when Beads are used

The existing PR template still applies. Add Beads information without deleting any required section:

  • Linked issue remains Closes #<issue>.
  • Mention the Bead id or local queue reference under What & why or the optional Beads section.
  • Include Beads-derived evidence paths in Test plan only when they are useful to a reviewer.
  • If the Bead changed scope, update the GitHub issue before asking for review.
  • If the Bead was blocked by an external dependency, note that in the PR or issue rather than hiding it in the local queue.

Local artifact hygiene

Beads state is usually local execution metadata. Do not commit raw Beads databases, scratch exports, or agent logs by default. Commit only intentional summaries or docs that reviewers need.

If a downstream project decides to version Beads state, document that policy in that project and make sure secret scanning, review, and retention expectations are explicit.

Closure checklist

The PR-merge and issue-closure gates already live in .github/pull_request_template.md and CONTRIBUTING.md — don't duplicate them here. The Bead-specific closure rule is narrower:

  • Do not mark a Bead done until the GitHub issue's closure conditions (per the PR template and CONTRIBUTING.md) are met. Beads track the local execution state of work GitHub already authorised; they don't grant new closure authority.
  • If the Bead and the GitHub issue disagree on scope, acceptance, or status, stop and reconcile against GitHub before continuing.

Beads improve local throughput only if they reduce ambiguity. If a Bead and a GitHub issue disagree, the GitHub issue wins.