zhongwei/gh-anton-abyzov-specweave-plugins-specweave-github
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 17:56:38 +08:00
commit 712abd45e8
19 changed files with 5806 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

227
skills/github-issue-standard/SKILL.md Normal file
View File

@@ -0,0 +1,227 @@
---
name: github-issue-standard
description: Standard format for ALL GitHub issues created by SpecWeave. Ensures checkable acceptance criteria, task connections, working links, and consistent metadata. Activates for create GitHub issue, sync to GitHub, format GitHub issue, standardize issue.
---
# GitHub Issue Standard - Universal Format
**CRITICAL**: This is the **MANDATORY** format for ALL GitHub issues created by SpecWeave, whether for:
- User stories (individual us-*.md files)
- Epics/Features (FS-* folders)
- Increments (0001-* folders)
- Specs (spec-*.md files)
## Issue Title Format (MANDATORY)
### ✅ ONLY Allowed Title Formats
```
[FS-XXX][US-YYY] User Story Title ← STANDARD (User Stories)
[FS-XXX] Feature Title ← Rare (Feature-level only)
```
**Examples**:
- ✅ `[FS-059][US-003] Hook Optimization (P0)`
- ✅ `[FS-054][US-001] Fix Reopen Desync Bug (P0)`
- ✅ `[FS-048] Smart Pagination Feature`
### ❌ PROHIBITED Title Formats (NEVER USE)
```
[BUG] Title ← WRONG! Bug is a LABEL, not title prefix
[HOTFIX] Title ← WRONG! Hotfix is a LABEL
[FEATURE] Title ← WRONG! Feature is a LABEL
[DOCS] Title ← WRONG! Docs is a LABEL
[Increment XXXX] Title ← DEPRECATED! Old format
```
**Why?** Type-based prefixes like `[BUG]` break traceability:
- Cannot link to Feature Spec (FS-XXX)
- Cannot link to User Story (US-YYY)
- Violates SpecWeave's data flow: `Increment → Living Docs → GitHub`
**What to do instead?**
1. Link work to a Feature (FS-XXX) in living docs
2. Create User Story (US-YYY) under that feature
3. Use GitHub **labels** for categorization: `bug`, `enhancement`, `hotfix`
### Validation
The GitHub client (`github-client-v2.ts`) enforces this:
- Rejects titles starting with `[BUG]`, `[HOTFIX]`, `[FEATURE]`, etc.
- Rejects deprecated `[Increment XXXX]` format
- Only allows `[FS-XXX][US-YYY]` or `[FS-XXX]` formats
---
## The Standard Format
### ✅ Required Elements
Every GitHub issue MUST include:
1. **Checkable Acceptance Criteria**
- Use GitHub task checkbox format: `- [x]` or `- [ ]`
- Include AC ID, description, priority, and testable flag
- Example: `- [x] **AC-US4-01**: Description (P1, testable)`
2. **Checkable Tasks**
- Link to increment tasks.md with GitHub URLs (not relative paths)
- Use GitHub task checkbox format
- Example: `- [x] [T-008: Title](https://github.com/owner/repo/tree/develop/.specweave/increments/0031/tasks.md#t-008-title)`
3. **Working GitHub URLs**
- Feature links: `https://github.com/owner/repo/tree/develop/.specweave/docs/internal/specs/_features/FS-031`
- User story links: `https://github.com/owner/repo/tree/develop/.specweave/docs/internal/specs/default/FS-031/us-004-*.md`
- Task links: `https://github.com/owner/repo/tree/develop/.specweave/increments/0031/tasks.md#task-anchor`
- Increment links: `https://github.com/owner/repo/tree/develop/.specweave/increments/0031`
4. **Extracted Priority**
- Extract from ACs (highest priority wins: P1 > P2 > P3)
- Show ONLY if priority exists (don't show "undefined")
- Example: `**Priority**: P1`
5. **NO Project Field**
- Don't include `**Project**: ...` - not needed for GitHub issues
- Project is determined by repository context
### ❌ Never Use
- ❌ Relative paths (`../../_features/FS-031`)
- ❌ Undefined values (`**Priority**: undefined`)
- ❌ Project field in metadata
- ❌ Plain bullet points for ACs (must be checkboxes)
- ❌ Plain bullet points for tasks (must be checkboxes with links)
## Implementation
### UserStoryContentBuilder (✅ REFERENCE IMPLEMENTATION)
**File**: `plugins/specweave-github/lib/user-story-content-builder.ts`
This is the **gold standard** implementation. All other builders must follow this pattern.
**Key features**:
```typescript
// 1. Accept GitHub repo parameter
async buildIssueBody(githubRepo?: string): Promise<string>
// 2. Auto-detect repo from git remote
private async detectGitHubRepo(): Promise<string | null>
// 3. Extract priority from ACs
private extractPriorityFromACs(criteria: AcceptanceCriterion[]): string | null
// 4. Generate GitHub URLs (not relative)
const featureUrl = `https://github.com/${repo}/tree/develop/.specweave/docs/internal/specs/_features/${featureId}`;
// 5. Convert task links to GitHub URLs
if (repo && taskLink.startsWith('../../')) {
const relativePath = taskLink.replace(/^\.\.\/\.\.\//, '.specweave/');
taskLink = `https://github.com/${repo}/tree/develop/${relativePath}`;
}
```
### Template
```markdown
**Feature**: [FS-031](https://github.com/owner/repo/tree/develop/.specweave/docs/internal/specs/_features/FS-031)
**Status**: complete
**Priority**: P1
---
## User Story
**As a** user
**I want** feature
**So that** benefit
📄 View full story: [`us-004-name.md`](https://github.com/owner/repo/tree/develop/.specweave/docs/internal/specs/default/_archive/FS-031/us-004-name.md)
---
## Acceptance Criteria
Progress: 4/6 criteria met (67%)
- [x] **AC-US4-01**: Description (P1, testable)
- [x] **AC-US4-02**: Description (P1, testable)
- [ ] **AC-US4-03**: Description (P2, testable)
- [ ] **AC-US4-04**: Description (P2, testable)
---
## Implementation Tasks
Progress: 3/6 tasks complete (50%)
**Increment**: [0031-name](https://github.com/owner/repo/tree/develop/.specweave/increments/0031-name)
- [x] [T-008: Title](https://github.com/owner/repo/tree/develop/.specweave/increments/0031/tasks.md#t-008-title)
- [x] [T-009: Title](https://github.com/owner/repo/tree/develop/.specweave/increments/0031/tasks.md#t-009-title)
- [ ] [T-010: Title](https://github.com/owner/repo/tree/develop/.specweave/increments/0031/tasks.md#t-010-title)
---
🤖 Auto-synced by SpecWeave
```
## Implementation
### Content Builders
All GitHub issue content is generated by these builders:
1. **UserStoryIssueBuilder** (`plugins/specweave-github/lib/user-story-issue-builder.ts`)
- Creates issues from `us-*.md` files
- Generates `[FS-XXX][US-YYY] Title` format
- Extracts ACs and tasks as checkboxes
- Uses GitHub URLs (not relative paths)
2. **GitHubFeatureSync** (`plugins/specweave-github/lib/github-feature-sync.ts`)
- Syncs Features as GitHub Milestones
- Syncs User Stories as GitHub Issues via UserStoryIssueBuilder
- Universal Hierarchy: Feature → Milestone, User Story → Issue
### Commands
All GitHub sync commands use the Universal Hierarchy:
- `/specweave-github:sync` - Sync increments via Feature/UserStory hierarchy
- `/specweave-github:create-issue` - Create issue using standard format
- `/specweave-github:update-user-story` - Update user story issue
## Validation Checklist
When creating/updating a GitHub issue, verify:
- [ ] Feature link is clickable GitHub URL (not `../../`)
- [ ] User story link is clickable GitHub URL
- [ ] All task links are clickable GitHub URLs
- [ ] ACs are checkable (GitHub checkboxes work in UI)
- [ ] Tasks are checkable (GitHub checkboxes work in UI)
- [ ] Priority shows actual value (P1/P2/P3) or is omitted
- [ ] No "Project: undefined" field
- [ ] Progress percentages are correct
- [ ] Increment link is clickable GitHub URL
## Benefits
- ✅ **Links work**: No more broken relative paths
- ✅ **Checkable**: ACs and tasks can be checked/unchecked in GitHub UI
- ✅ **Clean metadata**: No undefined values cluttering the issue
- ✅ **Consistent**: Same format across all issue types
- ✅ **Traceable**: Direct links to source files in repository
## When to Use
**Always!** This is the ONLY acceptable format for GitHub issues created by SpecWeave.
No exceptions. No shortcuts. Every issue follows this standard.
## Related Files
- **User Story Builder**: `plugins/specweave-github/lib/user-story-issue-builder.ts`
- **Feature Sync**: `plugins/specweave-github/lib/github-feature-sync.ts`
- **Example Issue**: https://github.com/anton-abyzov/specweave/issues/501

497
skills/github-issue-tracker/SKILL.md Normal file
View File

@@ -0,0 +1,497 @@
---
name: github-issue-tracker
description: Task-level GitHub issue tracking for SpecWeave increments. Provides fine-grained progress tracking via issue comments, task checklists, and labels. Enables team collaboration on individual tasks. Activates for task tracking, GitHub comments, issue updates, task progress, team collaboration, granular tracking.
---
# GitHub Issue Tracker - Task-Level Progress Tracking
**Purpose**: Provide fine-grained task-level visibility in GitHub issues for detailed progress tracking and team collaboration.
**When to Use**:
- Detailed progress tracking (per-task updates)
- Team collaboration on specific tasks
- Task assignments via GitHub
- Blocking issue tracking
- Task-level comments and discussions
**Integration**: Works with `github-sync` skill and `/specweave:github:*` commands
---
## How Task Tracking Works
### 1. Task Checklist in GitHub Issue
When creating an increment issue, automatically add task checklist:
```markdown
## Tasks
### Week 1: Foundation (12 tasks)
- [ ] T-001: Create plugin type definitions (6h) @developer1
- [ ] T-002: Create plugin manifest schema (4h) @developer1
- [ ] T-003: Implement PluginLoader (6h) @developer2
- [ ] T-004: Implement PluginManager (8h) @developer2
...
### Week 2: GitHub Plugin (10 tasks)
- [ ] T-013: Create GitHub plugin structure (2h)
- [ ] T-014: Implement github-sync skill (8h)
...
```
**Features**:
- Clickable checkboxes (GitHub native)
- Time estimates in parentheses
- Assignees via @mentions
- Organized by phase/week
### 2. Per-Task Comments
After each task completion, post detailed comment:
```markdown
### ✅ Task Completed: T-007
**Title**: Implement Claude plugin installer
**Estimated**: 8h
**Actual**: 7h
**Assignee**: @developer2
**What Changed**:
- Added `compilePlugin()` method to ClaudeAdapter
- Implemented plugin file copying to `.claude/`
- Added unload and status methods
- Updated adapter interface
**Files Modified**:
- `src/adapters/claude/adapter.ts` (+150 lines)
- `src/adapters/adapter-interface.ts` (+35 lines)
**Tests**:
- ✅ Unit tests passing (12 new tests)
- ✅ Integration test: plugin install/uninstall
**Next Task**: T-008 - Implement Cursor plugin compiler
---
**Progress**: 7/48 tasks (15%) | Week 1: 7/12 complete
🤖 Posted by SpecWeave at 2025-10-30 14:30:00
```
**Benefits**:
- Detailed change log per task
- Time tracking (estimated vs actual)
- File change summary
- Test status
- Context for code reviewers
### 3. Task Assignments
Assign tasks to team members via GitHub:
**Method 1: Task checklist with @mentions**
```markdown
- [ ] T-015: Create test suite (8h) @qa-engineer
```
**Method 2: Issue comments**
```
@developer1 Can you take T-003 and T-004 this week?
```
**Method 3: GitHub Projects**
- Drag tasks to columns (To Do, In Progress, Done)
- Auto-sync with increment status
### 4. Blocking Issues
Track dependencies and blockers:
```markdown
### 🚨 Blocked: T-020
**Task**: Implement Kubernetes plugin
**Blocked By**: #127 (Infrastructure setup incomplete)
**Blocking**: T-021, T-022
**Reason**: Need staging cluster before testing K8s plugin
**Resolution**: Wait for #127 to close, then proceed with T-020
---
**ETA**: Blocked since 2025-10-28, expected resolution by 2025-11-01
```
---
## Configuration
Enable task-level tracking in `.specweave/config.yaml`:
```yaml
plugins:
settings:
specweave-github:
# Task-level tracking
task_tracking:
enabled: true
# Post comment after each task
post_task_comments: true
# Update checklist after each task
update_checklist: true
# Include file changes in comments
include_file_changes: true
# Include time tracking
include_time_tracking: true
# Auto-assign tasks based on git author
auto_assign: true
# Blocking issue detection
blocking_issues:
enabled: true
# Check for blocking keywords in task descriptions
keywords: ["blocked by", "depends on", "requires"]
```
---
## Commands
### Check Task Status
```bash
/specweave:github:status 0004
```
Output:
```
GitHub Issue: #130
Status: Open (In Progress)
Tasks: 7/48 completed (15%)
Week 1: Foundation
✅ T-001: Create plugin types (Done)
✅ T-002: Create manifest schema (Done)
✅ T-003: Implement PluginLoader (Done)
✅ T-004: Implement PluginManager (Done)
✅ T-005: Implement PluginDetector (Done)
✅ T-006: Update adapter interface (Done)
✅ T-007: Implement Claude installer (Done)
⏳ T-008: Implement Cursor compiler (In Progress)
⏸️ T-009: Implement Copilot compiler (Pending)
```
### Sync Task Checklist
```bash
/specweave:github:sync 0004 --tasks
```
Updates GitHub issue checklist to match current increment progress.
### Comment on Task
```bash
/specweave:github:comment 0004 T-008 "Cursor adapter completed, moving to testing phase"
```
Posts custom comment to GitHub issue for specific task.
---
## GitHub Labels for Tasks
Automatically apply labels based on task status:
| Label | When Applied | Purpose |
|-------|--------------|---------|
| `in-progress` | First task starts | Increment is actively being worked on |
| `testing` | Implementation tasks done | Ready for QA |
| `blocked` | Task marked as blocked | Needs attention |
| `review-requested` | PR created | Code review needed |
| `ready-for-merge` | Review approved | Can be merged |
---
## Team Collaboration Patterns
### Pattern 1: Daily Standups via GitHub
Team members comment on tasks with daily updates:
```markdown
**@developer1** on T-008:
Yesterday: Implemented Cursor adapter skeleton
Today: Adding plugin compilation logic
Blockers: None
**@developer2** on T-014:
Yesterday: Created github-sync skill
Today: Testing sync workflow
Blockers: Waiting for #130 review
```
### Pattern 2: Code Review Integration
Link PRs to tasks:
```markdown
### T-007: Claude plugin installer
**PR**: #45
**Status**: Ready for review
**Reviewers**: @tech-lead, @architect
**Changes**:
- Implemented plugin support in Claude adapter
- Added comprehensive tests
- Updated documentation
**Review Checklist**:
- [ ] Code quality (clean, readable)
- [ ] Test coverage (80%+)
- [ ] Documentation updated
- [ ] No security issues
```
### Pattern 3: Task Handoff
Transfer task ownership:
```markdown
@developer1 → @developer2 (T-015)
**Context**:
- Tests framework configured
- Need to write E2E tests for plugin system
- Reference: T-007 implementation
**Handoff Notes**:
- Use Playwright for E2E tests
- Cover happy path + error scenarios
- See `.specweave/increments/0004/tests.md` for test cases
```
---
## Time Tracking
### Automatic Time Tracking
Track time spent on tasks:
```yaml
# .specweave/increments/0004-plugin-architecture/.metadata.yaml
tasks:
T-007:
estimated_hours: 8
actual_hours: 7
started_at: 2025-10-30T10:00:00Z
completed_at: 2025-10-30T17:00:00Z
assignee: developer2
```
### Time Reports
Generate time reports:
```bash
/specweave:github:time-report 0004
```
Output:
```
Time Report: Increment 0004
Estimated: 240 hours (6 weeks)
Actual: 56 hours (1.4 weeks)
Remaining: 184 hours (4.6 weeks)
By Developer:
- developer1: 24h (5 tasks)
- developer2: 32h (2 tasks)
By Phase:
- Week 1 Foundation: 56h / 96h (58%)
- Week 2 GitHub Plugin: 0h / 80h (0%)
- Week 3 Plugins: 0h / 120h (0%)
- Week 4 Docs: 0h / 88h (0%)
Pace: On track (4% ahead of schedule)
```
---
## GitHub Projects Integration
### Automated Kanban Board
Sync increment tasks with GitHub Projects:
**Board Columns**:
1. **Backlog**: Pending tasks
2. **Ready**: Tasks ready to start
3. **In Progress**: Currently being worked on
4. **Review**: PRs open, needs review
5. **Done**: Completed tasks
**Auto-Move Rules**:
- Task starts → Move to "In Progress"
- PR created → Move to "Review"
- PR merged → Move to "Done"
### Milestone Tracking
Link increments to GitHub Milestones:
```yaml
# .specweave/config.yaml
plugins:
settings:
specweave-github:
milestones:
"v0.4.0":
increments:
- 0004-plugin-architecture
- 0005-user-authentication
due_date: 2025-11-30
```
GitHub Milestone view shows progress across multiple increments.
---
## Advanced Features
### Task Dependencies
Define task dependencies in `tasks.md`:
```markdown
### T-008: Implement Cursor compiler
**Dependencies**: T-006, T-007
**Blocks**: T-011, T-012
**Description**: ...
```
SpecWeave enforces dependency order and warns if attempting blocked task.
### Subtasks
Break complex tasks into subtasks:
```markdown
### T-014: Implement github-sync skill (8h)
**Subtasks**:
- [ ] T-014.1: Create SKILL.md (1h)
- [ ] T-014.2: Implement export (increment → issue) (3h)
- [ ] T-014.3: Implement import (issue → increment) (2h)
- [ ] T-014.4: Add progress updates (1h)
- [ ] T-014.5: Write tests (1h)
```
Subtasks appear as nested checkboxes in GitHub issue.
### External Issue Links
Reference external blocking issues:
```markdown
### T-020: Kubernetes plugin
**Blocked By**:
- #127 (this repo): Infrastructure setup
- https://github.com/kubernetes/kubernetes/issues/12345: K8s API bug
**Resolution Plan**:
1. Wait for #127 (ETA: 2025-11-01)
2. Work around K8s bug using alternative API
```
---
## Notifications
### Task Assignment Notifications
GitHub automatically notifies assignees:
```
@developer1 you were assigned T-015 in #130
```
### Blocking Notifications
Notify blocked task assignees when blocker resolves:
```
@developer2 Task T-020 is unblocked (#127 was closed)
```
### Deadline Reminders
Warn when tasks are behind schedule:
```
⚠️ T-008 is 2 days overdue (estimated: 2 days, actual: 4 days)
```
---
## Troubleshooting
**Checklist not updating?**
- Verify `update_checklist: true` in config
- Check GitHub API permissions (repo write access)
- Manually sync: `/specweave:github:sync 0004 --tasks`
**Comments not posting?**
- Check `post_task_comments: true`
- Verify GitHub CLI authenticated: `gh auth status`
- Check rate limits: `gh api rate_limit`
**Time tracking inaccurate?**
- Verify task timestamps in `.metadata.yaml`
- Check for manual edits to metadata
- Re-sync: `/specweave:github:sync 0004 --force`
---
## Best Practices
1. **Keep Tasks Atomic**: Each task should be completable in one work session (2-8 hours)
2. **Update Checklists Daily**: Sync progress at least once per day
3. **Use Assignees**: Assign tasks to specific developers for accountability
4. **Track Blockers**: Immediately flag blocking issues for visibility
5. **Link PRs**: Always reference task ID in PR title (`T-007: Add plugin support`)
6. **Comment Context**: Add context comments when handing off tasks
7. **Review Time Estimates**: Adjust estimates based on actual time tracked
---
## Related
- **github-sync**: High-level increment ↔ issue synchronization
- **github-manager agent**: AI agent for GitHub operations
- **Commands**: All `/specweave:github:*` commands
---
**Version**: 1.0.0
**Plugin**: specweave-github
**Last Updated**: 2025-10-30

249
skills/github-multi-project/SKILL.md Normal file
View File

@@ -0,0 +1,249 @@
---
name: github-multi-project
description: Expert at organizing specs and splitting tasks across multiple GitHub repositories. Handles monorepo, polyrepo, and parent repo architectures. Activates for multi-project GitHub setups, task splitting, spec organization, team allocation, cross-repo coordination.
---
# GitHub Multi-Project Management Skill
Expert skill for managing SpecWeave projects across multiple GitHub repositories.
## Core Capabilities
### 1. Spec Organization
- Organizes specs in `.specweave/docs/internal/projects/{project-id}/` structure
- Maps increments to specific projects/repos
- Maintains traceability across repositories
- Handles cross-project dependencies
### 2. Task Splitting
When a SpecWeave increment spans multiple repositories:
- Analyzes tasks in `tasks.md`
- Identifies which tasks belong to which repo
- Creates repo-specific task lists
- Maintains cross-repo coordination
### 3. Repository Architectures
#### Single Repository
```
my-app/
├── .specweave/
│ └── docs/internal/projects/default/
└── src/
```
#### Multi-Repository (Polyrepo)
```
my-app-frontend/
├── .git
└── src/
my-app-backend/
├── .git
└── src/
my-app-shared/
├── .git
└── src/
```
#### Parent Repository Approach (Recommended for Multi-Repo)
```
my-app-parent/ # Parent repo with .specweave
├── .specweave/
│ └── docs/internal/projects/
│ ├── frontend/
│ ├── backend/
│ └── shared/
└── services/ # Implementation repos
├── frontend/
├── backend/
└── shared/
```
#### Monorepo
```
my-app/
├── .specweave/
│ └── docs/internal/projects/
│ ├── frontend/
│ ├── backend/
│ └── shared/
└── packages/
├── frontend/
├── backend/
└── shared/
```
## Task Splitting Examples
### Example 1: E-commerce Platform
**Increment**: Add shopping cart functionality
**Tasks split by repository**:
**Frontend (my-app-frontend)**:
- T-001: Create CartItem component
- T-002: Implement cart state management
- T-003: Add cart UI with add/remove buttons
**Backend (my-app-backend)**:
- T-004: Create cart database schema
- T-005: Implement cart API endpoints
- T-006: Add cart validation logic
**Shared (my-app-shared)**:
- T-007: Define cart TypeScript types
- T-008: Create cart utility functions
### Example 2: Microservices Architecture
**Increment**: Implement user notifications
**Tasks split by service**:
**User Service**:
- T-001: Add notification preferences to user profile
- T-002: Create preference API endpoints
**Notification Service**:
- T-003: Implement notification queue
- T-004: Create email sender
- T-005: Create push notification sender
**Gateway Service**:
- T-006: Add notification routes
- T-007: Implement rate limiting
## Commands
### Analyze Task Distribution
```typescript
// Analyze which tasks belong to which repository
function analyzeTaskDistribution(tasks: Task[]): Map<string, Task[]> {
const distribution = new Map();
for (const task of tasks) {
const repo = detectRepository(task);
if (!distribution.has(repo)) {
distribution.set(repo, []);
}
distribution.get(repo).push(task);
}
return distribution;
}
```
### Create Repository-Specific Issues
```typescript
// Create GitHub issues in each repository
async function createRepoSpecificIssues(
increment: Increment,
distribution: Map<string, Task[]>
) {
for (const [repo, tasks] of distribution) {
const issue = await createGitHubIssue({
repo,
title: `[${increment.id}] ${increment.name} - ${repo}`,
body: formatTasksAsChecklist(tasks),
labels: ['specweave', 'increment', repo]
});
console.log(`Created issue #${issue.number} in ${repo}`);
}
}
```
## Best Practices
### 1. Parent Repository Approach
**Recommended for multi-repo projects**:
- Central .specweave/ folder in parent repo
- Living docs sync to parent (single source of truth)
- Implementation repos stay clean
- Better for enterprise/multi-team projects
### 2. Task Naming Convention
```
T-{repo}-{number}: {description}
T-FE-001: Create user profile component
T-BE-001: Implement user API
T-SHARED-001: Define user types
```
### 3. Cross-Repository Dependencies
Mark dependencies clearly:
```
T-FE-002: Consume user API
Dependencies: T-BE-001 (must complete first)
```
### 4. Spec Organization
```
.specweave/docs/internal/projects/
├── frontend/
│ └── specs/
│ ├── spec-001-user-interface.md
│ └── spec-002-cart-ui.md
├── backend/
│ └── specs/
│ ├── spec-001-api-design.md
│ └── spec-002-database.md
└── shared/
└── specs/
└── spec-001-types.md
```
## Integration with GitHub Projects
### Multi-Repo GitHub Project
Create a GitHub Project that spans multiple repositories:
1. Create project at organization level
2. Add issues from all repos
3. Use project boards for cross-repo coordination
4. Track overall increment progress
### Repository-Specific Projects
Each repository can have its own project:
- Frontend Project: UI tasks
- Backend Project: API tasks
- Shared Project: Common tasks
## Automation
### GitHub Actions Integration
```yaml
# .github/workflows/specweave-sync.yml
name: SpecWeave Multi-Repo Sync
on:
workflow_dispatch:
schedule:
- cron: '0 */6 * * *' # Every 6 hours
jobs:
sync:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Sync to repositories
run: |
# Sync tasks to frontend repo
gh issue create --repo myorg/frontend ...
# Sync tasks to backend repo
gh issue create --repo myorg/backend ...
```
## Error Handling
### Common Issues
1. **Repository not found**: Ensure repos exist and token has access
2. **Task ambiguity**: Use clear naming to indicate target repo
3. **Cross-repo conflicts**: Use parent repo as single source of truth
4. **Permission errors**: Token needs repo scope for all repositories
## Related Skills
- github-sync: Basic GitHub synchronization
- github-issue-tracker: Task-level tracking
- specweave:multi-project-spec-mapper: Intelligent spec splitting

471
skills/github-sync/SKILL.md Normal file
View File

@@ -0,0 +1,471 @@
---
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