Multi-Project Spec Mapper - Intelligent Project Organization

Purpose: Automatically detect multiple projects in SpecWeave setup, analyze user stories to map them to the correct project (FE, BE, MOBILE, INFRA), and organize specs into project-specific folders with proper JIRA/GitHub sync.

When to Use:

•User has multiple JIRA projects configured (e.g., FE, BE, MOBILE)
•User has multiple GitHub repos to sync
•Brownfield projects with multiple teams/services
•Microservices architecture with separate frontend/backend/mobile codebases
•Need to split monolithic spec into project-specific specs

Key Capabilities:

•✅ Intelligent Project Detection - Analyze config.json to detect multi-project setup
•✅ User Story Classification - Map user stories to projects based on keywords, tech stack, components
•✅ Spec Splitting - Split monolithic specs into project-specific files
•✅ Folder Organization - Create specs/FE/, specs/BE/, specs/MOBILE/ structure
•✅ JIRA Item Type Mapping - Suggest Epic/Story/Task hierarchy based on scope
•✅ Bidirectional Sync - Configure hooks for GitHub/JIRA sync per project

How It Works

Step 1: Detect Multi-Project Setup

Check config.json for:

json

{
  "sync": {
    "profiles": {
      "jira-default": {
        "provider": "jira",
        "config": {
          "domain": "company.atlassian.net",
          "projects": ["FE", "BE", "MOBILE"]  // ← Multiple projects!
        }
      }
    }
  }
}

If multiple projects found → Activate multi-project mode

Step 2: Analyze User Stories

For each user story, analyze:

•Keywords: "UI", "chart", "API", "mobile", "database", "deployment"
•Tech Stack: "React", "Node.js", "React Native", "PostgreSQL", "Kubernetes"
•Components: "component", "service", "screen", "controller", "pipeline"

Example:

code

US-001: Log a Workout (Web UI)
→ Keywords: "UI", "web", "chart"
→ Tech: "React"
→ Project: FE (90% confidence)

US-002: View Workout History (API)
→ Keywords: "API", "endpoint", "database"
→ Tech: "Node.js", "PostgreSQL"
→ Project: BE (95% confidence)

US-005: Cross-Platform Data Sync (Mobile)
→ Keywords: "mobile", "offline", "sync"
→ Tech: "React Native"
→ Project: MOBILE (100% confidence)

Step 3: Create Project-Specific Specs

Folder Structure:

code

.specweave/docs/internal/specs/
├── FE/
│   ├── spec-0001-fitness-tracker-web.md
│   └── README.md
├── BE/
│   ├── spec-0001-fitness-tracker-api.md
│   └── README.md
├── MOBILE/
│   ├── spec-0001-fitness-tracker-mobile.md
│   └── README.md
└── SHARED/
    ├── spec-0001-fitness-tracker-shared.md  (cross-cutting concerns)
    └── README.md

spec.md YAML Frontmatter (MANDATORY):

yaml

# For 1-level structure (projects only)
---
increment: 0001-fitness-tracker-web
project: FE                      # REQUIRED
title: "Fitness Tracker Web UI"
status: planned
---

# For 2-level structure (projects + boards)
---
increment: 0001-fitness-tracker-web
project: acme-corp               # REQUIRED
board: digital-operations        # REQUIRED for 2-level
title: "Fitness Tracker Web UI"
status: planned
---

Detection: Use detectStructureLevel() from src/utils/structure-level-detector.ts

Each spec contains:

•YAML frontmatter with project: (and board: for 2-level) fields - MANDATORY
•User stories mapped to that project
•Project-specific acceptance criteria
•Links to shared infrastructure/requirements

Step 4: JIRA Sync with Project Mapping

Hierarchical JIRA Structure:

code

JIRA Project: FE
├── Epic: Fitness Tracker Web UI (SPEC-0001)
│   ├── Story: US-001: Log a Workout
│   │   ├── Task: T-001: Create Workout Form Component
│   │   ├── Task: T-002: Implement Exercise Search
│   │   └── Task: T-003: Add Set Logging UI
│   └── Story: US-004: Track Progress with Charts
│       ├── Task: T-010: Integrate Recharts Library
│       └── Task: T-011: Create Chart Components

