/multi-project

name: sw/multi-project
description: Unified multi-project management skill for GitHub, Azure DevOps, and Jira. Organizes specs and splits tasks across multiple repositories or projects for monorepo, polyrepo, project-per-team, and area-path architectures. Use `--tool github|ado|jira` to select the target integration.
version: 1.0.0
user-invokable: true
allowed-tools: Read, Write, Edit, Glob

Multi-Project Management Skill

Unified skill for organizing SpecWeave specs and increments across multiple projects or repositories. Supersedes the tool-specific `sw:github-multi-project` and `sw:ado-multi-project` skills, and adds Jira multi-project support.

`--tool` Flag

Select the target integration via the `--tool` flag:

| Value | Backend | Use When | |-------|---------|----------| | `--tool github` | GitHub repositories | Multi-repo and monorepo GitHub projects | | `--tool ado` | Azure DevOps projects / area paths | Project-per-team, area-path-based, or team-based ADO organizations | | `--tool jira` | Jira projects / components | Multi-project Jira instances with Epics/Stories |

Example invocations:

sw:multi-project --tool github
sw:multi-project --tool ado
sw:multi-project --tool jira

If `--tool` is omitted, the skill reads `integrations.primary` from `.specweave/config.json` and falls back to `github` when unset.

Core Capabilities (All Tools)

1. **Spec Organization** — organizes specs in `.specweave/docs/internal/projects/{project-id}/` 2. **Task Splitting** — analyzes `tasks.md` and splits work into project-specific tasks 3. **Cross-project Coordination** — tracks dependencies between projects 4. **Bidirectional Sync** — keeps local specs and remote work items in sync

Architectures

Single Repository / Single Project

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

Multi-Repository (Polyrepo — GitHub)

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

Parent Repository (Recommended for GitHub multi-repo)

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

Monorepo (GitHub / Jira / ADO)

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

Project-per-team (ADO / Jira recommended)

Organization: mycompany
├── AuthService
├── UserService
├── PaymentService
└── NotificationService

.specweave/docs/internal/specs/
├── AuthService/
├── UserService/
├── PaymentService/
└── NotificationService/

Area-path-based (ADO) / Component-based (Jira)

Organization: enterprise
└── ERP (Project)
    ├── Finance
    ├── HR
    ├── Inventory
    └── Sales

.specweave/docs/internal/specs/ERP/
├── Finance/
├── HR/
├── Inventory/
└── Sales/

---

GitHub (`--tool github`)

Merges the logic of the deprecated `sw:github-multi-project` skill.

Task Splitting Example

**Increment**: Add shopping cart functionality

| Repository | Tasks | |------------|-------| | `my-app-frontend` | T-001 CartItem component, T-002 cart state, T-003 cart UI | | `my-app-backend` | T-004 schema, T-005 API endpoints, T-006 validation | | `my-app-shared` | T-007 types, T-008 utilities |

Creating Repo-Specific Issues

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],
    });
  }
}

GitHub Projects Integration

• Org-level Project spanning multiple repos (preferred)
• Or per-repo Projects (Frontend / Backend / Shared)

GitHub Actions Sync

name: SpecWeave Multi-Repo Sync
on:
  workflow_dispatch:
  schedule: [{ cron: '0 */6 * * *' }]

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

---

Azure DevOps (`--tool ado`)

Merges the logic of the deprecated `sw:ado-multi-project` skill.

Intelligent Project Detection

const projectPatterns = {
  AuthService: {
    keywords: ['authentication', 'login', 'oauth', 'jwt', 'session'],
    filePatterns: ['auth/', 'login/', 'security/'],
  },
  UserService: {
    keywords: ['user', 'profile', 'account', 'registration'],
    filePatterns: ['users/', 'profiles/'],
  },
  PaymentService: {
    keywords: ['payment', 'stripe', 'billing', 'invoice'],
    filePatterns: ['payment/', 'billing/', 'checkout/'],
  },
};

**Confidence scoring**: keyword +0.2, file pattern +0.3, explicit mention +1.0, team mention +0.5. Threshold > 0.7 auto-assigns; otherwise prompts the user.

Area-path Strategy

AZURE_DEVOPS_STRATEGY=area-path-based
AZURE_DEVOPS_PROJECT=ERP
AZURE_DEVOPS_AREA_PATHS=Finance,HR,Inventory

Creates `.specweave/docs/internal/specs/ERP/{AreaPath}/` folders and maps increments to `ERP\{AreaPath}`.

Multi-project Work Items

A single increment spanning three ADO projects:

PaymentService  → Epic "Checkout Payment Processing" (primary)
UserService     → Feature "User Cart Management"     (linked)
NotificationService → Feature "Order Notifications"  (linked)

metadata.yml example

projects:
  primary: PaymentService
  dependencies:
    - UserService: [T-001, T-004]
    - NotificationService: [T-003]

ado_mappings:
  PaymentService:
    epic: 12345
    work_items: [12346, 12347]
  UserService:
    feature: 12348