beads-guard
Safe Beads workflow helper (warning-only). Use before bd sync/close/create toavoid JSONL conflicts. Ensures you are on a feature branch, up to date withorigin/master, and stages Beads files cleanly with Feature-Key commits.
When & Why to Use This Skill
Beads Guard is a specialized developer workflow helper designed to streamline the management of Beads database files within Git environments. It enhances Developer Experience (DX) by preventing common JSONL merge conflicts and enforcing version control best practices. By automating pre-commit checks, branch synchronization, and standardized metadata staging, it ensures a clean and traceable project history for teams using the Beads system.
Use Cases
- Conflict Prevention: Automatically synchronizing and staging .beads/issues.jsonl files to avoid recurring merge conflicts during collaborative development.
- Workflow Guardrails: Ensuring all database operations are performed on feature branches rather than the master branch to maintain codebase stability.
- Environment Cleanup: Automating the removal of stale socket locks and rebasing with origin/master to ensure the local environment is up-to-date before critical operations.
- Standardized Commits: Facilitating the creation of commits with mandatory Feature-Key trailers and agent metadata for better auditing and project management integration.
| name | beads-guard |
|---|---|
| description | | |
| tags | [beads, dx, guardrail] |
Beads Guard
Avoid recurring .beads/issues.jsonl conflicts and master commits.
How to run (manual steps)
# 0) Must be on a feature branch (not master)
git status -sb
# 1) Rebase to latest master
git fetch origin master
git rebase origin/master
# 2) Clear stale locks
rm -f .beads/bd.sock* || true
# 3) Pull Beads DB to JSONL
bd pull
# 4) Do your Beads op
# bd close <id> --reason "..."
# bd create "..." --type ... --priority ...
# bd sync
# 5) Stage Beads files
git add .beads/issues.jsonl .beads/deletions.jsonl 2>/dev/null || true
# 6) Commit with Feature-Key trailer (on feature branch)
git commit -m "beads: <summary>\n\nFeature-Key: <id>\nAgent: claude-code\nRole: backend-engineer"
# 7) Push/PR as normal
git push
Notes
- Warning-only flow; no hard blocks.
- If branch is behind master and Beads changed, rebase before committing.
- Keep Beads ops off master to avoid hook warnings.