Commit graph

107 commits

Author SHA1 Message Date
matt wilkie
46be5594d6
Add maintainer PR guidelines (bd-k0j) (#3665)
Turn the PR assessment workflow from @steveyegge 's Vibe Maintainer into an agent-neutral maintainer PR guidelines documents
2026-05-02 13:21:15 -07:00
matt wilkie
e19e31c191
docs(agents): add Storage Boundary section to AGENTS.md (#3617)
Captures the architectural direction that beads talks to storage through a
driver interface (dolthub/driver) and should not reach across that boundary.
Concurrency, locking, and crash-safety are the driver's job; storage-
implementation details should not appear on the public SDK surface.

Notes that storage issues are still welcome from the beads side, but should
be flagged for routing to the driver rather than worked around in beads.

Context: gastownhall/beads#3614 (removing the embedded-mode flock) is an
example of this direction — that PR motivated capturing the principle so
future contributors and agents don't reflexively reintroduce cross-boundary
workarounds.

Co-authored-by: CI Bot <ci@beads.test>
2026-05-01 11:53:01 -07:00
matt wilkie
8694c53589
doctor: detect AGENTS.md / CLAUDE.md user-authored divergence (#3600)
* doctor: detect AGENTS.md / CLAUDE.md user-authored divergence

Adds CheckAgentDocDivergence to bd doctor and bd preflight. The check
flags cases where AGENTS.md and CLAUDE.md exist as independent regular
files whose content outside the BEGIN/END BEADS INTEGRATION markers has
drifted apart — a common drift mode when agents hand-edit one of the
pair without mirroring the change.

Skipped when:
  - Either file is missing
  - The pair is symlinked or shares an inode (hardlink)
  - Normalized user-authored content matches
  - Either file contains the opt-out marker
    <!-- bd-doctor-divergence: ok --> (for projects that intentionally
    keep distinct files for different audiences, like beads itself)

Adds the opt-out marker to AGENTS.md so the upstream beads repo, whose
AGENTS.md and CLAUDE.md serve intentionally different audiences, does
not regress its own preflight.

Closes mybd-31m.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(lint): hyphenate hardlinked to satisfy misspell linter

misspell flags 'hardlinked' as a typo for 'hardline'. Hyphenating to
'hard-linked' is a common alternate spelling and sidesteps the false
positive without changing meaning.

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: CI Bot <ci@beads.test>
2026-04-30 13:26:31 -07:00
Afik
674561360d
schema: make DROP COLUMN migrations idempotent (fixes migration 0032 loop) (#3418)
* cmd/bd: extract sanitizeDBName to its own file for CGO_ENABLED=0 lint

sanitizeDBName lived in store_factory.go which is //go:build cgo,
but init.go (no tag) calls it. The pre-commit golangci-lint runs
with CGO_ENABLED=0 and flagged it as undefined. Move the pure-Go
function to its own untagged file and drop the now-unused strings
import from store_factory.go. No behavior change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* schema: tolerate "does not have column" errors in migration runner

Broadens isConcurrentInitError to also treat "does not have column"
as a benign migration error, symmetric with the existing "duplicate
column" tolerance for ADD races. Makes DROP COLUMN migrations
idempotent across databases bootstrapped with different base schemas.

Observed failure: migration 0032 (DROP COLUMN applied_at) loops
forever on any database that lands at v31 without the column. Dolt
has no DROP COLUMN IF EXISTS, so the SQL itself can't be guarded;
handling it in the runner keeps the migration file trivial.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Add migration 0032 idempotence tests (bd-7mh.3)

* Document bd execution metadata workflow (bd-b1a)

* Revert "Document bd execution metadata workflow (bd-b1a)"

This reverts commit 0d6a96babd.

* Reapply "Document bd execution metadata workflow (bd-b1a)"

This reverts commit df90cf5404.

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
2026-04-27 09:15:20 -07:00
matt wilkie
6e506b6ddd
Add PR preflight and contributor intake guidance (#3470)
* Handle legacy PR status contexts

* docs: add contributor PR intake checklist

* docs: wire PR preflight into agent guidance
2026-04-24 15:44:06 -07:00
matt wilkie
df25aa9229
Rename ICU-only test path to explicit opt-in workflow (bd-b18) (#3291) 2026-04-16 08:54:24 -07:00
matt wilkie
0ed8d0b271
docs: add contributor protection policy for AI agents (#3151)
Prevents agents from silently overwriting external contributor PRs.
Prompted by PR #3143 where bgjackma's work was reimplemented without
attribution.

- CONTRIBUTING.md: "Your PR Will Not Be Overwritten" section
- AGENT_INSTRUCTIONS.md: check-before-you-build procedure + CONTRIBUTING.md reference
- AGENTS.md: cross-reference to contributor protection
2026-04-09 12:41:43 -07:00
maphew
5ad64bea05 docs: teach agents to use stdin for descriptions (GH#1376)
bd create/update --description=- reads from stdin, avoiding shell
escaping failures with backticks, nested quotes, and special characters.
This capability already exists in flags.go but was not surfaced in
agent instructions or plugin skills.

Update AGENT_INSTRUCTIONS.md, AGENTS.md, and CLI_REFERENCE.md to show
the stdin pipe pattern as the recommended approach for descriptions
with special characters.

Closes: GH#1376
Co-authored-by: Amp <amp@ampcode.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019ca7ab-f5f9-761f-8934-60d3c590adc3
2026-02-28 21:34:14 -07:00
Aaron Lippold
49aed46c85
fix: harden SQLite→Dolt migration safety, old-schema compat, and doctor recovery (#2156)
* fix(configfile): respect backend field in metadata.json

GetBackend() was hardcoded to always return "dolt", ignoring the
backend field in metadata.json. This forced all SQLite users onto
Dolt with no migration path and no way to opt out.

- Add BackendSQLite constant and case-insensitive normalization
- GetBackend() reads backend field: sqlite → sqlite, empty/dolt → dolt
- DatabasePath() routes to SQLite or Dolt path based on backend
- BEADS_BACKEND env var override as escape hatch for corrupted configs
- CapabilitiesForBackend handles sqlite backend
- Warning on unrecognized BEADS_BACKEND values
- 55 tests covering all paths including env var, case normalization,
  roundtrip persistence, and DatabasePath routing

Fixes #2016.

Authored by: Aaron Lippold<lippold@gmail.com>

* feat(migrate): add shared migration safety functions

Extract reusable safety functions for SQLite→Dolt migration:
- backupSQLite: file copy with O_EXCL + 0600 permissions
- verifyServerTarget: TCP + SQL check to prevent wrong-server writes
- verifyMigrationCounts: source vs target count verification
- finalizeMigration: atomic metadata update (last step only)
- rollbackMetadata: restore original config on failure

22 unit tests covering all functions including counter overflow,
non-MySQL server detection, deps-only mismatch, nil config rollback,
server config preservation, and no-metadata scenarios.

Authored by: Aaron Lippold<lippold@gmail.com>

* refactor(migrate): use safety functions in auto-migration

Refactor both CGO and non-CGO auto-migration paths to use shared
safety functions instead of inline logic:

Phase 1 (pre-flight):
- Always backup SQLite before any migration attempt
- Verify server target to prevent writing to wrong Dolt server
- Skip migration when backend explicitly set to sqlite (GH#2016)
- Use GetBackend() for SQLite guard, strings.EqualFold for Dolt
  stale-leftover detection (preserves legacy empty-backend migration)

Phase 2 (import):
- Unchanged: extract from SQLite, create Dolt store, import data

Phase 3 (verify + finalize):
- Verify issue counts match before updating metadata
- Atomic finalization via finalizeMigration (metadata last)
- Rollback with warning on failure (not silent discard)

Clear, actionable error messages at every failure point showing
backup path. 13 unit tests including new SQLite backend guard test.

Authored by: Aaron Lippold<lippold@gmail.com>

* fix(main): clear error when SQLite backend detected

When GetBackend() returns "sqlite" (user opted to stay on SQLite or
migration was skipped), print a clear error with migration instructions
instead of falling through to dolt.New() which produces a confusing
Dolt connection failure.

Fixes #2016.

Authored by: Aaron Lippold<lippold@gmail.com>

* feat(doctor): detect and fix broken migration states

Add three new doctor checks for migration-related issues:

CheckBrokenMigrationState: detects metadata claiming Dolt backend
but no Dolt directory present (with server-mode awareness). Offers
bd doctor --fix to restore SQLite backend from beads.db or
beads.db.migrated files.

CheckSQLiteResidue: detects leftover beads.db after successful
migration. Fix renames to .migrated (with backend guard to prevent
accidentally renaming active SQLite database).

CheckEmbeddedModeConcurrency: detects embedded mode with lock
contention indicators (dolt-access.lock, noms LOCK files).
Recommends switching to server mode for multi-agent workflows.
Addresses #2086.

19 doctor tests covering all detection paths including server mode,
backup file detection, .migrated-only recovery, zero-byte files,
concurrent access with access locks and noms locks.

Fixes #2086.

Authored by: Aaron Lippold<lippold@gmail.com>

* test(migrate): add integration tests for migration safety

8 integration tests covering key business flows:
- Full migration lifecycle (SQLite → backup → Dolt → bd list works)
- Failed migration recovery (corrupt SQLite → backup exists → intact)
- Doctor detects broken state and fix restores SQLite backend
- Doctor fixes beads.db.migrated rename-back recovery
- Idempotent retry (second migration is no-op)
- SQLite guard prevents auto-migration (data intact, no backup)
- Backup content matches source byte-for-byte
- Metadata JSON valid with all required fields after migration

Authored by: Aaron Lippold<lippold@gmail.com>

* feat(scripts): add migrate-audit.sh for batch SQLite→Dolt migration

Utility script to audit and batch-migrate beads boards:
- Scans all .beads/ directories under a configurable root
- Reports backend state, issue count, and schema version for each board
- --dry-run: shows what --migrate would do without changes
- --migrate: batch converts eligible SQLite boards to Dolt
- --exclude PATTERN: skip projects matching regex (e.g., "backup|test")
- --port/--host: target a specific Dolt server

Safety features:
- Backs up metadata.json before modifying each board
- Restores original metadata.json on migration failure
- Skips boards with old schema (missing owner column)
- bd binary handles SQLite backup, server verification, count verification
- Uses jq for JSON (consistent with existing scripts, no python dependency)

Companion tool for the migration safety PR (GH#2016, GH#2086).

Authored by: Aaron Lippold<lippold@gmail.com>

* fix(migrate): handle all schema versions in SQLite extract

Databases from older beads versions are missing columns added over time
(owner, created_by, crystallizes, mol_type, work_type, quality_score,
source_system, and others). The extract functions hardcoded COALESCE
for all columns, causing "no such column" errors.

Fix: make ALL non-id columns use sqliteOptionalTextExpr via a DRY
opt() helper in both CGO extract and shim extract paths. Missing
columns default to empty/zero/null. Also adds empty/corrupt beads.db
handling to the migrate-audit.sh script.

Tested against 12 real-world databases spanning multiple beads versions,
from the earliest (~30 columns) to the current schema (50+ columns).
All 28 boards migrated successfully.

Authored by: Aaron Lippold<lippold@gmail.com>
2026-02-26 15:48:47 -08:00
David Ahmann
10edfa9894 docs+tooling: standardize CGO test workflow and ICU setup 2026-02-10 10:56:12 -05:00
beads/crew/elinor
febaf3f1ff docs: add non-interactive shell command guidance for agents
Adds documentation warning agents to always use -f flags with cp, mv, rm
to avoid hanging on interactive confirmation prompts. This is especially
important for polecats running on systems where shell aliases include
the -i flag by default.

Also includes guidance for scp, ssh, apt-get, and brew.

Fixes bd-tm2p

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-05 09:50:35 -08:00
mayor
d08c1b5162 fix(dolt): remove bd sync from AGENTS.md
SQLite-era instruction causing agents to run deprecated bd sync.
With Dolt backend, there is no sync - database is live.

Part of hq-e4eefc (Dolt migration epic)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-25 11:05:20 -08:00
Steve Yegge
aae234bba7
Merge pull request #1138 from steveyegge/fix/agents-md-claude-md-reference-1049
docs: fix AGENTS.md references to nonexistent CLAUDE.md
2026-01-17 00:24:55 -08:00
beads/crew/grip
7a61e6b1e5 docs: fix AGENTS.md references to nonexistent CLAUDE.md
Fixes #1049 - AGENTS.md referenced CLAUDE.md which doesn't exist on main.

Changes:
- "Key Sections in CLAUDE.md" -> "Key Sections"
- "See CLAUDE.md..." -> "See AGENT_INSTRUCTIONS.md..."

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-17 00:15:24 -08:00
beads/crew/giles
ff67b88ea9 docs: Add agent warning about interactive bd edit command
The bd edit command opens an interactive editor ($EDITOR) which AI agents
cannot use. Added warnings to AGENTS.md, AGENT_INSTRUCTIONS.md, and
cmd/bd/AGENTS.md directing agents to use bd update with flags instead.

Fixes: bd-3ft33

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-13 20:58:07 -08:00
Matthew Jacobi
7096c61fbe
Update link to full instructions in AGENTS.md (#1075) 2026-01-13 11:28:25 -08:00
beads/crew/emma
5528315838 Revert "docs: forbid crew workers from creating PRs"
This reverts commit d079af7cf9.
2026-01-10 23:52:43 -08:00
beads/crew/emma
d079af7cf9 docs: forbid crew workers from creating PRs
PRs are for external contributors. Crew workers commit directly to main.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-10 23:49:10 -08:00
Ryan Snodgrass
7e70de1f6d
docs: add daemon technical analysis and update agent instructions
- Add comprehensive daemon architecture documentation to CLAUDE.md
- Update AGENTS.md with AI workflow guidelines
- Document auto-sync configuration for simpler agent workflows

Co-Authored-By: SageOx <ox@sageox.ai>
2026-01-08 20:37:31 -08:00
Steve Yegge
5bf3515e8e feat(mol): add distill command to extract protos from epics
Implements bd mol distill to reverse the spawn operation:
- molecule → proto (spawn is proto → molecule)

Features:
- --as flag for custom proto title
- --var value=variable to replace concrete values with placeholders
- --dry-run to preview the distilled structure
- Preserves full subgraph structure and dependencies
- Adds template label to all cloned issues

Also updates AGENTS.md with landing checklist.

Closes: bd-iq19

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-21 10:32:23 -08:00
Steve Yegge
f3b0fb780f refactor: consolidate agent instructions into CLAUDE.md
Move all agent instructions from AGENTS.md into CLAUDE.md, which
Claude Code reads automatically. AGENTS.md now just redirects.

Also remove MCP server from plugin.json - the plugin now uses
hooks-only mode for better token efficiency.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-20 03:05:42 -08:00
Steve Yegge
83ae110508 refactor: Remove legacy MCP Agent Mail integration (bd-6gd)
Remove the external MCP Agent Mail server integration that required
running a separate HTTP server and configuring environment variables.

The native `bd mail` system (stored as git-synced issues) remains
unchanged and is the recommended approach for inter-agent messaging.

Files removed:
- cmd/bd/message.go - Legacy `bd message` command
- integrations/beads-mcp/src/beads_mcp/mail.py, mail_tools.py
- lib/beads_mail_adapter.py - Python adapter library
- examples/go-agent/ - Agent Mail-focused example
- examples/python-agent/agent_with_mail.py, AGENT_MAIL_EXAMPLE.md
- docs/AGENT_MAIL*.md, docs/adr/002-agent-mail-integration.md
- tests/integration/test_agent_race.py, test_mail_failures.py, etc.
- tests/benchmarks/ - Agent Mail benchmarks

Updated documentation to remove Agent Mail references while keeping
native `bd mail` documentation intact.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-17 23:14:23 -08:00
Steve Yegge
8d73a86f7a feat: complete bd-kwro messaging & knowledge graph epic
- Add bd cleanup --ephemeral flag for transient message cleanup (bd-kwro.9)
- Add Ephemeral filter to IssueFilter type
- Add ephemeral filtering to SQLite storage queries

Tests (bd-kwro.10):
- Add internal/hooks/hooks_test.go for hook system
- Add cmd/bd/mail_test.go for mail commands
- Add internal/storage/sqlite/graph_links_test.go for graph links

Documentation (bd-kwro.11):
- Add docs/messaging.md for full messaging reference
- Add docs/graph-links.md for graph link types
- Update AGENTS.md with inter-agent messaging section
- Update CHANGELOG.md with all bd-kwro features

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-16 20:36:47 -08:00
Steve Yegge
aed166fe85 fix: improve issue ID prefix extraction for word-like suffixes
Refine ExtractIssuePrefix to better distinguish hash IDs from English
words in multi-part issue IDs. Hash suffixes now require digits or be
exactly 3 chars, preventing "test", "gate", "part" from being treated
as hashes. This fixes prefix extraction for IDs like "vc-baseline-test".

Also updates git hooks to use -q flag and adds AGENTS.md documentation.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-16 13:19:22 -08:00
Logan Thomas
520e1007f1
fix/doc: Go version inconsistencies and broken documentation links (#535)
* docs: fix Go version typo in CONTRIBUTING.md (1.25 -> 1.24)

* docs: update Go version requirement to 1.24+ across docs

* docs: fix broken links to docs/ in npm-package/README.md

* docs: fix QUICKSTART.md path reference in AGENTS.md
2025-12-13 10:48:44 -08:00
Steve Yegge
59befda847 docs: add dependency direction guidance for AI agents
Add section explaining the cognitive trap where temporal language
("Phase 1", "Step 1", "before") causes inverted dependency direction.
Includes examples of correct vs incorrect dependency setup and
verification using bd blocked.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-30 12:57:58 -08:00
Steve Yegge
eeda2053b8 bd sync: 2025-11-26 18:07:01 2025-11-26 18:07:01 -08:00
Steve Yegge
4088e68da7 feat(deletions): complete deletions manifest epic with integration tests
Completes the deletion propagation epic (bd-imj) with all 9 subtasks:
- Cross-clone deletion propagation via deletions.jsonl
- bd deleted command for audit trail
- Auto-compact during sync (opt-in)
- Git history fallback with timeout and regex escaping
- JSON output for pruning results
- Integration tests for deletion scenarios
- Documentation in AGENTS.md, README.md, and docs/DELETIONS.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-25 16:36:46 -08:00
Steve Yegge
e0e6dff87f docs: Complete import.orphan_handling documentation (bd-9cdc)
Added comprehensive documentation for import orphan handling configuration
across all relevant documentation files:

- AGENTS.md: Added "Import Configuration" section with detailed mode
  explanations and usage guidance
- README.md: Documented orphan handling in Export/Import section with
  examples of all four modes
- TROUBLESHOOTING.md: Added "Import fails with missing parent errors"
  troubleshooting section with resurrection examples and prevention tips
- CLI_REFERENCE.md: Expanded Import/Export section with --orphan-handling
  flag documentation and cross-references

Documented resurrection behavior:
- Tombstone creation (Status=Closed, Priority=4)
- JSONL history search for deleted parents
- Best-effort dependency resurrection
- Hierarchical ancestor chain handling

Closes bd-9cdc

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-24 01:08:08 -08:00
Steve Yegge
a930fa35ac Refactor AGENTS.md: condense event-driven daemon section
Move detailed event-driven daemon documentation to docs/DAEMON.md.
Keep only brief mention in AGENTS.md with reference to full docs.
Reduces duplication and improves documentation organization.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-23 21:58:51 -08:00
Steve Yegge
9e16469b2e Implement BD_GUIDE.md generation for version-stamped documentation (bd-woro)
This implements the ability to separate bd-specific instructions from
project-specific instructions by generating a canonical BD_GUIDE.md file.

## Changes

1. Added `--output` flag to `bd onboard` command
   - Generates version-stamped BD_GUIDE.md at specified path
   - Includes both agentsContent and copilotInstructionsContent
   - Auto-generated header warns against manual editing

2. Version tracking integration
   - checkAndSuggestBDGuideUpdate() detects outdated BD_GUIDE.md
   - Suggests regeneration when bd version changes
   - Integrated with maybeShowUpgradeNotification()

3. Comprehensive test coverage
   - Tests for BD_GUIDE.md generation
   - Tests for version stamp validation
   - Tests for content inclusion

4. Documentation updates
   - Updated AGENTS.md with BD_GUIDE.md workflow
   - Added regeneration instructions to upgrade workflow

## Benefits

- Clear separation of concerns (bd vs project instructions)
- Deterministic updates (no LLM involved)
- Git-trackable diffs show exactly what changed
- Progressive disclosure (agents read when needed)

## Usage

\`\`\`bash
# Generate BD_GUIDE.md
bd onboard --output .beads/BD_GUIDE.md

# After upgrading bd
bd onboard --output .beads/BD_GUIDE.md  # Regenerate
\`\`\`

Closes bd-woro
2025-11-23 21:16:09 -08:00
Steve Yegge
1cc238f61d feat: Add agent upgrade awareness documentation and tooling
Implements bd-hwmp and bd-5otr (part of epic bd-nxgk) to help AI agents
automatically detect and adapt to bd upgrades.

## Changes

### Documentation (bd-hwmp)
- Added "After Upgrading bd" section to AGENTS.md with step-by-step workflow
- Enhanced "Pro Tips for Agents" with upgrade detection guidance
- Documents bd info --whats-new and bd hooks install commands
- References GitHub Discussion #239

### Startup Hook (bd-5otr)
- Created examples/startup-hooks/bd-version-check.sh
  - Auto-detects bd version changes via .beads/metadata.json
  - Shows bd info --whats-new when upgrade detected
  - Auto-updates outdated git hooks
  - Handles edge cases (no jq, not in beads project, etc.)
- Created examples/startup-hooks/README.md with integration examples
  - Claude Code, GitHub Copilot, Cursor integration patterns
  - Comprehensive usage and troubleshooting guide
- Updated examples/README.md with new startup-hooks section

## Impact

Agents can now:
- Automatically detect bd upgrades at session start
- See what changed without re-reading all documentation
- Keep git hooks in sync automatically
- Adapt workflows based on new features

Works today with zero bd code changes required!

Related: #239

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-23 16:29:56 -08:00
Steve Yegge
bf74160f05 Fix GH#366: Encourage descriptions when creating issues
Addresses GitHub Discussion #366 where users reported Claude Code
creating issues with titles but no descriptions.

Two-pronged solution:

1. Documentation improvements (bd-na8r):
   - Updated AGENTS.md with prominent guidance section
   - Added good/bad examples showing why/what/how to include
   - Updated all bd create examples to include --description
   - Enhanced MCP tool docstring with importance note
   - Updated .github/copilot-instructions.md

2. Code validation (bd-bcrt):
   - Added friendly yellow warning when description is empty
   - Warning skips test issues (title contains "test")
   - Works in both CLI and daemon modes
   - Non-blocking to preserve quick workflows

Evidence from our own projects showed significant empty description
rates:
- ~/src/beads: 110/630 (17.5%)
- ~/wyvern: 8/119 (6.7%)
- ~/src/vc: 3/170 (1.8%)

Fixes bd-0tr0, bd-na8r, bd-bcrt

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-23 14:14:40 -08:00
Steve Yegge
605fff151e feat: Add GitHub Copilot support with .github/copilot-instructions.md
Addresses GH #298 - GitHub Copilot inconsistently interpreting AGENTS.md

Changes:
- Create .github/copilot-instructions.md (132 lines, Copilot-optimized)
- Update AGENTS.md with prominent Copilot callout
- Enhance bd onboard command to generate copilot-instructions.md

Architecture: Two-file approach for different AI agents
- AGENTS.md (626 lines): Comprehensive guide for all AI agents
- .github/copilot-instructions.md (132 lines): Concise, auto-loaded for Copilot

Note: Untested with GitHub Copilot yet. Feedback from Copilot users welcome!

Co-authored-by: Claude <noreply@anthropic.com>
2025-11-21 20:52:18 -05:00
Steve Yegge
21a0656a4c Refactor AGENTS.md: Extract detailed instructions to prevent context pollution
Fixes #340

Created AGENT_INSTRUCTIONS.md to house detailed operational instructions,
reducing AGENTS.md from 963 to 626 lines (~35% reduction).

Changes:
- New AGENT_INSTRUCTIONS.md with development, testing, and release procedures
- AGENTS.md now serves as quick overview with references to detailed docs
- Updated README.md link to "Landing the Plane" section
- Fixed broken team-workflow README links

Benefits:
- Prevents context pollution when multiple tools add instructions
- Better separation: quick reference vs detailed operations
- Enables tool-specific instruction files
- Maintains all content, just reorganized

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-20 22:04:17 -05:00
Steve Yegge
f20aec672d Add warning that MCP Agent Mail is not configured
Added prominent warning at the top of the Agent Mail section in AGENTS.md
to prevent AI agents from attempting to use mcp-agent-mail tools when the
server is not set up.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-20 20:55:42 -05:00
Steve Yegge
f0d3d7345c Fix 'landing the plane' instructions - emphasize git push is CRITICAL
The previous instructions mentioned sync carefully but didn't emphasize that
git push is absolutely required for the plane to actually land. Multiple agents
have failed to push, leaving work uncommitted on the runway.

Changes:
- Added explicit 'git push' step with CRITICAL emphasis
- Added verification step to check 'up to date with origin/main'
- Updated example workflow to show push as mandatory step
- Added clear statement: 'The plane has NOT landed until git push completes'

The metaphor is obvious - if you don't push, the plane is still on the ground!

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-20 20:44:26 -05:00
Steve Yegge
346a599242 Update AGENTS.md to highlight automated release.sh script 2025-11-08 04:17:28 -08:00
Steve Yegge
37f9d3610d Complete Agent Mail documentation (bd-nl8z)
- Add AGENT_MAIL_QUICKSTART.md: 5-minute setup guide
- Add examples/python-agent/AGENT_MAIL_EXAMPLE.md: working code examples
- Add examples/python-agent/agent_with_mail.py: runnable multi-agent demo
- Update README.md: add Agent Mail to features and docs index
- Update AGENTS.md: enhance with quickstart/example references
- Update examples README: add Agent Mail example to index

Amp-Thread-ID: https://ampcode.com/threads/T-5d5e711d-7b5f-42ca-b75a-5b6cd843ad98
Co-authored-by: Amp <amp@ampcode.com>
2025-11-08 02:36:27 -08:00
Steve Yegge
a03737c89a feat: Add bd info --whats-new for agent version awareness (bd-eiz9)
- Add --whats-new flag to bd info command
- Display agent-relevant changes from last 3 versions
- Support both human-readable and JSON output
- Add version changelog data structure with workflow-impacting changes
- Add comprehensive tests for version changes structure
- Update AGENTS.md with whats-new documentation

Helps agents efficiently learn what changed between bd versions without
re-reading full documentation. Addresses weekly major version releases
requiring workflow adaptations.

Closes bd-eiz9

Amp-Thread-ID: https://ampcode.com/threads/T-5fe7e93d-7398-41c5-94bf-e914f2b331dd
Co-authored-by: Amp <amp@ampcode.com>
2025-11-08 02:28:54 -08:00
Steve Yegge
187fdd258a Add bd hooks install command with embedded git hooks (bd-908z)
- Embed git hooks in binary using go:embed and templates directory
- Add bd hooks install/uninstall/list subcommands
- Install hooks with automatic backup of existing hooks
- Update AGENTS.md to reference 'bd hooks install' instead of install.sh
- Add comprehensive tests for hooks commands
- Update hook version to 0.22.1

Closes bd-908z
2025-11-08 01:28:19 -08:00
Steve Yegge
826a3b2047 Refactor AGENTS.md: extract supplemental docs
- Create docs/DAEMON.md (daemon mgmt, event-driven mode)
- Create docs/GIT_INTEGRATION.md (worktrees, conflicts, merge drivers)
- Create docs/CLI_REFERENCE.md (comprehensive command examples)
- Reduce AGENTS.md from 1047 → 906 lines (13% reduction)
- Add Agent Mail optional workflow section (bd-2cvu)

Improves navigability while preserving all content.

Amp-Thread-ID: https://ampcode.com/threads/T-f8161cc4-d6d2-4f23-8854-4834dbdedb26
Co-authored-by: Amp <amp@ampcode.com>
2025-11-08 01:03:28 -08:00
Steve Yegge
6355ee1448 feat: implement agent-driven compaction (bd-buol)
- Add --analyze mode to export candidates without API key
- Add --apply mode to accept agent-provided summaries
- Move --auto mode for legacy AI-powered compaction
- Update documentation for new workflow
- Addresses GH #243 complaint about API key requirement
2025-11-07 23:11:05 -08:00
Steve Yegge
c416c7d266 Prevent test pollution in production database (bd-z528)
- Add warning when creating issues with 'Test' prefix
- Suggest BEADS_DB for isolated testing
- Document testing workflow in AGENTS.md
- Include examples for manual and automated testing

Amp-Thread-ID: https://ampcode.com/threads/T-fc7b7391-8881-4dd9-8e1f-28a2f95afb2b
Co-authored-by: Amp <amp@ampcode.com>
2025-11-07 22:50:58 -08:00
Steve Yegge
1065e66a75 Add bd cleanup command for bulk deletion of closed issues
Implements bd-jx90: simple cleanup command without API key requirement.

Features:
- Delete all closed issues with --force
- Filter by age with --older-than N (days)
- Preview with --dry-run
- Cascade deletion with --cascade
- JSON output support

Usage:
  bd cleanup --force                    # Delete all closed
  bd cleanup --older-than 30 --force    # Delete >30 days old
  bd cleanup --dry-run                  # Preview

Closes bd-jx90

Amp-Thread-ID: https://ampcode.com/threads/T-8d905db0-4ec7-411e-95de-1f044219dc9c
Co-authored-by: Amp <amp@ampcode.com>
2025-11-07 22:06:50 -08:00
Markus Flür
e7f532db93
Implementing an RPC monitoring solution with a web-ui as implementation example. (#244)
* bd sync: 2025-10-30 12:12:27

* Working on frontend

* bd sync: 2025-11-06 16:55:55

* feat: finish bd monitor human viewer

* Merge conflicts resolved and added tests

* bd sync: 2025-11-06 17:23:41

* bd sync: 2025-11-06 17:34:52

* feat: Add reload button and multiselect status filter to monitor

- Changed status filter from single select to multiselect with 'Open' selected by default
- Added reload button with visual feedback (hover/active states)
- Updated filterIssues() to handle multiple selected statuses
- Added reloadData() function that reloads both stats and issues
- Improved responsive design for mobile devices
- Filter controls now use flexbox layout with better spacing

* fix: Update monitor statistics to show Total, In Progress, Open, Closed

- Replaced 'Ready to Work' stat with 'In Progress' stat
- Reordered stats to show logical progression: Total -> In Progress -> Open -> Closed
- Updated loadStats() to fetch in-progress count from stats API
- Removed unnecessary separate API call for ready count

* fix: Correct API field names in monitor stats JavaScript

The JavaScript was using incorrect field names (stats.total, stats.by_status)
that don't match the actual types.Statistics struct which uses flat fields
with underscores (total_issues, in_progress_issues, etc).

Fixed by updating loadStats() to use correct field names:
- stats.total -> stats.total_issues
- stats.by_status?.['in-progress'] -> stats.in_progress_issues
- stats.by_status?.open -> stats.open_issues
- stats.by_status?.closed -> stats.closed_issues

Fixes beads-9

* bd sync: 2025-11-06 17:51:24

* bd sync: 2025-11-06 17:56:09

* fix: Make monitor require daemon to prevent SQLite locking

Implemented Option 1 from beads-eel: monitor now requires daemon and never
opens direct SQLite connection.

Changes:
- Added 'monitor' to noDbCommands list in main.go to skip normal DB initialization
- Added validateDaemonForMonitor() PreRun function that:
  - Finds database path using beads.FindDatabasePath()
  - Validates daemon is running and healthy
  - Fails gracefully with clear error message if no daemon
  - Only uses RPC connection, never opens SQLite directly

Benefits:
- Eliminates SQLite locking conflicts between monitor and daemon
- Users can now close/update issues via CLI while monitor runs
- Clear error messages guide users to start daemon first

Fixes beads-eel

* bd sync: 2025-11-06 18:03:50

* docs: Add bd daemons restart subcommand documentation

Added documentation for the 'bd daemons restart' subcommand across all documentation files:

- commands/daemons.md: Added full restart subcommand section with synopsis, description, arguments, flags, and examples
- README.md: Added restart examples to daemon management section
- AGENTS.md: Added restart examples with --json flag for agents

The restart command gracefully stops and starts a specific daemon by workspace path or PID,
useful after upgrading bd or when a daemon needs refreshing.

Fixes beads-11

* bd sync: 2025-11-06 18:13:16

* Separated the web ui from the general monitoring functionality

---------

Co-authored-by: Steve Yegge <stevey@sourcegraph.com>
2025-11-07 09:49:12 -08:00
Steve Yegge
e73f89edbe Add multi-repo patterns documentation for AI agents (bd-4b6u)
- Create docs/MULTI_REPO_AGENTS.md with comprehensive multi-repo patterns
- Document config options, routing behavior, troubleshooting, best practices
- Update AGENTS.md to reference new doc
- Update README.md documentation index

Amp-Thread-ID: https://ampcode.com/threads/T-645ccbf4-a5b6-44a1-bbd9-913447e17b49
Co-authored-by: Amp <amp@ampcode.com>
2025-11-06 19:53:29 -08:00
Steve Yegge
9c3ab7fba9 Document -short flag, update linting baseline, clarify bd edit MCP exclusion
- Enhanced CONTRIBUTING.md with -short flag usage guidance
- Updated LINTING.md: 22 issues baseline (down from 34)
- Added MCP exclusion note for bd edit command in AGENTS.md

Closes bd-iov0, bd-aec5439f, bd-fd8753d9
2025-11-06 19:42:01 -08:00
Steve Yegge
b23c472f55 Update AGENTS.md: use -short flag for all local tests
- Changed all test commands to 'go test -short ./...'
- Clarified that full tests run in CI
- Updated: Code Standards, Before Committing, Landing the Plane, Building and Testing, Release Process
- Agents should only run short tests; CI runs full suite
2025-11-06 18:48:23 -08:00
Steve Yegge
38489106c6 Add git cleanup step to 'land the plane' protocol
Amp-Thread-ID: https://ampcode.com/threads/T-c2d2b083-5566-4eea-9f8a-c4880a79e888
Co-authored-by: Amp <amp@ampcode.com>
2025-11-05 19:43:27 -08:00