specweave 0.17.16 → 0.18.0

package/plugins/specweave-github/commands/specweave-github-cleanup-duplicates.md

@@ -0,0 +1,205 @@
+---
+name: specweave-github-cleanup-duplicates
+description: Clean up duplicate GitHub issues for an Epic. Finds issues with duplicate titles and closes all except the first created issue.
+---
+
+# 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-epic` - Sync Epic (now with duplicate detection!)
+- `/specweave:validate` - Validate increment completeness
+- `gh issue list` - View all issues (GitHub CLI)
+
+## Implementation
+
+**File**: `plugins/specweave-github/lib/github-epic-sync.ts`
+
+**Method**: `cleanupDuplicates(epicId: string, dryRun: boolean)`
+
+**Algorithm**:
+1. Search GitHub for all issues with Epic 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
+5. Update Epic README frontmatter
+
+## Next Steps
+
+After cleanup:
+
+1. **Verify cleanup**: `gh issue list --search "[FS-031]"`
+2. **Check Epic README**: Verify frontmatter has correct issue numbers
+3. **Re-run sync**: `/specweave-github:sync-epic FS-031` (should show no duplicates)
+4. **Enable duplicate detection**: Already enabled in v0.18.0+
+
+---
+
+**✅ SAFE TO USE**: This command is idempotent and safe to run multiple times.

package/plugins/specweave-github/commands/specweave-github-sync-epic.md

