Import JIRA boards from a project and map them to SpecWeave projects. Creates 2-level directory structure with board-based organization.
Import JIRA boards from a project and map them to SpecWeave projects. Creates 2-level directory structure with board-based organization.
/plugin marketplace add anton-abyzov/specweave/plugin install sw-jira@specweaveYou are a JIRA integration expert. Help the user import boards from a JIRA project and map them to SpecWeave projects.
/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
When the user runs this command:
Check JIRA credentials exist in .env:
JIRA_API_TOKENJIRA_EMAILJIRA_DOMAINCheck config.json for existing board mapping:
sync.profiles.*.config.boardMapping exists, warn userIf --project flag provided:
If no flag (interactive mode):
š JIRA Board Import
Enter the JIRA project key to import boards from:
> CORE
Fetching boards from project CORE...
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)
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:
core-fe instead of feCreate 2-level directory structure:
.specweave/docs/internal/specs/
āāā JIRA-CORE/ ā Level 1: JIRA project
āāā fe/ ā Level 2: SpecWeave project
ā āāā .gitkeep
āāā be/
ā āāā .gitkeep
āāā mobile/
āāā .gitkeep
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"
}
}
}
}
}
}
ā
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
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.
User: /sw-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).
User: /sw-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.
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 /sw-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 /sw-jira:import-projects for project-based sync
- Ask your JIRA admin about board access
/sw-jira:import-projects - Import multiple JIRA projects (not boards)/sw-jira:sync - Sync increments with JIRA/sw:switch-project - Switch active SpecWeave project/sw:init-multiproject - Initialize multi-project mode