specweave 1.0.506 → 1.0.508

package/plugins/specweave-github/PLUGIN.md

@@ -1,29 +0,0 @@
-# GitHub Plugin
-
-**Version**: 1.0.0
-**Author**: SpecWeave Contributors
-**License**: MIT
-
-## Description
-
-GitHub integration plugin for issue standardization, task tracking, multi-repository coordination, and bidirectional synchronization with GitHub Projects. Enables consistent issue formatting, fine-grained progress visibility, and cross-repository organization.
-
-## Skills
-
-| Skill | Description |
-|-------|-------------|
-| github-issue-standard | Mandatory format standard for GitHub issues with checkable acceptance criteria and consistent metadata |
-| github-issue-tracker | Task-level progress tracking via comments, checklists, and labels for fine-grained visibility |
-| github-multi-project | Expert organization for monorepo, polyrepo, and parent repo architectures across multiple repositories |
-| github-sync | Two-way synchronization between SpecWeave specs and GitHub Projects with push and pull capability |
-
-## Installation
-
-```bash
-vskill add specweave --plugin sw-github
-```
-
-## Requirements
-
-- SpecWeave core plugin (sw@specweave)
-- GitHub authentication configured

package/plugins/specweave-github/SYNC-ARCHITECTURE-FIX-SUMMARY.md

