472 lines
11 KiB
Markdown
472 lines
11 KiB
Markdown
---
|
|
name: github-sync
|
|
description: Two-way synchronization between SpecWeave specs and GitHub Projects (push & pull by default). Activates ONLY when user asks questions about GitHub integration or needs help configuring GitHub sync. Does NOT activate for slash commands. For syncing, use /specweave-github:sync-spec command instead.
|
|
---
|
|
|
|
# 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 `/specweave-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 `/specweave-github:sync-spec` command (command handles it)
|
|
- Command is already running (avoid duplicate invocation)
|
|
- Task completion hook is syncing (automatic process)
|
|
|
|
**Integration**: Works with `/specweave-github:sync-spec` command
|
|
|
|
---
|
|
|
|
## CORRECT Architecture (v0.17.0+)
|
|
|
|
**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**:
|
|
1. Create GitHub Project with:
|
|
- Title: `[SPEC-001] Core Framework & Architecture`
|
|
- Description: Spec overview + progress
|
|
- Columns: Backlog, In Progress, Done
|
|
- Linked to repository
|
|
|
|
2. Store project ID in spec metadata:
|
|
```yaml
|
|
# .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
|
|
---
|
|
```
|
|
|
|
3. 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**:
|
|
```markdown
|
|
# [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**:
|
|
1. **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`)
|
|
|
|
2. **Update GitHub Project**:
|
|
- Moves cards between columns (Backlog → In Progress → Done)
|
|
- Updates project progress percentage
|
|
- Posts progress comment
|
|
|
|
**Example Issue Update**:
|
|
```markdown
|
|
**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
|
|
|
|
- [x] AC-001-01: `npm install -g specweave` works
|
|
- [x] 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**:
|
|
1. Close all GitHub Issues (user stories)
|
|
2. Archive GitHub Project
|
|
3. Post final comment:
|
|
```markdown
|
|
✅ **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**: `/specweave-github:import-project <project-number>`
|
|
|
|
**Actions**:
|
|
1. Fetch project via GitHub GraphQL API
|
|
2. Create spec structure:
|
|
- Parse project title → spec title
|
|
- Parse project body → spec overview
|
|
- Map issues → user stories
|
|
- Map labels → priority
|
|
|
|
3. Generate spec.md with user stories and acceptance criteria
|
|
4. Link project to spec in metadata
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
Configure GitHub sync in `.specweave/config.json`:
|
|
|
|
```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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
/specweave-github:sync-spec spec-001
|
|
```
|
|
|
|
Creates or updates GitHub Project for spec-001.
|
|
|
|
### Sync All Specs
|
|
|
|
```bash
|
|
/specweave-github:sync-spec --all
|
|
```
|
|
|
|
Syncs all specs to GitHub Projects.
|
|
|
|
### Import Project
|
|
|
|
```bash
|
|
/specweave-github:import-project 123
|
|
```
|
|
|
|
Imports GitHub Project #123 as a SpecWeave spec.
|
|
|
|
### Check Status
|
|
|
|
```bash
|
|
/specweave-github:status spec-001
|
|
```
|
|
|
|
Shows sync status (project ID, last sync time, progress %).
|
|
|
|
---
|
|
|
|
## Workflow Integration
|
|
|
|
### Full Automated Workflow
|
|
|
|
```bash
|
|
# 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
|
|
/specweave:increment "Add login flow"
|
|
→ Increment 0010 created (implements US-001, US-002)
|
|
|
|
# 4. Work on tasks
|
|
/specweave: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):
|
|
1. Spec status conflicts with project state
|
|
2. Manual edits to project/issue body/title
|
|
|
|
**Resolution**:
|
|
- Run `/specweave-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: `/specweave-github:sync-spec spec-001`
|
|
|
|
---
|
|
|
|
## Advanced Usage
|
|
|
|
### Custom Project Templates
|
|
|
|
Create `.specweave/github/project-template.md`:
|
|
|
|
```markdown
|
|
# [{{spec.id.toUpperCase()}}] {{spec.title}}
|
|
|
|
{{spec.overview}}
|
|
|
|
## SpecWeave Details
|
|
|
|
- **Spec**: [spec.md]({{spec.url}})
|
|
- **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:
|
|
|
|
```json
|
|
{
|
|
"plugins": {
|
|
"settings": {
|
|
"specweave-github": {
|
|
"syncSpecs": [
|
|
"spec-001-core-framework",
|
|
"spec-005-user-authentication"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Multi-Repo Sync
|
|
|
|
For monorepos with multiple GitHub repositories:
|
|
|
|
```json
|
|
{
|
|
"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**: `/specweave-github:sync-spec`, `/specweave-github:import-project`, `/specweave-github:status`
|
|
|
|
---
|
|
|
|
**Version**: 2.0.0 (Spec-based architecture)
|
|
**Plugin**: specweave-github
|
|
**Last Updated**: 2025-11-11
|