davdittrich/gsd-beads

Beads issue tracking for gsd-core's plan→execute→verify→ship lifecycle
What it does
gsd-core is an agentic planning framework that
turns a feature request into phased plans, tracked execution, and a ship gate, orchestrated
through lifecycle commands and markdown under a project's .planning/ directory.
Beads (bd) is a durable, git-native issue tracker
with a local Dolt database, issue dependencies, and blocker tracking, built for work that
has to survive multi-session handoff between people and agents.
gsd-beads is a gsd-core capability — an installable overlay, not a fork — that makes bd
the single source of truth for gsd's task state: one beads issue per plan task, task
dependencies become bd dep links, task completion closes its issue, and gsd's
planner/executor/ship gate all read live bd state instead of duplicating it as
hand-maintained .planning/ prose.
Why not just use gsd-core's built-in tracking?
gsd-core's .planning/ markdown is a good fit for plan *content* — what a phase is for, how a
task should be approached, what "done" means. It is a poor fit for task *state*. Without a
bridge, a developer who uses both trackers maintains two hand-written representations of the
same work by hand: every planned task gets re-typed as an issue, every finished task gets
closed twice, and the two drift silently because nothing compares them. gsd-beads makes bd
the single source of truth for task state, so no duplicated task-state bookkeeping survives in
.planning/.
| Need | .planning/ markdown | beads |
| :--- | :--- | :--- |
| Query "what can I work on now?" | read files, reason | bd ready |
| Dependencies and blocking | prose ordering | first-class, enforced |
| Status across phases | per-phase files | one query |
| Survives milestone archival | archived away | persists |
| Visible outside one project | no | yes |
| Machine-updatable without rewriting prose | no | yes |
Requirements
- bd >= 1.2.2 on PATH (check: bd --version). CI pins this version. An older bd prints one notice and is treated as unavailable; an unrecognised bd --version output is not.
- Python 3 (standard library only)
- gsd-core >= 1.11.0
The floor is 1.11.0: gsd-core 1.10 ship.md silently drops the whole ship:pre gate, and
onError: halt is honoured only from 1.11.0. The real reconciliation fixture and CI separately
pin public gsd-core 1.12.0 as the current runtime identity; that current-runtime gate does not
raise the declared floor.
Install
Claude Code:
Codex CLI: pin the marketplace to a release tag rather than tracking main.
codex plugin marketplace upgrade force-reinstalls every configured plugin's
cache on *any* new commit to the tracked ref, not just commits touching that
plugin — an unpinned main ref means an unrelated doc commit here can
invalidate a live session's plugin cache mid-run (davdittrich/gsd-beads#8,
root cause upstream in openai/codex#31383).
Bump --ref to the latest tag from git tag --sort=-creatordate | head -1 when upgrading.
Example workflow
The capability is on by default: beads.enabled defaults to true, so a fresh install runs
with issue tracking on. Opt out by setting beads.enabled: false in the project's
.planning/config.json — every step below checks that gate first and no-ops when a project has
opted out (a skill prints a notice; the hook path stays silent). See Configuration below for the full key
list.
gsd-core's own lifecycle commands drive bd state directly:
1. /gsd:plan-phase — before planning, beads-recall queries existing open issues so
already-ticketed work isn't planned twice; after the plan is written, beads-sync creates
one phase epic plus one bd issue per plan-task block, and writes the ids back into the plan
(a beads_epic frontmatter key and a element per task).
2. /gsd:execute-phase — before a wave of tasks runs, beads-status puts that wave's live
issue state into the orchestrator's context; after the wave finishes, it closes the bd
issues of every completed plan in the phase (complete = SUMMARY.md exists and its top-level
status is complete or absent; halted, blocked, incomplete, an unknown or an empty
value is not complete).
3. /gsd:verify-work — after verification, beads-status regenerates the projected BEADS.md
from live bd state (read-only: it closes nothing).
4. Shipping — immediately before ship, two blocking gates read BEADS.md frontmatter and