docs(claude): make root agent guide a source pointer (#3795)

Resolve the stale CLAUDE.md problem by removing the duplicated workflow/build/storage guide from the root Claude entrypoint. The root file now points to canonical sources, while the unique Visual Design System content moves into AGENT_INSTRUCTIONS.md where AGENTS.md already directs agents for full guidance.

Also refresh docs/CLAUDE.md architecture paths that had drifted from current main.

Refs GH#3426.

Co-authored-by: Steven Syrek <steven.syrek@deepl.com>
This commit is contained in:
matt wilkie 2026-05-07 13:44:56 -07:00 • committed by GitHub
commit 8b7cbfc3bc
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 121 additions and 346 deletions

View file

@ -93,7 +93,7 @@ bd hooks install
### Git Integration
**Dolt sync**: Dolt handles sync natively via `bd dolt push` / `bd dolt pull`. No JSONL export/import needed.
**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/PROTECTED_BRANCHES.md](docs/PROTECTED_BRANCHES.md).
@ -302,6 +302,97 @@ This installs:
## 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: `●` (filled circle with color)
#### 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 Icons and Colors
Format priority as `● P0` (filled circle icon plus label, colored by priority):
- `● P0`: Red + bold (critical)
- `● P1`: Orange (high)
- `● P2-P4`: Default text (normal)
#### 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:

353
CLAUDE.md
View file

