| name | beadworker |
| description | Work a beads issue end-to-end — fetch, verify, claim, branch, implement, commit, and comment. Usage: /beadworker <id> |
beadworker
Beadworker Skill
Work a single beads issue from triage to committed code.
Arguments
args contains the issue ID (e.g. beads-abc).
Steps
Execute these steps in order. Stop and surface any blocker to the user before continuing.
1. Fetch the issue
Run bd show <id> --long --json and parse the result. Read the title, description, acceptance criteria, design, notes, dependencies, and status.
2. Verify the issue
Before claiming anything, assess whether the issue is workable:
- Title — clear and specific (not "fix bug" or "improve stuff")
- Description — explains why this issue exists and what needs to be done; enough context to implement without guessing
- Scope — implementable as a single focused change; not underspecified or impossibly large
- Dependencies — all blocking issues are closed (check
dependency_type: "blocks")
- No conflicting information — design decisions don't contradict the description
If the issue fails any check, do NOT proceed. Instead:
- Post a comment:
bd comment <id> --actor "Claude" "Verification failed: <specific reason>. Needs: <what is missing or unclear>."
- Report to the user what was wrong and stop.
If the issue needs clarification but is otherwise sound, do NOT proceed. Instead:
- Post a comment:
bd comment <id> --actor "Claude" "Question before starting: <specific question>"
- Report to the user and stop.
3. Claim the issue and enrich it
Once verified:
- Claim:
bd update <id> --claim
- Update acceptance criteria if not already precise:
bd update <id> --acceptance="<criteria>"
- Update design notes with your implementation approach:
bd update <id> --design="<approach>"
- Update notes with any constraints or decisions:
bd update <id> --notes="<notes>"
Keep these concise and factual — they are permanent record.
4. Checkout a branch and create a worktree
Derive a short kebab-case branch name from the issue title (e.g. fix-char-limit, add-dark-mode). Create it off main
and create a brand new worktree in ~/Projects/worktrees:
git worktree add -b <short-description> ~/Projects/worktrees/<short-description> main
cd ~/Projects/worktrees/<short-description>
npm install
Do all your work within the new worktree. Do not make changes in the main project directory.
5. Implement
Work the issue to completion. Follow all project conventions from CLAUDE.md:
- No TypeScript —
.js / .jsx only
- No comments unless the WHY is non-obvious
- No features beyond what the issue requires
- No test runner configured — validate via the dev server where applicable
Read the relevant source files before editing. Prefer editing existing files over creating new ones.
6. Format & Lint
Run npm run format to apply code formatting. Run npm run lint to check for linting errors. Repeat until all issues are resolved.
Do not disable linter rules or add exceptions. If the code doesn't fit the rules, it needs to be refactored until it does.
7. Commit
Stage any resulting changes together with your implementation changes.
Stage only the files changed for this issue. Write a conventional commit — no scope, no mention of the issue ID. Include a body if the change warrants calling out non-obvious details (e.g. a tricky workaround, a subtle invariant, why an approach was chosen over an alternative):
git commit -m "$(cat <<'EOF'
<type>: <imperative summary under 72 chars>
[optional body — only if details warrant it]
EOF
)"
Include Co-authored-by: trailers with the appropriate model name.
Valid types: feat, fix, refactor, chore, docs, style, test.
8. Leave a completion comment
bd comment <id> --actor "Claude" "Implemented and committed on branch <branch-name>. Ready for review."
Then report to the user: what was done, what branch, and the commit hash.
Important: Do NOT close the issue
Never run bd close <id> at the end of this skill. The issue stays open for human review and merge before closing.
