359 lines
9.3 KiB
Markdown
359 lines
9.3 KiB
Markdown
---
|
|
name: specweave-ado:import-areas
|
|
description: Import Azure DevOps area paths from a project and map them to SpecWeave projects. Creates 2-level directory structure with area path-based organization.
|
|
---
|
|
|
|
# Import ADO Area Paths Command
|
|
|
|
You are an Azure DevOps integration expert. Help the user import area paths from an ADO project and map them to SpecWeave projects.
|
|
|
|
## Command Usage
|
|
|
|
```bash
|
|
/specweave-ado:import-areas # Interactive mode (prompts for project)
|
|
/specweave-ado:import-areas --project MyProduct # Specific ADO project
|
|
/specweave-ado:import-areas --dry-run # Preview without creating directories
|
|
/specweave-ado:import-areas --include-children # Include child area paths
|
|
```
|
|
|
|
## Your Task
|
|
|
|
When the user runs this command:
|
|
|
|
### Step 1: Validate Prerequisites
|
|
|
|
1. **Check ADO credentials** exist in `.env`:
|
|
- `AZURE_DEVOPS_PAT`
|
|
- `AZURE_DEVOPS_ORG`
|
|
- `AZURE_DEVOPS_PROJECT`
|
|
|
|
2. **Check config.json** for existing area path mapping:
|
|
- If `sync.profiles.*.config.areaPathMapping` exists, warn user
|
|
|
|
### Step 2: Get Project Name
|
|
|
|
**If `--project` flag provided:**
|
|
- Use the provided project name
|
|
|
|
**If no flag (interactive mode):**
|
|
```
|
|
🔷 Azure DevOps Area Path Import
|
|
|
|
Enter the ADO project name to import area paths from:
|
|
> MyProduct
|
|
|
|
Fetching area paths from project MyProduct...
|
|
```
|
|
|
|
### Step 3: Fetch and Display Area Paths
|
|
|
|
```typescript
|
|
import { fetchAreaPathsForProject } from '../lib/ado-board-resolver';
|
|
|
|
const areaPaths = await fetchAreaPathsForProject(
|
|
process.env.AZURE_DEVOPS_ORG,
|
|
'MyProduct',
|
|
process.env.AZURE_DEVOPS_PAT
|
|
);
|
|
```
|
|
|
|
**Display area paths:**
|
|
```
|
|
Found 6 area paths in project MyProduct:
|
|
|
|
1. ☑ MyProduct\Frontend (45 active items)
|
|
2. ☑ MyProduct\Backend (78 active items)
|
|
3. ☑ MyProduct\Mobile (23 active items)
|
|
4. ☑ MyProduct\DevOps (12 active items)
|
|
5. ☐ MyProduct\Archive (0 items) [deselected - archive]
|
|
6. ☐ MyProduct (root) [deselected - root level]
|
|
|
|
Select area paths to import (Space to toggle, Enter to confirm)
|
|
```
|
|
|
|
### Step 4: Map Area Paths to SpecWeave Projects
|
|
|
|
For each selected area path, prompt for SpecWeave project ID:
|
|
|
|
```
|
|
🏷️ Mapping area paths to SpecWeave projects:
|
|
|
|
Area path "MyProduct\Frontend" → SpecWeave project ID: [fe]
|
|
→ Include child area paths? [Y/n]: y
|
|
→ Keywords for auto-classification (optional): frontend, ui, angular, css
|
|
|
|
Area path "MyProduct\Backend" → SpecWeave project ID: [be]
|
|
→ Include child area paths? [Y/n]: y
|
|
→ Keywords for auto-classification (optional): api, server, database, c#
|
|
|
|
Area path "MyProduct\Mobile" → SpecWeave project ID: [mobile]
|
|
→ Include child area paths? [Y/n]: y
|
|
→ Keywords for auto-classification (optional): ios, android, xamarin
|
|
|
|
Area path "MyProduct\DevOps" → SpecWeave project ID: [devops]
|
|
→ Include child area paths? [Y/n]: y
|
|
→ Keywords for auto-classification (optional): infrastructure, ci, cd, terraform
|
|
```
|
|
|
|
**Project ID validation:**
|
|
- Must be lowercase, alphanumeric with hyphens
|
|
- Must not collide with existing project IDs
|
|
- If collision detected, suggest prefixed version: `myproduct-fe` instead of `fe`
|
|
|
|
### Step 5: Create Directory Structure
|
|
|
|
Create 2-level directory structure:
|
|
|
|
```
|
|
.specweave/docs/internal/specs/
|
|
└── ADO-myproduct/ ← Level 1: ADO project
|
|
├── fe/ ← Level 2: SpecWeave project
|
|
│ └── .gitkeep
|
|
├── be/
|
|
│ └── .gitkeep
|
|
├── mobile/
|
|
│ └── .gitkeep
|
|
└── devops/
|
|
└── .gitkeep
|
|
```
|
|
|
|
### Step 6: Update config.json
|
|
|
|
Add area path mapping to config:
|
|
|
|
```json
|
|
{
|
|
"sync": {
|
|
"profiles": {
|
|
"ado-default": {
|
|
"provider": "ado",
|
|
"config": {
|
|
"organization": "myorg",
|
|
"areaPathMapping": {
|
|
"project": "MyProduct",
|
|
"mappings": [
|
|
{
|
|
"areaPath": "MyProduct\\Frontend",
|
|
"specweaveProject": "fe",
|
|
"includeChildren": true,
|
|
"keywords": ["frontend", "ui", "angular", "css"]
|
|
},
|
|
{
|
|
"areaPath": "MyProduct\\Backend",
|
|
"specweaveProject": "be",
|
|
"includeChildren": true,
|
|
"keywords": ["api", "server", "database", "c#"]
|
|
},
|
|
{
|
|
"areaPath": "MyProduct\\Mobile",
|
|
"specweaveProject": "mobile",
|
|
"includeChildren": true,
|
|
"keywords": ["ios", "android", "xamarin"]
|
|
},
|
|
{
|
|
"areaPath": "MyProduct\\DevOps",
|
|
"specweaveProject": "devops",
|
|
"includeChildren": true,
|
|
"keywords": ["infrastructure", "ci", "cd", "terraform"]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"multiProject": {
|
|
"enabled": true,
|
|
"activeProject": "fe",
|
|
"projects": {
|
|
"fe": {
|
|
"name": "Frontend",
|
|
"externalTools": {
|
|
"ado": {
|
|
"areaPath": "MyProduct\\Frontend",
|
|
"project": "MyProduct"
|
|
}
|
|
}
|
|
},
|
|
"be": {
|
|
"name": "Backend",
|
|
"externalTools": {
|
|
"ado": {
|
|
"areaPath": "MyProduct\\Backend",
|
|
"project": "MyProduct"
|
|
}
|
|
}
|
|
},
|
|
"mobile": {
|
|
"name": "Mobile",
|
|
"externalTools": {
|
|
"ado": {
|
|
"areaPath": "MyProduct\\Mobile",
|
|
"project": "MyProduct"
|
|
}
|
|
}
|
|
},
|
|
"devops": {
|
|
"name": "DevOps",
|
|
"externalTools": {
|
|
"ado": {
|
|
"areaPath": "MyProduct\\DevOps",
|
|
"project": "MyProduct"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Step 7: Display Summary
|
|
|
|
```
|
|
✅ Azure DevOps Area Paths Import Complete!
|
|
|
|
🔷 ADO Project: MyProduct
|
|
📁 Created: .specweave/docs/internal/specs/ADO-myproduct/
|
|
|
|
Area paths imported:
|
|
✓ MyProduct\Frontend → fe (includes children)
|
|
Keywords: frontend, ui, angular, css
|
|
✓ MyProduct\Backend → be (includes children)
|
|
Keywords: api, server, database, c#
|
|
✓ MyProduct\Mobile → mobile (includes children)
|
|
Keywords: ios, android, xamarin
|
|
✓ MyProduct\DevOps → devops (includes children)
|
|
Keywords: infrastructure, ci, cd, terraform
|
|
|
|
💡 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 area path based on keywords
|
|
|
|
📖 Documentation: .specweave/docs/internal/architecture/adr/0143-jira-ado-multi-level-project-mapping.md
|
|
```
|
|
|
|
## Examples
|
|
|
|
### Example 1: Interactive Import
|
|
```
|
|
User: /specweave-ado:import-areas
|
|
|
|
You:
|
|
🔷 Azure DevOps Area Path Import
|
|
|
|
Enter the ADO project name: MyProduct
|
|
Fetching area paths...
|
|
|
|
Found 4 area paths:
|
|
☑ MyProduct\Frontend
|
|
☑ MyProduct\Backend
|
|
☑ MyProduct\Mobile
|
|
☐ MyProduct (root) [deselected]
|
|
|
|
Mapping to SpecWeave projects:
|
|
MyProduct\Frontend → fe
|
|
MyProduct\Backend → be
|
|
MyProduct\Mobile → mobile
|
|
|
|
✅ Import complete! 3 area paths mapped.
|
|
```
|
|
|
|
### Example 2: Dry Run
|
|
```
|
|
User: /specweave-ado:import-areas --project MyProduct --dry-run
|
|
|
|
You:
|
|
🔷 Azure DevOps Area Path Import (DRY RUN)
|
|
|
|
Would import from project: MyProduct
|
|
|
|
Would create:
|
|
.specweave/docs/internal/specs/ADO-myproduct/
|
|
.specweave/docs/internal/specs/ADO-myproduct/fe/
|
|
.specweave/docs/internal/specs/ADO-myproduct/be/
|
|
.specweave/docs/internal/specs/ADO-myproduct/mobile/
|
|
|
|
Would update config.json with area path mapping.
|
|
|
|
No changes made (dry run).
|
|
```
|
|
|
|
### Example 3: Already Configured
|
|
```
|
|
User: /specweave-ado:import-areas
|
|
|
|
You:
|
|
⚠️ Area path mapping already exists for project MyProduct
|
|
|
|
Current mappings:
|
|
MyProduct\Frontend → fe
|
|
MyProduct\Backend → be
|
|
|
|
Do you want to:
|
|
1. Add more area paths
|
|
2. Replace existing mapping
|
|
3. Cancel
|
|
|
|
> 1
|
|
|
|
Fetching additional area paths...
|
|
☐ MyProduct\Frontend (already mapped)
|
|
☐ MyProduct\Backend (already mapped)
|
|
☑ MyProduct\Mobile (new)
|
|
☑ MyProduct\DevOps (new)
|
|
|
|
Added:
|
|
MyProduct\Mobile → mobile
|
|
MyProduct\DevOps → devops
|
|
|
|
✅ Updated! Now 4 area paths mapped.
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
**Missing credentials:**
|
|
```
|
|
❌ Azure DevOps credentials not found
|
|
|
|
Please add to .env:
|
|
AZURE_DEVOPS_PAT=your_personal_access_token
|
|
AZURE_DEVOPS_ORG=your_organization
|
|
AZURE_DEVOPS_PROJECT=your_project
|
|
|
|
Or run: specweave init . (to configure Azure DevOps)
|
|
```
|
|
|
|
**Project not found:**
|
|
```
|
|
❌ ADO project "INVALID" not found in organization "myorg"
|
|
|
|
Available projects you have access to:
|
|
- MyProduct (My Product Development)
|
|
- Infrastructure (DevOps & Infrastructure)
|
|
- Legacy (Legacy Systems)
|
|
|
|
Tip: Use /specweave-ado:import-areas --project MyProduct
|
|
```
|
|
|
|
**No area paths found:**
|
|
```
|
|
⚠️ No child area paths found in project MyProduct
|
|
|
|
The project only has the root area path. This means:
|
|
1. Teams aren't using area paths for organization
|
|
2. You can create area paths in ADO Project Settings
|
|
|
|
Suggestions:
|
|
- Use single-project mode (no area path mapping)
|
|
- Create area paths in ADO: Project Settings → Work → Areas
|
|
- Run this command again after creating area paths
|
|
```
|
|
|
|
## Related Commands
|
|
|
|
- `/specweave-ado:import-projects` - Import multiple ADO projects
|
|
- `/specweave-ado:sync` - Sync increments with ADO
|
|
- `/specweave:switch-project` - Switch active SpecWeave project
|
|
- `/specweave:init-multiproject` - Initialize multi-project mode
|