specweave 0.28.11 → 0.28.13

package/plugins/specweave/hooks/lib/update-status-line.sh

@@ -58,9 +58,17 @@ fi
 # ============================================================================
 # TTL CHECK (10 seconds - balanced for UX vs performance)
 # ============================================================================
+# TTL check (skip if --force flag provided or SPECWEAVE_FORCE_STATUS_UPDATE=1)
+# ============================================================================
 TTL_SECONDS=10
+FORCE_UPDATE=0
+
+# Check for --force flag
+if [[ "${1:-}" == "--force" ]] || [[ "${SPECWEAVE_FORCE_STATUS_UPDATE:-0}" == "1" ]]; then
+  FORCE_UPDATE=1
+fi
 
-if [[ -f "$CACHE_FILE" ]]; then
+if [[ "$FORCE_UPDATE" -eq 0 ]] && [[ -f "$CACHE_FILE" ]]; then
   if [[ "$(uname)" == "Darwin" ]]; then
     CACHE_AGE=$(( $(date +%s) - $(stat -f %m "$CACHE_FILE" 2>/dev/null || echo 0) ))
   else

package/plugins/specweave/hooks/post-increment-completion.sh

@@ -21,8 +21,8 @@ if [ -z "$INCREMENT_ID" ]; then
   exit 0
 fi
 
-# Get project root
-PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../.." && pwd)"
+# Get project root (3 levels up from plugins/specweave/hooks/)
+PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
 INCREMENT_DIR="$PROJECT_ROOT/.specweave/increments/$INCREMENT_ID"
 
 # ============================================================================
@@ -135,6 +135,7 @@ if [ -f "$SPEC_FILE" ]; then
   echo "🔄 Syncing spec.md status to 'completed'..."
 
   # Read current status from spec.md frontmatter
+  # Use heredoc to avoid quote escaping issues in awk
   SPEC_STATUS=$(awk '
     BEGIN { in_frontmatter=0 }
     /^---$/ {
@@ -146,7 +147,7 @@ if [ -f "$SPEC_FILE" ]; then
     }
     in_frontmatter == 1 && /^status:/ {
       gsub(/^status:[ \t]*/, "");
-      gsub(/["'\''']/, "");
+      gsub(/["'"'"']/, "");
       print;
       exit
     }

package/plugins/specweave/hooks/post-metadata-change.sh

@@ -170,6 +170,20 @@ CURRENT_STATUS=$(jq -r '.status // "unknown"' "$METADATA_PATH" 2>/dev/null)
 
 echo "[$(date)] post-metadata-change: Current status: $CURRENT_STATUS" >> "$DEBUG_LOG" 2>/dev/null || true
 
+# ============================================================================
+# CRITICAL FIX (v0.28.12): Remove guard BEFORE calling sub-hooks
+# ============================================================================
+# PROBLEM: Sub-hooks (post-increment-completion.sh) check for recursion guard
+# and exit immediately if it exists. But the guard was created HERE (line 77),
+# so sub-hooks NEVER ran - causing status line to never update!
+#
+# SOLUTION: Temporarily remove the guard before calling sub-hooks.
+# The guard's purpose is to prevent THIS hook from being called recursively
+# (if sub-hooks modify metadata.json). Sub-hooks have their OWN guards.
+#
+# See: Root cause analysis 2025-11-25 - status line never updates after /done
+rm -f "$RECURSION_GUARD_FILE" 2>/dev/null || true
+
 # Dispatch to appropriate lifecycle hook based on status
 case "$CURRENT_STATUS" in
   completed)
@@ -186,9 +200,9 @@ case "$CURRENT_STATUS" in
       }
     else
       echo "[$(date)] post-metadata-change: post-increment-completion.sh not found or not executable" >> "$DEBUG_LOG" 2>/dev/null || true
-      # Fallback: Update status line directly
-      bash "$HOOK_DIR/lib/update-status-line.sh" 2>/dev/null || true
     fi
+    # ALWAYS update status line after completion (force bypass TTL cache)
+    bash "$HOOK_DIR/lib/update-status-line.sh" --force 2>/dev/null || true
     ;;
 
   paused|resumed|abandoned)
@@ -205,9 +219,9 @@ case "$CURRENT_STATUS" in
       }
     else
       echo "[$(date)] post-metadata-change: post-increment-status-change.sh not found" >> "$DEBUG_LOG" 2>/dev/null || true
