specweave 0.17.13 → 0.17.16

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

@@ -646,33 +646,96 @@ EOF
 
   translate_living_docs_specs "$increment_id"
 
-  # 7. Increment-level GitHub sync (DISABLED - See architecture note below)
+  # 7. Increment-level GitHub issue creation (for single-repo projects)
   log_info ""
-  log_info "ℹ️  Increment-level GitHub sync disabled (by design)"
-  log_debug "Increments are INTERNAL work units, not synced to external tools"
-  log_debug "External sync happens at SPEC level (.specweave/docs/internal/specs/)"
-  log_debug "See: .specweave/increments/0025-per-project-resource-config/reports/CORRECT-SYNC-ARCHITECTURE.md"
-
-  # TODO: Implement spec-level sync instead
-  # Architecture:
-  #   - SPECS (.specweave/docs/internal/specs/) → GitHub Projects/JIRA Epics/ADO Features
-  #   - User Stories → GitHub Issues
-  #   - Increments → INTERNAL ONLY (no external sync)
-  #
-  # Commands to implement:
-  #   - /specweave-github:sync-spec spec-001
-  #   - /specweave-jira:sync-spec spec-001
-  #   - /specweave-ado:sync-spec spec-001
-  #
-  # See: plugins/specweave-github/commands/specweave-github-sync-spec.md
-
-  # COMMENTED OUT: Increment-level GitHub issue creation (architecturally wrong)
-  # # Check if auto-create is enabled in config
-  # local auto_create=$(cat "$CONFIG_FILE" 2>/dev/null | grep -A 5 '"sync"' | grep -A 2 '"settings"' | grep -o '"autoCreateIssue"[[:space:]]*:[[:space:]]*\(true\|false\)' | grep -o '\(true\|false\)' || echo "false")
-  #
-  # if [ "$auto_create" = "true" ]; then
-  #   ... (increment-level sync code removed)
-  # fi
+  log_info "🔗 Checking GitHub issue auto-creation..."
+
+  # Check if auto-create is enabled in config
+  local auto_create=$(cat "$CONFIG_FILE" 2>/dev/null | grep -A 5 '"sync"' | grep -A 2 '"settings"' | grep -o '"autoCreateIssue"[[:space:]]*:[[:space:]]*\(true\|false\)' | grep -o '\(true\|false\)' || echo "false")
+
+  log_debug "Auto-create GitHub issue: $auto_create"
+
+  if [ "$auto_create" = "true" ]; then
+    log_info "  📦 Auto-create enabled, checking for GitHub CLI..."
+
+    # Check if gh CLI is available
+    if ! command -v gh >/dev/null 2>&1; then
+      log_info "  ⚠️  GitHub CLI (gh) not found, skipping issue creation"
+      log_debug "Install: https://cli.github.com/"
+    else
+      log_info "  ✓ GitHub CLI found"
+      log_info ""
+      log_info "🚀 Creating GitHub issue for $increment_id..."
+
+      # Create issue (non-blocking)
+      if create_github_issue "$increment_id" "$increment_dir"; then
+        log_info "  ✅ GitHub issue created successfully"
+      else
+        log_info "  ⚠️  GitHub issue creation failed (non-blocking)"
+        log_debug "Issue creation failed, but continuing execution"
+      fi
+    fi
+  else
+    log_debug "Auto-create disabled in config"
+  fi
+
+  # ============================================================================
+  # FALLBACK METADATA CREATION (v0.14.0+)
+  # ============================================================================
+  # CRITICAL: Ensure metadata.json exists even if GitHub integration failed
+  # This prevents silent failures where increment appears complete but lacks metadata
+
+  log_info ""
+  log_info "🔍 Validating metadata.json existence..."
+
+  local metadata_file="$increment_dir/metadata.json"
+
+  if [ ! -f "$metadata_file" ]; then
+    log_info "  ⚠️  metadata.json not found (hook may have failed)"
+    log_info "  📝 Creating minimal metadata as fallback..."
+
+    local current_timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+    # Extract type from spec.md frontmatter (if available)
+    local increment_type="feature"
+    if [ -f "$spec_file" ]; then
+      local extracted_type=$(awk '/^---$/,/^---$/ {if (/^type:/) {sub(/^type:[[:space:]]*"?/, ""); sub(/"?[[:space:]]*$/, ""); print; exit}}' "$spec_file" 2>/dev/null)
+      if [ -n "$extracted_type" ]; then
+        increment_type="$extracted_type"
+      fi
+    fi
+
+    # Create minimal metadata.json
+    cat > "$metadata_file" <<EOF_MINIMAL
+{
+  "id": "$increment_id",
+  "status": "active",
+  "type": "$increment_type",
+  "created": "$current_timestamp",
+  "lastActivity": "$current_timestamp"
+}
+EOF_MINIMAL
+
+    log_info "  ✅ Created minimal metadata.json"
+    log_info "  ⚠️  Note: No GitHub issue linked"
+    log_info "  💡 Run /specweave-github:create-issue $increment_id to create one manually"
+  else
+    log_info "  ✅ metadata.json exists"
+
+    # Check if GitHub issue was created
+    local has_github=$(cat "$metadata_file" 2>/dev/null | grep -o '"github"[[:space:]]*:[[:space:]]*{' || echo "")
+    if [ -n "$has_github" ]; then
+      local issue_num=$(cat "$metadata_file" 2>/dev/null | grep -o '"issue"[[:space:]]*:[[:space:]]*[0-9]*' | grep -o '[0-9]*' || echo "")
+      if [ -n "$issue_num" ]; then
+        log_info "  ✅ GitHub issue #$issue_num linked"
+      fi
+    else
+      log_debug "  ℹ️  No GitHub issue linked (autoCreateIssue may be disabled)"
+    fi
+  fi
+
+  # Note: Spec-level sync (SPECS → GitHub Projects/JIRA Epics) is handled separately
+  # See: /specweave-github:sync-spec, /specweave-jira:sync-spec, /specweave-ado:sync-spec
 
   # 8. Sync spec content to external tools (if configured)
   log_info ""

