specweave 0.28.17 → 0.28.20

package/dist/src/utils/project-id-generator.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Project ID Generator with Duplicate Prevention (v0.29.0+)
+ *
+ * Generates unique SpecWeave project IDs from external tool entities:
+ * - JIRA boards → Project IDs
+ * - ADO area paths → Project IDs
+ * - GitHub repos → Project IDs
+ *
+ * Handles collision detection and composite key generation.
+ */
+/**
+ * Project ID generation options
+ */
+export interface ProjectIdOptions {
+    /** External container (JIRA project key, ADO project name) */
+    externalContainer: string;
+    /** Local name (board name, area path, repo name) */
+    localName: string;
+    /** Provider type */
+    provider: 'jira' | 'ado' | 'github';
+    /** Existing project IDs to check for collisions */
+    existingIds?: string[];
+}
+/**
+ * Generated project ID result
+ */
+export interface ProjectIdResult {
+    /** Generated project ID */
+    id: string;
+    /** Whether collision was detected and prefix was added */
+    hadCollision: boolean;
+    /** Original local name before sanitization */
+    originalName: string;
+    /** Full composite key (container + local) */
+    compositeKey: string;
+}
+/**
+ * Normalize a string to a valid project ID
+ * - Lowercase
+ * - Replace spaces and special chars with hyphens
+ * - Remove consecutive hyphens
+ * - Remove leading/trailing hyphens
+ */
+export declare function normalizeToProjectId(name: string): string;
+/**
+ * Generate a short prefix from external container name
+ * Used when collision is detected
+ */
+export declare function generateContainerPrefix(container: string): string;
+/**
+ * Generate unique project ID with collision detection
+ *
+ * Algorithm:
+ * 1. Normalize local name to project ID format
+ * 2. Check if ID exists in existingIds
+ * 3. If collision, add container prefix: "core-fe" instead of "fe"
+ * 4. If still collision (rare), add numeric suffix: "core-fe-2"
+ *
+ * @param options Generation options
+ * @returns Generated project ID with metadata
+ */
+export declare function generateProjectId(options: ProjectIdOptions): ProjectIdResult;
+/**
+ * Batch generate project IDs from multiple sources
+ * Ensures no collisions within the batch and with existing IDs
+ */
+export declare function generateProjectIdsBatch(sources: Array<{
+    container: string;
+    localName: string;
+    provider: 'jira' | 'ado' | 'github';
+}>, existingIds?: string[]): Map<string, ProjectIdResult>;
+/**
+ * Get existing project IDs from a SpecWeave project
+ *
+ * @param projectRoot Path to project root
+ * @returns Array of existing project IDs
+ */
+export declare function getExistingProjectIds(projectRoot: string): string[];
+/**
+ * Create 2-level directory structure for JIRA/ADO projects
+ *
+ * Structure:
+ * .specweave/docs/internal/specs/
+ * ├── JIRA-CORE/                  (external container level)
+ * │   ├── fe/                     (SpecWeave project level)
+ * │   ├── be/
+ * │   └── mobile/
+ * └── ADO-MyProduct/
+ *     ├── fe/
+ *     └── be/
+ *
+ * @param projectRoot Path to project root
+ * @param containerType Type of external container
+ * @param containerId External container ID (JIRA project key or ADO project name)
+ * @param specweaveProjectId SpecWeave project ID
+ */
+export declare function createTwoLevelProjectDir(projectRoot: string, containerType: 'jira' | 'ado', containerId: string, specweaveProjectId: string): string;
+/**
+ * Get the 2-level path for a project
+ *
+ * @param projectRoot Path to project root
+ * @param containerType Type of external container
+ * @param containerId External container ID
+ * @param specweaveProjectId SpecWeave project ID
+ * @returns Full path or undefined if using flat structure
+ */
+export declare function getTwoLevelProjectPath(projectRoot: string, containerType: 'jira' | 'ado' | null, containerId: string | null, specweaveProjectId: string): string;
+/**
+ * Parse a 2-level project path to extract container and project info
+ *
+ * @param projectPath Path like ".specweave/docs/internal/specs/JIRA-CORE/fe"
+ * @returns Parsed container and project info
+ */
+export declare function parseTwoLevelPath(projectPath: string): {
+    containerType: 'jira' | 'ado' | null;
+    containerId: string | null;
+    projectId: string;
+} | null;
+/**
+ * Validate project ID format
+ */
+export declare function isValidProjectId(id: string): boolean;
+/**
+ * Suggest a valid project ID from an invalid one
+ */
+export declare function suggestProjectId(invalidId: string): string;
+//# sourceMappingURL=project-id-generator.d.ts.map

