From essentials
Provides Beads (bd CLI) reference for issue types, statuses, priorities, dependencies, hierarchies, and commands. Use when creating, editing, or managing git-backed beads issues via bd.
npx claudepluginhub gantisstorm/essentials-claude-code --plugin essentialsThis skill is limited to using the following tools:
Beads CLI (`bd`) reference from [Beads](https://github.com/steveyegge/beads). Use this when creating, editing, or managing beads issues.
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
Beads CLI (bd) reference from Beads. Use this when creating, editing, or managing beads issues.
Invoke /beads-schema before working with bd commands. Invoke /beads-schema validate to check that bd is initialized and working.
Beads is a git-backed issue tracker. Issues are stored as JSONL in .beads/ and sync via git. The CLI is bd.
Beads are typically created by /beads-converter from architectural plans (.claude/plans/*-plan.md). The pipeline:
/plan-creator (or /bug-plan-creator, /code-quality-plan-creator)
↓ writes
.claude/plans/{slug}-{hash5}-plan.md
↓ consumed by
/beads-converter <plan-path>
↓ runs
bd create (epic) + bd create (child tasks) + bd dep add
↓ stored in
.beads/beads.jsonl
↓ executed by
/beads-loop or /beads-swarm or ralph-tui
How plan sections map to bead fields:
| Plan Section | Bead Field | CLI Flag |
|---|---|---|
## Summary | Epic title + description | bd create "Title" -t epic -d "..." |
## Files | One bead per file (typically) | bd create "Title" --parent <epic> |
### Requirements | Bead description (exit checklist) | -d "## Requirements\n..." |
### Reference Implementation | Bead description (full code) | -d "## Reference Implementation\n..." |
### Migration Pattern | Bead description (before/after) | -d "## Migration Pattern\n..." |
## Dependency Graph | Bead dependencies | bd dep add <child> <parent> |
## Exit Criteria | Bead description (exit criteria) | -d "## Exit Criteria\n..." |
Each bead's description must be 100% self-contained — the executor agent receives only the bead description, never the source plan. All code, requirements, and verification commands are copied verbatim from the plan into the bead.
| Type | Description |
|---|---|
task | General work item (default) |
bug | Bug report or defect |
feature | New feature or enhancement (enhancement is alias) |
chore | Maintenance or housekeeping |
epic | Large body of work spanning multiple issues |
| Status | Description |
|---|---|
open | Ready to work (default) |
in_progress | Currently being worked on |
blocked | Waiting on dependency |
deferred | Deliberately put on ice |
closed | Finished |
| Priority | Meaning |
|---|---|
| P0 | Critical |
| P1 | High |
| P2 | Medium (default) |
| P3 | Low |
| P4 | Backlog |
Supports both --priority 1 and --priority P1 formats.
Beads supports parent-child hierarchies via dotted IDs:
bd-a3f8 (Epic)bd-a3f8.1 (Task under epic)bd-a3f8.1.1 (Sub-task)Use --parent <epic-id> when creating to auto-generate child IDs.
# Create a task (default type)
bd create "Fix login bug" -p 1
# Create with type and parent
bd create "Add toggle switch" --type task --parent bd-a3f8
# Create epic
bd create "User Authentication" --type epic
# Full flags
bd create "Title" \
--type task \
--priority 1 \
--parent bd-a3f8 \
--description "Detailed description" \
--acceptance "Criteria for completion" \
--labels frontend,auth \
--deps bd-001,bd-002
Create flags:
| Flag | Short | Description |
|---|---|---|
--type | -t | Issue type (default: task) |
--priority | -p | Priority 0-4 or P0-P4 (default: 2) |
--parent | Parent issue ID (creates child) | |
--description | -d | Issue description |
--acceptance | Acceptance criteria | |
--design | Design notes | |
--notes | Additional notes | |
--labels | -l | Comma-separated labels |
--deps | Dependencies (format: id or type:id) | |
--assignee | -a | Assignee |
--id | Explicit issue ID | |
--due | Due date (+6h, tomorrow, 2025-01-15) | |
--defer | Hide from bd ready until date | |
--silent | Output only the issue ID | |
--json | JSON output |
# Update status
bd update bd-a3f8 --status in_progress
# Update multiple fields
bd update bd-a3f8 --title "New title" --priority 1 --description "Updated desc"
# Append to notes (vs replace)
bd update bd-a3f8 --append-notes "Additional context"
Do NOT use bd edit — it opens an interactive editor. Use bd update with flags instead.
# Close one or more issues
bd close bd-a3f8 --reason "Completed"
bd close bd-001 bd-002 bd-003 --reason "All done"
bd show bd-a3f8 # Human-readable
bd show bd-a3f8 --json # JSON output
bd list # All open issues
bd list --type epic # Only epics
bd list --parent bd-a3f8 # Children of epic
bd list --status open # Filter by status
bd list --label frontend # Filter by label
bd list --json # JSON output
bd ready # Tasks with no open blockers
bd ready --json # JSON output
Shows tasks that are open, have all dependencies resolved (closed/cancelled), and are not deferred.
# Add dependency: child depends on parent (child blocked until parent closes)
bd dep add bd-child bd-parent
# Dependency types
bd dep add bd-child bd-parent # Default: "blocks"
bd dep add bd-child bd-parent --type related # Non-blocking relation
# Remove dependency
bd dep remove bd-child bd-parent
Dependency types that block readiness:
| Type | Effect |
|---|---|
blocks | Child blocked until parent closes (default) |
parent-child | Auto-created via --parent flag |
Non-blocking dependency types: related, discovered-from, replies-to, relates-to, duplicates, supersedes
bd label add bd-a3f8 frontend
bd label remove bd-a3f8 frontend
bd sync # Export to JSONL, commit, pull, import, push
Always run bd sync after making changes to persist them.
bd ready selects tasks by:
status: openclosed/cancelled)defer_until)| Field | JSON key | Type | Required |
|---|---|---|---|
| ID | id | string | auto-generated |
| Title | title | string | yes (max 500 chars) |
| Description | description | string | no |
| Status | status | string | yes (default: open) |
| Priority | priority | int 0-4 | yes (default: 2) |
| Type | issue_type | string | yes (default: task) |
| Acceptance Criteria | acceptance_criteria | string | no |
| Design | design | string | no |
| Notes | notes | string | no |
| Assignee | assignee | string | no |
| Labels | labels | string[] | no |
| Dependencies | dependencies | object[] | no |
| Field | JSON key |
|---|---|
| Created | created_at |
| Updated | updated_at |
| Closed | closed_at |
| Created by | created_by |
| Close reason | close_reason |
# 1. Create epic
bd create "User Authentication" --type epic --json
# Returns: bd-a3f8
# 2. Add tasks as children
bd create "Login form" --type task --parent bd-a3f8 -p 1
bd create "Auth API" --type task --parent bd-a3f8 -p 1
bd create "Integration tests" --type task --parent bd-a3f8 -p 2
# 3. Add dependency (tests depend on form + API)
bd dep add bd-a3f8.3 bd-a3f8.1
bd dep add bd-a3f8.3 bd-a3f8.2
# 4. Check ready tasks
bd ready --json
bd update bd-a3f8.1 --status in_progress
# ... do work ...
bd close bd-a3f8.1 --reason "Login form implemented with validation"
bd sync
Parse $ARGUMENTS to determine mode.
$ARGUMENTS is validate:Check beads is set up and working:
# Check bd is installed
bd version
# Check beads is initialized
ls .beads/
# List all issues
bd list --json
# Check for ready tasks
bd ready --json
Report the beads version, issue count, and any issues.
$ARGUMENTS is empty:Output the quick reference:
Beads CLI (bd) Quick Reference
Types: task (default), bug, feature, chore, epic
Statuses: open, in_progress, blocked, deferred, closed
Priority: P0 (critical) → P4 (backlog), default P2
Create: bd create "Title" --type task -p 1 --parent <epic-id>
Update: bd update <id> --status in_progress
Close: bd close <id> --reason "Done"
Ready: bd ready --json
List: bd list --parent <epic-id> --json
Deps: bd dep add <child> <parent>
Sync: bd sync
Do NOT use "bd edit" (interactive). Use "bd update" with flags.