specweave 0.23.8 → 0.23.12

package/plugins/specweave/skills/external-sync-wizard/SKILL.md

@@ -0,0 +1,610 @@
+---
+name: external-sync-wizard
+description: Expert guide for setting up bidirectional synchronization between SpecWeave and external tools (GitHub Issues, Jira Epics, Azure DevOps Work Items). Provides interactive setup wizards with sync direction options (bidirectional, export-only, import-only, manual). Activates for GitHub sync, Jira integration, Azure DevOps, ADO, external tool setup, issue tracking sync, sync configuration, bidirectional sync, import issues, export increments, sync direction, GitHub issues, Jira epics, work items, project management tools.
+---
+
+# External Sync Wizard Expert
+
+I'm a specialist in configuring synchronization between SpecWeave (your local source of truth) and external project management tools like GitHub Issues, Jira, and Azure DevOps.
+
+## When to Use This Skill
+
+Ask me when you need help with:
+- **Setting up GitHub Issues sync** with SpecWeave increments
+- **Configuring Jira Epic** integration
+- **Azure DevOps Work Items** synchronization
+- **Choosing sync direction** (bidirectional, export, import, manual)
+- **Understanding sync architecture** and source of truth principles
+- **Troubleshooting sync issues** or conflicts
+- **Migrating from external tools** to SpecWeave
+
+## My Expertise
+
+### SpecWeave's Sync Architecture
+
+**Critical Understanding**: `.specweave/docs/specs/` is the **permanent, local source of truth**. External tools (GitHub, Jira, ADO) are **MIRRORS** of this truth.
+
+#### Correct Sync Direction
+
+```
+✅ CORRECT Architecture:
+.specweave/docs/specs/  ↔  GitHub Issues
+.specweave/docs/specs/  ↔  Jira Epics
+.specweave/docs/specs/  ↔  Azure DevOps Work Items
+
+❌ WRONG (External-to-External):
+GitHub PRs  ↔  Jira
+GitHub Issues  ↔  Jira Epics
+```
+
+**The Hub is LOCAL**, not external!
+
+### Sync Direction Options
+
+When setting up sync, users choose from 4 options:
+
+| Option | Direction | Description | Use Case |
+|--------|-----------|-------------|----------|
+| **Bidirectional** | Local ↔ External | Changes sync **both ways** | Team collaboration (recommended) |
+| **Export only** | Local → External | Push **from Local to External** | SpecWeave is source of truth |
+| **Import only** | External → Local | Pull **from External to Local** | Onboarding existing projects |
+| **Manual sync** | On-demand | No auto-sync, use commands manually | Testing, one-off syncs |
+
+**Default recommendation**: **Bidirectional** (most useful for teams)
+
+---
+
+## Interactive Setup Wizards
+
+### GitHub Sync Setup
+
+#### Step 1: Authentication
+
+**Question**: "Do you want to sync increments to GitHub Issues?"
+
+**If YES** → Proceed to authentication setup:
+- Install GitHub CLI: `brew install gh` (macOS) or equivalent
+- Authenticate: `gh auth login`
+- Select repository: `gh repo set-default`
+
+**If NO** → Skip GitHub sync setup
+
+#### Step 2: Sync Direction
+
+**CRITICAL**: The prompt MUST say "between local increments and GitHub", NOT "between GitHub and Jira"!
+
+**Question**:
+```
+"What should be the sync behavior between local increments (.specweave/) and GitHub Issues?"
+```
+
+**Options**:
+
+**1. Bidirectional sync (Recommended)**
+```
+Local increments ↔ GitHub Issues
+
+Features:
+- Changes sync both ways automatically (on task completion)
+- Conflicts: You will be prompted to resolve when both sides change
+- Scope: Active increments only (completed/abandoned not auto-synced)
+- Example: Complete task in SpecWeave → GitHub issue updates with progress
+
+Best for: Teams using both SpecWeave and GitHub for project tracking
+```
+
+**2. Export only (Local → GitHub)**
+```
+Local increments → GitHub Issues
+
+Features:
+- SpecWeave is source of truth, GitHub is read-only mirror
+- Changes push from local to GitHub only
+- GitHub changes are ignored (must update locally)
+- Example: Create increment in SpecWeave → GitHub issue created automatically
+
+Best for: Solo developers who prefer SpecWeave but want GitHub visibility
+```
+
+**3. Import only (GitHub → Local)**
+```
+GitHub Issues → Local increments
+
+Features:
+- GitHub is source of truth, local workspace mirrors it
+- Changes pull from GitHub to local only
+- Good for: Onboarding existing GitHub projects
+- Example: Close GitHub issue → Local increment status updates
+
+Best for: Migrating from GitHub-first workflow to SpecWeave
+```
+
+**4. Manual sync only**
+```
+Use /specweave-github:sync command when needed
+
+Features:
+- No automatic sync via hooks
+- Full control over when sync happens
+- Good for: Testing, one-off syncs, experimental increments
+
+Best for: Advanced users who want explicit control
+```
+
+**Visual Aid** (include in prompt):
+```
+✅ CORRECT Architecture:
+Local (.specweave/) ↔ GitHub Issues
+
+❌ WRONG:
+GitHub ↔ Jira
+```
+
+#### Step 3: Auto-Create Issues
+
+**Question**: "Should SpecWeave auto-create GitHub issues when planning increments?"
+
+**Options**:
+
+**1. Yes, auto-create (Recommended)**
+```
+Every /specweave:increment creates a GitHub issue automatically
+
+Benefits:
+- Immediate team visibility
+- Bidirectional sync works from day 1
+- Zero manual work
+- Links: spec.md, plan.md, tasks.md included in issue
+
+Best for: Teams that want automatic GitHub integration
+```
+
+**2. No, manual creation**
+```
+Use /specweave-github:create-issue manually when needed
+
+Benefits:
+- Create issues only for important increments
+- More control over what goes to GitHub
+- Good for: Experimental/internal increments
+
+Best for: Solo developers or selective GitHub usage
+```
+
+---
+
+### Jira Sync Setup
+
+#### Step 1: Authentication
+
+**Question**: "Do you want to sync increments to Jira Epics?"
+
+**If YES** → Proceed to authentication setup:
+- Jira domain: `your-company.atlassian.net`
+- API token: Generate from Jira settings
+- Email: Your Jira account email
+- Project key: `PROJ` (e.g., `AUTH`, `PAY`, `INFRA`)
+
+**If NO** → Skip Jira sync setup
+
+#### Step 2: Sync Direction
+
+**Question**:
+```
+"What should be the sync behavior between local increments (.specweave/) and Jira Epics?"
+```
+
+**Options**:
+
+**1. Bidirectional sync (Recommended)**
+```
+Local increments ↔ Jira Epics
+
+Features:
+- Changes sync both ways automatically (on task completion)
+- Conflicts: You will be prompted to resolve when both sides change
+- Scope: Active increments only
+- Example: Complete task in SpecWeave → Jira epic status updates
+
+Best for: Teams using both SpecWeave and Jira for project management
+```
+
+**2. Export only (Local → Jira)**
+```
+Local increments → Jira Epics
+
+Features:
+- SpecWeave is source of truth, Jira is read-only mirror
+- Changes push from local to Jira only
+- Jira changes are ignored (must update locally)
+- Example: Create increment in SpecWeave → Jira epic created automatically
+
+Best for: Developers who prefer SpecWeave but need Jira reporting
+```
+
+**3. Import only (Jira → Local)**
+```
+Jira Epics → Local increments
+
+Features:
+- Jira is source of truth, local workspace mirrors it
+- Changes pull from Jira to local only
+- Good for: Onboarding existing Jira projects
+- Example: Update Jira epic → Local increment syncs
+
+Best for: Migrating from Jira-first workflow to SpecWeave
+```
+
+**4. Manual sync only**
+```
+Use /specweave-jira:sync command when needed
+
+Features:
+- No automatic sync via hooks
+- Full control over when sync happens
+
+Best for: Advanced users or testing scenarios
+```
+
+---
+
+### Azure DevOps Sync Setup
+
+#### Step 1: Authentication
+
+**Question**: "Do you want to sync increments to Azure DevOps work items?"
+
+**If YES** → Proceed to authentication setup:
+- Organization URL: `https://dev.azure.com/your-org`
+- Personal Access Token (PAT): Generate from ADO settings
+- Project name: `MyProject`
+- Area path: (optional) for multi-team organizations
+
+**If NO** → Skip ADO sync setup
+
+#### Step 2: Sync Direction
+
+**Question**:
+```
+"What should be the sync behavior between local increments (.specweave/) and Azure DevOps work items?"
+```
+
+**Options**:
+
+**1. Bidirectional sync (Recommended)**
+```
+Local increments ↔ ADO Work Items
+
+Features:
+- Changes sync both ways automatically (on task completion)
+- Conflicts: You will be prompted to resolve when both sides change
+- Scope: Active increments only
+- Example: Complete task in SpecWeave → ADO work item updates
+
+Best for: Enterprise teams using Azure DevOps
+```
+
+**2. Export only (Local → ADO)**
+```
+Local increments → ADO Work Items
+
+Features:
+- SpecWeave is source of truth, ADO is read-only mirror
+- Changes push from local to ADO only
+- ADO changes are ignored (must update locally)
+- Example: Create increment in SpecWeave → ADO work item created automatically
+
+Best for: Developers who prefer SpecWeave with ADO visibility
+```
+
+**3. Import only (ADO → Local)**
+```
+ADO Work Items → Local increments
+
+Features:
+- ADO is source of truth, local workspace mirrors it
+- Changes pull from ADO to local only
+- Good for: Onboarding existing ADO projects
+- Example: Update ADO work item → Local increment syncs
+
+Best for: Migrating from ADO-first workflow to SpecWeave
+```
+
+**4. Manual sync only**
+```
+Use /specweave-ado:sync command when needed
+
+Features:
+- No automatic sync via hooks
+- Full control over when sync happens
+
+Best for: Advanced users or selective sync scenarios
+```
+
+---
+
+## Implementation Notes
+
+### When Generating Increment Planning Wizard
+
+1. ✅ Check `config.plugins.enabled` array
+2. ✅ ONLY ask about enabled plugins (GitHub/Jira/ADO)
+3. ✅ For each enabled plugin, ask: "Local ↔ [Provider]" sync direction
+4. ❌ NEVER ask about external-to-external sync (e.g., "GitHub ↔ Jira")
+
+### Configuration Storage
+
+**Secrets** (`.env` - gitignored):
+```bash
+# GitHub
+GITHUB_TOKEN=ghp_xxx
+
+# Jira
+JIRA_API_TOKEN=xxx
+JIRA_EMAIL=user@example.com
+
+# Azure DevOps
+ADO_PAT=xxx
+```
+
+**Configuration** (`.specweave/config.json` - committed to git):
+```json
+{
+  "plugins": {
+    "enabled": ["github", "jira", "ado"]
+  },
+  "sync": {
+    "github": {
+      "enabled": true,
+      "direction": "bidirectional",
+      "autoCreateIssue": true,
+      "repo": "owner/repo"
+    },
+    "jira": {
+      "enabled": true,
+      "direction": "bidirectional",
+      "domain": "company.atlassian.net",
+      "projectKey": "PROJ"
+    },
+    "ado": {
+      "enabled": true,
+      "direction": "export-only",
+      "organization": "your-org",
+      "project": "MyProject"
+    }
+  }
+}
+```
+
+---
+
+## Sync Workflows
+
+### Bidirectional Sync (Automatic)
+
+**Trigger**: Task completion hook (`post-task-completion.sh`)
+
+**Flow**:
+1. User completes task in SpecWeave → `tasks.md` updated
+2. Hook detects change → Reads increment metadata
+3. If GitHub enabled → Updates GitHub issue with progress
+4. If Jira enabled → Updates Jira epic status
+5. If ADO enabled → Updates ADO work item
+
+**Conflict Resolution**:
+- If both local and external changed → Prompt user to resolve
+- Show diff: Local changes vs External changes
+- User chooses: Keep local, Keep external, or Merge
+
+### Export-Only Sync
+
+**Trigger**: Task completion hook
+
+**Flow**:
+1. User completes task in SpecWeave
+2. Hook pushes changes to external tool
+3. External tool changes are ignored (one-way flow)
+
+**Use Case**: SpecWeave is the authoritative source, external tools are read-only mirrors
+
+### Import-Only Sync
+
+**Trigger**: Manual `/specweave-[tool]:sync` command
+
+**Flow**:
+1. User runs sync command
+2. Fetch changes from external tool
+3. Update local increments with external data
+4. Local changes are NOT pushed (one-way flow)
+
+**Use Case**: Onboarding existing projects from external tools
+
+### Manual Sync
+
+**Trigger**: Explicit command
+
+**Flow**:
+1. User runs `/specweave-github:sync [increment-id]`
+2. Choose direction: pull, push, or bidirectional
+3. Execute sync operation
+4. Report results to user
+
+**Use Case**: Testing, one-off syncs, advanced control
+
+---
+
+## Common Questions
+
+### Q: What happens if I have GitHub and Jira both enabled?
+
+**A**: SpecWeave syncs to BOTH independently:
+```
+.specweave/docs/specs/ ↔ GitHub Issues
+.specweave/docs/specs/ ↔ Jira Epics
+```
+
+GitHub and Jira do NOT sync with each other. SpecWeave is the hub.
+
+### Q: Can I change sync direction later?
+
+**A**: Yes! Edit `.specweave/config.json`:
+```json
+{
+  "sync": {
+    "github": {
+      "direction": "export-only"  // Change from bidirectional
+    }
+  }
+}
+```
+
+### Q: What if I delete a GitHub issue manually?
+
+**A**: Depends on sync direction:
+- **Bidirectional**: SpecWeave increment marked as deleted (soft delete)
+- **Export-only**: GitHub issue recreated on next sync
+- **Import-only**: Local increment deleted
+- **Manual**: No effect until manual sync
+
+### Q: How do I onboard an existing GitHub project?
+
+**A**:
+1. Set sync direction: **Import-only**
+2. Run: `/specweave-github:import-all`
+3. SpecWeave creates increments from GitHub issues
+4. Review and adjust as needed
+5. Switch to **Bidirectional** when ready
+
+### Q: Can I sync only specific increments?
+
+**A**: Yes! Use manual sync:
+```bash
+/specweave-github:sync 0042-auth-feature  # Sync specific increment
+```
+
+Auto-sync only affects **active** increments (not completed/abandoned).
+
+---
+
+## Troubleshooting
+
+### Issue: GitHub issue not created after `/specweave:increment`
+
+**Diagnosis**:
+1. Check GitHub CLI: `gh auth status`
+2. Check config: `.specweave/config.json` → `sync.github.autoCreateIssue: true`
+3. Check metadata: `.specweave/increments/####/metadata.json` has `github` section
+
+**Fix**:
+```bash
+# Manual creation
+/specweave-github:create-issue 0042-auth-feature
+```
+
+### Issue: Jira epic not updating
+
+**Diagnosis**:
+1. Check Jira credentials in `.env`
+2. Check Jira domain and project key in `config.json`
+3. Check sync direction (must be bidirectional or export-only)
+4. Check hook logs: `.specweave/logs/sync-*.log`
+
+**Fix**:
+```bash
+# Manual sync
+/specweave-jira:sync 0042-auth-feature --force
+```
+
+### Issue: Conflict during bidirectional sync
+
+**Diagnosis**:
+- Both local and external modified the same field (e.g., status)
+
+**Resolution Options**:
+1. **Keep local**: Local changes overwrite external
+2. **Keep external**: External changes overwrite local
+3. **Merge**: Apply both changes (manual resolution)
+
+**Example**:
+```
+⚠️  Conflict detected for increment 0042-auth-feature
+
+Field: status
+Local value: in-progress
+GitHub value: completed
+
+Choose resolution:
+1. Keep local (in-progress)
+2. Keep external (completed)
+3. Merge manually
+
+Your choice:
+```
+
+---
+
+## Best Practices
+
+### 1. Start with Bidirectional
+
+Most teams benefit from bidirectional sync:
+- Developers update in SpecWeave
+- PMs/stakeholders track progress in GitHub/Jira
+- Changes sync automatically
+
+### 2. Use Export-Only for Solo Projects
+
+If you're working alone and just need GitHub visibility:
+- Set direction: export-only
+- SpecWeave is your source of truth
+- GitHub is a read-only mirror
+
+### 3. Import-Only for Onboarding
+
+When migrating from GitHub/Jira to SpecWeave:
+1. Start with import-only
+2. Pull all existing work into SpecWeave
+3. Review and clean up
+4. Switch to bidirectional once confident
+
+### 4. Manual Sync for Testing
+
+When experimenting or testing:
+- Disable auto-sync
+- Use manual commands
+- Verify behavior before enabling auto-sync
+
+### 5. One Source of Truth
+
+**Golden Rule**: Never manually edit the same field in both SpecWeave and external tool simultaneously.
+
+**Example**:
+- ❌ WRONG: Update task status in SpecWeave AND GitHub manually
+- ✅ CORRECT: Update in SpecWeave, let sync propagate to GitHub
+
+---
+
+## Related Slash Commands
+
+### GitHub
+- `/specweave-github:sync [increment-id]` - Manual sync
+- `/specweave-github:create-issue [increment-id]` - Create issue
+- `/specweave-github:close-issue [increment-id]` - Close issue
+- `/specweave-github:import-all` - Import all GitHub issues
+- `/specweave-github:status [increment-id]` - Check sync status
+
+### Jira
+- `/specweave-jira:sync [increment-id]` - Manual sync
+- `/specweave-jira:create-epic [increment-id]` - Create epic
+- `/specweave-jira:import-all` - Import all Jira epics
+- `/specweave-jira:status [increment-id]` - Check sync status
+
+### Azure DevOps
+- `/specweave-ado:sync [increment-id]` - Manual sync
+- `/specweave-ado:create-workitem [increment-id]` - Create work item
+- `/specweave-ado:import-all` - Import all ADO work items
+- `/specweave-ado:status [increment-id]` - Check sync status
+
+---
+
+**Remember**: SpecWeave is your local source of truth. External tools are mirrors. Sync is about keeping mirrors up-to-date, not managing dual sources of truth.