ado-sync

What This Skill Does

The ado-sync skill serves as the primary guidance and orchestration hub for integrating SpecWeave increments with Azure DevOps (ADO). Its core function is to facilitate a bidirectional synchronization process where project progress within SpecWeave is reflected in your ADO environment and vice versa. It provides essential documentation on setting up credentials, configuring the .specweave/config.json file, and understanding the workflow for mapping development increments to work items like Epics, Features, or User Stories. This skill empowers users to automate status updates, sync task completion percentages, and ensure that project management tools are always aligned with actual code development progress.

Installation

To integrate this functionality, ensure the ADO plugin is active. Verify the installation by running /plugin list --installed | grep sw-ado. If it is missing, install it via /plugin install sw-ado@specweave. Post-installation, you must authenticate by creating a Personal Access Token (PAT) in your Azure DevOps user settings with read/write permissions for Work Items and Comments. Export this as an environment variable: export AZURE_DEVOPS_PAT="your-token-here". Finally, populate your .specweave/config.json file under the externalPM key with your specific organization, project, and area path details to enable the automated bridge.

Use Cases

This skill is perfect for teams looking to eliminate manual status reporting. It is frequently used for mapping specific SpecWeave increments to ADO work items, automating the transition of work states (e.g., New to Active) as tasks are performed, and keeping stakeholders updated through automated comments in ADO that reflect granular task progress. It is also instrumental in closing work items automatically when an increment is marked complete.

Example Prompts

1. "How do I configure the .specweave/config.json file to connect to my Azure DevOps project?"
2. "What are the necessary scopes for my Azure DevOps PAT to allow SpecWeave to write comments?"
3. "Could you explain the difference between syncing progress manually versus the automatic sync on task completion?"

Tips & Limitations

Always remember that this skill is for guidance. Direct sync operations should use the /sw-ado:sync command directly. Do not trigger the sync skill during active CLI commands to avoid race conditions. Ensure your area paths are correctly formatted with double backslashes in your JSON configuration. If syncing fails, check your PAT expiry date and ensure the agent has read/write access to the specific team project area identified in your configuration file.