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

Weekly Installs

73

Source

smithery.ai/ski…to-beads

First Seen

Mar 6, 2026

Security Audits

SocketPass

Installed on

claude-code66

opencode12

cline10

cursor10

amp9

kimi-cli9