-      # Fallback: Update status line directly
-      bash "$HOOK_DIR/lib/update-status-line.sh" 2>/dev/null || true
     fi
+    # ALWAYS update status line after status change (force bypass TTL cache)
+    bash "$HOOK_DIR/lib/update-status-line.sh" --force 2>/dev/null || true
     ;;
 
   active|planning|in-progress)

package/plugins/specweave/skills/increment-planner/SKILL.md

@@ -130,9 +130,45 @@ Every increment MUST have `metadata.json` or:
 
 ## Workflow (Safe, Self-Contained)
 
-### STEP 0: Read Config Values (MANDATORY)
+### STEP 0: Detect Multi-Project Mode (MANDATORY FIRST!)
 
-**Read testing configuration from `.specweave/config.json`**:
+**⚠️ CRITICAL: Before creating ANY user stories, detect if this is a multi-project (umbrella) setup!**
+
+```bash
+# 1. Check config.json for umbrella mode
+UMBRELLA_ENABLED=$(cat .specweave/config.json 2>/dev/null | jq -r '.umbrella.enabled // false')
+
+# 2. Check for childRepos
+CHILD_REPOS=$(cat .specweave/config.json 2>/dev/null | jq -r '.umbrella.childRepos[]?.id // empty' | tr '\n' ',')
+
+# 3. Check for project folders in specs/
+PROJECT_FOLDERS=$(ls -1 .specweave/docs/internal/specs/ 2>/dev/null | grep -v "^_" | head -5)
+
+echo "Multi-project mode: $UMBRELLA_ENABLED"
+echo "Child repos: $CHILD_REPOS"
+echo "Project folders: $PROJECT_FOLDERS"
+```
+
+**If multi-project detected (`umbrella.enabled: true` OR multiple project folders exist):**
+- ✅ **MUST** generate project-scoped user stories: `US-FE-001`, `US-BE-001`, `US-SHARED-001`
+- ✅ **MUST** use project-scoped AC-IDs: `AC-FE-US1-01`, `AC-BE-US1-01`
+- ✅ **MUST** group user stories by project in spec.md
+- ✅ **MUST** infer project from repo name if available (e.g., `sw-app-fe` → FE, `sw-app-be` → BE)
+
+**Project Prefix Detection from Repo Names:**
+```
+sw-thumbnail-ab-fe     → prefix: FE (frontend)
+sw-thumbnail-ab-be     → prefix: BE (backend)
+sw-thumbnail-ab-shared → prefix: SHARED (shared library)
+my-app-mobile          → prefix: MOBILE (mobile app)
+infra-terraform        → prefix: INFRA (infrastructure)
+```
+
+**Store this for use in STEP 4 (spec.md generation)!**
+
+---
+
+### STEP 0A: Read Config Values (MANDATORY)
 
 ```bash
 # Read testMode (default: "TDD")
@@ -178,6 +214,10 @@ mkdir -p .specweave/increments/0021-feature-name
 
 Create `.specweave/increments/0021-feature-name/spec.md`:
 
+**⚠️ IMPORTANT: Use the correct template based on STEP 0 detection!**
+
+#### 4A: Single-Project Template (umbrella.enabled: false)
+
 ```markdown
 ---
 increment: 0021-feature-name
