using-beadslisted

# Using Beads ## Overview **Core principle:** In any git-hosted work, track it in **beads** — continuously, not as an afterthought. `bd` is a git-native, dependency-aware issue tracker. Every task, deferred TODO, discovered bug, and follow-up becomes a bead, so nothing is lost between sessions, ready-vs-blocked work is always visible, and parallel agents (you, Codex, a future session) share one work-list. **The rule here is: always, and frequently.** If you catch yourself holding a work item only in your head or buried in a `// TODO` comment, that is the signal — **make it a bead now.** **Beads vs. the harness todo list:** the in-session todo list is ephemeral scratch for *this* turn; beads is the **durable, git-shared, cross-session** record. Use beads for anything that outlives the current train of thought or that another agent might pick up. ## The Habit ### At the start of any git-hosted activity ```bash bd ready # what's unblocked and claimable right now? bd status # database overview, if you want the lay of the land ``` If the repo has no beads yet: `bd init` (fresh repo) or `bd bootstrap` (fresh clone of a repo that already uses beads). Run `bd prime` any time you want the full, up-to-date agent workflow. ### Capture the moment work appears Don't defer capture. The builder's "write it down, don't do it" and the whittler's "that's out of scope" **are bead-creating moments**: ```bash bd create "Handle the empty-input edge case" -t task -p