/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

sw-ado:import-areas                         # Interactive mode (prompts for project)
sw-ado:import-areas --project MyProduct     # Specific ADO project
sw-ado:import-areas --dry-run               # Preview without creating directories
sw-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 → mobil