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:
parent
e17502dda1
commit
8b7cbfc3bc
3 changed files with 121 additions and 346 deletions
|
|
@ -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
353
CLAUDE.md
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue