Skip to main content

Multi-Project Setup Guide

Version: 0.16.11+ (Flattened Structure) Last Updated: 2025-11-11 Previous Version: 0.8.0-0.16.10 (Nested Structure)

Complete guide to setting up and using SpecWeave's multi-project mode for enterprise teams managing multiple repos, microservices, or projects.

Table of Contents​

Overview​

Multi-project mode allows you to organize SpecWeave documentation by project or team:

  • Specs - Feature specifications per project
  • Modules - Module-level documentation per project
  • Team Docs - Team playbooks and conventions per project
  • Architecture - Project-specific architecture (optional)
  • Legacy - Brownfield imported documentation per project

Key Benefit: Clean separation for multiple teams, repos, or microservices while sharing cross-cutting docs (strategy, operations, governance).

When to Use Multi-Project​

Single Project Mode (Default)​

Use when:

  • Small projects or startups
  • One team, one codebase
  • Simple organizational structure
  • Getting started with SpecWeave

Structure:

.specweave/docs/internal/specs/default/
├── specs/
├── modules/
└── team/

Behavior: Uses projects/default/ automatically (transparent to you).

Multi-Project Mode​

Use when:

  • Multiple teams or repos
  • Microservices architecture
  • Platform engineering managing multiple projects
  • Different tech stacks per team
  • Enterprise with multiple products

Structure:

.specweave/docs/internal/specs/
├── web-app/
├── mobile-app/
└── platform-infra/

Behavior: Switch between projects using /sw:switch-project.

Getting Started​

Step 1: Initialize Multi-Project Mode​

/sw:init-multiproject

Interactive prompts:

🚀 Initialize Multi-Project Mode

✅ Migration complete! Using projects/default/ structure

Enable multi-project mode? (supports multiple teams/repos) (y/N): y
✅ Multi-project mode enabled!

Create additional projects? (besides "default") (y/N): y

📝 Create New Project

Project ID (kebab-case): web-app
Project name: Web Application
Description: Customer-facing web application
Tech stack (comma-separated): [React](/docs/glossary/terms/react), [TypeScript](/docs/glossary/terms/typescript), [Node.js](/docs/glossary/terms/nodejs), PostgreSQL
Team name: Frontend Team
Tech lead email (optional): lead@example.com
Product manager email (optional): pm@example.com

✅ Created project: Web Application (web-app)

Create another project? (y/N): y

Project ID (kebab-case): mobile-app
...

Step 2: Switch to a Project​

/sw:switch-project web-app

Output:

✅ Switched to project: Web Application (web-app)

ℹ️  Future increments will use:
   - .specweave/docs/internal/specs/web-app/
   - .specweave/docs/internal/modules/web-app/
   - .specweave/docs/internal/team/web-app/

Step 3: Create Increments (As Usual)​

/sw:increment "Add user authentication"

Result: Spec created in specs/web-app/spec-001-user-auth.md

Project Structure​

Full Directory Structure​

.specweave/docs/internal/
│
├── strategy/              # Cross-project (business rationale)
├── architecture/          # Shared architecture (system-wide ADRs)
├── delivery/              # Cross-project (build & release)
├── operations/            # Cross-project (production ops)
├── governance/            # Cross-project (policies)
│
└── projects/              # 🆕 Multi-project support
    │
    ├── _README.md         # Multi-project guide
    │
    ├── default/           # Default project (single-project mode)
    │   ├── README.md      # Project overview
    │   ├── specs/         # Living docs specs
    │   │   ├── spec-001-user-auth.md
    │   │   └── spec-002-payments.md
    │   ├── modules/       # Module-level docs
    │   │   ├── auth-module.md
    │   │   └── payment-module.md
    │   ├── team/          # Team playbooks
    │   │   ├── onboarding.md
    │   │   ├── conventions.md
    │   │   └── workflows.md
    │   ├── architecture/  # Project-specific architecture
    │   │   ├── README.md
    │   │   └── adr/       # Project-specific ADRs
    │   └── legacy/        # Brownfield imports
    │       ├── README.md
    │       ├── notion/
    │       └── confluence/
    │
    ├── web-app/           # Additional projects
    │   └── ... (same structure)
    │
    ├── mobile-app/
    │   └── ... (same structure)
    │
    └── platform-infra/
        └── ... (same structure)

Per-Project Folders​

Each project has:

1. specs/ - Living Documentation Specs​

Purpose: Feature specifications with user stories and acceptance criteria

Example:

