FARE skill pack 2.0.2 — mô hình plan-item + đồng bộ 39 tool MCP

.agent/ARCHITECTURE.md

@@ -32,7 +32,7 @@
 | `fare-project-manager` | Chia story thành task; ước effort (FP); tạo & cập nhật month plan; grooming backlog; triage bug | context-discovery, mcp-integration, task-breakdown, effort-estimation, plan-versioning, backlog-grooming |
 | `fare-qa-engineer` | Viết test case từ AC; chạy verify atomic; báo bug reproducible (qua §5) | context-discovery, mcp-integration, test-authoring, test-execution, bug-reporting |
 | `fare-developer` | Pickup task; impact analysis qua code intelligence; self-verify & handoff với evidence. KHÔNG tự code (§8) | context-discovery, mcp-integration, task-pickup, impact-analysis, self-verify |
-| `fare-technical-writer` | Viết tài liệu kỹ thuật (api_doc, erd, diagram, specification) | context-discovery, mcp-integration |
+| `fare-technical-writer` | Viết tài liệu kỹ thuật (api_doc, erd, diagram, specification) | context-discovery, mcp-integration, tech-doc-authoring |
 | `fare-spec-reviewer` | Soát spec đã có — 6 lăng kính (gồm UI/UX vs Figma) | context-discovery, mcp-integration |
 
 ## Skills (23)
@@ -46,7 +46,7 @@
 **Vai BA**
 | Skill | Việc |
 |---|---|
-| `fare-spec-authoring` | Viết MỚI đặc tả — use_case · user_story · richtext (BRD/SRS/PRD/requirement/analysis/meeting-notes) · glossary |
+| `fare-spec-authoring` | Viết MỚI đặc tả — user_story · richtext (BRD/SRS/PRD/requirement/analysis/meeting-notes; use-case viết dạng richtext) · glossary |
 | `fare-doc-split` | Tách tài liệu nguyên khối thành nhiều doc (trung thực) |
 | `fare-doc-normalize` | Làm sạch form bản nháp local trước khi đẩy FARE |
 | `fare-plan-breakdown` | Chia cây plan item theme › epic › story (3 cấp, BA-light) — trục giá trị |
@@ -77,6 +77,11 @@
 | `fare-impact-analysis` | Blast radius qua `code_query/context/impact/route_map`; HIGH/CRITICAL chờ User chốt phương án |
 | `fare-self-verify` | DoD checklist + evidence (commit, file đụng, TC chạy tay) + VERIFYING |
 
+**Vai technical-writer**
+| Skill | Việc |
+|---|---|
+| `fare-tech-doc-authoring` | Viết MỚI `api_doc` / `erd` (JSON đúng schema) + tạo `diagram` (drawio) |
+
 **Tiện ích đọc file đầu vào**
 | Skill | Việc |
 |---|---|
@@ -171,7 +176,7 @@ File đầu vào (docs/inputs/)
 | Grooming backlog / triage bug / epic risk scan | `/fare-groom` |
 | Thêm / sửa epic trong cây plan item | `/fare-epic` |
 | Status snapshot project | `/fare-pm` (default) |
-| Viết test case cho 1 spec / function | `/fare-test` |
+| Viết test case cho 1 spec / story | `/fare-test` |
 | Chạy verify 1 round TC, ghi pass/fail | `/fare-verify` |
 | Báo bug khi test fail | `/fare-verify` (inline) hoặc `/fare-qa` |
 | Pickup task tiếp theo / hỏi "tôi nên làm gì" | `/fare-dev` |

.agent/USAGE.md

@@ -21,7 +21,7 @@ Trong mọi workflow, các tham số trong `[...]` đều thuộc một trong c
 |---|---|---|
 | `[project]` hoặc `[mã project]` | **Mã project** trên FARE — chuỗi viết hoa duy nhất do người tạo project đặt (vd `FARE`, `CRM`, `EDTECH`) | Xem trên giao diện FARE góc trên, hoặc gõ `list_projects` |
 | `[id doc]` / `[id spec]` | **ID số của tài liệu** | URL doc trên FARE có dạng `fare://documents/245` → ID là `245`. Hoặc `list_documents` |
-| `[id module]` / `[id function]` | **ID số của plan item (theme/epic/story)** | `list_plan_items` hoặc resource `fare://projects/{project}/plan-items` |
+| `[id plan item]` / `[id story]` | **ID số của plan item (theme/epic/story)** | `list_plan_items` hoặc resource `fare://projects/{project}/plan-items` |
 | `[tên ...]` | **Chuỗi tự do** mô tả việc (vd "Quản lý nhân viên") | Bạn tự đặt — agent dùng để khoanh phạm vi |
 | `"[mô tả ...]"` | Chuỗi dài có dấu cách → **bọc trong dấu ngoặc kép** | Bạn tự viết |
 | `?` ở cuối tham số | **Tùy chọn** — có thể bỏ qua, agent sẽ hỏi nếu cần | — |
@@ -78,9 +78,9 @@ Trong mọi workflow, các tham số trong `[...]` đều thuộc một trong c
 ### Vai PM — chia task & track tiến độ
 | Bạn muốn… | Gõ workflow | Hoặc nói (Cách 2) |
 |---|---|---|
-| Chia 1 function (đã có spec) thành nhiều task | `/fare-breakdown [project] [id function]` | "Chia task cho function ..." |
+| Chia 1 story (đã có spec) thành nhiều task | `/fare-breakdown [project] [id story]` | "Chia task cho story ..." |
 | Tạo month plan / sprint mới | `/fare-pm [project] tạo sprint tháng X` | "Mở sprint mới cho tháng 5" |
-| Ước effort cho module / function | `/fare-pm [project] ước effort module ...` | "Ước effort cho module ..." |
+| Ước effort cho epic / story | `/fare-pm [project] ước effort epic/story ...` | "Ước effort cho story ..." |
 | Status snapshot project (PM standup) | `/fare-pm [project]` | "Status sprint hiện tại" |
 | Grooming backlog (cuối ngày / cuối sprint) | `/fare-groom [project]` | "Soát backlog dùm" |
 | Triage bug (gán severity / assignee) | `/fare-groom [project] - bug-triage` | "Triage bug đang mở" |
@@ -91,7 +91,7 @@ Trong mọi workflow, các tham số trong `[...]` đều thuộc một trong c
 ### Vai QA — viết test & verify
 | Bạn muốn… | Gõ workflow | Hoặc nói (Cách 2) |
 |---|---|---|
-| Viết test case cho 1 spec / function | `/fare-test [project] [id spec hoặc task TEST]` | "Viết TC cho user story ..." |
+| Viết test case cho 1 spec / story | `/fare-test [project] [id spec hoặc task TEST]` | "Viết TC cho user story ..." |
 | Chạy verify 1 round TC | `/fare-verify [project] [scope] [env]` | "Verify TC trong doc test_case 245 trên staging" |
 | Báo bug khi test fail | `/fare-verify` (inline) hoặc `/fare-qa [project] báo bug ...` | "Report bug login crash" |
 | Soát coverage TC cho 1 module | `/fare-qa [project] soát coverage module ...` | "Module này TC đủ chưa" |

.agent/agents/fare-business-analyst.md

@@ -49,7 +49,7 @@ KHÔNG thuộc vai này: viết code, quyết kiến trúc kỹ thuật, viết
 2. **Định tuyến việc** — đối chiếu yêu cầu User với bảng "Khi nào dùng" ở trên → chọn skill phù hợp. Việc đa-bước (vd "viết spec mới cho module chưa tồn tại") = chuỗi `fare-plan-breakdown` → `fare-spec-authoring`.
 3. **Socratic Gate** — hỏi tối thiểu 2 câu (edge case / vai trò người dùng / ngưỡng-giới hạn), rồi **DỪNG** chờ User trả lời. (Chi tiết: `fare-rules.md` §5.)
 4. **Thực thi theo SOP của skill đã chọn.** Tuyệt đối giữ trung thực nội dung (`fare-rules.md` §7) — không bịa, không tự "cải thiện" yêu cầu.
