@fromsvenwithlove/devops-issues-cli/README.md

AI-powered CLI tool and library for Azure DevOps work item management with Claude agents

# Azure DevOps AI-Powered CLI

An intelligent command-line interface and library for Azure DevOps work item management, powered by specialized Claude agents for automated work item generation, validation, and project workflow management.

## ✨ Features

- 🤖 **AI-Powered Work Item Generation** - Specialized Claude agents for creating user stories, features, tasks, and bugs
- 📋 **Rich Template Library** - Pre-built templates for common project patterns (web apps, APIs, mobile apps)
- ✅ **Schema Validation** - Validate work item JSON against Azure DevOps schema before creation
- 🔄 **Bulk Operations** - Create entire project hierarchies from JSON files
- 💻 **Dual Usage** - Use as CLI tool or import as library in your projects
- 🎯 **Project-Scoped** - Each project can have its own Azure DevOps configuration and scope
- 📊 **Interactive Explorer** - Browse and manage work items in an interactive tree view
- ⚡ **Smart Caching** - Efficient caching system for improved performance

## 🚀 Quick Start

### Installation

```bash
# Install as project dependency
npm install devops-issues-cli

# Or install globally
npm install -g devops-issues-cli
```

### Initialize AI Agents in Your Project

```bash
# Set up Claude agents and templates in your project
npx devops-ai-init

# This creates:
./claude-agents/        # Claude agent files for AI-powered generation
./devops-templates/     # JSON templates for common scenarios
.env.example           # Configuration template
AZURE_DEVOPS_AI.md     # Documentation and workflow guide
```

### Configure Azure DevOps

```bash
# Copy and configure environment variables
cp .env.example .env
# Edit .env with your Azure DevOps settings
```

Required environment variables:
- `AZ_DEVOPS_ORG` - Your Azure DevOps organization URL
- `AZ_DEVOPS_PROJECT` - Your project name
- `AZ_DEVOPS_PAT` - Your Personal Access Token
- `AZ_DEVOPS_USER` - Your user email or display name
- `AZ_DEVOPS_ROOT_ISSUE_ID` - (Optional) Filter by Epic/Feature ID for project scope

**Important**: All work items require a parent work item ID. This ensures proper hierarchy and prevents orphaned items in Azure DevOps.

## 🤖 AI-Powered Workflow

### 1. Generate Work Items with Claude

Use the specialized Claude agents to generate work items:

```bash
# List available agents
npx devops-issues agents list

# Show specific agent details
npx devops-issues agents show --agent userStory
```

**Example Claude conversation:**
```
User: "Help me break down the user authentication feature into user stories"
Claude: [Uses user-story-agent.md to create detailed, INVEST-compliant user stories]
```

**Note**: All generated templates require a `parentId` in the metadata section. Make sure to replace `"PARENT_WORK_ITEM_ID"` with an actual Epic, Feature, or other parent work item ID before creating work items.

### 2. Validate and Create

```bash
# Validate generated JSON
npx devops-issues validate user-stories.json

# Preview before creating
npx devops-issues bulk-create user-stories.json --preview

# Create in Azure DevOps
npx devops-issues bulk-create user-stories.json
```

### 3. Generate from Templates

```bash
# List available templates
npx devops-issues templates list

# Generate from template with customization
npx devops-issues templates generate --template webApp
```

## 📚 Usage

### CLI Commands

```bash
# Interactive mode (default)
devops-issues

# List work items
devops-issues list --state Active --type "User Story"

# Explore in tree view
devops-issues explore

# Create single work item
devops-issues create [parentId] [title]

# Validate JSON file
devops-issues validate workitems.json

# Template management
devops-issues templates list
devops-issues templates show --template userStory
devops-issues templates generate --template apiProject

# Claude agents
devops-issues agents list
devops-issues agents show --agent userStory

# Cache management
devops-issues cache refresh
```

### Library Usage

