GitHub Multi-Project Management Skill

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:

• Create project at organization level

• Add issues from all repos

• Use project boards for cross-repo coordination

• 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

• Repository not found: Ensure repos exist and token has access

• Task ambiguity: Use clear naming to indicate target repo

• Cross-repo conflicts: Use parent repo as single source of truth

• Permission errors: Token needs repo scope for all repositories

Related Skills

• github-sync: Basic GitHub synchronization

• github-issue-tracker: Task-level tracking

• specweave:multi-project-spec-mapper: Intelligent spec splitting