Complete mybd-pnm docs evidence review.\n\n- Add verified docs disposition inventory and canonical seams.\n- Stage stale duplicate docs under docs/staged-for-removal with a manifest.\n- Refresh generated CLI docs and harden the generator for CRLF/stdin handling.\n\nFollow-up: mybd-xfr for automated docs freshness checks.
3.6 KiB
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 for complete workflow instructions, bd commands, and development guidelines.
Architecture Overview
Three-Layer Design
-
Storage Layer (
internal/storage/)- Dolt in
storage/dolt/— version-controlled SQL database with cell-level merge - Common types and interfaces in
storage.go
- Dolt in
-
Database Runtime Layer
- Embedded mode runs Dolt in-process through
internal/storage/embeddeddolt/ - Server mode uses
internal/doltserver/andinternal/storage/db/ - Proxy and pidfile helpers live under
internal/storage/db/ - Storage-facing server adapters live under
internal/storage/doltserver/
- Embedded mode runs Dolt in-process through
-
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
--jsonfor programmatic use - Main entry point in
main.go
- Cobra-based commands (one file per command:
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/, andinternal/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 systemComment: Threaded discussionsEvent: Full audit trail
Development Command Source
Use AGENT_INSTRUCTIONS.md for the current command policy. This file should not duplicate command matrices or version-management workflows.
Do NOT use
go build -o bdorgo installdirectly — they create stale binaries that shadow~/.local/bin/bd. Always usemake install.
Testing Philosophy
Testing guidance lives in TESTING.md and TESTING_PHILOSOPHY.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
--jsonflags 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/LABELS.md - Complete label system guide
- docs/CONFIG.md - Configuration system
When Adding Features
See AGENTS.md "Adding a New Command" and "Adding Storage Features" sections for step-by-step guidance.