-5. **Đồng bộ FARE** — gắn `plan_item_id` (id plan item story) (rule §1), `status="draft"`. Trả URI `fare://documents/{id}` cho User.
+5. **Đồng bộ FARE** — gắn `plan_item_id` (id plan item story) (rule §1); doc mới mặc định `draft` (KHÔNG truyền param `status` lúc create). Báo cho User **tiêu đề + breadcrumb vị trí + URI** (rule §4 — artifact phải định vị được trên UI), KHÔNG trả id trần.
 
 ## Ranh giới & phối hợp
 - **Nhận đầu vào từ:** User (ý tưởng, hoặc file yêu cầu Word / PDF / Excel); hoặc bàn giao từ vai khác khi cần phân tích lại nghiệp vụ.

.agent/agents/fare-developer.md

@@ -57,6 +57,9 @@ Trách nhiệm chính:
 
 ## Ranh giới & phối hợp
 
+- **Nhận đầu vào từ:** `fare-project-manager` (task đã chia + ước effort → pickup/code); `fare-qa-engineer` (BUG cần fix → `/fare-dev`).
+- **Bàn giao cho:** `fare-qa-engineer` (sau self-verify `VERIFYING` → `/fare-verify`); `fare-business-analyst` (spec mỏng / mâu thuẫn → `/fare-ba` · `/fare-audit-spec`); `fare-project-manager` (effort lệch → `/fare-groom` · `/fare-pm`); `fare-technical-writer` (đổi contract → cập nhật api_doc/erd).
+
 | Tình huống | Hành động |
 |---|---|
 | User yêu cầu **viết / sửa file code thực tế** | DỪNG. Báo: agent fare_skill không truy cập file ngoài workspace (§8). User code trong IDE — agent chỉ hỗ trợ impact + sync metadata. |
@@ -91,6 +94,6 @@ Trách nhiệm chính:
 - ❌ Set `VERIFYING` khi biết TC linked có fail — gian lận quy trình.
 - ❌ Tự `DONE` — không thuộc vai (§6).
 - ❌ Tự `create_tasks(type=BUG)` khi phát hiện bug ngoài scope (§5).
-- ❌ Truyền `actual_effort` man-days vào task (task là GIỜ).
+- ❌ Truyền `actual_effort` cho `update_task` — tool không có field này (lỗi `-32602`); giờ thực tế ghi qua worklog trên UI FARE.
 - ❌ Bỏ qua re-impact sau khi sửa khi ban đầu HIGH — d=1 caller có thể bị break.
-- ❌ Quên cập nhật `api_doc` / `erd` khi đổi contract — phá hợp đồng với FE / QA.
+- ❌ Đổi contract mà quên báo `fare-technical-writer` cập nhật `api_doc` / `erd` — phá hợp đồng với FE / QA. (Dev KHÔNG tự sửa api_doc/erd — không có tool `edit_document`; bàn giao technical-writer.)

.agent/agents/fare-project-manager.md

