specweave 0.30.19 → 0.32.2

package/plugins/specweave/scripts/update-dashboard-cache.sh

@@ -0,0 +1,281 @@
+#!/usr/bin/env bash
+# update-dashboard-cache.sh - Incremental update of dashboard cache
+#
+# Usage: bash update-dashboard-cache.sh <incrementId> <changeType>
+#
+# Arguments:
+#   incrementId  - Increment ID (e.g., "0117-instant-dashboard-cache")
+#   changeType   - Type of change: metadata|tasks|spec|jobs
+#
+# Updates only the affected increment in the cache, not a full rebuild.
+# Uses file locking for concurrent safety.
+#
+# Compatible with bash 3.x (macOS default)
+
+set -e
+
+INCREMENT_ID="${1:-}"
+CHANGE_TYPE="${2:-}"
+
+if [[ -z "$INCREMENT_ID" ]]; then
+  echo "❌ Usage: update-dashboard-cache.sh <incrementId> <changeType>"
+  exit 1
+fi
+
+# Find project root
+PROJECT_ROOT="$PWD"
+while [[ "$PROJECT_ROOT" != "/" ]] && [[ ! -d "$PROJECT_ROOT/.specweave" ]]; do
+  PROJECT_ROOT=$(dirname "$PROJECT_ROOT")
+done
+
+if [[ ! -d "$PROJECT_ROOT/.specweave" ]]; then
+  echo "❌ No .specweave directory found"
+  exit 1
+fi
+
+INCREMENTS_DIR="$PROJECT_ROOT/.specweave/increments"
+STATE_DIR="$PROJECT_ROOT/.specweave/state"
+CACHE_FILE="$STATE_DIR/dashboard.json"
+LOCK_FILE="$STATE_DIR/.dashboard.lock"
+TEMP_FILE="$STATE_DIR/.dashboard.json.tmp.$$"
+
+# Check if jq is available
+if ! command -v jq >/dev/null 2>&1; then
+  echo "❌ jq is required. Install with: brew install jq"
+  exit 1
+fi
+
+# Acquire file lock (with timeout)
+acquire_lock() {
+  local timeout=5
+  local count=0
+  while [[ -f "$LOCK_FILE" ]] && [[ $count -lt $timeout ]]; do
+    sleep 0.1
+    count=$((count + 1))
+  done
+  echo "$$" > "$LOCK_FILE"
+}
+
+release_lock() {
+  rm -f "$LOCK_FILE"
+}
+
+# Cleanup on exit
+cleanup() {
+  release_lock
+  rm -f "$TEMP_FILE"
+}
+trap cleanup EXIT
+
+# If cache doesn't exist, do full rebuild
+if [[ ! -f "$CACHE_FILE" ]]; then
+  bash "$PROJECT_ROOT/plugins/specweave/scripts/rebuild-dashboard-cache.sh" --quiet
+  exit 0
+fi
+
+# Find increment directory
+INCREMENT_DIR=""
+for dir in "$INCREMENTS_DIR"/*"$INCREMENT_ID"*/; do
+  if [[ -d "$dir" ]]; then
+    INCREMENT_DIR="$dir"
+    INCREMENT_ID=$(basename "$dir")
+    break
+  fi
+done
+
+if [[ -z "$INCREMENT_DIR" ]] || [[ ! -d "$INCREMENT_DIR" ]]; then
+  # Increment might have been archived or deleted
+  # Remove from cache if it exists
+  acquire_lock
+  if jq -e --arg id "$INCREMENT_ID" '.increments[$id]' "$CACHE_FILE" >/dev/null 2>&1; then
+    # Get old status for counter updates
+    old_status=$(jq -r --arg id "$INCREMENT_ID" '.increments[$id].status // "backlog"' "$CACHE_FILE")
+    old_type=$(jq -r --arg id "$INCREMENT_ID" '.increments[$id].type // "feature"' "$CACHE_FILE")
+    old_priority=$(jq -r --arg id "$INCREMENT_ID" '.increments[$id].priority // "P1"' "$CACHE_FILE")
+
+    # Remove increment and update counters
+    jq --arg id "$INCREMENT_ID" \
+       --arg old_status "$old_status" \
+       --arg old_type "$old_type" \
+       --arg old_priority "$old_priority" '
+      del(.increments[$id]) |
+      del(.mtimes[$id]) |
+      .summary.total -= 1 |
+      .summary[$old_status] -= 1 |
+      .summary.byType[$old_type] -= 1 |
+      .summary.byPriority[$old_priority] -= 1 |
+      .updatedAt = (now | strftime("%Y-%m-%dT%H:%M:%SZ"))
+    ' "$CACHE_FILE" > "$TEMP_FILE"
+    mv "$TEMP_FILE" "$CACHE_FILE"
+  fi
+  exit 0
+fi
+
+metadata_file="$INCREMENT_DIR/metadata.json"
+tasks_file="$INCREMENT_DIR/tasks.md"
+spec_file="$INCREMENT_DIR/spec.md"
+
+# Skip if no metadata
+if [[ ! -f "$metadata_file" ]]; then
+  exit 0
+fi
+
+# Read current values
+status=$(jq -r '.status // "backlog"' "$metadata_file" 2>/dev/null)
+type=$(jq -r '.type // "feature"' "$metadata_file" 2>/dev/null)
+priority=$(jq -r '.priority // "P1"' "$metadata_file" 2>/dev/null)
+title=$(jq -r '.title // ""' "$metadata_file" 2>/dev/null)
+project=$(jq -r '.project // ""' "$metadata_file" 2>/dev/null)
+created_at=$(jq -r '.createdAt // ""' "$metadata_file" 2>/dev/null)
+user_stories=$(jq -c '.userStories // []' "$metadata_file" 2>/dev/null || echo "[]")
+
+# Count tasks
+total_tasks=0
+completed_tasks=0
+if [[ -f "$tasks_file" ]]; then
+  total_tasks=$(grep -c "^### T-" "$tasks_file" 2>/dev/null) || total_tasks=0
+  completed_tasks=$(grep "^\*\*Status\*\*:.*\[x\]" "$tasks_file" 2>/dev/null | wc -l | tr -d ' ') || completed_tasks=0
+  total_tasks="${total_tasks:-0}"
+  completed_tasks="${completed_tasks:-0}"
+fi
+if [[ "$total_tasks" -eq 0 ]]; then
+  total_tasks=$(jq -r '.tasks.total // 0' "$metadata_file" 2>/dev/null) || total_tasks=0
+  completed_tasks=$(jq -r '.tasks.completed // 0' "$metadata_file" 2>/dev/null) || completed_tasks=0
+  total_tasks="${total_tasks:-0}"
+  completed_tasks="${completed_tasks:-0}"
+fi
+
+# Count ACs
+total_acs=0
+completed_acs=0
+if [[ -f "$spec_file" ]]; then
+  total_acs=$(grep -c "\- \[.\] \*\*AC-" "$spec_file" 2>/dev/null) || total_acs=0
+  completed_acs=$(grep -c "\- \[x\] \*\*AC-" "$spec_file" 2>/dev/null) || completed_acs=0
+  total_acs="${total_acs:-0}"
+  completed_acs="${completed_acs:-0}"
+fi
+if [[ "$total_acs" -eq 0 ]]; then
+  total_acs=$(jq -r '.acceptanceCriteria.total // 0' "$metadata_file" 2>/dev/null) || total_acs=0
+  completed_acs=$(jq -r '.acceptanceCriteria.satisfied // 0' "$metadata_file" 2>/dev/null) || completed_acs=0
+  total_acs="${total_acs:-0}"
+  completed_acs="${completed_acs:-0}"
+fi
+
+# Get last activity
+last_activity=""
+if [[ "$(uname)" == "Darwin" ]]; then
+  last_activity=$(stat -f "%Sm" -t "%Y-%m-%dT%H:%M:%SZ" "$metadata_file" 2>/dev/null || echo "")
+else
+  last_activity=$(stat -c "%y" "$metadata_file" 2>/dev/null | sed 's/ /T/' | cut -d. -f1)Z || echo ""
+fi
+
+# Get mtimes for stale detection
+meta_mtime=0
+tasks_mtime=0
+spec_mtime=0
+if [[ "$(uname)" == "Darwin" ]]; then
+  [[ -f "$metadata_file" ]] && meta_mtime=$(stat -f "%m" "$metadata_file" 2>/dev/null || echo "0")
+  [[ -f "$tasks_file" ]] && tasks_mtime=$(stat -f "%m" "$tasks_file" 2>/dev/null || echo "0")
+  [[ -f "$spec_file" ]] && spec_mtime=$(stat -f "%m" "$spec_file" 2>/dev/null || echo "0")
+else
+  [[ -f "$metadata_file" ]] && meta_mtime=$(stat -c "%Y" "$metadata_file" 2>/dev/null || echo "0")
+  [[ -f "$tasks_file" ]] && tasks_mtime=$(stat -c "%Y" "$tasks_file" 2>/dev/null || echo "0")
+  [[ -f "$spec_file" ]] && spec_mtime=$(stat -c "%Y" "$spec_file" 2>/dev/null || echo "0")
+fi
+
+# Acquire lock for update
+acquire_lock
+
+# Get old values for delta update
+old_status=$(jq -r --arg id "$INCREMENT_ID" '.increments[$id].status // ""' "$CACHE_FILE" 2>/dev/null)
+old_type=$(jq -r --arg id "$INCREMENT_ID" '.increments[$id].type // ""' "$CACHE_FILE" 2>/dev/null)
+old_priority=$(jq -r --arg id "$INCREMENT_ID" '.increments[$id].priority // ""' "$CACHE_FILE" 2>/dev/null)
+is_new=false
+if [[ -z "$old_status" ]]; then
+  is_new=true
+fi
+
+# Build the increment update
+increment_json=$(jq -n \
+  --arg status "$status" \
+  --arg type "$type" \
+  --arg priority "$priority" \
+  --arg title "$title" \
+  --arg project "$project" \
+  --argjson total_tasks "$total_tasks" \
+  --argjson completed_tasks "$completed_tasks" \
+  --argjson total_acs "$total_acs" \
+  --argjson completed_acs "$completed_acs" \
+  --arg created_at "$created_at" \
+  --arg last_activity "$last_activity" \
+  --argjson user_stories "$user_stories" \
+  '{
+    status: $status,
+    type: $type,
+    priority: $priority,
+    title: $title,
+    project: $project,
+    tasks: { total: $total_tasks, completed: $completed_tasks },
+    acs: { total: $total_acs, completed: $completed_acs },
+    createdAt: $created_at,
+    lastActivity: $last_activity,
+    userStories: $user_stories
+  }')
+
+# Build mtime update
+mtime_json=$(jq -n \
+  --argjson meta "$meta_mtime" \
+  --argjson tasks "$tasks_mtime" \
+  --argjson spec "$spec_mtime" \
+  '{ metadata: $meta, tasks: $tasks, spec: $spec }')
+
+# Apply incremental update
+if [[ "$is_new" == "true" ]]; then
+  # New increment - add to cache and increment counters
+  jq --arg id "$INCREMENT_ID" \
+     --argjson inc "$increment_json" \
+     --argjson mtime "$mtime_json" \
+     --arg status "$status" \
+     --arg type "$type" \
+     --arg priority "$priority" '
+    .increments[$id] = $inc |
+    .mtimes[$id] = $mtime |
+    .summary.total += 1 |
+    .summary[$status] += 1 |
+    .summary.byType[$type] += 1 |
+    .summary.byPriority[$priority] += 1 |
+    .updatedAt = (now | strftime("%Y-%m-%dT%H:%M:%SZ"))
+  ' "$CACHE_FILE" > "$TEMP_FILE"
+else
+  # Existing increment - update and adjust counters if status/type/priority changed
+  jq --arg id "$INCREMENT_ID" \
+     --argjson inc "$increment_json" \
+     --argjson mtime "$mtime_json" \
+     --arg old_status "$old_status" \
+     --arg new_status "$status" \
+     --arg old_type "$old_type" \
+     --arg new_type "$type" \
+     --arg old_priority "$old_priority" \
+     --arg new_priority "$priority" '
+    .increments[$id] = $inc |
+    .mtimes[$id] = $mtime |
+    (if $old_status != $new_status then
+      .summary[$old_status] -= 1 |
+      .summary[$new_status] += 1
+    else . end) |
+    (if $old_type != $new_type then
+      .summary.byType[$old_type] -= 1 |
+      .summary.byType[$new_type] += 1
+    else . end) |
+    (if $old_priority != $new_priority then
+      .summary.byPriority[$old_priority] -= 1 |
+      .summary.byPriority[$new_priority] += 1
+    else . end) |
+    .updatedAt = (now | strftime("%Y-%m-%dT%H:%M:%SZ"))
+  ' "$CACHE_FILE" > "$TEMP_FILE"
+fi
+
+# Atomic write
+mv "$TEMP_FILE" "$CACHE_FILE"
+
+# Success - no output for silent operation in hooks

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

