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:

Create GitHub Project with:

• Title: [SPEC-001] Core Framework & Architecture

• Description: Spec overview + progress

• Columns: Backlog, In Progress, Done

• Linked to repository

Store project ID in spec metadata:

.specweave/docs/internal/specs/spec-001.md (frontmatter)

externalLinks: github: projectId: 123 projectUrl: https://github.com/users/anton-abyzov/projects/123 syncedAt: 2025-11-11T10:00:00Z

Create GitHub Issues for each user story:

• Title: [US-001] As a developer, I want to install SpecWeave via NPM

• Body: Acceptance criteria as checkboxes

• Labels: user-story , spec:spec-001 , priority:P1

• Linked to project

Example GitHub Project:

[SPEC-001] Core Framework & Architecture

Status: In Progress (75% complete) Priority: P0 (Critical) Feature Area: Foundation & Plugin System

Overview

The core framework and architecture spec covers SpecWeave's foundational capabilities:

• TypeScript-based CLI framework
• Plugin system architecture
• Cross-platform compatibility

Progress

• ✅ US-001: NPM installation (Complete)
• ✅ US-002: Plugin system (Complete)
• ⏳ US-003: Context optimization (In Progress)
• ⏳ US-004: Intelligent agents (In Progress)

Overall: 2/4 user stories complete (50%)

🤖 Auto-synced by SpecWeave GitHub Plugin

2. User Story Progress Updates (Spec → GitHub)

Trigger: After each task completion (via post-task-completion hook)

Actions:

Update GitHub Issue (for user story):

• Updates acceptance criteria checkboxes

• Marks completed ACs with [x]

• Updates issue description

• Updates labels (in-progress , testing , ready-for-review )

Update GitHub Project:

• Moves cards between columns (Backlog → In Progress → Done)

• Updates project progress percentage

• Posts progress comment

Example Issue Update:

User Story: US-001

As a developer, I want to install SpecWeave via NPM so that I can use it in my projects

Acceptance Criteria

• AC-001-01: npm install -g specweave works
• AC-001-02: specweave init creates .specweave/ structure
• AC-001-03: Version command shows current version (In Progress)

Progress: 2/3 ACs complete (67%)

🤖 Auto-updated by SpecWeave (2025-11-11)

3. Spec Completion (Close Project)

Trigger: All user stories in spec are complete

Actions:

• Close all GitHub Issues (user stories)

• Archive GitHub Project

• Post final comment: ✅ Spec Completed

Final Stats:

• 35 user stories completed (100%)
• 4 increments implemented (0001, 0002, 0004, 0005)
• Duration: 6 weeks

Deliverables:

• Core framework architecture
• Plugin system
• Cross-platform CLI

Spec complete. Project archived.

🤖 Auto-closed by SpecWeave

4. GitHub Project → Spec (Import)

Use Case: Import existing GitHub Projects as SpecWeave specs

Command: /sw-github:import-project <project-number>

Actions:

Fetch project via GitHub GraphQL API

Create spec structure:

• Parse project title → spec title

• Parse project body → spec overview

• Map issues → user stories

• Map labels → priority

Generate spec.md with user stories and acceptance criteria

Link project to spec in metadata

Configuration

Configure GitHub sync in .specweave/config.json :

{ "plugins": { "enabled": ["specweave-github"], "settings": { "specweave-github": { "repo": "owner/repo", "autoSyncSpecs": true, "syncDirection": "two-way", "defaultLabels": ["specweave", "spec"], "syncFrequency": "on-change" } } } }

GitHub CLI Requirements

This skill requires GitHub CLI (gh ) to be installed and authenticated:

Install GitHub CLI

brew install gh # macOS sudo apt install gh # Ubuntu choco install gh # Windows

Authenticate

gh auth login

Verify

gh auth status

Manual Sync Operations

Sync Spec to GitHub

/sw-github:sync-spec spec-001

Creates or updates GitHub Project for spec-001.

Sync All Specs

/sw-github:sync-spec --all

Syncs all specs to GitHub Projects.

Import Project

/sw-github:import-project 123

Imports GitHub Project #123 as a SpecWeave spec.

Check Status

/sw-github:status spec-001

Shows sync status (project ID, last sync time, progress %).

