Sync to ADO Skill

Overview

Push bead changes back to Azure DevOps as the source of truth. This skill:

• Creates ADO tasks for beads without ado:* labels
• Updates ADO task descriptions from bead descriptions
• Links ADO predecessor/successor relationships from bead blocks/blocked-by
• Labels beads with new ado:* IDs after creation

Usage

# Preview what would be synced (dry-run)
.beads/scripts/ado-sync.sh --dry-run --parent <story-bead-id>

# Sync after approval
.beads/scripts/ado-sync.sh --parent <story-bead-id>

Note: This is a guided skill with user approval gate. Never auto-sync without explicit approval.

---

Prerequisites

1. Azure DevOps CLI configured: az devops configure --defaults organization=<org> project=<proj>
2. Parent story has ado:* label (ADO work item must exist)
3. Task beads have structured descriptions (see decompose-story skill)

---

Workflow

Step 1: Identify Beads to Sync

Find child beads of the story that need syncing:

# List all children of the story
bd list --parent <story-id>

# Filter to those without ADO labels (new tasks)
bd list --parent <story-id> | grep -v "ado:"

Categorize beads:

• Create - No ado:* label (new task)
• Update - Has ado:* label but description changed
• Skip - Already synced, no changes

Step 2: Present Summary for Approval

Display what will be synced:

📤 Sync to ADO Summary
━━━━━━━━━━━━━━━━━━━━━

Parent Story: lista-j8w (ADO #669362)

CREATE (2 tasks):
  • lista-dud: Implement SSN encryption in EmployeePersonalProfile
    → Will create under ADO #669362
    → Blocks: lista-7yh, lista-7n6

  • lista-as6: Add employee address fields to EmployeePersonalProfile
    → Will create under ADO #669362
    → Blocks: lista-7yh

UPDATE (0 tasks):
  (none)

SKIP (2 tasks):
  • lista-7yh: blocked - waiting for lista-dud, lista-as6
  • lista-7n6: blocked - waiting for lista-dud

━━━━━━━━━━━━━━━━━━━━━
Proceed? [y/N]

Step 3: User Approval Gate

STOP and wait for explicit user approval.

Do not proceed without one of:

• User says "approved", "yes", "proceed", "sync"
• User runs the script directly

If user requests changes:

1. Update bead descriptions/labels as requested
2. Re-run Step 2 with updated summary

Step 4: Execute Sync

Run the sync script:

.beads/scripts/ado-sync.sh --parent <story-bead-id>

The script will:

1. Create ADO tasks under the parent work item
2. Set ADO description from bead description
3. Create predecessor links for blocking relationships
4. Update beads with new ado:* labels

Step 5: Report Results

Display sync results:

✅ Sync Complete
━━━━━━━━━━━━━━━━

Created:
  • lista-dud → ADO #676201
  • lista-as6 → ADO #676202

Links Created:
  • ADO #676201 blocks #676203, #676204
  • ADO #676202 blocks #676203

Beads Updated:
  • lista-dud: +label ado:676201
  • lista-as6: +label ado:676202

Step 6: Verify in ADO

Provide link to verify:

🔗 View in Azure DevOps:
   https://dev.azure.com/<org>/<project>/_workitems/edit/669362

---

ADO Work Item Mapping

Bead fields are mapped to a structured ADO Description with HTML sections:

Bead Field	ADO Description Section	Format
--description	Overview	<h3>Overview</h3><p>...</p>
--acceptance	Acceptance Criteria	<h3>Acceptance Criteria</h3><ul><li>...</li></ul>
--design	Technical Details	<h3>Technical Details</h3><p>...<br>...</p>
--notes	Notes	<h3>Notes</h3><p>...</p>

Other bead fields map directly:

Bead Field	ADO Field
Title	System.Title
phase:* label	Tags
project:* label	Tags
Parent	Parent Link
Blocks	Predecessor Link (Successor)
Blocked By	Predecessor Link (Predecessor)

Example ADO Description Output

<h3>Overview</h3>
<p>Implement AES-256 encryption for SSN field in EmployeePersonalProfile.</p>

<h3>Acceptance Criteria</h3>
<ul>
  <li>Create IEncryptionService interface with Encrypt/Decrypt methods</li>
  <li>Implement AesEncryptionService using AES-256-CBC</li>
  <li>Update EmployeePersonalProfile to store encrypted SSN</li>
</ul>

<h3>Technical Details</h3>
<p>Reference Pattern: src/services/accessor/profile/.../EmployeePersonalProfile.cs<br>
Project: Lista.Accessor.Profile</p>

<h3>Notes</h3>
<p>See marten.models.instructions.md for document patterns.</p>

---

Error Handling

Error	Action
ADO API rate limit	Wait and retry
Parent work item not found	Abort with error
Duplicate title exists	Warn, create anyway (ADO allows duplicates)
Bead lacks description	Warn, sync anyway with empty description
Link creation fails	Log warning, continue (links can be added manually)

---

Config

See .github/skills/sync-to-ado/config.json for:

• ADO field mappings
• Default work item type for tasks
• Link type names

---

Related Skills

• decompose-story - Create task beads from story
• lista-story formula - End-to-end workflow: ingest → decompose → review → sync