Initial commit

commands/specweave-ado-sync.md

@@ -0,0 +1,148 @@
+---
+name: specweave-ado:sync
+description: Two-way sync between SpecWeave increment and Azure DevOps work item (push & pull by default)
+---
+
+# Sync ADO Work Item Command
+
+**Usage**: `/specweave-ado:sync <increment-id> [options]`
+
+**Purpose**: Two-way synchronization between SpecWeave increment and Azure DevOps work item
+
+**Default**: Two-way sync (push & pull)
+
+---
+
+## Options
+
+- `--direction <mode>`: Sync direction (default: `two-way`)
+  - `two-way`: SpecWeave ↔ ADO (default - recommended)
+  - `to-ado`: SpecWeave → ADO only (push progress)
+  - `from-ado`: ADO → SpecWeave only (pull updates)
+
+## Examples
+
+```bash
+# Two-way sync (default - both directions)
+/specweave-ado:sync 0005
+
+# Push only (one-way to ADO)
+/specweave-ado:sync 0005 --direction to-ado
+
+# Pull only (one-way from ADO)
+/specweave-ado:sync 0005 --direction from-ado
+```
+
+---
+
+## Command Behavior
+
+When user runs this command, invoke `ado-manager` agent to perform two-way sync:
+
+### Phase 1: Pull FROM ADO (default behavior)
+1. Fetch work item state from ADO API
+2. Detect changes in ADO:
+   - State changes (New → Active → Resolved → Closed)
+   - Priority changes
+   - Iteration/sprint changes
+   - Comments from team members
+   - Field updates
+3. Apply ADO changes to SpecWeave increment:
+   - Update increment status to match ADO state
+   - Update priority in metadata
+   - Import team comments to increment notes
+   - Update iteration tracking
+
+### Phase 2: Push TO ADO (default behavior)
+1. Read tasks.md from increment
+2. Calculate completion percentage
+3. Identify recently completed tasks
+4. Format progress update comment
+5. POST comment to ADO work item
+6. Update work item state if needed (New → Active → Resolved)
+7. Update custom fields (completion %, current task, etc.)
+
+**Agent Invocation**:
+```
+Use Task tool with subagent_type: "specweave-ado:ado-manager:ado-manager"
+
+Prompt: "Two-way sync for increment 0005-payment-integration with ADO.
+
+Phase 1 - Pull FROM ADO:
+1. Fetch work item #12345 from ADO API
+2. Detect changes: state, priority, iteration, comments
+3. Apply ADO changes to increment metadata
+4. Import team comments to increment notes
+
+Phase 2 - Push TO ADO:
+1. Read .specweave/increments/0005/tasks.md
+2. Calculate: X/Y tasks complete (Z%)
+3. Identify: Recently completed tasks
+4. Format comment with progress update
+5. Load work item ID from increment-metadata.json
+6. POST comment to ADO API
+7. Update work item state/fields
+
+Display: Two-way sync summary"
+```
+
+---
+
+## Example Output
+
+### Two-way Sync (Default)
+
+```
+🔄 Two-way sync for increment 0005...
+
+✓ Azure DevOps work item: #12345
+✓ Sync direction: Two-way (push & pull)
+
+Detecting changes (both directions)...
+
+FROM ADO:
+✓ Work item state changed: Active → Resolved
+✓ Iteration updated: Sprint 23 → Sprint 24
+✓ Priority changed: 2 → 1
+✓ 3 new comments from team
+
+FROM SpecWeave:
+✓ 2 new tasks completed (T-005, T-006)
+✓ Progress: 40% → 60% (6/10 tasks)
+✓ Current task: T-007
+
+Syncing TO ADO...
+✓ Posted progress comment (ID: 98765)
+✓ Updated completion: 60%
+✓ Updated current task field: T-007
+
+Syncing FROM ADO...
+✓ Updated increment status: active → completed
+✓ Updated priority: P2 → P1
+✓ Updated iteration tracking: Sprint 24
+✓ Imported 3 team comments to increment notes
+
+✅ Bidirectional Sync Complete!
+
+   SpecWeave ↔ ADO synchronized
+   • Pushed: Progress (60%), 2 task updates
+   • Pulled: State (Resolved), priority (P1), iteration, 3 comments
+
+ADO Work Item: https://dev.azure.com/myorg/MyProject/_workitems/edit/12345
+Last synced: just now
+Next sync: Automatic (hook-based) or manual when ready
+```
+
+### One-Way Sync (to-ado)
+
+```
+✅ Pushed to ADO Work Item #12345
+
+Progress: 60% complete (6/10 tasks)
+
+Recently Completed:
+- T-005: Add payment tests
+- T-006: Update documentation
+
+URL: https://dev.azure.com/myorg/MyProject/_workitems/edit/12345
+```