- mint.sh + make docs-dev: local preview of the docs/ Mintlify site (Node 22 handling modeled on the Gas City wrapper). - test/docsync: Go guard keeping docs/ and docs.json in exact correspondence — every nav entry has a file, every page is in the nav (tiny stub allowlist for paths released bd binaries print), published pages use root-relative extensionless links that resolve, and engdocs/ plus curated root markdown keep exact GitHub-style paths. Wired into make check-docs. - .github/workflows/docs-mintlify.yml: docsync + baseline-aware mint broken-links check on PRs touching docs/**. - Retire scripts/sync-website-docs.sh and its mirror-drift gate: the six mirrored files now live once in the Mintlify site; the committed Docusaurus mirrors stay frozen so the parallel-run site keeps building. - Repoint inbound links to moved docs across README, guides, examples, npm-package, plugin resources, and Go comments; add docs/SYNC_CONCEPTS.md pointer stub (bd's agent templates print that path). Runtime strings in cmd/bd (prime.go, store_factory_nocgo.go, init_git_hooks.go) still print old paths — covered by stubs, flagged in the PR.
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/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.