BD Sync: OpenSpec <-> Beads Synchronization

Unified skill for managing synchronization between OpenSpec changes and beads epics. All analysis is delegated to specialized agents; this skill is a thin router.

SUBCOMMANDS

Subcommand	Agent	Purpose
audit	mindcontext-core:sync-auditor	Report gaps and quality between OpenSpec and beads
import	mindcontext-core:beads-builder	Import OpenSpec change to implementation-ready beads
import --lite	mindcontext-core:sync-importer	Import as lightweight tracking beads
update	mindcontext-core:sync-updater	Sync existing epic with evolving tasks.md
specgap	mindcontext-core:specgap-scanner	Find untracked work

USAGE

/bd-sync                          # Same as /bd-sync audit
/bd-sync audit                    # Full sync report
/bd-sync audit --missing          # Only untracked OpenSpec changes
/bd-sync audit --orphans          # Only orphaned beads epics
/bd-sync audit --drift            # Only completion status drift
/bd-sync audit --quality          # Include bead content quality assessment
/bd-sync import <change>          # Import (implementation-ready beads, default)
/bd-sync import <change> --lite   # Import (lightweight tracking beads)
/bd-sync import <change> --skip-tdd  # Skip TDD test-bead-first (TDD is default ON)
/bd-sync import <change> --containment=full  # Force containment level
/bd-sync import <change> --max-bead-size=300 # Custom decomposition threshold
/bd-sync import --all             # Import all untracked changes
/bd-sync import <change> --dry-run  # Preview without creating
/bd-sync update <change>          # Sync spec -> beads
/bd-sync update <change> --direction=beads-to-spec
/bd-sync update <change> --direction=both
/bd-sync update --all             # Update all tracked changes
/bd-sync specgap                  # Find untracked commits (last 7 days)
/bd-sync specgap --since=2w       # Custom date range
/bd-sync specgap --todos          # Also scan for TODO/FIXME
/bd-sync specgap --create         # Interactively create tasks for gaps

ROUTING

Parse $ARGUMENTS to determine subcommand:

• Empty, "audit", or starts with "--" -> Audit flow
• "import ..." -> Import flow
• "update ..." -> Update flow
• "specgap ..." -> Specgap flow

---

AUDIT FLOW

1. Gather context (bash):

   ls openspec/changes/ 2>/dev/null | grep -v archive
   br list -t epic
   

2. Parse flags:

   • --missing -> Only untracked changes
   • --orphans -> Only orphaned epics
   • --drift -> Only completion drift
   • --quality -> Add bead content quality assessment

3. Launch agent: mindcontext-core:sync-auditor

   • Pass: OpenSpec change list, beads epic list
   • Pass: quality_check: true if --quality flag present
   • Agent returns JSON: { tracked[], untracked[], orphaned[], summary{} }

4. Display report: Format the agent's JSON as a readable table

   • Show tracked changes with sync status
   • Highlight untracked changes (suggest: /bd-sync import <name>)
   • Show orphaned epics
   • Flag drift (tasks.md vs beads divergence)
   • If --quality: Show quality grades per change
     • Highlight tracking-only beads with suggestion: /bd-sync import <name> to upgrade

5. Handle filters: If flag present, show only that section

---

IMPORT FLOW

1. Validate change exists:

   test -d "openspec/changes/$CHANGE_NAME" || echo "Change not found"
   

2. Parse flags:

   • --lite -> Lightweight tracking beads (sync-importer agent)
   • --skip-tdd -> Skip TDD test-bead-first generation (TDD is ON by default)
   • --containment=full|hybrid|ref -> Override auto-detection
   • --max-bead-size=N -> Decomposition threshold (default 200)
   • --dry-run -> Preview without creating
   • --all -> Import all untracked changes

3. Handle --all flag: If --all, get untracked list from audit and loop

4. Route to agent:

   If --lite flag is present: Launch mindcontext-core:sync-importer (Sonnet, lightweight)

   • Pass: OpenSpec change directory path, change name
   • Agent returns JSON: { epic_id, phases[], dependencies[], summary{} }

   If --lite flag is NOT present (default): Read spec files and pass content to agent:

   cat "openspec/changes/$CHANGE_NAME/proposal.md"
   cat "openspec/changes/$CHANGE_NAME/design.md" 2>/dev/null || true
   cat "openspec/changes/$CHANGE_NAME/tasks.md"
   cat "openspec/changes/$CHANGE_NAME/tests.md" 2>/dev/null || true
   find "openspec/changes/$CHANGE_NAME/specs" -name "*.md" -exec cat {} \; 2>/dev/null || true
   

   Launch mindcontext-core:beads-builder (Opus, full quality)

   • Pass: Full spec file contents, change name, flags (containment, tdd, max-bead-size)
   • Agent creates beads directly with br create and returns structured result

5. Display results:

   • For lite: Show created epic, phases, task counts
   • For full: Show created epic, TDD structure, containment levels, quality metrics

6. Handle --dry-run: If dry-run, tell the agent to describe what would be created without executing br create

---

UPDATE FLOW

1. Find existing epic:

   br list -t epic -l "openspec:$CHANGE_NAME"
   

2. Gather current state:

   br list --parent $EPIC_ID
   cat "openspec/changes/$CHANGE_NAME/tasks.md"
   

3. Determine direction: Default spec-to-beads, or from --direction flag

4. Launch agent: mindcontext-core:sync-updater

   • Pass: Epic ID, beads children, tasks.md content, direction
   • Agent returns JSON: { direction, created[], closed[], checkbox_updates[], summary{} }

5. Display results: Show what was created/closed/updated

6. For beads-to-spec: If checkbox_updates returned, ask user before editing tasks.md:

   AskUserQuestion: "Update these checkboxes in tasks.md? [list changes]"
   

   Apply edits only if user confirms.

---

SPECGAP FLOW

1. Parse options: --since (default 7d), --todos flag, --create flag

2. Gather context:

   git log --oneline --since="$SINCE"
   br list --json
   

3. Launch agent: mindcontext-core:specgap-scanner

   • Pass: Git log, beads titles, TODO flag, new files
   • Agent returns JSON: { untracked_commits[], todos[], untracked_files[], summary{} }

4. Display report: Format as readable list with counts

5. Handle --create: If --create flag, for each untracked item:

   AskUserQuestion: "Create beads task for: [commit/todo/file]? (y/n/skip)"
   

   Create tasks for confirmed items.