beads-guard

stars-end's avatarfrom stars-end

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.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 27, 2025
[Developer Tools]

When & Why to Use This Skill

Beads Guard is a specialized developer workflow assistant designed to maintain the integrity of Beads database files and prevent version control conflicts. It acts as a safety layer for Git-based workflows, ensuring that JSONL files are handled correctly, branches are kept up-to-date with the master, and commits are standardized with essential metadata like Feature-Keys and agent roles.

Use Cases

  • Conflict Prevention: Use this skill before performing 'bd sync', 'close', or 'create' operations to avoid recurring merge conflicts in .beads/issues.jsonl files.
  • Branch Hygiene Enforcement: Automatically verifies that development occurs on feature branches rather than the master branch, preventing accidental direct commits to protected branches.
  • Automated Rebase Workflow: Streamlines the process of fetching and rebasing from origin/master to ensure the local environment is synchronized before making changes.
  • Standardized Commit Metadata: Ensures all Beads-related commits include mandatory trailers such as Feature-Key, Agent, and Role for better traceability in project history.
  • Environment Maintenance: Automatically clears stale socket locks and pulls the latest Beads database state to ensure a clean and functional working environment.
namebeads-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.