Convert OpenSpec specs to self-contained Beads (project)
Converts OpenSpec specifications into self-contained Beads work items with full context.
/plugin marketplace add GantisStorm/essentials-claude-code/plugin install essentials@essentials-claude-code<spec-path> [spec-path-2] [spec-path-3] ...Convert OpenSpec specification(s) into self-contained Beads issues.
IMPORTANT: Each bead must be SELF-CONTAINED - implementable with ONLY its description. Never reference external specs without copying the content.
Beads provide structured, trackable work items that integrate with the OpenSpec workflow.
Key advantages:
Context Chain
Requirements
Exit Criteria
Single spec: openspec/changes/<name>/
Multiple specs (from decomposed proposal): openspec/changes/<name-1>/ openspec/changes/<name-2>/
# Check bd installed
bd version
# Check initialized (use --stealth for brownfield projects)
bd ready &>/dev/null && echo "OK" || echo "Run: bd init --stealth"
# Check path exists
ls $ARGUMENTS
Note: Use bd init --stealth for brownfield development. This keeps .beads/ out of git so you don't pollute existing repos with tracking files.
# Split arguments into array of spec paths
SPEC_PATHS=($ARGUMENTS)
# Validate each spec
for spec_path in "${SPEC_PATHS[@]}"; do
if [ -f "$spec_path/proposal.md" ]; then
echo "✓ $spec_path validated"
else
echo "ERROR: $spec_path is not a valid OpenSpec directory (missing proposal.md)"
exit 1
fi
done
echo "Total specs: ${#SPEC_PATHS[@]}"
For single spec:
cat $ARGUMENTS/proposal.md
cat $ARGUMENTS/tasks.md
cat $ARGUMENTS/design.md 2>/dev/null || true
find $ARGUMENTS/specs -name "*.md" -exec cat {} \; 2>/dev/null || true
For multiple specs (decomposed):
for spec_path in "${SPEC_PATHS[@]}"; do
echo "=== Spec: $spec_path ==="
cat $spec_path/proposal.md
cat $spec_path/tasks.md
cat $spec_path/design.md 2>/dev/null || true
find $spec_path/specs -name "*.md" -exec cat {} \; 2>/dev/null || true
done
Launch beads-creator-default:
Convert OpenSpec(s) to self-contained beads.
Spec Count: <1 or N>
Spec Paths: <path(s)>
Change Names: <name(s)>
## Spec Content
<content of all spec files>
## Key Principle
Each bead must be SELF-CONTAINED:
- Copy requirements verbatim (never "see spec")
- Include code examples
- Include exact file paths
- Include acceptance criteria
For single spec: Create epic first, then child tasks with --parent.
For multiple specs: Create one epic per spec, respect depends_on between specs.
Use subagent_type: "beads-creator-default" and run_in_background: true.
For single spec:
===============================================================
BEADS CREATED
===============================================================
Epic: <id>
Tasks: <count>
Ready: <count>
Complexity Assessment: <trivial|small|medium|large|huge>
Decomposition Strategy: <single-bead|multi-bead|hierarchical>
## Quality Report
| Metric | Value | Status |
|--------|-------|--------|
| Total beads | N | OK |
| Avg lines | N | OK |
| Independence | N% | OK |
| Max chain | N | OK |
Recommendation: PROCEED
Next Steps:
1. Review: bd list -l "openspec:<name>"
2. Start: /beads-loop --label openspec:<name>
===============================================================
For multiple specs (decomposed):
===============================================================
BEADS CREATED (FROM DECOMPOSED PROPOSALS)
===============================================================
Specs Processed: N
| Spec | Epic ID | Tasks | Ready |
|------|---------|-------|-------|
| add-auth-backend | epic-001 | 5 | 5 |
| add-auth-frontend | epic-002 | 4 | 0 |
| add-auth-tests | epic-003 | 3 | 0 |
Cross-Spec Dependencies:
epic-001 (add-auth-backend) → blocks → epic-002 (add-auth-frontend)
epic-002 (add-auth-frontend) → blocks → epic-003 (add-auth-tests)
Total Beads: 12
Ready Now: 5 (from add-auth-backend)
## Quality Report
| Metric | Value | Status |
|--------|-------|--------|
| Total beads | 12 | OK |
| Avg lines | 85 | OK |
| Independence | 65% | OK |
| Max chain | 3 | OK |
Recommendation: PROCEED
Next Steps:
1. Review: bd list
2. Start: /beads-loop (will respect cross-spec dependencies)
===============================================================
Each bead must be implementable with ONLY its description. Include dual back-references for context recovery.
BAD:
bd create "Update auth" -t task
GOOD:
bd create "Add JWT validation" -t task -p 2 \
--parent <epic-id> \
-l "openspec:add-auth" \
-d "## Context Chain
**Spec Reference**: openspec/changes/add-auth/specs/auth/spec.md
**Plan Reference**: .claude/plans/auth-3k7f2-plan.md
**Task**: 1.2 from tasks.md
## Requirements
<copied from spec - FULL text>
## Reference Implementation
<FULL code from design.md>
## Exit Criteria
- [ ] \`npm test -- auth\` passes
- [ ] TypeScript compiles
## Files
- src/auth.ts"
Litmus test: Could someone implement this with ONLY the bead description? If not, add more context.
The agent automatically decomposes large beads - no user prompt needed.
| Trigger | Threshold | Action |
|---|---|---|
| Bead size | >200 lines | Auto-create sub-beads |
| Complexity | Multiple responsibilities | Auto-split by concern |
| Independence | <60% score | Auto-restructure dependencies |
When beads exceed thresholds, the agent automatically:
--parent:
bd update <parent-id> --status decomposed
bd create "Sub-task 1" -t task --parent <parent-id> -l "openspec:<name>" -d "<self-contained>"
bd create "Sub-task 2" -t task --parent <parent-id> -l "openspec:<name>" -d "<self-contained>"
===============================================================
BEADS CREATED (AUTO-DECOMPOSED)
===============================================================
Original Beads: 5
Decomposed: 2 (too large)
New Sub-Beads: 6
Decomposition Details:
• bead-003 "Implement auth handler" → 3 sub-beads
- bead-003a "Add JWT validation middleware"
- bead-003b "Implement token refresh logic"
- bead-003c "Add session management"
• bead-005 "Add API endpoints" → 3 sub-beads
- bead-005a "POST /auth/login endpoint"
- bead-005b "POST /auth/logout endpoint"
- bead-005c "GET /auth/me endpoint"
Total Beads Now: 9
Ready: 4
Next: /beads-loop --label openspec:<name>
===============================================================
Works with plans from any planner:
/plan-creator <task> ┐
/bug-plan-creator <error> ├─▶ .claude/plans/*-plan.md
/code-quality-plan-creator ┘
│
▼
/proposal-creator <plan>
│
├─── [single proposal] ─────────▶ openspec/changes/<id>/
│ │
└─── [decomposed: multiple] ────▶ openspec/changes/<id-1>/
openspec/changes/<id-2>/
openspec/changes/<id-3>/
│ │
▼ ▼
/beads-creator <spec> /beads-creator <spec-1> <spec-2> <spec-3>
│ │
▼ ▼
/beads-loop /beads-loop (respects cross-spec deps)
Step mode pauses after creating beads for human review.
After creating beads, you MUST use AskUserQuestion to pause.
Use AskUserQuestion with:
- question: "Beads created. What would you like to do?"
- header: "Next step"
- options:
- label: "Continue (Recommended)"
description: "Proceed to /beads-loop"
- label: "Stop"
description: "End here for manual review"
Use --auto flag to skip pauses and proceed directly to beads-loop.
| Scenario | Action |
|---|---|
| bd not installed | "Install bd: https://github.com/steveyegge/beads" |
| bd not initialized | "Run: bd init" |
| Path not found | Report error |
# Single spec from proposal
/beads-creator openspec/changes/add-auth/
# Multiple decomposed specs
/beads-creator openspec/changes/add-auth-backend/ openspec/changes/add-auth-frontend/
# Auto mode (skip review pause)
/beads-creator openspec/changes/add-auth/ --auto