specs/
├── spec-001-user-auth.md
├── spec-002-payments.md
└── spec-003-notifications.md

Naming: spec-NNN-feature-name.md

2. modules/ - Module Documentation​

Purpose: Module/component-level documentation

Example:

modules/
├── README.md
├── auth-module.md          # Authentication domain
├── payment-module.md       # Payment processing
└── notification-module.md  # Messaging

When to create: Large modules with complex logic, integration points, or security considerations

3. team/ - Team Playbooks​

Purpose: Team-specific conventions and workflows

Example:

team/
├── README.md
├── onboarding.md           # How to join this team
├── conventions.md          # Coding standards, naming
├── workflows.md            # PR process, deployments
└── contacts.md             # Team members, on-call

4. architecture/ - Project-Specific Architecture​

Purpose: Architecture docs specific to this project (optional)

Example:

architecture/
├── README.md
└── adr/                    # Project-specific ADRs
    ├── 0001-use-postgres.md
    └── 0002-api-versioning.md

When to use:

  • Project-specific: Decisions affecting only this project
  • Shared (.specweave/docs/internal/architecture/): System-wide decisions

5. legacy/ - Brownfield Imports​

Purpose: Imported documentation from external sources

Example:

legacy/
├── README.md              # Migration report
├── notion/                # From Notion export
├── confluence/            # From Confluence
└── wiki/                  # From GitHub Wiki

Workflows​

Workflow 1: Managing Multiple Teams​

Scenario: Frontend team and Mobile team, separate repos

# Morning: Frontend team work
/sw:switch-project web-app
/sw:increment "Add dark mode"
# Spec created in: specs/web-app/spec-004-dark-mode.md

# Afternoon: Mobile team work
/sw:switch-project mobile-app
/sw:increment "Add biometric auth"
# Spec created in: specs/mobile-app/spec-001-biometric-auth.md

Workflow 2: Platform Engineering​

Scenario: Platform team managing infrastructure + multiple app teams

# Projects:
# - platform-infra (Terraform, K8s, runbooks)
# - backend-api (Node.js API)
# - frontend-app (React)

# Infrastructure work
/sw:switch-project platform-infra
/sw:increment "Upgrade Kubernetes to 1.28"

# Backend work
/sw:switch-project backend-api
/sw:increment "Add rate limiting middleware"

# Frontend work
/sw:switch-project frontend-app
/sw:increment "Implement new design system"

Workflow 3: Microservices​

Scenario: 5 microservices, each with its own project

# Projects:
# - user-service
# - order-service
# - payment-service
# - notification-service
# - analytics-service

/sw:switch-project user-service
/sw:increment "Add OAuth2 support"

/sw:switch-project order-service
/sw:increment "Implement order tracking"

# Each service gets its own specs, modules, team docs

Integration with External Sync​

Multi-project mode integrates with external sync (GitHub, JIRA, ADO):

Configuration​

File: .specweave/config.json

{
  "multiProject": {
    "enabled": true,
    "activeProject": "web-app",
    "projects": [
      {
        "id": "web-app",
        "name": "Web Application",
        "description": "Customer-facing web app",
        "techStack": ["React", "TypeScript"],
        "team": "Frontend Team",
        "syncProfiles": ["web-app-github", "web-app-jira"]
      },
      {
        "id": "mobile-app",
        "name": "Mobile Application",
        "techStack": ["React Native"],
        "team": "Mobile Team",
        "syncProfiles": ["mobile-jira"]
      }
    ]
  },
  "sync": {
    "profiles": {
      "web-app-github": {
        "provider": "github",
        "config": {
          "owner": "acme-corp",
          "repo": "web-app"
        }
      },
      "web-app-jira": {
        "provider": "jira",
        "config": {
          "domain": "acme.atlassian.net",
          "projectKey": "WEBAPP"
        }
      },
      "mobile-jira": {
        "provider": "jira",
        "config": {
          "domain": "acme.atlassian.net",
          "projectKey": "MOBILE"
        }
      }
    }
  }
}

Workflow with Sync​

# Switch to web-app
/sw:switch-project web-app

# Create increment (syncs to web-app-github and web-app-jira)
/sw:increment "Add payment integration"

# Result:
# - Spec: specs/web-app/spec-005-payment-integration.md
# - GitHub issue created in acme-corp/web-app
# - JIRA epic created in WEBAPP project

Note: If you used the -shared flag during specweave init, ensure your git remote also includes -shared in the repo name. Validate with: bash scripts/validate-parent-repo-setup.sh

