# TAS Kit Skill Specification: ado-integration

**Skill name**: ado-integration
**Version**: 0.3 (kit v3 — Feature is the only TAS work unit; Epic / User Story removed)
**Purpose**:
Allows AI agent in coding environment (Claude Code, Cursor, VS Code + terminal) to perform **CRUD** and two-way sync between Markdown (.md) files in repository and work items on Azure DevOps (Feature, Bug).

Main objectives:
- Transform AI into "team member" capable of self-managing backlog without leaving editor
- Ensure .md file is single source of truth (local ↔ ADO sync)
- Record sync timestamp so agent knows data freshness

> **Migration note (v3):** Epic and User Story are no longer kit-managed. If your ADO project still uses Epic / User Story templates, treat each TAS Feature as the ADO `Feature` work item; legacy work items pulled with `get` are converted to local `feature-*.md` files.

## 1. Environment Requirements & Dependencies

**Required**:
- Azure CLI installed + extension `azure-devops`
  ```bash
  az extension add --name azure-devops --upgrade
  ```
- Python 3.8+
- Package: `pyyaml` (`pip install pyyaml`)

**Configuration** (file `tas.yaml` at repo root):
```yaml
ado:
  organization: https://dev.azure.com/your-org-name
  project: Your-Project-Name
  # pat: PAT with scope Work Items (Full) + optional Read & manage wiki
  # If no pat in file → use environment variable AZURE_DEVOPS_PAT
```

## 2. Main Files to Create

- `tools/tas-ado.py`          → Python script executing all commands
- `skills/ado-integration.md` → usage documentation (like this file)

## 3. Supported CLI Commands

All commands run in form:

```bash
python tools/tas-ado.py <command> [arguments]
```

### Create commands (create new + auto rename file + optional parent)

```bash
create-feature <temp-id> [--parent-id <id>]
create-bug     <temp-id> [--parent-id <id>]
```

Example:
```bash
python tools/tas-ado.py create-feature 042
# → reads feature-042-*.md → creates Feature on ADO → renames file to feature-1234-*.md
```

### Pull / Get commands

```bash
get  <ado-id>
pull <ado-id>          # alias
```

Example:
```bash
python tools/tas-ado.py get 5345
# → creates/updates file feature-5345-slug-title.md
# → if ADO type is Epic or User Story (legacy), saves as feature-*.md anyway
```

### Update commands

```bash
update-feature <ado-id> [--assign <name/email>] [--status <state>]
update-bug     <ado-id> [--assign <...>] [--status <...>]

update-status  <ado-id> --status <state> [--assign <name/email>]
```

### Delete commands

```bash
delete-feature <ado-id>
delete-bug     <ado-id>
```

## 4. File .md Convention

- File name pattern: `{type}-{ado_id or temp_id}-{slug-title}.md`
  - type: feature / bug
  - slug-title: lowercase, replace spaces with -, remove special characters

- Frontmatter YAML (always at file start):

```yaml
---
ado_id: 5345
ado_type: Feature        # Feature / Bug (legacy: Epic / User Story still accepted on get)
ado_title: Checkout Refactor
status: Active
owner: Nguyen Van A <email@domain.com>
created: 2026-03-10
last_ado_sync: 2026-03-17 15:42:08
# optional: parent_ado_id: 100
---
# Title (must match ado_title)

Content description, acceptance criteria, etc.
```

**Important**:
- Every successful create / pull / update / update-status → **update** `last_ado_sync` (format: YYYY-MM-DD HH:MM:SS)

## 5. Detailed Logic Requirements

### When create:
1. Find file by pattern `{type}-{temp_id}-*.md`
2. Extract title (first # line), description (remaining content)
3. Create work item using `az boards work-item create`
4. Get new ID → rename file to `{type}-{new_id}-*.md`
5. If `--parent-id` → run `az boards work-item relation add --id <new_id> --relation-type parent --target-id <parent_id>`
6. Auto detect parent_id from frontmatter `parent_ado_id`
7. Update `last_ado_sync` in frontmatter

### When pull/get:
1. Get work item using `az boards work-item show --id <id> --expand fields`
2. Convert description (HTML → basic Markdown)
3. Map ADO type → local file type via `TYPE_REVERSE` (Epic / User Story → feature)
4. Create file `{type}-{id}-{slug}.md`
5. Write frontmatter + content
6. Update `last_ado_sync`

### When update:
1. Find file by pattern `*-<id>-*.md`
2. Read title & description from file
3. Update using `az boards work-item update`
4. Update `last_ado_sync`

### When update-status:
1. Find file by pattern
2. Only update state &/or assigned-to
3. Update `last_ado_sync` if file found

### When delete:
- Only delete on ADO, don't touch local files

## 6. Extension Suggestions (not required for v0.3)

- Support additional fields: priority, effort, labels, acceptance criteria
- Auto git add/commit/push after sync
- Better HTML → Markdown conversion (table, code block, list)

## 7. How to Use in Agent Prompt

Example prompt template for AI agent:

```
/ado-create feature 042 --parent-id 100
/ado-get 1234          # fetch new bug to fix
/ado-update bug 1234 --status Resolved
```

This skill is designed to integrate smoothly into agentic frameworks like TAS Kit, Superpowers, BMAD.