/github-multi-project

description: "[DEPRECATED] Use `sw:multi-project --tool github` instead. Organizes specs and splits tasks across multiple GitHub repositories. This skill will be removed in SpecWeave v1.3.0."
version: 1.0.0
user-invokable: false

GitHub Multi-Project Management Skill

Migration

> Deprecated. Use: `sw:multi-project --tool github`

This skill has been consolidated into the unified `sw:multi-project` skill. Replace any invocation of `sw:github-multi-project` with `sw:multi-project --tool github`. The flag-based skill supports GitHub, Azure DevOps, and Jira under a single interface. See `plugins/specweave/skills/multi-project/SKILL.md`.

Scheduled for removal in SpecWeave v1.3.0.

Expert skill for managing SpecWeave projects across multiple GitHub repositories.

Core Capabilities

1. Spec Organization

• Organizes specs in `.specweave/docs/internal/projects/{project-id}/` structure
• Maps increments to specific projects/repos
• Maintains traceability across repositories
• Handles cross-project dependencies

2. Task Splitting

When a SpecWeave increment spans multiple repositories:

• Analyzes tasks in `tasks.md`
• Identifies which tasks belong to which repo
• Creates repo-specific task lists
• Maintains cross-repo coordination

3. Repository Architectures

Single Repository

my-app/
├── .specweave/
│   └── docs/internal/projects/default/
└── src/

Multi-Repository (Polyrepo)

my-app-frontend/
├── .git
└── src/

my-app-backend/
├── .git
└── src/

my-app-shared/
├── .git
└── src/

Parent Repository Approach (Recommended for Multi-Repo)

my-app-parent/              # Parent repo with .specweave
├── .specweave/
│   └── docs/internal/projects/
│       ├── frontend/
│       ├── backend/
│       └── shared/
└── services/               # Implementation repos
    ├── frontend/
    ├── backend/
    └── shared/

Monorepo

my-app/
├── .specweave/
│   └── docs/internal/projects/
│       ├── frontend/
│       ├── backend/
│       └── shared/
└── packages/
    ├── frontend/
    ├── backend/
    └── shared/

Task Splitting Examples

Example 1: E-commerce Platform

**Increment**: Add shopping cart functionality

**Tasks split by repository**:

**Frontend (my-app-frontend)**:

• T-001: Create CartItem component
• T-002: Implement cart state management
• T-003: Add cart UI with add/remove buttons

**Backend (my-app-backend)**:

• T-004: Create cart database schema
• T-005: Implement cart API endpoints
• T-006: Add cart validation logic

**Shared (my-app-shared)**:

• T-007: Define cart TypeScript types
• T-008: Create cart utility functions

Example 2: Microservices Architecture

**Increment**: Implement user notifications

**Tasks split by service**:

**User Service**:

• T-001: Add notification preferences to user profile
• T-002: Create preference API endpoints

**Notification Service**:

• T-003: Implement notification queue
• T-004: Create email sender
• T-005: Create push notification sender

**Gateway Service**:

• T-006: Add notification routes
• T-007: Implement rate limiting

Commands

Analyze Task Distribution

// Analyze which tasks belong to which repository
function analyzeTaskDistribution(tasks: Task[]): Map<string, Task[]> {
  const distribution = new Map();

  for (const task of tasks) {
    const repo = detectRepository(task);
    if (!distribution.has(repo)) {
      distribution.set(repo, []);
    }
    distribution.get(repo).push(task);
  }

  return distribution;
}

Create Repository-Specific Issues

// Create GitHub issues in each repository
async function createRepoSpecificIssues(
  increment: Increment,
  distribution: Map<string, Task[]>
) {
  for (const [repo, tasks] of distribution) {
    const issue = await createGitHubIssue({
      repo,
      title: `[${increment.id}] ${increment.name} - ${repo}`,
      body: formatTasksAsChecklist(tasks),
      labels: ['specweave', 'increment', repo]
    });

    console.log(`Created issue #${issue.number} in ${repo}`);
  }
}

Best Practices

1. Parent Repository Approach

**Recommended for multi-repo projects**:

• Central .specweave/ folder in parent repo
• Living docs sync to parent (single source of truth)
• Implementation repos stay clean
• Better for enterprise/multi-team projects

2. Task Naming Convention

T-{repo}-{number}: {description}
T-FE-001: Create user profile component
T-BE-001: Implement user API
T-SHARED-001: Define user types

3. Cross-Repository Dependencies

Mark dependencies clearly:

T-FE-002: Consume user API
  Dependencies: T-BE-001 (must complete first)

4. Spec Organization

.specweave/docs/internal/projects/
├── frontend/
│   └── specs/
│       ├── spec-001-user-interface.md
│       └── spec-002-cart-ui.md
├── backend/
│   └── specs/
│       ├── spec-001-api-design.md
│       └── spec-002-database.md
└── shared/
    └── specs/
        └── spec-001-types.md

Integration with GitHub Projects

Multi-Repo GitHub Project

Create a GitHub Project that spans multiple repositories: 1. Create project at organization level 2. Add issues from all repos 3. Use project boards for cross-repo coordination 4. Track overall increment progress

Repository-Specific Projects

Each repository can have its own project:

• Frontend Project: UI tasks
• Backend Project: API tasks
• Shared Project: Common tasks

Automation

GitHub Actions Integration

# .github/workflows/specweave-sync.yml
name: SpecWeave Multi-Repo Sync

on:
  workflow_dispatch:
  schedule:
    - cron: '0 */6 * * *' # Every 6 hours

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Sync to repositories
        run: |
          # Sync tasks to frontend repo
          gh issue create --repo myorg/frontend ...

          # Sync tasks to backend repo
          gh issue create --repo myorg/backend ...

Error Handling

Common Issues

1. **Repos