Problem
SKILL.md never states that beads live on the tbd-sync branch, and its one sentence about branches points the other way. An agent reading only the skill reasonably concludes that bead state is committed alongside its code.
The single branch-related line in the skill is:
Note: Never gitignore .tbd/workspaces/; the outbox must be committed to your working branch. See tbd guidelines tbd-sync-troubleshooting for details.
That is true and useful, but it is about .tbd/workspaces/ specifically. Read by an agent that does not already know the storage model, "the outbox must be committed to your working branch" reads as "bead state goes on your branch."
The README is clear about this:
- Git-native: Beads live in your repo, synced to a separate, dedicated
tbd-sync branch. Your code history stays clean—no bead churn polluting your logs.
But agents load SKILL.md, not README.md, and the two never meet. Meanwhile tbd-sync appears in agent-facing docs only inside tbd guidelines tbd-sync-troubleshooting, and only as failure symptoms ("Push permissions not granted for tbd-sync branch", "Commits not going to tbd-sync branch") — which require already knowing the model in order to parse.
How it surfaced
Working through a large feature branch, I created 8 beads, closed 7, and retitled 1, then verified before opening a PR that all my work was on that PR. git status showed nothing under .tbd/ beyond a pre-existing config.yml change, and no bead updates appeared in the branch's commits. Reasoning only from SKILL.md, that looked like the bead work had been lost or stranded.
It had not — tbd sync had pushed it to tbd-sync exactly as designed, which tbd sync --status confirmed. But confirming it meant reading .tbd/.gitignore, then tbd-sync-troubleshooting, then the README. One sentence in the skill would have answered it immediately, and an agent that did not dig would have reported the state wrongly to its user.
This also matters for PR review: a reviewer looking at the PR sees the code and the spec, and does not see bead state. That is the correct design, and it is worth the skill saying so, because it changes what an agent should claim about "everything is on this PR."
Suggested change
In packages/tbd/docs/shortcuts/system/skill-baseline.md (the generator for .claude/skills/tbd/SKILL.md and .agents/skills/tbd/SKILL.md), extend the existing note. Current text, around line 136:
**Note:** Never gitignore `.tbd/workspaces/`; the outbox must be committed to your
working branch. See `tbd guidelines tbd-sync-troubleshooting` for details.
Suggested replacement:
**Note:** Beads live on a separate, dedicated `tbd-sync` branch, not on your working
branch — `tbd sync` pushes them there, so bead changes never appear in your code
commits or in a PR diff. The one exception is `.tbd/workspaces/` (the outbox), which
must be committed to your working branch, so never gitignore it.
See `tbd guidelines tbd-sync-troubleshooting` for details.
This keeps the existing rule intact, states the model the README already documents, and names the consequence an agent needs when reporting on a branch or PR.
Happy to send a PR if the wording looks right.
Problem
SKILL.mdnever states that beads live on thetbd-syncbranch, and its one sentence about branches points the other way. An agent reading only the skill reasonably concludes that bead state is committed alongside its code.The single branch-related line in the skill is:
That is true and useful, but it is about
.tbd/workspaces/specifically. Read by an agent that does not already know the storage model, "the outbox must be committed to your working branch" reads as "bead state goes on your branch."The README is clear about this:
But agents load
SKILL.md, notREADME.md, and the two never meet. Meanwhiletbd-syncappears in agent-facing docs only insidetbd guidelines tbd-sync-troubleshooting, and only as failure symptoms ("Push permissions not granted for tbd-sync branch", "Commits not going to tbd-sync branch") — which require already knowing the model in order to parse.How it surfaced
Working through a large feature branch, I created 8 beads, closed 7, and retitled 1, then verified before opening a PR that all my work was on that PR.
git statusshowed nothing under.tbd/beyond a pre-existingconfig.ymlchange, and no bead updates appeared in the branch's commits. Reasoning only fromSKILL.md, that looked like the bead work had been lost or stranded.It had not —
tbd synchad pushed it totbd-syncexactly as designed, whichtbd sync --statusconfirmed. But confirming it meant reading.tbd/.gitignore, thentbd-sync-troubleshooting, then the README. One sentence in the skill would have answered it immediately, and an agent that did not dig would have reported the state wrongly to its user.This also matters for PR review: a reviewer looking at the PR sees the code and the spec, and does not see bead state. That is the correct design, and it is worth the skill saying so, because it changes what an agent should claim about "everything is on this PR."
Suggested change
In
packages/tbd/docs/shortcuts/system/skill-baseline.md(the generator for.claude/skills/tbd/SKILL.mdand.agents/skills/tbd/SKILL.md), extend the existing note. Current text, around line 136:Suggested replacement:
This keeps the existing rule intact, states the model the README already documents, and names the consequence an agent needs when reporting on a branch or PR.
Happy to send a PR if the wording looks right.