Workflow Integration

Full Automated Workflow

1. Create spec (PM agent)

User: "Create spec for user authentication" PM: Creates .specweave/docs/internal/specs/spec-005-user-auth.md

2. Auto-sync to GitHub (hook)

→ GitHub Project created automatically → Issues created for each user story

3. Implement increments

/sw:increment "Add login flow" → Increment 0010 created (implements US-001, US-002)

4. Work on tasks

/sw:do → Task completed → Hook fires → Spec updated (AC marked complete) → GitHub Project updated automatically

5. Complete spec

→ All user stories done → GitHub Project archived automatically

Team Collaboration

For Developers:

• Work in SpecWeave specs locally

• Automatic GitHub Project updates keep team informed

• No manual project management needed

For Project Managers:

• View all specs as GitHub Projects

• Track progress in GitHub Projects UI

• Comment on issues to communicate with developers

For Stakeholders:

• See progress in familiar GitHub interface

• No need to understand SpecWeave structure

• Clear visibility into feature development status

Conflict Resolution

What if project and spec diverge?

The spec is always the source of truth. GitHub Projects are a mirror for visibility.

Sync conflicts (rare):

• Spec status conflicts with project state

• Manual edits to project/issue body/title

Resolution:

• Run /sw-github:sync-spec spec-001 --force to overwrite project from spec

• Or manually update spec metadata to match project

Privacy & Security

What gets synced?

• ✅ Spec title, overview, progress

• ✅ User stories and acceptance criteria

• ✅ User story completion status

• ❌ Code diffs, file contents (never synced)

• ❌ Internal notes, sensitive data

Security:

• Uses GitHub token from environment (GITHUB_TOKEN or GH_TOKEN)

• Respects repository permissions (read/write)

• No data sent to third parties

Benefits

For SpecWeave Users:

• ✅ No manual GitHub project management

• ✅ Automatic team visibility

• ✅ Single source of truth (spec docs)

• ✅ GitHub integration without leaving IDE

For Teams:

• ✅ Track SpecWeave work in GitHub Projects

• ✅ Use milestones, labels, assignees as usual

• ✅ Comment on issues to communicate with developers

• ✅ View progress in real-time

For Organizations:

• ✅ Unified project tracking across repos

• ✅ GitHub-native workflow (familiar to all)

• ✅ Audit trail (all syncs timestamped)

• ✅ Integration with GitHub Actions, webhooks

Troubleshooting

Project not created?

• Check GitHub CLI: gh auth status

• Verify repo permissions (write access)

• Check config: .specweave/config.json

Sync failing?

• Check network connectivity

• Verify project still exists (not deleted)

• Check rate limits: gh api rate_limit

Progress not updating?

• Check autoSyncSpecs: true in config

• Verify hook execution: .specweave/logs/hooks-debug.log

• Manually sync: /sw-github:sync-spec spec-001

Advanced Usage

Custom Project Templates

Create .specweave/github/project-template.md :

[{{spec.id.toUpperCase()}}] {{spec.title}}

{{spec.overview}}

SpecWeave Details

• Spec: spec.md
• Priority: {{spec.priority}}
• Feature Area: {{spec.featureArea}}

User Stories

{{spec.userStories.map(us => - ${us.id}: ${us.title}).join('\n')}}

Selective Sync

Sync only specific specs:

{ "plugins": { "settings": { "specweave-github": { "syncSpecs": [ "spec-001-core-framework", "spec-005-user-authentication" ] } } } }

Multi-Repo Sync

For monorepos with multiple GitHub repositories:

{ "plugins": { "settings": { "specweave-github": { "repos": { "frontend": { "repo": "myorg/frontend", "specs": ["spec-001-", "spec-002-"] }, "backend": { "repo": "myorg/backend", "specs": ["spec-003-", "spec-004-"] } } } } } }

Related

• github-issue-tracker: Track individual tasks as issue comments (DEPRECATED - use spec sync instead)

• github-manager agent: AI agent for GitHub operations

• Commands: /sw-github:sync-spec , /sw-github:import-project , /sw-github:status

Version: 2.0.0 (Spec-based architecture) Plugin: specweave-github Last Updated: 2025-11-11