@@ -231,6 +271,110 @@ coverage_target: <VALUE FROM config.testing.defaultCoverageTarget OR 95>
 [Other features or systems this depends on]
 ```
 
+#### 4B: Multi-Project Template (umbrella.enabled: true) - USE THIS!
+
+```markdown
+---
+increment: 0021-feature-name
+title: "Feature Name"
+type: feature
+priority: P1
+status: planned
+created: 2025-11-24
+structure: user-stories
+test_mode: <VALUE FROM config.testing.defaultTestMode OR 'TDD'>
+coverage_target: <VALUE FROM config.testing.defaultCoverageTarget OR 95>
+multi_project: true
+projects:
+  - id: sw-app-fe
+    prefix: FE
+  - id: sw-app-be
+    prefix: BE
+  - id: sw-app-shared
+    prefix: SHARED
+---
+
+# Feature: [Title]
+
+## Overview
+
+[High-level description - WHAT this feature does and WHY it's needed]
+
+## User Stories by Project
+
+### Frontend ([repo-name-fe])
+
+#### US-FE-001: [Story Title] (P1)
+**Related Repo**: [repo-name-fe]
+**As a** [user type]
+**I want** [goal]
+**So that** [benefit]
+
+**Acceptance Criteria**:
+- [ ] **AC-FE-US1-01**: [Specific, testable criterion]
+- [ ] **AC-FE-US1-02**: [Another criterion]
+
+#### US-FE-002: [Story Title] (P2)
+[Repeat structure with FE prefix]
+
+---
+
+### Backend ([repo-name-be])
+
+#### US-BE-001: [Story Title] (P1)
+**Related Repo**: [repo-name-be]
+**As a** [system/frontend application]
+**I want** [API endpoint/service goal]
+**So that** [benefit]
+
+**Acceptance Criteria**:
+- [ ] **AC-BE-US1-01**: [API endpoint specification]
+- [ ] **AC-BE-US1-02**: [Data validation rule]
+
+#### US-BE-002: [Story Title] (P2)
+[Repeat structure with BE prefix]
+
+---
+
+### Shared Library ([repo-name-shared])
+
+#### US-SHARED-001: [Story Title] (P1)
+**Related Repo**: [repo-name-shared]
+**As a** developer in FE or BE repos
+**I want** [shared types/utilities/validators]
+**So that** [consistency across projects]
+
+**Acceptance Criteria**:
+- [ ] **AC-SHARED-US1-01**: [Type definition]
+- [ ] **AC-SHARED-US1-02**: [Validator/utility function]
+
+---
+
+## Functional Requirements
+
+### FR-001: [Requirement]
+[Detailed description]
+
+## Success Criteria
+
+[Measurable outcomes - metrics, KPIs]
+
+## Out of Scope
+
+[What this explicitly does NOT include]
+
+## Dependencies
+
+[Other features or systems this depends on]
+```
+
+**Key Rules for Multi-Project spec.md:**
+1. **User stories MUST be grouped by project** (Frontend, Backend, Shared, etc.)
+2. **User story IDs MUST have project prefix**: `US-FE-001`, `US-BE-001`, `US-SHARED-001`
+3. **AC-IDs MUST have project prefix**: `AC-FE-US1-01`, `AC-BE-US1-01`
+4. **Each user story MUST have `Related Repo` field**
+5. **Frontmatter MUST include `multi_project: true` and `projects` list**
+
 ### STEP 5: Create plan.md Template
 
 Create `.specweave/increments/0021-feature-name/plan.md`:
@@ -292,6 +436,10 @@ Create `.specweave/increments/0021-feature-name/plan.md`:
 
 Create `.specweave/increments/0021-feature-name/tasks.md`:
 
+**⚠️ IMPORTANT: Use the correct template based on STEP 0 detection!**
+
+#### 6A: Single-Project Template
+
 ```markdown
 # Tasks: [Feature Title]
 
@@ -343,6 +491,108 @@ Create `.specweave/increments/0021-feature-name/tasks.md`:
 - [ ] [T051] Verify all acceptance criteria
 ```
 
+#### 6B: Multi-Project Template (umbrella.enabled: true) - USE THIS!
+
+```markdown
+# Tasks: [Feature Title]
+
+## Task Notation
+
+- `[T###]`: Task ID
+- `[P]`: Parallelizable
+- `[ ]`: Not started
+- `[x]`: Completed
+- Model hints: ⚡ haiku, 🧠 sonnet, 💎 opus
+
+## Phase 1: Foundation & Setup
+
+### T-001: Initialize Shared Library (sw-app-shared)
+**User Story**: US-SHARED-001
+**Satisfies ACs**: AC-SHARED-US1-01, AC-SHARED-US1-02
+**Status**: [ ] Not Started
+
+**Description**: Set up shared TypeScript types and validators
+
+**Implementation**:
+- Create shared types package
+- Export common interfaces and types
+- Add validation schemas
+
+**Test Plan**:
+- **File**: `sw-app-shared/tests/types.test.ts`
+- **Tests**:
+  - **TC-001**: Type exports compile correctly
+
+---
+
+## Phase 2: Backend Implementation (sw-app-be)
+
+### T-002: Database Schema & Models
+**User Story**: US-BE-001
+**Satisfies ACs**: AC-BE-US1-01, AC-BE-US1-02
+**Status**: [ ] Not Started
+
+**Description**: Create database schema for backend service
+
+**Implementation**:
+- Define Prisma/TypeORM models
+- Run migrations
+- Seed initial data
+
+**Test Plan**:
+- **File**: `sw-app-be/tests/models.test.ts`
+- **Tests**:
+  - **TC-002**: Models create correctly
+  - **TC-003**: Relationships work
+
+### T-003: API Endpoints
+**User Story**: US-BE-001, US-BE-002
+**Satisfies ACs**: AC-BE-US1-01, AC-BE-US2-01
+**Status**: [ ] Not Started
+
+**Description**: Implement REST API endpoints
+
+---
+
+## Phase 3: Frontend Implementation (sw-app-fe)
+
+### T-004: UI Components
+**User Story**: US-FE-001
+**Satisfies ACs**: AC-FE-US1-01, AC-FE-US1-02
+**Status**: [ ] Not Started
+
+**Description**: Build frontend components
+
+**Implementation**:
+- Create upload component
+- Add comparison view
+- Wire up to backend API
+
+**Test Plan**:
+- **File**: `sw-app-fe/tests/components.test.tsx`
+- **Tests**:
+  - **TC-004**: Component renders correctly
+  - **TC-005**: Upload triggers validation
+
+---
+
+## Phase 4: Integration & Testing
+
+### T-005: End-to-End Tests
+**User Story**: US-FE-001, US-BE-001
+**Satisfies ACs**: (all FE and BE ACs)
+**Status**: [ ] Not Started
+
+**Description**: E2E tests across all projects
+```
+
+**Key Rules for Multi-Project tasks.md:**
+1. **Tasks MUST reference project-scoped user stories**: `US-FE-001`, `US-BE-001`
+2. **Tasks MUST reference project-scoped ACs**: `AC-FE-US1-01`, `AC-BE-US1-01`
+3. **Group tasks by project/phase** (Shared first, then BE, then FE)
+4. **Test file paths MUST include project folder**: `sw-app-be/tests/`, `sw-app-fe/tests/`
+5. **Dependencies between projects should be explicit**
+
 ### STEP 7: Create metadata.json (MANDATORY)
 
 **IMPORTANT**: Read `testMode` and `coverageTarget` from `.specweave/config.json`:

package/plugins/specweave/skills/spec-generator/SKILL.md

@@ -46,6 +46,12 @@ description: Generates comprehensive specifications (spec.md, plan.md, tasks.md
 ### Target Audience
 
 ## User Stories & Acceptance Criteria
+
+<!--
+⚠️ MULTI-PROJECT MODE: If umbrella.enabled=true in config.json,
+   user stories MUST be project-scoped! See section below.
+-->
+
 ### US-001: [Title]
 **As a** [user type]
 **I want** [goal]
@@ -348,15 +354,172 @@ spec_generator:
 
 ---
 
+## 🔀 Multi-Project User Story Generation (v0.29.0+)
+
+**CRITICAL**: When umbrella/multi-project mode is detected, user stories MUST be generated per-project!
+
+### Detection (MANDATORY FIRST STEP)
+
+**Before generating spec.md, ALWAYS check for multi-project mode:**
+
+```bash
+# 1. Check config.json for umbrella mode
+cat .specweave/config.json | jq '.umbrella.enabled'
+
+# 2. Check for childRepos configuration
+cat .specweave/config.json | jq '.umbrella.childRepos[]'
+
+# 3. Check for project folders in specs/
+ls -la .specweave/docs/internal/specs/
+```
+
+**If ANY of these conditions are TRUE → Multi-project mode ACTIVE:**
+- `umbrella.enabled: true` in config.json
+- `umbrella.childRepos` has entries
+- Multiple project folders exist in `specs/` (e.g., `sw-app-fe/`, `sw-app-be/`, `sw-app-shared/`)
+- User prompt mentions: "3 repos", "frontend repo", "backend API", "shared library"
+
+### Project-Scoped User Story Format (MANDATORY in Multi-Project Mode)
+
+**❌ WRONG (Single-Project Format - DO NOT USE in multi-project!):**
+```markdown
+## User Stories
+
+### US-001: Thumbnail Upload
+As a content creator, I want to upload thumbnails...
+
+### US-002: CTR Prediction API
+As a system, I want to predict click-through rates...
+```
+
+**✅ CORRECT (Multi-Project Format - ALWAYS USE when umbrella detected!):**
+```markdown
+## User Stories by Project
+
+### Frontend (sw-thumbnail-ab-fe)
+
+#### US-FE-001: Thumbnail Upload & Comparison (P1)
+**Related Repo**: sw-thumbnail-ab-fe
+**As a** content creator
+**I want** to upload multiple thumbnail variants and compare them side-by-side
+**So that** I can visually evaluate my options before testing
+
+**Acceptance Criteria**:
+- [ ] **AC-FE-US1-01**: User can drag-and-drop up to 5 thumbnail images (JPG, PNG, WebP)
+- [ ] **AC-FE-US1-02**: Images are validated for YouTube specs (1280x720 min, <2MB)
+- [ ] **AC-FE-US1-03**: Side-by-side comparison view displays all variants
+
+---
+
+### Backend (sw-thumbnail-ab-be)
+
+#### US-BE-001: Thumbnail Analysis API (P1)
+**Related Repo**: sw-thumbnail-ab-be
+**As a** frontend application
+**I want** to call POST /predict-ctr endpoint
+**So that** I can get AI-powered click-through rate predictions
+
+**Acceptance Criteria**:
+- [ ] **AC-BE-US1-01**: POST /predict-ctr endpoint accepts thumbnail image
+- [ ] **AC-BE-US1-02**: ML model analyzes: face detection, text readability, color psychology
+
+---
+
+### Shared Library (sw-thumbnail-ab-shared)
+
+#### US-SHARED-001: Common Types & Validators (P1)
+**Related Repo**: sw-thumbnail-ab-shared
+**As a** developer in FE or BE repos
+**I want** shared TypeScript types and validators
+**So that** API contracts are consistent across projects
+
+**Acceptance Criteria**:
+- [ ] **AC-SHARED-US1-01**: ThumbnailMetadata type exported
+- [ ] **AC-SHARED-US1-02**: Validation schemas for image specs
+```
+
+### Project Classification Rules
+
+When analyzing user descriptions, classify each user story by keywords:
+
+| Keywords | Project | Prefix |
+|----------|---------|--------|
+| UI, component, page, form, view, drag-drop, theme, builder, menu display | Frontend | FE |
+| API, endpoint, CRUD, webhook, analytics, database, service, ML model | Backend | BE |
+| types, schemas, validators, utilities, localization, common | Shared | SHARED |
+| iOS, Android, mobile app, push notification | Mobile | MOBILE |
+| Terraform, K8s, Docker, CI/CD, deployment | Infrastructure | INFRA |
+
+### AC-ID Format by Project
+
+```
+AC-{PROJECT}-US{story}-{number}
+
+Examples:
+- AC-FE-US1-01 (Frontend, User Story 1, AC #1)
+- AC-BE-US1-01 (Backend, User Story 1, AC #1)
+- AC-SHARED-US1-01 (Shared, User Story 1, AC #1)
+- AC-MOBILE-US1-01 (Mobile, User Story 1, AC #1)
+```
+
+### tasks.md Must Reference Project-Scoped User Stories
+
+```markdown
+### T-001: Create Thumbnail Upload Component
+**User Story**: US-FE-001           ← MUST reference project-scoped ID!
+**Satisfies ACs**: AC-FE-US1-01, AC-FE-US1-02
+**Status**: [ ] Not Started
+
+### T-004: Database Schema & Migrations
+**User Story**: US-BE-001, US-BE-002   ← Backend stories only!
+**Satisfies ACs**: AC-BE-US1-01, AC-BE-US2-01
+**Status**: [ ] Not Started
+```
+
+### Workflow Summary
+
+```
+1. DETECT multi-project mode (check config.json, folder structure)
+   ↓
+2. If multi-project → Group user stories by project (FE/BE/SHARED/MOBILE/INFRA)
+   ↓
+3. Generate prefixed user stories: US-FE-001, US-BE-001, US-SHARED-001
+   ↓
+4. Generate prefixed ACs: AC-FE-US1-01, AC-BE-US1-01
+   ↓
+5. Generate tasks referencing correct project user stories
+   ↓
+6. Each project folder gets its own filtered spec
+```
+
+### Why This Matters
+
+Without project-scoped stories:
+- ❌ All issues created in ONE repo (wrong!)
+- ❌ No clarity which team owns what
+- ❌ Tasks reference wrong user stories
+- ❌ GitHub sync broken across repos
+
+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
+
+---
+
 ## Related Skills
 
 - **Planning workflow**: Guides increment planning (uses Spec Generator internally)
 - **Context loading**: Loads relevant context for specification generation
 - **Quality validation**: Validates generated specifications for completeness
+- **multi-project-spec-mapper**: Splits specs into project-specific files
+- **umbrella-repo-detector**: Detects multi-repo architecture
 
 ---
 
 ## Version History
 
+- **v2.0.0** (0.29.0): Added multi-project user story generation support
 - **v1.0.0** (0.8.0): Initial release with flexible template system
 - Based on: Flexible Spec Generator (V2) - context-aware, non-rigid templates

package/plugins/specweave/skills/umbrella-repo-detector/SKILL.md

@@ -122,6 +122,32 @@ umbrella-project/                 # Optional parent repo
         └── ...                  # sync → my-app-shared GitHub issues
 ```
 
+## Project ID Strategy
+
+**CRITICAL**: The `id` field MUST match your canonical source name - no arbitrary abbreviations!
+
+| Scenario | ID Source | Example |
+|----------|-----------|---------|
+| **1:1 Repo Mapping** | Exact repo name | `sw-qr-menu-fe` |
+| **JIRA Project** | Project key (lowercase) | `WEBAPP` → `webapp` |
+| **ADO Project** | Project name (kebab-case) | `Frontend Team` → `frontend-team` |
+| **Area Path** | Last segment (kebab-case) | `Product\Web` → `web` |
+
+```
+✅ 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`):
@@ -131,33 +157,51 @@ umbrella-project/                 # Optional parent repo
     "enabled": true,
     "childRepos": [
       {
-        "id": "fe",
-        "path": "./my-app-fe",
+        "id": "sw-qr-menu-fe",
+        "path": "./sw-qr-menu-fe",
         "prefix": "FE",
-        "githubUrl": "https://github.com/myorg/my-app-fe"
+        "githubUrl": "https://github.com/myorg/sw-qr-menu-fe"
       },
       {
-        "id": "be",
-        "path": "./my-app-be",
+        "id": "sw-qr-menu-be",
+        "path": "./sw-qr-menu-be",
         "prefix": "BE",
-        "githubUrl": "https://github.com/myorg/my-app-be"
+        "githubUrl": "https://github.com/myorg/sw-qr-menu-be"
       },
       {
-        "id": "shared",
-        "path": "./my-app-shared",
+        "id": "sw-qr-menu-shared",
+        "path": "./sw-qr-menu-shared",
         "prefix": "SHARED",
-        "githubUrl": "https://github.com/myorg/my-app-shared"
+        "githubUrl": "https://github.com/myorg/sw-qr-menu-shared"
+      }
+    ]
+  }
+}
+```
+
+**JIRA-based project** (when JIRA is source of truth):
+```json
+{
+  "umbrella": {
+    "enabled": true,
+    "childRepos": [
+      {
+        "id": "webapp",
+        "path": "./frontend",
+        "prefix": "WEBAPP",
+        "jiraProject": "WEBAPP",
+        "githubUrl": "https://github.com/myorg/frontend"
       }
     ]
   }
 }
 ```
 
-**Child repo config** (`my-app-fe/.specweave/config.json`):
+**Child repo config** (`sw-qr-menu-fe/.specweave/config.json`):
 ```json
 {
   "project": {
-    "name": "My App Frontend",
+    "name": "QR Menu Frontend",
     "prefix": "FE"
   },
   "sync": {
@@ -167,7 +211,7 @@ umbrella-project/                 # Optional parent repo
         "provider": "github",
         "config": {
           "owner": "myorg",
-          "repo": "my-app-fe"
+          "repo": "sw-qr-menu-fe"
         }
       }
     }
@@ -211,9 +255,32 @@ Which would you like to do?
 | iOS, Android, mobile, push notification | Mobile | MOBILE |
 | Terraform, K8s, Docker, CI/CD | Infrastructure | INFRA |
 
+## Saving Changes Across Repos
+
+Use `/specweave:save` to commit and push changes across all repos at once:
+
+```bash
+# Save all repos with same commit message
+/specweave:save "feat: Add user authentication"
+
+# Preview what would happen
+/specweave:save --dry-run
+
+# Save specific repos only
+/specweave:save "fix: Bug fixes" --repos frontend,backend
+```
+
+**Features:**
+- 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
+
 ## 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 `/specweave:save`** - Single command to save changes across all repos