@relipa/ai-flow-kit 0.1.9 → 0.2.0-beta.1

package/README.md

@@ -188,6 +188,63 @@ ak use PROJ-33  (taskType: testcase)  →  claude
 
 ---
 
+## Create System Requirement Flow
+
+```
+ak use PROJ-33  (taskType: create-system-requirement)  →  claude
+        │
+        ▼
+⛩️ GATE 1 — Investigate UC & Draft             [AI + BA/Dev]
+  AI resolve UC Spec version hiện tại của functionId
+  AI đọc source code + convention error-handling hiện có
+  AI dịch từng Flow step + Business Rule → FR/NFR/Validation Rules/Exception Handling
+  AI viết Acceptance Test scenarios (Given/When/Then) — mọi item trace về đúng UC, không tự suy diễn
+  Q&A từng câu một tới khi hết Gap chưa rõ → "APPROVED"
+        │ APPROVED
+        ▼
+⛩️ GATE 2 — Finalize & Approve                  [AI + BA/Dev]
+  AI quyết định single-file vs split (mặc định 1 file 1-1 với UC Spec,
+  chỉ split khi có tín hiệu đo được — fan-out business rule/module, quá nhiều flow, ~400 dòng)
+  AI ghi AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v{N}.md
+  (N khớp đúng version UC Spec đã trace, ghi trong header `UC-Spec-Version`)
+  Review → "APPROVED"
+        │
+        ▼
+       DONE — Coding Gate 1 (read-study-requirement) mới được phép chạy cho functionId này
+```
+
+> **Entry point:** `ak use PROJ-33` → chọn taskType **"📐 Create System Requirement"** trong danh sách. Đây là bước bắt buộc, chạy 1 lần cho mỗi `functionId` (không phải mỗi ticket) — Coding Gate 1 sẽ tự chặn (`⏸️ Gate 1 cancelled`) nếu System Requirement chưa tồn tại hoặc chưa khớp UC Spec version hiện tại.
+
+---
+
+## Ingest Data Flow
+
+```
+ak use <link hoặc paste text>  (taskType: ingest-data)  →  claude
+        │
+        ▼
+⛩️ GATE 1 — Fetch, Classify, Draft              [AI + PM/BrSE/Comtor]
+  Input: Backlog ticket/comment/Document/Wiki link · Jira ticket/comment link ·
+         SharePoint link (chưa có connector — fallback paste text) · text thô
+  AI resolve nguồn: `ak fetch-links <url>` (nếu là link) hoặc dùng text trực tiếp
+  AI phân loại: QnA-Log / Meetings-Log / Confirmations-Log (hỏi lại nếu chưa rõ)
+  AI soạn draft đầy đủ — kèm Nguồn / functionId / Người tổng hợp / Người approve tại nguồn
+  Hiển thị draft nguyên văn, lặp sửa theo yêu cầu tới khi → "APPROVED"
+        │ APPROVED
+        ▼
+⛩️ GATE 2 — Branch + Merge Request              [AI, chờ xác nhận từng bước]
+  Ghi entry vào AK-Docs/01.QnA/{QnA-Log,Meetings-Log,Confirmations-Log}.md
+  `ak docs branch [functionId] [ticketId] --yes` — chỉ chạy sau khi user xác nhận
+  `ak docs submit --title "..." --yes` — chỉ chạy sau khi user xác nhận
+        │
+        ▼
+       DONE — chờ PM review & merge MR vào main (không tự merge)
+```
+
+> **Entry point:** `ak use` → chọn taskType **"📥 Ingest Data"**, hoặc `ak use "<backlog/jira-url>"` rồi chọn taskType tương ứng. SharePoint chưa fetch được nội dung thật — paste trực tiếp nội dung comment/tài liệu vào chat thay vì dán link (xem `docs/internal/PM Workflow_v1.0.md` "Vấn đề 4").
+
+---
+
 ## Installation
 
 ```bash
@@ -590,6 +647,14 @@ Then run `ak update` or `ak sync-skills` to apply.
 
 > Summary of major changes per version. See full details in [CHANGELOG.md](docs/common/CHANGELOG.md).
 
+### v0.2.0 — 2026-08-04
+- **New `create-system-requirement` task type (2-Gate):** bridges a UC Spec (BA) into a Dev-facing System Requirement scoped to a `functionId` (not a ticket) — Gate 1 investigates the UC + source code and drafts FR/NFR/Validation Rules/Exception Handling + Given/When/Then acceptance tests, Gate 2 finalizes and writes `AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v{N}.md`. Coding Gate 1 (`read-study-requirement`) now **blocks** with a Step 0 pre-check if this document is missing or stale against the current UC Spec version. See [Create System Requirement Flow](#create-system-requirement-flow).
+- **New `ingest-data` task type (2-Gate) — for PM/BrSE/Comtor:** ingest a Backlog ticket/comment/Document/Wiki link, a Jira link, a SharePoint link, or pasted text into `AK-Docs/01.QnA/{QnA-Log,Meetings-Log,Confirmations-Log}.md`. Gate 1 fetches + classifies + drafts the entry for self-review; Gate 2 opens the branch + Merge Request via the existing `ak docs branch`/`ak docs submit`. SharePoint has no connector yet (no Microsoft Graph API/OAuth) — falls back to pasted text. See [Ingest Data Flow](#ingest-data-flow) and `docs/internal/PM Workflow_v1.0.md`.
+- **`ak fetch-links` / `link-resolver.js` now fetch Backlog Document and Wiki links**, not just ticket/comment — `fetchBacklogDocument`, `fetchBacklogDocumentComment`, `fetchBacklogWiki`. Auto-resolution from a ticket description (`ak use`) still only follows ticket/comment links, capped at 5 — Document/Wiki/SharePoint are explicit single-URL lookups only.
+- **`ak use` now captures `projectId`/`projectKey`** from the loaded Backlog/Jira ticket (`.aiflow/context/current.json` and `.aiflow/state.json`) — a first step toward letting a future "create ticket" flow default to the right Backlog/Jira project instead of asking every time.
+- Fixed: **`ak use`'s "Task type:" selector crashed** (`CATEGORY_COLOR[cat] is not a function`) whenever it rendered the **"📐 Create System Requirement"** entry — the `"Dev"` category had no color mapping. Added.
+- `docs/common/Docs-Management-Flow.md`'s branch+MR flow now explicitly covers `AK-Docs/01.QnA/`, not just `02.BA-Specs/`/`03.Testing/`/`04.Coding/`/`99.Memory/`.
+
 ### v0.1.9 — 2026-08-04
 - **Codex (OpenAI) support — `ak init --env codex`:** One install covers all three local Codex surfaces, which share the same `CODEX_HOME` config, skills and MCP setup: the **VS Code extension**, **Codex mode in the ChatGPT desktop app**, and the **`codex` CLI**. Generates `AGENTS.md`, `.codex/skills/` (all kit skills, auto-discovered — the kit's `SKILL.md` layout is already Codex-compatible), `.codex/config.toml` (MCP servers mirrored from `.mcp.json`), and `.aiflow/instructions/`.
 - **Four Codex entry-point skills:** `/ak-coding`, `/ak-create-spec`, `/ak-create-testcase`, `/ak-ask` — the same workflows Claude Code exposes as slash commands.

package/bin/aiflow.js

@@ -22,6 +22,7 @@ const { record }      = require('../scripts/telemetry/record');
 const { updateTaskGateState } = require('../scripts/task');
 const scaffoldPlaywrightCommand = require('../scripts/scaffold-playwright');
 const docsBranchCommand = require('../scripts/docs-branch');
+const ticketWriterCommand = require('../scripts/ticket-writer');
 const semver = require('semver');
 const { execSync: execSyncChild, spawnSync } = require('child_process');
 
@@ -170,6 +171,11 @@ program
     .option('--cto <id>', 'load comments up to ID N', parseInt)
     .option('-F, --fast', 'fast mode: minimal Q&A, concise requirement doc (Default)')
     .option('-U, --full', 'full mode: force complete analysis with Q&A (default)')
+    .option('--task-type <type>', 'skip the interactive Task type prompt (e.g. feature, bug-fix)')
+    .option('--title <title>', 'manual entry: skip the interactive Title prompt')
+    .option('--description <description>', 'manual entry: skip the interactive Description prompt')
+    .option('--ticket-id <id>', 'manual entry: skip the interactive Ticket ID prompt')
+    .option('--preview', 'fetch a ticket/URL target and print its context as JSON to stdout — no save, no prompts')
     .addHelpText('after', `
 Examples:
   $ ak use PROJ-33                                  Single ticket (primary only)