@@ -1,302 +0,0 @@
-# GitHub Sync Architecture Fix - Complete Summary
-
-**Date**: 2025-11-11
-**Impact**: Breaking Change (v0.17.0+)
-**Status**: Complete
-
----
-
-## The Problem
-
-**SpecWeave was syncing the WRONG things to GitHub!**
-
-### ❌ OLD Architecture (WRONG!)
-
-```
-.specweave/increments/0001-feature  ↔  GitHub Issue
-├─ Tasks (T-001, T-002, T-003)       ↔  GitHub Checkboxes
-└─ metadata.json.github.issue        ↔  Issue #42
-```
-
-**Why this was wrong**:
-- ✅ Increments are **TEMPORARY** (implementation snapshots, can be deleted after done)
-- ❌ GitHub Issues are **PERMANENT** (long-term tracking)
-- ❌ Syncing temporary → permanent breaks traceability
-
-**The screenshot that exposed this**:
-```
-GitHub Issue: "Increment 0001: Daily Habit Tracker MVP - Frontend"
-```
-
-**User feedback**:
-> "syncing with increments is old approach, outdated it MUST be removed!! don't worry about backward compatibility, just remove it!!!"
-
----
-
-## The Solution
-
-### ✅ NEW Architecture (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
-
-Increments (NOT synced to GitHub):
-├─ 0001-core-framework (implements US-001, US-002)
-├─ 0002-core-enhancements (implements US-003, US-004)
-└─ 0004-plugin-architecture (implements US-005, US-006)
-```
-
-**Why this is correct**:
-- ✅ **Specs = Permanent** (living docs, feature-level knowledge base)
-- ✅ **User Stories = Permanent** (long-term requirements)
-- ✅ **GitHub Projects = Permanent** (feature tracking)
-- ✅ **Increments = Temporary** (NOT synced to GitHub!)
-
----
-
-## What Was Changed
-
-### 1. Hook Rewritten (`post-task-completion.sh`)
-
-**Before** (241 lines, synced increments):
-```bash
-# Detect current increment
-CURRENT_INCREMENT=$(ls -t .specweave/increments/...)
-
-# Read metadata.json from increment
-METADATA_FILE=".specweave/increments/$CURRENT_INCREMENT/metadata.json"
-GITHUB_ISSUE=$(jq -r '.github.issue' "$METADATA_FILE")
-
-# Update GitHub issue checkboxes
-gh issue edit "$GITHUB_ISSUE" ...
-```
-
-**After** (162 lines, syncs specs):
-```bash
-# Detect current increment (temporary context)
-CURRENT_INCREMENT=$(ls -t .specweave/increments/...)
-
-# Find which spec this increment implements
-SPEC_REF=$(grep -E "^(Implements|See).*SPEC-[0-9]+" "$SPEC_FILE")
-SPEC_ID=$(echo "$SPEC_REF" | grep -oE "SPEC-[0-9]+" | tr 'A-Z' 'a-z')
-
-# Sync spec to GitHub Project (via github-spec-sync.ts)
-node "$SYNC_CLI" --spec-id "$SPEC_ID"
-```
-
-**Key Changes**:
-- ❌ Removed: ALL increment → GitHub issue sync code (79 lines deleted)
-- ✅ Added: Spec detection logic (find spec from increment reference)
-- ✅ Added: Call to `github-spec-sync.ts` CLI (already correct!)
-- ✅ Result: Hook now syncs specs (permanent), not increments (temporary)
-
-### 2. Skill Documentation Rewritten (`github-sync/SKILL.md`)
-
-**Before** (479 lines, described increment sync):
-```markdown
-## How GitHub Sync Works
-
-### 1. Increment → GitHub Issue (Export)
-
-**Trigger**: After `/sw:inc` creates a new increment
-
-**Actions**:
-1. Create GitHub issue with:
-   - Title: `[Increment ${ID}] ${Title}`
-   - Body: Executive summary from spec.md
-   ...
-```
-
-**After** (472 lines, describes spec sync):
-```markdown
-## CORRECT Architecture (v0.17.0+)
-
-**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
-
-❌ 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)
-```
-
-**Key Changes**:
-- ❌ Removed: ALL references to increment → GitHub issue sync
-- ✅ Added: Clear explanation of WHY specs, not increments
-- ✅ Added: Visual architecture diagram (correct vs wrong)
-- ✅ Updated: All examples to use specs instead of increments
-- ✅ Updated: Commands to `/sw-github:sync-spec` (not `/sync`)
-
-### 3. Commands (DEPRECATED, need rewrite)
-
-**These commands are WRONG and need to be deprecated**:
-
-| Command | What It Does (WRONG!) | What It Should Do |
-|---------|----------------------|-------------------|
-| `/sw-github:sync` | Syncs increment to GitHub issue | **DEPRECATED!** Should be removed |
-| `/sw-github:sync-tasks` | Syncs tasks to GitHub issues | **DEPRECATED!** Should sync user stories instead |
-
-**Correct commands** (need to be created):
-
-| Command | What It Does (CORRECT!) | Status |
-|---------|------------------------|--------|
-| `/sw-github:sync-spec <spec-id>` | Syncs spec to GitHub Project | ✅ Already exists (github-spec-sync.ts) |
-| `/sw-github:sync-spec --all` | Syncs all specs to GitHub | ✅ Already exists |
-| `/sw-github:import-project <id>` | Imports GitHub Project as spec | 🔜 TODO |
-
----
-
-## What Needs to Be Done Next
-
-### 1. Deprecate Old Commands
-
-**File**: `plugins/specweave-github/commands/specweave-github-sync.md`
-**Action**: Add deprecation notice, point to `/sw-github:sync-spec`
-
-**File**: `plugins/specweave-github/commands/specweave-github-sync-tasks.md`
-**Action**: Add deprecation notice, point to spec-based sync
-
-### 2. Create New Command
-
-**File**: `plugins/specweave-github/commands/specweave-github-sync-spec.md`
-**Action**: Document the CORRECT command (already implemented in `github-spec-sync.ts`)
-
-### 3. Update References
-
-**Files to check**:
-- `plugins/specweave-github/skills/github-issue-tracker/SKILL.md` (deprecate or update)
-- `plugins/specweave-github/hooks/README.md` (update to reflect spec sync)
-- `plugins/specweave-github/reference/github-specweave-mapping.md` (update mapping)
-- `.claude-plugin/plugin.json` (update description)
-
-### 4. Remove Old Code
-
-**Files to delete or refactor**:
-- `lib/github-sync-bidirectional.ts` (increment-based sync, deprecated)
-- `lib/task-sync.ts` (task-level sync, deprecated)
-- `lib/task-parser.ts` (parses tasks from increments, deprecated)
-
-**Keep**:
-- `lib/github-spec-sync.ts` (✅ CORRECT! Already implements spec → GitHub Project sync)
-
----
-
-## Testing Checklist
-
-### ✅ Completed
-- [x] Hook no longer references `.specweave/increments/{id}/metadata.json`
-- [x] Hook detects spec from increment reference
-- [x] Hook calls `github-spec-sync.ts` CLI
-- [x] Skill documentation updated to reflect spec sync
-
-### 🔜 TODO
-- [ ] Deprecate `/sw-github:sync` command
-- [ ] Deprecate `/sw-github:sync-tasks` command
-- [ ] Create `/sw-github:sync-spec` command documentation
-- [ ] Update all references in docs and code
-- [ ] Remove old increment-based sync libraries
-- [ ] Test end-to-end spec → GitHub Project sync
-- [ ] Verify user stories sync to GitHub Issues
-- [ ] Verify acceptance criteria show as checkboxes
-
----
-
-## Migration Guide (For Users)
-
-### Before (WRONG!)
-
-```bash
-# Create increment
-/sw:increment "Add authentication"
-
-# Sync increment to GitHub issue (❌ WRONG!)
-/sw-github:sync 0005
-/sw-github:sync-tasks 0005
-
-# Result: GitHub Issue for increment (temporary!)
-```
-
-### After (CORRECT!)
-
-```bash
-# Create spec (PM agent)
-User: "Create spec for user authentication"
-PM: Creates .specweave/docs/internal/specs/spec-005-user-auth.md
-
-# Sync spec to GitHub Project (✅ CORRECT!)
-/sw-github:sync-spec spec-005
-
-# Create increments (implements parts of spec)
-/sw:increment "Add login flow"
-→ Increment 0010 (implements US-001, US-002 from spec-005)
-
-/sw:increment "Add 2FA"
-→ Increment 0011 (implements US-003 from spec-005)
-
-# Result: GitHub Project for spec (permanent!)
-```
-
----
-
-## Benefits of New Architecture
-
-### Before (Increment-Based)
-- ❌ Temporary GitHub Issues (deleted after increment done)
-- ❌ No long-term traceability (issues disappear)
-- ❌ Team loses historical context
-- ❌ Multiple increments = multiple issues for same feature
-
-### After (Spec-Based)
-- ✅ Permanent GitHub Projects (never deleted)
-- ✅ Complete traceability (feature history preserved)
-- ✅ Team has full context (all user stories in one place)
-- ✅ One Project per feature (regardless of # increments)
-
----
-
-## Related Documentation
-
-- [github-spec-sync.ts](lib/github-spec-sync.ts) - Implementation of spec → GitHub Project sync
-- [github-sync/SKILL.md](skills/github-sync/SKILL.md) - Updated skill documentation
-- [post-task-completion.sh](hooks/post-task-completion.sh) - Updated hook
-- [Specs Architecture (CLAUDE.md)](../../CLAUDE.md#specs-architecture-two-locations-explained) - Why specs vs increments
-
----
-
-## Summary
-
-**What was fixed**:
-- ✅ Hook now syncs specs (permanent) instead of increments (temporary)
-- ✅ Documentation updated to reflect correct architecture
-- ✅ Clear explanation of WHY specs, not increments
-- ✅ Deprecated old commands (need formal deprecation notices)
-
-**What was removed**:
-- ❌ ALL increment → GitHub issue sync code (79 lines deleted from hook)
-- ❌ ALL references to increment-based sync in documentation
-
-**What needs to be done**:
-- 🔜 Formally deprecate old commands
-- 🔜 Create command documentation for `/sw-github:sync-spec`
-- 🔜 Remove old increment-based sync libraries
-- 🔜 Test end-to-end workflow
-
-**Impact**:
-- Breaking change (v0.17.0+)
-- Users must migrate from increment-based to spec-based sync
-- Old increments with GitHub issues will continue to work (read-only)
-- New work will only sync specs to GitHub Projects
-
----
-
-**Version**: v0.17.0+
-**Last Updated**: 2025-11-11
-**Status**: Architecture Fixed, Documentation Updated, Testing Pending

package/plugins/specweave-github/hooks/README.md

@@ -1,289 +0,0 @@
-# SpecWeave GitHub Plugin Hooks
-
-**Plugin**: `specweave-github`
-**Location**: `plugins/specweave-github/hooks/`
-
----
-
-## Purpose
-
-This hook provides GitHub Issues sync functionality for SpecWeave increments.
-
-**Key Features**:
-- ✅ Updates GitHub issue checkboxes based on `tasks.md` completion status
-- ✅ Posts progress comments with percentage completion
-- ✅ Bidirectional sync (local → GitHub)
-- ✅ Non-blocking (failures don't stop core workflow)
-- ✅ Self-contained (no dependencies on core plugin)
-
-**IMPORTANT CHANGE (v0.26.0)**: This hook is NO LONGER automatically triggered on task completion. GitHub sync should be done manually or on increment completion to avoid excessive API calls and performance overhead.
-
----
-
-## Available Hooks
-
-### 1. `post-task-completion.sh`
-
-**Triggers**: Manual invocation or increment completion (NOT on task completion)
-
-**Preconditions**:
-- ✅ Active increment exists (`.specweave/increments/####/`)
-- ✅ `metadata.json` has `.github.issue` field
-- ✅ GitHub CLI (`gh`) installed and authenticated
-- ✅ `tasks.md` file exists in increment
-
-**Actions**:
-1. Reads completed tasks from `tasks.md`
-2. Fetches GitHub issue body
-3. Updates checkboxes for completed tasks
-4. Posts progress comment with percentage
-5. Logs all actions to `.specweave/logs/hooks-debug.log`
-
-**Example Flow**:
-```
-Task T-003 completed in tasks.md
-↓
-Hook fires (PostToolUse + TodoWrite matcher)
-↓
-GitHub issue #42 checkboxes updated: [ ] T-003 → [x] T-003
-↓
-Progress comment posted: "Progress Update: 3/5 tasks (60%)"
-↓
-Log: "[GitHub] ✅ GitHub sync complete"
-```
-
-**Dependencies**:
-- `gh` CLI (GitHub CLI)
-- `jq` for JSON parsing
-- Bash 4.0+
-
----
-
-## Configuration
-
-### Hook Registration
-
-**DEPRECATED (v0.26.0)**: This hook is NO LONGER automatically registered on TodoWrite events.
-
-**Previous behavior (v0.24.0 and earlier)**:
-- Hook automatically fired on EVERY task completion
-- Caused excessive GitHub API calls
-- Created performance overhead and duplicate executions
-
-**New behavior (v0.26.0+)**:
-- Hook must be invoked manually via `/sw-github:sync`
-- OR triggered on increment completion (not task completion)
-- Reduces API calls by 90%+
-- Eliminates duplicate hook executions
-
-### Usage
-
-**Manual Sync** (recommended workflow):
-```bash
-# After completing several tasks, sync progress to GitHub
-/sw-github:sync
-
-# Or sync specific feature
-/sw-github:sync FS-048
-```
-
-**Automatic Sync Options**:
-1. **On Increment Completion**: Add hook to specweave plugin's post-increment-completion
-2. **Periodic Sync**: Set up cron job or CI/CD trigger
-3. **On Demand**: Call `/sw-github:sync` when needed
-
-### Metadata Format
-
-Increments must have `metadata.json` with GitHub issue link:
-
-```json
-{
-  "github": {
-    "issue": 42,
-    "url": "https://github.com/owner/repo/issues/42",
-    "repo": "owner/repo"
-  }
-}
-```
-
----
-
-## Installation
-
-### Automatic (Recommended)
-
-When `specweave init` runs, all plugin hooks are automatically installed:
-
-```bash
-npx specweave init my-project
-# Installs all plugins including specweave-github
-# Hooks auto-register via hooks.json
-```
-
-### Manual (Development)
-
-For testing or development:
-
-```bash
-# Install plugin
-/plugin install sw-github@specweave
-
-# Verify hook registration
-cat ~/.claude/settings.json
-# Should show sw-github hooks registered
-```
-
----
-
-## Testing
-
-### Test Hook Independently
-
-```bash
-# Test syntax
-bash -n plugins/specweave-github/hooks/post-task-completion.sh
-
-# Test execution (requires active increment + GitHub issue)
-./plugins/specweave-github/hooks/post-task-completion.sh
-```
-
-### Test with GitHub Issue
-
-1. Create increment: `/sw:increment "test feature"`
-2. Create GitHub issue: `/sw-github:create-issue 0001`
-3. Complete several tasks via TodoWrite
-4. **Manually trigger sync**: `/sw-github:sync`
-5. Check GitHub issue for updates
-
----
-
-## Logging
-
-All GitHub sync actions are logged to:
-
-```
-.specweave/logs/hooks-debug.log
-```
-
-**Example Log Output**:
-```
-[2025-11-10] [GitHub] 🔗 GitHub sync hook fired
-[2025-11-10] [GitHub] 🔄 Syncing to GitHub issue #42
-[2025-11-10] [GitHub] 📊 Syncing task checkboxes to GitHub issue #42
-[2025-11-10] [GitHub] Completed tasks found: T-001 T-002 T-003
-[2025-11-10] [GitHub] Updated checkbox for task: T-001
-[2025-11-10] [GitHub] Updated checkbox for task: T-002
-[2025-11-10] [GitHub] Updated checkbox for task: T-003
-[2025-11-10] [GitHub] ✅ Issue description checkboxes updated
-[2025-11-10] [GitHub] ✅ Progress comment posted (60%)
-[2025-11-10] [GitHub] ✅ GitHub sync complete
-```
-
-**Log Prefixes**:
-- `[GitHub]` - All messages from this hook
-- `🔗` - Hook fired
-- `🔄` - Syncing started
-- `📊` - Syncing task data
-- `✅` - Success
-- `⚠️` - Warning (non-blocking failure)
-- `ℹ️` - Info (skipped due to precondition)
-
----
-
-## Architecture
-
-### How It Works with Core Plugin
-
-**Before (v0.12.x)**:
-```
-Core hook (500+ lines)
-├── Sound notifications
-├── Living docs sync
-├── Translation
-├── GitHub sync        ← Embedded in core!
-├── JIRA sync          ← Embedded in core!
-└── ADO sync           ← Embedded in core!
-```
-
-**After (v0.13.0+)**:
-```
-Core hook (330 lines)         GitHub plugin hook (241 lines)
-├── Sound notifications       ├── Check for GitHub issue
-├── Living docs sync          ├── Update checkboxes
-├── Translation               ├── Post progress comment
-└── Self-reflection           └── Log actions
-```
-
-**Key Benefits**:
-- ✅ **Separation of concerns**: Core plugin has NO external tool dependencies
-- ✅ **Optional plugin**: GitHub sync only runs if `specweave-github` installed
-- ✅ **Independent testing**: Test GitHub sync in isolation
-- ✅ **Cleaner code**: Each hook <250 lines, single responsibility
-- ✅ **Parallel execution**: Claude Code runs all hooks concurrently
-
----
-
-## Troubleshooting
-
-### Hook Not Firing
-
-**Check**:
-1. Plugin installed: `/plugin list --installed | grep specweave-github`
-2. Hook registered: `cat ~/.claude/settings.json | grep specweave-github`
-3. Active increment: `cat .specweave/logs/current-increment`
-4. GitHub issue linked: `cat .specweave/increments/####/metadata.json | jq .github`
-
-### GitHub CLI Not Found
-
-**Fix**:
-```bash
-# macOS
-brew install gh
-
-# Linux
-curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
-echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
-sudo apt update
-sudo apt install gh
-
-# Authenticate
-gh auth login
-```
-
-### Sync Failures
-
-**Check logs**:
-```bash
-tail -f .specweave/logs/hooks-debug.log | grep '\[GitHub\]'
-```
-
-**Common issues**:
-- ❌ No `metadata.json`: Create GitHub issue via `/sw-github:create-issue`
-- ❌ Not authenticated: Run `gh auth login`
-- ❌ Invalid issue number: Check `metadata.json` has correct issue ID
-- ❌ Network error: Check internet connection
-
----
-
-## Migration from v0.12.x
-
-If upgrading from SpecWeave v0.12.x or earlier:
-
-1. **Automatic**: Run `specweave init` (re-installs all hooks)
-2. **Manual**: Copy `plugins/specweave-github/hooks/` to `.claude/hooks/` (not recommended)
-
-**No action needed**: Existing increments with GitHub issues will continue to sync automatically.
-
----
-
-## Related Documentation
-
-- **Core Plugin Hooks**: `plugins/specweave/hooks/README.md`
-- **Architecture Analysis**: `.specweave/increments/0018-strict-increment-discipline-enforcement/reports/HOOKS-ARCHITECTURE-ANALYSIS.md`
-- **Claude Code Hooks Guide**: https://code.claude.com/docs/en/hooks-guide
-- **GitHub Sync Command**: `plugins/specweave-github/commands/sync.md`
-
----
-
-**Version**: v0.13.0+
-**Last Updated**: 2025-11-10