@@ -211,43 +211,298 @@ jq '.sync.profiles | to_entries[] | select(.value.provider == "ado") | .value.co
 ls -la .specweave/docs/internal/specs/*/  # If sub-folders exist (not FS-XXX) → 2-level
 ```
 
-**Project/Board Selection (MANDATORY BEFORE STEP 4!):**
+**Project/Board Selection - ULTRA-SMART LOGIC (MANDATORY BEFORE STEP 4!):**
 
-1. **For 1-level structure:**
-   - ASK user: "Which project should this increment sync to?"
-   - Options: List from `structureConfig.projects`
-   - Store selected `PROJECT_ID`
+**⚠️ CORE PRINCIPLE: Each User Story belongs to exactly ONE project (1-level) or ONE project+board (2-level). An increment can contain USs spanning MULTIPLE projects/boards.**
 
-2. **For 2-level structure:**
-   - ASK user: "Which project should this increment sync to?"
-   - Then ASK: "Which board/area path within {project}?"
-   - Options: List from `structureConfig.boardsByProject[selectedProject]`
-   - Store BOTH `PROJECT_ID` and `BOARD_ID`
+---
+
+### SMART SELECTION DECISION TREE
+
+**RULE 1: NO QUESTION IF ONLY 1 OPTION**
+```
+IF 1-level AND only 1 project → AUTO-SELECT silently
+IF 2-level AND only 1 project AND only 1 board → AUTO-SELECT silently
+```
+
+**RULE 2: KEYWORD-BASED AUTO-DETECTION**
+
+Analyze feature description and US content for keywords:
+
+**Project-Level Keywords (1-level and 2-level):**
+```
+Frontend (FE) keywords:
+  UI, form, button, page, component, React, Vue, Angular, Next.js,
+  CSS, style, responsive, chart, dashboard, view, modal, widget,
+  Tailwind, Material-UI, Recharts
+
+Backend (BE) keywords:
+  API, endpoint, REST, GraphQL, database, query, migration, service,
+  controller, authentication, JWT, session, middleware, CRUD,
+  Redis, PostgreSQL, MongoDB, microservice
+
+Mobile keywords:
+  mobile, iOS, Android, React Native, Flutter, Expo, app, native,
+  push notification, offline, AsyncStorage, screen, touch, gesture
+
+Infrastructure (INFRA) keywords:
+  deploy, CI/CD, Docker, Kubernetes, terraform, monitoring,
+  logging, pipeline, AWS, Azure, GCP, nginx, Helm, ArgoCD
+
+Shared (SHARED) keywords:
+  types, interfaces, utilities, validators, shared, common, library,
+  SDK, models, constants, helpers
+```
 
-**VALIDATION RULE:**
+**Board-Level Keywords (2-level structures only):**
 ```
-❌ FORBIDDEN: Creating spec.md without PROJECT_ID set
-❌ FORBIDDEN: Creating spec.md for 2-level without BOARD_ID set
-❌ FORBIDDEN: Vague increments like "show last git commits" without project context
-✅ REQUIRED: Always know WHERE this increment will sync BEFORE creating spec.md
+When project has multiple boards, also match board-specific keywords:
+
+analytics/reporting: analytics, metrics, KPI, dashboard, report, chart, graph
+user-management: user, auth, login, registration, profile, permissions, roles
+integrations: integration, webhook, API, third-party, sync, import, export
+payments: payment, billing, subscription, invoice, stripe, checkout
+notifications: notification, alert, email, SMS, push, messaging
+devops/platform: deploy, infrastructure, monitoring, CI/CD, pipeline
+```
+
+**RULE 3: CONFIDENCE CALCULATION FORMULA**
+```
+confidence = (matched_keywords / total_feature_keywords) × 100
+
+Example: "Add React login form with JWT authentication"
+  Keywords found: React (FE), login (FE), form (FE), JWT (BE), authentication (BE)
+  FE matches: 3, BE matches: 2
+  FE confidence: 3/5 = 60%
+  BE confidence: 2/5 = 40%
+  → Primary: FE (60%), Secondary: BE (40%)
+  → SUGGEST: "Frontend (60%), but also touches Backend (40%)"
+
+If multiple projects have similar confidence (within 15%):
+  → Treat as MULTI-PROJECT feature
+  → Auto-split USs by detected keywords
+```
+
+**RULE 4: CONFIDENCE-BASED DECISION**
+```
+>80% single project → AUTO-SELECT with notification (no question)
+50-80% single project → SUGGEST with quick confirm option
+Multiple projects within 15% → AUTO-SPLIT across projects
+<50% OR ambiguous → ASK user with all options
+```
+
+**RULE 5: FALLBACK TO DEFAULTS**
+```
+IF US has explicit **Project**: field → USE IT
+ELSE IF frontmatter has default_project → USE default_project
+ELSE → ASK user (should not happen if flow followed correctly)
+
+Same logic applies to **Board**: and default_board for 2-level
 ```
 
-**Example User Interaction:**
+---
 
+### DECISION FLOWCHART
+
+```
+START
+  │
+  ▼
+┌─────────────────────────────────────┐
+│ 1. Detect structure level (1 or 2) │
+│ 2. Count available projects/boards │
+└─────────────────────────────────────┘
+  │
+  ▼
+┌─────────────────────────────────────┐
+│ ONLY 1 PROJECT?                     │
+│ (1-level: 1 project)                │
+│ (2-level: 1 project + 1 board)      │
+└─────────────────────────────────────┘
+  │
+  ├── YES ──► AUTO-SELECT SILENTLY
+  │           Output: "✅ Project: {name} (auto-selected)"
+  │           NO QUESTION ASKED
+  │
+  ▼ NO
+┌─────────────────────────────────────┐
+│ ANALYZE KEYWORDS in feature desc   │
+│ Calculate confidence per project   │
+└─────────────────────────────────────┘
+  │
+  ├── HIGH CONFIDENCE (>80% single) ──► AUTO-SELECT + NOTIFY
+  │   Output: "✅ Detected: {project} (keywords: form, React)"
+  │
+  ├── MULTI-PROJECT (within 15%) ──► AUTO-SPLIT USs
+  │   Output: "🔀 Multi-project detected:
+  │            • US-001 (Login UI) → web-app (60%)
+  │            • US-002 (Auth API) → api-service (55%)
+  │            Proceed? (Y/n)"
+  │
+  ├── MEDIUM CONFIDENCE (50-80%) ──► SUGGEST + CONFIRM
+  │   Output: "📍 Suggested: {project}. Confirm? (Y/n)"
+  │
+  ▼ LOW CONFIDENCE (<50%)
+┌─────────────────────────────────────┐
+│ ASK USER with ALL options listed   │
+│ multiSelect: true                  │
+│ Show complete list (never truncate)│
+└─────────────────────────────────────┘
 ```
-🔍 Detected 2-level structure (ADO area path mapping)
-   Available projects: acme-corp
 
-   📁 Project: acme-corp
-      Boards: clinical-insights, platform-engineering, digital-operations
+---
+
+### PER-USER-STORY ASSIGNMENT MODEL
+
+**CRITICAL: Assignment is at USER STORY level, not increment level!**
+
+Each US in spec.md has its own project (and board for 2-level):
+
+```markdown
+## User Stories
+
+### US-001: Login Form UI
+**Project**: web-app
+**Board**: frontend  <!-- 2-level only -->
+**As a** user...
 
-Which board should this increment sync to?
-> digital-operations
+### US-002: Auth API Endpoints
+**Project**: api-service
+**Board**: backend  <!-- 2-level only -->
+**As a** developer...
 
-✅ Increment will sync to: internal/specs/acme-corp/digital-operations/FS-XXX/
+### US-003: Mobile Login Screen
+**Project**: mobile-app
+**Board**: mobile-team  <!-- 2-level only -->
+**As a** mobile user...
 ```
 
-**Store PROJECT_ID and BOARD_ID for use in STEP 4!**
+**User can manually change project/board per US at any time by editing spec.md!**
+
+---
+
+### EXAMPLE SCENARIOS
+
+**Scenario 1: Single Project (NO QUESTION)**
+```
+Config: 1 project (my-app)
+Feature: "Add user authentication"
+
+→ AUTO-SELECT: my-app
+→ Output: "✅ Project: my-app (single project - auto-selected)"
+→ NO question asked
+```
+
+**Scenario 2: Multiple Projects, Clear Keywords (AUTO-DETECT)**
+```
+Config: 3 projects (web-app, api-service, mobile-app)
+Feature: "Add React dashboard with charts"
+
+→ Keyword analysis: "React" (FE), "dashboard" (FE), "charts" (FE)
+→ Confidence: 95% → web-app
+→ Output: "✅ Detected project: web-app (keywords: React, dashboard, charts)"
+→ NO question asked (high confidence)
+```
+
+**Scenario 3: Multiple Projects, Multi-Area Feature (SMART SPLIT)**
+```
+Config: 3 projects (web-app, api-service, shared-lib)
+Feature: "User authentication with JWT"
+
+→ Analyze: This spans FE (login form) + BE (auth API) + possibly shared (types)
+→ Output:
+  "🔍 This feature likely spans multiple projects:
+
+   Based on 'user authentication with JWT', I'll create:
+   • US-001: Login/Register UI → web-app (keywords: UI, form)
+   • US-002: Auth API endpoints → api-service (keywords: API, JWT)
+   • US-003: Auth types/validators → shared-lib (keywords: types, shared)
+
+   ✅ Proceed with this assignment? (Y/n)
+   💡 You can modify project per US in spec.md anytime"
+```
+
+**Scenario 4: 2-Level, Single Project, Auto-Detect Board**
+```
+Config: 1 project (enterprise-corp), 5 boards (analytics, frontend, backend, mobile, devops)
+Feature: "Add reporting dashboard"
+
+→ Project: AUTO-SELECT enterprise-corp (only option)
+→ Board keywords: "reporting" → analytics, "dashboard" → frontend
+→ Confidence: 70% analytics, 60% frontend
+→ Output:
+  "✅ Project: enterprise-corp (auto-selected)
+   📍 Suggested board: analytics (keyword: reporting)
+
+   Confirm or select different board:
+   1. analytics (suggested)
+   2. frontend
+   3. backend
+   4. mobile
+   5. devops"
+```
+
+**Scenario 5: Completely Ambiguous (ASK WITH ALL OPTIONS)**
+```
+Config: 4 projects (proj-a, proj-b, proj-c, proj-d)
+Feature: "Improve system performance"
+
+→ Keyword analysis: No clear project match
+→ Output:
+  "❓ Which project(s) should this increment target?
+
+   Available projects:
+   • proj-a - E-commerce frontend
+   • proj-b - Order processing API
+   • proj-c - Mobile shopping app
+   • proj-d - Infrastructure/DevOps
+
+   Select one or more (comma-separated, e.g., '1,2' or 'proj-a,proj-b'):"
+```
+
+---
+
+### VALIDATION RULES
+
+```
+❌ FORBIDDEN: Asking project question when only 1 project exists
+❌ FORBIDDEN: Asking board question when only 1 board exists in project
+❌ FORBIDDEN: Hiding options behind "Let me see all" - ALWAYS show complete list
+❌ FORBIDDEN: Truncating project/board lists
+❌ FORBIDDEN: Assigning ALL USs to same project when content clearly differs
+✅ REQUIRED: Auto-select when only 1 option available
+✅ REQUIRED: Use keyword matching before asking user
+✅ REQUIRED: Each US has explicit project (and board for 2-level) assignment
+✅ REQUIRED: Allow user to modify assignments per-US in spec.md
+✅ REQUIRED: When asking, show ALL options with descriptions
+```
+
+---
+
+### SPEC.MD YAML FORMAT
+
+**1-Level Structure:**
+```yaml
+---
+increment: 0045-user-auth
+title: "User Authentication"
+# Optional default (used if US doesn't specify)
+default_project: web-app
+---
+```
+
+**2-Level Structure:**
+```yaml
+---
+increment: 0045-user-auth
+title: "User Authentication"
+# Optional defaults (used if US doesn't specify)
+default_project: enterprise-corp
+default_board: backend
+---
+```
+
+**Store detected/selected values for use in STEP 4!**
 
 ---
 
@@ -445,6 +700,60 @@ const metadata = {
 
 **DO NOT invoke Task() tool to spawn agents from this skill!**
 
+### STEP 9: Trigger Living Docs & External Tool Sync (v0.32.2+)
+
+**🔄 CRITICAL: After increment files are created, trigger sync to living docs AND external tools!**
+
+This step uses the existing sync infrastructure to:
+1. Create living docs (FS-XXX folder with FEATURE.md and us-*.md files)
+2. Check permissions (`canUpsertInternalItems`) from `.specweave/config.json`
+3. Sync to external tools (GitHub/JIRA/ADO) if configured and permitted
+
+**Run the sync-specs command:**
+
+```bash
+/specweave:sync-specs {increment-id}
+```
+
+**Expected output:**
+
+```
+🔄 Syncing increment to living docs...
+✅ Living docs synced: FS-021
+   Created: 4 files (FEATURE.md, us-001.md, us-002.md, us-003.md)
+
+📡 Syncing to external tools: github
+   📋 Permissions: upsert=true, update=true, status=true
+   ✅ Synced to GitHub: 0 updated, 3 created
+```
+
+**Permission handling (v0.32.2+):**
+
+If `canUpsertInternalItems: false` in config:
+```
+⚠️ Skipping external sync - canUpsertInternalItems is disabled
+💡 Enable in .specweave/config.json: sync.settings.canUpsertInternalItems: true
+```
+
+**Error handling:**
+
+External tool sync failures are NON-BLOCKING:
+```
+⚠️ External sync failed: Rate limit exceeded
+💡 Run /specweave:sync-specs {increment-id} to retry
+```
+
+**Output after sync:**
+
+```
+✅ Increment created and synced!
+
+Next steps:
+1. Review the increment plan and docs
+2. Start implementation: /specweave:do {increment-id}
+3. Monitor status: /specweave:status {increment-id}
+```
+
 ---
 
 ## Model Selection for Tasks