specweave 0.12.0 → 0.12.2

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

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

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

package/plugins/specweave-github/lib/cli-sync-increment-changes.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+/**
+ * CLI wrapper for syncing increment changes to GitHub
+ *
+ * Usage:
+ *   node dist/plugins/specweave-github/lib/cli-sync-increment-changes.js <incrementId> <changedFile>
+ *
+ * Example:
+ *   node dist/plugins/specweave-github/lib/cli-sync-increment-changes.js 0015-hierarchical-sync spec.md
+ */
+
+import { syncIncrementChanges } from './github-sync-increment-changes.js';
+
+const incrementId = process.argv[2];
+const changedFile = process.argv[3] as 'spec.md' | 'plan.md' | 'tasks.md';
+
+if (!incrementId || !changedFile) {
+  console.error('❌ Usage: cli-sync-increment-changes <incrementId> <changedFile>');
+  console.error('   Example: cli-sync-increment-changes 0015-hierarchical-sync spec.md');
+  process.exit(1);
+}
+
+if (!['spec.md', 'plan.md', 'tasks.md'].includes(changedFile)) {
+  console.error(`❌ Invalid file: ${changedFile}`);
+  console.error('   Must be one of: spec.md, plan.md, tasks.md');
+  process.exit(1);
+}
+
+syncIncrementChanges(incrementId, changedFile).catch((error) => {
+  console.error('❌ Fatal error:', error);
+  // Don't exit with error code - best-effort sync
+});