```javascript
import { AzureDevOpsClient, setup, createFromTemplate } from 'devops-issues-cli';

// Quick setup
const { client, cache } = await setup({
  orgUrl: 'https://dev.azure.com/yourorg',
  project: 'YourProject',
  pat: 'your-pat',
  user: 'user@company.com',
  rootIssueId: 12345  // Optional project scope
});

// Get work items
const workItems = await client.getAssignedWorkItems();

// Create from template
const workItemData = createFromTemplate('userStory', {
  metadata: { areaPath: 'MyProject\\MyArea' }
});

// Bulk create
await client.bulkCreateWorkItems(workItemData);
```

## 🎯 Project Integration Patterns

### Development Workflow Integration

```json
// package.json scripts
{
  "scripts": {
    "devops:list": "devops-issues list --state Active",
    "devops:create": "devops-issues create",
    "devops:sync": "devops-issues cache refresh",
    "feature:plan": "devops-issues templates generate --template feature"
  }
}
```

### CI/CD Pipeline Integration

```yaml
# .github/workflows/release.yml
- name: Create release tasks
  run: |
    npx devops-issues bulk-create .devops/release-tasks.json
    npx devops-issues list --type Task --state New > release-tasks.txt
```

## 📋 Available Claude Agents

### Work Item Generation Agents
- **user-story-agent** - Creates INVEST-compliant user stories with acceptance criteria
- **feature-agent** - Bridges Epics and User Stories with proper scope definition
- **task-agent** - Breaks down User Stories into implementable tasks
- **bug-agent** - Creates detailed bug reports with reproduction steps

### Development Support Agents
- **analyzer-agent** - Code quality and architecture analysis
- **programmer-agent** - Implementation following project patterns
- **validator-agent** - Quality assurance and testing
- **research-agent** - Information discovery and investigation
- **documentation-agent** - Technical writing and documentation

### Orchestration System
- **orchestrator** - Coordinates multiple agents for complex workflows

## 📁 Template Library

### Work Item Templates
- **userStory** - Basic user story with tasks
- **feature** - Feature with multiple user stories
- **epic** - Large epic with features and stories
- **bug** - Detailed bug report template

### Project Templates
- **webApp** - Complete web application project structure
- **api** - REST API development project
- **mobileApp** - Mobile application project

## 🔧 Configuration

### Environment Variables

```bash
# Required
AZ_DEVOPS_ORG=https://dev.azure.com/yourorganization
AZ_DEVOPS_PROJECT=YourProjectName
AZ_DEVOPS_PAT=your_personal_access_token
AZ_DEVOPS_USER=your.email@company.com

# Optional - Project scoping
AZ_DEVOPS_ROOT_ISSUE_ID=12345  # Epic/Feature ID to scope work items

# Optional - Performance tuning
CACHE_TTL=3600
CACHE_MAX_SIZE=1000
```

### Project-Specific Configuration

Each project can have its own Azure DevOps scope by setting `AZ_DEVOPS_ROOT_ISSUE_ID` to an Epic or Feature ID. This filters all operations to only show work items under that hierarchy, perfect for multi-project organizations.

## 📖 Documentation

- [Bulk Create Guide](docs/bulk-create.md) - Detailed bulk creation documentation
- [Field Compatibility Guide](docs/field-compatibility-guide.md) - Azure DevOps field mappings
- [AI Workflow Guide](AZURE_DEVOPS_AI.md) - Complete AI-powered workflow documentation

## 🤝 Contributing

Contributions welcome! This project benefits from:
- New Claude agent prompts for specialized work item types
- Additional project templates for different domains
- Enhanced validation rules and quality checks
- Integration examples for different development workflows

## 📄 License

MIT License - feel free to use in your projects and organizations.

## 🔗 Links

- [Azure DevOps Documentation](https://docs.microsoft.com/en-us/azure/devops/)
- [Claude AI](https://claude.ai/) - For AI-powered work item generation
- [Work Item Types](https://docs.microsoft.com/en-us/azure/devops/boards/work-items/about-work-items)