@torus-engineering/tas-kit 1.10.0 → 1.12.0

package/.tas/tools/tas-ado-readme.md

@@ -1,48 +1,48 @@
 # TAS Kit Skill Specification: ado-integration
 
-**Skill name**: ado-integration  
-**Version**: 0.2 (concept & spec date: March 17, 2026)  
-**Purpose**:  
-Cho phép AI agent trong môi trường coding (Claude Code, Cursor, VS Code + terminal) thực hiện **CRUD** và đồng bộ hai chiều giữa các file Markdown (.md) trong repository và work items trên Azure DevOps (Epic, Feature, User Story, Bug), bao gồm tự động quản lý hierarchy (parent-child relations).
+**Skill name**: ado-integration
+**Version**: 0.2 (concept & spec date: March 17, 2026)
+**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 (Epic, Feature, User Story, Bug), including automatic hierarchy management (parent-child relations).
 
-Mục tiêu chính:  
-- Biến AI thành "thành viên đội ngũ" có khả năng tự quản lý backlog mà không cần rời khỏi editor  
-- Đảm bảo file .md là single source of truth (local ↔ ADO sync)  
-- Ghi dấu thời gian đồng bộ để agent biết dữ liệu mới/cũ
+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
 
-## 1. Yêu cầu môi trường & Dependencies
+## 1. Environment Requirements & Dependencies
 
-**Bắt buộc**:
-- Azure CLI đã cài + extension `azure-devops`
+**Required**:
+- Azure CLI installed + extension `azure-devops`
   ```bash
   az extension add --name azure-devops --upgrade
   ```
 - Python 3.8+
 - Package: `pyyaml` (`pip install pyyaml`)
 
-**Cấu hình** (file `tas.yaml` ở root repo):
+**Configuration** (file `tas.yaml` at repo root):
 ```yaml
 ado:
   organization: https://dev.azure.com/your-org-name
   project: Your-Project-Name
-  # pat: PAT với scope Work Items (Full) + optional Read & manage wiki
-  # Nếu không có pat trong file → dùng biến môi trường AZURE_DEVOPS_PAT
+  # pat: PAT with scope Work Items (Full) + optional Read & manage wiki
+  # If no pat in file → use environment variable AZURE_DEVOPS_PAT
 ```
 
-## 2. File chính cần tạo
+## 2. Main Files to Create
 
-- `tools/tas-ado.py`          → script Python thực thi tất cả lệnh
-- `skills/ado-integration.md` → tài liệu hướng dẫn sử dụng (giống file bạn đang đọc)
+- `tools/tas-ado.py`          → Python script executing all commands
+- `skills/ado-integration.md` → usage documentation (like this file)
 
-## 3. Các lệnh CLI được hỗ trợ
+## 3. Supported CLI Commands
 
-Tất cả lệnh đều chạy dạng:
+All commands run in form:
 
 ```bash
 python tools/tas-ado.py <command> [arguments]
 ```
 
-### Create commands (tạo mới + tự rename file + optional parent)
+### Create commands (create new + auto rename file + optional parent)
 
 ```bash
 create-epic   <temp-id> [--parent-id <id>]
@@ -51,10 +51,10 @@ create-story   <temp-id> [--parent-id <id>]
 create-bug     <temp-id> [--parent-id <id>]
 ```
 
-Ví dụ:
+Example:
 ```bash
 python tools/tas-ado.py create-story 789 --parent-id 456
-# → đọc epic-789-*.md → tạo User Story → rename thành story-1234-*.md → add parent relation đến 456
+# → reads epic-789-*.md → creates User Story → renames to story-1234-*.md → adds parent relation to 456
 ```
 
 ### Pull / Get commands
@@ -64,10 +64,10 @@ get  <ado-id>
 pull <ado-id>          # alias
 ```
 
-Ví dụ:
+Example:
 ```bash
 python tools/tas-ado.py get 5345
-# → tạo/tạo lại file epic-5345-slug-title.md với frontmatter + nội dung
+# → creates/recreates file epic-5345-slug-title.md with frontmatter + content
 ```
 
 ### Update commands
@@ -90,13 +90,13 @@ delete-story   <ado-id>
 delete-bug     <ado-id>
 ```
 
-## 4. Quy ước file .md
+## 4. File .md Convention
 
-- Pattern tên file: `{type}-{ado_id hoặc temp_id}-{slug-title}.md`
+- File name pattern: `{type}-{ado_id or temp_id}-{slug-title}.md`
   - type: epic / feature / story / bug
-  - slug-title: lowercase, thay space bằng -, loại ký tự đặc biệt
+  - slug-title: lowercase, replace spaces with -, remove special characters
 
