Prepare for public launch: comprehensive examples, docs, and tooling
This commit adds everything needed for a successful public launch: **New Documentation** - SECURITY.md: Security policy and best practices - CLAUDE.md: Complete agent instructions for contributing to beads - Enhanced README with pain points, FAQ, troubleshooting sections - Added Taskwarrior to comparison table with detailed explanation **Installation** - install.sh: One-liner installation script with platform detection - Auto-detects OS/arch, tries go install, falls back to building from source - Updated README with prominent installation instructions **Examples** (2,268+ lines of working code) - examples/python-agent/: Full Python implementation of agent workflow - examples/bash-agent/: Shell script agent with colorized output - examples/git-hooks/: Pre-commit, post-merge, post-checkout hooks with installer - examples/claude-desktop-mcp/: Documentation for future MCP server integration - examples/README.md: Overview of all examples **Dogfooding** - Initialized bd in beads project itself (.beads/beads.db) - Created issues for roadmap (MCP server, migrations, demos, 1.0 milestone) - Exported to .beads/issues.jsonl for git versioning **Visual Assets** - Added screenshot showing agent using beads to README intro - Placed in .github/images/ following GitHub conventions This addresses all launch readiness items: ✅ Security policy ✅ Working agent examples (Python, Bash) ✅ Git hooks for automation ✅ FAQ addressing skeptics ✅ Troubleshooting common issues ✅ Easy installation ✅ Dogfooding our own tool ✅ Pain points that create urgency Ready to ship! 🚀 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
225
CLAUDE.md
Normal file
225
CLAUDE.md
Normal file
@@ -0,0 +1,225 @@
|
||||
# Instructions for AI Agents Working on Beads
|
||||
|
||||
## Project Overview
|
||||
|
||||
This is **beads** (command: `bd`), an issue tracker designed for AI-supervised coding workflows. We dogfood our own tool!
|
||||
|
||||
## Issue Tracking
|
||||
|
||||
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
|
||||
|
||||
# Create new issue
|
||||
bd create "Issue title" -t bug|feature|task -p 0-4 -d "Description" --json
|
||||
|
||||
# Update issue status
|
||||
bd update <id> --status in_progress --json
|
||||
|
||||
# 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
|
||||
```
|
||||
|
||||
### Workflow
|
||||
|
||||
1. **Check for ready work**: Run `bd ready` to see what's unblocked
|
||||
2. **Claim your task**: `bd update <id> --status in_progress`
|
||||
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"`
|
||||
6. **Export**: Run `bd export -o .beads/issues.jsonl` before committing
|
||||
|
||||
### 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**: 1.21+
|
||||
- **Linting**: `golangci-lint run ./...` (baseline warnings documented in LINTING.md)
|
||||
- **Testing**: All new features need tests (`go test ./...`)
|
||||
- **Documentation**: Update relevant .md files
|
||||
|
||||
### File Organization
|
||||
|
||||
```
|
||||
beads/
|
||||
├── cmd/bd/ # CLI commands
|
||||
├── internal/
|
||||
│ ├── types/ # Core data types
|
||||
│ └── storage/ # Storage layer
|
||||
│ └── sqlite/ # SQLite implementation
|
||||
├── examples/ # Integration examples
|
||||
└── *.md # Documentation
|
||||
```
|
||||
|
||||
### Before Committing
|
||||
|
||||
1. **Run tests**: `go test ./...`
|
||||
2. **Run linter**: `golangci-lint run ./...` (ignore baseline warnings)
|
||||
3. **Export issues**: `bd export -o .beads/issues.jsonl`
|
||||
4. **Update docs**: If you changed behavior, update README.md or other docs
|
||||
5. **Git add both**: `git add .beads/issues.jsonl <your-changes>`
|
||||
|
||||
### Git Workflow
|
||||
|
||||
```bash
|
||||
# Make changes
|
||||
git add <files>
|
||||
|
||||
# Export beads issues
|
||||
bd export -o .beads/issues.jsonl
|
||||
git add .beads/issues.jsonl
|
||||
|
||||
# Commit
|
||||
git commit -m "Your message"
|
||||
|
||||
# After pull
|
||||
git pull
|
||||
bd import -i .beads/issues.jsonl # Sync SQLite cache
|
||||
```
|
||||
|
||||
Or use the git hooks in `examples/git-hooks/` for automation.
|
||||
|
||||
## Current Project Status
|
||||
|
||||
Run `bd stats` to see overall progress.
|
||||
|
||||
### Active Areas
|
||||
|
||||
- **Core CLI**: Mature, but always room for polish
|
||||
- **Examples**: Growing collection of agent integrations
|
||||
- **Documentation**: Comprehensive but can always improve
|
||||
- **MCP Server**: Planned (see bd-5)
|
||||
- **Migration Tools**: Planned (see bd-6)
|
||||
|
||||
### 1.0 Milestone
|
||||
|
||||
We're working toward 1.0. Key blockers tracked in bd. Run:
|
||||
```bash
|
||||
bd dep tree bd-8 # Show 1.0 epic dependencies
|
||||
```
|
||||
|
||||
## 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. Update schema in `internal/storage/sqlite/schema.go`
|
||||
2. Add migration if needed
|
||||
3. Update `internal/types/types.go` if new types
|
||||
4. Implement in `internal/storage/sqlite/sqlite.go`
|
||||
5. Add tests
|
||||
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, TEXT_FORMATS.md, EXTENDING.md
|
||||
- Create an issue if unsure: `bd create "Question: ..." -t task -p 2`
|
||||
|
||||
## Important Files
|
||||
|
||||
- **README.md** - Main documentation (keep this updated!)
|
||||
- **EXTENDING.md** - Database extension guide
|
||||
- **TEXT_FORMATS.md** - JSONL format analysis
|
||||
- **CONTRIBUTING.md** - Contribution guidelines
|
||||
- **SECURITY.md** - Security policy
|
||||
|
||||
## 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?"
|
||||
- Export to JSONL before committing (or use git hooks)
|
||||
- Use `bd dep tree` to understand complex dependencies
|
||||
- Priority 0-1 issues are usually more important than 2-4
|
||||
|
||||
## Building and Testing
|
||||
|
||||
```bash
|
||||
# Build
|
||||
go build -o bd ./cmd/bd
|
||||
|
||||
# Test
|
||||
go test ./...
|
||||
|
||||
# Test with coverage
|
||||
go test -coverprofile=coverage.out ./...
|
||||
go tool cover -html=coverage.out
|
||||
|
||||
# Run locally
|
||||
./bd init --prefix test
|
||||
./bd create "Test issue" -p 1
|
||||
./bd ready
|
||||
```
|
||||
|
||||
## 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! 🔗
|
||||
Reference in New Issue
Block a user