Use for advanced bd operations - splitting tasks mid-flight, merging duplicates, changing dependencies, archiving epics, querying metrics, cross-epic dependencies
/plugin marketplace add withzombies/hyperpowers/plugin install withzombies-hyper@withzombies-hyperThis skill inherits all available tools. When active, it can use any tool Claude has access to.
resources/metrics-guide.mdresources/task-naming-guide.md<skill_overview> Advanced bd operations for managing complex task structures; bd is single source of truth, keep it accurate. </skill_overview>
<rigidity_level> HIGH FREEDOM - These are operational patterns, not rigid workflows. Adapt operations to your specific situation while following the core principles (keep bd accurate, merge don't delete, document changes). </rigidity_level>
<quick_reference>
| Operation | When | Key Command |
|---|---|---|
| Split task | Task too large mid-flight | Create subtasks, add deps, close parent |
| Merge duplicates | Found duplicate tasks | Combine designs, move deps, close with reference |
| Change dependencies | Dependencies wrong/changed | bd dep remove then bd dep add |
| Archive epic | Epic complete, hide from views | bd close bd-X --reason "Archived" |
| Query metrics | Need status/velocity data | bd list + filters + wc -l |
| Cross-epic deps | Task depends on other epic | bd dep add works across epics |
| Bulk updates | Multiple tasks need same change | Loop with careful review first |
| Recover mistakes | Accidentally closed/wrong dep | bd update --status or bd dep remove |
Core principle: Track all work in bd, update as you go, never batch updates. </quick_reference>
<when_to_use> Use this skill for advanced bd operations:
For basic operations: See skills/common-patterns/bd-commands.md (create, show, close, update) </when_to_use>
<operations> ## Operation 1: Splitting Tasks Mid-FlightWhen: Task in-progress but turns out too large.
Example: Started "Implement authentication" - realize it's 8+ hours of work across multiple areas.
Process:
# Original task bd-5 is in-progress
# Already completed: Login form
# Remaining work gets split:
bd create "Auth API endpoints" --type task --priority P1 --design "
POST /api/login and POST /api/logout endpoints.
## Success Criteria
- [ ] POST /api/login validates credentials, returns JWT
- [ ] POST /api/logout invalidates token
- [ ] Tests pass
"
# Returns bd-12
bd create "Session management" --type task --priority P1 --design "
JWT token tracking and validation.
## Success Criteria
- [ ] JWT generated on login
- [ ] Tokens validated on protected routes
- [ ] Token expiration handled
- [ ] Tests pass
"
# Returns bd-13
bd create "Password hashing" --type task --priority P1 --design "
Secure password hashing with bcrypt.
## Success Criteria
- [ ] Passwords hashed before storage
- [ ] Hash verification on login
- [ ] Tests pass
"
# Returns bd-14
# Password hashing must be done first
# API endpoints depend on password hashing
bd dep add bd-12 bd-14 # bd-12 depends on bd-14
# Session management depends on API endpoints
bd dep add bd-13 bd-12 # bd-13 depends on bd-12
# View tree
bd dep tree bd-5
bd edit bd-5 --design "
Implement user authentication.
## Status
✓ Login form completed (frontend)
✗ Remaining work split into subtasks:
- bd-14: Password hashing (do first)
- bd-12: Auth API endpoints (depends on bd-14)
- bd-13: Session management (depends on bd-12)
## Success Criteria
- [x] Login form renders
- [ ] See subtasks for remaining criteria
"
bd close bd-5 --reason "Split into bd-12, bd-13, bd-14"
bd ready # Shows bd-14 (no dependencies)
bd update bd-14 --status in_progress
# Complete bd-14...
bd close bd-14
# Now bd-12 is unblocked
bd ready # Shows bd-12
When: Discovered two tasks are same thing.
Example:
bd-7: "Add email validation"
bd-9: "Validate user email addresses"
^ Duplicates
Based on:
Example: Keep bd-7 (more complete)
bd show bd-7
bd show bd-9
# Combine into bd-7
bd edit bd-7 --design "
Add email validation to user creation and update.
## Background
Originally tracked as bd-7 and bd-9 (now merged).
## Success Criteria
- [ ] Email validated on creation
- [ ] Email validated on update
- [ ] Rejects invalid formats
- [ ] Rejects empty strings
- [ ] Tests cover all cases
## Notes from bd-9
Need validation on update, not just creation.
"
# Check bd-9 dependencies
bd show bd-9
# If bd-10 depended on bd-9, update to bd-7
bd dep remove bd-10 bd-9
bd dep add bd-10 bd-7
bd edit bd-9 --design "DUPLICATE: Merged into bd-7
This task was duplicate of bd-7. All work tracked there."
bd close bd-9
When: Dependencies were wrong or requirements changed.
Example: bd-10 depends on bd-8 and bd-9, but bd-9 got merged and bd-10 now also needs bd-11.
# Remove obsolete dependency
bd dep remove bd-10 bd-9
# Add new dependency
bd dep add bd-10 bd-11
# Verify
bd dep tree bd-1 # If bd-10 in epic bd-1
bd show bd-10 | grep "Blocking"
Common scenarios:
When: Epic complete, want to hide from default views but keep history.
# Verify all tasks closed
bd list --parent bd-1 --status open
# Output: [empty] = all closed
# Archive epic
bd close bd-1 --reason "Archived - completed Oct 2025"
# Won't show in open listings
bd list --status open # bd-1 won't appear
# Still accessible
bd show bd-1 # Still shows full epic
Use archived for: Completed epics, shipped features, historical reference Use open/in-progress for: Active work Use closed with note for: Cancelled work (explain why)
# Tasks closed this week
bd list --status closed | grep "closed_at" | grep "2025-10-" | wc -l
# Tasks closed by epic
bd list --parent bd-1 --status closed | wc -l
# Ready to work on
bd ready
bd ready | grep "^bd-" | wc -l
# All open tasks
bd list --status open | wc -l
# Blocked = open - ready
# Show tree
bd dep tree bd-1
# Total tasks in epic
bd list --parent bd-1 | grep "^bd-" | wc -l
# Completed tasks
bd list --parent bd-1 --status closed | grep "^bd-" | wc -l
# Percentage = (completed / total) * 100
For detailed metrics guidance: See resources/metrics-guide.md
When: Task in one epic depends on task in different epic.
Example:
Epic bd-1: User Management
- bd-10: User CRUD API
Epic bd-2: Order Management
- bd-20: Order creation (needs user API)
# Add cross-epic dependency
bd dep add bd-20 bd-10
# bd-20 (in bd-2) depends on bd-10 (in bd-1)
# Check dependencies
bd show bd-20 | grep "Blocking"
# Check ready tasks
bd ready
# Won't show bd-20 until bd-10 closed
Best practices:
When: Need to update multiple tasks.
Example: Mark all test tasks closed after suite complete.
# Get tasks
bd list --parent bd-1 --status open | grep "test:" > test-tasks.txt
# Review list
cat test-tasks.txt
# Update each
while read task_id; do
bd close "$task_id"
done < test-tasks.txt
# Verify
bd list --parent bd-1 --status open | grep "test:"
Use bulk for:
Never bulk:
bd update bd-15 --status open
# Or if was in progress
bd update bd-15 --status in_progress
bd dep remove bd-10 bd-8 # Remove wrong
bd dep add bd-10 bd-9 # Add correct
# bd has no undo, restore from git
git log -p -- .beads/issues.jsonl | grep -A 50 "bd-10"
# Find previous version, copy
bd edit bd-10 --design "[paste previous]"
bd close bd-9
<why_it_fails>
# Read BOTH tasks
bd show bd-7 # Only mentions validation on creation
bd show bd-9 # Mentions validation on update too
# Merge information
bd edit bd-7 --design "
Email validation for user creation and update.
## Background
Merged from bd-9.
## Success Criteria
- [ ] Validate on creation (from bd-7)
- [ ] Validate on update (from bd-9) ← Preserved!
- [ ] Tests for both cases
"
# Then close duplicate with reference
bd edit bd-9 --design "DUPLICATE: Merged into bd-7"
bd close bd-9
What you gain:
<why_it_fails>
# 3 hours in, stop and split
bd edit bd-15 --design "
Implement payment processing.
## Status
✓ Completed: Payment form UI (3 hours)
✗ Split remaining work into subtasks:
- bd-20: Stripe API integration
- bd-21: Payment validation
- bd-22: Retry logic
- bd-23: Receipt generation
"
bd close bd-15 --reason "Split into bd-20, bd-21, bd-22, bd-23"
# Create subtasks with dependencies
bd create "Stripe API integration" ... # bd-20
bd create "Payment validation" ... # bd-21
bd create "Retry logic" ... # bd-22
bd create "Receipt generation" ... # bd-23
bd dep add bd-21 bd-20 # Validation needs API
bd dep add bd-22 bd-20 # Retry needs API
bd dep add bd-23 bd-22 # Receipts after retry works
# Work on one at a time
bd update bd-20 --status in_progress
# Complete bd-20 (4 hours)
bd close bd-20
# Take break
# Next day: bd-21
What you gain:
bd create "Analytics API endpoints" ... # Creates bd-20
bd dep add bd-15 bd-20 # bd-15 now depends on bd-20 too
bd close bd-10
bd ready # Shows bd-15
bd update bd-15 --status in_progress
<why_it_fails>
# Create new API task
bd create "Analytics API endpoints" ... # bd-20
# Add dependency
bd dep add bd-15 bd-20
# UPDATE bd-15 to document new requirement
bd edit bd-15 --design "
Add analytics to dashboard.
## Dependencies
- bd-10: User dashboard (completed)
- bd-20: Analytics API endpoints (NEW - discovered during bd-10)
## Success Criteria
- [ ] Integrate with analytics API (bd-20)
- [ ] Display charts on dashboard
- [ ] Tests pass
"
# Close bd-10
bd close bd-10
# Check ready
bd ready # Does NOT show bd-15 (blocked on bd-20)
# Work on bd-20 first
bd update bd-20 --status in_progress
# Complete bd-20
bd close bd-20
# NOW bd-15 is truly ready
bd ready # Shows bd-15
What you gain:
<critical_rules>
All of these mean: STOP. Follow the operation properly.
<bd_best_practices> For detailed guidance on:
See: resources/task-naming-guide.md </bd_best_practices>
<red_flags> Watch for these patterns:
<verification_checklist> After advanced bd operations:
Can't check all boxes? Review operation and fix issues. </verification_checklist>
<integration> **This skill covers:** Advanced bd operationsFor basic operations:
Related skills:
CRITICAL: Use bd CLI commands, never read .beads/issues.jsonl directly.
</integration>
When stuck:
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.