@torus-engineering/tas-kit 1.9.0 → 1.11.1

package/.tas/templates/Story.md

@@ -22,16 +22,16 @@ plan_date:
 As a {role}, I want {goal}, so that {benefit}.
 
 ---
-## Business Requirements (nếu có)
-*(Yêu cầu nghiệp vụ đặc biệt, business rules, constraints từ stakeholders — chỉ thêm khi cần)*
+## Business Requirements (if any)
+*(Special business requirements, business rules, constraints from stakeholders — add only when needed)*
 
 ---
-## Design Notes (nếu có)
-*(UI/UX specs, mockup links, design decisions, flow diagrams — chỉ thêm khi cần)*
+## Design Notes (if any)
+*(UI/UX specs, mockup links, design decisions, flow diagrams — add only when needed)*
 
 ---
-## Prerequisites (nếu có)
-*(Dependencies từ Stories khác hoặc điều kiện phải có trước — chỉ thêm khi cần)*
+## Prerequisites (if any)
+*(Dependencies from other Stories or required conditions — add only when needed)*
 
 ---
 ## Acceptance Criteria
@@ -40,17 +40,17 @@ As a {role}, I want {goal}, so that {benefit}.
 - **Given** {precondition}
 - **When** {action}
 - **Then** {expected result}
-- **Functional Tests**: *(điền FT IDs sau khi chạy `/tas-functest` — vd: `{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_001_H`, `FT_002_N`)*
+- **Functional Tests**: *(fill FT IDs after running `/tas-functest` — e.g.: `{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_001_H`, `FT_002_N`)*
 
 ### AC-2: {title}
 - **Given** {precondition}
 - **When** {action}
 - **Then** {expected result}
-- **Functional Tests**: *(điền FT IDs sau khi chạy `/tas-functest`)*
+- **Functional Tests**: *(fill FT IDs after running `/tas-functest`)*
 
 ---
 ## Unit Test Cases
-*(PE thiết kế happy path + edge cases + negative cases. SE implement trong code.)*
+*(PE designs happy path + edge cases + negative cases. SE implements in code.)*
 
 ### Happy Path
 | ID | AC Ref | Description | Input | Expected Output |

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

@@ -1,169 +1,169 @@
-# 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).
-
-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ũ
-
-## 1. Yêu cầu môi trường & Dependencies
-
-**Bắt buộc**:
-- Azure CLI đã cài + 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):
-```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
-```
-
-## 2. File chính cần tạo
-
-- `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)
-
-## 3. Các lệnh CLI được hỗ trợ
-
-Tất cả lệnh đều chạy dạng:
-
-```bash
-python tools/tas-ado.py <command> [arguments]
-```
-
-### Create commands (tạo mới + tự rename file + optional parent)
-
-```bash
-create-epic   <temp-id> [--parent-id <id>]
-create-feature <temp-id> [--parent-id <id>]
-create-story   <temp-id> [--parent-id <id>]
-create-bug     <temp-id> [--parent-id <id>]
-```
-
-Ví dụ:
-```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
-```
-
-### Pull / Get commands
-
-```bash
-get  <ado-id>
-pull <ado-id>          # alias
-```
-
-Ví dụ:
-```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
-```
-
-### Update commands
-
-```bash
-update-epic   <ado-id> [--assign <name/email>] [--status <state>]
-update-feature <ado-id> [--assign <...>] [--status <...>]
-update-story   <ado-id> [--assign <...>] [--status <...>]
-update-bug     <ado-id> [--assign <...>] [--status <...>]
-
-update-status <ado-id> --status <state> [--assign <name/email>]
-```
-
-### Delete commands
-
-```bash
-delete-epic   <ado-id>
-delete-feature <ado-id>
-delete-story   <ado-id>
-delete-bug     <ado-id>
-```
-
-## 4. Quy ước file .md
-
-- Pattern tên file: `{type}-{ado_id hoặc temp_id}-{slug-title}.md`
-  - type: epic / feature / story / bug
-  - slug-title: lowercase, thay space bằng -, loại ký tự đặc biệt
-
-- Frontmatter YAML (luôn ở đầu file):
-
-```yaml
----
-ado_id: 5345
-ado_type: Epic           # Epic / Feature / User Story / Bug
-ado_title: Landing Page Redesign
-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)
----
-# Tiêu đề (phải trùng ado_title)
-
-Nội dung mô tả, acceptance criteria, steps to reproduce, v.v.
-```
-
-**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)
-
-## 5. Yêu cầu logic chi tiết
-
-### 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
-
-### 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`
-
-### 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`
-
-### 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
-
-### Khi delete:
-- Chỉ xóa trên ADO, không động đến file local
-
-## 6. Gợi ý mở rộng (không bắt buộc cho 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)
-
-## 7. Cách sử dụng trong agent prompt
-
-Ví dụ prompt mẫu cho 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-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.
+# TAS Kit Skill Specification: ado-integration
+
+**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).
+
+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. 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-epic   <temp-id> [--parent-id <id>]
+create-feature <temp-id> [--parent-id <id>]
+create-story   <temp-id> [--parent-id <id>]
+create-bug     <temp-id> [--parent-id <id>]
+```
+
+Example:
+```bash
+python tools/tas-ado.py create-story 789 --parent-id 456
+# → reads epic-789-*.md → creates User Story → renames to story-1234-*.md → adds parent relation to 456
+```
+
+### Pull / Get commands
+
+```bash
+get  <ado-id>
+pull <ado-id>          # alias
+```
+
+Example:
+```bash
+python tools/tas-ado.py get 5345
+# → creates/recreates file epic-5345-slug-title.md with frontmatter + content
+```
+
+### Update commands
+
+```bash
+update-epic   <ado-id> [--assign <name/email>] [--status <state>]
+update-feature <ado-id> [--assign <...>] [--status <...>]
+update-story   <ado-id> [--assign <...>] [--status <...>]
+update-bug     <ado-id> [--assign <...>] [--status <...>]
+
+update-status <ado-id> --status <state> [--assign <name/email>]
+```
+
+### Delete commands
+
+```bash
+delete-epic   <ado-id>
+delete-feature <ado-id>
+delete-story   <ado-id>
+delete-bug     <ado-id>
+```
+
+## 4. File .md Convention
+
+- File name pattern: `{type}-{ado_id or temp_id}-{slug-title}.md`
+  - type: epic / feature / story / bug
+  - slug-title: lowercase, replace spaces with -, remove special characters
+
+- Frontmatter YAML (always at file start):
+
+```yaml
+---
+ado_id: 5345
+ado_type: Epic           # Epic / Feature / User Story / Bug
+ado_title: Landing Page Redesign
+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   (if want to support auto detect parent later)
+---
+# Title (must match ado_title)
+
+Content description, acceptance criteria, steps to reproduce, etc.
+```
+
+**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. 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` or file name
+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. Create file `{type}-{id}-{slug}.md`
+4. Write frontmatter + content
+5. 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.2)
+
+- 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-create-story 789 --parent-id <feature-id just created>
+/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.

