zhongwei/gh-anton-abyzov-specweave-plugins-specweave-github
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
712abd45e8f7b33997b04ec3cfc16b368f619dba
gh-anton-abyzov-specweave-p…/commands/specweave-github-sync.md
Zhongwei Li 712abd45e8 Initial commit
2025-11-29 17:56:38 +08:00

16 KiB
Raw Blame History

name, description
name description
specweave-github:sync 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

# 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:

# 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:

# 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

/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
• Pull changes FROM GitHub (status, labels, comments)
• Push changes TO GitHub (tasks, progress, metadata)		 Always (recommended for keeping both systems in sync)
to-github SpecWeave → GitHub only
• Push increment progress to GitHub
• Don't pull GitHub changes back		 Read-only GitHub usage, or when GitHub is downstream
from-github GitHub → SpecWeave only
• Pull GitHub issue updates
• 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:

# 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

# 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:

{
  "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):

# GitHub
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Per-Increment Configuration

Each increment stores its sync metadata in .specweave/increments/{id}/metadata.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:

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:

    /specweave:sync-profile create

  2. Update increment metadata:

    {
  "sync": {
    "profile": "default-github",
    "issueNumber": 130
  }
}

  3. Test sync:

    /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:

gh api rate_limit

Output:

{
  "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:

{
  "sync": {
    "settings": {
      "autoSync": true,
      "syncFrequency": "every-task",
      "rateLimitProtection": true
    }
  }
}

5. Use Dry Run for Testing

Before large syncs:

/specweave-github:sync 0004 --dry-run --time-range 6M

This shows what would happen without actually executing.

Advanced

Batch Sync Multiple Increments

# 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:

{
  "sync": {
    "profiles": {
      "my-profile": {
        "rateLimits": {
          "maxItemsPerSync": 1000,
          "warnThreshold": 200
        }
      }
    }
  }
}

Resume Failed Syncs

If sync fails mid-operation:

/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+

Reference in New Issue View Git Blame Copy Permalink