Umbrella Repo Detector

Umbrella Multi-Repo Architecture Detector

When This Skill Activates

Activates when user describes:

• Multiple repos: "3 repos", "frontend repo", "backend repo", "shared library"
• Architecture patterns: "monorepo with services", "microservices", "multi-repo"
• Explicit splits: "FE/BE/Shared", "frontend/backend/common"
• GitHub URLs for multiple repositories

My Role

When I detect a multi-repo architecture in the user's prompt:

1. Acknowledge the architecture with detected repos
2. Explain project-scoped user stories (US-FE-, US-BE-, US-SHARED-*)
3. Guide the init flow for proper setup
4. Route to PM agent with multi-repo context

Detection Patterns

Project-Scoped User Stories

When user describes multi-repo, user stories MUST be prefixed:

## Instead of (generic):
US-001: User Registration
US-002: Registration API
US-003: Validation Schema

## Generate (project-scoped):
US-FE-001: User Registration Form
  - Related repo: frontend
  - Keywords: form, UI, validation display

US-BE-001: Registration API Endpoint
  - Related repo: backend
  - Keywords: API, endpoint, database

US-SHARED-001: Registration Validation Schema
  - Related repo: shared
  - Keywords: validator, schema, types

Cross-Cutting User Stories

For features that span multiple repos, use cross-project tagging:

US-AUTH-001: OAuth Integration
  - Tags: ["cross-project", "frontend", "backend"]
  - Creates linked issues in: FE repo, BE repo
  - Child stories:
    - US-FE-002: OAuth Login Button (frontend)
    - US-BE-002: OAuth Token Validation (backend)

Setup Flow Guidance

When multi-repo detected, guide user through options:

Option 1: Clone from GitHub (Recommended)

You have existing repos? Let's clone them:
1. Provide GitHub URLs (comma-separated or one per line)
2. Each repo gets its own .specweave/ configuration
3. Each repo syncs to its own GitHub issues

Option 2: Create New Repos

Creating fresh repos:
1. I'll create repos on GitHub for you
2. Each gets initialized with .specweave/
3. External tool sync configured per repo

Option 3: Initialize Local Folders

Have local folders already?
1. Point me to each folder
2. I'll initialize .specweave/ in each
3. Configure external tools per repo

Umbrella Repo Structure

umbrella-project/                 # Optional parent repo
├── .specweave/
│   ├── config.json              # umbrella config with childRepos[]
│   └── docs/                    # High-level PRD, roadmap only
│
├── my-app-fe/                   # Frontend repo (cloned/created)
│   └── .specweave/
│       ├── config.json          # sync → my-app-fe GitHub issues
│       └── increments/
│           └── 0001-feature/
│               └── spec.md      # Only US-FE-* stories
│
├── my-app-be/                   # Backend repo (cloned/created)
│   └── .specweave/
│       └── ...                  # sync → my-app-be GitHub issues
│
└── my-app-shared/               # Shared repo (cloned/created)
    └── .specweave/
        └── ...                  # sync → my-app-shared GitHub issues

Project ID Strategy

CRITICAL: The id field MUST match your canonical source name - no arbitrary abbreviations!

✅ CORRECT: id matches repo name
   id: "sw-qr-menu-fe"
   path: "./sw-qr-menu-fe"
   githubUrl: "https://github.com/user/sw-qr-menu-fe"

❌ WRONG: arbitrary abbreviation
   id: "fe"              ← What if you have 2 frontend repos?
   path: "./sw-qr-menu-fe"

Note: The prefix (for user stories like US-FE-001) can be short even if id is long:

• id: "sw-qr-menu-fe" (full repo name)
• prefix: "FE" (short, for user story IDs)

Config Example

Parent umbrella config (.specweave/config.json):

{
  "umbrella": {
    "enabled": true,
    "childRepos": [
      {
        "id": "sw-qr-menu-fe",
        "path": "./sw-qr-menu-fe",
        "prefix": "FE",
        "githubUrl": "https://github.com/myorg/sw-qr-menu-fe"
      },
      {
        "id": "sw-qr-menu-be",
        "path": "./sw-qr-menu-be",
        "prefix": "BE",
        "githubUrl": "https://github.com/myorg/sw-qr-menu-be"
      },
      {
        "id": "sw-qr-menu-shared",
        "path": "./sw-qr-menu-shared",
        "prefix": "SHARED",
        "githubUrl": "https://github.com/myorg/sw-qr-menu-shared"
      }
    ]
  }
}

JIRA-based project (when JIRA is source of truth):

{
  "umbrella": {
    "enabled": true,
    "childRepos": [
      {
        "id": "webapp",
        "path": "./frontend",
        "prefix": "WEBAPP",
        "jiraProject": "WEBAPP",
        "githubUrl": "https://github.com/myorg/frontend"
      }
    ]
  }
}

Child repo config (sw-qr-menu-fe/.specweave/config.json):

{
  "project": {
    "name": "QR Menu Frontend",
    "prefix": "FE"
  },
  "sync": {
    "activeProfile": "github",
    "profiles": {
      "github": {
        "provider": "github",
        "config": {
          "owner": "myorg",
          "repo": "sw-qr-menu-fe"
        }
      }
    }
  }
}

Response Template

When I detect multi-repo intent, respond:

I detected a **multi-repo architecture** in your description:

**Detected Repos:**
- Frontend (prefix: FE) - [matched keywords]
- Backend (prefix: BE) - [matched keywords]
- Shared (prefix: SHARED) - [matched keywords]

**User Story Format:**
User stories will be project-scoped:
- `US-FE-001`: Frontend stories
- `US-BE-001`: Backend stories
- `US-SHARED-001`: Shared library stories

**Setup Options:**
1. **Clone from GitHub** - Provide URLs, I'll clone and initialize each
2. **Create new repos** - I'll create on GitHub and initialize
3. **Initialize local folders** - Point to existing folders

Which would you like to do?

Keywords for Story Routing

Saving Changes Across Repos

Use /sw:save to commit and push changes across all repos at once:

# 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

Features:

• Auto-discovers nested repos - Scans repositories/, packages/, services/, apps/, libs/ for .git directories (up to 4 levels deep)
• Auto-detects repos with changes
• Sets up remotes if missing (prompts for URL or uses umbrella config)
• Commits with same message to all repos
• Pushes to origin
• Skips repos with no changes

Auto-Discovery (No Config Required): Even without umbrella config, /sw:save automatically finds all nested repos:

my-project/
├── repositories/
│   ├── frontend/.git    # ← Auto-discovered
│   ├── backend/.git     # ← Auto-discovered
│   └── shared/.git      # ← Auto-discovered
└── .git                 # ← Parent repo included

All 4 repos will be committed and pushed with a single /sw:save command!

Important Notes

1. Each repo is independent - Own .specweave/, own increments, own external tool sync
2. Parent repo is optional - Can have umbrella config or just independent repos
3. User stories MUST have project prefix - Never generate generic US-001 in multi-repo mode
4. Cross-project stories get special handling - Tagged and linked across repos
5. Use /sw:save - Single command to save changes across all repos

Project-Specific Learnings

Before starting work, check for project-specific learnings:

# Check if skill memory exists for this skill
cat .specweave/skill-memories/umbrella-repo-detector.md 2>/dev/null || echo "No project learnings yet"

Project learnings are automatically captured by the reflection system when corrections or patterns are identified during development. These learnings help you understand project-specific conventions and past decisions.