@@ -0,0 +1,248 @@
+---
+name: specweave-github-sync-epic
+description: Sync SpecWeave Epic folder to GitHub (Milestone + Issues). Implements Universal Hierarchy architecture - Epic → Milestone, Increments → Issues.
+---
+
+# Sync Epic to GitHub (Universal Hierarchy)
+
+**Architecture**: Hierarchical sync using Epic folder structure
+
+- **Epic (FS-001)** → **GitHub Milestone**
+- **Increment (0001-core-framework)** → **GitHub Issue** (linked to Milestone)
+
+## Usage
+
+```bash
+/specweave-github:sync-epic <epic-id>
+```
+
+## What It Does
+
+**Hierarchical Sync Process**:
+
+1. **Load Epic folder** from `.specweave/docs/internal/specs/FS-XXX-name/`
+2. **Parse Epic README.md** to get Epic metadata (title, increments, status)
+3. **Create or update GitHub Milestone**:
+   - Title: `[FS-001] Epic Title`
+   - Description: Epic overview + progress stats
+   - State: Open (active/planning) or Closed (complete)
+4. **Sync each increment as GitHub Issue**:
+   - Title: `[INC-0001-core-framework] Title`
+   - Body: Increment overview + link to tasks.md
+   - Milestone: Linked to Epic Milestone
+   - Labels: `increment`, `epic-sync`
+5. **Update frontmatter** in Epic README.md and increment files
+
+## Examples
+
+### Sync Epic FS-001 (Core Framework Architecture)
+
+```bash
+/specweave-github:sync-epic FS-001
+```
+
+**Output**:
+```
+🔄 Syncing Epic FS-001 to GitHub...
+   📦 Epic: Core Framework Architecture
+   📊 Increments: 4
+   🚀 Creating GitHub Milestone...
+   ✅ Created Milestone #10
+
+   📝 Syncing 4 increments...
+   ✅ Created Issue #130 for 0001-core-framework
+   ✅ Created Issue #131 for 0002-core-enhancements
+   ✅ Created Issue #132 for 0004-plugin-architecture
+   ✅ Created Issue #133 for 0005-cross-platform-cli
+
+✅ Epic sync complete!
+   Milestone: https://github.com/owner/repo/milestone/10
+   Issues created: 4
+   Issues updated: 0
+```
+
+### Sync Epic with short ID
+
+```bash
+/specweave-github:sync-epic 031
+# Resolves to FS-031
+```
+
+### Re-sync Epic (updates existing Milestone/Issues)
+
+```bash
+/specweave-github:sync-epic FS-001
+```
+
+**Output**:
+```
+🔄 Syncing Epic FS-001 to GitHub...
+   ♻️  Updating existing Milestone #10...
+   ✅ Updated Milestone #10
+
+   📝 Syncing 4 increments...
+   ♻️  Updated Issue #130 for 0001-core-framework
+   ♻️  Updated Issue #131 for 0002-core-enhancements
+   ♻️  Updated Issue #132 for 0004-plugin-architecture
+   ♻️  Updated Issue #133 for 0005-cross-platform-cli
+
+✅ Epic sync complete!
+   Milestone: https://github.com/owner/repo/milestone/10
+   Issues created: 0
+   Issues updated: 4
+```
+
+## Arguments
+
+- `<epic-id>` - Epic ID (e.g., `FS-001` or just `001`)
+
+## What Gets Created
+
+### GitHub Milestone (Epic-level)
+
+```
+Title: [FS-001] Core Framework Architecture
+Description:
+  Epic: Core Framework Architecture
+
+  Progress: 4/4 increments (100%)
+
+  Priority: P0
+  Status: complete
+
+State: Closed (if complete) or Open (if active/planning)
+```
+
+### GitHub Issues (Increment-level)
+
+```markdown
+Title: [INC-0001-core-framework] Core Framework
+
+# Core Framework
+
+Foundation framework with CLI, plugin system, and agent architecture...
+
+---
+
+**Increment**: 0001-core-framework
+**Milestone**: See milestone for Epic progress
+
+🤖 Auto-created by SpecWeave Epic Sync
+```
+
+**Labels**: `increment`, `epic-sync`
+**Milestone**: Linked to Epic Milestone
+
+## Frontmatter Updates
+
+### Epic README.md (after sync)
+
+```yaml
+---
+id: FS-001
+title: "Core Framework Architecture"
+external_tools:
+  github:
+    type: milestone
+    id: 10                              # ← Added
+    url: https://github.com/.../milestone/10  # ← Added
+increments:
+  - id: 0001-core-framework
+    external:
+      github: 130                       # ← Added
+  - id: 0002-core-enhancements
+    external:
+      github: 131                       # ← Added
+---
+```
+
+### Increment file (0001-core-framework.md)
+
+```yaml
+---
+id: 0001-core-framework
+epic: FS-001
+external:
+  github:
+    issue: 130                          # ← Added
+    url: https://github.com/.../issues/130  # ← Added
+---
+```
+
+## Benefits
+
+✅ **Hierarchical tracking**: GitHub Milestones group related increments
+✅ **Epic-level progress**: See completion percentage in Milestone
+✅ **Automatic linking**: All Issues linked to Milestone
+✅ **Idempotent**: Safe to re-run (updates existing Milestone/Issues)
+✅ **Brownfield-ready**: Links existing GitHub Milestones/Issues
+
+## Requirements
+
+1. **GitHub CLI** (`gh`) installed and authenticated
+2. **Git repository** with GitHub remote
+3. **Write access** to repository (for creating Milestones/Issues)
+4. **Epic folder exists** at `.specweave/docs/internal/specs/FS-XXX-name/`
+
+## Architecture: Why Milestones?
+
+**GitHub's Hierarchy**:
+- GitHub Milestones = Epic-level grouping
+- GitHub Issues = Increment-level work items
+- GitHub Projects = Optional (cross-Epic tracking)
+
+**Comparison with JIRA/ADO**:
+- JIRA: Epic → Epic, Increment → Story (with Epic Link field)
+- ADO: Epic → Feature, Increment → User Story (with Parent link)
+- GitHub: Epic → Milestone, Increment → Issue (with Milestone link)
+
+All three implement the same Universal Hierarchy, just with different terminology.
+
+## Troubleshooting
+
+**"Epic FS-001 not found"**:
+- Check Epic folder exists: `ls .specweave/docs/internal/specs/`
+- Verify Epic ID format: `FS-001-epic-name/`
+
+**"Epic README.md missing YAML frontmatter"**:
+- Ensure Epic was migrated with `migrate-to-epic-folders.ts`
+- Frontmatter must start with `---` on line 1
+
+**"Failed to create GitHub Milestone"**:
+- Check GitHub CLI auth: `gh auth status`
+- Verify write access: `gh repo view`
+- Check rate limits: `gh api rate_limit`
+
+**"Could not extract issue number"**:
+- GitHub CLI output format may have changed
+- Check CLI version: `gh --version` (need v2.0.0+)
+
+## Related Commands
+
+- `/specweave-github:sync-spec` - OLD (flat spec → project) - DEPRECATED for Epic architecture
+- `/specweave-jira:sync-epic` - Sync to JIRA Epic + Stories
+- `/specweave-ado:sync-epic` - Sync to ADO Feature + User Stories
+
+## Implementation
+
+**File**: `plugins/specweave-github/lib/github-epic-sync.ts`
+
+**Core Class**: `GitHubEpicSync`
+
+**Methods**:
+- `syncEpicToGitHub(epicId)` - Main sync logic
+- `createMilestone(epic)` - Create GitHub Milestone
+- `updateMilestone(number, epic)` - Update existing Milestone
+- `createIssue(increment, milestone)` - Create GitHub Issue
+- `updateIssue(number, increment, milestone)` - Update existing Issue
+- `updateEpicReadme(path, github)` - Update frontmatter
+- `updateIncrementExternalLink(...)` - Update increment frontmatter
+
+## Next Steps
+
+After syncing Epic to GitHub:
+
+1. **View Milestone progress**: `gh milestone view 10`
+2. **List Issues in Milestone**: `gh issue list --milestone 10`
+3. **Track completion**: GitHub automatically calculates Milestone progress
+4. **Close Milestone**: When all increments complete, Milestone auto-closes