Skip to content

BEADS.md

Latest commit

 

History

History
121 lines (94 loc) · 5.56 KB

BEADS.md

File metadata and controls

121 lines (94 loc) · 5.56 KB

Optional Beads execution queue

Beads can be layered onto this harness as a local execution queue for teams that want dependency-aware task planning, agent handoffs, or ready/blocked views while still keeping GitHub Issues as the external source of truth.

This document is intentionally conservative: it adds Beads guidance without replacing the repository's existing GitHub issue and PR process.

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.

Avoid storing secrets, tokens, credentials, private customer data, or raw production payloads in Beads. Treat Beads data as local operational metadata.

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

Before marking a Bead done:

  • The GitHub issue is still the correct external requirement.
  • The PR links the GitHub issue and, where useful, the Bead id.
  • Required CI checks passed or have documented non-applicability.
  • Required review happened according to repository policy.
  • Any requested browser, deploy, eval, or security evidence is attached or linked.
  • The GitHub issue receives a closeout note before or during closure.

Beads improve local throughput only if they reduce ambiguity. If a Bead and a GitHub issue disagree, stop and reconcile them before implementation continues.