specweave 0.18.1 → 0.20.1

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

@@ -1,147 +0,0 @@
----
-name: specweave-github:sync-from
-description: Sync state from GitHub to SpecWeave (bidirectional sync). Fetches issue state, comments, and detects conflicts.
----
-
-# Sync from GitHub to SpecWeave
-
-Bidirectional sync - pull changes from GitHub issue back to SpecWeave increment.
-
-## Usage
-
-```bash
-/specweave-github:sync-from <incrementId>
-```
-
-## What It Does
-
-1. **Fetches GitHub Issue State**:
-   - Issue status (open/closed)
-   - Comments
-   - Labels, assignees, milestones
-   - Last updated timestamp
-
-2. **Detects Conflicts**:
-   - GitHub closed but SpecWeave active
-   - SpecWeave completed but GitHub open
-   - GitHub abandoned but issue open
-
-3. **Syncs Comments**:
-   - Saves GitHub comments to `.specweave/increments/<id>/logs/github-comments.md`
-   - Only syncs new comments (tracks IDs)
-
-4. **Updates Metadata**:
-   - Updates `metadata.json` with latest GitHub state
-   - Tracks last sync timestamp
-
-## Examples
-
-### Basic Sync
-
-```bash
-/specweave-github:sync-from 0015-hierarchical-sync
-```
-
-**Output**:
-```
-🔄 Syncing from GitHub for increment: 0015-hierarchical-sync
-   Syncing from anton-abyzov/specweave#29
-✅ No conflicts - GitHub and SpecWeave in sync
-📝 Syncing 3 new comment(s)
-✅ Comments saved to: logs/github-comments.md
-✅ Metadata updated
-✅ Bidirectional sync complete
-```
-
-### Conflict Detection
-
-```bash
-/specweave-github:sync-from 0015-hierarchical-sync
-```
-
-**Output**:
-```
-🔄 Syncing from GitHub for increment: 0015-hierarchical-sync
-   Syncing from anton-abyzov/specweave#29
-⚠️  Detected 1 conflict(s)
-
-⚠️  Conflict detected: status
-   GitHub: closed
-   SpecWeave: active
-
-⚠️  **CONFLICT**: GitHub issue closed but SpecWeave increment still active!
-   Recommendation: Run /specweave:done 0015-hierarchical-sync to close increment
-   Or reopen issue on GitHub if work is not complete
-
-✅ Bidirectional sync complete
-```
-
-## When to Use
-
-Use this command when:
-- ✅ Someone closed/reopened the GitHub issue
-- ✅ Comments were added on GitHub (want to import them)
-- ✅ Want to check if GitHub and SpecWeave are in sync
-- ✅ Resolving conflicts between GitHub and SpecWeave state
-
-## Requirements
-
-- GitHub CLI (`gh`) installed and authenticated
-- GitHub issue linked in metadata.json
-- Repository has GitHub remote configured
-
-## Conflict Resolution
-
-### GitHub Closed, SpecWeave Active
-
-**Resolution**: Close SpecWeave increment
-```bash
-/specweave:done 0015-hierarchical-sync
-```
-
-**Or**: Reopen GitHub issue if work not complete
-```bash
-gh issue reopen 29
-```
-
-### SpecWeave Completed, GitHub Open
-
-**Resolution**: Close GitHub issue
-```bash
-gh issue close 29 --comment "Increment completed in SpecWeave"
-```
-
-### SpecWeave Abandoned, GitHub Open
-
-**Resolution**: Close GitHub issue with reason
-```bash
-gh issue close 29 --comment "Increment abandoned: Requirements changed"
-```
-
-## Files Modified
-
-- `.specweave/increments/<id>/logs/github-comments.md` - GitHub comments
-- `.specweave/increments/<id>/metadata.json` - Sync metadata
-
-## Related Commands
-
-- `/specweave-github:sync` - One-way sync (SpecWeave → GitHub)
-- `/specweave-github:create-issue` - Create GitHub issue
-- `/specweave-github:close-issue` - Close GitHub issue
-- `/specweave-github:status` - Check sync status
-
-## Automation
-
-For automatic bidirectional sync, add to cron or CI/CD:
-
-```bash
-# Sync all active increments hourly
-0 * * * * cd /path/to/project && \
-  for inc in $(ls .specweave/increments/ | grep -v _backlog); do \
-    /specweave-github:sync-from $inc; \
-  done
-```
-
-## Implementation
-
-Invokes `github-sync-bidirectional` agent with conflict detection and resolution logic.

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

@@ -1,208 +0,0 @@
----
-name: specweave-github-sync-spec
-description: Sync SpecWeave spec to GitHub Project (bidirectional). Use when syncing .specweave/docs/internal/specs/spec-*.md files with GitHub Projects for permanent feature tracking.
----
-
-# Sync Spec to GitHub Project
-
-**CORRECT ARCHITECTURE**: This command syncs `.specweave/docs/internal/specs/spec-*.md` files (PERMANENT living docs) to GitHub Projects, NOT increments to issues.
-
-## Usage
-
-```bash
-/specweave-github:sync-spec <spec-id> [--direction <to-github|from-github|bidirectional>]
-```
-
-## What It Does
-
-**Architecture**:
-- **Spec → GitHub Project** (not increment → issue!)
-- **User Story → GitHub Issue** (linked to project)
-- **Acceptance Criteria → Checklist** (in issue body)
-
-**Sync Process**:
-
-1. **Load spec** from `.specweave/docs/internal/specs/spec-{id}.md`
-2. **Detect repository** from git remote
-3. **Create or update GitHub Project**:
-   - Title: `[SPEC-001] Feature Title`
-   - Description: Spec overview + progress
-   - Status: Matches spec status
-4. **Sync user stories as issues**:
-   - Create issues for new user stories
-   - Update existing issues
-   - Close issues for completed user stories
-5. **Link spec to project** (update frontmatter)
-
-## Examples
-
-### Sync spec to GitHub (create or update)
-
-```bash
-/specweave-github:sync-spec spec-001
-```
-
-**Output**:
-```
-🔄 Syncing spec spec-001 to GitHub Project...
-   Creating new GitHub Project...
-   ✅ Created GitHub Project #5: https://github.com/owner/repo/projects/5
-   Syncing 35 user stories...
-   ✅ Created US-001 → Issue #130
-   ✅ Created US-002 → Issue #131
-   ...
-✅ Sync complete!
-   Created: 35 user stories
-   GitHub Project: https://github.com/owner/repo/projects/5
-```
-
-### Sync FROM GitHub to spec (bidirectional)
-
-```bash
-/specweave-github:sync-spec spec-001 --direction from-github
-```
-
-**Output**:
-```
-🔄 Syncing FROM GitHub to spec spec-001...
-   Fetching GitHub Project #5...
-   ⚠️  Detected 3 conflict(s)
-   🔄 Resolving: US-002 marked done in GitHub (GitHub wins)
-   🔄 Resolving: US-005 marked in-progress in GitHub (GitHub wins)
-✅ Sync FROM GitHub complete!
-   Updated: 3 user stories
-```
-
-### Bidirectional sync (default)
-
-```bash
-/specweave-github:sync-spec spec-001 --direction bidirectional
-```
-
-## Arguments
-
-- `<spec-id>` - Spec ID (e.g., `spec-001` or just `001`)
-- `--direction <mode>` - Sync direction (default: `to-github`)
-  - `to-github` - Push local spec to GitHub
-  - `from-github` - Pull GitHub state to spec
-  - `bidirectional` - Sync both ways (conflict resolution)
-
-## Conflict Resolution
-
-When syncing FROM GitHub, conflicts are resolved as follows:
-
-**GitHub wins** (default):
-- User story status changes → update spec
-- Acceptance criteria status → update spec
-- Issue closure → mark user story done
-
-**Local wins** (future):
-- Spec changes take precedence
-- Push to GitHub
-
-## Requirements
-
-1. **GitHub CLI** (`gh`) installed and authenticated
-2. **Git repository** with GitHub remote
-3. **Write access** to repository (for creating projects/issues)
-4. **Spec file exists** at `.specweave/docs/internal/specs/spec-{id}.md`
-
-## What Gets Synced
-
-### Spec → GitHub Project
-
-- ✅ Title: `[SPEC-001] Feature Area Title`
-- ✅ Description: Overview + progress stats
-- ✅ Status: Open/Closed based on spec completion
-
-### User Story → GitHub Issue
-
-- ✅ Title: `[US-001] As a user, I want...`
-- ✅ Body: User story + acceptance criteria checklist
-- ✅ Labels: `user-story`, `spec:spec-001`, `priority:P1`
-- ✅ State: Open (todo/in-progress) or Closed (done)
-
-### Acceptance Criteria → Checklist
-
-```markdown
-## Acceptance Criteria
-
-- [x] User can log in with email/password
-- [ ] Invalid credentials show error message
-- [ ] Account locks after 5 failed attempts
-```
-
-## Architecture
-
-**Why This Architecture?**
-
-✅ **Permanent tracking**: Specs never deleted, GitHub links remain valid
-✅ **Feature-level granularity**: One GitHub Project per feature (not per increment)
-✅ **PM-friendly**: Stakeholders see progress in GitHub Projects
-✅ **Brownfield-ready**: Existing GitHub Projects map to specs
-
-**What's WRONG?**
-
-❌ Increment → GitHub Issue (increments are temporary!)
-❌ Tasks → GitHub Issues (too granular, implementation details)
-❌ Multiple issues per feature (split across increments)
-
-## Metadata
-
-After sync, spec frontmatter is updated:
-
-```yaml
----
-id: spec-001
-title: Core Framework Architecture
-status: in-progress
-priority: P0
-externalLinks:
-  github:
-    projectId: 5
-    projectUrl: https://github.com/owner/repo/projects/5
-    syncedAt: "2025-11-10T12:00:00Z"
-    owner: owner
-    repo: repo
----
-```
-
-## Troubleshooting
-
-**"Could not detect GitHub repository"**:
-- Ensure you're in a git repo with GitHub remote
-- Run: `git remote -v` to check
-
-**"Spec not found"**:
-- Check spec exists: `ls .specweave/docs/internal/specs/`
-- Use correct ID: `spec-001` or `001`
-
-**"GraphQL query failed"**:
-- Check GitHub CLI auth: `gh auth status`
-- Re-authenticate: `gh auth login`
-
-**"No user stories to sync"**:
-- Add user stories to spec.md:
-  ```markdown
-  **US-001**: As a user, I want...
-  - [ ] **AC-001-01**: Acceptance criteria 1
-  ```
-
-## Related
-
-- `/specweave-github:sync` - OLD command (increment-based, DEPRECATED)
-- `/specweave-jira:sync-spec` - Sync to Jira Epic
-- `/specweave-ado:sync-spec` - Sync to Azure DevOps Feature
-- `/specweave:sync-docs` - Sync living docs from increments to specs
-
-## Implementation
-
-**File**: `plugins/specweave-github/lib/github-spec-sync.ts`
-
-**Core Class**: `GitHubSpecSync`
-
-**Methods**:
-- `syncSpecToGitHub(specId)` - Push to GitHub
-- `syncFromGitHub(specId)` - Pull from GitHub
-- `detectConflicts(spec, project)` - Compare states
-- `resolveConflicts(spec, conflicts)` - Apply resolution strategy