specweave 1.0.584 → 1.0.586

package/plugins/specweave/skills/github-sync/SKILL.md

@@ -1,578 +1,40 @@
 ---
-description: "[DEPRECATED] Two-way synchronization between SpecWeave specs and GitHub Projects (push & pull by default). Use when asking about GitHub integration setup, troubleshooting sync issues, or configuring sync settings. For actual syncing, use sw-github:sync-spec command."
-version: 1.0.0
+description: "[DEPRECATED] GitHub sync guidance. Superseded by the live sw-github:* command family. For actual syncing use sw-github:push / sw-github:pull / sw-github:close / sw-github:sync."
+version: 1.0.1
 user-invokable: false
 deprecated: true
 ---
 
-> ⚠️ DEPRECATED: Use `sw-github:sync-spec` instead. This skill will be removed in v1.3.0.
+> ⚠️ DEPRECATED — superseded by the live `sw-github:*` command family.
 
-## Migration
+This skill's standalone guidance is retired. GitHub sync is performed by the
+increment-based command family, which is the source of truth:
 
-This skill has been deprecated as part of the Opus 4.7 framework alignment (increment 0669).
+| Action | Live command |
+|--------|--------------|
+| Push local progress to GitHub Issues | `sw-github:push [increment-id]` |
+| Pull issue state back into the spec | `sw-github:pull` |
+| Create the GitHub Issue/milestone | `sw-github:create` |
+| Close issues on increment completion | `sw-github:close` |
+| Two-way reconcile | `sw-github:sync` |
+| Check sync status | `sw-github:status` |
 
-- **Use instead**: `sw-github:sync-spec` for push/pull operations
-- **Removal**: Scheduled for v1.3.0 (2 minor releases after v1.1.0)
-- **Why**: Consolidated sync logic moved to the `sw-github:*` command family. This skill's guidance content is now covered by `sw-github:sync-spec` help text and `.specweave/docs/internal/specs/github-sync.md`.
+**Mapping** (per CLAUDE.md): Feature → Milestone · User Story → Issue · Task → Checkbox.
 
-For the migration policy, see `.specweave/docs/internal/specs/skill-deprecation-policy.md`.
+## Why this skill is deprecated
 
----
-
-# GitHub Sync - Two-way Spec ↔ Project Synchronization
-
-**Purpose**: Seamlessly synchronize SpecWeave specs with GitHub Projects for team visibility and project management.
-
-**Default Behavior**: **Two-way sync** (push & pull) - Changes in either system are automatically synchronized
-
-**⚠️ IMPORTANT**: This skill provides HELP and GUIDANCE about GitHub sync. For actual syncing, users should use the `sw-github:sync-spec` command directly. This skill should NOT auto-activate when the command is being invoked.
-
-## When to Activate
-
-✅ **Do activate when**:
-- User asks: "How do I set up GitHub sync?"
-- User asks: "What GitHub credentials do I need?"
-- User asks: "How does the GitHub integration work?"
-- User needs help configuring GitHub integration
-
-❌ **Do NOT activate when**:
-- User invokes `sw-github:sync-spec` command (command handles it)
-- Command is already running (avoid duplicate invocation)
-- Task completion hook is syncing (automatic process)
-
-**Integration**: Works with `sw-github:sync-spec` command
-
----
-
-## CORRECT Architecture
-
-**CRITICAL**: SpecWeave syncs **SPECS** to GitHub, NOT increments!
-
-```
-✅ CORRECT:
-.specweave/docs/internal/specs/spec-001.md  ↔  GitHub Project
-├─ User Story US-001                        ↔  GitHub Issue #1
-├─ User Story US-002                        ↔  GitHub Issue #2
-└─ User Story US-003                        ↔  GitHub Issue #3
-
-❌ WRONG (OLD, REMOVED!):
-.specweave/increments/0001-feature  ↔  GitHub Issue (DEPRECATED!)
-```
-
-**Why Specs, Not Increments?**
-- ✅ **Specs = Permanent** (living docs, feature-level knowledge base)
-- ❌ **Increments = Temporary** (implementation snapshots, can be deleted after done)
-- ✅ **GitHub should mirror PERMANENT work**, not temporary iterations
-
----
-
-## How GitHub Sync Works
-
-### 1. Spec → GitHub Project (Export)
-
-**Trigger**: When spec is created or updated
-
-**Actions**:
-1. Create GitHub Project with:
-   - Title: `[SPEC-001] Core Framework & Architecture`
-   - Description: Spec overview + progress
-   - Columns: Backlog, In Progress, Done
-   - Linked to repository
-
-2. Store project ID in spec metadata:
-   ```yaml
-   # .specweave/docs/internal/specs/spec-001.md (frontmatter)
-   ---
-   externalLinks:
-     github:
-       projectId: 123
-       projectUrl: https://github.com/users/anton-abyzov/projects/123
-       syncedAt: 2025-11-11T10:00:00Z
-   ---
-   ```
-
-3. Create GitHub Issues for each user story:
-   - Title: `[US-001] As a developer, I want to install SpecWeave via NPM`
-   - Body: Acceptance criteria as checkboxes
-   - Labels: `user-story`, `spec:spec-001`, `priority:P1`
-   - Linked to project
-
-**Example GitHub Project**:
-```markdown
-# [SPEC-001] Core Framework & Architecture
-
-**Status**: In Progress (75% complete)
-**Priority**: P0 (Critical)
-**Feature Area**: Foundation & Plugin System
-
-## Overview
-
-The core framework and architecture spec covers SpecWeave's foundational capabilities:
-- TypeScript-based CLI framework
-- Plugin system architecture
-- Cross-platform compatibility
-
-## Progress
-
-- ✅ US-001: NPM installation (Complete)
-- ✅ US-002: Plugin system (Complete)
-- ⏳ US-003: Context optimization (In Progress)
-- ⏳ US-004: Intelligent agents (In Progress)
-
-**Overall**: 2/4 user stories complete (50%)
-
----
-
-🤖 Auto-synced by SpecWeave GitHub Plugin
-```
-
-### 2. User Story Progress Updates (Spec → GitHub)
-
-**Trigger**: After each task completion (via post-task-completion hook)
-
-**Actions**:
-1. **Update GitHub Issue** (for user story):
-   - Updates acceptance criteria checkboxes
-   - Marks completed ACs with `[x]`
-   - Updates issue description
-   - Updates labels (`in-progress`, `testing`, `ready-for-review`)
-
-2. **Update GitHub Project**:
-   - Moves cards between columns (Backlog → In Progress → Done)
-   - Updates project progress percentage
-   - Posts progress comment
-
-**Example Issue Update**:
-```markdown
-**User Story**: US-001
-
-As a developer, I want to install SpecWeave via NPM so that I can use it in my projects
-
-## Acceptance Criteria
-
-- [x] AC-001-01: `npm install -g specweave` works
-- [x] AC-001-02: `specweave init` creates `.specweave/` structure
-- [ ] AC-001-03: Version command shows current version (In Progress)
-
----
-
-**Progress**: 2/3 ACs complete (67%)
-
-🤖 Auto-updated by SpecWeave (2025-11-11)
-```
-
-### 3. Spec Completion (Close Project)
-
-**Trigger**: All user stories in spec are complete
-
-**Actions**:
-1. Close all GitHub Issues (user stories)
-2. Archive GitHub Project
-3. Post final comment:
-   ```markdown
-   ✅ **Spec Completed**
-
-   **Final Stats**:
-   - 35 user stories completed (100%)
-   - 4 increments implemented (0001, 0002, 0004, 0005)
-   - Duration: 6 weeks
-
-   **Deliverables**:
-   - Core framework architecture
-   - Plugin system
-   - Cross-platform CLI
-
-   Spec complete. Project archived.
-
-   ---
-   🤖 Auto-closed by SpecWeave
-   ```
-
-### 4. GitHub Project → Spec (Import)
-
-**Use Case**: Import existing GitHub Projects as SpecWeave specs
-
-**Command**: `sw-github:import-project <project-number>`
-
-**Actions**:
-1. Fetch project via GitHub GraphQL API
-2. Create spec structure:
-   - Parse project title → spec title
-   - Parse project body → spec overview
-   - Map issues → user stories
-   - Map labels → priority
-
-3. Generate spec.md with user stories and acceptance criteria
-4. Link project to spec in metadata
-
----
-
-## Configuration
-
-Configure GitHub sync in `.specweave/config.json`:
-
-```json
-{
-  "sync": {
-    "enabled": true,
-    "preset": "bidirectional",
-    "activeProfile": "default",
-    "profiles": {
-      "default": {
-        "provider": "github",
-        "config": {
-          "owner": "myorg",
-          "repo": "myrepo",
-          "autoSyncSpecs": true,
-          "defaultLabels": ["specweave", "spec"]
-        }
-      }
-    }
-  }
-}
-```
-
-**Credentials** (in `.env`, gitignored):
-```bash
-GITHUB_TOKEN=ghp_xxxxx
-# Or just run: gh auth login (auto-detected)
-```
-
----
-
-## GitHub CLI Requirements
-
-This skill requires GitHub CLI (`gh`) to be installed and authenticated:
-
-```bash
-# Install GitHub CLI
-brew install gh              # macOS
-apt install gh               # Ubuntu/Debian
-choco install gh             # Windows
-
-# Authenticate
-gh auth login
-
-# Verify
-gh auth status
-```
-
----
-
-## Manual Sync Operations
-
-### Sync Spec to GitHub
-
-```bash
-sw-github:sync-spec spec-001
-```
-
-Creates or updates GitHub Project for spec-001.
-
-### Sync All Specs
-
-```bash
-sw-github:sync-spec --all
-```
-
-Syncs all specs to GitHub Projects.
-
-### Import Project
+- The increment-based `sw-github:*` commands are the supported path. Run them
+  directly; this skill no longer carries its own workflow guidance (it was
+  contradictory — it pointed at a `sw-github:sync-spec` command that does not
+  exist and claimed increment-based sync was "removed" when it is the live flow).
+- Setup and credentials are handled by `sw:sync-setup`. Configuration lives in
+  `.specweave/config.json` (`sync.*`); the GitHub token is read from
+  `GITHUB_TOKEN` / `GH_TOKEN` in `.env` (or `gh auth login`).
+- For the deprecation policy, see
+  `.specweave/docs/internal/specs/skill-deprecation-policy.md`.
 
