What I Do

• Create new issues with proper descriptions and metadata

• Edit existing issue descriptions and fields

• Update issue states and progress

• Manage issue dependencies and relationships

• Label and categorize issues appropriately

• Add comments and context to issues

• Move issues between rigs/projects when needed

When to Use Me

Use this skill when you need to:

• Create a new task or issue with full context

• Update an existing issue's description or details

• Change an issue's state (open, in-progress, closed, etc.)

• Add or modify dependencies between issues

• Label issues for better organization

• Add comments to provide updates or context

• Split or reorganize work items

Git + JSONL: How bd Works

No database servers. No cloud APIs. Just Git + JSONL.

All issues live in .beads/issues.jsonl — a simple JSON Lines file that git tracks like any other code. This means:

• Pull → see updates: git pull brings down everyone's issue changes

• Push → share yours: git push publishes your issue updates to the team

• Merge conflicts are possible: If two people edit the same issue simultaneously, you'll get a classic git merge conflict (just like with code)

• Hash IDs reduce conflicts: Every issue has a unique hash ID, making simultaneous edits on different issues seamless

This is version control for your project management — fully distributed, offline-capable, and conflict-aware.

bd Commands to Use

Create a New Issue

bd create --title "<title>" --type <type> [--description "<description>"]

Creates a new issue. Common types: task, bug, feature, epic

Create from Markdown File

bd create --file <path-to-markdown>

Creates issues from a markdown file (useful for bulk creation).

Interactive Create

bd create-form

Creates an issue using an interactive form in your $EDITOR.

Quick Capture

bd q --title "<title>"

Quickly create an issue and output only the ID (useful for scripts).

Edit an Issue

bd edit <issue-id>

Opens the issue in $EDITOR to modify fields.

Update Specific Fields

bd update <issue-id> --title "<new-title>" bd update <issue-id> --description "<new-description>" bd update <issue-id> --type <new-type>

Update individual fields without opening an editor.

Set State

bd set-state <issue-id> <state>

Set operational state (creates event + updates label). States: open, in_progress, closed, etc.

Close/Reopen Issues

bd close <issue-id> [<issue-id>...] bd reopen <issue-id> [<issue-id>...]

Manage Dependencies

bd dep add <issue-id> <depends-on-issue-id> bd dep remove <issue-id> <depends-on-issue-id> bd dep list <issue-id>

Add Labels

bd label add <issue-id> <label> bd label remove <issue-id> <label>

Add Comments

bd comments add <issue-id> "<comment-text>"

View Issue Details

bd show <issue-id>

Show full issue details including description, state, dependencies, comments.

Move Issues Between Rigs

bd move <issue-id> <target-rig>

Move an issue to a different rig with automatic dependency remapping.

Mark as Duplicate

bd duplicate <issue-id> <original-issue-id>

Supersede an Issue

bd supersede <old-issue-id> <new-issue-id>

Mark an issue as superseded by a newer one.

Workflow for Creating Issues

• Define the work: Determine title, type, and description

• Create the issue: Use bd create or bd create-form

• Set dependencies: Use bd dep add to establish relationships

• Add labels: Use bd label add for categorization

• Verify: Use bd show to confirm everything is correct

Workflow for Modifying Issues

• View current state: Use bd show <issue-id> to see existing details

• Make changes: Use bd edit for complex changes or bd update for simple field updates

• Update state: Use bd set-state when work progresses

• Add context: Use bd comments add to document decisions or progress

• Sync: Changes auto-sync to JSONL (or run bd sync if needed)

Best Practices

• Clear titles: Make issue titles descriptive and actionable

• Detailed descriptions: Include context, acceptance criteria, and links

• Dependencies: Always set up dependencies before starting work

• State updates: Keep issue state current as work progresses

• Comments: Add comments for significant decisions or blockers

• Labels: Use consistent labeling for easy filtering