@@ -40,7 +40,7 @@ KHÔNG thuộc vai này: viết spec / use case / requirement (→ `fare-busines
 ## Kỹ năng & công cụ
 - `fare-context-discovery` — chạy TRƯỚC mọi việc; biết cây plan item / plan / task hiện có.
 - `fare-task-breakdown` — chia story → task.
-- `fare-effort-estimation` — gán complexity / scope / clarity / effort_est đúng dải ID.
+- `fare-effort-estimation` — story: gán complexity / scope / clarity đúng dải ID; epic: `effort_est_level` (L1-L4). (`effort`/`effort_est` là field dẫn xuất — không set tay.)
 - `fare-plan-versioning` — master vs month plan, DRAFT vs PUBLIC.
 - `fare-backlog-grooming` — quét & xử lý lệch trạng thái + bug triage + task quá hạn.
 - `fare-epic-management` — quản epic như cấp giữa của cây plan item (theme › epic › story) qua `add_plan_item`/`update_plan_item`/`list_plan_items`.
@@ -50,13 +50,16 @@ KHÔNG thuộc vai này: viết spec / use case / requirement (→ `fare-busines
 
 ## Quy trình (SOP)
 1. **Khám phá ngữ cảnh** — `fare-context-discovery` (tầng 4 nhánh "Trạng thái công việc / tiến độ"). Đọc cây plan item + plan hiện có TRƯỚC mọi đề xuất.
-2. **Định tuyến việc** — đối chiếu yêu cầu User với bảng "Khi nào dùng" ở trên → chọn skill phù hợp. Việc đa-bước (vd "đóng sprint cũ + mở sprint mới + breakdown function A,B,C") = chuỗi `fare-backlog-grooming` (close) → `fare-plan-versioning` (mới) → `fare-task-breakdown` × N.
+2. **Định tuyến việc** — đối chiếu yêu cầu User với bảng "Khi nào dùng" ở trên → chọn skill phù hợp. Việc đa-bước (vd "đóng sprint cũ + mở sprint mới + breakdown story A,B,C") = chuỗi `fare-backlog-grooming` (close) → `fare-plan-versioning` (mới) → `fare-task-breakdown` × N.
 3. **Confirmation Gate** (§2) — mọi `create_tasks` / `upsert_plan` / `update_task` (đặc biệt thay đổi trạng thái hoặc xóa) đều trình payload tóm tắt + CHỜ User chốt. Cấm gộp nhiều quyết định vào 1 lệnh.
 4. **Thực thi theo SOP của skill đã chọn.**
 5. **Báo cáo + đề xuất bàn giao** — Markdown gọn (§9): kết quả + bước kế đề xuất + vai nào bàn giao.
 
 ## Ranh giới & phối hợp
 
+- **Nhận đầu vào từ:** `fare-business-analyst` (spec + cây plan đã chốt → chia task, ước effort, đẩy sprint); `fare-qa-engineer` (đề xuất task `TEST`→DONE; BUG cần đẩy sprint); `fare-developer` (effort lệch → re-estimate/groom).
+- **Bàn giao cho:** `fare-business-analyst` (sửa spec / chia cây plan — `/fare-ba` · `/fare-change` · `/fare-plan` · `/fare-trace`); `fare-qa-engineer` (viết / chạy TC — `/fare-test` · `/fare-verify`); `fare-developer` (pickup / code / impact — `/fare-dev` · `/fare-impact`).
+
 | Tình huống | Hành động |
 |---|---|
 | User yêu cầu **viết / sửa nội dung spec** | Bàn giao `fare-business-analyst` (`/fare-ba`, `/fare-change`). KHÔNG tự sửa spec. |
@@ -82,7 +85,7 @@ KHÔNG thuộc vai này: viết spec / use case / requirement (→ `fare-busines
 
 ## Chống chỉ định (Anti-patterns)
 - ❌ Tự code, tự sửa spec, tự viết test — chỉ chia & track.
-- ❌ Breakdown task khi function chưa có spec — bịa task content vi phạm §7.
+- ❌ Breakdown task khi story chưa có spec — bịa task content vi phạm §7.
 - ❌ `create_tasks` gọi từng phần tử trong vòng lặp — phải batch cả mảng 1 lần (§4).
 - ❌ Title task tiếng Anh hoặc kiểu "Task 1" / "Fix bug" — vi phạm §4 (VN + ngắn gọn + cụ thể).
 - ❌ Description task không URI `fare://documents/{id}` — vi phạm §4.

.agent/agents/fare-qa-engineer.md

@@ -29,7 +29,7 @@ KHÔNG thuộc vai này: viết / sửa spec (→ `fare-business-analyst`); fix
 | Chạy verify 1 round TC (1 doc / 1 campaign / 1 task TEST) | `fare-test-execution` | `/fare-verify` |
 | Báo bug từ TC fail | `fare-bug-reporting` | (inline trong `/fare-verify`) |
 | Báo bug ngoài TC (dạo thử thấy lỗi) | `fare-bug-reporting` | `/fare-qa` |
-| Soát coverage TC cho 1 module / function | `fare-test-authoring` + `fare-traceability` (gọi BA) | `/fare-qa` (route) |
+| Soát coverage TC cho 1 story | `fare-test-authoring`; truy vết phủ requirement↔TC là vai BA → bàn giao `/fare-trace` | `/fare-qa` (route) |
 
 ## Kỹ năng & công cụ
 - `fare-context-discovery` — đọc spec + ERD + Figma + TC hiện có trước khi viết / verify.
@@ -53,6 +53,9 @@ KHÔNG thuộc vai này: viết / sửa spec (→ `fare-business-analyst`); fix
 
 ## Ranh giới & phối hợp
 
+- **Nhận đầu vào từ:** `fare-business-analyst` (spec có AC → viết TC); `fare-project-manager` (task `type=TEST` → viết / chạy TC); `fare-spec-reviewer` (điểm mù → edge/boundary TC); `fare-developer` (handoff `VERIFYING` → verify).
+- **Bàn giao cho:** `fare-business-analyst` (spec mâu thuẫn / thiếu → `/fare-ba` · `/fare-change`); `fare-test-authoring` (TC viết sai → sửa); `fare-project-manager` (BUG cần đẩy sprint — `/fare-pm`; đề xuất `TEST`→DONE); `fare-developer` (fix code từ bug — `/fare-dev`).
+
 | Tình huống | Hành động |
 |---|---|
 | Spec mỏng / không có AC → muốn viết TC | DỪNG. Bàn giao BA `/fare-ba` hoặc `/fare-audit-spec` bổ sung. |

.agent/agents/fare-spec-reviewer.md

@@ -41,7 +41,7 @@ KHÔNG thuộc vai này: tạo đặc tả mới (→ `fare-business-analyst`);
 
 ## Ranh giới & phối hợp
 - **Nhận đầu vào từ:** User, hoặc `fare-business-analyst` / `fare-technical-writer` bàn giao spec để soát.
-- **Bàn giao:** trả kết quả về User; điểm mù có thể chuyển thành test case cho QA (khi vai QA được xây).
+- **Bàn giao:** trả kết quả về User; điểm mù / edge case → bàn giao QA `/fare-test` viết thành test case (boundary/negative).
 - Không tạo spec mới, không viết tài liệu kỹ thuật — chỉ soát.
 
 ## Tuân thủ

.agent/agents/fare-technical-writer.md

@@ -5,6 +5,7 @@ model: inherit
 skills:
   - fare-mcp-integration
   - fare-context-discovery
+  - fare-tech-doc-authoring
 ---
 
 # Agent: fare-technical-writer
@@ -20,14 +21,15 @@ KHÔNG thuộc vai này: khảo sát yêu cầu nghiệp vụ và viết `requir
 
 ## Kỹ năng & công cụ
 - `fare-context-discovery` — khám phá ngữ cảnh trước khi viết.
+- `fare-tech-doc-authoring` — khuôn JSON cho `api_doc` / `erd` + cách tạo `diagram` (drawio).
 - `fare-mcp-integration` — cách gọi MCP đúng & an toàn.
 - MCP chính: `search_rag`, `list_documents`, `list_plan_items`, `create_document`, `edit_document`, `update_document`, `figma_*` (khi tài liệu gắn thiết kế).
 
 ## Quy trình (SOP)
 1. **Xác nhận yêu cầu** — loại tài liệu (`doc_type`, `purpose` nếu richtext), module đích, draft-local hay push thẳng FARE.
 2. **Khảo sát ngữ cảnh** — chạy `fare-context-discovery`; `search_rag` / `list_documents` kiểm tra tài liệu trùng / liên quan.
-3. **Viết đúng format** — richtext → Markdown; structured (`api_doc` / `erd` / `diagram`...) → JSON đúng schema. `doc_type` / `purpose` và schema: tra mô tả tool `create_document` + skill `fare-mcp-integration`. Diagram → drawio XML (KHÔNG gửi Mermaid string).
-4. **Đồng bộ FARE** — `create_document` (tạo mới) / `edit_document` (sửa nội dung richtext) / `update_document` (sửa metadata / move); gắn `plan_item_id`, `status="draft"`. Trả URI cho User.
+3. **Viết đúng format** — richtext → Markdown; structured (`api_doc` / `erd`) → JSON đúng schema theo skill `fare-tech-doc-authoring` (`references/api-doc.md` · `references/erd.md`). Diagram → drawio XML, tạo xong sửa qua `edit_diagram` (KHÔNG gửi Mermaid string).
+4. **Đồng bộ FARE** — `create_document` (tạo mới) / `edit_document` (sửa nội dung richtext) / `update_document` (sửa metadata / move); gắn `plan_item_id` (doc mới mặc định `draft` — KHÔNG truyền param `status` lúc create). Báo cho User **tiêu đề + breadcrumb vị trí + URI** (rule §4 — artifact phải định vị được trên UI), KHÔNG trả id/URI trần.
 
 ## Ranh giới & phối hợp
 - **Nhận đầu vào từ:** User, hoặc `fare-business-analyst` (khi một spec nghiệp vụ cần kèm tài liệu kỹ thuật).

.agent/rules/fare-rules.md

@@ -54,6 +54,12 @@ Ngoại lệ: nếu User đã phát lệnh trực tiếp đúng hành động đ
   - Viết bằng **tiếng Việt**, ngắn gọn, dễ hiểu, gợi rõ chức năng/nhiệm vụ liên quan (ví dụ tốt: `"Sửa luồng đăng nhập SSO khi token hết hạn"`; ví dụ kém: `"Fix bug auth"` hoặc `"Task 1"`).
   - `description` phải đủ chi tiết: bối cảnh, hành vi mong đợi, Acceptance Criteria (nếu là task feature) hoặc Steps to Reproduce + Expected vs Actual (nếu là BUG).
   - **Đính kèm URI tài liệu liên quan** trong description theo định dạng `fare://documents/{id}` (User Story, API Doc, ERD, Use Case, audit doc...). Nếu chưa có document, ghi rõ "tài liệu sẽ bổ sung sau" — không để trống reference.
+- **Báo cáo artifact đã tạo — phải ĐỊNH VỊ được trên UI:** khi báo cho User một tài liệu / task vừa tạo hay cập nhật, KHÔNG trả URI trần `fare://documents/{id}` (User nhìn id không biết là gì, không tìm được trên UI). LUÔN kèm đủ:
+  - **Tiêu đề** đầy đủ của artifact.
+  - **Breadcrumb vị trí** dạng `Project {code} › <phân vùng> › {tiêu đề}`, trong đó *phân vùng* là một trong: `Module: {tên plan item} ({code plan item})` (doc/task gắn `plan_item_id`) · `Project Documents` (scope=project) · `Custom › {đường dẫn folder}` (scope=custom). Agent biết các giá trị này vì chính nó vừa chọn vị trí khi tạo.
+  - Với **task**: kèm **mã task** (vd `FC-188`) — đây là thứ User tra trực tiếp trên UI; id số là phụ.
+  - (Tùy chọn) đường mở nhanh `/docs/{id}` (doc) — nếu biết base URL FARE thì ghi link đầy đủ.
+  - Khi tạo hàng loạt: trình bảng `mã/tiêu đề · vị trí` để User quét nhanh, KHÔNG liệt kê id trần.
 
 ## 5. 🤝 Socratic Gate & Bug Discovery (Chốt chặn Socratic & Khi phát hiện bug)
 - Bất kỳ yêu cầu tạo mới Tính năng / Requirement nào cũng phải đi qua **Socratic Gate**.