Skill v1.0.1

currentAutomated scan100/100

gantisstorm/essentials-claude-code/beads-schema

1 files

──Details

PublishedOctober 28, 2026 at 06:11 AM

Content Hashsha256:4f9369e07238dca1...

Git SHA8caeb0ca2ce8

Bump Typepatch

Compare with v1.0.0

──Files

Files (1 file, 9.0 KB)

SKILL.md9.0 KBactive

SKILL.md · 341 lines · 9.0 KB

name: beads-schema description: Beads (bd CLI) reference — issue types, statuses, priorities, dependencies, and common commands allowed-tools: Bash, Read, Write, Edit argument-hint: "[validate]" metadata: version: "1.0.1"

Beads CLI (bd) reference from Beads. Use this when creating, editing, or managing beads issues.

When to Use

Invoke /beads-schema before working with bd commands. Invoke /beads-schema validate to check that bd is initialized and working.

Core Concepts

Beads is a git-backed issue tracker. Issues are stored as JSONL in .beads/ and sync via git. The CLI is bd.

Conversion from Plans

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.

Issue Types (core)

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

Statuses

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 (0-4, lower = higher)

Priority	Meaning
P0	Critical
P1	High
P2	Medium (default)
P3	Low
P4	Backlog

Supports both --priority 1 and --priority P1 formats.

Hierarchical IDs

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.

Essential Commands

Create

bash

# 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

bash

# 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

bash

# Close one or more issues
bd close bd-a3f8 --reason "Completed"
bd close bd-001 bd-002 bd-003 --reason "All done"

Show

bash

bd show bd-a3f8          # Human-readable
bd show bd-a3f8 --json   # JSON output

List

bash

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

Ready

bash

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.

Dependencies

bash

# 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

Labels

bash

bd label add bd-a3f8 frontend
bd label remove bd-a3f8 frontend

Sync

bash

bd sync   # Export to JSONL, commit, pull, import, push

Always run bd sync after making changes to persist them.

Task Selection Order

bd ready selects tasks by:

Filter to status: open
Filter to tasks with all blocking dependencies resolved (closed/cancelled)
Filter out deferred tasks (past defer_until)
Sort by priority (P0 first)
Return matches

Issue Fields Reference

Core fields (used by essentials commands)

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

Timestamp fields (auto-managed)

Field	JSON key
Created	`created_at`
Updated	`updated_at`
Closed	`closed_at`
Created by	`created_by`
Close reason	`close_reason`

Common Workflows

Create epic with tasks

bash

# 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

Work on a task

bash

bd update bd-a3f8.1 --status in_progress
# ... do work ...
bd close bd-a3f8.1 --reason "Login form implemented with validation"
bd sync

Instructions

Parse $ARGUMENTS to determine mode.

If `$ARGUMENTS` is `validate`:

Check beads is set up and working:

bash

# 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.

If `$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.

← v1.0.0 All versions

Skill v1.0.1

When to Use

Core Concepts

Conversion from Plans

Issue Types (core)

Statuses

Priority (0-4, lower = higher)

Hierarchical IDs

Essential Commands

Create

Update

Close

Show

List

Ready

Dependencies

Labels

Sync

Task Selection Order

Issue Fields Reference

Core fields (used by essentials commands)

Timestamp fields (auto-managed)

Common Workflows

Create epic with tasks

Work on a task

Instructions

If $ARGUMENTS is validate:

If $ARGUMENTS is empty:

If `$ARGUMENTS` is `validate`:

If `$ARGUMENTS` is empty: