/progress-sync

description: Sync progress from tasks.md to living docs and external tools (GitHub/JIRA/ADO). Use when saying "sync progress" or "push progress".
version: 1.0.0
argument-hint: "[INCREMENT_ID] [--dry-run] [--no-create] [--no-github] [--no-jira]"

Progress Sync (Multi-System)

Orchestrate end-to-end progress synchronization: **tasks.md → spec.md ACs → living docs → external tools (GitHub/JIRA/ADO)**.

---

⚠️ CRITICAL: AUTO-CREATE IS MANDATORY

**When `sw:sync-progress` is executed and no external issue exists, it MUST automatically create the issue using the Skill tool.**

The command MUST invoke:

• `sw-github:create <increment-id>` for GitHub
• `sw-jira:create <increment-id>` for JIRA
• `sw-ado:create <increment-id>` for Azure DevOps

**DO NOT just report "No issues linked" - ACTUALLY CREATE THE ISSUE.**

---

What is sw:sync-progress?

**The TRUE "single button" to sync progress across all systems**:

tasks.md → spec.md ACs → living docs → AUTO-CREATE external issues → sync external tools (GitHub/JIRA/ADO)

**One command does EVERYTHING - including creating missing external issues!**

sw:sync-progress

**No more "No GitHub issue linked" errors!** The command auto-creates missing issues.

✅ Archived Increment Behavior

**For archived/completed increments, this command ALWAYS creates issues for historical tracking:**

| Situation | Action | |-----------|--------| | Issue EXISTS | ✅ Sync final state + Close/Transition | | NO issue linked | ✅ AUTO-CREATE + IMMEDIATELY CLOSE (historical tracking) |

**Why?** Historical tracking is important! Completed work should have external issues for:

• Team visibility
• Sprint retrospectives
• Release notes generation
• Audit trails

**For all increments (active or completed)**: Auto-creates issues if missing (the "single button" philosophy)

---

When to Use This Command

✅ Use sw:sync-progress when:

1. **First-time sync (no external issue yet)**: Just created increment, want to sync → auto-creates GitHub/JIRA/ADO issues! 2. **After completing tasks**: You've marked tasks as done in tasks.md and want to sync everywhere 3. **Before closing increment**: Final sync before `sw:done` to ensure all systems in sync 4. **Progress check**: Want to update status line and external tools with latest progress 5. **After bulk task completion**: Completed multiple tasks, sync all at once 6. **Manual sync trigger**: Hooks didn't fire or you want to force a sync 7. **"No GitHub issue linked" error**: This command fixes that by auto-creating the issue!

❌ Don't use when:

1. **Only want to sync GitHub (issue already exists)**: Use `sw-github:sync` instead 4. **Increment not started**: No tasks to sync yet 5. **Don't want auto-create**: Use `--no-create` flag or manual commands

---

How It Works

**Multi-Phase Orchestration**:

Phase 1: Tasks → ACs (spec.md)
  └─ Reads completed tasks from tasks.md
  └─ Finds linked ACs (via "Satisfies ACs" field)
  └─ Marks ACs as complete in spec.md: [ ] → [x]
  └─ Updates metadata.json with AC count

Phase 2: Spec → Living Docs (User Stories)
  └─ Syncs spec.md to living docs structure
  └─ Updates user story completion status
  └─ Generates/updates feature ID if needed

Phase 3: AUTO-CREATE External Issues (NEW!)
  ├─ Checks each configured external tool for linked issues
  ├─ If no issue exists → AUTO-CREATE via sw-github:create, sw-jira:create, sw-ado:create
  ├─ Respects permissions (canUpsertInternalItems, canUpdateExternalItems)
  └─ Skip with --no-create flag if needed

Phase 4: Sync to External Tools (Two-Way)
  ├─ GitHub: Two-way sync (push progress, pull team changes)
  ├─ JIRA: Two-way sync (push tasks, pull status)
  └─ Azure DevOps: Two-way sync (push comments, pull updates)

Phase 5: Status Line Cache
  └─ Updates status line with latest completion %

---

Usage Examples

Example 1: First-Time Sync (No GitHub Issue Yet) ⭐

**Scenario**: Just created increment, completed tasks, never created a GitHub issue. Want to sync.

# Single command does EVERYTHING
sw:sync-progress

**What happens**: 1. ✅ Tasks → ACs marked complete in spec.md 2. ✅ User stories synced to living docs 3. ✅ **GitHub issue AUTO-CREATED** (#123) 4. ✅ GitHub issue synced with task progress 5. ✅ Status line shows completion %

**No more "No GitHub issue linked" errors!**

Example 2: After Completing Tasks (Issue Exists)

**Scenario**: You completed 5 tasks and marked them in tasks.md. GitHub issue already exists.

# Single command syncs everything
sw:sync-progress

**What happens**: 1. ✅ 5 tasks → 12 ACs marked complete in spec.md 2. ✅ 2 user stories marked complete in living docs 3. ✅ GitHub issue #123 detected, synced with progress 4. ✅ Epic issue checklist updated (5/37 tasks complete) 5. ✅ Status line shows 68% → 85% completion

Example 3: Before Closing Increment

**Scenario**: All 37 tasks complete, ready to close. Ensure final sync.

# Final sync before closure
sw:sync-progress 0053

# Then close increment
sw:done 0053

**Why important**: `sw:done` validates completion. Final sync ensures:

• All ACs marked complete
• All user stories synced
• All GitHub issues closed
• Status line shows 100%

Example 4: Dry-Run (Preview Mode)

**Scenario**: Want to see what will be synced before executing.

# Preview mode
sw:sync-progress 0053 --dry-run

**Output**:

🔍 DRY-RUN MODE (No changes made)

Would sync:
   • 37 completed tasks → 70 ACs in spec.md
   • spec.md → 6 user stories in living docs
   • Living docs → 6 GitHub issues (would close completed)
   • Status line cache (would update completion %)

Run without --dry-run to execute sync.

Example 5: Local-Only Sync (No External Tools)

**Scenario**: Offline work, don't want to sync to GitHub/JIRA yet.

# Skip external tools
sw:sync-progress 0053 --no-github --no-jira --no-ado

**What syncs**:

• ✅ Tasks → ACs (spec.md)
• ✅ Spec → Living docs
• ❌ External to