sw-github-sync_skill

Overview

This skill helps set up and troubleshoot two-way synchronization between SpecWeave specs and GitHub Projects. It explains architecture, configuration, and common failure modes, and points users to the /sw-github:sync-spec command for executing actual syncs. Use it when you need guidance on GitHub integration, credentials, or conflict resolution.

How this skill works

The skill inspects SpecWeave spec metadata and GitHub Projects to keep both sides aligned by default in a two-way sync (push & pull). It describes how specs become GitHub Projects, how user stories map to issues, how progress updates propagate, and how imports work from existing GitHub Projects into specs. It also documents configuration, required CLI tooling, and conflict-resolution strategies.

When to use it

• Setting up GitHub sync or onboarding a repo to SpecWeave sync
• Troubleshooting failed syncs, missing projects, or progress mismatches
• Configuring sync behavior (direction, frequency, templates, repos)
• Importing an existing GitHub Project into SpecWeave
• Verifying GitHub CLI authentication and token permissions

Best practices

• Sync specs (permanent docs), not increments (temporary snapshots)
• Keep autoSyncSpecs enabled for real-time visibility unless you need manual control
• Store project ID and URL in spec frontmatter to maintain linkage
• Use a dedicated GitHub token with minimal required repo permissions
• Use project templates and selective sync to standardize project structure

Example use cases

• Create a new spec locally and automatically create a matching GitHub Project with issues for each user story
• Import an existing GitHub Project as a SpecWeave spec using /sw-github:import-project <number>
• Force-overwrite a diverged project from the spec with /sw-github:sync-spec spec-001 --force
• Sync all specs to GitHub for a repo with /sw-github:sync-spec --all
• Check sync status and last synced timestamp with /sw-github:status spec-001