-```bash
-sw-github:import-project 123
-```
-
-Imports GitHub Project #123 as a SpecWeave spec.
-
-### Check Status
-
-```bash
-sw-github:status spec-001
-```
-
-Shows sync status (project ID, last sync time, progress %).
-
----
-
-## Workflow Integration
-
-### Full Automated Workflow
-
-```bash
-# 1. Create spec (PM agent)
-User: "Create spec for user authentication"
-PM: Creates .specweave/docs/internal/specs/spec-005-user-auth.md
-
-# 2. Auto-sync to GitHub (hook)
-→ GitHub Project created automatically
-→ Issues created for each user story
-
-# 3. Implement increments
-sw:increment "Add login flow"
-→ Increment 0010 created (implements US-001, US-002)
-
-# 4. Work on tasks
-sw:do
-→ Task completed
-→ Hook fires
-→ Spec updated (AC marked complete)
-→ GitHub Project updated automatically
-
-# 5. Complete spec
-→ All user stories done
-→ GitHub Project archived automatically
-```
-
-### Team Collaboration
-
-**For Developers**:
-- Work in SpecWeave specs locally
-- Automatic GitHub Project updates keep team informed
-- No manual project management needed
-
-**For Project Managers**:
-- View all specs as GitHub Projects
-- Track progress in GitHub Projects UI
-- Comment on issues to communicate with developers
-
-**For Stakeholders**:
-- See progress in familiar GitHub interface
-- No need to understand SpecWeave structure
-- Clear visibility into feature development status
-
----
-
-## Conflict Resolution
-
-**What if project and spec diverge?**
-
-The spec is always the source of truth. GitHub Projects are a mirror for visibility.
-
-**Sync conflicts** (rare):
-1. Spec status conflicts with project state
-2. Manual edits to project/issue body/title
-
-**Resolution**:
-- Run `sw-github:sync-spec spec-001 --force` to overwrite project from spec
-- Or manually update spec metadata to match project
-
----
-
-## Privacy & Security
-
-**What gets synced?**
-- ✅ Spec title, overview, progress
-- ✅ User stories and acceptance criteria
-- ✅ User story completion status
-- ❌ Code diffs, file contents (never synced)
-- ❌ Internal notes, sensitive data
-
-**Security**:
-- Uses GitHub token from environment (GITHUB_TOKEN or GH_TOKEN)
-- Respects repository permissions (read/write)
-- No data sent to third parties
-
----
-
-## Benefits
-
-**For SpecWeave Users**:
-- ✅ No manual GitHub project management
-- ✅ Automatic team visibility
-- ✅ Single source of truth (spec docs)
-- ✅ GitHub integration without leaving IDE
-
-**For Teams**:
-- ✅ Track SpecWeave work in GitHub Projects
-- ✅ Use milestones, labels, assignees as usual
-- ✅ Comment on issues to communicate with developers
-- ✅ View progress in real-time
-
-**For Organizations**:
-- ✅ Unified project tracking across repos
-- ✅ GitHub-native workflow (familiar to all)
-- ✅ Audit trail (all syncs timestamped)
-- ✅ Integration with GitHub Actions, webhooks
-
----
-
-## Troubleshooting
-
-**Project not created?**
-- Check GitHub CLI: `gh auth status`
-- Verify repo permissions (write access)
-- Check config: `.specweave/config.json`
-
-**Sync failing?**
-- Check network connectivity
-- Verify project still exists (not deleted)
-- Check rate limits: `gh api rate_limit`
-
-**Progress not updating?**
-- Check `autoSyncSpecs: true` in config
-- Verify hook execution: `.specweave/logs/hooks-debug.log`
-- Manually sync: `sw-github:sync-spec spec-001`
-
----
-
-## Advanced Usage
-
-### Custom Project Templates
-
-Create `.specweave/github/project-template.md`:
-
-```markdown
-# [{{spec.id.toUpperCase()}}] {{spec.title}}
-
-{{spec.overview}}
-
-## SpecWeave Details
-
-- **Spec**: [spec.md]({{spec.url}})
-- **Priority**: {{spec.priority}}
-- **Feature Area**: {{spec.featureArea}}
-
-## User Stories
-
-{{spec.userStories.map(us => `- ${us.id}: ${us.title}`).join('\n')}}
-```
-
-### Selective Sync
-
-Sync only specific specs:
-
-```json
-{
-  "sync": {
-    "profiles": {
-      "default": {
-        "provider": "github",
-        "config": {
-          "owner": "myorg",
-          "repo": "myrepo",
-          "syncSpecs": [
-            "spec-001-core-framework",
-            "spec-005-user-authentication"
-          ]
-        }
-      }
-    }
-  }
-}
-```
-
-### Multi-Repo Sync
-
-For monorepos with multiple GitHub repositories, use multiple profiles:
-
-```json
-{
-  "sync": {
-    "profiles": {
-      "frontend": {
-        "provider": "github",
-        "config": {
-          "owner": "myorg",
-          "repo": "frontend",
-          "syncSpecs": ["spec-001-*", "spec-002-*"]
-        }
-      },
-      "backend": {
-        "provider": "github",
-        "config": {
-          "owner": "myorg",
-          "repo": "backend",
-          "syncSpecs": ["spec-003-*", "spec-004-*"]
-        }
-      }
-    }
-  }
-}
-```
-
----
-
-## Projects V2 Integration (v3.0.0+)
-
-### Enabling Projects V2
-
-Add `projectV2Enabled: true` to your sync config:
-
-```json
-{
-  "sync": {
-    "profiles": {
-      "myproject": {
-        "provider": "github",
-        "config": {
-          "owner": "myorg",
-          "repo": "myrepo",
-          "projectV2Enabled": true,
-          "projectV2Number": 5
-        }
-      }
-    }
-  }
-}
-```
-
-### What Happens with V2 Enabled
-
-1. **Push sync** creates/updates GitHub issues (same as before)
-2. **Issues are added to Projects V2 board** automatically
-3. **Status field** is set based on user story status (planned/in-progress/completed)
-4. **Priority field** is set based on user story priority (P1-P4)
-
-### Custom Field Mappings
-
-```json
-{
-  "statusFieldMapping": {
-    "planned": "Todo",
-    "in-progress": "In Progress",
-    "completed": "Done"
-  },
-  "priorityFieldMapping": {
-    "P1": "Urgent",
-    "P2": "High",
-    "P3": "Medium",
-    "P4": "Low"
-  }
-}
-```
-
-### Pull Sync (GitHub to Spec)
-
-Pull sync fetches issue state and compares with spec ACs:
-- AC checkbox toggles on GitHub are detected and applied to spec
-- Issue close/reopen is detected as status change
-- Conflicts are detected when both spec and GitHub changed the same field
-
-### Batch Sync
-
-Sync all specs at once:
-- Discovers all `spec-*.md` files in `.specweave/docs/internal/specs/`
-- Syncs each sequentially
-- Reports summary with created/updated/failed counts
-
-### Cross-Repo Sync
-
-For distributed strategies, issues can be created in different repos:
-- User stories specify target repos via `targetRepos` field
-- Cross-references added: "Also tracked in: org/other-repo#XX"
-- All cross-repo issues added to shared org-level Projects V2 board
-
----
-
-## Related
-
-- **github-issue-tracker**: DEPRECATED - use spec sync instead
-- **Commands**: `sw-github:sync-spec`, `sw-github:import-project`, `sw-github:status`
-- **Team Skills**: `sw:team-lead`, `sw:team-status`, `sw:team-merge`
-
----
+## Removal
 
