* 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>
|
||
|---|---|---|
| .. | ||
| bash-agent | ||
| bd-example-extension-go | ||
| claude-desktop-mcp | ||
| compaction | ||
| contributor-workflow | ||
| formulas | ||
| library-usage | ||
| linear-workflow | ||
| multi-phase-development | ||
| multiple-personas | ||
| protected-branch | ||
| python-agent | ||
| startup-hooks | ||
| team-workflow | ||
| README.md | ||
Beads Examples
This directory contains examples of how to integrate bd with AI agents and workflows.
Examples
Agent Integration
- python-agent/ - Simple Python agent that discovers ready work and completes tasks
- bash-agent/ - Bash script showing the full agent workflow
- startup-hooks/ - Session startup scripts for automatic bd upgrade detection
- claude-desktop-mcp/ - MCP server for Claude Desktop 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
- contributor-workflow/ - OSS contributor setup with separate planning repo
- team-workflow/ - Team collaboration with shared repositories
- multi-phase-development/ - Organize large projects by phases (planning, MVP, iteration, polish)
- multiple-personas/ - Architect/implementer/reviewer role separation
- protected-branch/ - Protected branch workflow for team collaboration
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:
- Find ready work:
bd ready --json --limit 1 - Claim the task:
bd update <id> --claim --json - Do the work: Execute the task
- Discover new issues:
bd create "Found bug" --json - Link discoveries:
bd dep add <new-id> <parent-id> --type discovered-from - Complete the task:
bd close <id> --reason "Done" --json
All commands support --json for easy parsing.