JIRA Project: BE
├── Epic: Fitness Tracker API Backend (SPEC-0001)
│   ├── Story: US-002: View Workout History (API)
│   │   ├── Task: T-004: Create GET /api/workouts Endpoint
│   │   ├── Task: T-005: Implement Filtering Logic
│   │   └── Task: T-006: Add Pagination
│   └── Story: US-003: Manage Exercise Library (API)
│       ├── Task: T-007: Create Exercise CRUD Endpoints
│       └── Task: T-008: Implement Search

JIRA Project: MOBILE
├── Epic: Fitness Tracker Mobile App (SPEC-0001)
    └── Story: US-005: Cross-Platform Data Sync
        ├── Task: T-012: Implement Offline Mode (AsyncStorage)
        ├── Task: T-013: Create Sync Queue
        └── Task: T-014: Handle Conflict Resolution

Step 5: Configure Bidirectional Sync

GitHub Hooks (.specweave/config.json):

json

{
  "hooks": {
    "post_task_completion": {
      "sync_living_docs": true,
      "external_tracker_sync": true
    }
  },
  "sync": {
    "enabled": true,
    "activeProfile": "jira-default",
    "settings": {
      "autoCreateIssue": true,
      "syncDirection": "bidirectional",
      "projectMapping": {
        "FE": {
          "jiraProject": "FE",
          "jiraBoards": [123],
          "githubRepo": "company/frontend-web"
        },
        "BE": {
          "jiraProject": "BE",
          "jiraBoards": [456],
          "githubRepo": "company/backend-api"
        },
        "MOBILE": {
          "jiraProject": "MOBILE",
          "jiraBoards": [789],
          "githubRepo": "company/mobile-app"
        }
      }
    }
  }
}

Project Mapping Rules

Frontend (FE)

Keywords:

•UI/UX: button, form, input, page, view, screen, modal, dropdown
•Visualization: chart, graph, dashboard, widget
•Styling: CSS, theme, dark mode, responsive
•State: Redux, Zustand, context, state management

Tech Stack:

•React, Vue, Angular, Next.js, Svelte
•TypeScript, JavaScript
•Tailwind, Material-UI, Chakra, Ant Design
•Recharts, D3, Chart.js

Components:

•Component, hook, context, provider, page, layout

Confidence: 30%+ for primary match

Backend (BE)

Keywords:

•API: endpoint, REST, GraphQL, route
•Database: query, migration, schema, model
•Auth: authentication, JWT, session, token
•Processing: queue, job, worker, cron, batch

Tech Stack:

•Node.js (Express, Fastify, NestJS)
•Python (FastAPI, Django, Flask)
•Java (Spring Boot), .NET (ASP.NET)
•PostgreSQL, MySQL, MongoDB, Redis

Components:

•Controller, service, repository, middleware, handler

Confidence: 30%+ for primary match

Mobile (MOBILE)

Keywords:

•Mobile: native, iOS, Android, cross-platform
•Device: camera, GPS, push notification, offline
•Navigation: tab bar, drawer, stack, screen transition
•Storage: AsyncStorage, local database

Tech Stack:

•React Native, Expo, Flutter
•Swift, Kotlin
•React Navigation

Components:

•Screen, navigator, bottom-sheet, drawer

Exclude: "web" keyword (penalty)

Confidence: 30%+ for primary match

Infrastructure (INFRA)

Keywords:

•DevOps: deployment, CI/CD, Docker, Kubernetes
•Monitoring: logging, metrics, alerting, SLO
•Security: SSL, TLS, firewall, VPC
•Scalability: load balancing, CDN, backup

Tech Stack:

•AWS, Azure, GCP
•Kubernetes, Docker, Terraform
•Jenkins, GitHub Actions, GitLab CI
•Prometheus, Grafana, Datadog

