docs(agents): contributor-only agent instructions and documented-issue intake (#7223)

Makes the repo's agent and contributor surface describe developing beads, not using bd, and requires every PR to link a documented issue.

- Contributor-only root AGENTS.md with a routing table; cmd/bd/AGENTS.md and engdocs/AGENTS.md seam files; CLAUDE.md symlinks so Claude Code loads nested files.
- Bug and feature issue forms, a PR template that requires Closes #, CONTRIBUTING sections for the triage and pipeline labels, and the opt-in fork-cache during dev setup.
- ROADMAP.md for 1.4: versioned beads (#6132), Graph Preview 2 (#7170), contributor onboarding (#7228).
- docsync guards: root AGENTS.md at or under 20 KB; every AGENTS.md symlinked, routed, and with resolving links, paths, and guard-test names.

Agent-Signature: claude-code-claude-opus-5-5-high on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Julian Knutsen 2026-10-05 01:43:53 -07:00 • committed by GitHub
commit 0773e6334e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
32 changed files with 1080 additions and 1269 deletions

View file

@ -8,7 +8,7 @@ the binary still prints, the docs now lie.
## The discipline
1. **Survey first.** Count occurrences in `docs/`, `engdocs/`, `README.md`,
`AGENTS.md`, `AGENT_INSTRUCTIONS.md`, and `*.go`. Read enough to tell
every `AGENTS.md` (root and nested), and `*.go`. Read enough to tell
*prose* (the concept) from *literals*.
2. **Rename prose only**, with judgment per occurrence — fix articles and
grammar so it reads naturally.

View file

@ -55,7 +55,7 @@ all of:
1. **Redirect** — add an entry to the `redirects` array in `docs/docs.json`
from the old route to the new one.
2. **Rewrite inbound links** — grep the whole repo, not just `docs/`:
README.md, AGENTS.md, AGENT_INSTRUCTIONS.md, engdocs/, examples/,
README.md, every AGENTS.md (root and nested), engdocs/, examples/,
npm-package/, plugins/, integrations/, scripts, and Go comments.
3. **Check bd's printed output** — if `bd` prints the old path (grep `cmd/`
and `internal/templates/` for it), fix the Go source to print the new

View file

@ -1,103 +0,0 @@
# Test Running Strategy for Claude Code
## Critical Rules
1. **ALWAYS use `./scripts/test.sh` instead of `go test` directly**
- It automatically skips broken tests from `.test-skip`
- Uses appropriate timeouts (3m default)
- Consistent with human developers and CI/CD
2. **Use `-run` to target specific tests when developing features**
```bash
# Good: When working on feature X
./scripts/test.sh -run TestFeatureX ./cmd/bd/...
# Avoid: Running full suite unnecessarily
./scripts/test.sh ./...
```
3. **Understand the bottleneck: COMPILATION not EXECUTION**
- 180s compilation time vs 3.8s actual test execution (cmd/bd)
- Running subset of tests doesn't save much time (still recompiles)
- But use `-run` anyway to avoid seeing unrelated failures
## Common Commands
```bash
# Full test suite (what 'make test' runs)
./scripts/test.sh
# Test specific package
./scripts/test.sh ./cmd/bd/...
./scripts/test.sh ./internal/storage/embeddeddolt/...
# Test specific feature
./scripts/test.sh -run TestCreate ./cmd/bd/...
./scripts/test.sh -run TestImport
# Verbose output (when debugging)
./scripts/test.sh -v -run TestSpecificTest
```
## When Tests Fail
1. **Check if it's a known broken test:**
```bash
cat .test-skip
```
2. **If it's new, investigate:**
- Read the test failure message
- Run with `-v` for more detail
- Check if recent code changes broke it
3. **If unfixable now:**
- File GitHub issue with details
- Add to `.test-skip` with issue reference
- Document in commit message
## Package Size Context
The `cmd/bd` package is LARGE:
- 41,696 lines of code
- 205 files (82 test files)
- 313 individual tests
- Compilation takes ~180 seconds
This is why:
- Compilation is slow
- Test script uses 3-minute timeout
- Targeting specific tests is important
## Environment Variables
Use these when needed:
```bash
# Custom timeout
TEST_TIMEOUT=5m ./scripts/test.sh
# Verbose by default
TEST_VERBOSE=1 ./scripts/test.sh
# Run pattern
TEST_RUN=TestSomething ./scripts/test.sh
```
## Quick Reference
| Task | Command |
|------|---------|
| Run all tests | `make test` or `./scripts/test.sh` |
| Test one package | `./scripts/test.sh ./cmd/bd/...` |
| Test one function | `./scripts/test.sh -run TestName` |
| Verbose output | `./scripts/test.sh -v` |
| Custom timeout | `./scripts/test.sh -timeout 10m` |
| Skip additional test | `./scripts/test.sh -skip TestFoo` |
## Remember
- The test script is in `.gitignore` path: `scripts/test.sh`
- Skip list is in repo root: `.test-skip`
- Full documentation: `engdocs/TESTING.md`
- Current broken tests: See GH issues #355, #356

94
.github/ISSUE_TEMPLATE/bug_report.yml vendored Normal file
View file

@ -0,0 +1,94 @@
name: Bug report
description: Report broken behavior in bd.
title: "bug: "
body:
- type: markdown
attributes:
value: |
Thanks for the report. This issue is the record a fix PR links to, so the more evidence here, the better. You can open a fix PR right away; no approval is needed first.
**Agents filling in this form:** answer each question only from evidence you have. If you cannot answer a question from the evidence, write exactly `NOT_ENOUGH_INFO` instead of guessing.
- type: checkboxes
id: checks
attributes:
label: Before you continue
options:
- label: I searched existing issues and did not find a duplicate.
required: true
- label: I reproduced this with stock `bd`, without an orchestrator or agent framework in the loop.
required: false
- type: textarea
id: summary
attributes:
label: Summary
description: What is broken, in one or two sentences.
validations:
required: true
- type: textarea
id: repro
attributes:
label: Steps to reproduce
description: Exact commands, starting from a fresh directory where possible.
render: shell
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected behavior
validations:
required: true
- type: textarea
id: actual
attributes:
label: Actual behavior
description: Include the full error output.
validations:
required: true
- type: input
id: version
attributes:
label: bd version
description: Output of `bd version`.
validations:
required: true
- type: dropdown
id: mode
attributes:
label: Storage mode
options:
- Embedded (default `bd init`)
- Server mode (`bd init --server`)
- Proxied server
- Not sure
validations:
required: true
- type: input
id: os
attributes:
label: Operating system
placeholder: "macOS 15.5 (arm64), Ubuntu 24.04, Windows 11, ..."
validations:
required: true
- type: textarea
id: impact
attributes:
label: Impact
description: Who is affected, how severe it is (data loss, blocked, workaround exists), and how often it happens.
validations:
required: true
- type: textarea
id: context
attributes:
label: Additional context
description: Logs, `bd doctor` output, root-cause notes, or a proposed fix.

11
.github/ISSUE_TEMPLATE/config.yml vendored Normal file
View file

@ -0,0 +1,11 @@
blank_issues_enabled: false
contact_links:
- name: Documentation
url: https://beads.gascity.com/
about: Installation, concepts, CLI reference, and troubleshooting.
- name: Questions and ideas
url: https://github.com/gastownhall/beads/discussions
about: Ask usage questions or float an idea before it is ready to be an issue.
- name: Security vulnerability
url: https://github.com/gastownhall/beads/security/policy
about: Report security issues privately, never in a public issue.

View file

@ -0,0 +1,108 @@
name: Feature request
description: Propose a change to bd, with the information needed to accept it.
title: "feat: "
body:
- type: markdown
attributes:
value: |
Every PR links a documented issue, and this form collects the context reviewers and future readers need. You can open your PR right after filing; no approval is needed first. Read the [project charter](https://github.com/gastownhall/beads/blob/main/engdocs/PROJECT_CHARTER.md) first — beads owns issue-tracking primitives, not orchestration policy or storage-engine behavior.
**Agents filling in this form:** answer each question only from evidence you have. If you cannot answer a question from the evidence, write exactly `NOT_ENOUGH_INFO` instead of guessing.
- type: checkboxes
id: checks
attributes:
label: Before you continue
options:
- label: I searched existing issues and pull requests and did not find a duplicate.
required: true
- type: textarea
id: motivation
attributes:
label: Motivation
description: The problem, and who has it. Describe the pain, not the implementation you prefer.
validations:
required: true
- type: textarea
id: proposal
attributes:
label: Proposed change
description: The behavior, command, flag, or API you want.
validations:
required: true
- type: textarea
id: impact
attributes:
label: Impact
description: Who is affected and how — users, agents, integrations, downstream consumers of the `--json` output.
validations:
required: true
- type: textarea
id: risk
attributes:
label: Risk and compatibility
description: Schema or migration changes, wire or `--json` output changes, behavior changes for existing workspaces, and how to roll back.
validations:
required: true
- type: textarea
id: verification
attributes:
label: Verification plan
description: How we will know it works end to end, beyond unit tests.
validations:
required: true
- type: textarea
id: alternatives
attributes:
label: Alternatives considered
description: Current workarounds, issue metadata, an integration or plugin, or other designs.
- type: dropdown
id: size
attributes:
label: Estimated size
options:
- XS (under 50 lines)
- S (under 200 lines)
- M (under 500 lines)
- L (under 1,000 lines)
- XL (more than 1,000 lines; likely needs splitting)
- Not sure
validations:
required: true
- type: dropdown
id: intent
attributes:
label: Intent
options:
- I am opening or will open a PR
- I'm reporting the need; someone else would implement it
validations:
required: true
- type: dropdown
id: ai
attributes:
label: AI assistance
description: Was an AI agent used to draft this issue?
options:
- "No"
- Yes, partly
- Yes, mostly
validations:
required: true
- type: checkboxes
id: accountability
attributes:
label: Accountability
options:
- label: A human has read this issue and stands behind it.
required: true

View file

@ -1,16 +1,23 @@
<!--
This is a starting scaffold to help reviewers (human and agent) parse intent before diff.
Replace, expand, or delete sections freely. CONTRIBUTING.md has the full hygiene rules.
Every PR closes a documented issue (file it first or alongside; no approval
needed). The issue carries the motivation, impact, and risk. See
CONTRIBUTING.md#issues-and-pull-requests.
-->
## What
Closes #
<!-- One or two plain-language sentences: what does this change do? -->
## What changed
## Why
<!-- One or two plain-language sentences. -->
<!-- The problem this solves, the motivation, or a link to the issue: e.g. "Fixes #123" -->
## Evidence it works
## Verification
<!-- Commands a reviewer can run and what they show, end to end.
"Unit tests pass" alone is not evidence. -->
<!-- How you tested. Commands a reviewer can run to confirm. -->
## Checklist
- [ ] The linked issue documents the problem (reproduction or motivation, impact, risk).
- [ ] Tests and lint selected per `engdocs/TESTING.md` pass locally.
- [ ] User-facing behavior changes are reflected in `docs/` or the generated CLI reference.
- [ ] If an invariant or rule changed, the owning `AGENTS.md` is updated.

View file

@ -1,138 +1,15 @@
# GitHub Copilot Instructions for Beads
# GitHub Copilot instructions for beads
## Project Overview
The canonical contributor instructions for this repository are in
[AGENTS.md](../AGENTS.md); area-specific rules are in the nested `AGENTS.md`
files listed in its routing table. Read those, not this file, for workflow,
build, test, and scope rules.
**beads** (command: `bd`) is a Dolt-powered issue tracker designed for AI-supervised coding workflows. Git integration is optional. We dogfood our own tool for all task tracking.
The rules most often missed in review:
**Key Features:**
- Dependency-aware issue tracking
- Auto-sync via Dolt-native replication
- AI-optimized CLI with JSON output
- Dolt server mode for background operations
- MCP server integration for Claude and other AI assistants
## Tech Stack
- **Language**: Go 1.21+
- **Storage**: Dolt (version-controlled SQL database)
- **CLI Framework**: Cobra
- **Testing**: Go standard testing + table-driven tests
- **CI/CD**: GitHub Actions
- **MCP Server**: Python (integrations/beads-mcp/)
## Coding Guidelines
### Testing
- Always write tests for new features
- Use `t.TempDir() in Go tests` to avoid polluting production database
- Run `go test -short ./...` before committing
- Never create test issues in production DB (use temporary DB)
### Code Style
- Run `make ci-pr-lint` before committing changes to Go or lint-controlled files
- Follow existing patterns in `cmd/bd/` for new commands
- Add `--json` flag to all commands for programmatic use
- Update docs when changing behavior
### Git Workflow
- Install git hooks: `bd hooks install`
- Use `bd dolt push` / `bd dolt pull` for remote sync
- Before implementing related work, opening a PR, or merging/closing a PR, run:
`scripts/pr-preflight.sh --search "<topic>" --repo gastownhall/beads` or
`scripts/pr-preflight.sh <pr-number> --repo gastownhall/beads`
- External contributor PRs have priority: build on them when possible, preserve
tests and attribution, and never close or replace them silently.
## Issue Tracking with bd
**CRITICAL**: This project uses **bd** for ALL task tracking. Do NOT create markdown TODO lists.
### Essential Commands
```bash
# Find work
bd ready --json # Unblocked issues
bd stale --days 30 --json # Forgotten issues
# Create and manage (ALWAYS include --description)
bd create "Title" --description="Detailed context" -t bug|feature|task -p 0-4 --json
bd update <id> --claim --json
bd close <id> --reason "Done" --json
# Search
bd list --status open --priority 1 --json
bd show <id> --json
# Sync (if remote configured)
bd dolt push # Push to Dolt remote
bd dolt pull # Pull from Dolt remote
```
### Workflow
1. **Check ready work**: `bd ready --json`
2. **Claim task**: `bd update <id> --claim`
3. **Work on it**: Implement, test, document
4. **Discover new work?** `bd create "Found bug" --description="What was found and why" -p 1 --deps discovered-from:<parent-id> --json`
5. **Complete**: `bd close <id> --reason "Done" --json`
6. **Sync**: `bd dolt push` (push to Dolt remote if configured)
**IMPORTANT**: Always include `--description` when creating issues. Issues without descriptions lack context for future work.
### Priorities
- `0` - Critical (security, data loss, broken builds)
- `1` - High (major features, important bugs)
- `2` - Medium (default, nice-to-have)
- `3` - Low (polish, optimization)
- `4` - Backlog (future ideas)
## Project Structure
```
beads/
├── cmd/bd/ # CLI commands (add new commands here)
├── internal/
│ ├── types/ # Core data types
│ └── storage/ # Storage layer
│ └── dolt/ # Dolt implementation
├── integrations/
│ └── beads-mcp/ # MCP server (Python)
├── examples/ # Integration examples
├── docs/ # Documentation
└── .beads/
└── dolt/ # Dolt database (source of truth)
```
## Available Resources
### MCP Server (Recommended)
Use the beads MCP server for native function calls instead of shell commands:
- Install: `pip install beads-mcp`
- Functions: `mcp__beads__ready()`, `mcp__beads__create()`, etc.
- See `integrations/beads-mcp/README.md`
### Scripts
- `./scripts/bump-version.sh <version> --commit` - Update all version files atomically
- `./scripts/release.sh <version>` - Complete release workflow
- `./scripts/update-homebrew.sh <version>` - Update Homebrew formula
### Key Documentation
- **AGENTS.md** - Comprehensive AI agent guide (detailed workflows, advanced features)
- **AGENT_INSTRUCTIONS.md** - Development procedures, testing, releases
- **README.md** - User-facing documentation
- **docs/CLI_REFERENCE.md** - Complete command reference
## Important Rules
- ✅ Use bd for ALL task tracking
- ✅ Always use `--json` flag for programmatic use
- ✅ Use `bd dolt push` / `bd dolt pull` for remote sync
- ✅ Test with `t.TempDir() in Go tests`
- ❌ Do NOT create markdown TODO lists
- ❌ Do NOT create test issues in production DB
- ❌ Do NOT manually modify `.beads/dolt/`
---
**For detailed workflows and advanced features, see [AGENTS.md](../AGENTS.md)**
- A PR must close a documented GitHub issue (filed before or alongside it).
- Build with `make install`, never `go build -o bd ./cmd/bd` or `go install ./cmd/bd`.
- `make ci-pr-lint` must pass with zero issues; choose tests with
[engdocs/TESTING.md](../engdocs/TESTING.md).
- Never create test issues in a production database; use `t.TempDir()`.
- CLI output uses small Unicode status symbols, never emoji icons.

View file

@ -19,6 +19,10 @@ on:
- 'CLAUDE.md'
- 'RELEASING.md'
- 'PR_MAINTAINER_GUIDELINES.md'
- 'ROADMAP.md'
- '**/AGENTS.md'
- '**/CLAUDE.md'
- '.github/copilot-instructions.md'
- '.github/scripts/docs-render-check.sh'
- '.github/workflows/docs-mintlify.yml'

409
AGENTS.md
View file

@ -1,290 +1,191 @@
# Agent Instructions
# Beads — Contributor Agent Instructions
<!-- bd-doctor-divergence: ok -->
This file is for agents and humans **developing beads** (`bd`). If you are
using `bd` to track work in your own project, read the user docs instead:
[docs site](https://beads.gascity.com/) and
[IDE and agent setup](docs/getting-started/ide-setup.md).
See [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for full instructions.
<!-- Contributor-only file. Do not run `bd setup` or `bd init` against this
checkout: they would inject the end-user beads integration block here. -->
This file exists for compatibility with tools that look for AGENTS.md.
Nested `AGENTS.md` files hold area-specific rules; the routing table at the
end lists them. `CLAUDE.md` files are symlinks to their sibling `AGENTS.md`.
The marker above tells `bd doctor` that the intentional divergence between
this file and `CLAUDE.md` (different audiences, different reading orders) is
expected and should not be flagged.
## How work flows here
## Key Sections
GitHub Issues is the public tracker, and every PR links a documented issue.
The issue carries the context reviewers and future readers need: for a bug,
the reproduction, impact, and evidence; for a change, the motivation, impact,
risk, and verification plan.
- **Issue Tracking** - How to use bd for work management
- **Development Guidelines** - Code standards and testing
- **Project Scope** - Read [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) before adding new feature surface area
- **Visual Design System** - Status icons, colors, and semantic styling for CLI output
- **Contributor Protection** - Read [CONTRIBUTING.md](CONTRIBUTING.md) before handling external PRs
- **Maintainer PR Guidelines** - Read [PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md) before triaging, landing, or closing PRs
1. Find or file the issue with the bug or feature form. It does not need
maintainer approval first; file it before or alongside the PR.
2. Work on a branch, open a PR against `main` whose body says
`Closes #<issue>`, and let CI and review run.
3. Maintainers triage issues with `status/needs-triage`, `status/needs-info`,
`status/needs-repro`, `status/needs-design`, and `status/accepted`
(confirmed); see [CONTRIBUTING.md](CONTRIBUTING.md).
## Project Scope
Maintainers also keep an internal bd ledger. It is optional for contributors
and not a substitute for the GitHub issue.
Before adding new feature surface area, read
[engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md). Beads owns issue tracking
primitives and should not encode orchestration-layer policy, become a storage
engine, or casually expand the database schema when metadata would work.
## Agent contribution policy
## PR Safety for Agents
- Every PR closes a documented issue. If none exists for your change, file
one with the bug or feature form fields, filling each from evidence and
answering `NOT_ENOUGH_INFO` where the evidence runs out, then link it from
the PR.
- A human reviews and stands behind every issue and PR an agent drafts.
Evidence that the change works end-to-end is required; "unit tests pass"
alone is not evidence.
- Before implementing work, opening a PR, or merging/closing a PR, run the PR
preflight:
```bash
scripts/pr-preflight.sh --search "<topic keywords>" --repo gastownhall/beads
scripts/pr-preflight.sh <pr-number> --repo gastownhall/beads
```
The preflight is the agent gate for PR handling; do not rely on
auto-discovery of CONTRIBUTING.md.
- Use `gh` for GitHub issues and PRs, not browser tools. Write PR, issue,
comment, and review bodies to a file, run `scripts/gh-body-lint <body-file>`,
and pass the file with `gh ... --body-file`. Sign agent-written GitHub
comments and reviews per [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md).
Before triaging, reviewing, landing, closing, or otherwise maintaining PRs, read
## Contributor protection
External contributor PRs have priority. Read [CONTRIBUTING.md](CONTRIBUTING.md)
— it contains promises we've made to contributors — and, before triaging,
reviewing, landing, closing, or otherwise maintaining PRs,
[PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md). The maintainer
policy is to maximize community throughput: find useful contributor value,
absorb or transform it locally when practical, preserve attribution, and use
request-changes only as a last resort.
Before implementing work, opening a PR, or merging/closing a PR, run the PR
preflight:
```bash
scripts/pr-preflight.sh --search "<topic keywords>" --repo gastownhall/beads
scripts/pr-preflight.sh <pr-number> --repo gastownhall/beads
```
Before implementing any feature or fix, check for existing open PRs on the
same topic. If one exists:
External contributor PRs have priority. Review and build on their branch when
possible, preserve their tests and attribution, and never close or supersede
their PR silently. If a rewrite is unavoidable, explain why on the original PR
and credit their design/tests.
1. **Review it first** — read the diff, understand the approach.
2. **Build on their work, don't rewrite it** — check out their branch,
fix/adapt as needed.
3. **Preserve their tests** — keep them unless they're wrong.
4. **Attribute properly** — `Co-authored-by:` in commits, reference their PR.
5. **Never close or supersede their PR silently.** If a rewrite is
unavoidable, explain why on the original PR and credit their design/tests.
## Visual Design Anti-Patterns
## Scope: where a change belongs
**NEVER use emoji-style icons** (🔴🟠🟡🔵⚪) in CLI output. They cause cognitive overload.
Read [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) before adding
feature surface area. Beads owns issue tracking primitives and should not
encode orchestration-layer policy, become a storage engine, or casually expand
the database schema when metadata would work. Prefer, in order: issue
metadata over new fields, a flag on an existing command over a new command,
an integration or plugin over core, and leave orchestration policy to the
orchestration layer.
**ALWAYS use small Unicode symbols** with semantic colors (status uses symbols; priority uses labels):
- Status: `○ ◐ ● ✓ ❄`
- Priority: `P0`–`P4` label with color (no status glyph)
**Storage boundary.** Beads talks to storage through a driver interface
(`dolthub/driver` for Dolt). Do not add beads-side flocks, engine
introspection, storage-specific retry or crash-recovery logic, or public SDK
return types that leak driver internals. If the boundary is too narrow, widen
the interface or route the issue to the driver instead of patching around it
in beads. `bd doctor` support for embedded mode is enabled one subcommand at a
time, each human-vetted (GH#3794): do not lift the embedded-mode gate in
`cmd/bd/doctor.go` wholesale, and keep database-layer checks and fixes
server-gated until the driver interface covers them.
See [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for full development guidelines.
**Layering.** Schema → `internal/storage/issueops` → `cmd/bd`. Add new
primitives at the lowest layer first, one layer per PR, stacked when a fix
spans layers. See
[CONTRIBUTING_PR_GUIDELINES.md](CONTRIBUTING_PR_GUIDELINES.md).
## Storage Boundary
The canonical storage boundary is in
[engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md#storage-boundary). In short:
Beads talks to storage through a driver interface (`dolthub/driver` for Dolt).
Do not add beads-side flocks, engine introspection, storage-specific retry or
crash-recovery logic, or public SDK return types that leak driver internals.
If the boundary is too narrow, widen the interface or route the issue to the
driver instead of patching around it in beads.
A live application of this rule: `bd doctor` support for embedded mode is
enabled one subcommand at a time, each human-vetted (GH#3794). Do not lift the
embedded-mode gate in `cmd/bd/doctor.go` wholesale, and keep database-layer
checks and fixes server-gated until the driver interface covers them.
## Agent Warning: Interactive Commands
**DO NOT use `bd edit`** - it opens an interactive editor ($EDITOR) which AI agents cannot use.
Use `bd update` with flags instead:
```bash
bd update <id> --description "new description"
bd update <id> --title "new title"
bd update <id> --design "design notes"
bd update <id> --append-notes "additional notes" # --notes replaces existing notes and requires --force once notes are set
bd update <id> --acceptance "acceptance criteria"
# Use stdin for descriptions with special characters (backticks, !, nested quotes)
echo 'Description with `backticks` and "quotes"' | bd create "Title" --description=-
echo 'Updated text' | bd update <id> --description=-
```
## Testing
Use [engdocs/TESTING.md](engdocs/TESTING.md) for the canonical commands,
test-design guidance, and PR-readiness gates.
## Non-Interactive Shell Commands
**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts.
Shell commands like `cp`, `mv`, and `rm` may be aliased to include `-i` (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.
**Use these forms instead:**
```bash
# Force overwrite without prompting
cp -f source dest # NOT: cp source dest
mv -f source dest # NOT: mv source dest
rm -f file # NOT: rm file
# For recursive operations
rm -rf directory # NOT: rm -r directory
cp -rf source dest # NOT: cp -r source dest
```
**Other commands that may prompt:**
- `scp` - use `-o BatchMode=yes` for non-interactive
- `ssh` - use `-o BatchMode=yes` to fail instead of prompting
- `apt-get` - use `-y` flag
- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var
## Landing the Plane (Session Completion)
**When ending a work session** (or when the user says "let's land the
plane"), you MUST complete ALL steps below. Work is NOT complete until
`git push` succeeds.
**MANDATORY WORKFLOW:**
1. **File issues for remaining work** - Create issues for anything that needs follow-up
2. **Run quality gates** (if code changed):
- `make ci-pr-lint` (required zero-finding formatting and lint wrapper)
- `make test` (and `make test-icu-path` only if you intentionally need the ICU regex path)
- File a P0 issue if quality gates are broken
3. **Update issue status** - Close finished work, update in-progress items
4. **PUSH TO REMOTE** - This is MANDATORY:
```bash
git pull --rebase
git push
git status # MUST show "up to date with origin"
```
5. **Clean up**:
```bash
git stash clear # Remove old stashes
git remote prune origin # Clean up deleted remote branches
```
6. **Verify** - All changes committed AND pushed, no untracked files remain
7. **Hand off** - Choose a follow-up issue and give the user a prompt for
the next session, e.g. "Continue work on bd-X: [issue title]. [Brief
context about what's been done and what's next]"
**CRITICAL RULES:**
- Work is NOT complete until `git push` succeeds
- NEVER stop before pushing - that leaves work stranded locally
- NEVER say "ready to push when you are" - YOU must push
- If push fails, resolve and retry until it succeeds
Close with a summary for the user: what was completed this session, issues
filed for follow-up, quality-gate status, confirmation everything is pushed,
and the recommended prompt for the next session.
<!-- BEGIN BEADS INTEGRATION v:1 profile:full hash:bacef91e -->
## Issue Tracking with bd (beads)
**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
### Why bd?
- Dependency-aware: Track blockers and relationships between issues
- Git-friendly: Dolt-powered version control with native sync
- Agent-optimized: JSON output, ready work detection, discovered-from links
- Prevents duplicate tracking systems and confusion
### Quick Start
**Check for ready work:**
## Build, test, lint
```bash
bd ready --json
make install # build and install bd to ~/.local/bin (canonical)
make test # unit tests with the right build tags
make ci-pr-lint # required zero-finding formatting + lint contract
make check-docs # doc flag, freshness, and docsync checks
make bazel-sync # after adding/removing/renaming Go files or changing imports/go.mod
```
**Create new issues:**
- **Do NOT** use `go build -o bd ./cmd/bd`, `go install ./cmd/bd`, or raw
`go run ./cmd/bd ...`: they bypass the canonical build path, leave stale
binaries, and raw `go run` misses the `gms_pure_go` tag. Use `make install`,
`./bd`, or `go run -tags gms_pure_go ./cmd/bd ...`.
- All new features need tests. Choose them with
[engdocs/TESTING.md](engdocs/TESTING.md); it is the canonical source for
commands, test design, and PR-readiness gates.
- **Never pollute a production database with test issues.** Use `t.TempDir()`
in Go tests and a disposable working directory for manual `bd` experiments.
- `make ci-pr-lint` must pass with zero issues; see
[engdocs/LINTING.md](engdocs/LINTING.md).
- **Optional shared Bazel cache (opt-in).** `--config=fork-cache` reads the
project's anonymous, read-only cache, so results CI already computed are
hits and nothing is uploaded. It is off by default; when setting up a dev
environment, ask your human before adding `build --config=fork-cache` to
`.bazelrc.local`.
- Without Bazel, let CI sync BUILD files: on same-repo PRs the bazel-autofix
workflow pushes the fix to your branch (pull before pushing again); fork PRs
get a comment with an apply recipe.
- If you changed behavior, update the user docs (`docs/`, via the
`beads-docs` skill) or README in the same PR.
```bash
bd create "Issue title" --description="Detailed context" -t bug|feature|task -p 0-4 --json
bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --json
```
## Commits and PRs
**Claim and update:**
- Conventional Commits: `type(scope): summary` (`fix`, `feat`, `docs`,
`test`, `refactor`, `chore`, `ci`, `perf`).
- For agent-prepared commits, include the `Agent-Signature:` trailer described
in [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md). Use
`unknown-model` or `unknown-reasoning` when reliable runtime metadata is
unavailable.
- Maintainers working from the internal ledger may also end the subject with
the bead ID, e.g. `(bd-abc)`, so `bd doctor` can detect orphaned issues.
- Work on a feature branch and open a PR against `main`; direct pushes to
`main` are reserved for releases and narrow operational fixes.
- When the user asks to bump the version, use `./scripts/bump-version.sh`; the
full release process is in [RELEASING.md](RELEASING.md).
```bash
bd update <id> --claim --json
bd update bd-42 --priority 1 --json
```
## Ending a session
**Complete work:**
Do not push to `main`. Before handing off:
```bash
bd close bd-42 --reason "Completed" --json
```
1. Run the quality gates your change needs (`make ci-pr-lint`, the tests
[engdocs/TESTING.md](engdocs/TESTING.md) selects). If gates are broken on
`main`, report it as a P0 issue.
2. Record follow-up work as GitHub issues (or ledger beads, for maintainers).
3. Commit, push, or open a PR only when the person you are working for asked
you to. Report changed files, validation run, and anything left open.
### Issue Types
## CLI output
- `bug` - Something broken
- `feature` - New functionality
- `task` - Work item (tests, docs, refactoring)
- `epic` - Large feature with subtasks
- `chore` - Maintenance (dependencies, tooling)
**NEVER use emoji-style icons** (🔴🟠🟡🔵⚪) in CLI output. **ALWAYS use small
Unicode symbols** with semantic colors: status `○ ◐ ● ✓ ❄`; priority as a
`P0`–`P4` label with color (no status glyph). The full visual design system
and CLI design principles are in
[engdocs/UI_PHILOSOPHY.md](engdocs/UI_PHILOSOPHY.md).
### Priorities
## Non-interactive shell commands
- `0` - Critical (security, data loss, broken builds)
- `1` - High (major features, important bugs)
- `2` - Medium (default, nice-to-have)
- `3` - Low (polish, optimization)
- `4` - Backlog (future ideas)
Agents cannot answer prompts. Use `cp -f`, `mv -f`, `rm -f`, `rm -rf`,
`cp -rf` (these may be aliased to `-i`); `scp`/`ssh -o BatchMode=yes`;
`apt-get -y`; `HOMEBREW_NO_AUTO_UPDATE=1 brew`. **DO NOT use `bd edit`** — it
opens `$EDITOR`; use `bd update <id> --title/--description/--design/--acceptance/--append-notes`
(pipe text with special characters via `--description=-`).
### Workflow for AI Agents
## Routing table
1. **Check ready work**: `bd ready` shows unblocked issues
2. **Claim your task atomically**: `bd update <id> --claim`
3. **Work on it**: Implement, test, document
4. **Discover new work?** Create linked issue:
- `bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:<parent-id>`
5. **Complete**: `bd close <id> --reason "Done"`
### Quality
- Use `--acceptance` and `--design` fields when creating issues
- Use `--validate` to check description completeness
### Lifecycle
- `bd defer <id>` / `bd supersede <id>` for issue management
- `bd stale` / `bd orphans` / `bd lint` for hygiene
- `bd human <id>` to flag for human decisions
- `bd formula list` / `bd mol pour <name>` for structured workflows
### Sync
bd stores issue history in Dolt:
- Each write auto-commits to Dolt history
- Use `bd dolt push`/`bd dolt pull` for remote sync
- Do not treat `.beads/issues.jsonl` as the sync protocol
**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns.
### Important Rules
- ✅ Use bd for ALL task tracking
- ✅ Always use `--json` flag for programmatic use
- ✅ Link discovered work with `discovered-from` dependencies
- ✅ Check `bd ready` before asking "what should I work on?"
- ❌ Do NOT create markdown TODO lists
- ❌ Do NOT use external issue trackers
- ❌ Do NOT duplicate tracking systems
For more details, see README.md and https://github.com/gastownhall/beads/blob/main/docs/getting-started/quickstart.md.
## Agent Context Profiles
The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.
- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands.
- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise.
- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.
## Session Completion
This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.
1. **File issues for remaining work** - Create beads for anything that needs follow-up
2. **Run quality gates** (if code changed) - Tests, linters, builds
3. **Update issue status** - Close finished work, update in-progress items
4. **Handle git/sync by active profile**:
```bash
# Conservative/minimal/default: report status and proposed commands; wait for approval.
git status
# Team-maintainer opt-in only, unless current instructions forbid it:
git pull --rebase
bd dolt push
git push
git status
```
5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step
**Critical rules:**
- Explicit user or orchestrator instructions override this Beads block.
- Do not commit or push without clear authority from the active profile or the current user request.
- If a required sync or push is blocked, stop and report the exact command and error.
<!-- END BEADS INTEGRATION -->
| When you are touching… | Read first |
|---|---|
| `cmd/bd/` (commands, output, proxied-server routes) | [cmd/bd/AGENTS.md](cmd/bd/AGENTS.md) |
| `engdocs/` (contributor and internals docs) | [engdocs/AGENTS.md](engdocs/AGENTS.md) |
| `docs/` (the published user docs) | `.claude/skills/beads-docs/SKILL.md` |
| Any Go test | [engdocs/TESTING.md](engdocs/TESTING.md) |
| Lint failures or `.golangci.yml` | [engdocs/LINTING.md](engdocs/LINTING.md) |
| A new storage operation or issueops role | [engdocs/ADDING_AN_ISSUEOPS_ROLE.md](engdocs/ADDING_AN_ISSUEOPS_ROLE.md) |
| Schema migrations | [internal/storage/schema/migrations/README.md](internal/storage/schema/migrations/README.md) |
| Dolt concurrency, server vs embedded mode | [engdocs/design/dolt-concurrency.md](engdocs/design/dolt-concurrency.md) |
| Errors returned to users | [engdocs/ERROR_HANDLING.md](engdocs/ERROR_HANDLING.md) |
| The `bd serve` HTTP surface | [engdocs/SERVE_RUNBOOK.md](engdocs/SERVE_RUNBOOK.md) |
| A new example under `examples/` | `examples/README.md` — give the example its own README and link it there |
| Releases and version bumps | [RELEASING.md](RELEASING.md) |
| Scope questions | [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) |
| Planned work and priorities | [ROADMAP.md](ROADMAP.md) |

View file

@ -1,537 +1,9 @@
# Detailed Agent Instructions for Beads Development
# Agent Instructions
**For project overview and quick start, see [AGENTS.md](AGENTS.md)**
Contributor instructions for agents developing beads live in
[AGENTS.md](AGENTS.md). Area-specific rules live in nested `AGENTS.md` files
listed in its routing table.
This document contains detailed operational instructions for AI agents working on beads development, testing, and releases.
## Development Guidelines
### Code Standards
- **Go version**: see `go.mod` for the required version (currently 1.26+)
- **Linting**: `make ci-pr-lint` must pass with zero issues; see
[engdocs/LINTING.md](engdocs/LINTING.md)
- **Testing**: All new features need tests; use [engdocs/TESTING.md](engdocs/TESTING.md) for command selection, test design, and PR readiness.
- **Documentation**: Update relevant .md files
### File Organization
```
beads/
├── cmd/bd/ # CLI commands
├── internal/
│ ├── types/ # Core data types
│ └── storage/ # Storage layer
│ └── dolt/ # Dolt implementation
├── examples/ # Integration examples
└── *.md # Documentation
```
### Testing Workflow
**IMPORTANT:** Never pollute the production database with test issues!
For test commands, tier selection, and test-design guidance, use the canonical
[engdocs/TESTING.md](engdocs/TESTING.md).
**For manual testing**, keep initialization and all experiments in a disposable
working directory. This safety example supplements the canonical testing guide:
```bash
beads_manual_dir="$(mktemp -d)"
(
set -e
cd "$beads_manual_dir"
bd init --quiet --prefix test --skip-hooks --skip-agents
bd create "Test issue" -p 1
)
rm -rf -- "$beads_manual_dir"
```
`BEADS_DB` alone does not redirect `bd init` workspace setup. Do not run manual
initialization from a production workspace even when selecting another database.
**For automated tests**, use `t.TempDir()` in Go tests:
```go
func TestMyFeature(t *testing.T) {
tmpDir := t.TempDir()
testDB := filepath.Join(tmpDir, ".beads", "beads.db")
s := newTestStore(t, testDB)
// ... test code
}
```
**Git test isolation:** For tests that create temporary git repos, force repo-local hooks:
```bash
git config core.hooksPath .git/hooks
```
Do not rely on the developer's global git config. Global `core.hooksPath` can leak
into temp repos and produce flaky test behavior.
**Warning:** bd will warn you when creating issues with a "Test" prefix in the
production database. The disposable working directory is the isolation
boundary for manual initialization and experiments.
**Tmpfs hosts:** the `cmd/bd` test suite creates an isolated `$HOME` and several
test binaries under `$TMPDIR`. They are normally cleaned by the test process,
but a SIGKILLed or OOMed run can leave orphans behind. On hosts where `/tmp`
is tmpfs (e.g. Fedora Atomic / Bluefin), run `make clean-test-tmp` between
test runs if `du -sh /tmp/beads-* /tmp/bd-*` shows accumulation. See bd-3q2u.
### Before Committing
1. **Run tests**: follow [engdocs/TESTING.md](engdocs/TESTING.md).
2. **Run the required lint contract when its code surface changed**:
`make ci-pr-lint`
3. **Update docs**: If you changed behavior, update README.md or other docs
4. **Sync Bazel BUILD files** if you added, removed or renamed Go files, or
changed imports or `go.mod`: `make bazel-sync` (needs Bazel), then commit
the BUILD.bazel / MODULE.bazel changes. Without Bazel, let CI do it: on
same-repo PRs the bazel-autofix workflow pushes the fix for the packages
your PR changed to your branch (pull before pushing again); fork PRs get
a comment with an apply recipe.
5. **Commit**: With git hooks installed (`bd hooks install`), Dolt changes are auto-committed
### Commit Message Convention
When committing work for an issue, include the issue ID in parentheses at the end:
```bash
git commit -m "Fix auth validation bug (bd-abc)"
git commit -m "Add retry logic for database locks (bd-xyz)"
```
This enables `bd doctor` to detect **orphaned issues** - work that was committed but the issue wasn't closed. The doctor check cross-references open issues against git history to find these orphans.
For agent-prepared commits, also include the
`Agent-Signature:` trailer described in
[engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md). Use `unknown-model` or
`unknown-reasoning` when reliable runtime metadata is unavailable.
### Git Workflow
bd uses **Dolt** as its primary database. Changes are committed to Dolt history automatically (one Dolt commit per write command).
**Install git hooks** for commit integration and legacy fallback behavior:
```bash
bd hooks install
```
### Git Integration
**Dolt sync**: Dolt handles sync natively via `bd dolt push` / `bd dolt pull`. No export/import round-trip needed for normal sync.
**Protected branches**: Dolt stores data under `refs/dolt/data`, separate from standard Git refs. See [docs/reference/protected-branches.md](docs/reference/protected-branches.md).
**Git worktrees**: Work directly with Dolt — no special flags needed. See [docs/reference/advanced.md](docs/reference/advanced.md).
**Merge conflicts**: Rare with hash IDs. Dolt uses cell-level 3-way merge for conflict resolution.
## Git Workflow: PR by Default
Crew workers use a PR-based workflow. Beads is a dependency of a downstream consumer, so we
defer to the standard PR flow to keep changes reviewable.
- Work on a feature branch, push the branch, open a PR against `main`
- `gh pr create` is the normal path to land work
- Direct push to main is reserved for releases (tag + release commit) and
narrow operational fixes; prefer a PR when unsure
- When handling external contributor PRs, use fix-merge: checkout the PR
branch locally, fix/rebase onto main, merge via PR, then close the PR
### Maintainer PR Guidelines
Before triaging, reviewing, landing, closing, or otherwise maintaining PRs,
read [PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md). The
maintainer policy is to maximize community throughput: find useful contributor
value, absorb or transform it locally when practical, preserve attribution, and
use request-changes only as a last resort.
Sign agent-written GitHub comments and reviews using
[engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md).
### External Contributor PRs: Check Before You Build
**Read [CONTRIBUTING.md](CONTRIBUTING.md)** — it contains promises we've made to contributors. Violating them damages trust and community.
Run the read-only preflight before implementing related work, opening a PR, or
merging/closing a PR:
```bash
scripts/pr-preflight.sh --search "<topic keywords>" --repo gastownhall/beads
scripts/pr-preflight.sh <pr-number> --repo gastownhall/beads
```
**Before implementing any feature or fix, check for existing open PRs on the same topic:**
```bash
gh pr list --repo gastownhall/beads --state open --search "<topic keywords>" --json number,title,author,headRefName
```
**Contributor work gets priority.** If an external PR already exists:
1. **Review it first** — read the diff, understand the approach
2. **Build on their work, don't rewrite it** — checkout their branch, fix/adapt as needed
3. **Preserve their tests** — contributor tests are signal; keep them unless they're wrong
4. **Attribute properly** — use `Co-authored-by:` in commits, reference their PR number
5. **Never auto-close a contributor PR** by merging a rewrite — that discards their contribution silently
If you must rewrite (e.g., fundamentally different approach needed), explain why on the original PR and credit the contributor's design/tests in your commits.
Do not rely on auto-discovery of CONTRIBUTING.md; the preflight is the agent
gate for PR handling.
## Landing the Plane
See [AGENTS.md](AGENTS.md#landing-the-plane-session-completion) for the
canonical session-completion protocol (quality gates, mandatory `git push`,
cleanup, and next-session hand-off).
## Agent Session Workflow
**WARNING: DO NOT use `bd edit`** - it opens an interactive editor ($EDITOR) which AI agents cannot use. Use `bd update` with flags instead:
```bash
bd update <id> --description "new description"
bd update <id> --title "new title"
bd update <id> --design "design notes"
bd update <id> --append-notes "additional notes" # --notes replaces existing notes and requires --force once notes are set
bd update <id> --acceptance "acceptance criteria"
```
**Read execution metadata before prose.** When enacting a bd issue, inspect the
structured metadata before using description or notes to choose execution mode,
delegation, model, reasoning level, or parallel group:
```bash
bd show <id> --json | jq '.[0] | {id,title,metadata,description,notes}'
```
The execution metadata keys are:
- `execution_agent_type`
- `execution_suggested_model`
- `execution_reasoning_effort`
- `execution_mode`
- `execution_parallel_group`
When these keys are present, treat them as the authoritative execution hints.
Use `description` for the work scope and `notes` for rationale or fallback
context. Parent/orchestrator agents must read these fields before spawning
subagents because a running subagent cannot change its model or reasoning effort
after launch.
**Use stdin for descriptions with special characters** (backticks, `!`, nested quotes):
```bash
# Pipe via stdin to avoid shell escaping issues
echo 'Description with `backticks` and "quotes"' | bd create "Title" --stdin
echo 'Updated description with $variables' | bd update <id> --description=-
# Or use --body-file for longer content
bd create "Title" --body-file=description.md
```
**GitHub body hygiene.** For GitHub PR, issue, comment, and review bodies,
write Markdown to a file and pass it with `gh ... --body-file`. Run
`scripts/gh-body-lint <body-file>` first to catch literal `\n` sequences and
non-linking `GH#123` references.
**Example agent session:**
```bash
# Make changes (each write auto-commits to Dolt)
bd create "Fix bug" -p 1
bd create "Add tests" -p 1
bd update bd-42 --claim
bd close bd-40 --reason "Completed"
# Push Dolt data to remote if configured
bd dolt push
# Now safe to end session
```
This installs:
- **pre-commit** — Commits pending Dolt changes
- **post-merge** — Runs chained hooks and a legacy JSONL import fallback only when no Dolt remote is configured
**Note:** Hooks are embedded in the bd binary and work for all bd users (not just source repo users).
## Common Development Tasks
### Visual Design System
When adding CLI output features, follow these design principles for consistent,
cognitively friendly visuals.
#### No Emoji-Style Icons
Do not use large colored emoji icons like red/orange/yellow/blue/white circles
for priorities or status. They cause cognitive overload and break visual
consistency.
Use small Unicode symbols with semantic colors applied via lipgloss:
- Status: `○ ◐ ● ✓ ❄`
- Priority: `P0`–`P4` label with color (no status glyph)
#### Status Icons
Use these symbols consistently across all commands:
```text
○ open - Available to work (white/default)
◐ in_progress - Currently being worked (yellow)
● blocked - Waiting on dependencies (red)
✓ closed - Completed (muted gray)
❄ deferred - Scheduled for later (blue/muted)
```
#### Priority Labels and Colors
Format priority as the P-label with color only (no status glyph — `●` is blocked status):
- `P0`: Red + bold (critical)
- `P1`: Orange (high)
- `P2`: Amber (elevated)
- `P3`–`P4`: Default text
#### Issue Type Colors
- `bug`: Red (problems need attention)
- `epic`: Purple (larger scope)
- Others: Default text
#### Design Principles
1. Small Unicode symbols only; avoid emoji blobs.
2. Semantic colors only for actionable items; do not color everything.
3. Closed items fade using muted gray.
4. Prefer icons over text labels for scanability.
5. Keep icons consistent across list, graph, show, and related commands.
6. Use tree connectors (`├──`, `└──`, `│`) for hierarchies.
7. Reduce cognitive noise; do not show `needs:1` when it is just the parent epic.
#### Semantic Styles
Use exported styles from `internal/ui/styles.go`:
```go
// Status styles
ui.StatusInProgressStyle // Yellow - active work
ui.StatusBlockedStyle // Red - needs attention
ui.StatusClosedStyle // Muted gray - done
// Priority styles
ui.PriorityP0Style // Red + bold
ui.PriorityP1Style // Orange
// Type styles
ui.TypeBugStyle // Red
ui.TypeEpicStyle // Purple
// General styles
ui.PassStyle, ui.WarnStyle, ui.FailStyle
ui.MutedStyle, ui.AccentStyle
ui.RenderMuted(text), ui.RenderAccent(text)
```
Example:
```go
switch issue.Status {
case types.StatusOpen:
icon = "○"
case types.StatusInProgress:
icon = ui.StatusInProgressStyle.Render("◐")
case types.StatusBlocked:
icon = ui.StatusBlockedStyle.Render("●")
case types.StatusClosed:
icon = ui.StatusClosedStyle.Render("✓")
}
```
### CLI Design Principles
**Minimize cognitive overload.** Every new command, flag, or option adds cognitive burden for users. Before adding anything:
1. **Recovery/fix operations → `bd doctor --fix`**: Don't create separate commands like `bd recover` or `bd repair`. Doctor already detects problems - let `--fix` handle remediation. This keeps all health-related operations in one discoverable place.
For git hook marker migration specifically: use `bd migrate hooks --dry-run` to preview operations, and `bd doctor --fix` for the standard apply path.
2. **Prefer flags on existing commands**: Before creating a new command, ask: "Can this be a flag on an existing command?" Example: `bd list --stale` instead of `bd stale`.
3. **Consolidate related operations**: Related operations should live together. Version control uses `bd vc {log,diff,commit}`, not separate top-level commands.
4. **Count the commands**: Run `bd --help` and count. If we're approaching 30+ commands, we have a discoverability problem. Consider subcommand grouping.
5. **New commands need strong justification**: A new command should represent a fundamentally different operation, not just a convenience wrapper.
### Adding a New Command
1. Create file in `cmd/bd/`
2. Add to root command in `cmd/bd/main.go`
3. Implement with Cobra framework
4. Add `--json` flag for agent use
5. Add tests in `cmd/bd/*_test.go`
6. Document in README.md
### Adding Storage Features
1. Add Dolt SQL schema changes in `internal/storage/dolt/`
2. Add migration if needed
3. Update `internal/types/types.go` if new types
4. Implement in `internal/storage/dolt/` (queries, issues, etc.)
5. Add tests
6. Update export/import in `cmd/bd/export.go` and `cmd/bd/import.go`
### Adding Examples
1. Create directory in `examples/`
2. Add README.md explaining the example
3. Include working code
4. Link from `examples/README.md`
5. Mention in main README.md
## Building
```bash
# Build and install bd to ~/.local/bin (the canonical location)
make install
# Verify installed binary
bd init --prefix test
bd create "Test issue" -p 1
bd ready
```
For testing commands, test design, and PR-readiness gates, use
[engdocs/TESTING.md](engdocs/TESTING.md).
> **WARNING**: Do NOT use `go build -o bd ./cmd/bd`, `go install ./cmd/bd`,
> or raw `go run ./cmd/bd ...`.
> These bypass the canonical build path, can create stale binaries in the
> working directory or `~/go/bin/`, and raw `go run` may miss the required
> `gms_pure_go` build tag. Always use `make install`, `./bd`, or
> `go run -tags gms_pure_go ./cmd/bd ...` when you explicitly need `go run`.
## Version Management
**IMPORTANT**: When the user asks to "bump the version" or mentions a new version number (e.g., "bump to 0.9.3"), use the version bump script:
```bash
# Preview changes (shows diff, doesn't commit)
./scripts/bump-version.sh 0.9.3
# Auto-commit the version bump
./scripts/bump-version.sh 0.9.3 --commit
git push origin main
```
**What it does:**
- Updates ALL version files (CLI, plugin, MCP server, docs) in one command
- Validates semantic versioning format
- Shows diff preview
- Verifies all versions match after update
- Creates standardized commit message
**User will typically say:**
- "Bump to 0.9.3"
- "Update version to 1.0.0"
- "Rev the project to 0.9.4"
- "Increment the version"
**You should:**
1. Run `./scripts/bump-version.sh <version> --commit`
2. Push to GitHub
3. Confirm all versions updated correctly
**Files updated automatically:**
- `cmd/bd/version.go` - CLI version
- `plugins/beads/.claude-plugin/plugin.json` - Claude plugin version
- `plugins/beads/.codex-plugin/plugin.json` - Codex plugin version
- `.claude-plugin/marketplace.json` - Claude marketplace version
- `integrations/beads-mcp/pyproject.toml` - MCP server version
- `README.md` - Documentation version
- `PLUGIN.md` - Version requirements
**Why this matters:** We had version mismatches (bd-66) when only `version.go` was updated. This script prevents that by updating all components atomically.
See `scripts/README.md` for more details.
## Release Process (Maintainers)
See [RELEASING.md](RELEASING.md) for the complete release process, including
the automated `./scripts/release.sh <version>` script and the manual,
step-by-step channel-by-channel instructions.
## Checking GitHub Issues and PRs
**IMPORTANT**: When asked to check GitHub issues or PRs, use command-line tools like `gh` instead of browser/playwright tools.
**Preferred approach:**
```bash
# List open issues with details
gh issue list --limit 30
# List open PRs
gh pr list --limit 30
# View specific issue
gh issue view 201
```
**Then provide an in-conversation summary** highlighting:
- Urgent/critical issues (regressions, bugs, broken builds)
- Common themes or patterns
- Feature requests with high engagement
- Items that need immediate attention
**Why this matters:**
- Browser tools consume more tokens and are slower
- CLI summaries are easier to scan and discuss
- Keeps the conversation focused and efficient
- Better for quick triage and prioritization
**Do NOT use:** `browser_navigate`, `browser_snapshot`, or other playwright tools for GitHub PR/issue reviews unless specifically requested by the user.
## Telemetry
`bd` collects anonymous command-usage metrics. Each event is a `cli_command`
record carrying only the command name; each batch also carries the bd version
and OS platform, keyed by a machine-derived, HMAC-protected distinct ID. No
email, repo path, remote URL, issue content, or user-supplied strings are
collected. Events are written under `~/.beads/eventsData` and POSTed to
`https://gastownhall-eventsapi.com/mp/collect`.
Metrics are enabled by default (opt-out). The friendliest way to see or change
them is `bd metrics` (`bd metrics on` / `bd metrics off` / `bd metrics example`),
which takes effect on the next command with no restart. `BD_DISABLE_METRICS=1`
still works as a one-off, shell-scoped override. The cross-tool
[`DO_NOT_TRACK`](https://donottrack.sh/) standard is honored as a disable-only
opt-out: `DO_NOT_TRACK=1` opts out, while a falsey or empty value
(`DO_NOT_TRACK=0`, `false`, or unset-but-present) falls through to your saved
`bd metrics` preference instead of forcing metrics back on. `BD_DISABLE_METRICS`
is the bidirectional override and takes precedence when both are set.
## Questions?
- Check existing issues: `bd list`
- Look at recent commits: `git log --oneline -20`
- Read the docs: README.md, ADVANCED.md, docs/reference/configuration.md
- Create an issue if unsure: `bd create "Question: ..." -t task -p 2`
## Important Files
- **README.md** - Main documentation (keep this updated!)
- **ADVANCED.md** - Advanced features (rename, merge, compaction)
- **CONTRIBUTING.md** - Contribution guidelines
- **SECURITY.md** - Security policy
If you are using `bd` to track work in your own project, see the user docs:
[IDE and agent setup](docs/getting-started/ide-setup.md) and
[https://beads.gascity.com/](https://beads.gascity.com/).

View file

@ -81,6 +81,8 @@ filegroup(
"engdocs/**",
]) + [
"integrations/beads-mcp/PYPI.md",
"//cmd/bd:AGENTS.md",
"//internal/storage/schema:migrations/README.md",
"//scripts:README.md",
],
visibility = ["//test/docsync:__pkg__"],

View file

@ -1,23 +0,0 @@
# Claude Code Entry Point for Beads
This file is intentionally short. Do not copy workflow, build, storage, or UI
rules here; those details drift quickly when repeated across agent entrypoints.
## Read First
- **Workflow and safety**: [AGENTS.md](AGENTS.md)
- **Detailed agent operations**: [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md)
- **Architecture orientation**: [engdocs/CLAUDE.md](engdocs/CLAUDE.md)
- **PR maintenance policy**: [PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md)
## Current Ground Rules
- Run `bd prime` before doing tracked work.
- Follow `go.mod` and [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for build
and test commands; do not hard-code toolchain versions here.
- Beads uses Dolt as the issue database. Use `bd dolt push` / `bd dolt pull`
for issue data sync; do not use export/import as a routine git workflow.
- The CLI Visual Design System lives in
[AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md#visual-design-system).
- If this file conflicts with a linked source, trust the linked source and fix
this file by removing the duplicate.

1
CLAUDE.md Symbolic link
View file

@ -0,0 +1 @@
AGENTS.md

View file

@ -2,6 +2,50 @@
Thank you for your interest in contributing to bd! This document provides guidelines and instructions for contributing.
## Issues and pull requests
GitHub Issues is the public tracker, and every pull request links a
documented issue. The issue is where the context lives: why the change is
needed, what it affects, and how we will know it works. File it with the bug
or feature form before or alongside your pull request; it does not need
maintainer approval first.
### Triage labels
| Label | Meaning | Applied by |
|---|---|---|
| `status/needs-triage` | Awaiting initial triage. | Automation, on every new issue |
| `status/needs-info` | Waiting on essential information from the reporter. | Maintainers |
| `status/needs-repro` | Needs a reproducible bug report. | Maintainers |
| `status/needs-design` | The direction needs a design decision before work starts. | Maintainers |
| `status/accepted` | Confirmed and on our radar. | Maintainers |
Issues left in `status/needs-info` or `status/needs-repro` are closed after 14
days without a reply to the request; reply with the details and a
maintainer will reopen them.
Priority (`priority/p0`–`priority/p3`) and kind (`kind/bug`, `kind/feature`,
`kind/docs`, `kind/chore`) labels are set during triage.
### Pull request pipeline labels
These labels drive the maintainers' automated review and merge workflow. They
are applied by maintainers and automation; contributors don't need to set
them.
| Label | Meaning |
|---|---|
| `status/needs-review` | Request the PR review workflow. |
| `status/needs-review-auto` | Request the automated PR review workflow. |
| `status/reviewing` | The PR review workflow is running. |
| `status/review-failed` | The PR review workflow failed before merge-ready. |
| `status/merge-ready` | The PR is ready for the merge workflow. |
| `status/merge-queued` | Queued for deterministic PR-review merge. |
| `status/merge-failed` | The merge queue needs operator attention. |
| `status/needs-bugflow` | Request the bugflow investigation workflow. |
The current priorities are on the [roadmap](ROADMAP.md); work in a priority
area is reviewed first.
## Development Setup
### Prerequisites
@ -29,6 +73,12 @@ make test
make install
```
Optional: if you use Bazel, opt in to the project's anonymous, read-only
build cache by adding `build --config=fork-cache` to your gitignored
`.bazelrc.local` (or pass `--config=fork-cache` per command). Results CI
already computed become cache hits, and nothing you build is uploaded. It is
off by default.
## Project Structure
```
@ -90,21 +140,23 @@ engine, or expand the database schema when issue metadata is sufficient.
### Workflow
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/my-feature`)
1. Find or file a documented issue (see [Issues and pull requests](#issues-and-pull-requests))
2. Fork the repository and create a feature branch (`git checkout -b feature/my-feature`)
3. Make your changes
4. Add tests for new functionality
5. Run tests and linter locally
6. Commit your changes with clear messages
7. Push to your fork
8. Open a pull request
8. Open a pull request whose description says `Closes #<issue>`
### Commit Messages
Write clear, concise commit messages:
Use [Conventional Commits](https://www.conventionalcommits.org/):
`type(scope): summary`, where type is one of `fix`, `feat`, `docs`, `test`,
`refactor`, `chore`, `ci`, or `perf`.
```
Add cycle detection for dependency graphs
feat(dep): add cycle detection for dependency graphs
- Implement recursive CTE-based cycle detection
- Add tests for simple and complex cycles
@ -115,6 +167,10 @@ Add cycle detection for dependency graphs
**One issue per PR, and one PR per issue.** No piggybacking or riders — each PR should address exactly one thing.
Read [CONTRIBUTING_PR_GUIDELINES.md](CONTRIBUTING_PR_GUIDELINES.md) for the
layering rules (schema → storage/issueops → cmd/bd, one layer per PR) and the
repro and benchmark evidence reviewers expect.
- Keep PRs focused on a single feature or fix
- Do not include unrelated changes, cleanup, or "while I'm here" improvements
- Do not include `.beads/` data (database, JSONL) in your PR
@ -178,22 +234,12 @@ round-trip paths should pattern-match on those tests.
## Feature Requests and Bug Reports
### Reporting Bugs
Include in your bug report:
- Steps to reproduce
- Expected behavior
- Actual behavior
- Version of bd (`bd version` if implemented)
- Operating system and Go version
### Feature Requests
When proposing new features:
- Explain the use case
- Describe the proposed solution
- Consider backwards compatibility
- Discuss alternatives you've considered
Use the issue forms: [bug report](https://github.com/gastownhall/beads/issues/new?template=bug_report.yml)
or [feature request](https://github.com/gastownhall/beads/issues/new?template=feature_request.yml).
The feature form asks for the motivation, impact, risk and compatibility,
and verification plan up front, so a maintainer can accept the issue without
a round trip. Questions go to
[Discussions](https://github.com/gastownhall/beads/discussions).
## Your PR Will Not Be Overwritten
@ -309,11 +355,7 @@ dlv debug ./cmd/bd -- create "Test issue"
(For maintainers)
1. Update version in code
2. Update CHANGELOG.md
3. Tag release: `git tag v0.x.0`
4. Push tag: `git push origin v0.x.0`
5. GitHub Actions will build and publish
Follow [RELEASING.md](RELEASING.md); it is the canonical release process.
The pre-push version gate requires Go and validates each `v*` release tag
against the checkout's canonical version. A batch containing different release

View file

@ -211,5 +211,6 @@ This is useful for:
## 📝 Documentation
* [Documentation site](https://beads.gascity.com/) | [Installing](docs/getting-started/installation.md) | [Sync Concepts](docs/core-concepts/sync-concepts.md) | [Agent Workflow](AGENT_INSTRUCTIONS.md) | [Copilot CLI Setup](docs/integrations/copilot-cli.md) | [Copilot VS Code MCP](docs/integrations/github-copilot.md) | [Articles](ARTICLES.md) | [Sync Branch Mode](docs/reference/protected-branches.md) | [Troubleshooting](docs/reference/troubleshooting.md) | [FAQ](docs/reference/faq.md)
* [Documentation site](https://beads.gascity.com/) | [Installing](docs/getting-started/installation.md) | [Sync Concepts](docs/core-concepts/sync-concepts.md) | [Agent Setup](docs/getting-started/ide-setup.md) | [Copilot CLI Setup](docs/integrations/copilot-cli.md) | [Copilot VS Code MCP](docs/integrations/github-copilot.md) | [Articles](ARTICLES.md) | [Sync Branch Mode](docs/reference/protected-branches.md) | [Troubleshooting](docs/reference/troubleshooting.md) | [FAQ](docs/reference/faq.md)
* Contributing: [CONTRIBUTING.md](CONTRIBUTING.md) | [Roadmap](ROADMAP.md) | [Contributor agent instructions](AGENTS.md)
* [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/gastownhall/beads)

69
ROADMAP.md Normal file
View file

@ -0,0 +1,69 @@
# Beads Roadmap
Last updated: 2026-10-05 · Owner: [@julianknutsen](https://github.com/julianknutsen)
This page lists the areas the maintainers are prioritizing. It reflects
current thinking, not commitments or dates: priorities change as we learn,
and the live state of each item is its tracking issue on GitHub.
## How this roadmap is used
- **Priority areas get expedited review.** Issues and PRs that advance a
priority area below are triaged and reviewed first.
- **Every PR links a documented issue.** To propose work — inside or
outside a priority area — open an issue with the feature form, before or
alongside your PR; see
[CONTRIBUTING.md](CONTRIBUTING.md#issues-and-pull-requests).
- **Scope.** Proposals must fit the product boundary in
[engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md).
- **Updates.** The owner rewrites this page at each minor release; the date
above says when it was last reviewed.
## Priority areas for 1.4
### Versioned beads and history
- **Goal:** every change to a bead is recorded as a version. Users can read
a bead's history and past versions, and writers can use `expectedRevision`
compare-and-swap to avoid lost updates. Everything ships behind a flag, off
by default, until the conformance suite and a production-corpus soak say
otherwise.
- **This period:** all six phases, enabled from the CLI by the end of the
period: conformance suite
([#6133](https://github.com/gastownhall/beads/issues/6133)), additive
schema ([#6134](https://github.com/gastownhall/beads/issues/6134)),
dual-write history behind a flag
([#6135](https://github.com/gastownhall/beads/issues/6135)), versioned
reads and CAS ([#6136](https://github.com/gastownhall/beads/issues/6136)),
production-corpus validation
([#6137](https://github.com/gastownhall/beads/issues/6137)), and CLI
surfacing and enablement
([#6138](https://github.com/gastownhall/beads/issues/6138)).
- **Tracking issue:** [#6132](https://github.com/gastownhall/beads/issues/6132);
design discussion stays on
[#5898](https://github.com/gastownhall/beads/issues/5898).
### Beads Graph Preview 2
- **Goal:** ship Beads Graph Preview 2, the next public checkpoint for the
generic Bead-and-Link graph model: a coherent daily-use CLI journey in
graph mode that behaves like ordinary `bd`, backed by a complete,
reviewable CLI specification.
- **This period:** the reviewed graph CLI specification, a complete
daily-use Issue journey proven through the installed CLI on embedded and
shared-server Dolt, and editing around that Issue (labels, notes, Memory
and Link edits).
- **Tracking issue:** [#7170](https://github.com/gastownhall/beads/issues/7170)
### Contributor onboarding
- **Goal:** a new contributor, human or agent, finds the rules for the code
they are changing next to that code, understands its intent and
invariants, and lands a change with a documented issue and PR.
- **This period:** contributor-only agent instructions and documented-issue
intake ([#7223](https://github.com/gastownhall/beads/pull/7223));
per-package `AGENTS.md` files for the storage packages, naming their
guard tests and lint rules; a package-doc linter and package docs for the
packages that have none; and a curated set of `help wanted` starter
issues.
- **Tracking issue:** [#7228](https://github.com/gastownhall/beads/issues/7228)

View file

@ -1,58 +1,90 @@
# Agent Instructions
# cmd/bd — contributor notes
This project uses **bd** (beads) for issue tracking. Run `bd prime` for full workflow context.
`cmd/bd` is the `bd` CLI: one Go package (about 340 non-test files) plus the
`doctor/`, `setup/`, `protocol/`, `help_supplements/`, and `winres/`
subpackages. Commands decide what to do; storage work belongs below them in
`internal/storage/issueops` (see the layering rules in
[CONTRIBUTING_PR_GUIDELINES.md](../../CONTRIBUTING_PR_GUIDELINES.md)).
## Quick Reference
## File families
```bash
bd ready # Find available work (open, no blockers)
bd blocked # Show blocked issues and what blocks them
bd list # List all issues (with blocker annotations)
bd show <id> # View issue details
bd update <id> --claim # Claim work (atomic compare-and-swap)
bd close <id> # Complete work
bd dolt push # Push to Dolt remote
```
| Pattern | Meaning |
|---|---|
| `<cmd>.go` | The Cobra command, its flags, and the mode-independent body. Registers itself with `rootCmd.AddCommand` in its own `init()` — `main.go` adds no commands. |
| `<cmd>_proxied_server.go` | The proxied-server route for the same command. A command that touches the store on a proxied-server workspace needs one. |
| `capability_registry.go` | One table for every command path: what the pre-provider gate does with it on a proxied-server workspace. |
| `<cmd>_embedded_test.go` | `cgo` tests against embedded Dolt. |
| `<cmd>_integration_test.go` | Integration tests, usually `cgo && unix`. |
| `<cmd>_proxied_test.go` | Proxied-server tests. |
| `<topic>_guard_test.go` | Policy and safety guards. |
**Dependency status**: `bd ready` and `bd blocked` are the authoritative
sources for whether work is blocked. `bd list` shows active blocker
annotations but use `bd ready`/`bd blocked` for accurate blocking status.
Which tier a test belongs in, and which command runs it, is decided by
[engdocs/TESTING.md](../../engdocs/TESTING.md).
## Agent Warning: Interactive Commands
## Adding a command
**DO NOT use `bd edit`** - it opens an interactive editor ($EDITOR) which AI agents cannot use.
1. Create `cmd/bd/<cmd>.go` with the Cobra command and register it in that
file's `init()`.
2. Add its row to `capability_registry.go`.
`TestProxyCapabilityRegistryCoversCommandTree` fails if a command path is
missing, and `TestProxyCapabilityRegistryHasNoStaleRows` fails on rows for
paths that no longer exist.
3. If the command uses the store on proxied-server workspaces, add
`<cmd>_proxied_server.go`.
4. Support `--json` for agent use. The `--json` wire surface is pinned by the
golden corpus in `protocol/` (`TestCorpusGolden`; regenerate with
`make corpus-regen` and review the diff — see `protocol/CATALOG.md`).
5. Add tests in the right tier.
6. Regenerate the CLI reference with `scripts/generate-cli-docs.sh`;
`scripts/check-cli-docs-drift.sh` fails a PR whose command-surface change
leaves the generated docs stale.
Use `bd update` with flags instead:
```bash
bd update <id> --description "new description"
bd update <id> --title "new title"
bd update <id> --design "design notes"
bd update <id> --append-notes "additional notes" # --notes replaces existing notes and requires --force once notes are set
bd update <id> --acceptance "acceptance criteria"
```
Prefer a flag on an existing command over a new command, and route
recovery/repair operations to `bd doctor --fix`; see the CLI design principles
in [engdocs/UI_PHILOSOPHY.md](../../engdocs/UI_PHILOSOPHY.md).
## Landing the Plane (Session Completion)
## Boundaries enforced by lint
**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
From `.golangci.yml` (read the rule comments there before changing scope):
**MANDATORY WORKFLOW:**
- **`cmd-bd-role-constructors` (depguard, all of `cmd/bd/**`):** "a command
reaches the reader role through store.IssueReader(), never through the
constructor: the accessor is where each storage decorator adds its layer".
The same applies to `store.Counter()`, `store.WorkspaceConfig()`,
`store.VersionReconciler()`, `store.StatsReporter()`,
`store.ReadyCounter()`, and `store.Querier()`.
- **`cmd-bd-domain-boundary` (depguard, `label.go` and `state.go`):** "bd label
and bd state reach storage through an issueops role accessor, never through
the domain use cases - see openIssueLifecycle in cmd/bd/label.go".
- **forbidigo `LabelUseCase$`:** "reach the label plane through
issueops.Lifecycle (Patch.Labels) and issueops.Reader, never the domain use
case".
- **forbidigo `types.IssueFilter` / `types.WorkFilter`:** "do not write a
filter here: take one back from a builder in internal/workapi, or pass the
whole request to issueops.Reader". `cmd/bd` denies these by default; the
files allowed to build their own filters are listed, with reasons, in
`.golangci.yml`.
- **forbidigo `fmt.Print*` / `os.Stdout` in list/graph code:** "route format
output through the command writer; mark an intentional non-format path
locally".
1. **File issues for remaining work** - Create issues for anything that needs follow-up
2. **Run quality gates** (if code changed) - Tests, linters, builds
3. **Update issue status** - Close finished work, update in-progress items
4. **PUSH TO REMOTE** - This is MANDATORY:
```bash
git pull --rebase
git push
git status # MUST show "up to date with origin"
```
5. **Clean up** - Clear stashes, prune remote branches
6. **Verify** - All changes committed AND pushed
7. **Hand off** - Provide context for next session
A deliberate exception is marked on its line with
`//nolint:forbidigo // <reason>`; the reason is expected (review checks it;
no linter enforces it).
**CRITICAL RULES:**
- Work is NOT complete until `git push` succeeds
- NEVER stop before pushing - that leaves work stranded locally
- NEVER say "ready to push when you are" - YOU must push
- If push fails, resolve and retry until it succeeds
## Guard tests
- `TestEveryStoreConstructionActivatesTheEventsJournal` — every store
construction site activates the events journal; new non-bead-writing sites
go in its exemption table with a reason.
- `TestProxyCapabilityRegistryCoversCommandTree` and the other
`TestProxyCapabilityRegistry*` tests — the registry stays complete and
consistent.
- `TestCobraParallelPolicyGuard` — a test that calls `t.Parallel()` must not
call the Cobra methods in `cobraParallelUnsafeMethods`; drop `t.Parallel()`
or serialize the call under `stdioMutex`.
- `TestCorpusGolden` (`protocol/`) — no unreviewed change to the `--json`
wire shapes.
Fresh-workspace command fixtures call `isolateBeadsDirForTest(t)` before
setup or dispatch and must not use `t.Parallel()`.

View file

@ -1556,6 +1556,13 @@ exports_files(
visibility = ["//test/docsync:__pkg__"],
)
# Contributor agent instructions; root AGENTS.md links them and
# //:docsync_files checks those links.
exports_files(
["AGENTS.md"],
visibility = ["//:__pkg__"],
)
# Release-metadata surfaces gated by //internal/versioncheck's releaseSources
# table: the canonical version and the Windows PE resource files. Aggregated
# into //:release_metadata_files, which is what the tests declare as data.

1
cmd/bd/CLAUDE.md Symbolic link
View file

@ -0,0 +1 @@
AGENTS.md

View file

@ -207,4 +207,4 @@ This page covers VS Code. For JetBrains IDEs, check whether your IDE supports MC
- [Copilot CLI](/integrations/copilot-cli) - Terminal-based Copilot integration
- [Quickstart](/getting-started/quickstart) - bd command basics
- [Installation](/getting-started/installation) - Full install guide
- [Agent Instructions](https://github.com/gastownhall/beads/blob/main/AGENT_INSTRUCTIONS.md) - Full agent workflow reference
- [IDE and Agent Setup](/getting-started/ide-setup) - Agent integration profiles and setup

View file

@ -46,6 +46,25 @@ Nothing specific — it's a metaphor for linked work items, like beads on a stri
Beads is a 1.x product used in production for AI-assisted development. The core functionality — create, update, dependencies, ready work, Dolt-backed sync — is stable, and releases follow semantic versioning. Data stays portable: `bd export` produces human-readable JSONL, and `bd backup` pushes Dolt-native backups. As with any tracker holding work you care about, keep normal backup hygiene (a Dolt remote or a `bd backup` destination).
### Does bd collect usage metrics?
`bd` collects anonymous command-usage metrics. Each event is a `cli_command`
record carrying only the command name; each batch also carries the bd version
and OS platform, keyed by a machine-derived, HMAC-protected distinct ID. No
email, repo path, remote URL, issue content, or user-supplied strings are
collected. Events are written under `~/.beads/eventsData` and POSTed to
`https://gastownhall-eventsapi.com/mp/collect`.
Metrics are enabled by default (opt-out). The friendliest way to see or change
them is `bd metrics` (`bd metrics on` / `bd metrics off` / `bd metrics example`),
which takes effect on the next command with no restart. `BD_DISABLE_METRICS=1`
still works as a one-off, shell-scoped override. The cross-tool
[`DO_NOT_TRACK`](https://donottrack.sh/) standard is honored as a disable-only
opt-out: `DO_NOT_TRACK=1` opts out, while a falsey or empty value
(`DO_NOT_TRACK=0`, `false`, or unset-but-present) falls through to your saved
`bd metrics` preference instead of forcing metrics back on. `BD_DISABLE_METRICS`
is the bidirectional override and takes precedence when both are set.
## Architecture
### Why Dolt instead of plain SQLite or flat files?

45
engdocs/AGENTS.md Normal file
View file

@ -0,0 +1,45 @@
# engdocs/ — contributor notes
`engdocs/` holds contributor and internals documentation. It is read on
GitHub, not published: local links must be exact relative file paths, and
`TestEngdocsAndRootMarkdownLinks` in `test/docsync` fails on any that do not
resolve. User-facing documentation lives in `docs/` (the Mintlify site) and
follows the `beads-docs` skill.
## What lives where
| Path | Contents |
|---|---|
| `PROJECT_CHARTER.md` | Product boundary: what belongs in core, an integration, or the orchestration layer. |
| `TESTING.md`, `LINTING.md` | Canonical test and lint policy. |
| `ERROR_HANDLING.md`, `UI_PHILOSOPHY.md` | Conventions for errors and CLI output. |
| `ADDING_AN_ISSUEOPS_ROLE.md` | How to add a storage operation end to end. |
| `EXTENDING.md`, `INTEGRATION_CHARTER.md` | Extension and integration boundaries. |
| `AGENT_SIGNING.md` | Signatures for agent-prepared commits, comments, and reviews. |
| `design/` | Design documents for subsystems (Dolt concurrency, `bd serve`, ownership hand-off, …). |
| `adr/` | Architecture decision records, `<NNNN>-<slug>.md`, each with a `## Status` section. Accepted ADRs are superseded by a new ADR, not rewritten. |
| `decisions/` | Dated decision records for the docs tooling. |
| `staged-for-removal/` | Docs that no longer meet the active-doc bar (see `staged-for-removal/MANIFEST.md`). Do not link to or update them. |
## Code orientation
- `cmd/bd/` — the CLI (see [cmd/bd/AGENTS.md](../cmd/bd/AGENTS.md)).
- `internal/workapi/` — the work-query contract shared by every bd frontend:
filter construction, defaults, validation, response shaping.
- `internal/httpapi/` — the `bd serve` HTTP surface
([SERVE_RUNBOOK.md](SERVE_RUNBOOK.md)).
- `internal/storage/` — shared storage interface and value types, plus
`HookFiringStore` and its `hook_*.go` decorators, which fire
on_create/on_update/on_close hooks after successful mutations.
- `internal/storage/issueops/` — transaction-scoped SQL operations shared by
the server-mode (`internal/storage/dolt/`) and embedded
(`internal/storage/embeddeddolt/`) stores.
- `internal/storage/schema/` — schema and migrations
([migrations/README.md](../internal/storage/schema/migrations/README.md)).
- `internal/doltserver/` — lifecycle of a local `dolt sql-server` process.
- `beads.go`, `backend/`, `issueops/`, `journalops/`, `memoryops/`,
`format/`, `beadserrors/` — the public Go API for extending bd and for
out-of-tree storage backends.
Each package's doc comment (`go doc ./internal/<pkg>`) is the authoritative
description; prefer it over prose here when they disagree, and fix this file.

View file

@ -1,93 +0,0 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
**beads** (command: `bd`) is a Dolt-powered issue tracker for AI-supervised coding workflows. Git integration is optional — see `BEADS_DIR` + `--stealth` for git-free operation. We dogfood our own tool.
**IMPORTANT**: See [AGENTS.md](../AGENTS.md) for complete workflow instructions, bd commands, and development guidelines.
## Architecture Overview
### Three-Layer Design
1. **Storage Layer** (`internal/storage/`)
- **Dolt** in `storage/dolt/` — version-controlled SQL database with cell-level merge
- Common types and interfaces in `storage.go`
2. **Database Runtime Layer**
- Embedded mode runs Dolt in-process through `internal/storage/embeddeddolt/`
- Server mode uses `internal/doltserver/` and `internal/storage/db/`
- Proxy and pidfile helpers live under `internal/storage/db/`
- Storage-facing server adapters live under `internal/storage/doltserver/`
3. **CLI Layer** (`cmd/bd/`)
- Cobra-based commands (one file per command: `create.go`, `list.go`, etc.)
- Direct database access (embedded mode for standalone, server mode for orchestrator)
- All commands support `--json` for programmatic use
- Main entry point in `main.go`
### Storage Architecture
Beads uses **Dolt** as its storage backend — a version-controlled SQL database:
```
Dolt DB (.beads/dolt/)
↕ Dolt commits (automatic per write)
↕ Dolt push/pull (native sync)
Remote (Dolt remotes: DoltHub, S3, GCS, etc.)
```
- **Write path**: CLI → Dolt → auto-commit to Dolt history
- **Read path**: Direct SQL queries against Dolt
- **Sync**: Dolt handles versioning and sync natively via `bd dolt push` / `bd dolt pull`
- **Hash-based IDs**: Automatic collision prevention (v0.20+)
Core implementation:
- Dolt storage: `internal/storage/dolt/`
- Embedded runtime: `internal/storage/embeddeddolt/`
- Server runtime: `internal/doltserver/`, `internal/storage/db/`, and `internal/storage/doltserver/`
- Sync commands: `cmd/bd/dolt_*.go`, `cmd/bd/sync_*.go`
### Key Data Types
See `internal/types/types.go`:
- `Issue`: Core work item (title, description, status, priority, etc.)
- `Dependency`: Four types (blocks, related, parent-child, discovered-from)
- `Label`: Flexible tagging system
- `Comment`: Threaded discussions
- `Event`: Full audit trail
## Development Command Source
Use the canonical [TESTING.md](TESTING.md) for test commands, test design, and
PR-readiness gates. This file should not duplicate command matrices or
version-management workflows.
> **Do NOT** use `go build -o bd` or `go install` directly — they create
> stale binaries that shadow `~/.local/bin/bd`. Always use `make install`.
## Testing
Testing guidance lives in [TESTING.md](TESTING.md). Architecture-specific notes
for Claude are limited to where tests touch agent setup, hooks, or
instruction-file generation.
## Important Notes
- **Always read AGENTS.md first** - it has the complete workflow
- Check for duplicates proactively: `bd duplicates --auto-merge`
- Use `--json` flags for all programmatic use
## Key Files
- **AGENTS.md** - Complete workflow and development guide (READ THIS!)
- **README.md** - User-facing documentation
- **ADVANCED.md** - Advanced features (rename, merge, compaction)
- **docs/core-concepts/labels.md** - Complete label system guide
- **docs/reference/configuration.md** - Configuration system
## When Adding Features
See AGENTS.md "Adding a New Command" and "Adding Storage Features" sections for step-by-step guidance.

1
engdocs/CLAUDE.md Symbolic link
View file

@ -0,0 +1 @@
AGENTS.md

View file

@ -63,7 +63,7 @@ Follow-up automation should replace marker-only checks with generated or
| `BDP_GRAPH_ARCHITECTURE.md` | Keep | Graph-plane design record; ruled contracts and dated dependency sources, not runtime or merge clearance. |
| `BDP_GRAPH_CLI_AND_STORAGE_SPEC.md` | Keep | Graph-plane design record; ruled contracts and dated dependency sources, not runtime or merge clearance. |
| `CLAUDE_INTEGRATION.md` | Keep | Design/user guide for Claude setup; paired with `SETUP.md`. |
| `CLAUDE.md` | Revise | Kept as architecture orientation only; command/workflow duplication was reduced in favour of root `AGENTS.md` and `AGENT_INSTRUCTIONS.md`. |
| `AGENTS.md` (`CLAUDE.md` is a symlink to it) | Keep | Contributor orientation for `engdocs/`: verified pointers only; workflow rules live in the root `AGENTS.md`. |
| `CLI_REFERENCE.md` | Keep/generated | Generated command reference from live help output. |
| `CI_CLEANUP_PLAN.md` | Keep as maintainer context | Dated CI policy, measurements, and implementation roadmap; current commands live in workflows and the `Makefile`. |
| `CI_REQUIRED_CHECK_TOPOLOGY.md` | Keep as maintainer context | Implemented workflow design record for aggregate-gate policy; branch-protection and ruleset adoption remain pending. Live job membership and display names come from `.github/workflows/*.yml` and their structural tests; copied wiring and rollout steps are historical snapshots. |

View file

@ -195,6 +195,12 @@ rm -rf -- "$beads_manual_dir"
itself redirect `bd init` workspace setup. Never run a manual `bd init` from a
production workspace merely because `BEADS_DB` points elsewhere.
**Tmpfs hosts:** the `cmd/bd` test suite creates an isolated `$HOME` and several
test binaries under `$TMPDIR`. They are normally cleaned by the test process,
but a SIGKILLed or OOMed run can leave orphans behind. On hosts where `/tmp`
is tmpfs (e.g. Fedora Atomic / Bluefin), run `make clean-test-tmp` between
test runs if `du -sh /tmp/beads-* /tmp/bd-*` shows accumulation. See bd-3q2u.
`testing.Short()` is for genuine runtime, stress, or large-fixture skips. It
is not a substitute for declaring an integration, end-to-end, API, Docker, or
external-dependency boundary. Keep new uses within the repository policy:

View file

@ -106,6 +106,113 @@ Following Tufte's principle of layered information:
5. **Descriptions** - Plain, primary content
6. **Examples** - Plain, copy-paste friendly
## Visual Design System
When adding CLI output features, follow these design principles for consistent,
cognitively friendly visuals.
### No Emoji-Style Icons
Do not use large colored emoji icons like red/orange/yellow/blue/white circles
for priorities or status. They cause cognitive overload and break visual
consistency.
Use small Unicode symbols with semantic colors applied via lipgloss:
- Status: `○ ◐ ● ✓ ❄`
- Priority: `P0`–`P4` label with color (no status glyph)
### Status Icons
Use these symbols consistently across all commands:
```text
○ open - Available to work (white/default)
◐ in_progress - Currently being worked (yellow)
● blocked - Waiting on dependencies (red)
✓ closed - Completed (muted gray)
❄ deferred - Scheduled for later (blue/muted)
```
### Priority Labels and Colors
Format priority as the P-label with color only (no status glyph — `●` is blocked status):
- `P0`: Red + bold (critical)
- `P1`: Orange (high)
- `P2`: Amber (elevated)
- `P3`–`P4`: Default text
### Issue Type Colors
- `bug`: Red (problems need attention)
- `epic`: Purple (larger scope)
- Others: Default text
### Design Principles
1. Small Unicode symbols only; avoid emoji blobs.
2. Semantic colors only for actionable items; do not color everything.
3. Closed items fade using muted gray.
4. Prefer icons over text labels for scanability.
5. Keep icons consistent across list, graph, show, and related commands.
6. Use tree connectors (`├──`, `└──`, `│`) for hierarchies.
7. Reduce cognitive noise; do not show `needs:1` when it is just the parent epic.
### Semantic Styles
Use exported styles from `internal/ui/styles.go`:
```go
// Status styles
ui.StatusInProgressStyle // Yellow - active work
ui.StatusBlockedStyle // Red - needs attention
ui.StatusClosedStyle // Muted gray - done
// Priority styles
ui.PriorityP0Style // Red + bold
ui.PriorityP1Style // Orange
// Type styles
ui.TypeBugStyle // Red
ui.TypeEpicStyle // Purple
// General styles
ui.PassStyle, ui.WarnStyle, ui.FailStyle
ui.MutedStyle, ui.AccentStyle
ui.RenderMuted(text), ui.RenderAccent(text)
```
Example:
```go
switch issue.Status {
case types.StatusOpen:
icon = "○"
case types.StatusInProgress:
icon = ui.StatusInProgressStyle.Render("◐")
case types.StatusBlocked:
icon = ui.StatusBlockedStyle.Render("●")
case types.StatusClosed:
icon = ui.StatusClosedStyle.Render("✓")
}
```
## CLI Design Principles
**Minimize cognitive overload.** Every new command, flag, or option adds cognitive burden for users. Before adding anything:
1. **Recovery/fix operations → `bd doctor --fix`**: Don't create separate commands like `bd recover` or `bd repair`. Doctor already detects problems - let `--fix` handle remediation. This keeps all health-related operations in one discoverable place.
For git hook marker migration specifically: use `bd migrate hooks --dry-run` to preview operations, and `bd doctor --fix` for the standard apply path.
2. **Prefer flags on existing commands**: Before creating a new command, ask: "Can this be a flag on an existing command?" Example: `bd list --stale` instead of `bd stale`.
3. **Consolidate related operations**: Related operations should live together. Version control uses `bd vc {log,diff,commit}`, not separate top-level commands.
4. **Count the commands**: Run `bd --help` and count. If we're approaching 30+ commands, we have a discoverability problem. Consider subcommand grouping.
5. **New commands need strong justification**: A new command should represent a fundamentally different operation, not just a convenience wrapper.
## References
- Tufte, E. (2001). *The Visual Display of Quantitative Information*

View file

@ -179,6 +179,12 @@ filegroup(
visibility = ["//internal/storage:__subpackages__"],
)
# Linked from the root and engdocs AGENTS.md; //:docsync_files checks those links.
exports_files(
["migrations/README.md"],
visibility = ["//:__pkg__"],
)
# --- begin go_srcs (managed by tools/bazel/go_srcs.py; run `make bazel-sync`) ---
filegroup(

View file

@ -67,7 +67,7 @@ echo "=== Check 1: Removed commands ==="
SYNC_REFS=$(grep -rn 'bd sync\b' \
"$PROJECT_ROOT"/docs/*.md \
"$PROJECT_ROOT"/docs/*/*.md \
"$PROJECT_ROOT"/AGENT_INSTRUCTIONS.md \
"$PROJECT_ROOT"/cmd/bd/AGENTS.md \
"$PROJECT_ROOT"/AGENTS.md \
"$PROJECT_ROOT"/README.md \
"$PROJECT_ROOT"/npm-package/*.md \
@ -108,7 +108,7 @@ fi
BRANCH_REFS=$(grep -rn 'bd init.*--branch' \
"$PROJECT_ROOT"/docs/*.md \
"$PROJECT_ROOT"/docs/*/*.md \
"$PROJECT_ROOT"/AGENT_INSTRUCTIONS.md \
"$PROJECT_ROOT"/cmd/bd/AGENTS.md \
"$PROJECT_ROOT"/AGENTS.md \
"$PROJECT_ROOT"/README.md \
2>/dev/null \
@ -135,7 +135,7 @@ echo "=== Check 3: Legacy storage references ==="
SQLITE_REFS=$(grep -rn 'beads\.db\|default\.db\|sqlite3.*\.beads\|\.beads/.*\.db' \
"$PROJECT_ROOT"/docs/*.md \
"$PROJECT_ROOT"/docs/*/*.md \
"$PROJECT_ROOT"/AGENT_INSTRUCTIONS.md \
"$PROJECT_ROOT"/cmd/bd/AGENTS.md \
"$PROJECT_ROOT"/AGENTS.md \
"$PROJECT_ROOT"/README.md \
2>/dev/null \

View file

@ -3,6 +3,7 @@ load("@rules_go//go:def.bzl", "go_test")
go_test(
name = "docsync_test",
srcs = [
"agentfiles_test.go",
"docsync_test.go",
"doltpin_test.go",
"init_safety_recovery_test.go",

View file

@ -0,0 +1,214 @@
package docsync
import (
"bytes"
"io/fs"
"os"
"path/filepath"
"regexp"
"sort"
"strings"
"testing"
"github.com/steveyegge/beads/internal/testutil/bazeltest"
)
// rootAgentsMaxBytes caps the root AGENTS.md. Agent tools load it into every
// session, Codex stops reading project instructions at 32 KiB combined, and
// area-specific rules belong in nested AGENTS.md files instead.
const rootAgentsMaxBytes = 20000
// agentFileSkipDirs are repo-relative directories whose AGENTS.md/CLAUDE.md
// files are shipped to users (product assets), not contributor instructions.
var agentFileSkipDirs = map[string]bool{
"plugins": true,
"internal/templates": true,
}
// backtickPathRE matches a backticked token that names a repository file.
var backtickPathRE = regexp.MustCompile("`([A-Za-z0-9_./-]+\\.(?:md|go|sh|yml|yaml|json|txt))`")
// backtickRepoPathRE matches a backticked repo-relative path under a top-level
// source or docs directory, with or without an extension (directories and
// extensionless scripts included). Globs and placeholders are skipped by the
// caller.
var backtickRepoPathRE = regexp.MustCompile("`((?:\\.github|backend|cmd|docs|engdocs|internal|issueops|scripts|test|tests)/[^`\\s]*)`")
// backtickTestRE matches a backticked Go test name cited as a guard.
var backtickTestRE = regexp.MustCompile("`(Test[A-Z][A-Za-z0-9_]*)`")
var goTestFuncRE = regexp.MustCompile(`(?m)^func (Test[A-Za-z0-9_]+)\(`)
func TestRootAgentsFileWithinBudget(t *testing.T) {
info, err := os.Stat(filepath.Join(repoRoot(), "AGENTS.md"))
if err != nil {
t.Fatalf("stat AGENTS.md: %v", err)
}
if info.Size() > rootAgentsMaxBytes {
t.Errorf("AGENTS.md is %d bytes; keep it at or under %d and move area-specific rules into a nested AGENTS.md listed in its routing table",
info.Size(), rootAgentsMaxBytes)
}
}
// contributorAgentFiles walks the checkout for AGENTS.md files outside the
// shipped product-asset directories, returning repo-relative paths.
func contributorAgentFiles(t *testing.T, root string) []string {
t.Helper()
var files []string
err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
if err != nil {
return err
}
rel, _ := filepath.Rel(root, path)
rel = filepath.ToSlash(rel)
if d.IsDir() {
if path != root && (strings.HasPrefix(d.Name(), ".") || d.Name() == "node_modules" || d.Name() == "testdata" || agentFileSkipDirs[rel]) {
return filepath.SkipDir
}
return nil
}
if d.Name() == "AGENTS.md" {
files = append(files, rel)
}
return nil
})
if err != nil {
t.Fatalf("walking checkout: %v", err)
}
sort.Strings(files)
return files
}
// TestAgentInstructionFilesAreLinkedAndRouted: every contributor AGENTS.md has
// a sibling CLAUDE.md symlink (Claude Code skips AGENTS.md files when a
// CLAUDE.md exists above them), every nested one is listed in the root routing
// table, and every local link, backticked repo path, and backticked guard-test
// name in them resolves. Make targets are not checked.
func TestAgentInstructionFilesAreLinkedAndRouted(t *testing.T) {
if bazeltest.IsBazel() {
t.Skip("walks the source checkout; Bazel runfiles hold only declared data, so this runs under go test")
}
root := repoRoot()
agentFiles := contributorAgentFiles(t, root)
if len(agentFiles) < 2 {
t.Fatalf("found %d contributor AGENTS.md files; the walk or the skip list is wrong", len(agentFiles))
}
rootAgents, err := os.ReadFile(filepath.Join(root, "AGENTS.md"))
if err != nil {
t.Fatalf("reading AGENTS.md: %v", err)
}
for _, rel := range agentFiles {
agentsPath := filepath.Join(root, filepath.FromSlash(rel))
claudePath := filepath.Join(filepath.Dir(agentsPath), "CLAUDE.md")
claudeRel := filepath.ToSlash(filepath.Join(filepath.Dir(rel), "CLAUDE.md"))
info, err := os.Lstat(claudePath)
switch {
case err != nil:
t.Errorf("%s has no sibling CLAUDE.md; add one with `ln -s AGENTS.md CLAUDE.md`", rel)
case info.Mode()&os.ModeSymlink == 0:
t.Errorf("%s is a regular file; replace it with a symlink to AGENTS.md", claudeRel)
default:
agents, aerr := os.ReadFile(agentsPath)
claude, cerr := os.ReadFile(claudePath)
if aerr != nil || cerr != nil || !bytes.Equal(agents, claude) {
t.Errorf("%s does not resolve to its sibling AGENTS.md", claudeRel)
}
}
if rel != "AGENTS.md" && !bytes.Contains(rootAgents, []byte("("+rel+")")) {
t.Errorf("%s is not linked from the routing table in the root AGENTS.md", rel)
}
}
checked := append(agentFiles, filepath.ToSlash(filepath.Join(".github", "copilot-instructions.md")))
tests := goTestFuncNames(t, root)
var broken []string
for _, rel := range checked {
path := filepath.Join(root, filepath.FromSlash(rel))
data, err := os.ReadFile(path)
if err != nil {
t.Fatalf("reading %s: %v", rel, err)
}
content := stripCodeFences(string(data))
for _, target := range extractMarkdownLinks(content) {
if isExternalLink(target) {
continue
}
if idx := strings.IndexAny(target, "#?"); idx >= 0 {
target = target[:idx]
}
if target == "" {
continue
}
if _, err := os.Stat(filepath.Join(filepath.Dir(path), filepath.FromSlash(target))); err != nil {
broken = append(broken, rel+" -> "+target)
}
}
for _, m := range backtickPathRE.FindAllStringSubmatch(content, -1) {
ref := filepath.FromSlash(m[1])
if _, err := os.Stat(filepath.Join(filepath.Dir(path), ref)); err == nil {
continue
}
if _, err := os.Stat(filepath.Join(root, ref)); err == nil {
continue
}
broken = append(broken, rel+" -> `"+m[1]+"`")
}
for _, m := range backtickRepoPathRE.FindAllStringSubmatch(content, -1) {
ref := m[1]
if strings.ContainsAny(ref, "*{}<>$") {
continue
}
// "file.go:Symbol" cites a symbol inside a file; check the file.
ref, _, _ = strings.Cut(ref, ":")
if _, err := os.Stat(filepath.Join(root, filepath.FromSlash(ref))); err != nil {
broken = append(broken, rel+" -> `"+m[1]+"`")
}
}
for _, m := range backtickTestRE.FindAllStringSubmatch(content, -1) {
if !tests[m[1]] {
broken = append(broken, rel+" -> guard test "+m[1]+" does not exist")
}
}
}
if len(broken) > 0 {
sort.Strings(broken)
t.Errorf("agent instruction files reference paths that do not exist (%d):", len(broken))
for _, b := range broken {
t.Errorf(" %s", b)
}
}
}
// goTestFuncNames returns the names of every top-level Test function in the
// checkout's Go test files.
func goTestFuncNames(t *testing.T, root string) map[string]bool {
t.Helper()
names := make(map[string]bool)
err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
if err != nil {
return err
}
if d.IsDir() {
if path != root && (strings.HasPrefix(d.Name(), ".") || d.Name() == "node_modules") {
return filepath.SkipDir
}
return nil
}
if !strings.HasSuffix(path, "_test.go") {
return nil
}
data, err := os.ReadFile(path)
if err != nil {
return err
}
for _, m := range goTestFuncRE.FindAllSubmatch(data, -1) {
names[string(m[1])] = true
}
return nil
})
if err != nil {
t.Fatalf("collecting Go test names: %v", err)
}
return names
}

View file

@ -57,6 +57,7 @@ var rootDocFiles = []string{
"CLAUDE.md",
"RELEASING.md",
"PR_MAINTAINER_GUIDELINES.md",
"ROADMAP.md",
}
func collectMintPages(v any, out *[]string) {

View file

@ -30,6 +30,7 @@ scripts TestBazelNoRemoteEndpointsInTrackedFiles skip # scans git-tracked files
scripts TestBazelTestTagsFollowTaxonomy skip # reads every BUILD file in the checkout; runs under go test
scripts TestBazelTreeGoSrcsListsEveryPackage skip # walks the source checkout; runs under go test
scripts TestCheckTestingShortPassesOnCleanRepoTree skip # walks the whole checkout; runs under go test
test/docsync TestAgentInstructionFilesAreLinkedAndRouted skip # walks the source checkout for every AGENTS.md; runs under go test
scripts TestReleaseFormula* skip # .beads/ is in .bazelignore, so the formula cannot be data; runs under go test
# Policy tests whose inputs (other packages' BUILD files, .github/scripts,