# Instructions for using `bd` (Beads) **bd** (Beads) is a command-line tool for issue tracking. Run `bd prime` to get detailed instructions how to use Beads. ## Creating issues The simplest way to plan work is to add `epic` and `task` issues. And you need to create the correct dependencies between issues: - parent-child: `bd dep add CHILD_ID PARENT_ID --type parent-child` - blocking issues: `bd dep add BLOCKEE_ID BLOCKER_ID --type blocks` Use parent-child dependencies for tasks (or epics) that are grouped under a given epic. Use blocking dependencies for tasks (or epics) that cannot be worked on until the blocker is resolved. ## Finding issues to work on When you are asked to work on the next ready beads issue, follow these steps to identify the issue, and get it done: ```bash bd ready # Find available work bd show <id> # View issue details bd update <id> --status in_progress # Claim the issue ``` And once you get it done, follow these two steps to mark it as done: ```bash bd close <id> # Once you complete the work bd sync # Sync with git ``` ## Completing work **When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds (see step 3 below). **MANDATORY WORKFLOW:** 1. **File issues for remaining work** - Create issues for anything that needs follow-up, such as: `bd create "issue title" -d "issue description"` 2. **Update issue status** - Close finished work, updating in-progress items to closed: `bd close <id>` 3. **PUSH TO REMOTE** - This is MANDATORY: ```bash git pull --rebase git add <files> # add code changes bd sync # commit beads changes git commit -m "<commit message>" # commit code changes git push # mandatory push git status # MUST show "up to date with origin" ``` 4. **Clean up** - Clear stashes, prune remote branches 5. **Hand off** - Provide context for next session **CRITICAL RULES:** - Work is NOT complete until `git push` succeeds - Complete work as frequently as possible - ideally after every issue. - NEVER stop before pushing - that leaves work stranded locally - NEVER say "ready to push when you are" - YOU must push - If push fails, resolve and retry until it succeeds - NEVER create issues purely for testing; Any new capability must be added using TDD. - Use TDD to work on the tasks, using the following cycle of 3 steps: 1. Check if a test for the planned functionality already exists; If not, write the test. 2. Only once you have a failing test, start implementing the minimal code to pass the test. 3. If the passing tests fulfill all acceptance criteria of the task, you are done. If not, continue the cycle.