diff --git a/AGENT_INSTRUCTIONS.md b/AGENT_INSTRUCTIONS.md index 9419dddd4..d67abd67d 100644 --- a/AGENT_INSTRUCTIONS.md +++ b/AGENT_INSTRUCTIONS.md @@ -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: diff --git a/CLAUDE.md b/CLAUDE.md index 5c2fb4820..bd43df886 100644 --- a/CLAUDE.md +++ b/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 --status in_progress --json - -# Update issue with due/defer dates -bd update --due=+2d # Set due date -bd update --defer="" # Clear defer (show immediately) - -# Link discovered work -bd dep add --type discovered-from - -# Complete work -bd close --reason "Done" --json - -# Show dependency tree -bd dep tree - -# Get issue details -bd show --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 --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 --type discovered-from` -5. **Complete**: `bd close --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 -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. diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md index 987a39767..61a362471 100644 --- a/docs/CLAUDE.md +++ b/docs/CLAUDE.md @@ -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