specweave 0.28.17 → 0.28.20

package/plugins/specweave-jira/commands/specweave-jira-import-boards.md

@@ -0,0 +1,331 @@
+---
+name: specweave-jira:import-boards
+description: Import JIRA boards from a project and map them to SpecWeave projects. Creates 2-level directory structure with board-based organization.
+---
+
+# Import JIRA Boards Command
+
+You are a JIRA integration expert. Help the user import boards from a JIRA project and map them to SpecWeave projects.
+
+## Command Usage
+
+```bash
+/specweave-jira:import-boards                      # Interactive mode (prompts for project)
+/specweave-jira:import-boards --project CORE       # Specific JIRA project
+/specweave-jira:import-boards --dry-run            # Preview without creating directories
+```
+
+## Your Task
+
+When the user runs this command:
+
+### Step 1: Validate Prerequisites
+
+1. **Check JIRA credentials** exist in `.env`:
+   - `JIRA_API_TOKEN`
+   - `JIRA_EMAIL`
+   - `JIRA_DOMAIN`
+
+2. **Check config.json** for existing board mapping:
+   - If `sync.profiles.*.config.boardMapping` exists, warn user
+
+### Step 2: Get Project Key
+
+**If `--project` flag provided:**
+- Use the provided project key
+
+**If no flag (interactive mode):**
+```
+📋 JIRA Board Import
+
+Enter the JIRA project key to import boards from:
+> CORE
+
+Fetching boards from project CORE...
+```
+
+### Step 3: Fetch and Display Boards
+
+```typescript
+import { JiraClient } from '../../../src/integrations/jira/jira-client';
+import { fetchBoardsForProject } from '../lib/jira-board-resolver';
+
+const client = new JiraClient({
+  domain: process.env.JIRA_DOMAIN,
+  email: process.env.JIRA_EMAIL,
+  apiToken: process.env.JIRA_API_TOKEN,
+  instanceType: 'cloud'
+});
+
+const boards = await fetchBoardsForProject(client, 'CORE');
+```
+
+**Display boards:**
+```
+Found 5 boards in project CORE:
+
+  1. ☑ Frontend Board (Scrum, 23 active items)
+  2. ☑ Backend Board (Kanban, 45 active items)
+  3. ☑ Mobile Board (Scrum, 12 active items)
+  4. ☐ Platform Board (Kanban, 3 active items)
+  5. ☐ Archive Board (Simple, 0 items) [deselected - archive]
+
+Select boards to import (Space to toggle, Enter to confirm)
+```
+
+### Step 4: Map Boards to SpecWeave Projects
+
+For each selected board, prompt for SpecWeave project ID:
+
+```
+🏷️  Mapping boards to SpecWeave projects:
+
+Board "Frontend Board" → SpecWeave project ID: [fe]
+  → Keywords for auto-classification (optional): frontend, ui, react, css
+
+Board "Backend Board" → SpecWeave project ID: [be]
+  → Keywords for auto-classification (optional): api, server, database
+
+Board "Mobile Board" → SpecWeave project ID: [mobile]
+  → Keywords for auto-classification (optional): ios, android, react-native
+```
+
+**Project ID validation:**
+- Must be lowercase, alphanumeric with hyphens
+- Must not collide with existing project IDs
+- If collision detected, suggest prefixed version: `core-fe` instead of `fe`
+
+### Step 5: Create Directory Structure
+
+Create 2-level directory structure:
+
+```
+.specweave/docs/internal/specs/
+└── JIRA-CORE/                  ← Level 1: JIRA project
+    ├── fe/                     ← Level 2: SpecWeave project
+    │   └── .gitkeep
+    ├── be/
+    │   └── .gitkeep
+    └── mobile/
+        └── .gitkeep
+```
+
+### Step 6: Update config.json
+
+Add board mapping to config:
+
+```json
+{
+  "sync": {
+    "profiles": {
+      "jira-default": {
+        "provider": "jira",
+        "config": {
+          "domain": "example.atlassian.net",
+          "boardMapping": {
+            "projectKey": "CORE",
+            "boards": [
+              {
+                "boardId": 123,
+                "boardName": "Frontend Board",
+                "specweaveProject": "fe",
+                "boardType": "scrum",
+                "keywords": ["frontend", "ui", "react", "css"]
+              },
+              {
+                "boardId": 456,
+                "boardName": "Backend Board",
+                "specweaveProject": "be",
+                "boardType": "kanban",
+                "keywords": ["api", "server", "database"]
+              },
+              {
+                "boardId": 789,
+                "boardName": "Mobile Board",
+                "specweaveProject": "mobile",
+                "boardType": "scrum",
+                "keywords": ["ios", "android", "react-native"]
+              }
+            ]
+          }
+        }
+      }
+    }
+  },
+  "multiProject": {
+    "enabled": true,
+    "activeProject": "fe",
+    "projects": {
+      "fe": {
+        "name": "Frontend",
+        "externalTools": {
+          "jira": {
+            "boardId": 123,
+            "projectKey": "CORE"
+          }
+        }
+      },
+      "be": {
+        "name": "Backend",
+        "externalTools": {
+          "jira": {
+            "boardId": 456,
+            "projectKey": "CORE"
+          }
+        }
+      },
+      "mobile": {
+        "name": "Mobile",
+        "externalTools": {
+          "jira": {
+            "boardId": 789,
+            "projectKey": "CORE"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Step 7: Display Summary
+
+```
+✅ JIRA Boards Import Complete!
+
+📋 JIRA Project: CORE
+📁 Created: .specweave/docs/internal/specs/JIRA-CORE/
+
+Boards imported:
+  ✓ Frontend Board (scrum) → fe
+    Keywords: frontend, ui, react, css
+  ✓ Backend Board (kanban) → be
+    Keywords: api, server, database
+  ✓ Mobile Board (scrum) → mobile
+    Keywords: ios, android, react-native
+
+💡 Next steps:
+  1. Use /specweave:switch-project fe to switch active project
+  2. Create increment: /specweave:increment "feature name"
+  3. User stories will auto-sync to the correct board based on keywords
+
+📖 Documentation: .specweave/docs/internal/architecture/adr/0143-jira-ado-multi-level-project-mapping.md
+```
+
+## Examples
+
+### Example 1: Interactive Import
+```
+User: /specweave-jira:import-boards
+
+You:
+📋 JIRA Board Import
+
+Enter the JIRA project key: CORE
+Fetching boards...
+
+Found 3 boards:
+  ☑ Frontend Board (scrum)
+  ☑ Backend Board (kanban)
+  ☐ Archive (simple) [deselected]
+
+Mapping to SpecWeave projects:
+  Frontend Board → fe
+  Backend Board → be
+
+✅ Import complete! 2 boards mapped.
+```
+
+### Example 2: Dry Run
+```
+User: /specweave-jira:import-boards --project CORE --dry-run
+
+You:
+📋 JIRA Board Import (DRY RUN)
+
+Would import from project: CORE
+
+Would create:
+  .specweave/docs/internal/specs/JIRA-CORE/
+  .specweave/docs/internal/specs/JIRA-CORE/fe/
+  .specweave/docs/internal/specs/JIRA-CORE/be/
+
+Would update config.json with board mapping.
+
+No changes made (dry run).
+```
+
+### Example 3: Already Configured
+```
+User: /specweave-jira:import-boards
+
+You:
+⚠️  Board mapping already exists for project CORE
+
+Current mappings:
+  Frontend Board → fe
+  Backend Board → be
+
+Do you want to:
+  1. Add more boards
+  2. Replace existing mapping
+  3. Cancel
+
+> 1
+
+Fetching additional boards...
+  ☐ Frontend Board (already mapped)
+  ☐ Backend Board (already mapped)
+  ☑ Mobile Board (new)
+  ☐ Archive (deselected)
+
+Added Mobile Board → mobile
+
+✅ Updated! Now 3 boards mapped.
+```
+
+## Error Handling
+
+**Missing credentials:**
+```
+❌ JIRA credentials not found
+
+Please add to .env:
+  JIRA_API_TOKEN=your_token
+  JIRA_EMAIL=your_email@example.com
+  JIRA_DOMAIN=your-company.atlassian.net
+
+Or run: specweave init . (to configure JIRA)
+```
+
+**Project not found:**
+```
+❌ JIRA project "INVALID" not found
+
+Available projects you have access to:
+  - CORE (Core Development)
+  - INFRA (Infrastructure)
+  - MOBILE (Mobile Team)
+
+Tip: Use /specweave-jira:import-boards --project CORE
+```
+
+**No boards found:**
+```
+⚠️  No boards found in project CORE
+
+This could mean:
+  1. The project uses classic projects (no boards)
+  2. You don't have access to boards in this project
+
+Suggestions:
+  - Use /specweave-jira:import-projects for project-based sync
+  - Ask your JIRA admin about board access
+```
+
+## Related Commands
+
+- `/specweave-jira:import-projects` - Import multiple JIRA projects (not boards)
+- `/specweave-jira:sync` - Sync increments with JIRA
+- `/specweave:switch-project` - Switch active SpecWeave project
+- `/specweave:init-multiproject` - Initialize multi-project mode

package/plugins/specweave-jira/lib/jira-spec-sync.js

@@ -132,6 +132,7 @@ class JiraSpecSync {
   async createJiraEpic(spec) {
     const epicSummary = `[${spec.metadata.id.toUpperCase()}] ${spec.metadata.title}`;
     const epicDescription = this.generateEpicDescription(spec);
+    const issueType = this.mapTypeToJira(spec.metadata.type, "Epic");
     const payload = {
       fields: {
         project: {
@@ -140,9 +141,13 @@ class JiraSpecSync {
         summary: epicSummary,
         description: epicDescription,
         issuetype: {
-          name: "Epic"
+          name: issueType
         },
-        labels: [`spec:${spec.metadata.id}`, `priority:${spec.metadata.priority}`]
+        labels: [`spec:${spec.metadata.id}`, `priority:${spec.metadata.priority}`],
+        // Set native JIRA priority field (P0→Highest, P1→High, P2→Medium, P3→Low)
+        priority: {
+          name: this.mapPriorityToJira(spec.metadata.priority)
+        }
       }
     };
     const response = await this.client.post("/issue", payload);
@@ -213,7 +218,8 @@ class JiraSpecSync {
           summary: storySummary,
           description: storyDescription,
           epicLink: epicKey,
-          labels: [`user-story`, `spec:${spec.metadata.id}`, `priority:${us.priority}`]
+          labels: [`user-story`, `spec:${spec.metadata.id}`, `priority:${us.priority}`],
+          priority: us.priority
         });
         created.push(us.id);
         console.log(`   \u2705 Created ${us.id} \u2192 Story ${newStory.key}`);
@@ -347,6 +353,7 @@ ${acList}
    * Create Jira Story
    */
   async createStory(story) {
+    const issueType = this.mapTypeToJira(story.type, "Story");
     const payload = {
       fields: {
         project: {
@@ -355,12 +362,16 @@ ${acList}
         summary: story.summary,
         description: story.description,
         issuetype: {
-          name: "Story"
+          name: issueType
         },
         labels: story.labels,
         // Link to epic (field name may vary by Jira configuration)
-        customfield_10014: story.epicLink
+        customfield_10014: story.epicLink,
         // Epic Link field (adjust if needed)
+        // Set native JIRA priority field
+        priority: {
+          name: this.mapPriorityToJira(story.priority)
+        }
       }
     };
     const response = await this.client.post("/issue", payload);
@@ -411,6 +422,43 @@ ${acList}
       }
     });
   }
+  /**
+   * Map SpecWeave priority to JIRA priority name
+   *
+   * JIRA standard priority names: Highest, High, Medium, Low, Lowest
+   */
+  mapPriorityToJira(priority) {
+    if (!priority) return "Medium";
+    const map = {
+      P0: "Highest",
+      P1: "High",
+      P2: "Medium",
+      P3: "Low",
+      p0: "Highest",
+      p1: "High",
+      p2: "Medium",
+      p3: "Low"
+    };
+    return map[priority] || "Medium";
+  }
+  /**
+   * Map SpecWeave type to JIRA issue type
+   *
+   * Supports: Epic, Story, Bug, Task
+   */
+  mapTypeToJira(type, defaultType = "Story") {
+    if (!type) return defaultType;
+    const normalizedType = type.toLowerCase();
+    const map = {
+      bug: "Bug",
+      feature: "Epic",
+      epic: "Epic",
+      story: "Story",
+      task: "Task",
+      enhancement: "Story"
+    };
+    return map[normalizedType] || defaultType;
+  }
 }
 export {
   JiraSpecSync

package/plugins/specweave-jira/lib/jira-spec-sync.ts

@@ -223,7 +223,19 @@ export class JiraSpecSync {
     const epicSummary = `[${spec.metadata.id.toUpperCase()}] ${spec.metadata.title}`;
     const epicDescription = this.generateEpicDescription(spec);
 
-    const payload = {
+    // Determine issue type based on spec type (supports Bug for bug-type specs)
+    const issueType = this.mapTypeToJira(spec.metadata.type, 'Epic');
+
+    const payload: {
+      fields: {
+        project: { key: string };
+        summary: string;
+        description: string;
+        issuetype: { name: string };
+        labels: string[];
+        priority?: { name: string };
+      };
+    } = {
       fields: {
         project: {
           key: this.config.projectKey
@@ -231,9 +243,13 @@ export class JiraSpecSync {
         summary: epicSummary,
         description: epicDescription,
         issuetype: {
-          name: 'Epic'
+          name: issueType
         },
-        labels: [`spec:${spec.metadata.id}`, `priority:${spec.metadata.priority}`]
+        labels: [`spec:${spec.metadata.id}`, `priority:${spec.metadata.priority}`],
+        // Set native JIRA priority field (P0→Highest, P1→High, P2→Medium, P3→Low)
+        priority: {
+          name: this.mapPriorityToJira(spec.metadata.priority)
+        }
       }
     };
 
@@ -329,7 +345,8 @@ export class JiraSpecSync {
           summary: storySummary,
           description: storyDescription,
           epicLink: epicKey,
-          labels: [`user-story`, `spec:${spec.metadata.id}`, `priority:${us.priority}`]
+          labels: [`user-story`, `spec:${spec.metadata.id}`, `priority:${us.priority}`],
+          priority: us.priority
         });
 
         created.push(us.id);
@@ -497,8 +514,23 @@ ${acList}
     description: string;
     epicLink: string;
     labels: string[];
+    priority?: string;
+    type?: string;
   }): Promise<JiraStory> {
-    const payload = {
+    // Determine issue type (supports Bug for bug-type stories)
+    const issueType = this.mapTypeToJira(story.type, 'Story');
+
+    const payload: {
+      fields: {
+        project: { key: string };
+        summary: string;
+        description: string;
+        issuetype: { name: string };
+        labels: string[];
+        customfield_10014: string;
+        priority?: { name: string };
+      };
+    } = {
       fields: {
         project: {
           key: this.config.projectKey
@@ -506,11 +538,15 @@ ${acList}
         summary: story.summary,
         description: story.description,
         issuetype: {
-          name: 'Story'
+          name: issueType
         },
         labels: story.labels,
         // Link to epic (field name may vary by Jira configuration)
-        customfield_10014: story.epicLink // Epic Link field (adjust if needed)
+        customfield_10014: story.epicLink, // Epic Link field (adjust if needed)
+        // Set native JIRA priority field
+        priority: {
+          name: this.mapPriorityToJira(story.priority)
+        }
       }
     };
 
@@ -579,4 +615,48 @@ ${acList}
       }
     });
   }
+
+  /**
+   * Map SpecWeave priority to JIRA priority name
+   *
+   * JIRA standard priority names: Highest, High, Medium, Low, Lowest
+   */
+  private mapPriorityToJira(priority?: string): string {
+    if (!priority) return 'Medium';
+
+    const map: Record<string, string> = {
+      P0: 'Highest',
+      P1: 'High',
+      P2: 'Medium',
+      P3: 'Low',
+      p0: 'Highest',
+      p1: 'High',
+      p2: 'Medium',
+      p3: 'Low'
+    };
+
+    return map[priority] || 'Medium';
+  }
+
+  /**
+   * Map SpecWeave type to JIRA issue type
+   *
+   * Supports: Epic, Story, Bug, Task
+   */
+  private mapTypeToJira(type?: string, defaultType: string = 'Story'): string {
+    if (!type) return defaultType;
+
+    const normalizedType = type.toLowerCase();
+
+    const map: Record<string, string> = {
+      bug: 'Bug',
+      feature: 'Epic',
+      epic: 'Epic',
+      story: 'Story',
+      task: 'Task',
+      enhancement: 'Story'
+    };
+
+    return map[normalizedType] || defaultType;
+  }
 }

package/plugins/specweave-jira/lib/jira-status-sync.js

@@ -33,25 +33,31 @@ class JiraStatusSync {
    * JIRA requires using transitions to change status.
    * Cannot directly set status field.
    *
+   * Handles missing transitions gracefully by logging a warning
+   * instead of throwing an error.
+   *
    * @param issueKey - JIRA issue key (e.g., PROJ-123)
    * @param status - Desired status
+   * @returns true if transition succeeded, false if not available
    */
   async updateStatus(issueKey, status) {
     const transitionsResponse = await this.client.get(`/issue/${issueKey}/transitions`);
     const transitions = transitionsResponse.data.transitions;
     const targetTransition = transitions.find(
-      (t) => t.to.name === status.state
+      (t) => t.to.name.toLowerCase() === status.state.toLowerCase()
     );
     if (!targetTransition) {
-      throw new Error(
-        `Transition to ${status.state} not available for ${issueKey}. Available transitions: ${transitions.map((t) => t.to.name).join(", ")}`
+      console.warn(
+        `\u26A0\uFE0F  Cannot transition ${issueKey} to "${status.state}". Available transitions: ${transitions.map((t) => t.to.name).join(", ")}. This may be expected if your JIRA workflow doesn't support this status.`
       );
