diff --git a/AGENTS.md b/AGENTS.md index a029b9a58..83fad5d3e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,9 @@ # Instructions for AI Agents Working on Beads +> **📖 For detailed development instructions**, see [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) +> +> This file provides a quick overview and reference. For in-depth operational details (development, testing, releases, git workflow), consult the detailed instructions. + ## Project Overview This is **beads** (command: `bd`), an issue tracker designed for AI-supervised coding workflows. We dogfood our own tool! @@ -381,215 +385,17 @@ bd show bd-41 --json # Verify merged content ## Development Guidelines -### Code Standards +> **📋 For complete development instructions**, see [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) + +**Quick reference:** - **Go version**: 1.21+ -- **Linting**: `golangci-lint run ./...` (baseline warnings documented in [docs/LINTING.md](docs/LINTING.md)) -- **Testing**: All new features need tests (`go test -short ./...` for local, full tests run in CI) -- **Documentation**: Update relevant .md files +- **Testing**: Use `BEADS_DB=/tmp/test.db` to avoid polluting production database +- **Before committing**: Run tests (`go test -short ./...`) and linter (`golangci-lint run ./...`) +- **End of session**: Always run `bd sync` to flush/commit/push changes +- **Git hooks**: Run `bd hooks install` to ensure DB ↔ JSONL consistency -### File Organization - -``` -beads/ -├── cmd/bd/ # CLI commands -├── internal/ -│ ├── types/ # Core data types -│ └── storage/ # Storage layer -│ └── sqlite/ # SQLite implementation -├── examples/ # Integration examples -└── *.md # Documentation -``` - -### Testing Workflow - -**IMPORTANT:** Never pollute the production database with test issues! - -**For manual testing**, use the `BEADS_DB` environment variable to point to a temporary database: - -```bash -# Create test issues in isolated database -BEADS_DB=/tmp/test.db ./bd init --quiet --prefix test -BEADS_DB=/tmp/test.db ./bd create "Test issue" -p 1 - -# Or for quick testing -BEADS_DB=/tmp/test.db ./bd create "Test feature" -p 1 -``` - -**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 -} -``` - -**Warning:** bd will warn you when creating issues with "Test" prefix in the production database. Always use `BEADS_DB` for manual testing. - -### Before Committing - -1. **Run tests**: `go test -short ./...` (full tests run in CI) -2. **Run linter**: `golangci-lint run ./...` (ignore baseline warnings) -3. **Update docs**: If you changed behavior, update README.md or other docs -4. **Commit**: Issues auto-sync to `.beads/issues.jsonl` and import after pull - -### Git Workflow - -**Auto-sync provides batching!** bd automatically: - -- **Exports** to JSONL after CRUD operations (30-second debounce for batching) -- **Imports** from JSONL when it's newer than DB (e.g., after `git pull`) -- **Daemon commits/pushes** every 5 seconds (if `--auto-commit` / `--auto-push` enabled) - -The 30-second debounce provides a **transaction window** for batch operations - multiple issue changes within 30 seconds get flushed together, avoiding commit spam. - -### Git Integration - -**Auto-sync**: bd automatically exports to JSONL (30s debounce), imports after `git pull`, and optionally commits/pushes. - -**Protected branches**: Use `bd init --branch beads-metadata` to commit to separate branch. See [docs/PROTECTED_BRANCHES.md](docs/PROTECTED_BRANCHES.md). - -**Git worktrees**: Daemon mode NOT supported. Use `bd --no-daemon` for all commands. See [docs/GIT_INTEGRATION.md](docs/GIT_INTEGRATION.md). - -**Merge conflicts**: Rare with hash IDs. If conflicts occur, use `git checkout --theirs/.beads/beads.jsonl` and `bd import`. See [docs/GIT_INTEGRATION.md](docs/GIT_INTEGRATION.md). - -### Landing the Plane - -**When the user says "let's land the plane"**, follow this clean session-ending protocol: - -1. **File beads issues for any remaining work** that needs follow-up -2. **Ensure all quality gates pass** (only if code changes were made) - run tests, linters, builds (file P0 issues if broken) -3. **Update beads issues** - close finished work, update status -4. **Sync and PUSH everything to remote** - Work methodically to ensure both local and remote are synchronized: - ```bash - # Pull first to catch any remote changes - git pull --rebase - - # If conflicts in .beads/beads.jsonl, resolve thoughtfully: - # - git checkout --theirs .beads/beads.jsonl (accept remote) - # - bd import -i .beads/beads.jsonl (re-import) - # - Or manual merge, then import - - # Sync the database (exports to JSONL, commits) - bd sync - - # CRITICAL: Push everything to remote - git push - - # Verify push succeeded - git status # Should show "up to date with origin/main" - ``` - **CRITICAL**: The plane has NOT landed until `git push` completes successfully. If you don't push, the work is still on the runway! -5. **Clean up git state** - Clear old stashes and prune dead remote branches: - ```bash - git stash clear # Remove old stashes - git remote prune origin # Clean up deleted remote branches - ``` -6. **Verify clean state** - Ensure all changes are committed AND PUSHED, no untracked files remain -7. **Choose a follow-up issue for next session** - - Provide a prompt for the user to give to you in the next session - - Format: "Continue work on bd-X: [issue title]. [Brief context about what's been done and what's next]" - -**Example "land the plane" session:** - -```bash -# 1. File remaining work -bd create "Add integration tests for sync" -t task -p 2 --json - -# 2. Run quality gates (only if code changes were made) -go test -short ./... -golangci-lint run ./... - -# 3. Close finished issues -bd close bd-42 bd-43 --reason "Completed" --json - -# 4. Sync and PUSH everything -git pull --rebase -# If conflicts in .beads/beads.jsonl, resolve thoughtfully: -# - git checkout --theirs .beads/beads.jsonl (accept remote) -# - bd import -i .beads/beads.jsonl (re-import) -# - Or manual merge, then import -bd sync # Export/import/commit -git push # CRITICAL - Must push! -git status # Verify "up to date with origin/main" - -# 5. Clean up git state -git stash clear -git remote prune origin - -# 6. Verify everything is clean and pushed -git status - -# 7. Choose next work -bd ready --json -bd show bd-44 --json -``` - -**Then provide the user with:** - -- Summary of what was completed this session -- What issues were filed for follow-up -- Status of quality gates (all passing / issues filed) -- Recommended prompt for next session - -### Agent Session Workflow - -**IMPORTANT for AI agents:** When you finish making issue changes, always run: - -```bash -bd sync -``` - -This immediately: - -1. Exports pending changes to JSONL (no 30s wait) -2. Commits to git -3. Pulls from remote -4. Imports any updates -5. Pushes to remote - -**Example agent session:** - -```bash -# Make multiple changes (batched in 30-second window) -bd create "Fix bug" -p 1 -bd create "Add tests" -p 1 -bd update bd-42 --status in_progress -bd close bd-40 --reason "Completed" - -# Force immediate sync at end of session -bd sync - -# Now safe to end session - everything is committed and pushed -``` - -**Why this matters:** - -- Without `bd sync`, changes sit in 30-second debounce window -- User might think you pushed but JSONL is still dirty -- `bd sync` forces immediate flush/commit/push - -**STRONGLY RECOMMENDED: Install git hooks for automatic sync** (prevents stale JSONL problems): - -```bash -# One-time setup - run this in each beads workspace -bd hooks install -``` - -This installs: - -- **pre-commit** - Flushes pending changes immediately before commit (bypasses 30s debounce) -- **post-merge** - Imports updated JSONL after pull/merge (guaranteed sync) -- **pre-push** - Exports database to JSONL before push (prevents stale JSONL from reaching remote) -- **post-checkout** - Imports JSONL after branch checkout (ensures consistency) - -**Why git hooks matter:** -Without the pre-push hook, you can have database changes committed locally but stale JSONL pushed to remote, causing multi-workspace divergence. The hooks guarantee DB ↔ JSONL consistency. - -**Note:** Hooks are embedded in the bd binary and work for all bd users (not just source repo users). +See [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for detailed workflows, testing patterns, and operational procedures. @@ -615,48 +421,16 @@ bd dep tree bd-8 # Show 1.0 epic dependencies -## Common Tasks +## Common Development Tasks -### Adding a New Command +See [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for detailed instructions on: -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. Update schema in `internal/storage/sqlite/schema.go` -2. Add migration if needed -3. Update `internal/types/types.go` if new types -4. Implement in `internal/storage/sqlite/sqlite.go` -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 - -## Questions? - -- Check existing issues: `bd list` -- Look at recent commits: `git log --oneline -20` -- Read the docs: README.md, ADVANCED.md, EXTENDING.md -- Create an issue if unsure: `bd create "Question: ..." -t task -p 2` - -## Important Files - -- **README.md** - Main documentation (keep this updated!) -- **EXTENDING.md** - Database extension guide -- **ADVANCED.md** - JSONL format analysis -- **CONTRIBUTING.md** - Contribution guidelines -- **SECURITY.md** - Security policy +- Adding new commands +- Adding storage features +- Adding examples +- Building and testing +- Version management +- Release process ## Pro Tips for Agents @@ -674,125 +448,15 @@ bd dep tree bd-8 # Show 1.0 epic dependencies ### 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. +Use `gh` CLI tools for checking issues/PRs (see [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for details). -**Preferred approach:** +## Building, Testing, Versioning, and Releases -```bash -# List open issues with details -gh issue list --limit 30 +See [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for complete details on: -# 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. - -## Building and Testing - -```bash -# Build -go build -o bd ./cmd/bd - -# Test (short - for local development) -go test -short ./... - -# Test with coverage (full tests - for CI) -go test -coverprofile=coverage.out ./... -go tool cover -html=coverage.out - -# Run locally -./bd init --prefix test -./bd create "Test issue" -p 1 -./bd ready -``` - -## 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 --commit` -2. Push to GitHub -3. Confirm all versions updated correctly - -**Files updated automatically:** - -- `cmd/bd/version.go` - CLI version -- `.claude-plugin/plugin.json` - Plugin version -- `.claude-plugin/marketplace.json` - 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) - -**Automated (Recommended):** - -```bash -# One command to do everything (version bump, tests, tag, Homebrew update, local install) -./scripts/release.sh 0.9.3 -``` - -This handles the entire release workflow automatically, including waiting ~5 minutes for GitHub Actions to build release artifacts. See [scripts/README.md](scripts/README.md) for details. - -**Manual (Step-by-Step):** - -1. Bump version: `./scripts/bump-version.sh --commit` -2. Update CHANGELOG.md with release notes -3. Run tests: `go test -short ./...` (CI runs full suite) -4. Push version bump: `git push origin main` -5. Tag release: `git tag v && git push origin v` -6. Update Homebrew: `./scripts/update-homebrew.sh ` (waits for GitHub Actions) -7. Verify: `brew update && brew upgrade bd && bd version` - -See [docs/RELEASING.md](docs/RELEASING.md) for complete manual instructions. +- Building and testing (`go build`, `go test`) +- Version management (`./scripts/bump-version.sh`) +- Release process (`./scripts/release.sh`) --- diff --git a/AGENT_INSTRUCTIONS.md b/AGENT_INSTRUCTIONS.md new file mode 100644 index 000000000..876a3171d --- /dev/null +++ b/AGENT_INSTRUCTIONS.md @@ -0,0 +1,382 @@ +# Detailed Agent Instructions for Beads Development + +**For project overview and quick start, see [AGENTS.md](AGENTS.md)** + +This document contains detailed operational instructions for AI agents working on beads development, testing, and releases. + +## Development Guidelines + +### Code Standards + +- **Go version**: 1.21+ +- **Linting**: `golangci-lint run ./...` (baseline warnings documented in [docs/LINTING.md](docs/LINTING.md)) +- **Testing**: All new features need tests (`go test -short ./...` for local, full tests run in CI) +- **Documentation**: Update relevant .md files + +### File Organization + +``` +beads/ +├── cmd/bd/ # CLI commands +├── internal/ +│ ├── types/ # Core data types +│ └── storage/ # Storage layer +│ └── sqlite/ # SQLite implementation +├── examples/ # Integration examples +└── *.md # Documentation +``` + +### Testing Workflow + +**IMPORTANT:** Never pollute the production database with test issues! + +**For manual testing**, use the `BEADS_DB` environment variable to point to a temporary database: + +```bash +# Create test issues in isolated database +BEADS_DB=/tmp/test.db ./bd init --quiet --prefix test +BEADS_DB=/tmp/test.db ./bd create "Test issue" -p 1 + +# Or for quick testing +BEADS_DB=/tmp/test.db ./bd create "Test feature" -p 1 +``` + +**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 +} +``` + +**Warning:** bd will warn you when creating issues with "Test" prefix in the production database. Always use `BEADS_DB` for manual testing. + +### Before Committing + +1. **Run tests**: `go test -short ./...` (full tests run in CI) +2. **Run linter**: `golangci-lint run ./...` (ignore baseline warnings) +3. **Update docs**: If you changed behavior, update README.md or other docs +4. **Commit**: Issues auto-sync to `.beads/issues.jsonl` and import after pull + +### Git Workflow + +**Auto-sync provides batching!** bd automatically: + +- **Exports** to JSONL after CRUD operations (30-second debounce for batching) +- **Imports** from JSONL when it's newer than DB (e.g., after `git pull`) +- **Daemon commits/pushes** every 5 seconds (if `--auto-commit` / `--auto-push` enabled) + +The 30-second debounce provides a **transaction window** for batch operations - multiple issue changes within 30 seconds get flushed together, avoiding commit spam. + +### Git Integration + +**Auto-sync**: bd automatically exports to JSONL (30s debounce), imports after `git pull`, and optionally commits/pushes. + +**Protected branches**: Use `bd init --branch beads-metadata` to commit to separate branch. See [docs/PROTECTED_BRANCHES.md](docs/PROTECTED_BRANCHES.md). + +**Git worktrees**: Daemon mode NOT supported. Use `bd --no-daemon` for all commands. See [docs/GIT_INTEGRATION.md](docs/GIT_INTEGRATION.md). + +**Merge conflicts**: Rare with hash IDs. If conflicts occur, use `git checkout --theirs/.beads/beads.jsonl` and `bd import`. See [docs/GIT_INTEGRATION.md](docs/GIT_INTEGRATION.md). + +## Landing the Plane + +**When the user says "let's land the plane"**, follow this clean session-ending protocol: + +1. **File beads issues for any remaining work** that needs follow-up +2. **Ensure all quality gates pass** (only if code changes were made) - run tests, linters, builds (file P0 issues if broken) +3. **Update beads issues** - close finished work, update status +4. **Sync and PUSH everything to remote** - Work methodically to ensure both local and remote are synchronized: + ```bash + # Pull first to catch any remote changes + git pull --rebase + + # If conflicts in .beads/beads.jsonl, resolve thoughtfully: + # - git checkout --theirs .beads/beads.jsonl (accept remote) + # - bd import -i .beads/beads.jsonl (re-import) + # - Or manual merge, then import + + # Sync the database (exports to JSONL, commits) + bd sync + + # CRITICAL: Push everything to remote + git push + + # Verify push succeeded + git status # Should show "up to date with origin/main" + ``` + **CRITICAL**: The plane has NOT landed until `git push` completes successfully. If you don't push, the work is still on the runway! +5. **Clean up git state** - Clear old stashes and prune dead remote branches: + ```bash + git stash clear # Remove old stashes + git remote prune origin # Clean up deleted remote branches + ``` +6. **Verify clean state** - Ensure all changes are committed AND PUSHED, no untracked files remain +7. **Choose a follow-up issue for next session** + - Provide a prompt for the user to give to you in the next session + - Format: "Continue work on bd-X: [issue title]. [Brief context about what's been done and what's next]" + +**Example "land the plane" session:** + +```bash +# 1. File remaining work +bd create "Add integration tests for sync" -t task -p 2 --json + +# 2. Run quality gates (only if code changes were made) +go test -short ./... +golangci-lint run ./... + +# 3. Close finished issues +bd close bd-42 bd-43 --reason "Completed" --json + +# 4. Sync and PUSH everything +git pull --rebase +# If conflicts in .beads/beads.jsonl, resolve thoughtfully: +# - git checkout --theirs .beads/beads.jsonl (accept remote) +# - bd import -i .beads/beads.jsonl (re-import) +# - Or manual merge, then import +bd sync # Export/import/commit +git push # CRITICAL - Must push! +git status # Verify "up to date with origin/main" + +# 5. Clean up git state +git stash clear +git remote prune origin + +# 6. Verify everything is clean and pushed +git status + +# 7. Choose next work +bd ready --json +bd show bd-44 --json +``` + +**Then provide the user with:** + +- Summary of what was completed this session +- What issues were filed for follow-up +- Status of quality gates (all passing / issues filed) +- Recommended prompt for next session + +## Agent Session Workflow + +**IMPORTANT for AI agents:** When you finish making issue changes, always run: + +```bash +bd sync +``` + +This immediately: + +1. Exports pending changes to JSONL (no 30s wait) +2. Commits to git +3. Pulls from remote +4. Imports any updates +5. Pushes to remote + +**Example agent session:** + +```bash +# Make multiple changes (batched in 30-second window) +bd create "Fix bug" -p 1 +bd create "Add tests" -p 1 +bd update bd-42 --status in_progress +bd close bd-40 --reason "Completed" + +# Force immediate sync at end of session +bd sync + +# Now safe to end session - everything is committed and pushed +``` + +**Why this matters:** + +- Without `bd sync`, changes sit in 30-second debounce window +- User might think you pushed but JSONL is still dirty +- `bd sync` forces immediate flush/commit/push + +**STRONGLY RECOMMENDED: Install git hooks for automatic sync** (prevents stale JSONL problems): + +```bash +# One-time setup - run this in each beads workspace +bd hooks install +``` + +This installs: + +- **pre-commit** - Flushes pending changes immediately before commit (bypasses 30s debounce) +- **post-merge** - Imports updated JSONL after pull/merge (guaranteed sync) +- **pre-push** - Exports database to JSONL before push (prevents stale JSONL from reaching remote) +- **post-checkout** - Imports JSONL after branch checkout (ensures consistency) + +**Why git hooks matter:** +Without the pre-push hook, you can have database changes committed locally but stale JSONL pushed to remote, causing multi-workspace divergence. The hooks guarantee DB ↔ JSONL consistency. + +**Note:** Hooks are embedded in the bd binary and work for all bd users (not just source repo users). + +## Common Development Tasks + +### 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. Update schema in `internal/storage/sqlite/schema.go` +2. Add migration if needed +3. Update `internal/types/types.go` if new types +4. Implement in `internal/storage/sqlite/sqlite.go` +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 and Testing + +```bash +# Build +go build -o bd ./cmd/bd + +# Test (short - for local development) +go test -short ./... + +# Test with coverage (full tests - for CI) +go test -coverprofile=coverage.out ./... +go tool cover -html=coverage.out + +# Run locally +./bd init --prefix test +./bd create "Test issue" -p 1 +./bd ready +``` + +## 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 --commit` +2. Push to GitHub +3. Confirm all versions updated correctly + +**Files updated automatically:** + +- `cmd/bd/version.go` - CLI version +- `.claude-plugin/plugin.json` - Plugin version +- `.claude-plugin/marketplace.json` - 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) + +**Automated (Recommended):** + +```bash +# One command to do everything (version bump, tests, tag, Homebrew update, local install) +./scripts/release.sh 0.9.3 +``` + +This handles the entire release workflow automatically, including waiting ~5 minutes for GitHub Actions to build release artifacts. See [scripts/README.md](scripts/README.md) for details. + +**Manual (Step-by-Step):** + +1. Bump version: `./scripts/bump-version.sh --commit` +2. Update CHANGELOG.md with release notes +3. Run tests: `go test -short ./...` (CI runs full suite) +4. Push version bump: `git push origin main` +5. Tag release: `git tag v && git push origin v` +6. Update Homebrew: `./scripts/update-homebrew.sh ` (waits for GitHub Actions) +7. Verify: `brew update && brew upgrade bd && bd version` + +See [docs/RELEASING.md](docs/RELEASING.md) for complete manual 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. + +## Questions? + +- Check existing issues: `bd list` +- Look at recent commits: `git log --oneline -20` +- Read the docs: README.md, ADVANCED.md, EXTENDING.md +- Create an issue if unsure: `bd create "Question: ..." -t task -p 2` + +## Important Files + +- **README.md** - Main documentation (keep this updated!) +- **EXTENDING.md** - Database extension guide +- **ADVANCED.md** - JSONL format analysis +- **CONTRIBUTING.md** - Contribution guidelines +- **SECURITY.md** - Security policy diff --git a/README.md b/README.md index 309f59e32..7bab0ec5c 100644 --- a/README.md +++ b/README.md @@ -245,7 +245,7 @@ This pattern has proven invaluable for maintaining database hygiene and preventi **5. Choose next work** - Provide a formatted prompt for the next session with context -See the ["Landing the Plane"](AGENTS.md#landing-the-plane) section in this project's `AGENTS.md` for a complete example you can adapt. The key insight: explicitly reminding agents to maintain issue tracker hygiene prevents the common problem of agents creating issues during work but forgetting to sync them at session end. +See the ["Landing the Plane"](AGENT_INSTRUCTIONS.md#landing-the-plane) section in this project's documentation for a complete example you can adapt. The key insight: explicitly reminding agents to maintain issue tracker hygiene prevents the common problem of agents creating issues during work but forgetting to sync them at session end. ## The Magic: Distributed Database via Git diff --git a/examples/team-workflow/README.md b/examples/team-workflow/README.md index 3d921b565..e4820f656 100644 --- a/examples/team-workflow/README.md +++ b/examples/team-workflow/README.md @@ -255,7 +255,7 @@ git checkout --ours .beads/beads.jsonl bd import -i .beads/beads.jsonl # Option 3: Use beads-merge tool (recommended) -# See AGENTS.md for beads-merge integration +# See docs/GIT_INTEGRATION.md for merge conflict resolution git add .beads/beads.jsonl git commit @@ -369,7 +369,7 @@ bd daemon start --auto-commit --auto-push ### Issue: Merge conflicts in JSONL -Use beads-merge (see [AGENTS.md](../../AGENTS.md#advanced-intelligent-merge-tools)) or resolve manually: +Use beads-merge or resolve manually (see [GIT_INTEGRATION.md](../../docs/GIT_INTEGRATION.md)): ```bash git checkout --theirs .beads/beads.jsonl @@ -399,4 +399,4 @@ bd validate --checks=conflicts - [Protected Branch Setup](../protected-branch/) - [Contributor Workflow](../contributor-workflow/) - [Multi-Repo Migration Guide](../../docs/MULTI_REPO_MIGRATION.md) -- [Advanced Merge Tools](../../AGENTS.md#advanced-intelligent-merge-tools) +- [Git Integration Guide](../../docs/GIT_INTEGRATION.md)