package/.tas/tools/tas-ado.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """
 TAS ADO Integration Script
-Đồng bộ hai chiều giữa file .md local và Azure DevOps work items.
+Two-way sync between local .md files and Azure DevOps work items.
 
 Usage: python tools/tas-ado.py <command> [arguments]
 

package/CLAUDE-Example.md

@@ -1,58 +1,37 @@
-# Project Context
-
-## Tech Stack
-- Backend: .NET 8, C#, Entity Framework Core
-- Frontend: ReactJS
-- Database: MySQL
-- Infrastructure: AWS
-- CI/CD: Azure DevOps Pipelines
-
-## Conventions
-- Branching: git-flow
-- Commit: conventional commits
-- Namespace: Torus.{ProjectName}.{Layer}
-- Naming: PascalCase for classes/methods, camelCase for variables
-- Test framework: xUnit
-
-## Legacy Patterns to Avoid (Brownfield)
-- Repository pattern without interface
-- Direct SQL queries in controllers
-
-## Mermaid Rules (AzureDevops Wiki)
-- Always wrap with :::mermaid and :::
-- NEVER use () in node labels, use [] instead
-- Example: A["Web App"] --> B["API Gateway"]
-
-## Build & Test
-- Build: dotnet build
-- Test: dotnet test
-- Lint: dotnet format --verify-no-changes
-
-## TAS Kit
-This project uses Torus-Agentic-SDLC (TAS) kit.
-- Flow config: root/tas.yaml
-- Templates: .tas/templates/
-- Generated docs: docs/
-
-## Key Rules
-- Architecture: see docs/sad.md
-- Decisions: see docs/adr/
-
-## Commands
-Type /tas-status to see current project state.
-Type /tas-[artifact] to create or update artifacts (prd, sad, adr, epic, feature, story, design).
-Type /tas-dev to implement a story.
-Type /tas-verify to verify a Feature on Staging (Phase 2).
-Type /tas-review-code, /tas-brainstorm, /tas-bug, /tas-security-check for dev workflows.
-
-## ADO Commands
-Type /ado-create <type> <temp-id> [--parent-id <id>] to create work item on ADO.
-Type /ado-get <ado-id> to pull work item from ADO.
-Type /ado-update <type> <ado-id> [--assign <n>] [--status <state>] to update on ADO.
-Type /ado-status <ado-id> --status <state> to quick update status on ADO.
-Type /ado-delete <type> <ado-id> to delete work item on ADO.
-
-## ADO Prerequisites
-- Azure CLI + azure-devops extension: az extension add --name azure-devops --upgrade
-- Python 3.8+ with pyyaml: pip install pyyaml
-- PAT configured in .env file: AzureDevops_Personal_AccessToken=your-pat-here
+# Project Context
+
+## Tech Stack
+<!-- Specify your backend, frontend, database, infrastructure, and CI/CD -->
+- Backend: [e.g., .NET 8, Node.js, Python]
+- Frontend: [e.g., ReactJS, Vue, Angular]
+- Database: [e.g., PostgreSQL, MySQL, MongoDB]
+- Infrastructure: [e.g., AWS, Azure, GCP]
+- CI/CD: [e.g., GitHub Actions, Azure DevOps, Jenkins]
+
+## Conventions
+<!-- Define coding standards and patterns used in this project -->
+- Branching: [e.g., git-flow, trunk-based, GitHub flow]
+- Commit: [e.g., conventional commits, custom format]
+- Naming: [e.g., PascalCase for classes, camelCase for variables]
+- Test framework: [e.g., xUnit, Jest, pytest]
+
+## Architecture
+<!-- Reference key architecture documents -->
+- System design: see [docs/sad.md](docs/sad.md)
+- Architecture decisions: see [docs/adr/](docs/adr/)
+
+## Build & Test
+<!-- Commands for building, testing, and linting -->
+- Build: [e.g., dotnet build, npm run build]
+- Test: [e.g., dotnet test, npm test]
+- Lint: [e.g., dotnet format, npm run lint]
+
+## Environment Setup
+<!-- Prerequisites for running this project -->
+- [e.g., Node.js 20+, .NET 8 SDK, Python 3.11+]
+- [e.g., Azure CLI with specific extensions]
+- [e.g., Required environment variables in .env file]
+
+## Key Workflows
+<!-- Common commands for this project -->
+Type /[command-name] to [describe what it does].