beads/examples
matt wilkie 935afe2466
fix(examples): tidy both example modules and build them in CI (#5229)
* fix(examples): tidy both example modules and build them in CI

Both Go modules under examples/ fail a plain `go build` on current main:

    go: updates to go.mod needed; to update it:
            go mod tidy

They are separate modules that reach the parent through
`replace github.com/steveyegge/beads => ../..`, so their go.mod and go.sum
record the parent's entire dependency graph. Every root dependency change
therefore invalidates them — and nothing in CI ever compiled them, so the drift
accumulated silently. examples/ is the first code a new user copies, which makes
this a bad first five minutes rather than a cosmetic wart.

Two parts:

1. `go mod tidy` in examples/bd-example-extension-go and examples/library-usage.
   The extension example carries most of the churn (~1.6k lines of go.sum),
   which is inherent to recording the parent graph through the replace directive
   and is why an earlier fix (#4942, the Go 1.26.5 bump) deliberately left it
   out. Both modules now build clean with the project's canonical
   `-tags gms_pure_go`.

2. scripts/build-examples.sh plus a `build-examples` job in the PR workflow, so
   the same drift cannot recur unnoticed. The script discovers example modules
   from `git ls-files 'examples/*/go.mod'` (no hardcoded list), sources
   .buildflags for the canonical CGO/tag settings, builds into a scratch
   directory so it leaves no untracked binaries, reports every failing module
   rather than stopping at the first, and prints the exact `go mod tidy`
   command to run.

The job is deliberately NOT added to ci-gate's required list. Because of the
replace directive it would fail on any root go.mod change not mirrored into the
examples, so making it blocking imposes a "tidy the examples too" step on every
dependency bump. That is a maintainer call about contributor friction; the job
is visible on the checks list either way, and pr.yml records how to promote it.

Verified locally: both modules build with -tags gms_pure_go; the script exits 1
and names the module when an example go.mod is reverted to its pre-tidy state;
scripts/check-build-tags.sh stays clean (the script sources .buildflags).

Agent-Signature: claude-opus-5-high on behalf of matt wilkie

* fix(examples): address dual-vendor review — vet not build, advisory job, portability

Reviewed by a claude reviewer and scripts/codex-agent reviewer (gpt-5.6-sol).
Four fixes, two of them correctness.

1. `go build -o <dir>/ ./...` was a FALSE GREEN: with -o naming a directory, Go
   compiles only the MAIN packages and silently skips every library package.
   Reproduced in an isolated module with a good main package plus a library
   package containing a type error — `go build -o dir/ ./...` exits 0 while
   `go build ./...` and `go vet ./...` both exit 1. The mirror-image bug: a
   library-only example module fails `go build` with "no main packages to
   build", a false red. Switched to `go vet ./...`, which type-checks every
   package INCLUDING test files (examples/library-usage/main_test.go exercises
   a lot of live API, and `go mod tidy` counts its imports, so a build that
   never compiles it left part of the recorded graph unverified), writes no
   artifacts, and still fails on the stale-go.mod condition this exists for.
   That also deletes the mktemp/trap/scratch-dir machinery entirely.

2. "Not in ci-gate" is NOT "non-blocking", which the previous comment claimed.
   Verified in source: pr-preflight.sh gates on every FAILURE in the raw
   statusCheckRollup and calls block(), and pr-babysit requires all rollup
   entries SUCCESS/NEUTRAL/SKIPPED before merging. Both ignore ci-gate
   membership. So the previous state was the one posture that stalls the merge
   patrol repo-wide after any un-mirrored dependency bump while advertising
   itself as optional. The job is now continue-on-error: true — genuinely
   advisory — and the comment records how to promote it to a real gate. Whether
   it SHOULD be a gate remains the maintainers' call.

3. Portability and robustness in the script, all reproduced by the reviewers:
   - `mapfile` does not exist in bash 3.2 (stock macOS) and `xargs -r` is
     GNU-only, so the advertised local check could not run on macOS. Replaced
     with a NUL-delimited read loop, which also fixes module paths containing
     whitespace (`git ls-files | xargs -n1 dirname` turned "examples/has
     space/go.mod" into two bogus entries).
   - `source ./.buildflags` was unguarded under `set -uo pipefail`; a failure
     continued with GOFLAGS unset and would type-check the ICU path while
     check-build-tags.sh still passed, since that only greps for the literal
     string. Now a hard exit.
   - Finding zero modules exited 0. A job that checks nothing must not report
     success; it is now an error.

Verified: both modules vet clean; reverting an example go.mod to its pre-tidy
state still exits 1 with the exact `go mod tidy` command; a broken library
package now fails where it previously passed; check-build-tags.sh clean
(97 files); shellcheck clean.

Agent-Signature: claude-opus-5-high on behalf of matt wilkie

* fix(examples): drop GNU-only sort -z from the module discovery pipeline

BSD sort has no -z, so on stock macOS — the exact platform the Bash-3.2
compatibility block targets — the sort stage emptied the pipeline and the
script exited claiming 'found no example modules'. git ls-files output is
already sorted, so the stage bought nothing. Found by cross-vendor review
(codex gpt-5.6-sol) of this branch.

Agent-Signature: claude-fable-5-high on behalf of maphew

* fix(ci,examples): disable setup-go cache in build-examples; re-tidy examples after merge

TestGoCacheOwnershipTopology requires every setup-go step in pr.yml to set
cache: false (caching is owned by explicit restore/save steps); the new
build-examples job predates that policy landing on main. Also re-run
go mod tidy in both example modules so their recorded dependency graphs
match the merged main — exactly the drift this PR's CI job exists to catch.

Agent-Signature: claude-fable-5-high on behalf of maphew

* ci(examples): bound build-examples with timeout-minutes: 10

continue-on-error keeps a red result advisory, but a hung job at the
6-hour default timeout holds the check pending, stalling merge-lane
consumers the advisory posture was meant to protect. Matches
pr-preflight-platforms' bound.

Agent-Signature: claude-fable-5-high on behalf of maphew

* ci(examples): make the advisory posture real - step-level continue-on-error

Job-level continue-on-error still reports the check run as FAILURE in the
PR rollup (only the workflow-run conclusion flips), and pr-preflight /
pr-babysit gate on per-check-run conclusions - so the job as written was
de facto blocking while advertising itself advisory. Follow the cygwin-leg
precedent: continue-on-error on the build step, outcome-guarded ::warning
annotation on failure. Also restore the repo-wide Go module cache (the
examples' graph is the parent's via the replace directive) so the job
stops cold-downloading the full dependency graph on every PR.

Agent-Signature: claude-fable-5-high on behalf of maphew

* test: register build-examples' module-cache restore in the cache topology registry

TestGoCacheOwnershipTopology keeps an explicit inventory of every cache
step per job; the advisory-lane fix added a restore step to build-examples
without registering it, so the whole scripts package went red on this
head. Register the job (inventory, managed map, ordering, setup-go id)
and drop the step's unused 'restore-cache' id — the registry compares
ids, and nothing references it.

Agent-Signature: claude-fable-5-high on behalf of maphew
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019CwiLhLbAGZdJtKYT76CPp

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-12 21:16:27 -07:00
..
bash-agent Document supported go install modes (bd-o5a) (#3480) 2026-04-25 11:30:19 -07:00
bd-example-extension-go fix(examples): tidy both example modules and build them in CI (#5229) 2026-08-12 21:16:27 -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(lint): align contributor guidance with CI (saa-90w) (#5317) 2026-08-07 05:37:12 -07:00
library-usage fix(examples): tidy both example modules and build them in CI (#5229) 2026-08-12 21:16:27 -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.