Task Management with Beads (bd)
Relevant source files
The following files were used as context for generating this wiki page:
Beads (bd) is the issue tracking system for the flext-quality repository. It replaces traditional TODO lists and external trackers with a local, Git-integrated database for managing project tasks and persistent knowledge. Sources: CLAUDE.md:12-17, AGENTS.md:53-58
System Architecture
The Beads architecture utilizes a local Dolt database to store all issue data. This database synchronizes with the project's Git remote using the refs/dolt/data reference. A passive export of the issue state is maintained in the .beads/issues.jsonl file. Sources: CLAUDE.md:31-34, AGENTS.md:72-75
Data Synchronization Flow
This diagram illustrates how issue data moves between the local environment and the remote repository.
The flow ensures that issue data remains versioned alongside source code while allowing for structured database queries. Sources: CLAUDE.md:31-34, AGENTS.md:72-75
Command Reference
The bd CLI provides several commands to manage the lifecycle of an issue or "bead."
| Command | Description |
|---|---|
bd prime | Refreshes the full workflow context and command reference. |
bd ready | Lists available work and unassigned issues. |
bd show <id> | Displays detailed information for a specific issue. |
bd update <id> --claim | Assigns a specific issue to the current agent or user. |
bd close <id> | Marks an issue as completed. |
bd remember | Stores persistent knowledge within the Beads system. |
Sources: CLAUDE.md:20-27, AGENTS.md:61-69, AGENTS.md:144-152
Agent Context Profiles
Beads defines specific profiles that govern how automated agents interact with task tracking and Git operations.
Profile Definitions
- Conservative (Default): Uses
bdfor tracking. It avoids runninggit commit,git push, or Dolt remote sync unless explicitly requested. - Minimal: Functions as a pointer to
bd prime. It follows the same strict Git policies as the Conservative profile. - Team-maintainer: Opt-in profile for specific repositories. It permits agents to close beads, run quality gates, commit, and push during session closure.
Sources: CLAUDE.md:38-46, AGENTS.md:79-87
Session Completion Protocol
The project enforces a specific protocol when ending an implementation workflow. This protocol ensures all work is tracked and validated before handoff.
This sequence ensures that no work remains undocumented and that the code passes all defined quality standards. Sources: CLAUDE.md:52-70, AGENTS.md:93-112
Mandatory Completion Steps
- File remaining work: Create new beads for any follow-up tasks discovered during development.
- Run quality gates: Execute
make checkandmake testto validate code changes. - Update status: Close completed beads and update in-progress items.
- Sync data: Report Git status and, if using the Team-maintainer profile, perform
git pushandbd dolt push. - Handoff: Provide a summary of changes, validation results, and issue status.
Sources: CLAUDE.md:56-74, AGENTS.md:97-116, README.md:66-68
Quality Integration
Beads tasks often require passing the repository's quality gates before closure. The flext-quality module map and governance rules provide the canonical pre-change checklist. Sources: README.md:21-25, README.md:61-64
- Pre-requisites: Skills loading, zero-debt baseline, and slot registry verification.
- Quality Gates: Mandatory execution of
make check(Ruff, basedpyright, Bandit) andmake test(pytest, coverage).
Sources: README.md:33-37, README.md:66-68, AGENTS.md:32-34
Summary
Task management with Beads (bd) provides a decentralized, database-driven approach to issue tracking within the flext-quality project. By integrating directly with Dolt and Git, it ensures that project tasks, persistent memory, and code changes remain synchronized and enforceable through automated agent profiles and quality gates. Sources: CLAUDE.md:12-34, AGENTS.md:53-75