package/dist/src/utils/project-id-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-id-generator.d.ts","sourceRoot":"","sources":["../../../src/utils/project-id-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,iBAAiB,EAAE,MAAM,CAAC;IAE1B,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAElB,oBAAoB;IACpB,QAAQ,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAEpC,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,2BAA2B;IAC3B,EAAE,EAAE,MAAM,CAAC;IAEX,0DAA0D;IAC1D,YAAY,EAAE,OAAO,CAAC;IAEtB,8CAA8C;IAC9C,YAAY,EAAE,MAAM,CAAC;IAErB,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMzD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAgBjE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CA6C5E;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,KAAK,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAA;CAAE,CAAC,EAC7F,WAAW,GAAE,MAAM,EAAO,GACzB,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAoB9B;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAenE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,GAAG,KAAK,EAC7B,WAAW,EAAE,MAAM,EACnB,kBAAkB,EAAE,MAAM,GACzB,MAAM,CAoBR;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,EACpC,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,kBAAkB,EAAE,MAAM,GACzB,MAAM,CAwBR;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG;IACtD,aAAa,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAAC;IACrC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,IAAI,CAyBP;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAG1D"}

package/dist/src/utils/project-id-generator.js

@@ -0,0 +1,228 @@
+/**
+ * Project ID Generator with Duplicate Prevention (v0.29.0+)
+ *
+ * Generates unique SpecWeave project IDs from external tool entities:
+ * - JIRA boards → Project IDs
+ * - ADO area paths → Project IDs
+ * - GitHub repos → Project IDs
+ *
+ * Handles collision detection and composite key generation.
+ */
+import * as fs from './fs-native.js';
+import * as path from 'path';
+/**
+ * Normalize a string to a valid project ID
+ * - Lowercase
+ * - Replace spaces and special chars with hyphens
+ * - Remove consecutive hyphens
+ * - Remove leading/trailing hyphens
+ */
+export function normalizeToProjectId(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-') // Replace non-alphanumeric with hyphens
+        .replace(/-+/g, '-') // Remove consecutive hyphens
+        .replace(/^-|-$/g, ''); // Remove leading/trailing hyphens
+}
+/**
+ * Generate a short prefix from external container name
+ * Used when collision is detected
+ */
+export function generateContainerPrefix(container) {
+    // For JIRA project keys like "CORE", use as-is (already short)
+    if (/^[A-Z]{2,10}$/.test(container)) {
+        return container.toLowerCase();
+    }
+    // For longer names, create abbreviation
+    // "MyProduct" → "mp", "Backend-Services" → "bs"
+    const words = container.split(/[-_\s]+/);
+    if (words.length === 1) {
+        // Single word: use first 3 chars
+        return container.substring(0, 3).toLowerCase();
+    }
+    // Multiple words: use first letter of each
+    return words.map(w => w[0]).join('').toLowerCase();
+}
+/**
+ * Generate unique project ID with collision detection
+ *
+ * Algorithm:
+ * 1. Normalize local name to project ID format
+ * 2. Check if ID exists in existingIds
+ * 3. If collision, add container prefix: "core-fe" instead of "fe"
+ * 4. If still collision (rare), add numeric suffix: "core-fe-2"
+ *
+ * @param options Generation options
+ * @returns Generated project ID with metadata
+ */
+export function generateProjectId(options) {
+    const { externalContainer, localName, provider, existingIds = [] } = options;
+    // Step 1: Normalize local name
+    const baseId = normalizeToProjectId(localName);
+    const compositeKey = `${externalContainer}/${localName}`;
+    // Step 2: Check for collision
+    if (!existingIds.includes(baseId)) {
+        return {
+            id: baseId,
+            hadCollision: false,
+            originalName: localName,
+            compositeKey,
+        };
+    }
+    // Step 3: Collision detected - add container prefix
+    const prefix = generateContainerPrefix(externalContainer);
+    let prefixedId = `${prefix}-${baseId}`;
+    if (!existingIds.includes(prefixedId)) {
+        return {
+            id: prefixedId,
+            hadCollision: true,
+            originalName: localName,
+            compositeKey,
+        };
+    }
+    // Step 4: Still collision (rare) - add numeric suffix
+    let suffix = 2;
+    while (existingIds.includes(`${prefixedId}-${suffix}`)) {
+        suffix++;
+        if (suffix > 100) {
+            throw new Error(`Cannot generate unique ID for ${compositeKey} after 100 attempts`);
+        }
+    }
+    return {
+        id: `${prefixedId}-${suffix}`,
+        hadCollision: true,
+        originalName: localName,
+        compositeKey,
+    };
+}
+/**
+ * Batch generate project IDs from multiple sources
+ * Ensures no collisions within the batch and with existing IDs
+ */
+export function generateProjectIdsBatch(sources, existingIds = []) {
+    const results = new Map();
+    const allIds = [...existingIds];
+    for (const source of sources) {
+        const result = generateProjectId({
+            externalContainer: source.container,
+            localName: source.localName,
+            provider: source.provider,
+            existingIds: allIds,
+        });
+        // Add to tracking to prevent intra-batch collisions
+        allIds.push(result.id);
+        // Key by composite key for easy lookup
+        results.set(result.compositeKey, result);
+    }
+    return results;
+}
+/**
+ * Get existing project IDs from a SpecWeave project
+ *
+ * @param projectRoot Path to project root
+ * @returns Array of existing project IDs
+ */
+export function getExistingProjectIds(projectRoot) {
+    const specsDir = path.join(projectRoot, '.specweave', 'docs', 'internal', 'specs');
+    if (!fs.existsSync(specsDir)) {
+        return [];
+    }
+    try {
+        const entries = fs.readdirSync(specsDir, { withFileTypes: true });
+        return entries
+            .filter(entry => entry.isDirectory() && !entry.name.startsWith('_'))
+            .map(entry => entry.name);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Create 2-level directory structure for JIRA/ADO projects
+ *
+ * Structure:
+ * .specweave/docs/internal/specs/
+ * ├── JIRA-CORE/                  (external container level)
+ * │   ├── fe/                     (SpecWeave project level)
+ * │   ├── be/
+ * │   └── mobile/
+ * └── ADO-MyProduct/
+ *     ├── fe/
+ *     └── be/
+ *
+ * @param projectRoot Path to project root
+ * @param containerType Type of external container
+ * @param containerId External container ID (JIRA project key or ADO project name)
+ * @param specweaveProjectId SpecWeave project ID
+ */
+export function createTwoLevelProjectDir(projectRoot, containerType, containerId, specweaveProjectId) {
+    // Normalize container ID to directory-safe name
+    const containerDirName = `${containerType.toUpperCase()}-${normalizeToProjectId(containerId)}`;
+    const projectDirName = specweaveProjectId;
+    const fullPath = path.join(projectRoot, '.specweave', 'docs', 'internal', 'specs', containerDirName, projectDirName);
+    if (!fs.existsSync(fullPath)) {
+        fs.mkdirSync(fullPath, { recursive: true });
+    }
+    return fullPath;
+}
+/**
+ * Get the 2-level path for a project
+ *
+ * @param projectRoot Path to project root
+ * @param containerType Type of external container
+ * @param containerId External container ID
+ * @param specweaveProjectId SpecWeave project ID
+ * @returns Full path or undefined if using flat structure
+ */
+export function getTwoLevelProjectPath(projectRoot, containerType, containerId, specweaveProjectId) {
+    // If no container type, use flat structure (GitHub or single project)
+    if (!containerType || !containerId) {
+        return path.join(projectRoot, '.specweave', 'docs', 'internal', 'specs', specweaveProjectId);
+    }
+    // 2-level structure for JIRA/ADO
+    const containerDirName = `${containerType.toUpperCase()}-${normalizeToProjectId(containerId)}`;
+    return path.join(projectRoot, '.specweave', 'docs', 'internal', 'specs', containerDirName, specweaveProjectId);
+}
+/**
+ * Parse a 2-level project path to extract container and project info
+ *
+ * @param projectPath Path like ".specweave/docs/internal/specs/JIRA-CORE/fe"
+ * @returns Parsed container and project info
+ */
+export function parseTwoLevelPath(projectPath) {
+    // Match pattern: .../specs/{CONTAINER-TYPE-ID}/{PROJECT-ID}
+    const match = projectPath.match(/specs[/\\]((?:JIRA|ADO)-([^/\\]+))[/\\]([^/\\]+)/);
+    if (!match) {
+        // Try flat structure: .../specs/{PROJECT-ID}
+        const flatMatch = projectPath.match(/specs[/\\]([^/\\]+)$/);
+        if (flatMatch) {
+            return {
+                containerType: null,
+                containerId: null,
+                projectId: flatMatch[1],
+            };
+        }
+        return null;
+    }
+    const [, containerDir, containerId, projectId] = match;
+    const containerType = containerDir.startsWith('JIRA-') ? 'jira' : 'ado';
+    return {
+        containerType,
+        containerId,
+        projectId,
+    };
+}
+/**
+ * Validate project ID format
+ */
+export function isValidProjectId(id) {
+    return /^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/.test(id);
+}
+/**
+ * Suggest a valid project ID from an invalid one
+ */
+export function suggestProjectId(invalidId) {
+    const suggestion = normalizeToProjectId(invalidId);
+    return suggestion || 'project';
+}
+//# sourceMappingURL=project-id-generator.js.map

package/dist/src/utils/project-id-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-id-generator.js","sourceRoot":"","sources":["../../../src/utils/project-id-generator.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "0.28.17",
+  "version": "0.28.20",
   "description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
   "type": "module",
   "main": "dist/index.js",

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

@@ -615,6 +615,208 @@ With project-scoped stories:
 
 ---
 
+## 🌐 Multi-Project User Stories (v0.29.0+ - JIRA Boards/ADO Area Paths)
+
+**⚠️ CRITICAL: User Stories MUST Consider ALL Relevant Projects!**
+
+When working with enterprise setups where JIRA boards or ADO area paths map to SpecWeave projects, a single user story often spans MULTIPLE projects.
+
+### STEP 0C: Detect Multi-Project Mode (Board/Area Path Mapping)
+
+**YOU MUST CHECK THIS BEFORE WRITING ANY USER STORIES:**
+
+```bash
+# Check for JIRA board mapping
+cat .specweave/config.json | jq '.sync.profiles[].config.boardMapping'
+
+# Check for ADO area path mapping
+cat .specweave/config.json | jq '.sync.profiles[].config.areaPathMapping'
+
+# Check for 2-level spec structure
+ls -la .specweave/docs/internal/specs/JIRA-*/
+ls -la .specweave/docs/internal/specs/ADO-*/
+```
+
+**Decision Flow:**
+```
+Is boardMapping or areaPathMapping configured?
+  → YES → MUST use multi-project-aware user stories
+         Each US must list ALL affected projects with scope
+  → NO → Check for umbrella mode (see Step 0)
+         Use standard or project-scoped user stories
+```
+
+### Multi-Project User Story Format (v0.29.0+)
+
+**When board/area path mapping is detected, EVERY user story MUST:**
+
+1. List ALL projects it touches
+2. Define scope per project
+3. Identify cross-project dependencies
+
+**Example: OAuth Implementation Spanning 3 Projects**
+
+```markdown
+### US-001: OAuth Authentication (Priority: P0 - Critical)
+
+**Projects Involved**:
+| Project | Scope | Keywords |
+|---------|-------|----------|
+| BE (Backend Board) | OAuth API endpoints, token validation, session management | api, oauth, token, session |
+| FE (Frontend Board) | Login UI with OIDC, token storage, logout flow | ui, login, oidc, logout |
+| Shared | Common auth types, interfaces, JWT utilities | types, interfaces, jwt |
+
+**As a** user
+**I want** to log in using Google OAuth
+**So that** I can access the system without creating a new password
+
+**Cross-Project Dependencies**:
+- FE depends on Shared (auth types/interfaces)
+- BE depends on Shared (JWT utilities)
+- FE calls BE (OAuth callback API)
+
+**Acceptance Criteria**:
+
+**BE Project (Backend Board)**:
+- [ ] **AC-BE-US1-01**: POST /api/auth/oauth/google initiates OAuth flow
+  - Priority: P0
+  - Testable: Yes (integration test)
+- [ ] **AC-BE-US1-02**: GET /api/auth/oauth/callback processes OAuth response
+  - Priority: P0
+  - Testable: Yes (integration test)
+- [ ] **AC-BE-US1-03**: JWT tokens generated with 1-hour expiry
+  - Priority: P0
+  - Testable: Yes (unit test)
+
+**FE Project (Frontend Board)**:
+- [ ] **AC-FE-US1-01**: "Sign in with Google" button visible on login page
+  - Priority: P0
+  - Testable: Yes (E2E test)
+- [ ] **AC-FE-US1-02**: OAuth redirect handled correctly
+  - Priority: P0
+  - Testable: Yes (E2E test)
+- [ ] **AC-FE-US1-03**: Token stored securely in HTTP-only cookie
+  - Priority: P0
+  - Testable: Yes (security test)
+
+**Shared Project**:
+- [ ] **AC-SHARED-US1-01**: AuthUser interface defined with OAuth fields
+  - Priority: P0
+  - Testable: Yes (type check)
+- [ ] **AC-SHARED-US1-02**: JWT decode utility function
+  - Priority: P0
+  - Testable: Yes (unit test)
+```
+
+### spec.md Frontmatter for Multi-Project US
+
+```yaml
+---
+increment: 0001-oauth-implementation
+feature_id: FS-001
+status: active
+
+# Single project (legacy - backward compatible)
+# project: BE
+
+# Multi-project user story (v0.29.0+)
+projects:
+  - id: BE
+    scope: "OAuth API endpoints, token validation, session management"
+    keywords: ["api", "oauth", "token", "session"]
+    effort_percentage: 50
+  - id: FE
+    scope: "Login UI with OIDC, token storage, logout flow"
+    keywords: ["ui", "login", "oidc", "logout"]
+    effort_percentage: 35
+  - id: Shared
+    scope: "Common auth types, interfaces, JWT utilities"
+    keywords: ["types", "interfaces", "jwt"]
+    effort_percentage: 15
+
+cross_dependencies:
+  - from: FE
+    to: Shared
+    reason: "FE uses auth types from Shared"
+  - from: BE
+    to: Shared
+    reason: "BE uses JWT utilities from Shared"
+  - from: FE
+    to: BE
+    reason: "FE calls OAuth callback API"
+
+sync_strategy: linked  # 'linked' | 'primary-only' | 'all'
+primary_project: BE    # Which project owns the main issue
+---
+```
+
+### Sync Behavior for Multi-Project US
+
+**sync_strategy options**:
+
+| Strategy | Behavior |
+|----------|----------|
+| `linked` | Create main issue in primary_project, linked child issues in others |
+| `primary-only` | Only create issue in primary_project |
+| `all` | Create full issues in all projects (may cause duplication) |
+
+**Example: `linked` strategy with JIRA boards**:
+```
+JIRA Project: CORE
+
+Backend Board (BE project):
+  → CORE-123: [Epic] OAuth Authentication (parent)
+    → CORE-124: OAuth API endpoints
+    → CORE-125: Token validation
+
+Frontend Board (FE project):
+  → CORE-130: OAuth Login UI (linked to CORE-123)
+    → CORE-131: Google sign-in button
+    → CORE-132: Token storage
+
+Both boards can track progress, but CORE-123 is the parent epic.
+```
+
+### Why Multi-Project Awareness Matters
+
+**Without multi-project awareness**:
+- ❌ US created in ONE board/area only (wrong!)
+- ❌ Cross-team dependencies unclear
+- ❌ Frontend dev doesn't know backend is a blocker
+- ❌ Shared changes not communicated to dependent teams
+- ❌ Progress tracking incomplete
+
+**With multi-project awareness**:
+- ✅ Each board/area gets relevant ACs
+- ✅ Clear cross-project dependencies
+- ✅ All teams know their scope
+- ✅ Linked issues enable coordination
+- ✅ Progress tracked across all projects
+
+### PM Agent Workflow for Multi-Project US
+
+1. **Detect** board/area path mapping in config.json
+2. **Analyze** user story for multi-project scope
+3. **Ask** user: "This feature spans BE, FE, and Shared. Should I create linked issues?"
+4. **Generate** spec.md with `projects` array in frontmatter
+5. **Create** ACs grouped by project (AC-BE-*, AC-FE-*, AC-SHARED-*)
+6. **Document** cross-project dependencies
+7. **Sync** to external tool based on sync_strategy
+
+### Validation Checklist for Multi-Project US
+
+Before finalizing any user story:
+
+- [ ] Analyzed scope across ALL configured projects (BE, FE, Shared, etc.)
+- [ ] `projects` array in frontmatter lists all affected projects
+- [ ] Each project has defined scope and keywords
+- [ ] ACs are grouped by project with correct prefixes
+- [ ] Cross-project dependencies documented
+- [ ] sync_strategy explicitly chosen
+- [ ] primary_project designated for linked strategy
+
+---
+
 **Role**: Product Manager specialized in product strategy, requirements gathering, and feature prioritization.
 
 ## Purpose

package/plugins/specweave/commands/specweave-import-external.md

@@ -1,11 +1,13 @@
 ---
 name: specweave:import-external
-description: Manually pull external work items from GitHub, JIRA, or Azure DevOps into living docs. Supports time range filtering, platform selection, and dry-run mode for ongoing imports after initial setup.
+description: Pull external work items from GitHub, JIRA, or Azure DevOps into living docs as READ-ONLY REFERENCES (not increments). To implement imported items, manually create an increment. Supports time range filtering and dry-run mode.
 ---
 
-# Import External Work Items
+# Import External Work Items (Reference Import)
 
-Import work items from GitHub (issues/milestones), JIRA (epics/stories), or Azure DevOps (work items) into SpecWeave living docs.
+Import work items from GitHub (issues/milestones), JIRA (epics/stories), or Azure DevOps (work items) into SpecWeave living docs **as read-only references**.
+
+> **Important**: This command creates a **reference catalog**, NOT increments. Imported items have E-suffix IDs (US-001E, FS-042E). To implement an imported item, you must **manually create an increment** that references it.
 
 ## What This Does