Initial commit

2025-11-29 17:56:38 +08:00
commit 712abd45e8
19 changed files with 5806 additions and 0 deletions
--- a/commands/specweave-github-sync.md
+++ b/commands/specweave-github-sync.md
@@ -0,0 +1,674 @@
+---
+name: specweave-github:sync
+description: Synchronize SpecWeave increment with GitHub issue (Multi-Project Support). Select profile, configure time range, and sync with rate limit protection.
+---
+
+# Sync Increment with GitHub Issue (Multi-Project)
+
+## ⚠️ CRITICAL: Sync Routing (Read First!)
+
+**Before executing ANY sync, you MUST determine the correct sync path:**
+
+### Step 0: Detect Project Structure
+
+```bash
+# Check for living docs structure
+if [ -d ".specweave/docs/internal/specs" ] && [ -n "$(ls -A .specweave/docs/internal/specs/*/FEATURE.md 2>/dev/null)" ]; then
+    echo "✅ Living docs found → Use Feature Sync"
+else
+    echo "⚠️ No living docs → Use Increment Sync (brownfield)"
+fi
+```
+
+### Sync Path Decision:
+
+| Structure | Command | Issue Format |
+|-----------|---------|--------------|
+| **Living docs exist** (`.specweave/docs/internal/specs/FS-XXX/`) | Use `github-feature-sync-cli.ts` | `[FS-XXX][US-YYY] Title` |
+| **Increment only** (brownfield, no living docs) | Use `github-increment-sync-cli.ts` | `[FS-XXX] Title` with ACs |
+
+### For Brownfield Projects (No Living Docs):
+
+Use the Increment Sync CLI directly:
+
+```bash
+# Set token
+export GITHUB_TOKEN=$(grep GITHUB_TOKEN .env | cut -d'=' -f2)
+
+# Run increment sync
+node dist/plugins/specweave-github/lib/github-increment-sync-cli.js <increment-id>
+
+# Example
+node dist/plugins/specweave-github/lib/github-increment-sync-cli.js 0002
+```
+
+This creates issues with:
+- ✅ Proper format: `[FS-002] Increment Title`
+- ✅ User Stories listed with checkbox headers
+- ✅ All ACs as checkable items
+- ✅ Links to increment files
+
+### For Projects with Living Docs:
+
+Use the Feature Sync CLI:
+
+```bash
+# Run feature sync
+node dist/plugins/specweave-github/lib/github-feature-sync-cli.js <feature-id>
+
+# Example
+node dist/plugins/specweave-github/lib/github-feature-sync-cli.js FS-062
+```
+
+---
+
+Synchronize the current state of a SpecWeave increment with its GitHub issue across multiple repositories. Supports multi-profile management, time range filtering, and rate limit protection.
+
+## Usage
+
+```bash
+/specweave-github:sync <increment-id> [options]
+```
+
+## Arguments
+
+- `increment-id`: Increment ID (e.g., `0004` or `0004-plugin-architecture`)
+
+## Options
+
+### Sync Options
+- `--profile <id>`: Use specific sync profile (skip selection prompt)
+- `--time-range <preset>`: Time range for sync (`1W`, `2W`, `1M`, `3M`, `6M`, `1Y`, `ALL`)
+- `--tasks`: Update task checklist in issue body
+- `--comment`: Post progress comment (default)
+- `--labels`: Update issue labels based on status
+- `--force`: Force sync even if up-to-date
+- `--direction`: Sync direction (`to-github`, `from-github`, `two-way` - **default: two-way**)
+- `--all`: Sync all active increments
+
+### Safety Options
+- `--dry-run`: Preview changes without applying
+- `--skip-rate-check`: Skip rate limit validation (not recommended)
+
+## Sync Direction
+
+**Default: Two-way** (both directions)
+
+SpecWeave syncs changes in **both directions** by default:
+
+| Direction | What It Does | Use When |
+|-----------|-------------|----------|
+| **`two-way`** (default) | SpecWeave ↔ GitHub<br>• Pull changes FROM GitHub (status, labels, comments)<br>• Push changes TO GitHub (tasks, progress, metadata) | **Always** (recommended for keeping both systems in sync) |
+| `to-github` | SpecWeave → GitHub only<br>• Push increment progress to GitHub<br>• Don't pull GitHub changes back | Read-only GitHub usage, or when GitHub is downstream |
+| `from-github` | GitHub → SpecWeave only<br>• Pull GitHub issue updates<br>• Don't push SpecWeave changes | Importing GitHub issues, or when SpecWeave is downstream |
+
+**Why Two-way?**
+- ✅ Keep both systems synchronized automatically
+- ✅ GitHub status changes update SpecWeave (closed issue → completed increment)
+- ✅ SpecWeave task completion updates GitHub (task done → checklist updated)
+- ✅ Team members can work in either tool
+- ✅ No data loss from changes in either system
+
+**Override if needed:**
+```bash
+# Push only (one-way to GitHub)
+/specweave-github:sync 0004 --direction to-github
+
+# Pull only (one-way from GitHub)
+/specweave-github:sync 0004 --direction from-github
+```
+
+## Examples
+
+```bash
+# Interactive two-way sync (default - both directions)
+/specweave-github:sync 0004
+
+# Use specific profile (still two-way by default)
+/specweave-github:sync 0004 --profile specweave-dev
+
+# Specify time range (two-way)
+/specweave-github:sync 0004 --time-range 1M
+
+# Full two-way sync with all options
+/specweave-github:sync 0004 --profile main --time-range 1M --tasks --labels
+
+# One-way sync examples (override default)
+/specweave-github:sync 0004 --direction to-github     # Push only
+/specweave-github:sync 0004 --direction from-github   # Pull only
+
+# Dry run to preview changes
+/specweave-github:sync 0004 --dry-run
+
+# Force sync all increments (two-way)
+/specweave-github:sync --all --force
+```
+
+## Interactive Workflow
+
+### Step 1: Profile Selection
+
+If multiple GitHub profiles exist, you'll be prompted to select one:
+
+```
+🔗 Select GitHub Profile
+
+Available profiles:
+
+  1. specweave-dev
+     └─ 🐙 GitHub: anton-abyzov/specweave
+     └─ Main SpecWeave repository
+     └─ Default time range: 1 month (max: 6 months)
+
+  2. another-repo
+     └─ 🐙 GitHub: myorg/another-project
+     └─ Another project repository
+     └─ Default time range: 1 month (max: 6 months)
+
+  3. ✨ Create new profile
+
+Your choice: [1]
+```
+
+### Step 2: Time Range Selection
+
+Choose how far back to fetch GitHub data:
+
+```
+📅 Select Time Range for Sync
+
+⚠️  IMPORTANT: Time range affects sync performance and rate limits
+
+📅 GitHub Rate Limits:
+   • Limit: 5,000 requests per 1h
+   • Current: 4,850/5,000 (97% available)
+   • Resets: 3:00:00 PM (25 min)
+
+Select time range:
+
+  1. Last 1 week
+     └─ ~50 items | 75 API calls | ⚡ 30 sec | Rate: LOW (1.5%)
+
+  2. Last 2 weeks
+     └─ ~100 items | 150 API calls | ⚡ 1 min | Rate: LOW (3%)
+
+  3. Last 1 month  ← Recommended
+     └─ ~200 items | 300 API calls | ⚡ 2 min | Rate: LOW (6%)
+
+  4. Last 3 months
+     └─ ~600 items | 900 API calls | ⚠️  5 min | Rate: MEDIUM (18%)
+
+  5. Last 6 months
+     └─ ~1,200 items | 1,800 API calls | ⚠️  10 min | Rate: HIGH (36%)
+
+  6. All time
+     └─ ~5,000 items | 7,500 API calls | ❌ 30+ min | Rate: CRITICAL (150%)
+     └─ ⚠️  WARNING: Will exceed rate limit! Not recommended.
+
+Your choice: [3]
+```
+
+### Step 3: Sync Preview
+
+Before executing, you'll see a preview:
+
+```
+📊 Sync Preview:
+
+   Profile: specweave-dev (GitHub)
+   └─ Repository: anton-abyzov/specweave
+   └─ Time range: Last 1 month (2025-10-04 to 2025-11-04)
+
+   Estimated sync:
+   ├─ Work items: ~187 issues/PRs
+   ├─ API calls: ~280 requests
+   ├─ Duration: ~2 minutes
+   └─ Rate limit: Low impact (5.6% of hourly limit)
+
+   GitHub rate limit (BEFORE sync):
+   ├─ Current: 4,850/5,000 (97% available)
+   ├─ After sync: ~4,570/5,000 (91% available)
+   └─ Reset: 3:00:00 PM (25 min)
+
+✅ This sync is SAFE to proceed
+
+Continue with sync? [Y/n]:
+```
+
+### Step 4: Execution
+
+If confirmed, sync proceeds with progress updates:
+
+```
+🔄 Two-way sync for increment 0004...
+
+✓ Profile loaded: specweave-dev
+✓ GitHub repository: anton-abyzov/specweave
+✓ Rate limit check: PASSED (4,850/5,000 remaining)
+✓ Sync direction: Two-way (push & pull)
+
+Fetching increment state...
+✓ Increment loaded: 0004-plugin-architecture
+✓ GitHub issue: #130
+✓ Last synced: 30 minutes ago
+
+Detecting changes (both directions)...
+
+FROM GitHub:
+✓ Issue status changed: open → closed
+✓ Label added: ready-for-release
+✓ 2 new comments from team
+
+FROM SpecWeave:
+✓ 3 new tasks completed (T-005, T-006, T-007)
+✓ Progress: 4/48 → 7/48 (15%)
+✓ Current task: T-008
+
+Syncing TO GitHub...
+✓ Posted progress comment (ID: 1234567)
+✓ Updated task checklist (7 tasks marked complete)
+✓ Updated labels: +in-progress
+✓ Metadata updated
+
+Syncing FROM GitHub...
+✓ Updated increment status: active → completed
+✓ Applied label: ready-for-release
+✓ Imported 2 team comments to increment notes
+
+Rate limit after sync: 4,570/5,000 (91% available)
+
+✅ Two-way Sync Complete!
+
+   SpecWeave ↔ GitHub synchronized
+   • Pushed: 3 task updates, progress comment
+   • Pulled: Status change, label, 2 comments
+
+GitHub Issue: https://github.com/anton-abyzov/specweave/issues/130
+Last synced: just now
+Next sync: Automatic (hook-based) or manual when ready
+```
+
+## Key Features
+
+- **Multi-Profile Support**: Unlimited GitHub repos (3+, 5+, 10+ profiles)
+- **Flexible Syncing**: Different increments can sync to different repos
+  - Increment 0001 → anton-abyzov/specweave
+  - Increment 0002 → client-org/mobile-app
+  - Increment 0003 → internal-org/infrastructure
+- **Time Range Filtering**: Fast syncs (2 min vs 25+ min)
+- **Rate Limit Protection**: 95%+ success rate with smart estimates
+- **Smart Estimates**: Preview impact before every sync
+
+## Configuration
+
+### Sync Profiles
+
+Configure profiles in `.specweave/config.json`:
+
+```json
+{
+  "sync": {
+    "activeProfile": "specweave-dev",
+    "profiles": {
+      "specweave-dev": {
+        "provider": "github",
+        "displayName": "SpecWeave Development",
+        "config": {
+          "owner": "anton-abyzov",
+          "repo": "specweave"
+        },
+        "timeRange": {
+          "default": "1M",
+          "max": "6M"
+        },
+        "rateLimits": {
+          "maxItemsPerSync": 500,
+          "warnThreshold": 100
+        }
+      },
+      "another-repo": {
+        "provider": "github",
+        "displayName": "Another Repository",
+        "config": {
+          "owner": "myorg",
+          "repo": "another-project"
+        },
+        "timeRange": {
+          "default": "2W",
+          "max": "3M"
+        }
+      }
+    },
+    "settings": {
+      "autoDetectProject": true,
+      "defaultTimeRange": "1M",
+      "rateLimitProtection": true
+    }
+  }
+}
+```
+
+### Credentials
+
+Store credentials in `.env` (never committed):
+
+```env
+# GitHub
+GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
+```
+
+### Per-Increment Configuration
+
+Each increment stores its sync metadata in `.specweave/increments/{id}/metadata.json`:
+
+```json
+{
+  "id": "0004-plugin-architecture",
+  "sync": {
+    "profile": "specweave-dev",
+    "issueNumber": 130,
+    "issueUrl": "https://github.com/anton-abyzov/specweave/issues/130",
+    "timeRange": "1M",
+    "createdAt": "2025-10-15T10:00:00Z",
+    "lastSyncAt": "2025-11-04T14:30:00Z",
+    "status": "active"
+  }
+}
+```
+
+## Rate Limiting Protection
+
+### What It Does
+
+Before every sync:
+1. **Estimates API calls** based on time range and project size
+2. **Checks current rate limit** via GitHub API
+3. **Calculates impact** (low/medium/high/critical)
+4. **Validates safety** (will it exceed limit?)
+5. **Warns user** if risky operation detected
+
+### Impact Levels
+
+| Impact | API Calls | Duration | Safe? | Example Time Range |
+|--------|-----------|----------|-------|-------------------|
+| **Low** | <250 | <2 min | ✅ Yes | 1 week, 2 weeks, 1 month |
+| **Medium** | 250-1000 | 2-5 min | ⚠️  Maybe | 3 months |
+| **High** | 1000-2500 | 5-15 min | ⚠️  Risky | 6 months, 1 year |
+| **Critical** | 2500+ | 15+ min | ❌ No | All time |
+
+### Protection Actions
+
+**Low/Medium Impact** → Proceed with optional warning
+**High Impact** → Warn user, require confirmation
+**Critical Impact** → Block sync, show recommendations
+
+### Example: Critical Impact Blocked
+
+```
+❌ This sync may FAIL due to:
+
+Blockers:
+   • CRITICAL rate limit impact: 7,500 API calls exceeds safe threshold for github
+   • Not enough rate limit remaining. Need 7,500 calls, only 4,850 remaining.
+     Reset at 2025-11-04 15:00:00
+
+Recommendations:
+   1. Reduce time range to 1 month (~300 API calls, SAFE)
+   2. Wait for rate limit reset (25 minutes)
+   3. Split sync across multiple time periods
+
+Sync cancelled. Please adjust and try again.
+```
+
+## Error Handling
+
+### Profile Not Found
+
+```
+❌ Error: Sync profile 'unknown-profile' not found
+
+Available profiles:
+  • specweave-dev (GitHub: anton-abyzov/specweave)
+  • another-repo (GitHub: myorg/another-project)
+
+Create profile: /specweave:sync-profile create
+List profiles: /specweave:sync-profile list
+```
+
+### No Profiles Configured
+
+```
+❌ Error: No GitHub sync profiles configured
+
+Create your first profile:
+  /specweave:sync-profile create
+
+Or migrate from old configuration:
+  specweave migrate-to-profiles
+```
+
+### Rate Limit Exceeded During Sync
+
+```
+⚠️  GitHub API rate limit exceeded during sync
+
+Synced: 127/187 items (68%)
+Remaining: 60 items
+Rate limit resets: 2025-11-04 15:00:00 (12 minutes)
+
+What would you like to do?
+
+  1. Wait and resume (auto-resume in 12 min)
+  2. Resume manually later (/specweave-github:sync 0004 --resume)
+  3. Cancel sync (partial data saved)
+
+Your choice: [1]
+```
+
+### Network Error with Retry
+
+```
+❌ Error: Network error while syncing to GitHub
+
+Failed to connect to GitHub API.
+Synced: 45/187 items before error
+
+Retry options:
+  1. Retry immediately
+  2. Retry with exponential backoff (recommended)
+  3. Cancel and retry manually later
+
+Your choice: [2]
+
+Retrying in 5 seconds...
+Retrying in 10 seconds...
+✓ Connection restored! Resuming sync...
+```
+
+## First-Time Setup
+
+### Automatic Profile Creation
+
+Run migration script:
+
+```bash
+specweave migrate-to-profiles
+```
+
+Output:
+```
+🔍 Detected old configuration:
+   GitHub: Yes
+
+✅ Backed up old configuration to .specweave/config.json.backup
+
+✅ Created GitHub profile: default-github
+   Repository: anton-abyzov/specweave
+
+✅ Created default project context
+   Name: specweave
+   Default profile: default-github
+
+📊 Migration Summary:
+   Profiles created: 1
+   Projects created: 1
+   Warnings: 0
+   Errors: 0
+
+✅ Migration completed successfully!
+
+Next steps:
+  1. Review profiles: /specweave:sync-profile list
+  2. Test sync: /specweave-github:sync 0004
+  3. Keep backup: .specweave/config.json.backup (until confirmed working)
+```
+
+### Manual Setup
+
+If automatic profile creation fails:
+
+1. Create profile manually:
+   ```bash
+   /specweave:sync-profile create
+   ```
+
+2. Update increment metadata:
+   ```json
+   {
+     "sync": {
+       "profile": "default-github",
+       "issueNumber": 130
+     }
+   }
+   ```
+
+3. Test sync:
+   ```bash
+   /specweave-github:sync 0004
+   ```
+
+## Related Commands
+
+- `/specweave-github:create-issue <increment-id>`: Create issue with profile selection
+- `/specweave-github:close-issue <increment-id>`: Close issue
+- `/specweave-github:status <increment-id>`: Check sync status
+- `/specweave:sync-profile create`: Create new sync profile
+- `/specweave:sync-profile list`: List all profiles
+
+## Tips & Best Practices
+
+### 1. Choose the Right Time Range
+
+**For Active Projects**:
+- Use `1M` (1 month) - Balances completeness and performance
+- Daily syncs: `1W` (fast, <1 min)
+
+**For Historical Analysis**:
+- Use `3M` or `6M` with caution (check rate limits first)
+- Never use `ALL` unless absolutely necessary
+
+### 2. Monitor Rate Limits
+
+Check before large operations:
+```bash
+gh api rate_limit
+```
+
+Output:
+```json
+{
+  "resources": {
+    "core": {
+      "limit": 5000,
+      "remaining": 4850,
+      "reset": 1699027200
+    }
+  }
+}
+```
+
+### 3. Use Profiles Strategically
+
+**Organize by project**:
+- `project-a-dev` → Development repo
+- `project-a-prod` → Production repo
+- `project-b` → Different project
+
+**Organize by team**:
+- `frontend-team` → Frontend repo
+- `backend-team` → Backend repo
+- `infra-team` → Infrastructure repo
+
+### 4. Enable Auto-Sync
+
+For active development:
+```json
+{
+  "sync": {
+    "settings": {
+      "autoSync": true,
+      "syncFrequency": "every-task",
+      "rateLimitProtection": true
+    }
+  }
+}
+```
+
+### 5. Use Dry Run for Testing
+
+Before large syncs:
+```bash
+/specweave-github:sync 0004 --dry-run --time-range 6M
+```
+
+This shows what would happen without actually executing.
+
+## Advanced
+
+### Batch Sync Multiple Increments
+
+```bash
+# Sync all active increments (respects rate limits)
+/specweave-github:sync --all --time-range 1M
+
+# Sync specific increments
+/specweave-github:sync 0001,0002,0003 --time-range 2W
+```
+
+### Custom Rate Limit Thresholds
+
+Override default thresholds:
+```json
+{
+  "sync": {
+    "profiles": {
+      "my-profile": {
+        "rateLimits": {
+          "maxItemsPerSync": 1000,
+          "warnThreshold": 200
+        }
+      }
+    }
+  }
+}
+```
+
+### Resume Failed Syncs
+
+If sync fails mid-operation:
+```bash
+/specweave-github:sync 0004 --resume
+```
+
+System will:
+1. Load sync state from metadata
+2. Skip already-synced items
+3. Continue from last checkpoint
+
+---
+
+**Command**: `/specweave-github:sync`
+**Plugin**: specweave-github
+**Version**: 1.0.0 (Multi-Project)
+**Last Updated**: 2025-11-05
+**Requires**: SpecWeave Core v0.8.0+