github-sync

# GitHub Sync - Two-way Spec ↔ Project Synchronization

**Purpose**: Seamlessly synchronize SpecWeave specs with GitHub Projects for team visibility and project management.

**Default Behavior**: **Two-way sync** (push & pull) - Changes in either system are automatically synchronized

**⚠️ IMPORTANT**: This skill provides HELP and GUIDANCE about GitHub sync. For actual syncing, users should use the `/sw-github:sync-spec` command directly. This skill should NOT auto-activate when the command is being invoked.

## When to Activate

✅ **Do activate when**:
- User asks: "How do I set up GitHub sync?"
- User asks: "What GitHub credentials do I need?"
- User asks: "How does the GitHub integration work?"
- User needs help configuring GitHub integration

❌ **Do NOT activate when**:
- User invokes `/sw-github:sync-spec` command (command handles it)
- Command is already running (avoid duplicate invocation)
- Task completion hook is syncing (automatic process)

**Integration**: Works with `/sw-github:sync-spec` command

---

## CORRECT Architecture

**CRITICAL**: SpecWeave syncs **SPECS** to GitHub, NOT increments!

```
✅ CORRECT:
.specweave/docs/internal/specs/spec-001.md  ↔  GitHub Project
├─ User Story US-001                        ↔  GitHub Issue #1
├─ User Story US-002                        ↔  GitHub Issue #2
└─ User Story US-003                        ↔  GitHub Issue #3

❌ WRONG (OLD, REMOVED!):
.specweave/increments/0001-feature  ↔  GitHub Issue (DEPRECATED!)
```

**Why Specs, Not Increments?**
- ✅ **Specs = Permanent** (living docs, feature-level knowledge base)
- ❌ **Increments = Temporary** (implementation snapshots, can be deleted after done)
- ✅ **GitHub should mirror PERMANENT work**, not temporary iterations

---

## How GitHub Sync Works

### 1. Spec → GitHub Project (Export)

**Trigger**: When spec is created or updated

**Actions**:
1. Create GitHub Project with:
   - Title: `[SPEC-001] Core Framework & Architecture`
   - Description: Spec overview + progress