🚀 Announcing: Backlog Sync Features for DevOps Teams

[djm81]

🚀 Announcing: Backlog Sync Features for DevOps Teams

We're excited to announce powerful new backlog synchronization capabilities in SpecFact CLI v0.25.1! These features enable seamless integration between OpenSpec change proposals and your existing DevOps backlog tools, making specification-driven development accessible to agile teams.

✨ What's New

🔄 Azure DevOps Backlog Adapter

Full bidirectional sync between OpenSpec change proposals and Azure DevOps work items:

• Import ADO Work Items → OpenSpec change proposals
• Export Change Proposals → ADO work items
• Status Synchronization → Automatic two-way status sync (OpenSpec ↔ ADO)
• Markdown Support → Native Markdown formatting for work item descriptions
• Progress Tracking → Automatic code change detection and progress comments

🌉 Cross-Adapter Sync (NEW!)

Lossless round-trip synchronization between different backlog tools:

• Tool Migration → Migrate from GitHub to ADO (or vice versa) with 100% content fidelity
• Multi-Tool Workflows → Sync the same change proposal to both GitHub (public) and ADO (internal)
• Zero Data Loss → Original raw content preserved for perfect round-trips
• Bundle-Based → Use project bundles to store and export content across adapters

🎯 Key Features

Lossless Content Preservation

• Stores original raw content (title, body, format) in project bundles
• Enables perfect round-trips: GitHub → OpenSpec → ADO → OpenSpec → GitHub
• No formatting loss, no data corruption

Three-Level Source Tracking

• Prevents duplicate work items across projects
• Handles ADO URL GUIDs and project name changes
• Smart matching: exact → org+type → org-only (when project unknown)

Automatic Status Mapping

• Maps ADO states (New/Active/Closed) ↔ OpenSpec status (proposed/in-progress/applied)
• Conflict resolution strategies: prefer OpenSpec, prefer backlog, or merge (most advanced)

🎬 Use Cases

1. Tool Migration

Migrate your backlog from GitHub to Azure DevOps (or vice versa) without losing any content:

# Step 1: Import from GitHub into bundle (preserves raw content)
specfact sync bridge --adapter github --bundle migration \
  --backlog-ids 110,112 --repo-owner nold-ai --repo-name specfact-cli

# Step 2: Export to ADO with lossless content
specfact sync bridge --adapter ado --mode export-only \
  --bundle migration --change-ids add-ado-backlog-adapter \
  --ado-org myorg --ado-project myproject

2. Multi-Tool Workflows

Sync the same change proposal to both public GitHub and internal ADO:

# Export to GitHub (public)
specfact sync bridge --adapter github --mode export-only \
  --repo-owner nold-ai --repo-name specfact-cli

# Export to ADO (internal)
specfact sync bridge --adapter ado --mode export-only \
  --ado-org myorg --ado-project myproject

3. Bidirectional Sync

Keep OpenSpec and ADO in sync automatically:

specfact sync bridge --adapter ado --bidirectional \
  --ado-org myorg --ado-project myproject \
  --ado-token $ADO_TOKEN

📚 Getting Started

Quick Start: Azure DevOps

1. Install SpecFact CLI:

   pip install specfact-cli
   # or
   uvx specfact-cli@latest

2. Export a Change Proposal to ADO:

   specfact sync bridge --adapter ado --mode export-only \
     --ado-org your-org \
     --ado-project your-project \
     --ado-token $ADO_TOKEN \
     --change-ids your-change-id

3. Import ADO Work Items:

   specfact sync bridge --adapter ado --bidirectional \
     --ado-org your-org \
     --ado-project your-project \
     --ado-token $ADO_TOKEN \
     --backlog-ids 123,456

Documentation

• 📖 Azure DevOps Adapter Guide - Complete reference
• 📖 DevOps Integration Guide - Integration patterns
• 📖 Cross-Adapter Sync Guide - Migration workflows

🔧 Configuration

Azure DevOps Options

--ado-org <org>              # Azure DevOps organization
--ado-project <project>      # Project name
--ado-base-url <url>        # Optional: For Azure DevOps Server (on-prem)
--ado-token <token>         # Personal Access Token (Work Items Read & Write)
--ado-work-item-type <type> # Optional: User Story, Product Backlog Item, Bug

GitHub Options

--repo-owner <owner>        # GitHub organization/user
--repo-name <repo>          # Repository name
--github-token <token>      # GitHub token (or use GITHUB_TOKEN env var)

💡 Why This Matters

For DevOps Teams:

• ✅ Use your existing backlog tools (GitHub Issues, ADO) with SpecFact
• ✅ No workflow disruption - works with your current agile processes
• ✅ Automatic progress tracking via code change detection
• ✅ Tool migration without data loss

For Engineering Teams:

• ✅ Specification-driven development with backlog integration
• ✅ Change proposals automatically synced to your backlog
• ✅ Implementation progress tracked automatically
• ✅ Cross-team collaboration with different tool preferences

🎉 What's Next

We're planning support for:

• Linear adapter (coming soon)
• Jira adapter (coming soon)
• Enhanced conflict resolution strategies
• Webhook-based real-time sync

🤝 Feedback & Support

We'd love to hear from you! Share your use cases, ask questions, or report issues:

• 💬 Discussions: GitHub Discussions - Share your use cases and ask questions
• 🐛 Issues: GitHub Issues - Report bugs or request features
• 📖 Docs: Documentation - Complete guides and API reference

---

Ready to get started? Check out our quick start guide and let us know how it works for your team!