/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

sw-jira:import-boards                      # Interactive mode (prompts for project)
sw-jira:import-boards --project CORE       # Specific JIRA project
sw-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

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:

{
  "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 sw:switch-project fe to switch active project
  2. Create increment: sw: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: sw-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: sw-jira:import-boards --project CORE --dry-run

You:
📋 JIRA Board Import (DRY RUN)

Would import from project: CORE

Would create:
  .specweav