specweave 0.28.9 → 0.28.13

package/plugins/specweave/agents/pm/AGENT.md

@@ -437,6 +437,184 @@ graph TD
 
 ---
 
+## 🔀 Multi-Repo Project-Scoped User Stories (v0.28.8+)
+
+**⚠️ CRITICAL - MANDATORY CHECK BEFORE GENERATING ANY SPEC.MD!**
+
+### STEP 0: Multi-Project Detection (RUN FIRST!)
+
+**YOU MUST CHECK THIS BEFORE WRITING ANY USER STORIES:**
+
+```bash
+# 1. Check config.json for umbrella mode
+cat .specweave/config.json | jq '.umbrella.enabled'
+
+# 2. Check for childRepos
+cat .specweave/config.json | jq '.umbrella.childRepos[]'
+
+# 3. Check for project folders
+ls -la .specweave/docs/internal/specs/
+```
+
+**Decision Flow:**
+```
+Is umbrella.enabled: true?
+  → YES → MUST use project-scoped user stories (US-FE-001, US-BE-001)
+  → NO → Check for multiple project folders in specs/
+          → YES → MUST use project-scoped user stories
+          → NO → Use standard user stories (US-001, US-002)
+```
+
+**If multi-project detected, NEVER generate:**
+- ❌ `US-001`, `US-002` (generic format)
+- ❌ `AC-US1-01`, `AC-US2-01` (generic AC format)
+
+**ALWAYS generate:**
+- ✅ `US-FE-001`, `US-BE-001`, `US-SHARED-001` (project-scoped)
+- ✅ `AC-FE-US1-01`, `AC-BE-US1-01` (project-scoped ACs)
+
+---
+
+### Detection Patterns
+
+Detect multi-repo intent when user mentions:
+- **Explicit repos**: "3 repos", "multiple repos", "separate repos"
+- **Repo types**: "Frontend repo", "Backend API repo", "Shared library"
+- **Architecture patterns**: "monorepo with services", "microservices"
+- **Tech stack splits**: React frontend + Node backend + Shared types
+- **GitHub URLs**: Multiple github.com/... URLs
+
+### User Story Prefixing Rules (MANDATORY!)
+
+**When multi-repo detected, NEVER generate generic `US-001`!**
+
+| Repo Type | Prefix | Detection Keywords |
+|-----------|--------|-------------------|
+| Frontend | `FE` | UI, component, page, form, view, theme, drag-drop, builder, menu display |
+| Backend | `BE` | API, endpoint, CRUD, webhook, notification, analytics, database, service |
+| Shared | `SHARED` | validator, schema, types, utilities, localization, common, helpers |
+| Mobile | `MOBILE` | iOS, Android, mobile app, push notification, native |
+| Infrastructure | `INFRA` | Terraform, K8s, Docker, CI/CD, deployment |
+
+### Example: Generic vs Project-Scoped
+
+**❌ WRONG (Generic - for single-repo only)**:
+```markdown
+## User Stories
+
+### US-001: User Registration
+As a user, I want to register...
+
+### US-002: Registration API
+As a system, I want to process registrations...
+
+### US-003: Validation Schema
+As a developer, I want shared validation...
+```
+
+**✅ CORRECT (Project-Scoped - for multi-repo)**:
+```markdown
+## User Stories
+
+### US-FE-001: User Registration Form
+**Related Repo**: frontend
+As a user, I want to fill out the registration form...
+
+### US-BE-001: Registration API Endpoint
+**Related Repo**: backend
+As a system, I want to process POST /api/register...
+
+### US-SHARED-001: Registration Validation Schema
+**Related Repo**: shared
+As a developer, I want reusable validation schemas...
+```
+
+### Acceptance Criteria Also Prefixed
+
+```markdown
+### US-FE-001: Menu Builder Interface
+
+**Acceptance Criteria**:
+- [ ] **AC-FE-US1-01**: Drag-drop menu item ordering
+  - Priority: P0 (Critical)
+  - Testable: Yes
+- [ ] **AC-FE-US1-02**: Category management UI
+  - Priority: P0 (Critical)
+  - Testable: Yes
+
+### US-BE-001: Menu CRUD API
+
+**Acceptance Criteria**:
+- [ ] **AC-BE-US1-01**: POST /api/menus creates menu
+  - Priority: P0 (Critical)
+  - Testable: Yes
+- [ ] **AC-BE-US1-02**: GET /api/menus/:id returns menu
+  - Priority: P0 (Critical)
+  - Testable: Yes
+```
+
+### Cross-Cutting User Stories
+
+For features that span multiple repos (auth, shared state):
+
+```markdown
+### US-AUTH-001: OAuth Integration (Cross-Project)
+**Related Repos**: frontend, backend
+**Tags**: ["cross-project", "auth"]
+
+**Child Stories**:
+- US-FE-002: OAuth Login Button (frontend)
+- US-BE-002: OAuth Token Validation (backend)
+- US-SHARED-002: OAuth Types (shared)
+
+As a user, I want to log in with Google OAuth...
+```
+
+### Workflow in Multi-Repo Mode
+
+1. **Detect** multi-repo intent from user prompt
+2. **Confirm** with user: "I detected FE/BE/Shared architecture. Should I create project-scoped user stories?"
+3. **Generate** prefixed user stories: US-FE-*, US-BE-*, US-SHARED-*
+4. **Route** stories to correct increment in each repo
+5. **Sync** to each repo's own GitHub issues
+
+### Config Check (Optional)
+
+If `.specweave/config.json` has umbrella config:
+```json
+{
+  "umbrella": {
+    "enabled": true,
+    "childRepos": [
+      { "id": "sw-app-fe", "prefix": "FE" },
+      { "id": "sw-app-be", "prefix": "BE" },
+      { "id": "sw-app-shared", "prefix": "SHARED" }
+    ]
+  }
+}
+```
+
+**ID Strategy**: `id` MUST match repo name (e.g., `sw-app-fe`), NOT arbitrary abbreviations (`fe`).
+The `prefix` (for user stories like `US-FE-001`) can be short.
+
+Use these prefixes for user stories. If no config, infer from user prompt.
+
+### Why This Matters
+
+Without project-scoped stories:
+- ❌ All issues created in ONE repo (wrong!)
+- ❌ No clarity which team owns what
+- ❌ Cross-project dependencies unclear
+- ❌ Frontend dev sees backend tasks in their repo
+
+With project-scoped stories:
+- ✅ Each repo gets only its user stories
+- ✅ Clear ownership per team/repo
+- ✅ GitHub issues in correct repo
+- ✅ Clean separation of concerns
+
+---
+
 **Role**: Product Manager specialized in product strategy, requirements gathering, and feature prioritization.
 
 ## Purpose

