$ show gastownhall/beads
Beads (bd) is a CLI-based issue tracking system designed for AI agents and developers, using Dolt as a version-controlled SQL database backend. It provides persistent, structured memory for coding agents through features like dependency tracking, workflow automation (molecules/formulas), and JSON output for scripting. The architecture features a modular Go design with clear separation between CLI, storage abstraction (supporting both embedded and server Dolt modes), workflow APIs, and extensibility systems. Key capabilities include issue lifecycle management, dependency graphs, blocking detection, telemetry, hook-based extensibility, and integrations with external trackers like Jira, GitHub, and Notion. The system emphasizes correctness through extensive conformance testing, transactional operations, and merge-safety mechanisms for distributed clones.
The LLM identified 5 files worth highlighting for reuse:
Implements the Unit of Work pattern with capability accessors that decouple application logic from storage specifics. Provides transaction management through interfaces like IssueReaderSource and RelationsSource, allowing storage operations to be swapped (embedded vs server Dolt) without changing business logic. Demonstrates non-obvious skill in designing storage abstractions that maintain ACID guarantees while enabling testability and flexibility.
Provides a robust hook system for executing user scripts on system events with timeout enforcement, process group isolation, and OpenTelemetry tracing. Allows extensibility without modifying core code, supporting lifecycle events like issue creation, updates, and deletions. Shows craftsmanship in handling edge cases like signal propagation, execution context isolation, and secure script execution while maintaining observability.
Implements a generic telemetry decorator that wraps storage operations to collect metrics and traces without modifying business logic. Demonstrates the wrapper pattern applied consistently across storage interfaces (issue operations, dependency queries, etc.) to provide observability. Reusable pattern that could be extracted to add instrumentation to any service interface with minimal coupling.
Implements a credential resolution system using the Chain of Responsibility pattern to fetch secrets from multiple sources (environment variables, files, executable outputs). Used for database authentication and external tracker integrations, allowing flexible deployment across environments. Shows skill in designing secure, configurable credential handling that supports both simple and complex secret retrieval scenarios while maintaining auditability.
Provides a framework for contract testing that verifies behavioral parity between different implementations of storage interfaces (e.g., embedded vs server Dolt). Defines conformance interfaces and test harnesses that ensure storage backends behave identically under various conditions. Demonstrates advanced testing practices that prevent drift between implementations and provide confidence during refactoring or migration.