Initial commit
This commit is contained in:
Zhongwei Li
331
commands/specweave-jira-import-boards.md
Normal file
331
commands/specweave-jira-import-boards.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user