package/plugins/specweave/agents/test-aware-planner/AGENT.md

@@ -125,6 +125,60 @@ The test-aware-planner agent is responsible for generating `tasks.md` with **emb
 
 **CRITICAL**: v0.23.0+ requires hierarchical structure grouped by User Story.
 
+### ⚠️ Multi-Project Mode Detection (v0.29.0+)
+
+**BEFORE generating tasks, check for multi-project mode:**
+
+```bash
+# Check if multi-project mode is active
+cat .specweave/config.json | jq '.umbrella.enabled'
+```
+
+**If multi-project detected:**
+- User stories will have prefixes: `US-FE-001`, `US-BE-001`, `US-SHARED-001`
+- AC-IDs will have prefixes: `AC-FE-US1-01`, `AC-BE-US1-01`
+- **Match the format from spec.md exactly!**
+
+### Single-Project Format (umbrella.enabled: false)
+
+```markdown
+## User Story: US-001 - User Story Title
+
+**Linked ACs**: AC-US1-01, AC-US1-02, AC-US1-03
+**Tasks**: X total, 0 completed
+```
+
+### Multi-Project Format (umbrella.enabled: true)
+
+```markdown
+## Phase 1: Shared Library (sw-app-shared)
+
+### User Story: US-SHARED-001 - Common Types & Validators
+
+**Linked ACs**: AC-SHARED-US1-01, AC-SHARED-US1-02
+**Tasks**: X total, 0 completed
+
+---
+
+## Phase 2: Backend (sw-app-be)
+
+### User Story: US-BE-001 - API Endpoints
+
+**Linked ACs**: AC-BE-US1-01, AC-BE-US1-02
+**Tasks**: X total, 0 completed
+
+---
+
+## Phase 3: Frontend (sw-app-fe)
+
+### User Story: US-FE-001 - UI Components
+
+**Linked ACs**: AC-FE-US1-01, AC-FE-US1-02
+**Tasks**: X total, 0 completed
+```
+
+---
+
 Each task in `tasks.md` follows this format:
 
 ```markdown

package/plugins/specweave/commands/specweave-increment.md

@@ -372,6 +372,36 @@ Proceeding with hotfix 0006...
 - Find highest number across both directories (e.g., 032)
 - Next increment: 033
 
+### Step 1.5: Detect Multi-Project Mode (CRITICAL!)
+
+**⚠️ MANDATORY CHECK before generating spec.md:**
+
+```bash
+# Check for umbrella configuration
+UMBRELLA_ENABLED=$(cat .specweave/config.json 2>/dev/null | jq -r '.umbrella.enabled // false')
+CHILD_REPOS=$(cat .specweave/config.json 2>/dev/null | jq -r '.umbrella.childRepos[]?.id // empty' | tr '\n' ',')
+PROJECT_FOLDERS=$(ls -1 .specweave/docs/internal/specs/ 2>/dev/null | grep -v "^_" | head -5)
+```
+
+**If multi-project detected:**
+```
+📁 Multi-Project Mode Detected!
+
+Child Repos:
+  • FE: sw-thumbnail-ab-fe
+  • BE: sw-thumbnail-ab-be
+  • SHARED: sw-thumbnail-ab-shared
+
+User stories will be generated with project prefixes:
+  • US-FE-001, US-FE-002 (Frontend stories)
+  • US-BE-001, US-BE-002 (Backend stories)
+  • US-SHARED-001 (Shared library stories)
+
+Each story will include "Related Repo" field for clarity.
+```
+
+**Pass this context to increment-planner skill!**
+
 ### Step 2: Detect tech stack (CRITICAL - framework-agnostic)
    - Settings auto-detected
    - If not found, detect from project files: