675 lines
16 KiB
Markdown
675 lines
16 KiB
Markdown
---
|
|
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+
|