npm - specweave - Versions diffs - 1.0.506 → 1.0.508 - Mend

specweave 1.0.506 → 1.0.508

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1038) hide show

package/plugins/specweave-github/MULTI-PROJECT-SYNC-ARCHITECTURE.md DELETED Viewed

@@ -1,744 +0,0 @@
-# Multi-Project GitHub Sync Architecture
-**Version**: v1.0.235+ (V2 Integration)
-**Date**: 2026-02-06
-**Status**: Implemented and Tested
----
-## Executive Summary
-SpecWeave's GitHub sync has been enhanced to support enterprise-scale multi-project/multi-team architectures. The system now automatically detects which project a spec belongs to and routes it to the correct GitHub repository based on configuration.
-**Key Capabilities**:
-- ✅ Detects project from spec file path (`.specweave/docs/internal/specs/{project-id}/`)
-- ✅ Routes to correct GitHub repo based on project config
-- ✅ Supports 4 sync strategies (project-per-spec, team-board, centralized, distributed)
-- ✅ Handles cross-team specs (auth touches frontend + backend)
-- ✅ Backward compatible with single-project setups
----
-## Real-World Scenarios Supported
-### 1. **Monorepo with Multiple Teams**
-```
-my-company/monorepo/
-├── frontend/  (React web app)
-├── backend/   (Node.js API)
-├── ml/        (TensorFlow models)
-└── infrastructure/  (K8s configs)
-```
-**Solution**: Each team has their own GitHub Project board. Specs in `.specweave/docs/internal/specs/frontend/` sync to `myorg/frontend-app`, specs in `.specweave/docs/internal/specs/backend/` sync to `myorg/backend-api`, etc.
-**Strategy**: `distributed` (each team syncs to their repo)
-### 2. **Multi-Repo with Parent Repo**
-```
-parent/  (docs only, no code)
-├── .specweave/docs/internal/specs/_parent/
-Child repos:
-- github.com/myorg/frontend
-- github.com/myorg/backend
-- github.com/myorg/mobile
-```
-**Solution**: Specs in `_parent/` create issues in child repos OR parent repo tracks all with labels.
-**Strategy**: `centralized` (parent repo tracks all) or `distributed` (issues created in child repos)
-### 3. **Team-Specific Repos**
-```
-platform-engineering/  (own .specweave/)
-frontend-team/         (own .specweave/)
-ml-team/              (own .specweave/)
-```
-**Solution**: Each team repo has its own `.specweave/` and syncs to its own GitHub Projects.
-**Strategy**: `project-per-spec` (default, one GitHub Project per spec)
-### 4. **Cross-Team Specs**
-```
-Auth spec touches:
-- Frontend: Login UI
-- Backend: JWT validation
-- Mobile: Biometric login
-```
-**Solution**: Auth spec creates issues in all three repos (frontend, backend, mobile), filtered by relevance.
-**Strategy**: `distributed` with `enableCrossTeamDetection: true`
----
-## Sync Strategies
-### Strategy 1: Project-per-Spec (DEFAULT)
-- **Use When**: Standard single-project or independent projects
-- **Behavior**: One GitHub Project per spec (current behavior, no changes)
-- **Example**: `spec-001-user-auth.md` → GitHub Project "User Authentication"
-**Configuration**:
-```json
-{
-  "sync": {
-    "profiles": {
-      "myproject": {
-        "provider": "github",
-        "config": {
-          "owner": "myorg",
-          "repo": "myrepo",
-          "githubStrategy": "project-per-spec"
-        }
-      }
-    }
-  }
-}
-```
-**Result**:
-- `.specweave/docs/internal/specs/spec-001.md` → GitHub Project in `myorg/myrepo`
-- One spec = One GitHub Project
----
-### Strategy 2: Team-Board
-- **Use When**: Team wants one board for all their specs
-- **Behavior**: All specs from same team/project sync to one shared GitHub Project
-- **Example**: `spec-001.md`, `spec-002.md`, `spec-003.md` → All to "Frontend Team Board"
-**Configuration**:
-```json
-{
-  "sync": {
-    "profiles": {
-      "frontend": {
-        "provider": "github",
-        "config": {
-          "owner": "myorg",
-          "repo": "frontend-app",
-          "githubStrategy": "team-board",
-          "teamBoardId": 12345  // Optional: existing board ID
-        }
-      }
-    }
-  }
-}
-```
-**Result**:
-- Multiple specs → One GitHub Project (team board)
-- Easier to see all team work in one place
----
-### Strategy 3: Centralized
-- **Use When**: Parent repo tracks all specs (multi-repo pattern)
-- **Behavior**: Issues created in parent repo with tags for child repos
-- **Example**: All specs → Parent repo issues with labels like `project:frontend`, `project:backend`
-**Configuration**:
-```json
-{
-  "sync": {
-    "profiles": {
-      "parent": {
-        "provider": "github",
-        "config": {
-          "owner": "myorg",
-          "repo": "parent-repo",
-          "githubStrategy": "centralized"
-        }
-      }
-    },
-    "projects": {
-      "frontend": {
-        "id": "frontend",
-        "defaultSyncProfile": "parent"
-      },
-      "backend": {
-        "id": "backend",
-        "defaultSyncProfile": "parent"
-      }
-    }
-  }
-}
-```
-**Result**:
-- All specs sync to parent repo
-- Issues tagged with project/team labels
-- Good for high-level tracking
----
-### Strategy 4: Distributed
-- **Use When**: Each team syncs to their repo (microservices)
-- **Behavior**: Each team's specs go to their repo; cross-team specs create issues in multiple repos
-- **Example**: Auth spec (cross-team) → Issues in `frontend-app`, `backend-api`, `mobile-app`
-**Configuration**:
-```json
-{
-  "sync": {
-    "profiles": {
-      "frontend": {
-        "provider": "github",
-        "config": {
-          "owner": "myorg",
-          "repo": "frontend-app",
-          "githubStrategy": "distributed",
-          "enableCrossTeamDetection": true
-        }
-      },
-      "backend": {
-        "provider": "github",
-        "config": {
-          "owner": "myorg",
-          "repo": "backend-api",
-          "githubStrategy": "distributed",
-          "enableCrossTeamDetection": true
-        }
-      }
-    },
-    "projects": {
-      "frontend": {
-        "id": "frontend",
-        "defaultSyncProfile": "frontend"
-      },
-      "backend": {
-        "id": "backend",
-        "defaultSyncProfile": "backend"
-      }
-    }
-  }
-}
-```
-**Result**:
-- Single-team specs sync to their repo
-- Cross-team specs sync to all relevant repos
-- User stories filtered by relevance
----
-## Cross-Team Spec Detection
-**How It Works**:
-1. Spec title contains keywords: `integration`, `cross-team`, `shared`, `auth`, `api-contract`
-2. Spec has multiple project tags: `["project:frontend", "project:backend"]`
-3. User stories reference multiple projects
-**Example**:
-```markdown
----
-title: "User Authentication Integration"
-tags: ["project:frontend", "project:backend", "cross-team"]
----
-## User Stories
-**US-001**: As a frontend developer, I want login UI
-**US-002**: As a backend developer, I want JWT validation
-**US-003**: As a developer, I want API contract  (shared)
-```
-**Result**:
-- Issue created in `frontend-app` with US-001 + US-003
-- Issue created in `backend-api` with US-002 + US-003
-- Shared stories (US-003) appear in both repos
----
-## Project Detection
-**Automatic Detection** from spec file path:
-```
-.specweave/docs/internal/specs/frontend/spec-001.md  → projectId: "frontend"
-.specweave/docs/internal/specs/backend/spec-001.md   → projectId: "backend"
-.specweave/docs/internal/specs/spec-001.md           → projectId: "default"
-```
-**Configuration Lookup**:
-```json
-{
-  "sync": {
-    "projects": {
-      "frontend": {
-        "id": "frontend",
-        "name": "Frontend Team",
-        "defaultSyncProfile": "frontend-profile",
-        "specsFolder": ".specweave/docs/internal/specs/frontend"
-      }
-    },
-    "profiles": {
-      "frontend-profile": {
-        "provider": "github",
-        "config": {
-          "owner": "myorg",
-          "repo": "frontend-app"
-        }
-      }
-    }
-  }
-}
-```
-**Result**: Spec automatically routed to correct GitHub repo!
----
-## Configuration Examples
-### Example 1: Simple Single-Project (Backward Compatible)
-```json
-{
-  "sync": {
-    "activeProfile": "main",
-    "profiles": {
-      "main": {
-        "provider": "github",
-        "config": {
-          "owner": "myorg",
-          "repo": "myrepo"
-        }
-      }
-    }
-  }
-}
-```
-**Result**: All specs sync to `myorg/myrepo` (default behavior, no changes)
----
-### Example 2: Multi-Project with Distributed Strategy
-```json
-{
-  "sync": {
-    "profiles": {
-      "frontend-profile": {
-        "provider": "github",
-        "config": {
-          "owner": "myorg",
-          "repo": "frontend-app",
-          "githubStrategy": "distributed",
-          "enableCrossTeamDetection": true
-        }
-      },
-      "backend-profile": {
-        "provider": "github",
-        "config": {
-          "owner": "myorg",
-          "repo": "backend-api",
-          "githubStrategy": "distributed",
-          "enableCrossTeamDetection": true
-        }
-      }
-    },
-    "projects": {
-      "frontend": {
-        "id": "frontend",
-        "name": "Frontend Team",
-        "keywords": ["frontend", "react", "ui"],
-        "defaultSyncProfile": "frontend-profile",
-        "specsFolder": ".specweave/docs/internal/specs/frontend"
-      },
-      "backend": {
-        "id": "backend",
-        "name": "Backend Team",
-        "keywords": ["backend", "api", "nodejs"],
-        "defaultSyncProfile": "backend-profile",
-        "specsFolder": ".specweave/docs/internal/specs/backend"
-      }
-    }
-  }
-}
-```
-**Result**:
-- Frontend specs → `myorg/frontend-app`
-- Backend specs → `myorg/backend-api`
-- Cross-team specs → Both repos
----
-### Example 3: Team-Board Strategy
-```json
-{
-  "sync": {
-    "profiles": {
-      "frontend-team": {
-        "provider": "github",
-        "config": {
-          "owner": "myorg",
-          "repo": "frontend-app",
-          "githubStrategy": "team-board"
-        }
-      }
-    },
-    "projects": {
-      "frontend": {
-        "id": "frontend",
-        "defaultSyncProfile": "frontend-team"
-      }
-    }
-  }
-}
-```
-**Result**: All frontend specs sync to ONE shared GitHub Project
----
-### Example 4: Centralized Strategy (Parent Repo)
-```json
-{
-  "sync": {
-    "profiles": {
-      "parent": {
-        "provider": "github",
-        "config": {
-          "owner": "myorg",
-          "repo": "parent-repo",
-          "githubStrategy": "centralized"
-        }
-      }
-    },
-    "projects": {
-      "_parent": {
-        "id": "_parent",
-        "defaultSyncProfile": "parent"
-      },
-      "frontend": {
-        "id": "frontend",
-        "defaultSyncProfile": "parent"
-      },
-      "backend": {
-        "id": "backend",
-        "defaultSyncProfile": "parent"
-      }
-    }
-  }
-}
-```
-**Result**: All specs sync to parent repo with project tags
----
-## Usage
-### Basic Usage (Single Project)
-```bash
-# Create spec
-/sw:increment "User authentication"
-# Sync to GitHub (auto-detects project = default)
-/sw-github:sync-spec spec-001
-```
-### Multi-Project Usage
-```bash
-# Create spec in frontend project
-# (place in .specweave/docs/internal/specs/frontend/)
-# Sync to GitHub (auto-detects project = frontend, routes to frontend-app repo)
-/sw-github:sync-spec spec-001
-# Cross-team spec (auto-syncs to multiple repos)
-/sw-github:sync-spec spec-auth
-# → Creates issues in frontend-app AND backend-api
-```
----
-## Metadata Schema (v0.18.0+)
-**Enhanced GitHubLink with multi-project support**:
-```typescript
-export interface GitHubLink {
-  projectId?: number;
-  projectUrl?: string;
-  syncedAt?: string;
-  owner?: string;
-  repo?: string;
-  // NEW in v0.18.0
-  syncStrategy?: 'project-per-spec' | 'team-board' | 'centralized' | 'distributed';
-  specProjectId?: string;  // Maps to .specweave/docs/internal/specs/{projectId}/
-  crossTeamRepos?: Array<{
-    owner: string;
-    repo: string;
-    projectUrl?: string;
-    relevantUserStories?: string[];  // US-IDs synced to this repo
-  }>;
-  teamBoardId?: number;
-  syncProfileId?: string;
-}
-```
-**Example metadata in spec.md**:
-```yaml
----
-id: spec-auth
-title: "User Authentication Integration"
-externalLinks:
-  github:
-    syncStrategy: distributed
-    specProjectId: frontend
-    crossTeamRepos:
-      - owner: myorg
-        repo: frontend-app
-        projectUrl: https://github.com/myorg/frontend-app/projects/1
-        relevantUserStories: [US-001, US-003]
-      - owner: myorg
-        repo: backend-api
-        projectUrl: https://github.com/myorg/backend-api/projects/1
-        relevantUserStories: [US-002, US-003]
----
-```
----
-## Implementation Details
-### File Structure
-**Enhanced Files**:
-- `plugins/specweave-github/lib/github-spec-sync.ts` (1246 lines) - Multi-project routing logic
-- `src/core/types/sync-profile.ts` (546 lines) - GitHubSyncStrategy type
-- `src/core/types/spec-metadata.ts` (301 lines) - Enhanced GitHubLink interface
-**New Methods**:
-- `detectProjectFromSpecPath()` - Detects project from file path
-- `getGitHubConfigForProject()` - Gets GitHub config for project
-- `syncWithStrategy()` - Routes to strategy-specific sync
-- `syncProjectPerSpec()` - Strategy 1 implementation
-- `syncTeamBoard()` - Strategy 2 implementation
-- `syncCentralized()` - Strategy 3 implementation
-- `syncDistributed()` - Strategy 4 implementation
-- `isCrossTeamSpec()` - Detects cross-team specs
-- `syncCrossTeamSpec()` - Syncs to multiple repos
-- `detectRelatedProfiles()` - Finds all related profiles
-- `filterRelevantUserStories()` - Filters stories by project
----
-## Testing
-**E2E Test Suite** (`tests/e2e/github-sync-multi-project.spec.ts`):
-- ✅ Single-project sync (backward compatible)
-- ✅ Multi-project sync (frontend, backend, ml)
-- ✅ Parent repo pattern (_parent project)
-- ✅ Cross-team specs (auth touches frontend + backend)
-- ✅ Team-board strategy (aggregate multiple specs)
-- ✅ Centralized strategy (parent repo tracks all)
-- ✅ Distributed strategy (each team syncs to their repo)
-**Run Tests**:
-```bash
-npm run test:e2e -- github-sync-multi-project
-```
----
-## Migration from Single-Project
-**Existing single-project setups continue to work without changes!**
-**No Action Required** if you have:
-```json
-{
-  "sync": {
-    "activeProfile": "main",
-    "profiles": {
-      "main": {
-        "provider": "github",
-        "config": {
-          "owner": "myorg",
-          "repo": "myrepo"
-        }
-      }
-    }
-  }
-}
-```
-**To Enable Multi-Project**:
-1. Create project contexts in config
-2. Set `defaultSyncProfile` for each project
-3. Choose sync strategy per profile
-4. Organize specs into project folders
-**Example Migration**:
-```bash
-# Before: All specs in .specweave/docs/internal/specs/
-spec-001.md
-spec-002.md
-spec-003.md
-# After: Specs organized by project
-.specweave/docs/internal/specs/frontend/spec-001.md
-.specweave/docs/internal/specs/backend/spec-002.md
-.specweave/docs/internal/specs/ml/spec-003.md
-```
----
-## Troubleshooting
-### Issue: Spec syncs to wrong repo
-**Cause**: Project detection failed or config incorrect
-**Solution**:
-1. Check spec file path: `.specweave/docs/internal/specs/{projectId}/`
-2. Verify project exists in config: `config.sync.projects[projectId]`
-3. Verify profile config: `config.sync.profiles[profileId]`
-### Issue: Cross-team spec not detected
-**Cause**: Missing tags or keywords
-**Solution**:
-1. Add project tags: `tags: ["project:frontend", "project:backend"]`
-2. Or use cross-team keywords in title: "integration", "cross-team", "auth"
-### Issue: Team board not created
-**Cause**: Missing `githubStrategy: "team-board"`
-**Solution**: Set strategy in profile config:
-```json
-{
-  "config": {
-    "githubStrategy": "team-board"
-  }
-}
-```
----
-## Future Enhancements
-**Planned for v0.19.0+**:
-- [ ] Auto-create projects from git submodules
-- [ ] Visual project/repo mapping dashboard
-- [ ] GitHub Actions integration per project
-- [ ] Cross-repo PR linking
-- [ ] Team velocity metrics per project
----
-## Projects V2 Integration (v1.0.235+)
-### Overview
-The sync system now supports GitHub Projects V2 for visual project management:
-- Issues are added to Projects V2 boards after creation
-- Status and Priority custom fields are synced via configurable mappings
-- Cross-repo issues can be added to the same org-level project
-### Architecture
-```
-Spec → Push Sync → GitHub Issues → Board Resolver V2 → Projects V2
-                                   Field Sync → Status/Priority fields
-                                   Frontmatter Updater → spec.md metadata
-```
-### Key Components
-| Module | Purpose |
-|--------|---------|
-| `github-sync-orchestrator.ts` | Composes push + V2 + frontmatter into single flow |
-| `github-board-resolver-v2.ts` | Find/create Projects V2 boards |
-| `github-field-sync.ts` | Sync Status/Priority custom fields |
-| `github-graphql-client.ts` | GraphQL mutations via `gh api graphql` |
-| `github-spec-frontmatter-updater.ts` | Write sync results to spec.md |
-### Configuration
-```json
-{
-  "sync": {
-    "profiles": {
-      "myproject": {
-        "provider": "github",
-        "config": {
-          "owner": "myorg",
-          "repo": "myrepo",
-          "projectV2Enabled": true,
-          "projectV2Number": 5,
-          "statusFieldMapping": {
-            "planned": "Todo",
-            "in-progress": "In Progress",
-            "completed": "Done"
-          }
-        }
-      }
-    }
-  }
-}
-```
-### Pull Sync (GitHub to Spec)
-The pull sync fetches GitHub issue state and compares with spec ACs:
-- `github-pull-sync.ts` — fetches issues, compares AC states
-- `github-conflict-resolver.ts` — field-level conflict detection
-- Modes: `github-wins` (default for status/AC), `spec-wins`, `prompt` (for content)
-### Cross-Repo Sync
-- `github-cross-repo-sync.ts` — creates issues in multiple repos per user story
-- Cross-references added: "Also tracked in: org/other-repo#XX"
-- All cross-repo issues can be added to a shared org-level Projects V2 board
-### Batch Sync
-- `github-batch-sync.ts` — discovers all specs and syncs sequentially
-- Usage: `batchSyncAllSpecs({ owner, repo, workspaceRoot })`
-- Returns aggregated summary: specs processed, issues created/updated, errors
-### Agent Teams Orchestration
-Skills for parallel multi-domain development:
-- `/sw:team-lead` — analyze feature, create per-domain increments, spawn agents
-- `/sw:team-status` — show agent progress table
-- `/sw:team-merge` — merge in dependency order, trigger sync per increment
-## References
-- **Orchestrator**: `plugins/specweave-github/lib/github-sync-orchestrator.ts`
-- **Push Sync**: `plugins/specweave-github/lib/github-push-sync.ts`
-- **Pull Sync**: `plugins/specweave-github/lib/github-pull-sync.ts`
-- **Board Resolver V2**: `plugins/specweave-github/lib/github-board-resolver-v2.ts`
-- **Field Sync**: `plugins/specweave-github/lib/github-field-sync.ts`
-- **Conflict Resolver**: `plugins/specweave-github/lib/github-conflict-resolver.ts`
-- **Cross-Repo**: `plugins/specweave-github/lib/github-cross-repo-sync.ts`
-- **Batch Sync**: `plugins/specweave-github/lib/github-batch-sync.ts`
-- **GraphQL Client**: `plugins/specweave-github/lib/github-graphql-client.ts`
-- **Types**: `src/core/types/sync-profile.ts`
-- **Tests**: `tests/unit/plugins/github/`
-- **Legacy**: `plugins/specweave-github/lib/github-spec-sync.ts`
-- **Original Architecture Fix**: `plugins/specweave-github/SYNC-ARCHITECTURE-FIX-SUMMARY.md`
----
-**Version**: v1.0.235
-**Last Updated**: 2026-02-06
-**Status**: Complete and Tested