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:
parent
ec72c8c563
commit
0773e6334e
32 changed files with 1080 additions and 1269 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
94
.github/ISSUE_TEMPLATE/bug_report.yml
vendored
Normal 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
11
.github/ISSUE_TEMPLATE/config.yml
vendored
Normal 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.
|
||||
108
.github/ISSUE_TEMPLATE/feature_request.yml
vendored
Normal file
108
.github/ISSUE_TEMPLATE/feature_request.yml
vendored
Normal 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
|
||||
23
.github/PULL_REQUEST_TEMPLATE.md
vendored
23
.github/PULL_REQUEST_TEMPLATE.md
vendored
|
|
@ -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.
|
||||
|
|
|
|||
147
.github/copilot-instructions.md
vendored
147
.github/copilot-instructions.md
vendored
|
|
@ -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.
|
||||
|
|
|
|||
4
.github/workflows/docs-mintlify.yml
vendored
4
.github/workflows/docs-mintlify.yml
vendored
|
|
@ -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
409
AGENTS.md
|
|
@ -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) |
|
||||
|
|
|
|||
|
|
@ -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/).
|
||||
|
|
|
|||
|
|
@ -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__"],
|
||||
|
|
|
|||
23
CLAUDE.md
23
CLAUDE.md
|
|
@ -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
1
CLAUDE.md
Symbolic link
|
|
@ -0,0 +1 @@
|
|||
AGENTS.md
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
* [](https://deepwiki.com/gastownhall/beads)
|
||||
|
|
|
|||
69
ROADMAP.md
Normal file
69
ROADMAP.md
Normal 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)
|
||||
122
cmd/bd/AGENTS.md
122
cmd/bd/AGENTS.md
|
|
@ -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()`.
|
||||
|
|
|
|||
|
|
@ -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
1
cmd/bd/CLAUDE.md
Symbolic link
|
|
@ -0,0 +1 @@
|
|||
AGENTS.md
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
45
engdocs/AGENTS.md
Normal 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.
|
||||
|
|
@ -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
1
engdocs/CLAUDE.md
Symbolic link
|
|
@ -0,0 +1 @@
|
|||
AGENTS.md
|
||||
|
|
@ -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. |
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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*
|
||||
|
|
|
|||
|
|
@ -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(
|
||||
|
|
|
|||
|
|
@ -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 \
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
|
|
|
|||
214
test/docsync/agentfiles_test.go
Normal file
214
test/docsync/agentfiles_test.go
Normal 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
|
||||
}
|
||||
|
|
@ -57,6 +57,7 @@ var rootDocFiles = []string{
|
|||
"CLAUDE.md",
|
||||
"RELEASING.md",
|
||||
"PR_MAINTAINER_GUIDELINES.md",
|
||||
"ROADMAP.md",
|
||||
}
|
||||
|
||||
func collectMintPages(v any, out *[]string) {
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue