Comprehensive progress synchronization expert. Explains when and how to use /sw:sync-progress for multi-system sync (tasks → docs → external tools). Activates for sync progress, update progress, sync everything, sync all systems, sync to GitHub, sync to JIRA, how to sync, progress synchronization, multi-system sync.
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
I'm the comprehensive progress synchronization expert for SpecWeave. I help you understand and use the /sw:sync-progress command for end-to-end progress synchronization.
The "single button" to sync progress across all systems:
tasks.md → spec.md ACs → living docs → external tools (GitHub/JIRA/ADO)
One command, complete synchronization:
/sw:sync-progress
/sw:done to ensure all systems in sync/sw:sync-acs instead (faster, more targeted)/sw:sync-specs instead/sw-github:sync insteadMulti-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: Living Docs → External Tools
├─ GitHub: Closes completed user story issues, updates epic checklist
├─ JIRA: Updates story status, transitions workflow
└─ Azure DevOps: Updates work item state, comments
Phase 4: Status Line Cache
└─ Updates status line with latest completion %
Scenario: You completed 5 tasks and marked them in tasks.md. Now sync everywhere.
# Single command syncs everything
/sw:sync-progress
What happens:
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:
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.
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:
| Flag | Purpose | Example |
|---|---|---|
--dry-run | Preview without executing | --dry-run |
--no-github | Skip GitHub sync | --no-github |
--no-jira | Skip JIRA sync | --no-jira |
--no-ado | Skip Azure DevOps sync | --no-ado |
--force | Force sync even if validation fails | --force |
Combine flags:
# Dry-run with no external tools
/sw:sync-progress --dry-run --no-github
# Force sync, skip GitHub
/sw:sync-progress --force --no-github
| Command | Scope | When to Use |
|---|---|---|
/sw:sync-acs | Tasks → ACs only | Quick AC update |
/sw:sync-specs | Spec → Docs only | After spec changes |
/sw-github:sync | Docs → GitHub only | GitHub-only sync |
/sw:sync-progress | Tasks → Docs → External | Complete sync ✅ |
Rule of thumb:
sync-acs, sync-specs)/sw:sync-progress ✅Smart increment detection:
# Explicit increment ID
/sw:sync-progress 0053
# Auto-detect from active increment
/sw:sync-progress
How auto-detection works:
.specweave/state/active-increment.jsonAutomatic detection of configured tools:
The command checks .specweave/config.json for:
"provider": "github""provider": "jira""provider": "azure-devops"Only configured tools are synced:
✅ GitHub integration detected → Will sync
ℹ️ No JIRA integration → Skip
ℹ️ No ADO integration → Skip
Graceful degradation:
| Error Type | Behavior | Impact |
|---|---|---|
| AC sync fails | ❌ Abort sync | Critical - blocks all sync |
| Docs sync fails | ❌ Abort sync | Critical - blocks external sync |
| GitHub sync fails | ⚠️ Log warning, continue | Non-critical - docs still synced |
| JIRA sync fails | ⚠️ Log warning, continue | Non-critical - docs still synced |
| ADO sync fails | ⚠️ Log warning, continue | Non-critical - docs still synced |
Philosophy: Core sync (tasks → docs) must succeed. External tool sync is best-effort.
Error:
❌ No active increment found
Fix:
# Provide increment ID explicitly
/sw:sync-progress 0053
Error:
⚠️ AC sync had warnings: 5 ACs not found in spec.md
Fix:
# Embed ACs from living docs into spec.md
/sw:embed-acs 0053
# Then retry sync
/sw:sync-progress 0053
Why this happens: spec.md missing inline ACs (ADR-0064 requirement).
Error:
⚠️ GitHub sync had warnings: Rate limit exceeded
Fix: Non-critical. Docs are synced. Retry later when rate limit resets:
# Retry GitHub sync only (when rate limit resets)
/sw-github:sync 0053
Typical increment workflow with progress sync:
# 1. Plan increment
/sw:increment "Safe feature deletion"
# 2. Execute tasks
/sw:do
# [Complete tasks manually or via sub-agents...]
# 3. Sync progress after each batch of tasks
/sw:sync-progress
# 4. Final sync before closure
/sw:sync-progress 0053
# 5. Validate quality
/sw:validate 0053 --quality
# 6. Close increment
/sw:done 0053
/sw:done--dry-run/sw:done--force bypasses validationWhy comprehensive sync is needed:
Problem: Manual multi-step sync is error-prone
1. Update spec.md ACs manually
2. Run /sw:sync-specs
3. Run /sw-github:sync
4. Run /sw:update-status
5. Check each system for correctness
Solution: Single command orchestrates all steps
/sw:sync-progress → Does all 4 steps automatically
Benefits:
Version: v0.25.0+ Increment: 0053-safe-feature-deletion ADR: None yet (new feature)
Context: Before this command, users had to manually:
/sw:sync-acs/sw:sync-specs/sw-github:sync/sw:update-statusNow: One command does all 4 steps ✅
/sw:sync-acs - Sync tasks → ACs only/sw:sync-specs - Sync spec → living docs only/sw:sync-tasks - Sync external → tasks (bidirectional)/sw-github:sync - Sync docs → GitHub only/sw-jira:sync - Sync docs → JIRA only/sw-ado:sync - Sync docs → ADO only/sw:update-status - Update status line cacheI'm here to help you sync progress efficiently across all systems!
Ask me: