beads/examples
Jim Wordelman bc9d854ebb
feat(stats): --no-blocked flag skips blocked-count computation; fix Blocked:0 red render (be-nnqp, be-4b63) (#4022)
* feat(stats): add --no-blocked flag; fix Blocked:0 red render (be-nnqp, be-4b63)

- types.go: BlockedIssues int → *int (nil when --no-blocked skips computation)
- storage: add FastStatisticsStore interface + GetStatisticsNoBlocked to DoltStorage;
  implement in DoltStore and EmbeddedDoltStore (ScanIssueCountsInTx only, no blocked traversal)
- status.go: --no-blocked flag (no short alias), BlockedCountSkipped bool in StatusOutput;
  fast path calls GetStatisticsNoBlocked; human output renders "(skipped)" in muted style
- be-4b63: Blocked:0 now renders plain text; only Blocked:N>0 uses RenderFail (red)
- nil-guard BlockedIssues callers: getAssignedStatistics, status_test.go, queries_test.go,
  examples/library-usage/main.go

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(cli): regen CLI reference for `bd status --no-blocked`

Regenerates docs/CLI_REFERENCE.md and the website CLI reference pages
(`website/docs/cli-reference/status.md` and the version-1.0.0 / 1.0.4
snapshots) from the live `bd help` output so the doc-flags freshness
check passes.

Picks up the new `--no-blocked` flag, the updated `--no-activity`
description ("Skip git activity summary"), and the matching example
lines added in ddf53438c.

Fixes the CI "Check doc flags freshness" failure on PR #4022.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: release gate PASS for be-nnqp+be-4b63 (bd stats --no-blocked)

* fix(stats): ReadyIssues *int, data-derived skip render, proxied-server warning

Address the adjudicated cross-vendor review on PR #4022:

- internal/types.Statistics.ReadyIssues is now *int, mirroring BlockedIssues:
  nil when --no-blocked skips the computation (readiness needs the blocked
  set), populated by all three backends' full GetStatistics, by
  issueops.GetStatisticsInTx, and by buildAssignedStats. Left nil only in
  the *NoBlocked fast-path variants. JSON now emits `"ready_issues": null`
  instead of a fake 0 a CI consumer could misread as "nothing ready".
- renderStatus derives "(skipped)" rendering from the data itself
  (stats.BlockedIssues/ReadyIssues == nil) instead of the noBlocked flag,
  fixing the --assigned + --no-blocked contradiction where fully-recomputed
  stats were mislabeled as skipped. The noBlocked parameter is gone from
  renderStatus entirely; both call sites (status.go, status_proxied_server.go)
  simplified accordingly.
- Proxied-server mode now prints a one-line stderr warning when --no-blocked
  is passed but not honored, instead of silently discarding the flag; the
  flag's help string documents the limitation.

Agent-Signature: claude-sonnet-medium on behalf of maphew

* test(stats): cover GetStatisticsNoBlocked nil semantics and renderStatus skip branch

- internal/storage/dolt: new TestGetStatisticsNoBlocked_LeavesBlockedAndReadyNil
  asserts the --no-blocked fast path leaves BlockedIssues/ReadyIssues nil
  while the full GetStatistics path on the same store populates both.
- cmd/bd: new TestGetStatisticsNoBlocked (storage-level, same assertion via
  the CLI-facing store handle), TestRenderStatus_SkipJSONEmitsNullNotZero
  (asserts blocked_count_skipped:true plus literal `"blocked_issues": null`
  / `"ready_issues": null` in the JSON envelope),
  TestRenderStatus_SkipHumanRendersSkippedNotZero (asserts the "(skipped)"
  human branch renders for both fields), and
  TestRenderStatus_AssignedIgnoresSkipEvenWithNoBlockedFlag (guards the
  --assigned + --no-blocked fix: fully-populated stats never render
  "(skipped)").
- Update existing statistics assertions in
  internal/storage/conformance/audit_search-counts-stats.go,
  internal/storage/dolt/queries_test.go, and
  internal/storage/domain/db/ready_helpers*_test.go for
  ReadyIssues's int -> *int change.

Agent-Signature: claude-sonnet-medium on behalf of maphew

* docs(cli): drop --no-blocked doc lines from CLI_REFERENCE.md/status.md (pinned-generator policy)

CI's "Check doc flags freshness" job builds bd from the release pin in
docs/cli-docs.pin (currently v1.1.0) to regenerate docs/CLI_REFERENCE.md
and docs/cli-reference/status.md, not from this branch's HEAD. v1.1.0
predates --no-blocked entirely, so the pinned generator's output omits
every --no-blocked reference (use case bullet, both example lines, the
flag description) and also reverts the --no-activity flag description
wording, flagging both files as stale relative to it. Same trap PR #3920
hit for --mem-profile.

Applied the exact patch CI generated and uploaded as the
cli-docs-freshness-patch artifact on the failing job
(run 30063539327 / job 89390739992) verbatim to both files; the lines
will reappear automatically once the pin advances past a release that
includes --no-blocked.

Agent-Signature: claude-sonnet-medium on behalf of maphew

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
2026-07-23 23:52:39 -07:00
..
bash-agent Document supported go install modes (bd-o5a) (#3480) 2026-04-25 11:30:19 -07:00
bd-example-extension-go Bump Go to 1.26.5 (#4942) 2026-07-23 18:54:32 -07:00
claude-desktop-mcp bd sync: 2025-11-26 18:07:01 2025-11-26 18:07:01 -08:00
compaction fix(compact): stop advertising the unimplemented Tier 2 compaction (#4465) 2026-06-20 15:29:28 -07:00
contributor-workflow docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
formulas docs: redirect legacy GitHub Pages site to Mintlify (#4759) 2026-07-13 14:19:13 -07:00
library-usage feat(stats): --no-blocked flag skips blocked-count computation; fix Blocked:0 red render (be-nnqp, be-4b63) (#4022) 2026-07-23 23:52:39 -07:00
linear-workflow docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
multi-phase-development docs(claim): standardize start-work semantics to --claim (#2070) 2026-02-24 22:11:39 -08:00
multiple-personas docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
protected-branch docs: canonical concept page, section overviews, and concept diagrams 2026-07-12 10:37:07 -07:00
python-agent Document supported go install modes (bd-o5a) (#3480) 2026-04-25 11:30:19 -07:00
startup-hooks feat: Add agent upgrade awareness documentation and tooling 2025-11-23 16:29:56 -08:00
team-workflow docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
README.md docs(claim): standardize start-work semantics to --claim (#2070) 2026-02-24 22:11:39 -08:00

Beads Examples

This directory contains examples of how to integrate bd with AI agents and workflows.

Examples

Agent Integration

Tools & Utilities

  • monitor-webui/ - Standalone web interface for real-time issue monitoring and visualization
  • git-hooks/ - Pre-configured git hooks for automatic Dolt sync

Workflow Patterns

Quick Start

# Try the Python agent example
cd python-agent
python agent.py

# Try the bash agent example
cd bash-agent
./agent.sh

# Install git hooks
cd git-hooks
./install.sh

# REMOVED (bd-4c74): branch-merge demo - hash IDs eliminate collision resolution

Creating Your Own Agent

The basic agent workflow:

  1. Find ready work: bd ready --json --limit 1
  2. Claim the task: bd update <id> --claim --json
  3. Do the work: Execute the task
  4. Discover new issues: bd create "Found bug" --json
  5. Link discoveries: bd dep add <new-id> <parent-id> --type discovered-from
  6. Complete the task: bd close <id> --reason "Done" --json

All commands support --json for easy parsing.