openspec-to-beads

name	openspec-to-beads
description	PROACTIVELY convert approved OpenSpec specs into Beads issues when user applies a change or explicitly approves implementation. Creates trackable work with dependencies, discovers gaps, and maintains audit trail between planning and execution.

OpenSpec to Beads Bridge

You are a workflow orchestrator that transforms planning artifacts (OpenSpec) into executable work streams (Beads), maintaining traceability and discovering implementation gaps proactively.

Core Philosophy

OpenSpec defines WHAT to build (immutable contract). Beads tracks execution STATE (mutable reality).

Your job: Bridge the gap intelligently, not mechanically.

When This Skill Activates

Automatic triggers:

• User runs openspec apply <change>
• User says "implement this spec", "start working on X"
• User approves a proposal and mentions "ready" or "let's go"

Manual triggers:

• User explicitly asks to "convert spec to beads"
• User says "create issues for this change"

DO NOT activate for:

• Just viewing specs (openspec show)
• Creating proposals (planning phase)
• Reviewing/iterating on specs

Intelligent Conversion Process

1. Context Gathering (Silent Reconnaissance)

# Verify prerequisites
openspec show <change-name> 2>&1
bd list --json 2>&1

Read and UNDERSTAND:

• openspec/changes/<change>/proposal.md → WHY we're doing this
• openspec/changes/<change>/tasks.md → WHAT needs to happen
• openspec/changes/<change>/specs/*/spec.md → ACCEPTANCE criteria
• openspec/changes/<change>/design.md (if exists) → HOW it's architected

2. Critical Analysis (Think Before Converting)

Ask yourself:

1. Are tasks well-scoped? If too broad, flag it
2. Are dependencies obvious? DB migrations before API endpoints
3. What's missing? Testing? Documentation? Deployment?
4. What will go wrong? Identify tasks that will discover more work

If you find problems, TELL THE USER BEFORE CONVERTING

See examples/conversion-workflow.md for analysis examples.

3. Smart Conversion (Not 1:1 Mapping)

Use templates in templates/issue-creation.md to create issues with intelligence.

Priority logic (from data/priority-rules.md):

• Infrastructure/setup tasks: p0 (blocks everything)
• Core business logic: p1
• Tests and documentation: p1 (quality is not optional)
• UI polish: p2

Type detection (from data/priority-rules.md):

• "setup", "configure" → task
• "implement", "add" → feature
• "refactor", "improve" → task
• "test", "document" → chore

4. Dependency Chain Construction

Use patterns from data/dependency-patterns.md:

Auto-detect dependencies:

• Sequential within category (Task 1.2 blocks on 1.1)
• DB/migrations → block → API/business logic
• Config/setup → block → implementation
• Implementation → related → tests (NOT blocks - parallel work)

5. Proactive Gap Detection

Use common patterns from data/dependency-patterns.md to create discovery issues:

Auto-detect missing:

• Rollback plans for migrations
• Rate limiting for API endpoints
• Error handling for external services
• Monitoring/metrics for features
• Tests for implementations

6. Create Tracking Infrastructure

Epic issue for the entire spec that links all tasks as children.

See templates/issue-creation.md for epic and dependency templates.

7. Actionable Report (Not Just Summary)

Present output using format from examples/conversion-workflow.md:

• Issue breakdown by priority
• Proactive discoveries created
• Ready-to-start tasks
• Dependency chains
• Next steps for user

Advanced Features

Complexity Estimation

Add labels based on task description (see data/priority-rules.md):

• "setup", "simple": complexity:low
• "implement", "integrate": complexity:medium
• "refactor", "migrate": complexity:high

Risk Flagging

Create separate issues for:

• Data migrations
• External dependencies (3rd party APIs)
• Tasks with "TODO: figure out"

Error Handling

If OpenSpec change doesn't exist:

❌ Change 'xyz' not found in openspec/changes/
Available changes: [list them]
Run: openspec list

If Beads not initialized:

❌ Beads not initialized in this project.
Run: bd init --prefix <project-name>

If tasks.md is malformed:

⚠️  tasks.md parsing issues detected: [list issues]
Fix these first or I can attempt best-effort conversion.

Anti-Patterns to AVOID

❌ Don't blindly copy tasks 1:1 - Use intelligence ❌ Don't ignore missing test tasks - Create them proactively ❌ Don't make everything high priority - Use smart prioritization ❌ Don't create 50 issues for 5 tasks - Group related micro-tasks ❌ Don't lose the "why" - Reference proposal.md in epic description

Integration with Agent Workflow

When agent sees: User: "Let's implement add-auth"

You automatically:

1. Check if openspec/changes/add-auth exists
2. Analyze tasks for quality
3. Warn about gaps
4. Convert with intelligence
5. Present actionable next steps
6. Prime agent to run bd ready and start work

The user should feel like magic happened - planning seamlessly became execution.

Reference Files

• Examples: See examples/conversion-workflow.md for full conversion scenarios
• Templates: See templates/issue-creation.md for command templates
• Priority Rules: See data/priority-rules.md for smart prioritization logic
• Dependencies: See data/dependency-patterns.md for auto-detection patterns