@ -1,340 +1,23 @@
# Instructions for AI Agents Working on Beads
# Claude Code Entry Point for Beads
> **Reading order**: Architecture → `docs/CLAUDE.md` | Workflow → `AGENT_INSTRUCTIONS.md` | PR maintenance → `PR_MAINTAINER_GUIDELINES.md` | Quick ref → `AGENTS.md`
>
> Run `bd prime` for AI-optimized context. Run `bd memories` to see persistent learnings.
This file is intentionally short. Do not copy workflow, build, storage, or UI
rules here; those details drift quickly when repeated across agent entrypoints.
## Project Overview
## Read First
This is **beads** (command: `bd`), a Dolt-powered issue tracker designed for AI-supervised coding workflows. We dogfood our own tool!
- **Workflow and safety**: [AGENTS.md](AGENTS.md)
- **Detailed agent operations**: [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md)
- **Architecture orientation**: [docs/CLAUDE.md](docs/CLAUDE.md)
- **PR maintenance policy**: [PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md)
## Issue Tracking
## Current Ground Rules
We use bd (beads) for issue tracking instead of Markdown TODOs or external tools.
### Quick Reference
```bash
# Find ready work (no blockers)
bd ready --json
# Find ready work including future deferred issues
bd ready --include-deferred --json
# Create new issue
bd create "Issue title" -t bug|feature|task -p 0-4 -d "Description" --json
# Create issue with due date and defer (GH#820)
bd create "Task" --due=+6h # Due in 6 hours
bd create "Task" --defer=tomorrow # Hidden from bd ready until tomorrow
bd create "Task" --due="next monday" --defer=+1h # Both
# Update issue status
bd update <id> --status in_progress --json
# Update issue with due/defer dates
bd update <id> --due=+2d # Set due date
bd update <id> --defer="" # Clear defer (show immediately)
# Link discovered work
bd dep add <discovered-id> <parent-id> --type discovered-from
# Complete work
bd close <id> --reason "Done" --json
# Show dependency tree
bd dep tree <id>
# Get issue details
bd show <id> --json
# Query issues by time-based scheduling (GH#820)
bd list --deferred # Show issues with defer_until set
bd list --defer-before=tomorrow # Deferred before tomorrow
bd list --defer-after=+1w # Deferred after one week from now
bd list --due-before=+2d # Due within 2 days
bd list --due-after="next monday" # Due after next Monday
bd list --overdue # Due date in past (not closed)
```
### Workflow
1. **Check for ready work**: Run `bd ready` to see what's unblocked
2. **Claim your task**: `bd update <id> --claim` (atomic compare-and-swap)
3. **Work on it**: Implement, test, document
4. **Discover new work**: If you find bugs or TODOs, create issues:
- `bd create "Found bug in auth" -t bug -p 1 --json`
- Link it: `bd dep add <new-id> <current-id> --type discovered-from`
5. **Complete**: `bd close <id> --reason "Implemented"`
### Issue Types
- `bug` - Something broken that needs fixing
- `feature` - New functionality
- `task` - Work item (tests, docs, refactoring)
- `epic` - Large feature composed of multiple issues
- `chore` - Maintenance work (dependencies, tooling)
### Priorities
- `0` - Critical (security, data loss, broken builds)
- `1` - High (major features, important bugs)
- `2` - Medium (nice-to-have features, minor bugs)
- `3` - Low (polish, optimization)
- `4` - Backlog (future ideas)
### Dependency Types
- `blocks` - Hard dependency (issue X blocks issue Y)
- `related` - Soft relationship (issues are connected)
- `parent-child` - Epic/subtask relationship
- `discovered-from` - Track issues discovered during work
Only `blocks` dependencies affect the ready work queue.
## Development Guidelines
### Code Standards
- **Go version**: see `go.mod` for the required version (currently 1.26+)
- **Build tag**: `-tags gms_pure_go` is **MANDATORY** for all builds and tests
- **Build/Install**: `make build` / `make install` (never bare `go build` or `go install`)
- **Testing**: `make test` (never bare `go test ./...` — it misses required tags)
- **Linting**: `golangci-lint run ./...` (baseline warnings documented in docs/LINTING.md)
- **Documentation**: Update relevant .md files
### File Organization
```
beads/
├── cmd/bd/ # CLI commands (Cobra, one file per command)
├── internal/
│ ├── types/ # Core data types
│ ├── config/ # Configuration
│ ├── configfile/ # Config file handling
│ └── storage/ # Storage layer
│ ├── dolt/ # Dolt implementation (primary)
│ └── embeddeddolt/ # Embedded Dolt (CGO-dependent)
├── integrations/ # MCP server, external integrations
├── examples/ # Integration examples
└── *.md # Documentation
```
### Before Committing
1. **Run tests**: `make test` (or `./scripts/test.sh`)
2. **Run linter**: `golangci-lint run ./...` (ignore baseline warnings)
3. **Update docs**: If you changed behavior, update README.md or other docs
4. **Install git hooks**: `bd hooks install` (auto-commits Dolt changes)
### Git Workflow
bd uses **Dolt** as its primary database with automatic versioning:
```bash
# Each bd write auto-commits to Dolt history
bd create "Issue title" -p 1
# Sync with remote
bd dolt push # Push Dolt data
bd dolt pull # Pull Dolt data
# Git workflow (code changes only)
git add <files>
git commit -m "Your message"
git push
```
Install git hooks via `bd hooks install` for automatic sync.
## Current Project Status
Run `bd stats` to see overall progress.
### Active Areas
- **Core CLI**: Mature, always room for polish
- **Examples**: Growing collection of agent integrations
- **Documentation**: Comprehensive but can always improve
- **MCP Server**: Available at `integrations/beads-mcp/`
- **Claude/Codex Plugin**: Shared plugin package at `plugins/beads/`
## Common 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. 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 (both unit and embedded via `//go:build cgo`)
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, docs/CONFIG.md
- Create an issue if unsure: `bd create "Question: ..." -t task -p 2`
## Important Files
- **README.md** - Main documentation (keep this updated!)
- **AGENT_INSTRUCTIONS.md** - Detailed agent operational guide (authoritative)
- **ADVANCED.md** - Advanced features (rename, merge, compaction)
- **CONTRIBUTING.md** - Contribution guidelines
- **SECURITY.md** - Security policy
- **docs/CLAUDE.md** - Architecture overview
## Pro Tips for Agents
- Always use `--json` flags for programmatic use
- Link discoveries with `discovered-from` to maintain context
- Check `bd ready` before asking "what next?"
- Use `bd dolt push` to sync Dolt data to remote
- Use `bd dep tree` to understand complex dependencies
- Priority 0-1 issues are usually more important than 2-4
## Visual Design System
When adding CLI output features, follow these design principles for consistent, cognitively-friendly visuals.
### CRITICAL: No Emoji-Style Icons
**NEVER use large colored emoji icons** like 🔴🟠🟡🔵⚪ for priorities or status.
These cause cognitive overload and break visual consistency.
**ALWAYS use small Unicode symbols** with semantic colors applied via lipgloss:
- Status: `○ ◐ ● ✓ ❄`
- Priority: `●` (filled circle with color)
### Status Icons (use consistently across all commands)
```
○ 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 Icons and Colors
Format: `● P0` (filled circle icon + label, colored by priority)
- **● P0**: Red + bold (critical)
- **● P1**: Orange (high)
- **● P2-P4**: Default text (normal)
### Issue Type Colors
- **bug**: Red (problems need attention)
- **epic**: Purple (larger scope)
- **Others**: Default text
### Design Principles
1. **Small Unicode symbols only** - NO emoji blobs (🔴🟠 etc.)
2. **Semantic colors only for actionable items** - Don't color everything
3. **Closed items fade** - Use muted gray to show "done"
4. **Icons > text labels** - More scannable, less cognitive load
5. **Consistency across commands** - Same icons in list, graph, show, etc.
6. **Tree connectors** - Use `├──`, `└──`, `│` for hierarchies (file explorer pattern)
7. **Reduce cognitive noise** - Don't show "needs:1" when it's just the parent epic
### Semantic Styles (internal/ui/styles.go)
Use exported styles from the `ui` package:
```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 Usage
```go
// Status icon with semantic color
switch issue.Status {
case types.StatusOpen:
icon = "○" // no color - available but not urgent
case types.StatusInProgress:
icon = ui.StatusInProgressStyle.Render("◐") // yellow
case types.StatusBlocked:
icon = ui.StatusBlockedStyle.Render("●") // red
case types.StatusClosed:
icon = ui.StatusClosedStyle.Render("✓") // muted
}
```
## Building and Testing
```bash
# Build (uses gms_pure_go tag, CGO)
make build
# Install to ~/.local/bin (canonical path)
make install
# Test (default local/CI path)
make test
# Test with coverage
go test -tags gms_pure_go -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
# Verify installed binary
bd init --prefix test
bd create "Test issue" -p 1
bd ready
```
> **WARNING**: Never use bare `go build -o bd` or `go install` — they miss the
> required `gms_pure_go` tag and create stale binaries. Always use `make install`.
## Release Process (Maintainers)
1. Update version in code (if applicable)
2. Update CHANGELOG.md (if exists)
3. Run full test suite
4. Tag release: `git tag v0.x.0`
5. Push tag: `git push origin v0.x.0`
6. GitHub Actions handles the rest
---
**Remember**: We're building this tool to help AI agents like you! If you find the workflow confusing or have ideas for improvement, create an issue with your feedback.
Happy coding!
- 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.

View file

@ -16,11 +16,11 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
- **Dolt** in `storage/dolt/` — version-controlled SQL database with cell-level merge
- Common types and interfaces in `storage.go`
2. **RPC Layer** (`internal/rpc/`)
- Client/server architecture using Unix domain sockets (Windows named pipes)
- Protocol defined in `protocol.go`
- Server split into focused files: `server_core.go`, `server_issues_epics.go`, `server_labels_deps_comments.go`, etc.
- Used by Dolt server mode for multi-writer access
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.)
@ -41,13 +41,14 @@ 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; `bd export` available for data portability, `bd init --from-jsonl` for bootstrapping
- **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/`
- Export: `cmd/bd/export.go`
- Sync: `cmd/bd/sync_git.go`
- 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
@ -103,8 +104,8 @@ bd ready
- **AGENTS.md** - Complete workflow and development guide (READ THIS!)
- **README.md** - User-facing documentation
- **ADVANCED.md** - Advanced features (rename, merge, compaction)
- **LABELS.md** - Complete label system guide
- **CONFIG.md** - Configuration system
- **docs/LABELS.md** - Complete label system guide
- **docs/CONFIG.md** - Configuration system
## When Adding Features