Skill Overview

This skill bridges Beads (git-backed multi-repository issue tracker) with project management tools like GitHub Projects v2 and Shortcut. It enables teams working across multiple repositories to maintain a unified view of work while preserving detailed technical tracking in Beads.

How Claude Uses This Skill:

•Check if beads-bridge is installed: Run beads-bridge --version
•If not found: Show helpful error message directing user to installation instructions
•Execute commands: Use beads-bridge <command> <args> via Bash tool
•Parse output: Commands return JSON that can be presented to the user

IMPORTANT:

•The beads-bridge CLI must be installed and available in PATH
•Always run commands from the project root so CLI can find .beads/ directory
•If beads-bridge command not found, instruct user to install it (see Installation section below)

Key Capabilities

Works with both GitHub Issues/Projects and Shortcut Stories:

•Query Status - Get aggregated progress across issues/stories and Beads epics
•Sync Progress - Post progress updates from Beads to GitHub/Shortcut
•Generate Diagrams - Create Mermaid dependency visualizations
•Detect Discoveries - Identify newly discovered work during implementation
•Manage Mappings - Create/query links between issues/stories and Beads epics
•Interactive Visualization - Serve interactive web dashboard for beads exploration
•Decompose - Convert issue/story task lists into Beads epics and tasks

Use Cases

•Tech Leads: Monitor progress across 5+ repositories from a single GitHub Projects board
•Product Managers: Get accurate completion estimates based on actual dependency analysis
•Engineering Teams: Automatically propagate discovered work to project tracking
•Stakeholders: View real-time progress with auto-updating diagrams and metrics

Installation

If beads-bridge is not found in PATH, provide this message to the user:

code

The beads-bridge CLI is not installed. Please install it first:

# Download and install the latest release:
curl -fsSL https://raw.githubusercontent.com/wellmaintained/skills/main/src/beads-bridge/scripts/install-beads-bridge.sh | bash

# Or install as Claude Code plugin (will install CLI automatically):
claude-code plugin install wellmaintained/skills/beads-bridge

After installation, beads-bridge should be available in your PATH.

Command Usage

Before Running Commands

Always verify beads-bridge is available:

bash

beads-bridge --version

If this fails, show the installation message above and stop.

Unified Commands

All commands should be run from the project root directory:

bash

# Sync a bead to its external system (GitHub/Shortcut)
beads-bridge sync <bead-id>

# Decompose an external issue into Beads epics and tasks
beads-bridge decompose <ref>
# Examples:
beads-bridge decompose https://github.com/owner/repo/issues/123
beads-bridge decompose github:owner/repo#123
beads-bridge decompose shortcut:89216

Interactive Visualization

bash

# Serve interactive web dashboard for a bead
beads-bridge serve <bead-id>

# Example:
beads-bridge serve wms-123

This starts a local web server (typically at http://localhost:3000) showing:

•Interactive dependency graph
•Task status and progress
•Real-time updates via SSE
•Drag-and-drop canvas for exploring relationships

Capability Implementation

When user requests a beads-bridge operation, use the corresponding CLI command:

1. Sync Progress

bash

# Sync a bead by ID (uses external_ref from the bead)
beads-bridge sync <bead-id>

# Example:
beads-bridge sync wms-123

# Dry run to see what would be synced
beads-bridge sync wms-123 --dry-run

The sync command automatically:

•Reads the bead's external_ref field
•Detects the backend (GitHub or Shortcut)
•Generates a Mermaid dependency diagram
•Posts updates to the linked issue/story

Confirm to user that progress was synced successfully.

2. Decompose Issues

bash

# Decompose using URL
beads-bridge decompose https://github.com/owner/repo/issues/123

# Decompose using shorthand format
beads-bridge decompose github:owner/repo#123
beads-bridge decompose shortcut:89216

# Decompose without posting confirmation comment
beads-bridge decompose github:owner/repo#123 --no-comment

# Decompose with custom priority for created beads
beads-bridge decompose github:owner/repo#123 --priority 1

The decompose command automatically:

•Detects the backend from the reference format
•Creates an epic with external_ref set
•Creates child tasks from the issue/story body

Confirm that task lists were decomposed into Beads epics and tasks.

3. Interactive Visualization

bash

beads-bridge serve wms-123

Inform user that the server is starting and provide the URL to access the visualization.

Error Handling

If beads-bridge command fails:

•Command not found: Show installation instructions (see Installation section)
•Config file missing: User needs to create .beads-bridge/config.json in project root
•Authentication errors: User needs to run beads-bridge auth for GitHub/Shortcut
•Invalid arguments: Check command syntax in this SKILL.md

Always provide helpful guidance based on the error message from the CLI.

Best Practices

For Product Managers

•Set external_ref early - Link GitHub Issues or Shortcut stories when creating epics
•Review discoveries weekly - Check discover output during standups
•Use interactive visualization - Run beads-bridge serve for visual progress tracking

For Tech Leads

•Keep diagrams current - Run sync after major scope changes to update diagrams
•Track blockers actively - Use bd show <bead-id> to check status
•Verify cross-repo deps - Use bd dep tree to verify dependencies

For Engineering Teams

•Use Beads for technical work - Detailed tracking stays in repositories
•Let sync handle GitHub - Don't manually update tracking issues
•Tag discoveries properly - Beads issues with discovered-from relationships

Troubleshooting

CLI Not Found

bash

# Check if beads-bridge is in PATH
which beads-bridge

# If not found, install it
curl -fsSL https://raw.githubusercontent.com/wellmaintained/skills/main/src/beads-bridge/scripts/install-beads-bridge.sh | bash

Authentication Issues

bash

# GitHub: Set up authentication
beads-bridge auth --backend github

# Shortcut: Set up authentication
beads-bridge auth --backend shortcut

Config File Missing

Create .beads-bridge/config.json in your project root:

json

{
  "repositories": {
    "repo-name": {
      "path": "/absolute/path/to/repository"
    }
  },
  "backend": "github",
  "githubRepository": "owner/repo"
}

See the beads-bridge documentation for complete configuration options.

Output Format

All commands output JSON that can be parsed and presented to the user. Example:

json

{
  "completionPercentage": 65,
  "totalTasks": 23,
  "completedTasks": 15,
  "epics": [
    {
      "id": "frontend-e42",
      "repository": "frontend",
      "status": "in_progress",
      "completion": 80
    }
  ]
}

Parse this JSON and present key information in a user-friendly format.

Skill Overview

Key Capabilities

Use Cases

Installation

Command Usage

Before Running Commands

Unified Commands

Interactive Visualization

Capability Implementation

1. Sync Progress

2. Decompose Issues

3. Interactive Visualization

Error Handling

Best Practices

For Product Managers

For Tech Leads

For Engineering Teams

Troubleshooting

CLI Not Found

Authentication Issues

Config File Missing

Output Format

Related Documentation