TL;DR: SpecFact CLI v0.25.1 now supports bidirectional synchronization between OpenSpec change proposals and DevOps backlog tools (GitHub Issues, Azure DevOps). This enables seamless integration of specification-driven development into your existing agile workflows without disrupting your team's processes.

New in v0.25.1: This feature is available in SpecFact CLI v0.25.1 and later. Install via pip install specfact-cli or uvx specfact-cli@latest.

Introduction

Specification-driven development (SDD) tools like OpenSpec create excellent change proposals and specifications. But how do you integrate these specs with your existing DevOps backlog tools? How do you keep your GitHub Issues or Azure DevOps work items in sync with your OpenSpec change proposals?

SpecFact CLI v0.25.1 introduces powerful backlog synchronization capabilities that bridge the gap between OpenSpec change proposals and your DevOps backlog tools. This enables you to:

  • Export OpenSpec change proposals as GitHub Issues or Azure DevOps work items
  • Import backlog items as OpenSpec change proposals
  • Sync status bidirectionally (OpenSpec ↔ Backlog)
  • Migrate between tools without losing content
  • Track progress automatically via code change detection

The Problem: Specs vs. Backlogs

Most teams use backlog management tools (GitHub Issues, Azure DevOps, Jira, Linear) for agile planning and tracking. These tools are great for:

  • Sprint planning
  • Task assignment
  • Progress tracking
  • Team collaboration

But when you adopt specification-driven development with OpenSpec, you create change proposals that live separately from your backlog. This creates a disconnect:

  • Change proposals live in OpenSpec (markdown files)
  • Backlog items live in GitHub Issues or ADO
  • Status can drift between the two
  • Content must be manually synchronized
  • Migration between tools is painful

Result: Teams either abandon OpenSpec for backlog tools, or maintain two separate systems manually.

The Solution: Backlog Adapters

SpecFact CLI v0.25.1 introduces backlog adapters that provide bidirectional synchronization between OpenSpec and DevOps backlog tools:

Supported Adapters

  • ✅ GitHub Issues (--adapter github) - Full support
  • ✅ Azure DevOps (--adapter ado) - NEW in v0.25.1
  • 🔜 Linear - Coming soon
  • 🔜 Jira - Coming soon

Key Features

1. Bidirectional Sync

Keep OpenSpec and your backlog in sync automatically:

# Sync OpenSpec proposals to GitHub Issues
specfact sync bridge --adapter github --bidirectional \
  --repo-owner nold-ai --repo-name specfact-cli

# Sync OpenSpec proposals to Azure DevOps
specfact sync bridge --adapter ado --bidirectional \
  --ado-org myorg --ado-project myproject \
  --ado-token $ADO_TOKEN

2. Lossless Content Preservation

Original raw content is preserved for perfect round-trips:

  • Raw title and raw body stored in project bundles
  • Format information preserved (Markdown, HTML)
  • Zero data loss when migrating between tools

3. Cross-Adapter Sync

Migrate between backlog tools without losing 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

4. Automatic Status Mapping

Status is automatically mapped between OpenSpec and backlog tools:

  • OpenSpec → GitHub: proposed → open, applied → closed
  • OpenSpec → ADO: proposed → New, applied → Closed
  • Conflict resolution: Prefer OpenSpec, prefer backlog, or merge (most advanced)

5. Progress Tracking

Automatically detect code changes and add progress comments:

specfact sync bridge --adapter github --mode export-only \
  --track-code-changes \
  --code-repo /path/to/source-code-repo

Azure DevOps Integration (NEW!)

Azure DevOps backlog adapter is now available in v0.25.1 with full feature parity:

Features

  • Work Item Creation: Export OpenSpec proposals as ADO work items
  • Work Item Import: Import ADO work items as OpenSpec proposals
  • Status Sync: Automatic two-way status synchronization
  • Markdown Support: Native Markdown formatting for work item descriptions
  • HTML Conversion: Automatically converts HTML-formatted work items to Markdown
  • Progress Tracking: Code change detection and progress comments
  • Three-Level Matching: Prevents duplicate work items across projects

Quick Start

  1. 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
  2. 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
  3. Bidirectional Sync: 
    specfact sync bridge --adapter ado --bidirectional \
  --ado-org your-org \
  --ado-project your-project \
  --ado-token $ADO_TOKEN

Configuration

--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

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

Result: All content preserved, zero data loss, perfect round-trip.

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

Result: Same change proposal available in both tools, status synced automatically.

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

Result: Changes in either system are automatically reflected in the other.

Technical Deep Dive

Lossless Content Preservation

To enable perfect round-trips, SpecFact stores original raw content in project bundles:

# .specfact/projects/my-bundle/bundle.manifest.yaml
source_tracking:
  source_metadata:
    raw_title: "Original Title from GitHub Issue"
    raw_body: "Original body content with formatting"
    raw_format: "markdown"
    backlog_entries:
      - source_id: "123"
        source_repo: "nold-ai/specfact-cli"
        source_type: "github"
        source_url: "https://github.com/nold-ai/specfact-cli/issues/123"

When exporting to a different adapter, this raw content is used to preserve 100% fidelity.

Three-Level Source Tracking Matching

Prevents duplicate work items when syncing across projects:

  1. Exact Match: source_repo matches exactly
  2. Org+Type Match: Organization and adapter type match (for ADO)
  3. Org-Only Match: Organization matches (only when project is unknown, e.g., GUID URLs)

This handles ADO's GUID-based URLs and project name changes gracefully.

Status Mapping

Automatic status mapping between OpenSpec and backlog tools:

OpenSpec Status GitHub Label ADO State
proposed open New
in-progress in-progress Active
applied closed Closed
deprecated deprecated Removed
discarded discarded Rejected

Why This Matters

For DevOps Teams

  • ✅ Use existing tools: Work with GitHub Issues or ADO you already use
  • ✅ No workflow disruption: Fits into your current agile processes
  • ✅ Automatic progress tracking: Code changes detected automatically
  • ✅ Tool migration: Switch tools without data loss

For Engineering Teams

  • ✅ Specification-driven development: Change proposals automatically synced to backlog
  • ✅ Implementation tracking: Progress tracked automatically via code changes
  • ✅ Cross-team collaboration: Different teams can use different tools
  • ✅ Single source of truth: OpenSpec remains the authoritative source

Getting Started

Installation

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

Quick Start: GitHub

# Export OpenSpec proposals to GitHub Issues
specfact sync bridge --adapter github --mode export-only \
  --repo-owner your-org \
  --repo-name your-repo \
  --github-token $GITHUB_TOKEN

Quick Start: Azure DevOps

# Export OpenSpec proposals to ADO work items
specfact sync bridge --adapter ado --mode export-only \
  --ado-org your-org \
  --ado-project your-project \
  --ado-token $ADO_TOKEN

Documentation

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

Conclusion

SpecFact CLI v0.25.1 brings powerful backlog synchronization capabilities that bridge the gap between OpenSpec change proposals and your DevOps backlog tools. Whether you use GitHub Issues, Azure DevOps, or both, you can now:

  • Keep specs and backlogs in sync automatically
  • Migrate between tools without losing content
  • Track implementation progress automatically
  • Use your existing agile workflows

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