Initial commit
This commit is contained in:
Zhongwei Li
230
commands/specweave-github-cleanup-duplicates.md
Normal file
230
commands/specweave-github-cleanup-duplicates.md
Normal file
@@ -0,0 +1,230 @@
|
||||
---
|
||||
name: specweave-github:cleanup-duplicates
|
||||
description: Clean up duplicate GitHub issues for a Feature. Finds issues with duplicate titles and closes all except the first created issue.
|
||||
justification: |
|
||||
CRITICAL INCIDENT RESPONSE TOOL - DO NOT DELETE!
|
||||
|
||||
Why This Command Exists:
|
||||
- Prevention systems (deduplication, GitHub self-healing) work for single-process execution
|
||||
- Multiple parallel Claude Code instances bypass all prevention (file-based cache, no distributed locking)
|
||||
- GitHub API race conditions: Time gap between "check exists" and "create issue" allows duplicates
|
||||
- Historical duplicates from pre-v0.14.1 users (before prevention was added)
|
||||
|
||||
Evidence of Need:
|
||||
- 2025-11-13: 123 duplicate GitHub issues incident (cleaned to 29 unique)
|
||||
- Parallel execution creates race conditions that prevention CANNOT solve
|
||||
- Industry standard: Prevention + Detection + Cleanup (defense in depth)
|
||||
|
||||
When to Delete:
|
||||
- ONLY if distributed locking implemented (Redis/file locks)
|
||||
- AND parallel execution tested (100+ concurrent syncs with zero duplicates)
|
||||
- AND zero duplicates for 6+ months in production
|
||||
- AND all users migrated to prevention-enabled versions
|
||||
|
||||
See: .specweave/increments/0043-spec-md-desync-fix/reports/ULTRATHINK-CLEANUP-DUPLICATES-NECESSITY-2025-11-18.md
|
||||
---
|
||||
|
||||
# Clean Up Duplicate GitHub Issues
|
||||
|
||||
**CRITICAL**: This command detects and closes duplicate GitHub issues created by multiple syncs.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/specweave-github:cleanup-duplicates <epic-id> [--dry-run]
|
||||
```
|
||||
|
||||
## What It Does
|
||||
|
||||
**Duplicate Detection & Cleanup**:
|
||||
|
||||
1. **Find all issues** for the Epic (searches by Epic ID in title)
|
||||
2. **Group by title** (detect duplicates)
|
||||
3. **For each duplicate group**:
|
||||
- Keep the **FIRST created** issue (lowest number)
|
||||
- Close all **LATER** issues with comment: "Duplicate of #XXX"
|
||||
4. **Update Epic README** with correct issue numbers
|
||||
|
||||
## Examples
|
||||
|
||||
### Dry Run (No Changes)
|
||||
|
||||
```bash
|
||||
/specweave-github:cleanup-duplicates FS-031 --dry-run
|
||||
```
|
||||
|
||||
**Output**:
|
||||
```
|
||||
🔍 Scanning for duplicates in Epic FS-031...
|
||||
Found 25 total issues
|
||||
Detected 10 duplicate groups:
|
||||
|
||||
📋 Group 1: "[FS-031] External Tool Status Synchronization"
|
||||
- #250 (KEEP) - Created 2025-11-10
|
||||
- #255 (CLOSE) - Created 2025-11-11 - DUPLICATE
|
||||
- #260 (CLOSE) - Created 2025-11-12 - DUPLICATE
|
||||
|
||||
📋 Group 2: "[FS-031] Multi-Project GitHub Sync"
|
||||
- #251 (KEEP) - Created 2025-11-10
|
||||
- #256 (CLOSE) - Created 2025-11-11 - DUPLICATE
|
||||
|
||||
...
|
||||
|
||||
✅ Dry run complete!
|
||||
Total issues: 25
|
||||
Duplicate groups: 10
|
||||
Issues to close: 15
|
||||
|
||||
⚠️ This was a DRY RUN - no changes made.
|
||||
Run without --dry-run to actually close duplicates.
|
||||
```
|
||||
|
||||
### Actual Cleanup
|
||||
|
||||
```bash
|
||||
/specweave-github:cleanup-duplicates FS-031
|
||||
```
|
||||
|
||||
**Output**:
|
||||
```
|
||||
🔍 Scanning for duplicates in Epic FS-031...
|
||||
Found 25 total issues
|
||||
Detected 10 duplicate groups
|
||||
|
||||
⚠️ CONFIRM: Close 15 duplicate issues? [y/N]
|
||||
> y
|
||||
|
||||
🗑️ Closing duplicates...
|
||||
✅ Closed #255 (duplicate of #250)
|
||||
✅ Closed #256 (duplicate of #251)
|
||||
✅ Closed #260 (duplicate of #250)
|
||||
...
|
||||
|
||||
📝 Updating Epic README frontmatter...
|
||||
✅ Updated frontmatter with correct issue numbers
|
||||
|
||||
✅ Cleanup complete!
|
||||
Closed: 15 duplicates
|
||||
Kept: 10 original issues
|
||||
```
|
||||
|
||||
## Arguments
|
||||
|
||||
- `<epic-id>` - Epic ID (e.g., `FS-031` or just `031`)
|
||||
- `--dry-run` - Preview changes without actually closing issues (optional)
|
||||
|
||||
## Safety Features
|
||||
|
||||
✅ **Confirmation prompt**: Asks before closing issues (unless --dry-run)
|
||||
✅ **Dry run mode**: Preview changes safely
|
||||
✅ **Keeps oldest issue**: Preserves the first created issue
|
||||
✅ **Adds closure comment**: Links to the original issue
|
||||
✅ **Updates metadata**: Fixes Epic README frontmatter
|
||||
|
||||
## What Gets Closed
|
||||
|
||||
**Closed issues**:
|
||||
- ✅ Duplicate titles (second, third, etc. occurrences)
|
||||
- ✅ Closed with comment: "Duplicate of #XXX"
|
||||
- ✅ Original issue kept open (or maintains its status)
|
||||
|
||||
**Example comment on closed duplicate**:
|
||||
```markdown
|
||||
Duplicate of #250
|
||||
|
||||
This issue was automatically closed by SpecWeave cleanup because it is a duplicate.
|
||||
|
||||
The original issue (#250) contains the same content and should be used for tracking instead.
|
||||
|
||||
🤖 Auto-closed by SpecWeave Duplicate Cleanup
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
1. **GitHub CLI** (`gh`) installed and authenticated
|
||||
2. **Write access** to repository (for closing issues)
|
||||
3. **Epic folder exists** at `.specweave/docs/internal/specs/FS-XXX-name/`
|
||||
|
||||
## When to Use
|
||||
|
||||
**Use this command when**:
|
||||
- ✅ You see multiple issues with the same title in GitHub
|
||||
- ✅ Epic sync ran multiple times and created duplicates
|
||||
- ✅ Epic README frontmatter got corrupted and reset
|
||||
- ✅ Post-sync validation warns about duplicates
|
||||
|
||||
**Example warning that triggers this**:
|
||||
```
|
||||
⚠️ WARNING: 10 duplicate(s) detected!
|
||||
Run cleanup command to resolve:
|
||||
/specweave-github:cleanup-duplicates FS-031
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**"No duplicates found"**:
|
||||
- Good! Your Epic has no duplicate issues
|
||||
- Run epic sync is working correctly with duplicate detection
|
||||
|
||||
**"GitHub CLI not authenticated"**:
|
||||
- Run: `gh auth login`
|
||||
- Ensure you have write access to the repository
|
||||
|
||||
**"Could not find Epic folder"**:
|
||||
- Check Epic exists: `ls .specweave/docs/internal/specs/`
|
||||
- Verify Epic ID format: `FS-031-epic-name/`
|
||||
|
||||
**"Error closing issue"**:
|
||||
- Check GitHub CLI: `gh auth status`
|
||||
- Verify write permissions: `gh repo view`
|
||||
|
||||
## Architecture
|
||||
|
||||
**Duplicate Detection Logic**:
|
||||
1. Group issues by **exact title match**
|
||||
2. Within each group, sort by **issue number** (ascending)
|
||||
3. Keep **first issue** (lowest number = oldest)
|
||||
4. Close **all others** as duplicates
|
||||
|
||||
**Why lowest number?**:
|
||||
- Lower issue numbers were created first
|
||||
- Preserves chronological order
|
||||
- Maintains links from old documentation
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/specweave-github:sync` - Sync Feature to GitHub (with duplicate detection)
|
||||
- `/specweave:validate` - Validate increment completeness
|
||||
- `gh issue list` - View all issues (GitHub CLI)
|
||||
|
||||
## Implementation
|
||||
|
||||
**File**: `plugins/specweave-github/lib/duplicate-detector.ts`
|
||||
|
||||
**Class**: `DuplicateDetector`
|
||||
|
||||
**Algorithm** (3-phase protection):
|
||||
1. **Detection**: Search GitHub for existing issues matching pattern
|
||||
2. **Verification**: Count check to detect duplicates after creation
|
||||
3. **Reflection**: Auto-close duplicates automatically
|
||||
|
||||
For manual cleanup:
|
||||
1. Search GitHub for all issues with Feature ID
|
||||
2. Group by title (Map<string, number[]>)
|
||||
3. Filter groups with >1 issue (duplicates)
|
||||
4. For each duplicate group:
|
||||
- Keep first issue (lowest number)
|
||||
- Close others with gh CLI
|
||||
|
||||
## Next Steps
|
||||
|
||||
After cleanup:
|
||||
|
||||
1. **Verify cleanup**: `gh issue list --search "[FS-031]"`
|
||||
2. **Check Feature FEATURE.md**: Verify frontmatter has correct issue numbers
|
||||
3. **Re-run sync**: `/specweave-github:sync` (should show no duplicates)
|
||||
4. **Duplicate detection**: Automatically enabled via DuplicateDetector
|
||||
|
||||
---
|
||||
|
||||
**✅ SAFE TO USE**: This command is idempotent and safe to run multiple times.
|
||||
418
commands/specweave-github-close-issue.md
Normal file
418
commands/specweave-github-close-issue.md
Normal file
@@ -0,0 +1,418 @@
|
||||
---
|
||||
name: specweave-github:close-issue
|
||||
description: Close GitHub issue for completed SpecWeave increment. Posts completion summary with final stats, deliverables, and closes the issue. Links closure in increment metadata.
|
||||
---
|
||||
|
||||
# Close GitHub Issue for Completed Increment
|
||||
|
||||
Close the GitHub issue associated with a completed SpecWeave increment.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/specweave:github:close-issue <increment-id> [options]
|
||||
```
|
||||
|
||||
## Arguments
|
||||
|
||||
- `increment-id`: Increment ID (e.g., `0004` or `0004-plugin-architecture`)
|
||||
|
||||
## Options
|
||||
|
||||
- `--force`: Force close even if increment not marked complete
|
||||
- `--comment`: Custom closing comment (default: auto-generated summary)
|
||||
- `--reopen`: Reopen a previously closed issue
|
||||
- `--skip-validation`: Skip PM gate validation
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Basic usage (auto-generates completion summary)
|
||||
/specweave:github:close-issue 0004
|
||||
|
||||
# With custom comment
|
||||
/specweave:github:close-issue 0004 --comment "Merged to main, deploying to production"
|
||||
|
||||
# Force close (skip validation)
|
||||
/specweave:github:close-issue 0004 --force
|
||||
|
||||
# Reopen closed issue
|
||||
/specweave:github:close-issue 0004 --reopen
|
||||
```
|
||||
|
||||
## What This Command Does
|
||||
|
||||
1. **Validates Increment Completion**
|
||||
- All tasks completed (48/48)
|
||||
- All tests passing
|
||||
- PM gates passed (from `/specweave:done`)
|
||||
- Documentation updated
|
||||
|
||||
2. **Generates Completion Summary**
|
||||
```markdown
|
||||
✅ **Increment Completed**
|
||||
|
||||
This increment has been successfully completed and is ready for release.
|
||||
|
||||
## Final Stats
|
||||
|
||||
- **Tasks**: 48/48 completed (100%)
|
||||
- **Duration**: 4 weeks (2025-10-01 → 2025-10-30)
|
||||
- **Time Tracked**: 240 hours (estimated) / 235 hours (actual)
|
||||
- **Test Coverage**: 127 test cases, 95% coverage
|
||||
- **Priority**: P1
|
||||
|
||||
## Deliverables
|
||||
|
||||
✅ Plugin architecture implemented
|
||||
✅ 15 plugins migrated (github, kubernetes, frontend-stack, ...)
|
||||
✅ Documentation updated (ADRs, user guides, API docs)
|
||||
✅ E2E tests passing (Playwright suite)
|
||||
✅ Integration tests passing (Jest suite)
|
||||
|
||||
## Key Changes
|
||||
|
||||
- Added plugin system with loader, manager, detector
|
||||
- Implemented 4 adapters (Claude, Cursor, Copilot, Generic)
|
||||
- Created 15 domain-specific plugins
|
||||
- Updated all documentation
|
||||
- Achieved 80% test coverage
|
||||
|
||||
## Files Changed
|
||||
|
||||
- 48 files modified
|
||||
- +12,500 lines added
|
||||
- -3,200 lines removed
|
||||
- Net: +9,300 lines
|
||||
|
||||
## Related
|
||||
|
||||
- **Spec**: [spec.md](https://github.com/owner/repo/blob/main/.specweave/increments/0004/spec.md)
|
||||
- **Plan**: [plan.md](https://github.com/owner/repo/blob/main/.specweave/increments/0004/plan.md)
|
||||
- **Tests**: [tests.md](https://github.com/owner/repo/blob/main/.specweave/increments/0004/tests.md)
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Deploy to production (tracked in #135)
|
||||
- Monitor for issues (see runbook)
|
||||
- Plan next increment (0005-user-authentication)
|
||||
|
||||
---
|
||||
|
||||
🎉 Thank you to all contributors!
|
||||
|
||||
🤖 Auto-closed by SpecWeave at 2025-10-30 17:00:00
|
||||
```
|
||||
|
||||
3. **Posts Completion Comment**
|
||||
```bash
|
||||
gh issue comment 130 --body "$(cat completion-summary.md)"
|
||||
```
|
||||
|
||||
4. **Closes GitHub Issue**
|
||||
```bash
|
||||
gh issue close 130
|
||||
```
|
||||
|
||||
5. **Updates Metadata**
|
||||
```yaml
|
||||
# .metadata.yaml
|
||||
github:
|
||||
issue_number: 130
|
||||
issue_url: "https://github.com/owner/repo/issues/130"
|
||||
closed_at: "2025-10-30T17:00:00Z"
|
||||
closed_by: "specweave-github-plugin"
|
||||
closing_comment_id: 1234590
|
||||
```
|
||||
|
||||
6. **Reports Result**
|
||||
```
|
||||
✅ GitHub issue #130 closed!
|
||||
|
||||
Increment 0004 is complete.
|
||||
Issue: https://github.com/owner/repo/issues/130 (closed)
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Settings from `.specweave/config.yaml`:
|
||||
|
||||
```yaml
|
||||
plugins:
|
||||
settings:
|
||||
specweave-github:
|
||||
# Auto-close issues when increment completes
|
||||
auto_close_issue: true
|
||||
|
||||
# Validate before closing
|
||||
require_validation: true
|
||||
|
||||
# Include in closing comment
|
||||
closing_comment:
|
||||
include_stats: true
|
||||
include_deliverables: true
|
||||
include_file_changes: true
|
||||
include_next_steps: true
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
### Success
|
||||
|
||||
```
|
||||
🔒 Closing GitHub issue for increment 0004...
|
||||
|
||||
Validation:
|
||||
✓ All tasks completed (48/48)
|
||||
✓ All tests passing (127/127)
|
||||
✓ PM gates passed
|
||||
✓ Documentation updated
|
||||
|
||||
Generating completion summary...
|
||||
✓ Final stats calculated
|
||||
✓ Deliverables listed
|
||||
✓ File changes summarized
|
||||
|
||||
Closing issue...
|
||||
✓ Posted completion comment (ID: 1234590)
|
||||
✓ Issue #130 closed
|
||||
✓ Metadata updated
|
||||
|
||||
✅ GitHub Issue Closed!
|
||||
|
||||
Issue #130: https://github.com/owner/repo/issues/130
|
||||
Status: Closed
|
||||
Closed at: 2025-10-30 17:00:00
|
||||
|
||||
Increment 0004 is complete! 🎉
|
||||
```
|
||||
|
||||
### Validation Failure
|
||||
|
||||
```
|
||||
❌ Cannot close issue: Validation failed
|
||||
|
||||
Increment 0004 is not yet complete:
|
||||
|
||||
Issues:
|
||||
✗ Tasks: 45/48 completed (3 remaining)
|
||||
- T-046: Update documentation
|
||||
- T-047: Run E2E tests
|
||||
- T-048: Final review
|
||||
|
||||
✗ Tests: 2 tests failing
|
||||
- TC-105: Plugin unload test
|
||||
- TC-127: E2E sync test
|
||||
|
||||
✗ PM Gates: Not run yet
|
||||
- Run /specweave:done 0004 first
|
||||
|
||||
Fix these issues, then retry:
|
||||
/specweave:github:close-issue 0004
|
||||
|
||||
Or force close (not recommended):
|
||||
/specweave:github:close-issue 0004 --force
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- GitHub CLI (`gh`) installed and authenticated
|
||||
- Increment marked as complete (via `/specweave:done`)
|
||||
- Valid GitHub issue exists for increment
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Increment not complete**:
|
||||
```
|
||||
❌ Error: Increment 0004 is not complete
|
||||
|
||||
Status: in_progress (should be: completed)
|
||||
|
||||
Complete the increment first:
|
||||
/specweave:done 0004
|
||||
|
||||
Then close the issue:
|
||||
/specweave:github:close-issue 0004
|
||||
```
|
||||
|
||||
**Issue not found**:
|
||||
```
|
||||
❌ Error: No GitHub issue found for increment 0004
|
||||
|
||||
Check .metadata.yaml for issue number.
|
||||
|
||||
Create issue first:
|
||||
/specweave:github:create-issue 0004
|
||||
```
|
||||
|
||||
**Issue already closed**:
|
||||
```
|
||||
ℹ️ Issue #130 is already closed
|
||||
|
||||
Closed by: @developer1
|
||||
Closed at: 2025-10-30 16:00:00
|
||||
|
||||
Use --reopen to reopen the issue.
|
||||
```
|
||||
|
||||
**Permission denied**:
|
||||
```
|
||||
❌ Error: Insufficient permissions to close issue #130
|
||||
|
||||
Required: Write or Admin access to repository
|
||||
|
||||
Contact repository admin for access.
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/specweave:done <increment-id>`: Mark increment complete (run this first)
|
||||
- `/specweave:github:sync <increment-id>`: Sync final progress before closing
|
||||
- `/specweave:github:status <increment-id>`: Check issue status
|
||||
|
||||
## Tips
|
||||
|
||||
1. **Auto-Close**: Enable `auto_close_issue: true` for automatic closing when running `/specweave:done`
|
||||
|
||||
2. **Final Sync**: Always run `/specweave:github:sync` before closing to ensure latest progress is posted
|
||||
|
||||
3. **Validation**: Don't skip validation (`--force`) unless absolutely necessary - it ensures quality
|
||||
|
||||
4. **Custom Comments**: Use `--comment` for release-specific notes (deployment status, known issues, etc.)
|
||||
|
||||
5. **Reopening**: If increment needs more work after closing, use `--reopen` to reopen the issue
|
||||
|
||||
## Advanced
|
||||
|
||||
### Custom Closing Template
|
||||
|
||||
Create `.specweave/github/closing-template.md`:
|
||||
|
||||
```markdown
|
||||
# 🎉 Increment {{id}} Completed!
|
||||
|
||||
{{summary}}
|
||||
|
||||
## Achievements
|
||||
|
||||
{{deliverables}}
|
||||
|
||||
## Stats
|
||||
|
||||
- Duration: {{duration}}
|
||||
- Team size: {{team_size}}
|
||||
- Commits: {{commit_count}}
|
||||
|
||||
## Deployment
|
||||
|
||||
- Merged to: {{branch}}
|
||||
- Deployed to: {{environment}}
|
||||
- Release: {{version}}
|
||||
|
||||
## Thank You
|
||||
|
||||
Special thanks to:
|
||||
{{contributors}}
|
||||
|
||||
---
|
||||
|
||||
_Closed by SpecWeave on {{date}}_
|
||||
```
|
||||
|
||||
### Conditional Closing
|
||||
|
||||
Close only if specific conditions met:
|
||||
|
||||
```yaml
|
||||
plugins:
|
||||
settings:
|
||||
specweave-github:
|
||||
closing_conditions:
|
||||
# Require all tests passing
|
||||
- type: "tests"
|
||||
threshold: 100
|
||||
required: true
|
||||
|
||||
# Require coverage >= 80%
|
||||
- type: "coverage"
|
||||
threshold: 80
|
||||
required: true
|
||||
|
||||
# Require PR merged
|
||||
- type: "pr_merged"
|
||||
required: true
|
||||
|
||||
# Require approval from tech lead
|
||||
- type: "approval"
|
||||
approvers: ["@tech-lead"]
|
||||
required: true
|
||||
```
|
||||
|
||||
### Post-Closing Actions
|
||||
|
||||
Trigger actions after closing:
|
||||
|
||||
```yaml
|
||||
plugins:
|
||||
settings:
|
||||
specweave-github:
|
||||
post_close:
|
||||
# Create release tag
|
||||
- action: "create_tag"
|
||||
format: "increment-{{id}}"
|
||||
|
||||
# Trigger deployment
|
||||
- action: "github_workflow"
|
||||
workflow: "deploy.yml"
|
||||
inputs:
|
||||
increment: "{{id}}"
|
||||
|
||||
# Notify team
|
||||
- action: "slack_notification"
|
||||
channel: "#releases"
|
||||
message: "Increment {{id}} completed! 🎉"
|
||||
|
||||
# Archive to notion
|
||||
- action: "notion_export"
|
||||
database: "Completed Increments"
|
||||
```
|
||||
|
||||
### Bulk Close
|
||||
|
||||
Close multiple completed increments:
|
||||
|
||||
```bash
|
||||
# Close all completed increments
|
||||
/specweave:github:close-issue --status completed --all
|
||||
|
||||
# Close specific increments
|
||||
for i in 0004 0005 0006; do
|
||||
/specweave:github:close-issue $i
|
||||
done
|
||||
```
|
||||
|
||||
### Reopen with Context
|
||||
|
||||
Reopen issue with explanation:
|
||||
|
||||
```bash
|
||||
/specweave:github:close-issue 0004 --reopen \
|
||||
--comment "Reopening: Critical bug found in production (issue #140). Need to add rollback mechanism."
|
||||
```
|
||||
|
||||
### Close and Lock
|
||||
|
||||
Close and lock issue to prevent further comments:
|
||||
|
||||
```bash
|
||||
/specweave:github:close-issue 0004 --lock \
|
||||
--lock-reason "resolved" # or "off-topic", "spam", "too heated"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Command**: `/specweave:github:close-issue`
|
||||
**Plugin**: specweave-github
|
||||
**Agent**: github-manager
|
||||
**Version**: 1.0.0
|
||||
**Last Updated**: 2025-10-30
|
||||
307
commands/specweave-github-create-issue.md
Normal file
307
commands/specweave-github-create-issue.md
Normal file
@@ -0,0 +1,307 @@
|
||||
---
|
||||
name: specweave-github:create-issue
|
||||
description: Create a GitHub issue for a SpecWeave increment. Generates issue from increment specs with task checklist, labels, and milestone. Links issue to increment metadata.
|
||||
---
|
||||
|
||||
# Create GitHub Issue from Increment
|
||||
|
||||
Create a GitHub issue for the specified SpecWeave increment.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/specweave:github:create-issue <increment-id> [options]
|
||||
```
|
||||
|
||||
## Arguments
|
||||
|
||||
- `increment-id`: Increment ID (e.g., `0004` or `0004-plugin-architecture`)
|
||||
|
||||
## Options
|
||||
|
||||
- `--force`: Force create even if issue already exists
|
||||
- `--labels`: Comma-separated labels (default: from config)
|
||||
- `--milestone`: Milestone name (default: from config)
|
||||
- `--assignee`: Assign to user (@username)
|
||||
- `--project`: Add to GitHub project (project number)
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Basic usage
|
||||
/specweave:github:create-issue 0004
|
||||
|
||||
# With custom labels
|
||||
/specweave:github:create-issue 0004 --labels "urgent,backend"
|
||||
|
||||
# Assign to developer
|
||||
/specweave:github:create-issue 0004 --assignee @developer1
|
||||
|
||||
# Add to project
|
||||
/specweave:github:create-issue 0004 --project 3
|
||||
|
||||
# Force recreate
|
||||
/specweave:github:create-issue 0004 --force
|
||||
```
|
||||
|
||||
## What This Command Does
|
||||
|
||||
1. **Loads Increment**
|
||||
- Reads `.specweave/increments/<increment-id>/`
|
||||
- Parses `spec.md`, `plan.md`, `tasks.md`
|
||||
- Checks `.metadata.yaml` for existing issue
|
||||
|
||||
2. **Detects Repository**
|
||||
- Extracts repo from git remote
|
||||
- Format: `owner/repo`
|
||||
- Verifies write permissions
|
||||
|
||||
3. **Generates Issue Body**
|
||||
- Executive summary from `spec.md`
|
||||
- Task checklist from `tasks.md`
|
||||
- Progress tracker (0% initially)
|
||||
- Links to increment files
|
||||
|
||||
4. **Creates GitHub Issue** (via GitHub CLI)
|
||||
- Uses `gh issue create`
|
||||
- Applies labels (specweave, increment, priority)
|
||||
- Sets milestone (if configured)
|
||||
- Assigns to user (if specified)
|
||||
|
||||
5. **Updates Metadata**
|
||||
- Saves issue number to `.metadata.yaml`
|
||||
- Stores issue URL
|
||||
- Logs creation timestamp
|
||||
|
||||
6. **Reports Result**
|
||||
- Issue number and URL
|
||||
- Labels applied
|
||||
- Milestone set
|
||||
- Auto-sync status
|
||||
|
||||
## Requirements
|
||||
|
||||
- GitHub CLI (`gh`) installed and authenticated
|
||||
- Write access to repository
|
||||
- Valid increment directory
|
||||
|
||||
## Configuration
|
||||
|
||||
Settings from `.specweave/config.yaml`:
|
||||
|
||||
```yaml
|
||||
plugins:
|
||||
settings:
|
||||
specweave-github:
|
||||
repo: "owner/repo" # Auto-detected from git remote
|
||||
default_labels:
|
||||
- "specweave"
|
||||
- "increment"
|
||||
milestone: "v0.4.0" # Optional
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Increment not found**:
|
||||
```
|
||||
❌ Error: Increment '0004' not found
|
||||
|
||||
Check: ls .specweave/increments/
|
||||
```
|
||||
|
||||
**Issue already exists**:
|
||||
```
|
||||
⚠️ GitHub issue already exists for increment 0004
|
||||
|
||||
Issue #130: https://github.com/owner/repo/issues/130
|
||||
|
||||
Use --force to recreate (will close existing issue first).
|
||||
```
|
||||
|
||||
**GitHub CLI not authenticated**:
|
||||
```
|
||||
❌ Error: GitHub CLI not authenticated
|
||||
|
||||
Please run: gh auth login
|
||||
|
||||
Then retry this command.
|
||||
```
|
||||
|
||||
**No write permissions**:
|
||||
```
|
||||
❌ Error: Insufficient permissions
|
||||
|
||||
Required: Write access to owner/repo
|
||||
|
||||
Contact repository admin to request access.
|
||||
```
|
||||
|
||||
## Implementation
|
||||
|
||||
This command invokes the `github-manager` agent via the Task tool:
|
||||
|
||||
```typescript
|
||||
const agent = new TaskAgent('github-manager', {
|
||||
prompt: `Create GitHub issue for increment ${incrementId}`,
|
||||
context: {
|
||||
incrementPath: `.specweave/increments/${incrementId}`,
|
||||
options: { force, labels, milestone, assignee, project }
|
||||
}
|
||||
});
|
||||
|
||||
await agent.execute();
|
||||
```
|
||||
|
||||
The agent handles:
|
||||
- File reading (spec.md, tasks.md)
|
||||
- GitHub API calls (via `gh` CLI)
|
||||
- Metadata updates
|
||||
- Error handling
|
||||
|
||||
## Output Format
|
||||
|
||||
### Success
|
||||
|
||||
```
|
||||
📦 Creating GitHub issue for increment 0004...
|
||||
|
||||
✓ Increment loaded: 0004-plugin-architecture
|
||||
✓ Repository detected: owner/repo
|
||||
✓ Issue body generated (2,500 characters)
|
||||
|
||||
Creating issue...
|
||||
✓ Issue #130 created
|
||||
✓ Labels applied: specweave, increment, P1
|
||||
✓ Milestone set: v0.4.0
|
||||
✓ Metadata updated
|
||||
|
||||
✅ GitHub Issue Created! (❌ DEPRECATED FORMAT)
|
||||
|
||||
Issue #130: [Increment 0004] Plugin Architecture # ❌ DEPRECATED
|
||||
URL: https://github.com/owner/repo/issues/130
|
||||
|
||||
Auto-sync enabled: progress will update automatically after each task.
|
||||
```
|
||||
|
||||
### Failure
|
||||
|
||||
```
|
||||
❌ Failed to create GitHub issue
|
||||
|
||||
Error: API rate limit exceeded
|
||||
Rate limit resets at: 2025-10-30 15:30:00
|
||||
|
||||
Options:
|
||||
1. Wait 30 minutes
|
||||
2. Use authenticated token (higher limit)
|
||||
|
||||
Run /specweave:github:status 0004 to check sync state.
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/specweave:github:sync <increment-id>`: Update existing issue
|
||||
- `/specweave:github:close-issue <increment-id>`: Close issue
|
||||
- `/specweave:github:status <increment-id>`: Check sync status
|
||||
|
||||
## Tips
|
||||
|
||||
1. **Auto-Create**: Enable `auto_create_issue: true` in config to auto-create issues when running `/specweave:inc`
|
||||
|
||||
2. **Templates**: Customize issue template in `.specweave/github/issue-template.md`
|
||||
|
||||
3. **Labels**: Use labels for filtering in GitHub Projects:
|
||||
- `specweave`: All SpecWeave increments
|
||||
- `increment`: Differentiate from regular issues
|
||||
- `P0`/`P1`/`P2`/`P3`: Priority levels
|
||||
|
||||
4. **Milestones**: Group increments by release milestone for progress tracking
|
||||
|
||||
5. **Projects**: Add issues to GitHub Projects for Kanban-style tracking
|
||||
|
||||
## Advanced
|
||||
|
||||
### Custom Issue Body Template
|
||||
|
||||
Create `.specweave/github/issue-template.md`:
|
||||
|
||||
```markdown
|
||||
# [Increment {{id}}] {{title}}
|
||||
|
||||
{{summary}}
|
||||
|
||||
## Details
|
||||
|
||||
- **Spec**: [spec.md]({{spec_url}})
|
||||
- **Priority**: {{priority}}
|
||||
- **Duration**: {{duration}}
|
||||
|
||||
## Tasks
|
||||
|
||||
{{tasks}}
|
||||
|
||||
---
|
||||
|
||||
_Auto-created by SpecWeave_
|
||||
```
|
||||
|
||||
### Bulk Create
|
||||
|
||||
Create issues for multiple increments:
|
||||
|
||||
```bash
|
||||
for i in 0004 0005 0006; do
|
||||
/specweave:github:create-issue $i
|
||||
done
|
||||
```
|
||||
|
||||
Or using a script:
|
||||
|
||||
```bash
|
||||
# Create issues for all increments in backlog
|
||||
ls .specweave/increments/_backlog/ | while read inc; do
|
||||
/specweave:github:create-issue $inc
|
||||
done
|
||||
```
|
||||
|
||||
### Dry Run
|
||||
|
||||
Preview issue body before creating:
|
||||
|
||||
```bash
|
||||
/specweave:github:create-issue 0004 --dry-run
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
📄 Preview: Issue body for increment 0004 (❌ DEPRECATED FORMAT)
|
||||
|
||||
Title: [Increment 0004] Plugin Architecture # ❌ DEPRECATED
|
||||
Labels: specweave, increment, P1
|
||||
Milestone: v0.4.0
|
||||
|
||||
Body:
|
||||
---
|
||||
# [Increment 0004] Plugin Architecture # ❌ DEPRECATED
|
||||
|
||||
**Status**: Planning
|
||||
**Priority**: P1
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Implement a modular plugin architecture for SpecWeave...
|
||||
|
||||
[... full body ...]
|
||||
|
||||
---
|
||||
|
||||
Run without --dry-run to create this issue.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Command**: `/specweave:github:create-issue`
|
||||
**Plugin**: specweave-github
|
||||
**Agent**: github-manager
|
||||
**Version**: 1.0.0
|
||||
**Last Updated**: 2025-10-30
|
||||
110
commands/specweave-github-reconcile.md
Normal file
110
commands/specweave-github-reconcile.md
Normal file
@@ -0,0 +1,110 @@
|
||||
---
|
||||
name: specweave-github:reconcile
|
||||
description: Reconcile GitHub issue states with increment statuses. Fixes drift by closing issues for completed increments and reopening issues for resumed increments.
|
||||
---
|
||||
|
||||
# GitHub Status Reconciliation
|
||||
|
||||
Scan all increments and fix any drift between local metadata.json status and GitHub issue states.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/specweave-github:reconcile [options]
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
- `--dry-run`: Preview changes without making them
|
||||
- `--verbose`: Show detailed output for each issue checked
|
||||
|
||||
## What It Does
|
||||
|
||||
1. **Scans** all non-archived increments
|
||||
2. **Compares** metadata.json status with GitHub issue state
|
||||
3. **Fixes** mismatches:
|
||||
- `metadata=completed` + `GH=open` → **Close** the issue
|
||||
- `metadata=in-progress` + `GH=closed` → **Reopen** the issue
|
||||
|
||||
## When to Use
|
||||
|
||||
- After manual metadata.json edits
|
||||
- After git pulls that changed increment statuses
|
||||
- When you notice open issues for completed work
|
||||
- As a periodic health check
|
||||
|
||||
## Implementation
|
||||
|
||||
Run the reconciliation using the GitHubReconciler:
|
||||
|
||||
```typescript
|
||||
import { GitHubReconciler } from '../../../src/sync/github-reconciler.js';
|
||||
|
||||
const reconciler = new GitHubReconciler({
|
||||
projectRoot: process.cwd(),
|
||||
dryRun: args.includes('--dry-run'),
|
||||
});
|
||||
|
||||
const result = await reconciler.reconcile();
|
||||
|
||||
// Report results
|
||||
console.log(`\nReconciliation complete:`);
|
||||
console.log(` Scanned: ${result.scanned} increments`);
|
||||
console.log(` Fixed: ${result.closed} closed, ${result.reopened} reopened`);
|
||||
if (result.errors.length > 0) {
|
||||
console.log(` Errors: ${result.errors.length}`);
|
||||
}
|
||||
```
|
||||
|
||||
## Example Output
|
||||
|
||||
```
|
||||
📊 Scanning 5 increment(s) for GitHub state drift...
|
||||
|
||||
✅ Issue #765 (0056-plugin-fix/US-001): State matches (open)
|
||||
❌ Issue #771 (0066-import-wizard/US-003): OPEN but should be CLOSED (status=completed)
|
||||
✅ Closed issue #771
|
||||
❌ Issue #763 (0063-multi-repo/US-001): CLOSED but should be OPEN (status=in-progress)
|
||||
✅ Reopened issue #763
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
📊 RECONCILIATION SUMMARY
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Increments scanned: 5
|
||||
Mismatches found: 2
|
||||
Issues closed: 1
|
||||
Issues reopened: 1
|
||||
Errors: 0
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
## Dry Run Mode
|
||||
|
||||
```bash
|
||||
/specweave-github:reconcile --dry-run
|
||||
```
|
||||
|
||||
Shows what would be changed without making any modifications:
|
||||
|
||||
```
|
||||
❌ Issue #771 (0066-import-wizard/US-003): OPEN but should be CLOSED
|
||||
[DRY RUN] Would close issue #771
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
📊 RECONCILIATION SUMMARY
|
||||
⚠️ DRY RUN - No changes were made
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- GitHub CLI (`gh`) installed and authenticated
|
||||
- `sync.github.enabled = true` in config.json
|
||||
- `sync.settings.canUpdateExternalItems = true` in config.json
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/specweave-github:status`: View sync status for increments
|
||||
- `/specweave-github:sync`: Manual sync to GitHub
|
||||
- `/specweave:done`: Close increment (triggers auto-close)
|
||||
- `/specweave:resume`: Resume increment (now triggers auto-reopen)
|
||||
533
commands/specweave-github-status.md
Normal file
533
commands/specweave-github-status.md
Normal file
@@ -0,0 +1,533 @@
|
||||
---
|
||||
name: specweave-github:status
|
||||
description: Check GitHub sync status for SpecWeave increment. Shows issue number, sync state, progress, last update, and any sync issues. Useful for troubleshooting and monitoring.
|
||||
---
|
||||
|
||||
# Check GitHub Sync Status
|
||||
|
||||
Display the current GitHub sync status for a SpecWeave increment.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/specweave:github:status [increment-id] [options]
|
||||
```
|
||||
|
||||
## Arguments
|
||||
|
||||
- `increment-id`: Increment ID (optional, defaults to current increment)
|
||||
|
||||
## Options
|
||||
|
||||
- `--all`: Show status for all increments
|
||||
- `--verbose`: Show detailed sync information
|
||||
- `--json`: Output in JSON format
|
||||
- `--check-health`: Run health check on sync connection
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Check current increment
|
||||
/specweave:github:status
|
||||
|
||||
# Check specific increment
|
||||
/specweave:github:status 0004
|
||||
|
||||
# Check all increments
|
||||
/specweave:github:status --all
|
||||
|
||||
# Verbose output with full details
|
||||
/specweave:github:status 0004 --verbose
|
||||
|
||||
# JSON output for scripting
|
||||
/specweave:github:status 0004 --json
|
||||
|
||||
# Health check
|
||||
/specweave:github:status --check-health
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
### Basic Status
|
||||
|
||||
```
|
||||
📊 GitHub Sync Status: Increment 0004
|
||||
|
||||
Increment: 0004-plugin-architecture
|
||||
Status: In Progress
|
||||
Priority: P1
|
||||
|
||||
GitHub Issue: #130
|
||||
URL: https://github.com/owner/repo/issues/130
|
||||
State: Open
|
||||
Labels: specweave, increment, P1, in-progress
|
||||
|
||||
Sync Status: ✅ Up-to-date
|
||||
Last Synced: 5 minutes ago (2025-10-30 16:55:00)
|
||||
Sync Count: 7
|
||||
Auto-Sync: Enabled (every-task)
|
||||
|
||||
Progress:
|
||||
- Tasks: 7/48 completed (15%)
|
||||
- Week: 1 of 4 (Foundation)
|
||||
- Current Task: T-008 - Implement Cursor compiler
|
||||
|
||||
GitHub vs Local:
|
||||
✅ Progress matches
|
||||
✅ Labels match
|
||||
✅ Status matches
|
||||
✅ No conflicts detected
|
||||
```
|
||||
|
||||
### Verbose Status
|
||||
|
||||
```
|
||||
📊 GitHub Sync Status: Increment 0004 (Detailed)
|
||||
|
||||
═══════════════════════════════════════════
|
||||
BASIC INFO
|
||||
═══════════════════════════════════════════
|
||||
|
||||
Increment ID: 0004
|
||||
Full Name: 0004-plugin-architecture
|
||||
Title: Plugin Architecture
|
||||
Status: in_progress
|
||||
Priority: P1
|
||||
Created: 2025-10-01 10:00:00
|
||||
Duration: 29 days
|
||||
|
||||
═══════════════════════════════════════════
|
||||
GITHUB ISSUE
|
||||
═══════════════════════════════════════════
|
||||
|
||||
Issue Number: #130
|
||||
Issue URL: https://github.com/owner/repo/issues/130
|
||||
Issue State: open
|
||||
Issue Created: 2025-10-01 10:15:00
|
||||
Issue Updated: 2025-10-30 16:55:00
|
||||
|
||||
Labels:
|
||||
- specweave
|
||||
- increment
|
||||
- P1
|
||||
- in-progress
|
||||
|
||||
Milestone: v0.4.0 (due: 2025-11-30)
|
||||
Assignees: @developer1, @developer2
|
||||
|
||||
Comments: 12
|
||||
- 7 auto-sync comments
|
||||
- 5 manual comments
|
||||
|
||||
Last Comment:
|
||||
By: @developer2
|
||||
At: 2025-10-30 16:00:00
|
||||
Text: "Cursor adapter completed, moving to testing..."
|
||||
|
||||
═══════════════════════════════════════════
|
||||
SYNC STATUS
|
||||
═══════════════════════════════════════════
|
||||
|
||||
Sync State: ✅ Up-to-date
|
||||
Last Synced: 5 minutes ago (2025-10-30 16:55:00)
|
||||
Sync Method: Auto (post-task hook)
|
||||
Sync Count: 7
|
||||
Failed Syncs: 0
|
||||
|
||||
Auto-Sync Settings:
|
||||
- Enabled: Yes
|
||||
- Frequency: every-task
|
||||
- Post Comments: Yes
|
||||
- Update Checklist: Yes
|
||||
- Update Labels: Yes
|
||||
- Include Files: Yes
|
||||
- Include Time: Yes
|
||||
|
||||
═══════════════════════════════════════════
|
||||
PROGRESS
|
||||
═══════════════════════════════════════════
|
||||
|
||||
Tasks: 7/48 completed (15%)
|
||||
|
||||
Week 1: Foundation (7/12 tasks, 58%)
|
||||
✅ T-001: Plugin types
|
||||
✅ T-002: Manifest schema
|
||||
✅ T-003: PluginLoader
|
||||
✅ T-004: PluginManager
|
||||
✅ T-005: PluginDetector
|
||||
✅ T-006: Adapter interface
|
||||
✅ T-007: Claude installer
|
||||
⏳ T-008: Cursor compiler (in progress)
|
||||
⏸️ T-009: Copilot compiler
|
||||
⏸️ T-010: Generic compiler
|
||||
⏸️ T-011: Config schema
|
||||
⏸️ T-012: Update .gitignore
|
||||
|
||||
Week 2: GitHub Plugin (0/10 tasks, 0%)
|
||||
Week 3: Additional Plugins (0/15 tasks, 0%)
|
||||
Week 4: Documentation (0/11 tasks, 0%)
|
||||
|
||||
Current Task: T-008
|
||||
Estimated: 6 hours
|
||||
Started: 2025-10-30 15:00:00
|
||||
Duration: 2 hours (33% of estimate)
|
||||
|
||||
═══════════════════════════════════════════
|
||||
COMPARISON (GitHub vs Local)
|
||||
═══════════════════════════════════════════
|
||||
|
||||
✅ Progress: 7/48 (both sides match)
|
||||
✅ Labels: All 4 labels match
|
||||
✅ Status: in_progress (both sides)
|
||||
✅ Comments: All synced (no missing)
|
||||
|
||||
No conflicts detected.
|
||||
Last comparison: Just now
|
||||
|
||||
═══════════════════════════════════════════
|
||||
METADATA
|
||||
═══════════════════════════════════════════
|
||||
|
||||
Metadata File: .specweave/increments/0004/.metadata.yaml
|
||||
GitHub Section:
|
||||
issue_number: 130
|
||||
issue_url: https://github.com/owner/repo/issues/130
|
||||
created_at: 2025-10-01T10:15:00Z
|
||||
last_synced_at: 2025-10-30T16:55:00Z
|
||||
sync_count: 7
|
||||
closing_comment_ids: []
|
||||
|
||||
Repository: owner/repo
|
||||
Remote URL: https://github.com/owner/repo.git
|
||||
Branch: features/0004-plugin-architecture
|
||||
|
||||
═══════════════════════════════════════════
|
||||
HEALTH
|
||||
═══════════════════════════════════════════
|
||||
|
||||
✅ GitHub CLI: Authenticated
|
||||
✅ Repository Access: Write
|
||||
✅ Issue Exists: Yes
|
||||
✅ Network: Connected
|
||||
✅ Rate Limit: 4,823 / 5,000 remaining
|
||||
✅ Sync Hook: Installed and working
|
||||
|
||||
All systems operational.
|
||||
```
|
||||
|
||||
### Status for All Increments
|
||||
|
||||
```
|
||||
📊 GitHub Sync Status: All Increments
|
||||
|
||||
┌──────┬────────────────┬────────┬────────┬──────────┬─────────────┐
|
||||
│ ID │ Title │ Issue │ State │ Progress │ Last Synced │
|
||||
├──────┼────────────────┼────────┼────────┼──────────┼─────────────┤
|
||||
│ 0001 │ Core Framework │ #100 │ Closed │ 100% │ 30 days ago │
|
||||
│ 0002 │ Enhancements │ #110 │ Closed │ 100% │ 15 days ago │
|
||||
│ 0003 │ Model Select │ #120 │ Closed │ 100% │ 5 days ago │
|
||||
│ 0004 │ Plugins │ #130 │ Open │ 15% │ 5 mins ago │
|
||||
│ 0005 │ Auth │ #135 │ Open │ 0% │ Never │
|
||||
└──────┴────────────────┴────────┴────────┴──────────┴─────────────┘
|
||||
|
||||
Summary:
|
||||
- Total Increments: 5
|
||||
- Synced: 4
|
||||
- Not Synced: 1 (0005)
|
||||
- Open Issues: 2
|
||||
- Closed Issues: 2
|
||||
|
||||
Issues:
|
||||
⚠️ Increment 0005: Not synced to GitHub (run /specweave:github:create-issue 0005)
|
||||
```
|
||||
|
||||
### JSON Output
|
||||
|
||||
```json
|
||||
{
|
||||
"increment": {
|
||||
"id": "0004",
|
||||
"name": "0004-plugin-architecture",
|
||||
"title": "Plugin Architecture",
|
||||
"status": "in_progress",
|
||||
"priority": "P1",
|
||||
"created_at": "2025-10-01T10:00:00Z",
|
||||
"duration_days": 29
|
||||
},
|
||||
"github": {
|
||||
"issue_number": 130,
|
||||
"issue_url": "https://github.com/owner/repo/issues/130",
|
||||
"state": "open",
|
||||
"labels": ["specweave", "increment", "P1", "in-progress"],
|
||||
"milestone": "v0.4.0",
|
||||
"assignees": ["developer1", "developer2"],
|
||||
"comments_count": 12,
|
||||
"created_at": "2025-10-01T10:15:00Z",
|
||||
"updated_at": "2025-10-30T16:55:00Z"
|
||||
},
|
||||
"sync": {
|
||||
"status": "up-to-date",
|
||||
"last_synced_at": "2025-10-30T16:55:00Z",
|
||||
"sync_count": 7,
|
||||
"failed_syncs": 0,
|
||||
"auto_sync_enabled": true,
|
||||
"sync_frequency": "every-task",
|
||||
"conflicts": []
|
||||
},
|
||||
"progress": {
|
||||
"tasks_completed": 7,
|
||||
"tasks_total": 48,
|
||||
"percentage": 15,
|
||||
"current_task": "T-008",
|
||||
"current_week": 1
|
||||
},
|
||||
"health": {
|
||||
"github_cli_authenticated": true,
|
||||
"repository_access": "write",
|
||||
"issue_exists": true,
|
||||
"network_connected": true,
|
||||
"rate_limit_remaining": 4823,
|
||||
"rate_limit_total": 5000,
|
||||
"sync_hook_working": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Health Check
|
||||
|
||||
```
|
||||
🏥 GitHub Sync Health Check
|
||||
|
||||
Checking system components...
|
||||
|
||||
✅ GitHub CLI
|
||||
Version: 2.38.0
|
||||
Authenticated: Yes
|
||||
User: developer1
|
||||
|
||||
✅ Repository Access
|
||||
Repository: owner/repo
|
||||
Access Level: Write
|
||||
Remote: https://github.com/owner/repo.git
|
||||
|
||||
✅ Network Connectivity
|
||||
GitHub API: Reachable
|
||||
Latency: 45ms
|
||||
Status: All systems operational
|
||||
|
||||
✅ Rate Limits
|
||||
Remaining: 4,823 / 5,000
|
||||
Resets at: 2025-10-30 17:00:00 (5 minutes)
|
||||
Status: Healthy
|
||||
|
||||
✅ Sync Configuration
|
||||
Config file: .specweave/config.yaml
|
||||
Plugin enabled: Yes
|
||||
Auto-sync: Enabled
|
||||
Frequency: every-task
|
||||
|
||||
✅ Hooks
|
||||
Post-task hook: Installed
|
||||
Last fired: 5 minutes ago
|
||||
Status: Working
|
||||
|
||||
✅ Metadata Integrity
|
||||
Metadata file: Exists
|
||||
Issue number: 130 (valid)
|
||||
Timestamps: Consistent
|
||||
|
||||
All systems healthy! ✅
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Settings from `.specweave/config.yaml`:
|
||||
|
||||
```yaml
|
||||
plugins:
|
||||
settings:
|
||||
specweave-github:
|
||||
# Display settings
|
||||
status_display:
|
||||
default_format: "basic" # or "verbose", "json"
|
||||
show_health: true
|
||||
show_comparison: true
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
### 1. Quick Progress Check
|
||||
|
||||
```bash
|
||||
/specweave:github:status 0004
|
||||
```
|
||||
|
||||
See current sync state, progress, and last update time.
|
||||
|
||||
### 2. Troubleshooting Sync Issues
|
||||
|
||||
```bash
|
||||
/specweave:github:status 0004 --verbose
|
||||
```
|
||||
|
||||
Get detailed sync information to diagnose problems.
|
||||
|
||||
### 3. Monitoring All Increments
|
||||
|
||||
```bash
|
||||
/specweave:github:status --all
|
||||
```
|
||||
|
||||
Dashboard view of all increments and their sync state.
|
||||
|
||||
### 4. CI/CD Integration
|
||||
|
||||
```bash
|
||||
/specweave:github:status 0004 --json | jq '.sync.status'
|
||||
```
|
||||
|
||||
Check sync status in scripts/automation.
|
||||
|
||||
### 5. Health Monitoring
|
||||
|
||||
```bash
|
||||
/specweave:github:status --check-health
|
||||
```
|
||||
|
||||
Verify all sync components are working correctly.
|
||||
|
||||
## Interpreting Status
|
||||
|
||||
### Sync States
|
||||
|
||||
| State | Meaning |
|
||||
|-------|---------|
|
||||
| ✅ Up-to-date | Local and GitHub match |
|
||||
| ⚠️ Out of sync | Changes not yet synced |
|
||||
| 🔄 Syncing | Sync in progress |
|
||||
| ❌ Failed | Last sync failed |
|
||||
| ⏸️ Paused | Auto-sync disabled |
|
||||
| ❓ Unknown | Cannot determine state |
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Out of Sync**:
|
||||
```
|
||||
⚠️ Sync Status: Out of sync (2 changes pending)
|
||||
|
||||
Local changes not synced to GitHub:
|
||||
- Task T-008 completed (1 hour ago)
|
||||
- Task T-009 started (30 minutes ago)
|
||||
|
||||
Action: Run /specweave:github:sync 0004
|
||||
```
|
||||
|
||||
**Sync Failed**:
|
||||
```
|
||||
❌ Sync Status: Failed (last attempt 10 minutes ago)
|
||||
|
||||
Error: Rate limit exceeded
|
||||
Rate limit resets at: 2025-10-30 17:00:00
|
||||
|
||||
Action: Wait for rate limit reset, then retry
|
||||
```
|
||||
|
||||
**No GitHub Issue**:
|
||||
```
|
||||
⚠️ Sync Status: Not synced
|
||||
|
||||
No GitHub issue found for increment 0004.
|
||||
|
||||
Action: Create issue first
|
||||
/specweave:github:create-issue 0004
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- GitHub CLI (`gh`) installed
|
||||
- Valid increment directory
|
||||
- Network connectivity (for GitHub API checks)
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/specweave:github:create-issue`: Create GitHub issue
|
||||
- `/specweave:github:sync`: Sync increment with GitHub
|
||||
- `/specweave:github:close-issue`: Close GitHub issue
|
||||
- `/specweave:progress`: Check increment progress (local only)
|
||||
|
||||
## Tips
|
||||
|
||||
1. **Quick Check**: Run `/specweave:github:status` before syncing to see if sync is needed
|
||||
|
||||
2. **Verbose Mode**: Use `--verbose` when troubleshooting sync issues
|
||||
|
||||
3. **JSON Output**: Use `--json` for automation and scripting
|
||||
|
||||
4. **Health Check**: Run `--check-health` if syncs are failing
|
||||
|
||||
5. **Monitor All**: Use `--all` to get a dashboard of all increments
|
||||
|
||||
## Advanced
|
||||
|
||||
### Watch Mode
|
||||
|
||||
Monitor sync status in real-time:
|
||||
|
||||
```bash
|
||||
# Refresh every 30 seconds
|
||||
watch -n 30 '/specweave:github:status 0004'
|
||||
```
|
||||
|
||||
### Custom Health Checks
|
||||
|
||||
Define custom health checks:
|
||||
|
||||
```yaml
|
||||
plugins:
|
||||
settings:
|
||||
specweave-github:
|
||||
health_checks:
|
||||
- name: "Rate Limit"
|
||||
threshold: 100 # Warn if < 100 remaining
|
||||
critical: 10 # Error if < 10
|
||||
|
||||
- name: "Sync Lag"
|
||||
threshold: 3600 # Warn if not synced in 1 hour
|
||||
critical: 86400 # Error if not synced in 24 hours
|
||||
```
|
||||
|
||||
### Status Notifications
|
||||
|
||||
Get notified of status changes:
|
||||
|
||||
```yaml
|
||||
plugins:
|
||||
settings:
|
||||
specweave-github:
|
||||
notifications:
|
||||
- event: "sync_failed"
|
||||
action: "slack"
|
||||
channel: "#dev-alerts"
|
||||
|
||||
- event: "rate_limit_low"
|
||||
threshold: 100
|
||||
action: "email"
|
||||
recipients: ["admin@example.com"]
|
||||
```
|
||||
|
||||
### Status Dashboard
|
||||
|
||||
Generate HTML dashboard:
|
||||
|
||||
```bash
|
||||
/specweave:github:status --all --format html > status.html
|
||||
open status.html
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Command**: `/specweave:github:status`
|
||||
**Plugin**: specweave-github
|
||||
**Agent**: github-manager
|
||||
**Version**: 1.0.0
|
||||
**Last Updated**: 2025-10-30
|
||||
674
commands/specweave-github-sync.md
Normal file
674
commands/specweave-github-sync.md
Normal file
@@ -0,0 +1,674 @@
|
||||
---
|
||||
name: specweave-github:sync
|
||||
description: 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
/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<br>• Pull changes FROM GitHub (status, labels, comments)<br>• Push changes TO GitHub (tasks, progress, metadata) | **Always** (recommended for keeping both systems in sync) |
|
||||
| `to-github` | SpecWeave → GitHub only<br>• Push increment progress to GitHub<br>• Don't pull GitHub changes back | Read-only GitHub usage, or when GitHub is downstream |
|
||||
| `from-github` | GitHub → SpecWeave only<br>• Pull GitHub issue updates<br>• 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:**
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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`:
|
||||
|
||||
```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):
|
||||
|
||||
```env
|
||||
# GitHub
|
||||
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
|
||||
```
|
||||
|
||||
### Per-Increment Configuration
|
||||
|
||||
Each increment stores its sync metadata in `.specweave/increments/{id}/metadata.json`:
|
||||
|
||||
```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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
/specweave:sync-profile create
|
||||
```
|
||||
|
||||
2. Update increment metadata:
|
||||
```json
|
||||
{
|
||||
"sync": {
|
||||
"profile": "default-github",
|
||||
"issueNumber": 130
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. Test sync:
|
||||
```bash
|
||||
/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:
|
||||
```bash
|
||||
gh api rate_limit
|
||||
```
|
||||
|
||||
Output:
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
```json
|
||||
{
|
||||
"sync": {
|
||||
"settings": {
|
||||
"autoSync": true,
|
||||
"syncFrequency": "every-task",
|
||||
"rateLimitProtection": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Use Dry Run for Testing
|
||||
|
||||
Before large syncs:
|
||||
```bash
|
||||
/specweave-github:sync 0004 --dry-run --time-range 6M
|
||||
```
|
||||
|
||||
This shows what would happen without actually executing.
|
||||
|
||||
## Advanced
|
||||
|
||||
### Batch Sync Multiple Increments
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```json
|
||||
{
|
||||
"sync": {
|
||||
"profiles": {
|
||||
"my-profile": {
|
||||
"rateLimits": {
|
||||
"maxItemsPerSync": 1000,
|
||||
"warnThreshold": 200
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Resume Failed Syncs
|
||||
|
||||
If sync fails mid-operation:
|
||||
```bash
|
||||
/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+
|
||||
156
commands/specweave-github-update-user-story.md
Normal file
156
commands/specweave-github-update-user-story.md
Normal file
@@ -0,0 +1,156 @@
|
||||
---
|
||||
name: specweave-github-update-user-story
|
||||
description: Update GitHub issue for user story with proper ACs and tasks
|
||||
---
|
||||
|
||||
# Update User Story GitHub Issue
|
||||
|
||||
**Purpose**: Update an existing GitHub issue for a user story to include:
|
||||
- ✅ Checkable acceptance criteria (GitHub task checkboxes)
|
||||
- ✅ Task connections (links to increment tasks)
|
||||
- ✅ Proper formatting and status
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
/specweave-github:update-user-story FS-031 US-004
|
||||
```
|
||||
|
||||
**What It Does**:
|
||||
|
||||
1. **Finds user story file**: `.specweave/docs/internal/specs/{project}/FS-031/us-004-*.md`
|
||||
2. **Parses content**:
|
||||
- User story description (As a... I want... So that...)
|
||||
- Acceptance criteria with completion status
|
||||
- Tasks from increment tasks.md
|
||||
3. **Finds existing GitHub issue**: Searches for `[FS-031][US-004]` or `[FS-031 US-004]`
|
||||
4. **Updates issue body**: Replaces with properly formatted content including:
|
||||
- Checkable ACs
|
||||
- Task connections
|
||||
- Status and progress
|
||||
|
||||
**Arguments**:
|
||||
- `featureId` - Feature ID (e.g., `FS-031`)
|
||||
- `userStoryId` - User Story ID (e.g., `US-004`)
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
# Update US-004 in FS-031
|
||||
/specweave-github:update-user-story FS-031 US-004
|
||||
|
||||
# Output:
|
||||
# 🔍 Finding user story: FS-031/US-004
|
||||
# 📄 Found: .specweave/docs/internal/specs/default/FS-031/us-004-bidirectional-status-sync.md
|
||||
# 🔍 Searching for existing GitHub issue...
|
||||
# 🔗 Found issue #501: [FS-031][US-004] Bidirectional Status Sync
|
||||
# 📝 Building updated issue body...
|
||||
# ✅ 6 acceptance criteria (4 completed)
|
||||
# ✅ 6 tasks (3 completed)
|
||||
# 🚀 Updating GitHub issue #501...
|
||||
# ✅ Updated successfully!
|
||||
# 🔗 https://github.com/owner/repo/issues/501
|
||||
```
|
||||
|
||||
**What Gets Updated**:
|
||||
|
||||
```markdown
|
||||
**Feature**: [FS-031](../../_features/_archive/FS-031/FEATURE.md)
|
||||
**Status**: complete
|
||||
**Priority**: P1
|
||||
**Project**: default
|
||||
|
||||
---
|
||||
|
||||
## User Story
|
||||
|
||||
**As a** PM
|
||||
**I want** status changes in external tools to sync back to SpecWeave
|
||||
**So that** both systems stay in sync without manual updates
|
||||
|
||||
📄 View full story: [`us-004-bidirectional-status-sync.md`](...)
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
Progress: 4/6 criteria met (67%)
|
||||
|
||||
- [x] **AC-US4-01**: SpecWeave status change triggers external update (P1, testable)
|
||||
- [x] **AC-US4-02**: External issue close triggers SpecWeave prompt (P1, testable)
|
||||
- [x] **AC-US4-03**: External issue reopen triggers SpecWeave prompt (P2, testable)
|
||||
- [x] **AC-US4-04**: Sync logs include timestamp and reason (P2, testable)
|
||||
- [ ] **AC-US4-05**: Failed syncs retry with exponential backoff (P2, testable)
|
||||
- [ ] **AC-US4-06**: Sync works for GitHub, JIRA, and ADO (P1, testable)
|
||||
|
||||
---
|
||||
|
||||
## Implementation Tasks
|
||||
|
||||
Progress: 3/6 tasks complete (50%)
|
||||
|
||||
**Increment**: [0031-external-tool-status-sync](../../increments/0031-external-tool-status-sync/)
|
||||
|
||||
- [x] [T-008: Create Status Sync Engine (Core)](../../increments/0031/tasks.md#t-008-create-status-sync-engine-core)
|
||||
- [x] [T-009: Implement GitHub Status Sync](../../increments/0031/tasks.md#t-009-implement-github-status-sync)
|
||||
- [x] [T-010: Implement JIRA Status Sync](../../increments/0031/tasks.md#t-010-implement-jira-status-sync)
|
||||
- [ ] [T-011: Implement ADO Status Sync](../../increments/0031/tasks.md#t-011-implement-ado-status-sync)
|
||||
- [ ] [T-018: Add Sync Event Logging](../../increments/0031/tasks.md#t-018-add-sync-event-logging)
|
||||
- [ ] [T-021: Error Handling & Retry Logic](../../increments/0031/tasks.md#t-021-error-handling-retry-logic)
|
||||
|
||||
---
|
||||
|
||||
🤖 Auto-synced by SpecWeave User Story Sync
|
||||
```
|
||||
|
||||
**When to Use**:
|
||||
|
||||
- ✅ After completing increment implementation (update task statuses)
|
||||
- ✅ After modifying acceptance criteria
|
||||
- ✅ When GitHub issue is missing proper formatting
|
||||
- ✅ When you want to refresh issue content from living docs
|
||||
|
||||
**Related Commands**:
|
||||
- `/specweave-github:sync-epic FS-031` - Sync entire epic (all user stories)
|
||||
- `/specweave-github:create-issue 0031` - Create issue for increment
|
||||
- `/specweave-github:sync 0031` - Two-way sync for increment
|
||||
|
||||
---
|
||||
|
||||
## Implementation
|
||||
|
||||
**File**: `plugins/specweave-github/lib/user-story-content-builder.ts`
|
||||
|
||||
**Workflow**:
|
||||
1. Parse user story file with `UserStoryContentBuilder`
|
||||
2. Search GitHub for existing issue (title pattern matching)
|
||||
3. Build rich issue body with checkable ACs and task links
|
||||
4. Update issue via `gh issue edit` with new body
|
||||
|
||||
**Error Handling**:
|
||||
- ✅ Graceful fallback if user story file not found
|
||||
- ✅ Clear error if GitHub issue doesn't exist
|
||||
- ✅ Validation of required fields (epic, status, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Execution
|
||||
|
||||
When user runs this command, the Claude Code assistant should:
|
||||
|
||||
1. Extract `featureId` and `userStoryId` from command arguments
|
||||
2. Find user story file in living docs (search all projects)
|
||||
3. Use `UserStoryContentBuilder` to parse and build issue body
|
||||
4. Search for existing GitHub issue using `gh issue list --search`
|
||||
5. Update issue using `gh issue edit --body`
|
||||
6. Report success with issue URL
|
||||
|
||||
**Tech Stack**:
|
||||
- TypeScript (UserStoryContentBuilder class)
|
||||
- GitHub CLI (`gh issue list`, `gh issue edit`)
|
||||
- YAML frontmatter parsing
|
||||
- Markdown formatting
|
||||
|
||||
**Testing**:
|
||||
- Test with FS-031/US-004 (bidirectional status sync)
|
||||
- Verify ACs are checkable
|
||||
- Verify tasks link to correct increment tasks.md
|
||||
- Verify progress percentages are correct
|
||||
Reference in New Issue
Block a user