-**Version**: 3.0.0 (Projects V2 + Pull Sync + Cross-Repo)
-**Plugin**: specweave-github
-**Last Updated**: 2026-02-06
+Scheduled for removal once the `sw-github:*` command help fully absorbs any
+remaining setup notes. Until then this stub exists only to avoid contradictory
+guidance; it is non-activating (`user-invokable: false`).

package/plugins/specweave/skills/github-sync/evals/evals.json

@@ -5,7 +5,7 @@
       "id": 1,
       "name": "initial-github-sync-setup",
       "prompt": "I just started using SpecWeave on my project at github.com/myorg/backend-api. I want to sync my specs to GitHub Projects so my team can track progress. How do I set up the GitHub integration? I need two-way sync.",
-      "expected_output": "Should guide through GitHub CLI authentication (gh auth login), explain the config.json setup for specweave-github plugin with repo, autoSyncSpecs, syncDirection settings, explain that specs (not increments) are synced to GitHub Projects, and mention the sw-github:sync-spec command for manual sync.",
+      "expected_output": "Should guide through GitHub CLI authentication (gh auth login), explain the config.json setup for the specweave-github plugin with repo and sync settings, and mention the live sw-github:push / sw-github:pull / sw-github:sync commands for manual sync.",
       "files": [],
       "assertions": [
         {
@@ -30,7 +30,7 @@
         },
         {
           "id": "sync-command",
-          "text": "References the sw-github:sync-spec command for triggering manual sync operations",
+          "text": "References a live sw-github:* command (sw-github:push, sw-github:pull, or sw-github:sync) for triggering manual sync operations",
           "type": "boolean"
         }
       ]
@@ -38,7 +38,7 @@
     {
       "id": 2,
       "name": "sync-troubleshooting-permissions",
-      "prompt": "My GitHub sync keeps failing with a 403 error when I run sw-github:sync-spec spec-003. I'm getting 'insufficient permissions' errors. I set up the token but something is wrong. How do I fix this?",
+      "prompt": "My GitHub sync keeps failing with a 403 error when I run sw-github:push for increment 0003. I'm getting 'insufficient permissions' errors. I set up the token but something is wrong. How do I fix this?",
       "expected_output": "Should diagnose GitHub permissions issues: check gh auth status, verify token scopes (needs repo and project access), check repository write access, suggest re-authenticating with correct scopes, and mention rate limit checking with gh api rate_limit.",
       "files": [],
       "assertions": [