azure-devops-generator 1.0.9
CLI tool for managing Azure DevOps work items with hierarchical structure and Claude Code integration
License: MIT
Requires Python: >=3.8
Keywords: azure, devops, work-items, cli, task-management, bug-tracking, claude-code

# Azure DevOps Generator

[![PyPI version](https://badge.fury.io/py/azure-devops-generator.svg)](https://badge.fury.io/py/azure-devops-generator)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A powerful CLI tool for managing Azure DevOps work items with hierarchical structure (Feature → User Story → Task/Bug) and seamless Claude Code integration.

## Features

✨ **Hierarchical Work Item Management**
- Automatic parent-child relationships (Feature → User Story → Task/Bug)
- Smart User Story iteration tracking and duplication
- Efficient workflow with `--simple` and `--get` commands

🚀 **Claude Code Integration**
- Automatic slash command setup (`/generate_tasks`)
- Platform-specific integration (Windows/Linux/Mac)
- Auto-updates on package upgrade

⚙️ **Easy Configuration**
- Interactive setup wizard on first run
- Config stored in `~/.azure-generator/config.json`
- Support for environment variables

🔄 **Comprehensive CRUD Operations**
- Create, read, update, delete work items
- Batch processing support
- Status management and duplication

📊 **Advanced Features**
- Feature, User Story, Task, and Bug management
- Iteration caching (72 hours TTL)
- Daily task tracking (`todays_tasks.txt`)
- JSON-based work item definitions

## Installation

```bash
pip install azure-devops-generator
```

On first run, the interactive configuration wizard will guide you through the setup:

```
🔧 Azure DevOps Generator - First Time Setup
============================================================

Config dosyası bulunamadı. Lütfen aşağıdaki bilgileri girin:

Organization name: myorg
Project name: MyProject
PAT token: ******************************
User email: user@example.com
Area path: ML AR-GE\MLOps Team
Tasks folder [~/Desktop/Claude/Tasks]:

============================================================
✅ Yapılandırma tamamlandı!
============================================================
✅ Claude Code entegrasyonu oluşturuldu!
✅ Slash komut: /generate_tasks
📁 Konum: ~/.claude/commands/generate_tasks.md
```

## Quick Start

### List Work Items

```bash
# List features (simple format)
azure-generator --features --simple

# List user stories
azure-generator --stories --simple

# List tasks
azure-generator --tasks --simple

# List bugs
azure-generator --bugs --simple
```

### Get Work Item Details

```bash
# Get full details
azure-generator --get 12345

# Get simple summary
azure-generator --get --simple 12345
```

### Create Work Items

```bash
# From JSON file
azure-generator "path/to/task.json"

# From directory (batch)
azure-generator "path/to/tasks_folder/"

# Today's tasks folder
azure-generator --today
```

### Update Work Items

```bash
# Update from JSON
azure-generator --update "update.json"

# Quick status change
azure-generator --status 12345 "Completed"
```

### Duplicate User Story

```bash
# Duplicate to current iteration
azure-generator --duplicate 12345

# Duplicate to specific iteration
azure-generator --duplicate 12345 --iteration "ML AR-GE\2025\November\01.11.2025 - 14.11.2025"
```

### Delete Work Item

```bash
azure-generator --delete 12345
```

## JSON Work Item Format

### Task

```json
{
  "type": "Task",
  "title": "Implement JWT Authentication",
  "summary": "Add JWT-based authentication to API",
  "reason": "Need secure user authentication",
  "impact": "All API endpoints will be protected",
  "importance": "High",
  "implementation_steps": [
    "Created JWT token generation service",
    "Implemented refresh token mechanism"
  ],
  "related_files": [
    "src/auth/jwt_service.py",
    "src/middleware/auth.py"
  ],
  "time_spent_hours": 6,
  "status": "Completed",
  "parent_id": 85650,
  "created_date": "2025-10-21",
  "tags": ["auth", "security"]
}
```

### Bug

```json
{
  "type": "Bug",
  "title": "Fix timeout error in Kafka consumer",
  "summary": "Consumer crashes after 30 seconds of inactivity",
  "impact": "Messages are lost in production",
  "importance": "Critical",
  "discovery_method": "Production monitoring",
  "root_cause": "Missing heartbeat mechanism",
  "solution": "Added keepalive configuration",
  "status": "Closed",
  "parent_id": 85650,
  "created_date": "2025-10-21"
}
```

### User Story

```json
{
  "type": "User Story",
  "title": "Implement Authentication System",
  "description": "Add JWT-based auth to replace session-based system for better security and scalability",
  "status": "Active",
  "parent_id": 85610,
  "tags": ["feature", "auth"]
}
```

## Claude Code Integration

After installation, you can use the `/generate_tasks` slash command in Claude Code:

1. Have a conversation about your work
2. Type `/generate_tasks`
3. Claude will analyze the conversation and create hierarchical work items

The integration automatically:
- Lists features and user stories
- Creates proper parent-child relationships
- Handles iteration management
- Duplicates user stories when needed
- Tracks daily tasks

## Upgrading

```bash
pip install --upgrade azure-devops-generator
```

The upgrade process will:
- Update the package to the latest version
- Refresh Claude Code integration files
- Preserve your existing configuration

## Configuration

Configuration is stored in `~/.azure-generator/config.json`:

```json
{
  "organization": "your-org-name",
  "project": "your-project-name",
  "pat_token": "your-personal-access-token",
  "user_email": "your-email@example.com",
  "area_path": "ML AR-GE\\MLOps Team",
  "tasks_folder": "~/Desktop/Claude/Tasks",
  "iteration_cache_ttl_hours": 72,
  "max_filename_length": 50
}
```

## Work Item Hierarchy

```
Feature
└── User Story
    ├── Task
    ├── Task
    └── Bug
```

- **Tasks** must have a User Story parent
- **Bugs** can have User Story or Feature parent
- **User Stories** can have Feature parent
- Iteration tracking ensures User Stories are in current sprint

## Advanced Usage

### Iteration Management

Iterations are automatically selected based on today's date. You can override:

```bash
# CLI parameter (highest priority)
azure-generator "task.json" --iteration "ML AR-GE\2025\October\13.10.2025 - 24.10.2025"

# JSON field (second priority)
{
  "type": "Task",
  "title": "My Task",
  "iteration": "ML AR-GE\\2025\\October\\13.10.2025 - 24.10.2025"
}
```

### Daily Task Tracking

Created task IDs are automatically saved to `todays_tasks.txt`:

```
~/Desktop/Claude/Tasks/21-10-2025/todays_tasks.txt
85660
85661
85662
```

## Requirements

- Python 3.8+
- Azure DevOps account with PAT token
- `requests` library (automatically installed)

## License

MIT License - see [LICENSE](LICENSE) file for details

## Author

Ahmet

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

For issues, questions, or suggestions, please open an issue on GitHub.