332 lines
7.8 KiB
Markdown
332 lines
7.8 KiB
Markdown
---
|
|
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
|