+      return false;
     }
     await this.client.post(`/issue/${issueKey}/transitions`, {
       transition: {
         id: targetTransition.id
       }
     });
+    return true;
   }
   /**
    * Post comment about status change to JIRA issue

package/plugins/specweave-jira/lib/jira-status-sync.ts

@@ -85,24 +85,31 @@ export class JiraStatusSync {
    * JIRA requires using transitions to change status.
    * Cannot directly set status field.
    *
+   * Handles missing transitions gracefully by logging a warning
+   * instead of throwing an error.
+   *
    * @param issueKey - JIRA issue key (e.g., PROJ-123)
    * @param status - Desired status
+   * @returns true if transition succeeded, false if not available
    */
-  async updateStatus(issueKey: string, status: ExternalStatus): Promise<void> {
+  async updateStatus(issueKey: string, status: ExternalStatus): Promise<boolean> {
     // 1. Get available transitions for this issue
     const transitionsResponse = await this.client.get(`/issue/${issueKey}/transitions`);
     const transitions: JiraTransition[] = transitionsResponse.data.transitions;
 
-    // 2. Find transition that leads to desired status
+    // 2. Find transition that leads to desired status (case-insensitive)
     const targetTransition = transitions.find(
-      (t) => t.to.name === status.state
+      (t) => t.to.name.toLowerCase() === status.state.toLowerCase()
     );
 
     if (!targetTransition) {
-      throw new Error(
-        `Transition to ${status.state} not available for ${issueKey}. ` +
-        `Available transitions: ${transitions.map(t => t.to.name).join(', ')}`
+      // Log warning instead of throwing - workflow may not support this transition
+      console.warn(
+        `⚠️  Cannot transition ${issueKey} to "${status.state}". ` +
+        `Available transitions: ${transitions.map(t => t.to.name).join(', ')}. ` +
+        `This may be expected if your JIRA workflow doesn't support this status.`
       );
+      return false;
     }
 
     // 3. Execute transition
@@ -111,6 +118,8 @@ export class JiraStatusSync {
         id: targetTransition.id
       }
     });
+
+    return true;
   }
 
   /**