gh-anton-abyzov-specweave-plugins-specweave-ado/commands/specweave-ado-import-areas.md

name, description

name	description
specweave-ado:import-areas	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

/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

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:

{
  "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