Files

Steve Yegge 19cd7d1887 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>

2025-10-12 11:25:29 -07:00

3.0 KiB

Raw Blame History

Security Policy

Reporting Security Issues

If you discover a security vulnerability in bd, please report it responsibly:

Email: security@steveyegge.com (or open a private security advisory on GitHub)

Please include:

Description of the vulnerability
Steps to reproduce
Potential impact
Suggested fix (if any)

We will respond within 48 hours and work with you to address the issue.

Security Considerations

Database Security

bd stores issue data locally in:

SQLite databases (.beads/*.db) - local only, gitignored
JSONL files (.beads/issues.jsonl) - committed to git

Important:

Do not store sensitive information (passwords, API keys, secrets) in issue descriptions or metadata
Issue data is committed to git and will be visible to anyone with repository access
bd does not encrypt data at rest (it's a local development tool)

Git Workflow Security

bd uses standard git operations (no custom protocols)
Export/import operations read and write local files only
No network communication except through git itself
Git hooks (if used) run with your local user permissions

Command Injection Protection

bd uses parameterized SQL queries to prevent SQL injection. However:

Do not pass untrusted input directly to bd commands
Issue IDs are validated against the pattern ^[a-z0-9-]+$
File paths are validated before reading/writing

Dependency Security

bd has minimal dependencies:

Go standard library
SQLite (via modernc.org/sqlite - pure Go implementation)
Cobra CLI framework

All dependencies are regularly updated. Run go mod verify to check integrity.

Supported Versions

We provide security updates for:

Version	Supported
main	✅
< 1.0	❌

Once version 1.0 is released, we will support the latest major version and one previous major version.

Best Practices

Don't commit secrets - Never put API keys, passwords, or credentials in issue descriptions
Review before export - Check .beads/issues.jsonl before committing sensitive project details
Use private repos - If your issues contain proprietary information, use private git repositories
Validate git hooks - If using automated export/import hooks, review them for safety
Regular updates - Keep bd updated to the latest version: go install github.com/steveyegge/beads/cmd/bd@latest

Known Limitations

bd is designed for development/internal use, not production secret management
Issue data is stored in plain text (both SQLite and JSONL)
No built-in encryption or access control (relies on filesystem permissions)
No audit logging beyond git history

For sensitive workflows, consider using bd only for non-sensitive task tracking.

Security Updates

Security updates will be announced via:

GitHub Security Advisories
Release notes on GitHub
Git commit messages (tagged with [security])

Subscribe to the repository for notifications.

3.0 KiB Raw Blame History