Best Practices​

1. Project Organization​

Group by team or repo:

projects/
├── team-alpha/         ✅ Good (team-based)
├── team-beta/
└── team-gamma/

projects/
├── web-app/            ✅ Good (repo-based)
├── mobile-app/
└── backend-api/

projects/
├── feature-auth/       ❌ Bad (feature-based, too granular)
├── feature-payments/
└── feature-reports/

2. Spec Numbering​

Specs are numbered per project:

specs/web-app/
├── spec-001-user-auth.md       ← Web app feature 1
└── spec-002-payments.md        ← Web app feature 2

specs/mobile-app/
├── spec-001-push-notifs.md     ← Mobile feature 1 (different from web!)
└── spec-002-offline-mode.md   ← Mobile feature 2

Key: spec-001 in web-app is DIFFERENT from spec-001 in mobile-app.

3. Module Documentation​

Create module docs when:

  • Module has complex logic (>1000 lines of code)
  • Module has security implications (auth, payments)
  • Module has integration points (external APIs)
  • Module is reused across services

Example:

modules/
├── auth-module.md              ✅ Good (auth is complex)
├── payment-module.md           ✅ Good (payments are critical)
├── notification-module.md      ✅ Good (integrations)
└── button-component.md         ❌ Overkill (too simple)

4. Team Playbooks​

Update regularly:

  • Onboarding: Review every quarter
  • Conventions: Update when tech stack changes
  • Workflows: Update when process changes

5. Legacy Cleanup​

After brownfield import:

  • Review classification weekly
  • Move misclassified files immediately
  • Delete obsolete content monthly
  • Remove legacy/ folder when migration complete

Troubleshooting​

Problem: Can't switch projects​

Error: Multi-project mode not enabled

Solution:

/sw:init-multiproject
# Select "Yes" to enable multi-project mode

Problem: Project not found​

Error: Project 'foo' not found

Solution:

# List all projects
/sw:switch-project

# Create missing project
/sw:init-multiproject
# Select "Yes" to create additional projects

Problem: Specs in wrong project​

Issue: Created increment in wrong project

Solution:

  1. Switch to correct project: /sw:switch-project correct-project
  2. Manually move spec file to correct project folder
  3. Update increment metadata if needed

Problem: Sync profiles not working​

Issue: External sync not creating issues in correct repo

Solution:

  1. Check config: cat .specweave/config.json
  2. Verify syncProfiles array in project config
  3. Verify profiles exist in sync.profiles
  4. Restart SpecWeave after config changes

Migration from Single to Multi-Project​

/sw:init-multiproject

# Prompts:
# - Enable multi-project mode? → Yes
# - Create additional projects? → Yes (optional)

Saving Changes Across Repos​

Use /sw:save to commit and push changes across all repos with a single command:

# Save all repos with same commit message
/sw:save "feat: Add user authentication"

# Preview what would happen
/sw:save --dry-run

# Save specific repos only
/sw:save "fix: Bug fixes" --repos frontend,backend

Example Workflow​

/sw:save "feat: Complete user registration"

Scanning for repositories...
Mode: Umbrella (3 child repos)

frontend:
  Status: 4 files changed
  ✓ Committed and pushed

backend:
  Status: 2 files changed
  ✓ Committed and pushed

shared:
  Status: No changes (skipping)

Summary:
  ✓ Saved: 2/3 repositories

Remote Setup​

If a repo has no remote configured, the command will:

  1. Check umbrella config - Use githubUrl if configured
  2. Prompt for URL - Ask you to enter manually or use GitHub convention
  3. Skip - Continue without saving that repo

Tip: Configure githubUrl in your umbrella config for seamless remote setup:

{
  "umbrella": {
    "childRepos": [
      {
        "id": "myapp-frontend",
        "path": "./myapp-frontend",
        "githubUrl": "https://github.com/myorg/myapp-frontend"
      }
    ]
  }
}

ID Strategy: The id MUST match the repo name exactly (e.g., myapp-frontend), not arbitrary abbreviations like fe.

See the full /sw:save command reference for more options.

See Also​

  • Brownfield Import Guide (coming soon) - Import existing docs from external sources
  • Team Playbooks Guide (coming soon) - Best practices for team documentation
  • /sw:init-multiproject - CLI command reference
  • /sw:switch-project - CLI command reference
  • /sw:import-docs - CLI command reference
  • /sw:save - Save changes across all repos

Last Updated: 2025-11-05 Version: 0.8.0+