# ADO Integration Rules

Bidirectional sync between .md files in repo and work items on Azure DevOps.
ADO sync is **intentional operation** — not automatic after each file edit.

> **Kit v3:** Only `feature` and `bug` types are supported by `/ado-*` commands. Epic and User Story were removed because TAS uses Feature as the single business unit. Legacy ADO Epic / User Story items pulled via `/ado-get` are saved as local `feature-*.md` files (see `tools/tas-ado.py` `TYPE_REVERSE`).

## When to Apply

- User runs `/ado-create`, `/ado-update`, `/ado-status`, `/ado-get`, `/ado-delete`
- DO NOT apply when: user only edits .md file normally without mentioning ADO

## Always / Ask / Never

| | Action |
|---|---|
| **Always** | Read `tas.yaml` and check `ado.enabled` before any operation |
| **Always** | Display ADO ID and URL after each successful create/update |
| **Always** | Update frontmatter `ado_id`, `status`, `last_ado_sync` in .md file after sync |
| **Ask** | When syncing multiple items at once — confirm list before running |
| **Ask** | When detecting conflict between .md file and ADO item (which is source of truth?) |
| **Ask** | When deleting work item — this is irreversible operation |
| **Never** | Auto-sync whenever .md file is edited (too aggressive, creates noise) |
| **Never** | Delete ADO item without clear user confirmation |
| **Never** | Create duplicate work item if `ado_id` already exists in frontmatter |

## First Step — Check ADO Enabled

Before performing any operation, read `tas.yaml` at root and check `ado.enabled`:
- If `ado.enabled: false` or field doesn't exist: notify "ADO integration is disabled in tas.yaml (`ado.enabled: false`). Enable if project uses ADO." then stop.
- If `ado.enabled: true`: continue normally.

## Prerequisites

- Azure CLI + azure-devops extension: `az extension add --name azure-devops --upgrade`
- Python 3.8+ with pyyaml: `pip install pyyaml`
- PAT in .env file: `AzureDevops_Personal_AccessToken=your-pat-here`

## Commands

All ADO commands run via: `python .tas/tools/tas-ado.py <command> [args]`

Or use slash commands:
- `/ado-create <type> <temp-id> [--parent-id <id>]`
- `/ado-get <ado-id>`
- `/ado-update <type> <ado-id> [--assign <name>] [--status <state>]`
- `/ado-status <ado-id> --status <state>`
- `/ado-delete <type> <ado-id>`

## File Convention

- Filename: `{type}-{ado_id}-{slug-title}.md`
- Each file has YAML frontmatter: `ado_id`, `ado_type`, `status`, `last_ado_sync`
- .md file is single source of truth, sync to ADO when needed

## Red Flags

- File has `ado_id` but state in file differs from ADO → confirm with user before overwriting
- PAT expired → guide to rotate, don't log token to stdout
- `ado.enabled: true` but project hasn't set up Azure CLI → check prerequisites first

## Anti-Rationalization

| Rationalization | Counter |
|---|---|
| "Auto-sync is more convenient, no need to remember" | Hook auto-sync causes unintended pushes when editing draft — sync must be intentional |
| "Delete is OK, I know what I'm doing" | ADO delete has no undo — always confirm, even if user seems confident |