@@ -180,6 +186,12 @@ Examples:
   $ ak use --file task.md                           Load from local file
   $ ak use --manual                                 Manual entry
 
+Non-interactive entry (v0.3.0+, for scripting/GUI callers):
+  $ ak use --manual --task-type feature --title "x" --description "y"
+                                                     Manual entry, zero prompts
+  $ ak use PROJ-33 --task-type bug-fix              Skip the Task type prompt after fetch
+  $ ak use PROJ-33 --preview                        Fetch only — print context JSON, no save/prompts
+
 Auto link resolution (v0.1.0+):
   Backlog/Jira URLs in the primary ticket description are auto-fetched and added
   to supplementaryContext[]. Comment links (#comment-456 or ?focusedCommentId=456)
@@ -195,17 +207,20 @@ Related:
 // ── fetch-links ───────────────────────────────────────────────
 program
     .command('fetch-links <url>')
-    .description('Fetch a backlog/jira link and output SupplementaryContext JSON to stdout. Used by AI at runtime.')
+    .description('Fetch a backlog/jira/sharepoint link and output SupplementaryContext JSON to stdout. Used by AI at runtime.')
     .addHelpText('after', `
 Examples:
   $ ak fetch-links "https://company.backlog.com/view/PROJ-10"
   $ ak fetch-links "https://company.backlog.com/view/PROJ-10#comment-456"
+  $ ak fetch-links "https://company.backlog.com/document/98765"          Backlog Document (ingest-data)
+  $ ak fetch-links "https://company.backlog.com/alias/wiki/1234"         Backlog Wiki (ingest-data)
   $ ak fetch-links "https://company.atlassian.net/browse/PROJ-10"
   $ ak fetch-links "https://company.atlassian.net/browse/PROJ-10?focusedCommentId=789"
+  $ ak fetch-links "https://company.sharepoint.com/sites/proj/doc.docx"  → { sourceType: "unsupported" }, no connector yet
 
 Exit codes:
-  0   Success — JSON written to stdout
-  1   URL not recognised, or fetch failed (error on stderr)
+  0   Success — JSON written to stdout (including the SharePoint "unsupported" stub)
+  1   URL not recognised at all, or fetch failed (error on stderr)
 `)
     .action(async (url) => {
         const { fetchLink } = require('../scripts/link-resolver');
@@ -214,7 +229,7 @@ Exit codes:
         try {
             const result = await fetchLink(url, credentials);
             if (!result) {
-                process.stderr.write(`Not a recognized backlog/jira URL: ${url}\n`);
+                process.stderr.write(`Not a recognized backlog/jira/sharepoint URL: ${url}\n`);
                 process.exit(1);
             }
             process.stdout.write(JSON.stringify(result, null, 2) + '\n');
@@ -224,6 +239,61 @@ Exit codes:
         }
     });
 
+// ── backlog-projects ─────────────────────────────────────────
+program
+    .command('backlog-projects')
+    .description('List Backlog projects in the configured space, and which one is the default for manually-created tasks')
+    .option('--json', 'output as JSON (for headless callers, e.g. the VS Code extension)')
+    .action((options) => {
+        useCommand.listBacklogProjectsCommand(options);
+    });
+
+// ── backlog-set-default-project ──────────────────────────────
+program
+    .command('backlog-set-default-project <id> <key>')
+    .description('Set the default Backlog project for tasks created manually (ak use --manual)')
+    .action((id, key) => {
+        useCommand.setDefaultBacklogProjectCommand(id, key);
+    });
+
+// ── jira-projects ─────────────────────────────────────────────
+program
+    .command('jira-projects')
+    .description('List Jira projects visible to the configured account, and the default for task-creation')
+    .option('--json', 'output as JSON (for headless callers, e.g. the VS Code extension)')
+    .action((options) => {
+        useCommand.listJiraProjectsCommand(options);
+    });
+
+// ── jira-set-default-project ─────────────────────────────────
+program
+    .command('jira-set-default-project <key>')
+    .description('Set the default Jira project for tasks created from Meeting Minutes/QnA (ingest-data Gate 3)')
+    .action((key) => {
+        useCommand.setDefaultJiraProjectCommand(key);
+    });
+
+// ── tasks (Vấn đề 5 — sinh task từ feedback/meeting minutes) ──
+const tasksCmd = program.command('tasks').description('Turn an AI-proposed, PM-approved task list into real tickets (ingest-data Gate 3)');
+
+tasksCmd
+    .command('create-tickets <file>')
+    .description('Create Backlog/Jira tickets from a JSON task list — see scripts/ticket-writer.js for the input shape')
+    .option('--json', 'machine-readable output only')
+    .action((file, options) => {
+        ticketWriterCommand.createTicketsCommand(file, options);
+    });
+
+// ── credentials ───────────────────────────────────────────────
+const credentialsCmd = program.command('credentials').description('Manage supplementary credentials (WRITE keys, default projects) not covered by `ak init --adapter`');
+
+credentialsCmd
+    .command('set <key> <value>')
+    .description(`Save a credential value (allowed keys: ${ticketWriterCommand.SETTABLE_CREDENTIAL_KEYS.join(', ')})`)
+    .action((key, value) => {
+        ticketWriterCommand.setCredentialCommand(key, value);
+    });
+
 // ── prompt ────────────────────────────────────────────────────
 program
     .command('prompt [type]')

package/custom/rules/output-language.md

@@ -0,0 +1,36 @@
+# Ngôn ngữ Output — Auto-detect theo Input
+
+> File này là quy tắc dùng chung cho **tất cả** các skill trong `custom/skills/` (BA, Dev, QA, ML) có sinh file markdown output (requirement, plan, test-analysis, checklist, testcase, report, review, UC Spec, v.v.).
+> Mọi skill sinh markdown output PHẢI đọc file này trước khi viết, thay cho việc mặc định cố định tiếng Anh hoặc tiếng Việt.
+
+## Quy tắc
+
+Ngôn ngữ của output PHẢI khớp với ngôn ngữ của input — không dùng một ngôn ngữ mặc định cố định cho mọi task.
+
+**Xác định ngôn ngữ input theo thứ tự ưu tiên** (dùng nguồn đầu tiên có sẵn):
+
+1. Tester/dev chỉ định rõ ngôn ngữ output (ví dụ: "viết bằng tiếng Anh giúp tôi") → dùng đúng ngôn ngữ đó, bỏ qua các bước dưới.
+2. Title + description của ticket đang xử lý — từ `.aiflow/context/current.json` (fetch qua Backlog/Jira, hoặc nhập qua `ak use --manual`).
+3. Nếu skill đang mở rộng/tiếp nối một tài liệu đã có sẵn (UC Spec, System Requirement, plan, testcase set của gate trước) và không có ticket text mới — dùng ngôn ngữ của tài liệu đó.
+
+**Kết luận:**
+- Input chủ yếu là **tiếng Việt** (có dấu, từ vựng tiếng Việt) → viết **toàn bộ** output bằng tiếng Việt: heading, mô tả, tóm tắt, câu hỏi clarify, nội dung bảng, v.v.
+- Ngược lại (tiếng Anh hoặc ngôn ngữ khác) → **mặc định tiếng Anh**.
+
+Nếu một task có nhiều gate (Gate 1 → Gate N) hoặc nhiều phase, ngôn ngữ được xác định **một lần** ở bước đầu tiên (đọc ticket/input) và giữ nguyên xuyên suốt các gate/phase sau, trừ khi tester/dev đổi ý.
+
+## Không đổi ngôn ngữ (giữ nguyên bất kể input)
+
+- Code, command, file path, tên biến/hàm/class/API.
+- Table column headers / field keys mang tính cấu trúc, dùng để tham chiếu chéo giữa các gate (ví dụ `TC_ID`, `Priority`, `Status`, `Gate N`) — theo quy ước hiện có ở `custom/skills/test-skills/rules/qa-writing-standards.md`.
+- Từ khóa điều khiển flow: `APPROVED`, `RETEST`, tên skill, tên file/thư mục chuẩn (`test-analysis.md`, `checklist.md`, ...).
+- Ticket ID, YAML frontmatter keys.
+
+## Cách trích dẫn quy tắc này trong một SKILL.md
+
+Thêm 1 dòng ngắn ngay gần bước xác định output đầu tiên của skill:
+
+```
+Output language: auto-detect từ ticket/task input — xem `custom/rules/output-language.md`
+(input tiếng Việt → output tiếng Việt; ngược lại mặc định tiếng Anh).
+```

package/custom/rules/project-conventions.md

@@ -50,6 +50,22 @@
 
 ---
 
+## ingest-data Workflow Output Paths (`AK-Docs/01.QnA/`)
+
+Áp dụng cho taskType `ingest-data` (PM/BrSE/Comtor ingest communication — xem `.claude/skills/ingest-data/SKILL.md`). Khác với các taskType coding/gen-doc ở trên: **không** ghi vào `04.Coding/`, và **không** theo cấu trúc `[functionId]/[ticketId].md` — cả 3 file dưới đây là log dùng chung, phẳng, cho toàn dự án (append entry mới, không tạo file theo ticket):
+
+| Log | Path | Ghi khi nào |
+|---|---|---|
+| QnA-Log | `AK-Docs/01.QnA/QnA-Log.md` | Trao đổi hỏi-đáp thông thường (file có sẵn — thêm cột `Nguồn` nếu chưa có) |
+| Meetings-Log | `AK-Docs/01.QnA/Meetings-Log.md` | Tổng hợp 1 buổi họp — tạo file nếu chưa có |
+| Confirmations-Log | `AK-Docs/01.QnA/Confirmations-Log.md` | Mốc khách CHỐT chính thức — tạo file nếu chưa có |
+
+`functionId` cho Gate 2 (đặt tên branch `feature/[functionId]/[ticketId]`) vẫn theo đúng quy tắc "functionId & ticketId" ở trên — không suy ra được thì dùng `general` (tương tự gen-doc dùng `AD-HOC`).
+
+> **Chưa đổi tên thư mục** `01.QnA/` thành `01.Communications/` như phương án đang chờ PM chốt trong `docs/internal/PM Workflow_v1.0.md` — giữ nguyên tên hiện có để không phá vỡ project đang chạy; đổi tên (nếu PM chốt) là 1 task migration riêng.
+
+---
+
 ## Execution Handoff Message
 
 When `writing-plans` skill says to announce the saved path, use the **actual path**:

package/custom/skills/automation-testing/SKILL.md

@@ -235,5 +235,5 @@ Xem report:
 
 - **Gate trước khi sinh code** (Phase 2) là bắt buộc — tránh sinh sai hàng loạt.
 - **Selector phải đến từ DOM thật** (Phase 3) — đây là lý do tồn tại của skill này.
-- Viết test case, tên test, comment bằng **tiếng Việt** cho khớp draft của tester.
+- Tên test, comment viết theo ngôn ngữ của draft test case của tester (xem `custom/rules/output-language.md`) — draft tiếng Việt → tiếng Việt, draft tiếng Anh → tiếng Anh.
 - Nếu app yêu cầu đăng nhập trước, hỏi tester credentials test (đừng hardcode tài khoản thật).

package/custom/skills/ba-skills/skill-ba-build-business-rules-v1.md

@@ -3,6 +3,8 @@
 ## 1. Mục đích (Purpose)
 Kỹ năng này giúp BA bóc tách, chuẩn hóa và đặc tả các quy tắc nghiệp vụ (Business Rules - BR) của hệ thống một cách chặt chẽ nhất. Các quy tắc nghiệp vụ được định nghĩa chi tiết tại đây sẽ là căn cứ trực tiếp để lập trình viên viết code logic (backend/frontend) và kiểm thử viên viết các kịch bản kiểm thử (Test Cases), đảm bảo bao phủ toàn bộ các trường hợp biên và ngoại lệ.
 
+Ngôn ngữ output: auto-detect theo ngôn ngữ của ticket/task input — xem `custom/rules/output-language.md` (input tiếng Việt → output tiếng Việt; ngược lại mặc định tiếng Anh).
+
 ## 2. Kiến thức cần có (Prerequisite Knowledge)
 - **Các loại Business Rules phổ biến:**
   - *Validation Rules (Quy tắc kiểm tra dữ liệu):* Bao gồm kiểm tra rỗng (Required), kiểm tra định dạng (Format - Regex, Email, số điện thoại), kiểm tra độ dài/giới hạn (Length/Range), và kiểm tra ràng buộc chéo giữa các trường (Dependency validation - ví dụ: Ngày kết thúc phải sau Ngày bắt đầu).

package/custom/skills/ba-skills/skill-ba-initial-analysis-v1.md

@@ -3,6 +3,8 @@
 ## 1. Mục đích (Purpose)
 Kỹ năng này giúp Business Analyst (hoặc Agent) quét, đọc hiểu và cấu trúc hóa các yêu cầu thô được cung cấp bởi khách hàng hoặc các stakeholders. Mục tiêu là phân tách rõ ràng giữa các thông tin thực tế (Facts) và các giả định (Assumptions), phát hiện các khoảng trống nghiệp vụ (Gaps), và tạo cơ sở cho việc lập danh sách câu hỏi làm rõ (Q&A) cũng như dự thảo spec ban đầu.
 
+Ngôn ngữ output: auto-detect theo ngôn ngữ của ticket/task input — xem `custom/rules/output-language.md` (input tiếng Việt → output tiếng Việt; ngược lại mặc định tiếng Anh).
+
 ## 2. Kiến thức cần có (Prerequisite Knowledge)
 - **Tư duy phân tích (Analytical Thinking):** Khả năng chia nhỏ một yêu cầu lớn thành các luồng nghiệp vụ nhỏ và các thành phần cấu thành.
 - **Phân biệt Fact vs. Assumption:**

package/custom/skills/ba-skills/skill-ba-mermaid-flowchart-v1.md

@@ -3,6 +3,8 @@
 ## 1. Mục đích (Purpose)
 Kỹ năng này giúp BA chuyển đổi các đặc tả luồng nghiệp vụ văn bản (Main flow, Alternative flows, Exception flows) thành một sơ đồ hoạt động trực quan (Activity Diagram) sử dụng mã nguồn Mermaid. Sơ đồ này giúp lập trình viên nắm bắt luồng đi tổng thể của hệ thống một cách tức thì và giúp kiểm thử viên xác minh các nhánh rẽ của kịch bản.
 
+Ngôn ngữ output: auto-detect theo ngôn ngữ của ticket/task input — xem `custom/rules/output-language.md` (input tiếng Việt → output tiếng Việt; ngược lại mặc định tiếng Anh).
+
 ## 2. Kiến thức cần có (Prerequisite Knowledge)
 - **Cấu trúc biểu đồ Flowchart trong Mermaid:**
   - Khai báo hướng biểu đồ: Dùng `graph TD` (Top-Down - từ trên xuống) hoặc `graph LR` (Left-to-Right - từ trái sang phải). Đối với quy trình nghiệp vụ phần mềm, khuyến nghị dùng `graph TD`.

package/custom/skills/ba-skills/skill-ba-qna-v1.md

@@ -3,6 +3,8 @@
 ## 1. Mục đích (Purpose)
 Kỹ năng này giúp BA thiết kế các câu hỏi rõ ràng, khách quan và chuyên nghiệp để gửi tới khách hàng/stakeholders nhằm làm rõ các khoảng trống nghiệp vụ (Gaps). Đồng thời, hướng dẫn cách tiếp nhận câu trả lời để cập nhật tài liệu phân tích một cách nhất quán, tránh hiểu sai hoặc tự ý giả định thông tin.
 
+Ngôn ngữ output: auto-detect theo ngôn ngữ của ticket/task input — xem `custom/rules/output-language.md` (input tiếng Việt → output tiếng Việt; ngược lại mặc định tiếng Anh).
+
 ## 2. Kiến thức cần có (Prerequisite Knowledge)
 - **Kỹ năng giao tiếp bằng văn bản (Written Communication):** Sử dụng câu từ ngắn gọn, lịch sự, đi thẳng vào vấn đề.
 - **Kỹ thuật đặt câu hỏi mở và đóng:**

package/custom/skills/ba-skills/skill-ba-ui-prototype-v1.md

@@ -3,6 +3,8 @@
 ## 1. Mục đích (Purpose)
 Kỹ năng này hướng dẫn BA thiết kế và hiện thực hóa giao diện người dùng (UI mockup/prototype) dưới dạng mã nguồn HTML/CSS tự chứa (self-contained). Prototype giúp khách hàng hình dung trực quan luồng đi của màn hình, đồng thời giúp lập trình viên và kiểm thử viên xác định chính xác cấu trúc trang, ID của các phần tử và vị trí hiển thị lỗi.
 
+Ngôn ngữ output: auto-detect theo ngôn ngữ của ticket/task input — xem `custom/rules/output-language.md` (input tiếng Việt → output tiếng Việt; ngược lại mặc định tiếng Anh).
+
 ## 2. Kiến thức cần có (Prerequisite Knowledge)
 - **HTML5 Semantic Tags:** Sử dụng các thẻ ngữ nghĩa như `<header>`, `<main>`, `<section>`, `<nav>`, `<form>`, `<input>`, `<button>`, `<label>` để trang web có cấu trúc chuẩn SEO và dễ kiểm thử.
 - **Vanilla CSS Layouts:** Thành thạo Flexbox và CSS Grid để dựng bố cục nhanh chóng, đáp ứng tốt trên các kích thước màn hình khác nhau (Responsive).

package/custom/skills/ba-skills/skill-ba-write-uc-spec-v1.md

@@ -3,6 +3,8 @@
 ## 1. Mục đích (Purpose)
 Kỹ năng này giúp BA chuyển hóa toàn bộ các thông tin yêu cầu nghiệp vụ đã được thống nhất sau quá trình Q&A thành một tài liệu Đặc tả Use Case (Use Case Spec) hoàn chỉnh. Tài liệu này là "nguồn sự thật duy nhất" (Single Source of Truth) giúp đội ngũ Dev lập trình chính xác và đội ngũ Test thiết kế toàn bộ kịch bản kiểm thử (Test Cases/Scripts).
 
+Ngôn ngữ output: auto-detect theo ngôn ngữ của ticket/task input — xem `custom/rules/output-language.md` (input tiếng Việt → output tiếng Việt; ngược lại mặc định tiếng Anh).
+
 ## 2. Kiến thức cần có (Prerequisite Knowledge)
 - **Cấu trúc Use Case chuẩn:** Hiểu rõ các thành phần của một Use Case Spec bao gồm: Thông tin chung, Mô tả màn hình, Mô tả thành phần UI, Luồng hoạt động (Activity Flow) và Quy tắc nghiệp vụ (Business Rules).
 - **Cách mô tả Luồng xử lý (Flow):** 

package/custom/skills/coverage-check/SKILL.md

@@ -93,6 +93,8 @@ Consolidate toàn bộ TCs (sau khi apply actions) vào **1 file duy nhất**:
 
 Lưu `test-plan/test-cases/final-testcases.md`:
 
+Ngôn ngữ output: auto-detect theo ngôn ngữ của ticket/testcase input — xem `custom/rules/output-language.md` và `custom/skills/test-skills/rules/qa-writing-standards.md` (input tiếng Việt → output tiếng Việt; ngược lại mặc định tiếng Anh; tiêu đề cột bảng vẫn giữ tiếng Anh).
+
 ```markdown
 # Final Test Cases — [Feature Name]
 

package/custom/skills/create-system-requirement/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: create-system-requirement
+description: Bridges UC Spec (BA, Gate 4) to Dev — investigates source code and translates the UC into System Requirement (Functional/Non-Functional Requirements, Business Rules → Validation Rules, Exception/Error Handling, Acceptance Tests). Runs once per functionId per UC Spec version, ideally BEFORE the first coding ticket. Gate 1 (`read-study-requirement`) warns (non-blocking) if this is missing or out of sync with the current UC Spec version — this skill is how DEV closes that gap.
+keywords: system requirement, uc spec, functionId, trace, acceptance test, exception handling, business rule, matching, version sync
+---
+
+# Create System Requirement — Bridge Gate (before Gate 1)
+
+> **Runs once per functionId per UC Spec version — NOT per ticket.**
+>
+> Principle: System Requirement is the Dev-facing translation of UC Spec (User Requirement). It must trace 1-1 to a specific UC Spec version, cover the full UC (flows, business rules, exceptions, acceptance criteria), and never invent content the UC Spec doesn't support. If anything is unclear, ask until it's Confirmed — do not guess.
+
+---
+
+## Trigger
+
+`create-system-requirement` is its own **task type** — 2 gates, selectable in the "Task type:" prompt of `ak use` (or auto-detected by `aiflow prompt "..."` — see `scripts/detect.js`). It is not invoked inline from within a coding ticket's session; it runs as its own task, tied to the `functionId` (not to a coding ticket).
+
+- **Gate 1** = Steps 0–4 below (resolve UC Spec, investigate source code, draft, Q&A until every Gap is Confirmed).
+- **Gate 2** = Steps 5–7 below (split decision, write output, present for APPROVED).
+
+**Hand-off from coding Gate 1 Pre-flight** (`read-study-requirement`, Step 0) when:
+- No `System-Requirement_v*.md` exists yet for this `functionId`, **or**
+- The existing one's `UC-Spec-Version` header does not match the UC Spec's current version, **or**
+- It exists and matches but its `Status` header is not `✅ Approved`.
+
+Any of these → coding Gate 1 shows a ⚠️ non-blocking warning and **continues** (it does not cancel). DEV can close the gap at any point — before or after the current ticket — by starting a new task with `ak use`, picking **"📐 Create System Requirement"** at the Task type prompt, and running it through both gates to APPROVED.
+
+---
+
+## Steps
+
+> Steps 0–4 = **Gate 1** (investigate & draft). Steps 5–7 = **Gate 2** (finalize & approve). Run `aiflow task next` between them like any other gated task.
+
+### Step 0: Pre-flight — Resolve functionId & Versions [Gate 1]
+
+0. `git status --porcelain` → clean tree → `git pull --ff-only`; dirty tree → skip pull, notify DEV (same rule as `read-study-requirement` Step 1.0).
+1. Resolve `functionId` from `.aiflow/context/current.json` (or ask DEV once if absent).
+2. Locate the current UC Spec: `AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v{N}.md` (highest non-archived version). **Not found → STOP.** Tell DEV the UC Spec must exist and be BA-signed-off before System Requirement can be created — this skill never fabricates a UC.
+3. Check `AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v*.md`:
+   - **None exists** → Mode = `CREATE` (go to Step 1).
+   - **Exists, `UC-Spec-Version` matches current UC Spec version** → nothing to do — this task is not needed; tell DEV the coding Gate 1 (`read-study-requirement`) can proceed directly.
+   - **Exists, `UC-Spec-Version` is older** → Mode = `RESYNC` (go to Step 1, but Step 3 diffs against the existing file instead of starting blank).
+
+---
+
+### Step 1: Read UC Spec (full) [Gate 1]
+
+Read all 5 sections of the UC Spec end-to-end — General Info + Main/Alternative/Exception Flows, Screen Description, UI Components, Activity Diagram, Business Rules (BR1 Validation / BR2 Saving / BR3 Authorization, or whatever domains the BA defined). Do not skim — every Functional Requirement, Validation Rule, Exception, and Acceptance Test written later must trace back to something read here.
+
+`RESYNC` mode: also read the previous `System-Requirement_v{N-1}.md` in full — it's the diff baseline for Step 3.
+
+---
+
+### Step 2: Investigate Source Code [Gate 1]
+
+Same methodology as `read-study-requirement` Step 1 (steps 4–5), reused here:
+- Read `CLAUDE.md` for architecture/conventions.
+- Find modules/files that implement or would implement this UC's Main Flow (existing feature being extended, or nearest analogous feature for a new one).
+- **If GitNexus MCP available:** `gitnexus: query()` / `gitnexus: context()` for the relevant area — same token-saving shortcut as `read-study-requirement`.
+- Identify **existing error-handling conventions** (error code format, message structure, exception class hierarchy) — the Exception & Error Handling section (Step 4 below) must reuse these, not invent a new convention.
+- Identify **existing data model / API surface** touched by this UC (tables, DTOs, endpoints) — feeds Section 6 of the output.
+
+This step exists so System Requirement reflects what the system *can actually do today*, not just what the UC Spec says in the abstract.
+
+---
+
+### Step 3: Draft Content — Translate UC → System Requirement [Gate 1]
+
+For every row in the UC Spec's Main Flow, Alternative/Exception Flows, and Business Rules, produce at least one corresponding item below, and record the UC reference it came from. Nothing goes into the draft without a traced source (UC Spec) or a confirmed answer from DEV — no invented content.
+
+- **Functional Requirements** — one per distinct system behavior in Main/Alternative Flow steps.
+- **Non-Functional Requirements** — from BR3-type rules (security, authz) or explicit constraints in the UC Spec / ticket context; do not invent performance/scale numbers that aren't stated anywhere — mark as Gap and ask instead.
+- **Business Rules → Validation Rules** — translate each BR into a concrete system-level rule, cross-referenced with the existing pattern found in Step 2 (or flagged if no existing pattern applies).
+- **Exception & Error Handling** — one per Exception Flow, using the error-handling convention found in Step 2.
+- **Acceptance Test Scenarios** — Given/When/Then, at least one per Main Flow outcome + one per Alternative/Exception Flow. This is the concrete deliverable requested by proposal #1 (acceptance tests generated from the spec, not copied from the ticket).
+
+**`RESYNC` mode:** diff the new UC Spec version against the previous one section by section; carry forward unchanged items, mark changed/removed items, draft new items only for the delta. Never silently drop an item without noting why in the Change Log.
+
+Classify every item as **Fact** (explicit in UC Spec or confirmed in code) / **Assumption** (inferred, unconfirmed) / **Gap** (missing entirely) — same convention as `read-study-requirement` Step 1.75.
+
+---
+
+### Step 4: Clarify via Q&A (ask until Confirmed) [Gate 1]
+
+- Ask **one question at a time**, prioritizing unresolved Assumptions/Gaps from Step 3.
+- **Do not run `aiflow task next` into Gate 2 while any Gap remains unresolved.** This is the hard rule from proposal #7 — no fabrication, no "reasonable default" for missing UC content. If DEV genuinely cannot answer (needs BA), stop and record it as an open item in Section 8 rather than guessing.
+- Do NOT invoke `superpowers:brainstorming` (same reason as `read-study-requirement`: its terminal state bypasses this gate's approval).
+- All Gaps Confirmed → present a short Gate 1 summary, wait for DEV to run `aiflow task next` before continuing to Step 5.
+
+---
+
+### Step 5: Decide Single File vs Split [Gate 2]
+
+**Default: one file.** `System-Requirement_v{N}.md` mirrors `UC-Spec_v{N}.md` 1-1 — most UCs stay a single, reviewable document. Split is the exception, triggered by any ONE of:
+
+| Signal | Threshold | Split by |
+|---|---|---|
+| Business-rule domain fan-out | 2+ BR domains (e.g. Validation, Authorization) each with 8+ concrete rules, touching different system layers | One sub-file per domain |
+| Module/service fan-out | Step 2 investigation shows 3+ separately deployable modules/services with little shared logic (e.g. separate microservice + separate batch job) | One sub-file per module |
+| Flow-count overload | 6+ Alternative/Exception flows AND draft would exceed ~300 lines | Split Exception & Error Handling into its own sub-file; keep Functional Requirements + Acceptance Tests together |
+| Size ceiling | Draft exceeds ~400 lines even without the above | Split along whichever axis (domain or module) holds the most content — never split by raw line count alone with no semantic seam |
+
+**Anti-pattern — do not split for this, escalate instead:** if the UC Spec itself reads like 2+ independent use cases bundled together (no shared Business Rule, no shared data entity, could be tested/shipped separately) → **stop, do not split System Requirement to cope.** Flag to BA that the UC Spec's granularity may need revisiting (per the kit's own convention, 1 UC should be 1 Function-ID). Splitting Dev's document to paper over a BA-side granularity problem just hides it.
+
+**When split occurs:** keep one master `System-Requirement_v{N}.md` as the index — holds header/metadata, the full Traceability Matrix, links to each sub-file, and the Change Log. Sub-files: `System-Requirement_v{N}_[Domain].md` (e.g. `_Validation.md`, `_BackendAPI.md`). The mandatory `UC-Spec-Version` header lives on the master file only.
+
+---
+
+### Step 6: Write Output [Gate 2]
+
+Save to `AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v{N}.md` (`N` = the UC Spec version this was traced against — **not** an independent counter):
+
+```markdown
+# System Requirement: [functionId] — [Feature Name]
+
+**Date:** [YYYY-MM-DD]
+**System-Requirement-Version:** v{N}
+**UC-Spec-Version:** [functionId] @ v{N}   <!-- MANDATORY — the 1-1 matching anchor -->
+**Source UC Spec:** AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v{N}.md
+**Status:** ⏸️ Waiting for Approval
+
+---
+
+## 0. Traceability Matrix
+| UC Reference (Flow / BR) | System Requirement Item(s) |
+|---|---|
+| Main Flow step 3 | FR-01 |
+| Exception Flow B | FR-05, ER-02 |
+| BR1.1 | VR-01 |
+
+## 1. Functional Requirements
+| ID | Requirement | Traced UC Ref | Type |
+|---|---|---|---|
+| FR-01 | ... | Main Flow #3 | Fact |
+
+## 2. Non-Functional Requirements
+| ID | Requirement | Traced UC Ref | Type |
+|---|---|---|---|
+| NFR-01 | ... | BR3.1 | Fact |
+
+## 3. Business Rules → Validation Rules
+| ID | System-level Rule | Traced UC BR | Existing Code Pattern |
+|---|---|---|---|
+| VR-01 | ... | BR1.1 | [file:line] |
+
+## 4. Exception & Error Handling
+| ID | Trigger Condition | System Behavior | Traced Exception Flow | Error Convention Used |
+|---|---|---|---|---|
+| ER-01 | ... | ... | Exception Flow B | [existing error code/class] |
+
+## 5. Acceptance Test Scenarios
+### AT-01: [Scenario] (Main Flow)
+- **Given** ...
+- **When** ...
+- **Then** ...
+
+### AT-02: [Scenario] (Exception Flow B)
+...
+
+## 6. Existing System Context
+### Related Modules / Files
+| File | Role | Current Behavior |
+|---|---|---|
+
+### Data / API Impact
+| Entity / Endpoint | Change Type | Note |
+|---|---|---|
+
+## 7. Facts / Assumptions / Gaps
+| Type | Item | Resolution |
+|---|---|---|
+
+## 8. Open Questions Log
+[Question asked → answer received → date. Unresolved Gaps stay listed here, never silently dropped.]
+
+## 9. Change Log
+| Date | Ticket | Change | Note |
+|---|---|---|---|
+| [YYYY-MM-DD] | — | Initial creation from UC Spec v{N} | |
+```
+
+Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md` (Vietnamese input → Vietnamese output; otherwise English).
+
+---
+
+### Step 7: Present for Approval [Gate 2]
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⏸️  GATE 2: SYSTEM REQUIREMENT READY
+
+FunctionId: [functionId]
+UC Spec:    v{N} (AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v{N}.md)
+File:       AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v{N}.md
+Mode:       CREATE | RESYNC
+
+Coverage:
+  Functional Requirements: [N]   Acceptance Tests: [N]
+  Validation Rules:        [N]   Exception Handling: [N]
+  Open Gaps:                [N]  ← must be 0 to approve
+
+Please review — matching 1-1 with UC Spec v{N} is the point of this document.
+  → Type APPROVED (then run `aiflow task next`) to close this task and clear
+    the Gate 1 warning for tickets on this functionId
+  → Or provide feedback to update
+
+⚠️  Until this task is APPROVED, coding Gate 1 for this functionId will keep
+    showing a non-blocking warning (it does not cancel).
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+- Any Gap still open → cannot approve; go back to Step 4 (re-open Gate 1).
+- DEV feedback → update draft → re-show prompt.
+- `APPROVED` → write `Status: ✅ Approved`, task is done — coding Gate 1 unlocks.
+
+---
+
+### Step 8: Later Update (invoked from inside coding Gate 1, not standalone)
+
+`read-study-requirement` Step 3 (end of Gate 1, per ticket) may discover a case, rule, or exception that the UC Spec supports but the current System Requirement missed. That step **proposes** an addition — presents the diff to DEV, does not write directly — and on confirmation appends it to the master file's relevant section plus a `Change Log` row (`Ticket: [ticketId]`). This skill owns the template/contract for that row; `read-study-requirement` owns triggering it.
+
+This does not bump `System-Requirement-Version` — the version stays tied to the UC Spec version. Only a new UC Spec version triggers `RESYNC` (Step 0).
+
+---
+
+## What This Skill Delegates vs Owns
+
+| Concern | Handled by |
+|---|---|
+| Source code investigation methodology | `read-study-requirement` Step 1 pattern (reused inline) / GitNexus MCP |
+| Fact/Assumption/Gap classification | This skill (inline, same convention as `read-study-requirement` Step 1.75) |
+| Q&A loop (one question at a time, no fabrication) | This skill (inline) |
+| UC Spec structure/content | `skill-ba-uc-template-v1.md` (read-only reference, never edited by this skill) |
+| Split decision | This skill (Step 5) |
+| Mid-ticket addition proposals | `read-study-requirement` Step 3 triggers; this skill owns the write contract |
+| Gate/approval mechanics | This skill (Step 7) |
+
+---
+
+## Mandatory Rules
+
+- ❌ **DO NOT** create System Requirement content that isn't traced to the UC Spec or a DEV-confirmed answer — no invented Functional Requirements, error messages, or NFR numbers.
+- ❌ **DO NOT** proceed to Step 5 while any Gap is unresolved.
+- ❌ **DO NOT** split into multiple files unless a Step 5 threshold is actually met — default is one file.
+- ❌ **DO NOT** split to paper over a UC Spec that bundles multiple independent use cases — escalate to BA instead.
+- ❌ **DO NOT** run this skill if the UC Spec isn't BA-signed-off yet — this skill never substitutes for missing UC Spec content.
+- ❌ **DO NOT** bump `System-Requirement-Version` independently of the UC Spec version.
+- ✅ **MUST** read the full UC Spec (Step 1) before drafting anything.
+- ✅ **MUST** investigate source code (Step 2) before drafting Exception/Error Handling or Existing System Context.
+- ✅ **MUST** carry the mandatory `UC-Spec-Version` header on the master file.
+- ✅ **MUST** surface a ⚠️ non-blocking warning (never a cancel) from the Gate 1 Pre-flight check until this skill reaches APPROVED.

package/custom/skills/deploy-model/SKILL.md

@@ -73,6 +73,8 @@ Update the model card drafted at Gate 4 with:
 
 The model card is the primary audit document for the deployed model.
 
+Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md` (Vietnamese input → Vietnamese output; otherwise English).
+
 ### 6. Create the PR
 
 Invoke `superpowers:requesting-code-review`. Open a PR that includes: serving code, model card, monitoring plan, and any pipeline changes. Link the ticket. Reference the eval report and the registered artifact version in the PR description.

package/custom/skills/design-experiment/SKILL.md

@@ -73,6 +73,8 @@ An open-ended experiment loop with no stopping rule is out of scope for a gated
 
 Write all of the above to `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md` (see `custom/rules/ml-conventions.md` — do NOT use the legacy `plan/[ticket-id]/` path). The document must be self-contained: a developer who did not attend the framing discussion should be able to reproduce the full experiment sequence from the plan alone.
 
+Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md` (Vietnamese input → Vietnamese output; otherwise English).
+
 ---
 
 ## Completion Checklist

package/custom/skills/evaluate-model/SKILL.md

@@ -78,6 +78,8 @@ Output `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` (see `custom/ru
 
 Draft a model card covering: intended use, training data description, evaluation metrics and their context, known limitations, and owner/contact.
 
+Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md` (Vietnamese input → Vietnamese output; otherwise English).
+
 ---
 
 ## Completion Checklist