-- Frontmatter YAML (luôn ở đầu file):
+- Frontmatter YAML (always at file start):
 
 ```yaml
 ---
@@ -107,63 +107,63 @@ ado_state: Active
 ado_assigned_to: Nguyen Van A <email@domain.com>
 ado_created: 2026-03-10
 last_ado_sync: 2026-03-17 15:42:08
-# optional: parent_ado_id: 100   (nếu muốn hỗ trợ detect parent tự động sau này)
+# optional: parent_ado_id: 100   (if want to support auto detect parent later)
 ---
-# Tiêu đề (phải trùng ado_title)
+# Title (must match ado_title)
 
-Nội dung mô tả, acceptance criteria, steps to reproduce, v.v.
+Content description, acceptance criteria, steps to reproduce, etc.
 ```
 
-**Quan trọng**:  
-- Mỗi lần **create / pull / update / update-status** thành công → **cập nhật** (hoặc thêm) trường `last_ado_sync` với thời gian hiện tại (format: YYYY-MM-DD HH:MM:SS)
+**Important**:
+- Every time **create / pull / update / update-status** succeeds → **update** (or add) `last_ado_sync` field with current time (format: YYYY-MM-DD HH:MM:SS)
 
-## 5. Yêu cầu logic chi tiết
+## 5. Detailed Logic Requirements
 
-### Khi create:
-1. Tìm file theo pattern `{type}-{temp_id}-*.md`
-2. Extract title (dòng # đầu tiên), description (phần còn lại)
-3. Tạo work item bằng `az boards work-item create`
-4. Lấy ID mới → rename file thành `{type}-{new_id}-*.md`
-5. Nếu có `--parent-id` → chạy `az boards work-item relation add --id <new_id> --relation-type parent --target-id <parent_id>`
-6. Tự động detect parent_id từ frontmatter `parent_ado_id` hoặc tên file
-7. Cập nhật `last_ado_sync` trong frontmatter
+### 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` or file name
+7. Update `last_ado_sync` in frontmatter
 
-### Khi pull/get:
-1. Lấy work item bằng `az boards work-item show --id <id> --expand fields`
-2. Convert description (HTML → Markdown cơ bản)
-3. Tạo file `{type}-{id}-{slug}.md`
-4. Ghi frontmatter + nội dung
-5. Cập nhật `last_ado_sync`
+### When pull/get:
+1. Get work item using `az boards work-item show --id <id> --expand fields`
+2. Convert description (HTML → basic Markdown)
+3. Create file `{type}-{id}-{slug}.md`
+4. Write frontmatter + content
+5. Update `last_ado_sync`
 
-### Khi update:
-1. Tìm file theo pattern `*-<id>-*.md`
-2. Đọc title & description từ file
-3. Cập nhật bằng `az boards work-item update`
-4. Cập nhật `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`
 
-### Khi update-status:
-1. Tìm file theo pattern
-2. Chỉ update state &/hoặc assigned-to
-3. Cập nhật `last_ado_sync` nếu tìm thấy file
+### When update-status:
+1. Find file by pattern
+2. Only update state &/or assigned-to
+3. Update `last_ado_sync` if file found
 
-### Khi delete:
-- Chỉ xóa trên ADO, không động đến file local
+### When delete:
+- Only delete on ADO, don't touch local files
 
-## 6. Gợi ý mở rộng (không bắt buộc cho v0.2)
+## 6. Extension Suggestions (not required for v0.2)
 
-- Hỗ trợ thêm fields: priority, effort, labels, acceptance criteria
-- Tự động git add/commit/push sau sync
-- Convert HTML → Markdown tốt hơn (table, code block, list)
+- Support additional fields: priority, effort, labels, acceptance criteria
+- Auto git add/commit/push after sync
+- Better HTML → Markdown conversion (table, code block, list)
 
-## 7. Cách sử dụng trong agent prompt
+## 7. How to Use in Agent Prompt
 
-Ví dụ prompt mẫu cho AI agent:
+Example prompt template for AI agent:
 
 ```
 /ado-create-feature 042 --parent-id 100
-/ado-create-story 789 --parent-id <feature-id vừa tạo>
-/ado-get 1234          # lấy bug mới về để fix
+/ado-create-story 789 --parent-id <feature-id just created>
+/ado-get 1234          # fetch new bug to fix
 /ado-update-bug 1234 --status Resolved
 ```
 
-Skill này được thiết kế để tích hợp mượt mà vào các framework agentic như TAS Kit, Superpowers, BMAD.
+This skill is designed to integrate smoothly into agentic frameworks like TAS Kit, Superpowers, BMAD.