package/plugins/specweave/hooks/user-prompt-submit.sh

@@ -30,7 +30,7 @@ if echo "$PROMPT" | grep -q "/specweave:increment"; then
       # Check active increments using MetadataManager
       ACTIVE_COUNT=$(node -e "
         try {
-          const { MetadataManager } = require('./dist/core/increment/metadata-manager.js');
+          const { MetadataManager } = require('./dist/src/core/increment/metadata-manager.js');
           const active = MetadataManager.getActive();
           console.log(active.length);
         } catch (e) {
@@ -44,7 +44,7 @@ if echo "$PROMPT" | grep -q "/specweave:increment"; then
         # Get list of active increments for error message
         ACTIVE_LIST=$(node -e "
           try {
-            const { MetadataManager } = require('./dist/core/increment/metadata-manager.js');
+            const { MetadataManager } = require('./dist/src/core/increment/metadata-manager.js');
             const active = MetadataManager.getActive();
             active.forEach(inc => console.log('  - ' + inc.id + ' [' + inc.type + ']'));
           } catch (e) {}
@@ -64,7 +64,7 @@ EOF
         # Get list of active increments for warning
         ACTIVE_LIST=$(node -e "
           try {
-            const { MetadataManager } = require('./dist/core/increment/metadata-manager.js');
+            const { MetadataManager } = require('./dist/src/core/increment/metadata-manager.js');
             const active = MetadataManager.getActive();
             active.forEach(inc => console.log('  - ' + inc.id + ' [' + inc.type + ']'));
           } catch (e) {}
@@ -231,7 +231,7 @@ if [[ -d ".specweave/increments" ]]; then
       # Get status line from cache (ultra-fast)
       STATUS_LINE=$(node -e "
         try {
-          const { StatusLineManager } = require('./dist/core/status-line/status-line-manager.js');
+          const { StatusLineManager } = require('./dist/src/core/status-line/status-line-manager.js');
           const manager = new StatusLineManager(process.cwd());
           const result = manager.render();
           console.log(result || '');

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

@@ -110,13 +110,15 @@ This skill activates automatically when users say:
 
 ---
 
-## 🆕 Multi-Project Support (v0.8.0+)
+## 🆕 Multi-Project Support (v0.8.0+ | Flattened v0.16.11+)
 
 **Key Changes**:
-- Specs are now organized by project: `.specweave/docs/internal/projects/{project-id}/specs/`
-- Use `ProjectManager` (from `src/core/project-manager.ts`) to get correct paths
-- Single project uses `projects/default/` automatically (transparent)
+- ✅ **CORRECT** (v0.16.11+): Specs organized with FLATTENED structure: `.specweave/docs/internal/specs/{project-id}/`
+- ❌ **OLD** (v0.8.0-v0.16.10): `.specweave/docs/internal/projects/{project-id}/specs/` (DEPRECATED nested structure)
+- Use `ProjectManager` (from `src/core/project-manager.ts`) to get correct paths (always returns flattened structure)
+- Single project uses `specs/default/` automatically (transparent)
 - Multi-project mode allows multiple teams/repos
+- Parent repo content goes to `specs/_parent/` (for multi-repo setups with parent repositories)
 
 **Path Resolution**:
 ```typescript
@@ -177,7 +179,7 @@ Task(
   1. Spec (living docs - SOURCE OF TRUTH, permanent):
      - IMPORTANT: Use ProjectManager to get correct path for active project
      - Create at: {projectManager.getSpecsPath()}/spec-{number}-{name}.md
-       (This resolves to projects/{activeProject}/specs/ automatically)
+       (This resolves to specs/{activeProject}/ with FLATTENED structure v0.16.11+)
      - This is the COMPLETE, PERMANENT source of truth
      - Include ALL of:
        * User stories (US-001, US-002, etc.) with full details
@@ -299,17 +301,20 @@ STEP 6: Validate Living Docs and Increment Files
 
 #### Living Spec (Living Docs - Source of Truth) ✅
 ```
-.specweave/docs/internal/projects/{project-id}/specs/  # ← Multi-project (v0.8.0+)
+.specweave/docs/internal/specs/{project-id}/  # ← FLATTENED structure (v0.16.11+)
 └── spec-{number}-{name}.md          # ← PM Agent (MANDATORY)
                                      # COMPLETE user stories, AC, requirements
                                      # This is the PERMANENT source of truth
                                      # Can be linked to Jira/ADO/GitHub Issues
                                      # Persists after increment completes
 
-# Examples:
-# Single project: projects/default/specs/spec-001-user-auth.md
-# Multi-project: projects/web-app/specs/spec-001-user-auth.md
-#                projects/mobile/specs/spec-001-push-notifications.md
+# Examples (v0.16.11+ Flattened):
+# Single project: specs/default/spec-001-user-auth.md
+# Multi-project: specs/web-app/spec-001-user-auth.md
+#                specs/mobile/spec-001-push-notifications.md
+# Parent repo:   specs/_parent/spec-002-system-architecture.md
+
+# OLD (v0.8.0-v0.16.10): projects/default/specs/... ← DEPRECATED
 ```
 
 #### Strategy Docs (Optional, High-Level) ⚠️

package/plugins/specweave/skills/plugin-validator/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: plugin-validator
-description: Proactively validates SpecWeave plugin installation before workflows execute. Auto-activates when /specweave:* commands detected. Ensures marketplace registered, core plugin installed, and context-specific plugins available. Prevents cryptic errors from missing plugins. Enables seamless environment migration (local → VM → Cloud IDE). Activates for plugin validation, environment setup, missing plugins, specweave commands, marketplace registration, plugin installation, environment migration, fresh setup.
+description: Validates SpecWeave plugin installation when EXPLICITLY requested by user. Ensures marketplace registered, core plugin installed, and context-specific plugins available. ONLY activates for explicit validation requests - does NOT auto-activate for workflow commands to avoid false positives. Activates ONLY for plugin validation, environment setup, validate plugins, check plugins, specweave init, fresh setup, marketplace registration.
 allowed-tools: Read, Bash, Grep
 ---
 
 # Plugin Validator Skill
 
-**Purpose**: Proactively validate and install SpecWeave plugins before workflow commands execute.
+**Purpose**: Validate and install SpecWeave plugins when explicitly requested by the user.
 
-**Auto-Activation**: Triggers when `/specweave:*` commands are detected or when plugin-related issues arise.
+**Activation**: Triggers ONLY when user explicitly requests plugin validation (e.g., "validate plugins", "check plugins", or runs `specweave validate-plugins` command). Does NOT auto-activate for workflow commands to prevent false positive errors.
 
 ## What This Skill Does
 
@@ -24,16 +24,19 @@ This skill ensures that your SpecWeave environment is properly configured with a
 
 ## When This Skill Activates
 
-✅ **Automatically activates when**:
-- You run any `/specweave:*` command (increment, do, next, etc.)
-- You mention "plugin validation" or "environment setup"
-- You encounter errors related to missing plugins
-- You're setting up SpecWeave in a new environment
-
-✅ **Manual activation**:
-- Run: `specweave validate-plugins`
-- Ask: "Can you validate my plugins?"
-- Report: "I'm getting plugin errors"
+✅ **ONLY activates when explicitly requested**:
+- You mention "plugin validation" or "validate plugins"
+- You mention "environment setup" or "check plugins"
+- You run: `specweave validate-plugins`
+- You ask: "Can you validate my plugins?"
+- You report: "I'm getting plugin errors"
+- During: `specweave init` (initial setup only)
+
+❌ **Does NOT auto-activate for**:
+- `/specweave:increment` commands
+- `/specweave:do` commands
+- Any other workflow commands
+- Reason: Prevents false positive errors when plugins are installed but detection fails
 
 ## Validation Process
 

package/plugins/specweave-ado/lib/ado-project-detector.js

@@ -233,15 +233,15 @@ class AdoProjectDetector {
    */
   async detectFromContent(content) {
     const candidates = this.analyzeContent(content);
-    if (candidates[0]?.confidence > 0.7) {
+    if (candidates[0]?.confidence >= 0.7) {
       return {
         primary: candidates[0].project,
         confidence: candidates[0].confidence,
         strategy: this.strategy
       };
     }
-    if (candidates[0]?.confidence > 0.4) {
-      const secondary = candidates.slice(1).filter((c) => c.confidence > 0.3).map((c) => c.project);
+    if (candidates[0]?.confidence >= 0.4) {
+      const secondary = candidates.slice(1).filter((c) => c.confidence >= 0.3).map((c) => c.project);
       return {
         primary: candidates[0].project,
         secondary: secondary.length > 0 ? secondary : void 0,
@@ -306,7 +306,7 @@ class AdoProjectDetector {
    */
   async detectMultiProject(content) {
     const candidates = this.analyzeContent(content);
-    const significantProjects = candidates.filter((c) => c.confidence > 0.3);
+    const significantProjects = candidates.filter((c) => c.confidence >= 0.3);
     if (significantProjects.length === 0) {
       return {
         primary: this.availableProjects[0] || "Unknown",
@@ -328,11 +328,38 @@ class AdoProjectDetector {
    */
   mapToAreaPath(content, project) {
     const areaPaths = process.env.AZURE_DEVOPS_AREA_PATHS?.split(",").map((a) => a.trim()) || [];
+    const lowerContent = content.toLowerCase();
     for (const areaPath of areaPaths) {
-      if (content.toLowerCase().includes(areaPath.toLowerCase())) {
+      if (lowerContent.includes(areaPath.toLowerCase())) {
         return `${project}\\${areaPath}`;
       }
     }
+    const areaPathKeywordMap = {
+      "Frontend": ["WebApp", "frontend"],
+      "Backend": ["backend", "api", "server"],
+      "Mobile": ["MobileApp", "mobile", "ios", "android"],
+      "Infrastructure": ["Platform", "infrastructure"],
+      "Data": ["DataService", "data", "analytics"]
+    };
+    let bestMatch = { areaPath: "", confidence: 0 };
+    for (const areaPath of areaPaths) {
+      const relatedTypes = areaPathKeywordMap[areaPath] || [areaPath];
+      let matchCount = 0;
+      for (const projectType of relatedTypes) {
+        const keywords = this.projectKeywords[projectType] || [];
+        for (const keyword of keywords) {
+          if (lowerContent.includes(keyword.toLowerCase())) {
+            matchCount++;
+          }
+        }
+      }
+      if (matchCount > bestMatch.confidence) {
+        bestMatch = { areaPath, confidence: matchCount };
+      }
+    }
+    if (bestMatch.confidence >= 2) {
+      return `${project}\\${bestMatch.areaPath}`;
+    }
     return project;
   }
   /**

package/plugins/specweave-ado/lib/ado-project-detector.ts

@@ -202,7 +202,7 @@ export class AdoProjectDetector {
     const candidates = this.analyzeContent(content);
 
     // High confidence: Auto-select
-    if (candidates[0]?.confidence > 0.7) {
+    if (candidates[0]?.confidence >= 0.7) {
       return {
         primary: candidates[0].project,
         confidence: candidates[0].confidence,
@@ -211,10 +211,10 @@ export class AdoProjectDetector {
     }
 
     // Medium confidence: Primary with secondary projects
-    if (candidates[0]?.confidence > 0.4) {
+    if (candidates[0]?.confidence >= 0.4) {
       const secondary = candidates
         .slice(1)
-        .filter(c => c.confidence > 0.3)
+        .filter(c => c.confidence >= 0.3)
         .map(c => c.project);
 
       return {
@@ -299,7 +299,7 @@ export class AdoProjectDetector {
     const candidates = this.analyzeContent(content);
 
     // Get all projects with meaningful confidence
-    const significantProjects = candidates.filter(c => c.confidence > 0.3);
+    const significantProjects = candidates.filter(c => c.confidence >= 0.3);
 
     if (significantProjects.length === 0) {
       return {
@@ -330,13 +330,52 @@ export class AdoProjectDetector {
    */
   mapToAreaPath(content: string, project: string): string {
     const areaPaths = process.env.AZURE_DEVOPS_AREA_PATHS?.split(',').map(a => a.trim()) || [];
+    const lowerContent = content.toLowerCase();
 
+    // First try exact area path name match
     for (const areaPath of areaPaths) {
-      if (content.toLowerCase().includes(areaPath.toLowerCase())) {
+      if (lowerContent.includes(areaPath.toLowerCase())) {
         return `${project}\\${areaPath}`;
       }
     }
 
+    // Try keyword-based detection using PROJECT_KEYWORDS
+    // Map area paths to common project types
+    const areaPathKeywordMap: { [key: string]: string[] } = {
+      'Frontend': ['WebApp', 'frontend'],
+      'Backend': ['backend', 'api', 'server'],
+      'Mobile': ['MobileApp', 'mobile', 'ios', 'android'],
+      'Infrastructure': ['Platform', 'infrastructure'],
+      'Data': ['DataService', 'data', 'analytics']
+    };
+
+    let bestMatch = { areaPath: '', confidence: 0 };
+
+    for (const areaPath of areaPaths) {
+      // Get related project types for this area path
+      const relatedTypes = areaPathKeywordMap[areaPath] || [areaPath];
+      let matchCount = 0;
+
+      for (const projectType of relatedTypes) {
+        // Check if this project type has keywords defined
+        const keywords = this.projectKeywords[projectType] || [];
+        for (const keyword of keywords) {
+          if (lowerContent.includes(keyword.toLowerCase())) {
+            matchCount++;
+          }
+        }
+      }
+
+      if (matchCount > bestMatch.confidence) {
+        bestMatch = { areaPath, confidence: matchCount };
+      }
+    }
+
+    // Return best match if confidence is high enough
+    if (bestMatch.confidence >= 2) {
+      return `${project}\\${bestMatch.areaPath}`;
+    }
+
     // Default area path
     return project;
   }

package/src/templates/AGENTS.md.template

@@ -22,6 +22,11 @@ This is a **SpecWeave project** where specifications and documentation are the s
 
 ## Project Structure
 
+**IMPORTANT**: This project uses {MONOREPO_OR_SINGLE} mode.
+
+{#IF_SINGLE_PROJECT}
+### Single Project Structure
+
 ```
 .specweave/
 ├── increments/              # Feature increments (auto-numbered)
@@ -36,7 +41,8 @@ This is a **SpecWeave project** where specifications and documentation are the s
 │       └── reports/         # Analysis, completion reports
 ├── docs/internal/
 │   ├── strategy/            # Business specs (WHAT, WHY)
-│   ├── specs/               # Feature specifications (detailed requirements)
+│   ├── specs/               # Feature specifications (living docs)
+│   │   └── default/         # ✅ All specs in default project
 │   ├── architecture/        # Technical design (HOW)
 │   ├── delivery/            # Roadmap, CI/CD, guides
 │   ├── operations/          # Runbooks, SLOs
@@ -55,6 +61,54 @@ plugins/                     # Optional plugins (extended capabilities)
     ├── agents/              # Plugin-specific agents
     └── commands/            # Plugin-specific commands
 ```
+{#ENDIF}
+
+{#IF_MULTI_PROJECT}
+### Multi-Project Structure (v0.16.11+ Flattened)
+
+**CRITICAL**: Specs are organized by project with FLATTENED structure (v0.16.11+).
+
+```
+.specweave/
+├── docs/internal/
+│   ├── strategy/            # Cross-project strategy
+│   ├── specs/               # ✅ FLATTENED structure (v0.16.11+)
+│   │   ├── backend/         # Backend project specs
+│   │   │   ├── spec-001-api-auth.md
+│   │   │   └── spec-002-data-layer.md
+│   │   ├── frontend/        # Frontend project specs
+│   │   │   ├── spec-001-user-dashboard.md
+│   │   │   └── spec-002-dark-mode.md
+│   │   ├── mobile/          # Mobile project specs (if applicable)
+│   │   │   └── spec-001-push-notifications.md
+│   │   └── _parent/         # Parent repo specs (multi-repo only)
+│   │       └── spec-001-system-architecture.md
+│   ├── architecture/        # System-wide technical design
+│   ├── delivery/            # Cross-project delivery
+│   ├── operations/          # Cross-project operations
+│   └── governance/          # Cross-project governance
+├── increments/
+│   ├── 0001-backend-auth/   # Backend increment
+│   ├── 0002-frontend-ui/    # Frontend increment
+│   └── 0003-mobile-push/    # Mobile increment
+└── ...
+```
+
+**Living Docs Path Format**:
+- ✅ **CORRECT** (v0.16.11+): `.specweave/docs/internal/specs/{project-id}/spec-NNN-name.md`
+- ❌ **OLD** (v0.8.0-v0.16.10): `.specweave/docs/internal/projects/{project-id}/specs/...` (DEPRECATED)
+
+**Project Detection** (automatic):
+- **From increment name**: `0001-backend-auth` → project: `backend`
+- **From tech stack**: React/Next.js → `frontend`, ASP.NET/Node.js → `backend`
+- **From config**: `multiProject.activeProject` in `.specweave/config.json`
+- **Fallback**: Uses `default` project
+
+**When creating living docs specs**:
+1. Detect project from increment name or tech stack
+2. Use flattened path: `specs/{project-id}/spec-NNN-name.md`
+3. Never use old nested structure: `projects/{project-id}/specs/...`
+{#ENDIF}
 
 **CRITICAL**: Always read `context-manifest.yaml` first! Only load files listed there.
 

package/src/templates/CLAUDE.md.template

@@ -289,13 +289,19 @@ Config: Auto-detected from project files
 
 ## Project Structure
 
+**IMPORTANT**: This project uses {MONOREPO_OR_SINGLE} mode.
+
+{#IF_SINGLE_PROJECT}
+### Single Project Structure
+
 ```
 {PROJECT_NAME}/
 ├── .specweave/
 │   ├── docs/                    # Strategic documentation
 │   │   ├── internal/
 │   │   │   ├── strategy/        # Business specs (WHAT, WHY)
-│   │   │   ├── specs/           # Feature specifications (detailed requirements)
+│   │   │   ├── specs/           # Feature specifications (living docs)
+│   │   │   │   └── default/     # ✅ All specs in default project
 │   │   │   ├── architecture/    # Technical design (HOW)
 │   │   │   ├── delivery/        # Guides, roadmap, CI/CD
 │   │   │   ├── operations/      # Runbooks, monitoring
@@ -319,6 +325,50 @@ Config: Auto-detected from project files
 ├── CLAUDE.md                    # This file
 └── src/                         # Your source code
 ```
+{#ENDIF}
+
+{#IF_MULTI_PROJECT}
+### Multi-Project Structure (v0.16.11+ Flattened)
+
+**CRITICAL**: Specs are organized by project with FLATTENED structure (v0.16.11+).
+
+```
+{PROJECT_NAME}/
+├── .specweave/
+│   ├── docs/internal/
+│   │   ├── strategy/            # Cross-project strategy
+│   │   ├── specs/               # ✅ FLATTENED structure (v0.16.11+)
+│   │   │   ├── backend/         # Backend project specs
+│   │   │   │   ├── spec-001-api-auth.md
+│   │   │   │   └── spec-002-data-layer.md
+│   │   │   ├── frontend/        # Frontend project specs
+│   │   │   │   ├── spec-001-user-dashboard.md
+│   │   │   │   └── spec-002-dark-mode.md
+│   │   │   ├── mobile/          # Mobile project specs (if applicable)
+│   │   │   │   └── spec-001-push-notifications.md
+│   │   │   └── _parent/         # Parent repo specs (multi-repo only)
+│   │   │       └── spec-001-system-architecture.md
+│   │   ├── architecture/        # System-wide technical design
+│   │   ├── delivery/            # Cross-project delivery
+│   │   ├── operations/          # Cross-project operations
+│   │   └── governance/          # Cross-project governance
+│   ├── increments/
+│   │   ├── 0001-backend-auth/   # Backend increment
+│   │   ├── 0002-frontend-ui/    # Frontend increment
+│   │   └── 0003-mobile-push/    # Mobile increment
+│   └── ...
+```
+
+**Living Docs Path Format**:
+- ✅ **CORRECT** (v0.16.11+): `.specweave/docs/internal/specs/{project-id}/spec-NNN-name.md`
+- ❌ **OLD** (v0.8.0-v0.16.10): `.specweave/docs/internal/projects/{project-id}/specs/...` (DEPRECATED)
+
+**Project Detection** (automatic):
+- **From increment name**: `0001-backend-auth` → project: `backend`
+- **From tech stack**: React/Next.js → `frontend`, ASP.NET/Node.js → `backend`
+- **From config**: `multiProject.activeProject` in `.specweave/config.json`
+- **Fallback**: Uses `default` project
+{#ENDIF}
 
 ---