Components:

•Pipeline, manifest, Helm chart, Terraform module

Confidence: 30%+ for primary match

JIRA Item Type Hierarchy

Epic (> 13 story points):

•Large feature area spanning multiple stories
•Example: "Fitness Tracker MVP" (29 story points total)

Story (3-13 story points):

•Standard user story with clear value
•Example: "US-001: Log a Workout" (8 story points)

Task (1-2 story points):

•Small implementation task
•Example: "T-001: Create Workout Form Component" (2 story points)

Subtask (< 1 story point):

•Granular work item
•Example: "Create POST /api/workouts endpoint" (0.5 story points)

Usage Examples

Example 1: Fitness Tracker (Multi-Project)

Input: Monolithic spec with 35 user stories

Detection:

code

✓ Multi-project setup detected:
  - FE (Frontend Web)
  - BE (Backend API)
  - MOBILE (React Native)

Classification:

code

Analyzing 35 user stories...
✓ US-001: Log a Workout → FE (90% confidence: React, UI, chart)
✓ US-002: View Workout History → BE (95% confidence: API, database, query)
✓ US-004: Track Progress with Charts → FE (100% confidence: Recharts, visualization)
✓ US-005: Cross-Platform Data Sync → MOBILE (100% confidence: React Native, offline)

Project Distribution:
- FE: 12 user stories (34%)
- BE: 15 user stories (43%)
- MOBILE: 6 user stories (17%)
- SHARED: 2 user stories (6%)

Output:

code

Creating project-specific specs...
✓ specs/FE/spec-0001-fitness-tracker-web.md (12 user stories)
✓ specs/BE/spec-0001-fitness-tracker-api.md (15 user stories)
✓ specs/MOBILE/spec-0001-fitness-tracker-mobile.md (6 user stories)
✓ specs/SHARED/spec-0001-fitness-tracker-shared.md (2 user stories)

JIRA Sync Configuration:
✓ FE → JIRA Project FE (Board 123)
✓ BE → JIRA Project BE (Board 456)
✓ MOBILE → JIRA Project MOBILE (Board 789)

Example 2: Microservices E-Commerce

Input: Spec for multi-service platform

Detection:

code

✓ Multi-project setup detected:
  - FRONTEND (Web storefront)
  - PRODUCT-SVC (Product service)
  - ORDER-SVC (Order service)
  - PAYMENT-SVC (Payment service)
  - INFRA (Kubernetes + monitoring)

Classification:

code

Analyzing 50 user stories...
✓ US-010: Product Catalog UI → FRONTEND (95%)
✓ US-011: Product Search API → PRODUCT-SVC (100%)
✓ US-020: Shopping Cart → ORDER-SVC (90%)
✓ US-030: Stripe Integration → PAYMENT-SVC (100%)
✓ US-040: Kubernetes Deployment → INFRA (100%)

Project Distribution:
- FRONTEND: 15 user stories
- PRODUCT-SVC: 12 user stories
- ORDER-SVC: 10 user stories
- PAYMENT-SVC: 8 user stories
- INFRA: 5 user stories

Configuration

Enable Multi-Project Mode in .specweave/config.json:

json

{
  "multiProject": {
    "enabled": true,
    "autoDetect": true,
    "customRules": {
      "FE": {
        "keywords": ["react", "ui", "chart"],
        "techStack": ["react", "typescript", "recharts"],
        "confidenceThreshold": 0.3
      }
    }
  }
}

Related Skills

•spec-generator: Creates comprehensive specs (uses this skill for multi-project splitting)
•increment-planner: Plans increments (uses this skill to assign work to projects)
•jira-sync: Syncs to JIRA (uses project mappings from this skill)
•github-sync: Syncs to GitHub (uses project mappings from this skill)

Based on: Increment 0020-multi-project-intelligent-sync

Project-Specific Learnings

Before starting work, check for project-specific learnings:

bash

# Check if skill memory exists for this skill
cat .specweave/skill-memories/multi-project-spec-mapper.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.