diff --git a/.agent/ARCHITECTURE.md b/.agent/ARCHITECTURE.md index 91c6270..05a0f69 100644 --- a/.agent/ARCHITECTURE.md +++ b/.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` | diff --git a/.agent/USAGE.md b/.agent/USAGE.md index 2b196ef..d28bff1 100644 --- a/.agent/USAGE.md +++ b/.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" | diff --git a/.agent/agents/fare-business-analyst.md b/.agent/agents/fare-business-analyst.md index 2ede89e..1dcbfde 100644 --- a/.agent/agents/fare-business-analyst.md +++ b/.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ụ. diff --git a/.agent/agents/fare-developer.md b/.agent/agents/fare-developer.md index 50f7769..dc0f87b 100644 --- a/.agent/agents/fare-developer.md +++ b/.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.) diff --git a/.agent/agents/fare-project-manager.md b/.agent/agents/fare-project-manager.md index 35eae9c..37cfcd2 100644 --- a/.agent/agents/fare-project-manager.md +++ b/.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. diff --git a/.agent/agents/fare-qa-engineer.md b/.agent/agents/fare-qa-engineer.md index 30e659f..f0f293e 100644 --- a/.agent/agents/fare-qa-engineer.md +++ b/.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. | diff --git a/.agent/agents/fare-spec-reviewer.md b/.agent/agents/fare-spec-reviewer.md index 813afbc..05ac8bf 100644 --- a/.agent/agents/fare-spec-reviewer.md +++ b/.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ủ diff --git a/.agent/agents/fare-technical-writer.md b/.agent/agents/fare-technical-writer.md index 5d225e5..e718482 100644 --- a/.agent/agents/fare-technical-writer.md +++ b/.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). diff --git a/.agent/rules/fare-rules.md b/.agent/rules/fare-rules.md index daad92c..5a88a9f 100644 --- a/.agent/rules/fare-rules.md +++ b/.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} › › {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**. diff --git a/.agent/skills/fare-backlog-grooming/SKILL.md b/.agent/skills/fare-backlog-grooming/SKILL.md index ae35811..74a71f5 100644 --- a/.agent/skills/fare-backlog-grooming/SKILL.md +++ b/.agent/skills/fare-backlog-grooming/SKILL.md @@ -1,6 +1,6 @@ --- name: fare-backlog-grooming -description: Review backlog định kỳ — quét task lệch trạng thái (IN_PROGRESS không activity, DONE chưa verify, TODO không owner / quá hạn), bug triage (sắp xếp severity / assign), phát hiện task mồ côi (không module / không spec). Đề xuất hành động sửa và CHỜ User chốt — KHÔNG tự đổi trạng thái hàng loạt. +description: Review backlog định kỳ — quét task lệch trạng thái (IN_PROGRESS không activity, DONE chưa verify, TODO không owner / quá hạn), bug triage (sắp xếp severity / assign), phát hiện task mồ côi (không plan item / không spec). Đề xuất hành động sửa và CHỜ User chốt — KHÔNG tự đổi trạng thái hàng loạt. --- # fare-backlog-grooming — Grooming backlog @@ -22,10 +22,10 @@ Hỏi & CHỜ: | Truy vấn | Mục đích | |---|---| -| `list_tasks(projectCode, plan_month_id?, meta_status="IN_PROGRESS")` | Task đang code | -| `list_tasks(projectCode, plan_month_id?, meta_status="VERIFYING")` | Task chờ verify | -| `list_tasks(projectCode, plan_month_id?, meta_status="DONE")` | Task đóng — kiểm verify | -| `list_tasks(projectCode, plan_month_id?, meta_status="TODO", type="TASK")` | Backlog chưa pickup | +| `list_tasks(projectCode, plan_month_id?, status="IN_PROGRESS")` | Task đang code | +| `list_tasks(projectCode, plan_month_id?, status="VERIFYING")` | Task chờ verify | +| `list_tasks(projectCode, plan_month_id?, status="DONE")` | Task đóng — kiểm verify | +| `list_tasks(projectCode, plan_month_id?, status="TODO", type="TASK")` | Backlog chưa pickup | | `list_tasks(projectCode, type="BUG")` | Bug list — không lọc status, để thấy mọi bug đang mở | | `list_tasks(projectCode, type="BUG", bug_origin="INTRINSIC")` | Bug nội sinh đang chặn task cha (xem `linked_task_id` để biết chặn task nào) | | `list_tasks(projectCode, type="BUG", bug_origin="EXTRINSIC")` | Bug độc lập — triage riêng, không chặn task | @@ -43,7 +43,7 @@ Với mỗi task `IN_PROGRESS`: `list_tasks(id=)` lấy chi tiết + comment | **Skip lifecycle** | Lịch sử nhảy `TODO → DONE` không qua `IN_PROGRESS`/`VERIFYING` | 🟥 BLOCKER — vi phạm §6 | | **Quá hạn** | `end_at < hôm nay` mà `meta_status ≠ DONE` | 🟧 HIGH | | **Mồ côi spec** | `description` không có URI `fare://documents/{id}` | 🟨 MEDIUM — vi phạm §4 | -| **Mồ côi module** | `plan_item_id` rỗng / không hợp lệ | 🟥 BLOCKER — vi phạm §1 (nhưng FARE schema cấm, hiếm gặp) | +| **Task mồ côi (thiếu plan item)** | `plan_item_id` rỗng / không hợp lệ | 🟥 BLOCKER — vi phạm §1 (nhưng FARE schema cấm, hiếm gặp) | | **TODO bỏ quên** | `created_at` > 14 ngày mà vẫn `TODO`, không assignee | 🟨 MEDIUM — backlog có khả năng outdated | | **Bug chưa triage** | `type=BUG` không có `severity` hoặc `priority` | 🟧 HIGH | | **Bug stuck** | `type=BUG` `severity=blocker` mà `TODO` > 24h | 🟥 BLOCKER | diff --git a/.agent/skills/fare-bug-reporting/SKILL.md b/.agent/skills/fare-bug-reporting/SKILL.md index beccc12..533e192 100644 --- a/.agent/skills/fare-bug-reporting/SKILL.md +++ b/.agent/skills/fare-bug-reporting/SKILL.md @@ -115,7 +115,7 @@ Tránh: `Fix login`, `Bug auth`, `Task 4` — quá mơ hồ (§4). 2. **Suy luận sơ bộ** (không quá xa — chỉ trên dữ liệu có): - Root cause: hệ thống nào lỗi (BE / FE / DB / 3rd party / config)? - Plan item (epic/story) / thành phần ảnh hưởng: tra qua `list_tasks` / `code_query` nếu có index code. - - Có bug tương tự đang mở? `list_tasks(projectCode, type="BUG", search=...)` — tránh tạo trùng. + - Có bug tương tự đang mở? `list_tasks(projectCode, type="BUG", q=...)` — tránh tạo trùng. 3. **Soạn bản nháp BUG** đầy đủ Steps/Expected/Actual/Evidence/Tham chiếu/Severity/Priority + **`bug_origin` + `linked_task_id`** (nếu INTRINSIC). 4. **Báo cáo Markdown + HỎI User** (rule §5): ``` @@ -124,7 +124,7 @@ Tránh: `Fix login`, `Bug auth`, `Task 4` — quá mơ hồ (§4). → Đề xuất tạo BUG task title "[BUG] ..." trên project FARE bug_origin=INTRINSIC, linked_task_id=87 (task TEST gốc), - severity=major, priority=high, plan_item_id=. + severity=major, priority=high, plan_item_id=. (INTRINSIC sẽ chặn task #87 chuyển DONE đến khi bug đóng.) Tạo không? @@ -163,12 +163,12 @@ Tránh: `Fix login`, `Bug auth`, `Task 4` — quá mơ hồ (§4). ## Tự kiểm - [ ] Đã có bằng chứng cụ thể (TC fail với actual rõ, hoặc reproduction tay). -- [ ] Đã kiểm bug tương tự không trùng (`list_tasks(type="BUG", search=...)`). +- [ ] Đã kiểm bug tương tự không trùng (`list_tasks(type="BUG", q=...)`). - [ ] Nháp BUG đầy đủ Steps / Expected / Actual / Env / Evidence / Tham chiếu / Severity / Priority đề xuất. - [ ] Đã trình nháp + HỎI User → chờ User xác nhận TRƯỚC khi `create_tasks` (§5). - [ ] Title dạng `[BUG] {hiện tượng cụ thể} — {nơi}`. - [ ] Phân biệt severity ↔ priority — không gán giống nhau cơ học. - [ ] Đã xác định `bug_origin`: TC fail → INTRINSIC + `linked_task_id` task cha; bug độc lập → EXTRINSIC. Không chắc đã hỏi User. -- [ ] BUG có `plan_item_id` của function chứa bug (§1). +- [ ] BUG có `plan_item_id` của story chứa bug (§1). - [ ] Sau khi tạo BUG → đã cập nhật TC fail với `linked_task_id=` (truy nguồn 2 chiều). - [ ] Trường hợp KHÔNG nên tạo BUG (TC viết sai / spec mơ hồ / không reproduce / trùng) → đã chuyển sang hành động đúng. diff --git a/.agent/skills/fare-change-request/SKILL.md b/.agent/skills/fare-change-request/SKILL.md index 4078781..d6f03f0 100644 --- a/.agent/skills/fare-change-request/SKILL.md +++ b/.agent/skills/fare-change-request/SKILL.md @@ -65,12 +65,12 @@ Báo cáo `## Impact Assessment` — nhóm theo mức rủi ro 🟥/🟧/🟨 (t | yyyy-mm-dd | vN→vN+1 | {tóm tắt diff theo bullet} | {nguồn ở Bước 1} | ``` - Structured: nếu schema không có chỗ → ghi log vào 1 `add_comment` của doc (description gắn URI yêu cầu thay đổi). -- **Status:** giữ `draft` (hoặc `in_review` nếu User yêu cầu gửi soát). **KHÔNG `approved`** (§7). +- **Status:** giữ `draft` (hoặc `in_review` qua `update_document(status="in_review")` nếu User yêu cầu gửi soát). **KHÔNG `approved`** (§7). - **Publish / bump version:** việc của User — KHÔNG tự gọi tool publish. ### Sau Bước 5 — Bàn giao downstream - UC/US bị đổi flows/AC → đề xuất `fare-spec-reviewer` soát lại blind spot. -- Test case bị ảnh hưởng → đề xuất bàn giao QA cập nhật (khi vai QA có). +- Test case bị ảnh hưởng → đề xuất bàn giao QA `/fare-test` cập nhật. - Task downstream `DONE` mà spec đổi sau khi code → đề xuất tạo task BUG / re-verify (NHƯNG theo rule §5: chỉ tạo BUG sau khi User xác nhận). - **Nhánh epic bị ảnh hưởng** → nếu thay đổi đụng nhiều story dưới cùng epic → bàn giao PM `/fare-pm` xem lại phạm vi / month plan của nhánh đó (`list_tasks(plan_item_ids=[], include_descendants=true)` để soát task chịu ảnh hưởng). @@ -89,4 +89,4 @@ Báo cáo `## Impact Assessment` — nhóm theo mức rủi ro 🟥/🟧/🟨 (t - [ ] Diff đã được User chốt TRƯỚC khi `edit_document` / `update_document` (§2). - [ ] Richtext dùng `edit_document` (block ops); structured gửi FULL JSON qua `edit_document(replace_all)`. - [ ] Change log đã ghi (block hoặc comment) — không sửa "lặng". -- [ ] `status="draft"` hoặc `in_review` — KHÔNG `approved`. Việc publish dành cho User. +- [ ] `status` ở `draft` hoặc `review` — KHÔNG `approved`. Việc publish dành cho User. diff --git a/.agent/skills/fare-context-discovery/SKILL.md b/.agent/skills/fare-context-discovery/SKILL.md index 5a69727..bc866c0 100644 --- a/.agent/skills/fare-context-discovery/SKILL.md +++ b/.agent/skills/fare-context-discovery/SKILL.md @@ -32,6 +32,12 @@ Skill này dạy cách dùng **MCP `fare` tools** để dựng đủ ngữ cản - Phân trang cắt ngang thẻ HTML/bảng → tự ghép lại; cần ID block ổn định để sửa thì dùng `mode="blocks"`. - Artifact khác: `list_tasks(id=)`, `list_test_cases(id=)` — truyền `id` để lấy chi tiết đầy đủ 1 task / test case. Trang mô tả của folder/module: tìm qua `list_documents`. +> **Greenfield — đầu vào là file ngoài / feature CHƯA có trên FARE.** Vai BA thường nhận **file khách (Word/PDF/Excel)** cho một chức năng chưa tồn tại → KHÔNG có artifact mỏ neo để `read_document(id)`, không có `id/kind/status`. Khi đó: +> - **Đọc file nguồn** bằng skill `docx` / `pdf` / `xlsx` → trích cấu trúc yêu cầu thô (FR, actor, luồng). +> - **"Mỏ neo" đổi nghĩa thành NƠI feature sẽ đáp xuống:** `list_projects` dò project đích (chưa có project → DỪNG, đề nghị User tạo — xem tiền điều kiện `/fare-ba`); `list_plan_items` kiểm cây xem đã có nhánh theme/epic/story để gắn chưa. Chưa có chỗ gắn → đánh dấu "cần `/fare-plan` dựng cây trước" (rule §1). +> - **Vẫn chạy Tầng 2–3** (hàng xóm, glossary, ERD anh em) để feature mới không mâu thuẫn / trùng cái đã có. +> - Xuất **Bản đồ ngữ cảnh — biến thể greenfield** (mẫu cuối file): không có id mỏ neo; thay bằng nguồn file + project đích + nhánh plan dự kiến / "chưa tồn tại". + ### Tầng 2 — Hàng xóm & cấu trúc - `list_documents(projectCode, scope)` → cây thư mục. Tài liệu anh em cho biết artifact thuộc một *bộ* (vd SRS nhiều module). - Đọc tài liệu Preamble / Tổng quan / Glossary anh em để lấy domain, vai trò, thuật ngữ chuẩn. @@ -83,7 +89,7 @@ Tham chiếu chéo: Đối chiếu nguồn khác: - ERD: -- Plan/module: <đã có breakdown? khớp tài liệu không?> +- Plan item: <đã có breakdown cây theme/epic/story? khớp tài liệu không?> - Code/Figma: Khoảng trống & rủi ro: @@ -92,9 +98,29 @@ Khoảng trống & rủi ro: ``` +### Biến thể greenfield (đầu vào là file ngoài, chưa có mỏ neo trên FARE) +``` +## Bản đồ ngữ cảnh: (greenfield) + +Nguồn: file · +Mỏ neo (đích): project · nhánh plan dự kiến: +Domain/vai trò: + +Cấu trúc yêu cầu thô (từ file): +- FR-xxx ... + +Đối chiếu cái đã có trên FARE: +- Tài liệu / feature anh em: +- ERD / glossary liên quan: + +Khoảng trống & rủi ro: +Độ tin cậy: +Cần người xác nhận: <...> +``` + ## Tự kiểm trước khi kết thúc -1. Đã đọc hết artifact mỏ neo (không bỏ trang)? +1. Đã đọc hết artifact mỏ neo (không bỏ trang)? — *greenfield:* đã đọc hết file nguồn + xác định project đích & nhánh plan để gắn (hoặc đánh dấu "cần /fare-plan")? 2. Đã xem cây thư mục và đọc tài liệu định hướng (Tổng quan/Glossary)? 3. Mọi tham chiếu chéo đều đã phân giải hoặc được đánh dấu rõ? 4. Đã đào đúng tầng 4 mà mục tiêu kế tiếp cần (ERD / code / Figma / plan)? diff --git a/.agent/skills/fare-doc-split/SKILL.md b/.agent/skills/fare-doc-split/SKILL.md index d0dc605..5e9c349 100644 --- a/.agent/skills/fare-doc-split/SKILL.md +++ b/.agent/skills/fare-doc-split/SKILL.md @@ -8,7 +8,7 @@ description: Tách một tài liệu nguyên khối thành nhiều tài liệu F Dùng khi có một tài liệu nguồn nguyên khối (nhiều mục đánh số 1.1, 1.2…) cần tách thành nhiều tài liệu FARE. ## Tiền đề -- Đã có **Bản đồ ngữ cảnh** (folder / module hiện có, ERD, tài liệu anh em). Nếu đã chạy `fare-context-discovery` ở bước trước trong phiên → dùng lại, KHÔNG chạy lại. +- Đã có **Bản đồ ngữ cảnh** (folder / cây plan item hiện có, ERD, tài liệu anh em). Nếu đã chạy `fare-context-discovery` ở bước trước trong phiên → dùng lại, KHÔNG chạy lại. - Tuân `rules/fare-rules.md` — đặc biệt §7 Content Fidelity, §2 Confirmation Gate, §8, §9. ## ⚠️ Nguyên tắc tối cao: TRUNG THỰC (§7) @@ -98,9 +98,9 @@ Nháp lúc này còn **form thô** (bảng HTML từ nguồn) — bình thườn Chỉ làm khi User đã duyệt nháp VÀ ra lệnh đẩy. 1. **Xem cấu trúc FARE hiện có.** Đọc resource `fare://projects/{code}/knowledge-tree` — trả cây đầy đủ: `custom_documents` (các folder kèm `id`/`parent_id`/`documents`), `project_documents`, `module_documents` (doc gắn plan item). FARE KHÔNG có tool riêng liệt kê folder — cấu trúc nằm trong resource này. -2. **Đặt theo cách project ĐÃ tổ chức tài liệu tương tự — KHÔNG mặc định.** Soi cây: một bộ tách trước đó (vd các mục "2.x") đang nằm đâu, gom theo kiểu gì → làm theo đúng kiểu đó. Tài liệu FARE có thể ở folder Custom / Project / gắn Module — chọn theo cấu trúc sẵn có; KHÔNG mặc định folder của tài liệu nguồn, cũng KHÔNG mặc định Module. -3. **Đề xuất + CHỜ User chốt** (`fare-rules §2`): trình bày cấu trúc liên quan (rút gọn) + đề xuất vị trí cho cả bộ doc (kể cả tạo folder Custom mới nếu mô phỏng bộ tách trước) + lý do. KHÔNG `create_document` khi User chưa chốt. KHÔNG tự tạo Module / Function (xem Phạm vi). -4. **Tạo.** `create_document` từng file, `status="draft"`, đặt đúng vị trí đã chốt — cơ chế `folder_id` / `plan_item_id` / `path`: xem `fare-mcp-integration`. +2. **Đặt theo cách project ĐÃ tổ chức tài liệu tương tự — KHÔNG mặc định.** Soi cây: một bộ tách trước đó (vd các mục "2.x") đang nằm đâu, gom theo kiểu gì → làm theo đúng kiểu đó. Tài liệu FARE có thể ở folder Custom / Project / gắn plan item (Module Documents) — chọn theo cấu trúc sẵn có; KHÔNG mặc định folder của tài liệu nguồn, cũng KHÔNG mặc định gắn plan item. +3. **Đề xuất + CHỜ User chốt** (`fare-rules §2`): trình bày cấu trúc liên quan (rút gọn) + đề xuất vị trí cho cả bộ doc (kể cả tạo folder Custom mới nếu mô phỏng bộ tách trước) + lý do. KHÔNG `create_document` khi User chưa chốt. KHÔNG tự tạo plan item — theme / epic / story (xem Phạm vi). +4. **Tạo.** `create_document` từng file (doc mặc định `draft` — KHÔNG truyền param `status`, create không nhận), đặt đúng vị trí đã chốt — cơ chế `folder_id` / `plan_item_id` / `path`: xem `fare-mcp-integration`. 5. **Nối link** = **chip mention**, KHÔNG dùng markdown link. Sau khi mọi doc có ID, nâng `{số} {tên}` → ```html {số} {tên} @@ -127,5 +127,5 @@ Chỉ làm khi User đã duyệt nháp VÀ ra lệnh đẩy. - [ ] Cross-ref mọi dạng (số trần / "(Mục X.Y)" / số lạ) → `{số} {tên}`; không phân giải được → giữ `{số}` + ghi **sổ phát hiện** (KHÔNG `⚠️` trong thân). - [ ] Suy luận / lỗi nguồn / điểm mở / markup biên tập đều nằm trong **sổ phát hiện** ngoài luồng và đã báo User — KHÔNG trong thân nháp. - [ ] Đã nháp local + chờ User duyệt TRƯỚC khi đẩy FARE. -- [ ] Vị trí đẩy lên FARE: đã đọc `knowledge-tree`, đặt theo cách project tổ chức tài liệu tương tự + User chốt — KHÔNG mặc định folder nguồn, cũng không mặc định Module. -- [ ] Không doc nào set `approved`; không tự tạo module / folder. +- [ ] Vị trí đẩy lên FARE: đã đọc `knowledge-tree`, đặt theo cách project tổ chức tài liệu tương tự + User chốt — KHÔNG mặc định folder nguồn, cũng không mặc định gắn plan item. +- [ ] Không doc nào set `approved`; không tự tạo plan item / folder. diff --git a/.agent/skills/fare-effort-estimation/SKILL.md b/.agent/skills/fare-effort-estimation/SKILL.md index 54ded4d..6f4557e 100644 --- a/.agent/skills/fare-effort-estimation/SKILL.md +++ b/.agent/skills/fare-effort-estimation/SKILL.md @@ -43,7 +43,7 @@ Truyền field lệch cấp (vd `complexity` cho epic, hay `effort_est_level` ch | story `effort` | **Man-days** | Story | **Auto** — FARE tính từ FP_score qua `fare://effort-matrix`. KHÔNG set tay. | | epic `effort_est` | **Man-days** | Epic | **Dẫn xuất** từ `effort_est_level` (L1-L4). KHÔNG set trực tiếp. | | `task.est_effort` | **GIỜ** (decimal, 0.5 = 30 phút, 8 = 1 ngày công) | Task | Manual — PM hoặc Dev điền. | -| `task.actual_effort` | **GIỜ** | Task | Manual — Dev điền sau khi làm xong, đối chiếu est. | +| `task.actual_effort` | **GIỜ** | Task | Dev điền qua **worklog trên UI FARE** sau khi làm xong — KHÔNG set được qua MCP (`update_task` không có field này). | Nhầm man-days ↔ giờ trên cùng project = số liệu effort vô nghĩa. Mỗi lần truyền số → tự hỏi: "đây là task hay plan item?" diff --git a/.agent/skills/fare-impact-analysis/SKILL.md b/.agent/skills/fare-impact-analysis/SKILL.md index 8757596..54849df 100644 --- a/.agent/skills/fare-impact-analysis/SKILL.md +++ b/.agent/skills/fare-impact-analysis/SKILL.md @@ -106,7 +106,7 @@ Lý do: signature đổi → 3 caller d=1 phải sửa; 1 trên route `/api/logi ### Bước 6 — Cập nhật task -`add_comment(taskId, comment=)` — để mọi người (cả PM/QA) thấy mức rủi ro & phương án dev chọn: +`add_comment(projectCode, entityType="task", entityId=taskId, content=)` — để mọi người (cả PM/QA) thấy mức rủi ro & phương án dev chọn: ``` [Impact] validateUser — HIGH (3 d=1 callers, 2 flows). Phương án chốt: (1) backward-compatible overload — không break caller cũ. diff --git a/.agent/skills/fare-mcp-integration/SKILL.md b/.agent/skills/fare-mcp-integration/SKILL.md index 2bc800a..c8befcd 100644 --- a/.agent/skills/fare-mcp-integration/SKILL.md +++ b/.agent/skills/fare-mcp-integration/SKILL.md @@ -1,6 +1,6 @@ --- name: fare-mcp-integration -description: Dùng MCP của FARE đúng & an toàn — HỢP ĐỒNG tool canonical (40 tool server thật expose), mô hình plan-item theme/epic/story, các bẫy không hiển nhiên và pattern bắt buộc. Mọi skill khác trỏ về đây để lấy chữ ký tool. +description: Dùng MCP của FARE đúng & an toàn — HỢP ĐỒNG tool canonical (39 tool server thật expose), mô hình plan-item theme/epic/story, các bẫy không hiển nhiên và pattern bắt buộc. Mọi skill khác trỏ về đây để lấy chữ ký tool. --- # fare-mcp-integration — Hợp đồng MCP FARE @@ -13,16 +13,16 @@ description: Dùng MCP của FARE đúng & an toàn — HỢP ĐỒNG tool canon ## Nguồn canonical: đọc FARE, đừng học theo trí nhớ FARE tự mô tả chính nó — luôn đúng theo phiên bản hiện tại: - **Mô tả từng tool** — mỗi MCP tool tự kèm schema/tham số chi tiết. Đọc trước khi gọi. -- **Resource** (đọc trạng thái hệ thống): `fare://projects`, `fare://projects/{code}/knowledge-tree`, `fare://projects/{code}/plan-items`, `fare://documents/{id}`, `fare://documents/{id}/versions`, `fare://system-attributes`, `fare://effort-matrix`. +- **Resource** (đọc trạng thái hệ thống): `fare://projects`, `fare://projects/{code}/knowledge-tree`, `fare://projects/{code}/plan-items`, `fare://documents/{id}`, `fare://documents/{id}/versions`, `fare://system-attributes`, `fare://effort-matrix`. Hướng dẫn soạn tài liệu (đọc khi cần chi tiết, không nhồi vào schema tool): `fare://document-purposes` (catalogue preset `purpose`), `fare://doc-type-schemas` (JSON shape từng doc_type). - Bảng manifest dưới đây là **bản chụp để định hướng** — khi lệch với mô tả tool sống, tin mô tả sống và sửa file này. -## Manifest 40 tool (gom theo miền) +## Manifest 39 tool (gom theo miền) | Miền | Tool | Ghi chú nhanh | |---|---|---| | **Project** | `list_projects` | Bỏ `id` = liệt kê; có `id` = chi tiết 1 project (`include_members`, `include_task_statuses`). | | **Tài liệu (đọc/ghi)** | `list_documents`, `read_document`, `create_document`, `edit_document`, `update_document`, `delete_document` | `edit_document` = sửa NỘI DUNG (block ops hoặc `replace_all`). `update_document` = sửa METADATA/vị trí (title/status/purpose/move). `delete_document` = xóa mềm. | -| | `patch_document` | ⚠️ **DEPRECATED** → dùng `edit_document` (block ops y hệt). | +| | ~~`patch_document`~~ | ❌ **ĐÃ GỠ** khỏi MCP → dùng `edit_document` (block ops y hệt). | | | `create_suggestion` | Đề xuất sửa 1 block (`node_id`) — không ghi đè. | | **Folder** | `manage_folder` | `action: create\|update\|delete` — chỉ phân vùng Custom. `delete` cần `confirm=true`. | | **Diagram** | `read_diagram`, `edit_diagram` | doc_type=`diagram` (drawio). Per-cell, lossless. KHÔNG sửa diagram qua edit_document. | @@ -30,7 +30,7 @@ FARE tự mô tả chính nó — luôn đúng theo phiên bản hiện tại: | **Plan / Sprint** | `list_plans`, `upsert_plan` | `list_plans(id=..., include=["versions","commits"])` = chi tiết. `upsert_plan` tạo/sửa month plan. KHÔNG có `get_plan`. | | **Task** | `list_tasks`, `create_tasks`, `update_task`, `delete_task` | `create_tasks` luôn batch (mảng). `list_tasks(id=...)` = chi tiết 1 task. KHÔNG có `create_task` số ít. | | **Test case** | `list_test_cases`, `create_test_cases`, `update_test_case` | `create_test_cases` luôn batch. `list_test_cases(id=...)` = chi tiết 1 TC. Ghi verify qua `update_test_case(verify={...})`. KHÔNG có `get_test_case`/`create_test_case` số ít. | -| **Comment** | `add_comment`, `get_comments` | entityType ∈ `document\|task\|plan\|campaign`. | +| **Comment** | `add_comment`, `get_comments` | `add_comment(projectCode, entityType, entityId, content)` — entityType ∈ `document\|task\|plan\|campaign`; `entityId` = id thực thể; **`content` là HTML** (vd `

…

`), KHÔNG Markdown. KHÔNG có param `taskId`/`comment`. | | **RAG / tìm** | `search_rag` | Search NỘI DUNG đã index (`query` HOẶC `entity_name`). Không match tên doc/folder. | | **Code intelligence** | `code_repos`, `code_query`, `code_context`, `code_impact`, `code_route_map`, `code_read_file` | Chỉ project đã index repo. Nhiều repo/branch → `code_repos` trước. | | **Ảnh** | `read_image`, `upload_image` | | @@ -72,10 +72,10 @@ Function" hay "Epic initiative độc lập" của bản cũ. - `effort` và `effort_est` là **dẫn xuất** — không bao giờ truyền tay. ## Link nội bộ giữa tài liệu = chip mention (KHÔNG markdown link) -Trỏ từ nội dung richtext (thân tài liệu, `description` task…) sang tài liệu/folder khác: -- **Gọn (auto):** ghi **URI trần** `fare://documents/{id}` (hoặc `fare://folders/{id}`) → frontend tự đổi thành **chip bấm được** (nhãn placeholder `Document #{id}`). -- **Có nhãn đẹp:** ghi **chip HTML đầy đủ** — `{nhãn}` (folder → `data-doc-type="folder"`, `href="/docs?folder={id}"`). ⚠️ **Bắt buộc có `data-type="mention"`** — thiếu nó backend chèn thêm 1 chip resolve nữa → **bị nhân đôi**. -- ⚠️ **KHÔNG** dùng `[{nhãn}](fare://documents/{id})` (markdown link): thiếu `class="fare-mention"` → frontend bỏ qua, không bấm được. +Hành vi auto-chip **KHÁC nhau theo ngữ cảnh** (đã kiểm round-trip): +- **Trong `description` task / `add_comment`:** ghi **URI trần** `fare://documents/{id}` là đủ → backend auto-convert thành chip bấm được (mô tả tool `update_task`/`add_comment`: "auto-chip-converted"). +- **Trong THÂN tài liệu richtext (doc body):** URI trần **KHÔNG** tự thành chip — lưu xong vẫn là **text thuần** (đã kiểm doc 619). PHẢI ghi **chip HTML đầy đủ**: `{nhãn}` (folder → `data-doc-type="folder"`, `href="/docs?folder={id}"`). ⚠️ **Bắt buộc có `data-type="mention"`** — thiếu nó backend chèn thêm 1 chip resolve → **bị nhân đôi**. +- ⚠️ **KHÔNG** dùng `[{nhãn}](fare://documents/{id})` (markdown link): bị rút còn text trần, không bấm được (đã kiểm). ## Bug INTRINSIC ≠ EXTRINSIC (bug nội sinh vs ngoại lai) @@ -94,10 +94,10 @@ Bug (`type=BUG`) có `bug_origin` quyết định nó có chặn task khác hay ## Bẫy không hiển nhiên - **Param sai tên bị REJECT, không bị bỏ qua âm thầm.** Strict validation → key lạ = `-32602 Unrecognized key`. Vd dùng `search=` cho `list_tasks` sai (đúng là `q`). Gặp lỗi: đọc mô tả tool, KHÔNG đoán tên param từ tool khác. - **Optional param — KHÔNG truyền `null`.** Field không đổi → bỏ hẳn khỏi payload. Truyền `null` cho field số (`folder_id`, `plan_item_id`…) → lỗi `-32602`. -- **Sửa nội dung vs vị trí tài liệu:** `edit_document` cho NỘI DUNG (block ops rẻ token, hoặc `replace_all` ghi đè cả doc). `update_document` chỉ METADATA/move (`title`/`status`/`purpose`/`folder_id`/`scope`/`plan_item_id`). `patch_document` cũ đã DEPRECATED. +- **Sửa nội dung vs vị trí tài liệu:** `edit_document` cho NỘI DUNG (block ops rẻ token, hoặc `replace_all` ghi đè cả doc). `update_document` chỉ METADATA/move (`title`/`status`/`purpose`/`folder_id`/`scope`/`plan_item_id`). `patch_document` đã bị GỠ khỏi MCP. - **Folder & vị trí tài liệu:** `manage_folder` (create/update/delete, Custom only). `create_document` có `path` cũng mkdir -p (khớp chính xác `(tên, cha, scope)`, lệch → folder trùng; đã có → dùng `folder_id`). Folder chỉ tồn tại ở phân vùng Custom; Project & Module phẳng. - **`search_rag` chỉ search NỘI DUNG** đã index — không match tên doc/folder. Tra theo tên → `list_documents(query=...)`; duyệt cây → resource `knowledge-tree`. -- **`status`:** agent chỉ set `draft`/`review`. `approved`/`archived` là quyết định con người (rule §7). +- **`status`:** agent chỉ set `draft`/`in_review`. `approved`/`archived` là quyết định con người (rule §7). - **Phiên bản tài liệu:** `read_document(documentId)` = bản hiện tại; `read_document(documentId, version=n)` = version cụ thể; danh sách version = resource `fare://documents/{id}/versions`. KHÔNG tự chế `?version=`. - **Structured doc** (`user_story`/`api_doc`/`erd`/`glossary`/`test_case`): content là JSON đúng schema. Sửa → `read_document` lấy bản hiện tại → `edit_document(replace_all)` gửi lại FULL JSON. diff --git a/.agent/skills/fare-plan-breakdown/SKILL.md b/.agent/skills/fare-plan-breakdown/SKILL.md index d23c5f0..de608ef 100644 --- a/.agent/skills/fare-plan-breakdown/SKILL.md +++ b/.agent/skills/fare-plan-breakdown/SKILL.md @@ -23,6 +23,12 @@ Cây WBS trả lời "sản phẩm mang lại GIÁ TRỊ gì", KHÔNG phải "co - **Theme ≠ Initiative** (mục tiêu chiến lược nhiều quý — quá lớn) và **≠ module kỹ thuật** (nhầm trục). - **Task nằm NGOÀI 3 tầng** — task neo vào đúng 1 story (cha = story). Một story đẻ nhiều task ([BE]/[FE]/[QA]…). KHÔNG break task lúc lập plan (xem Quy trình). +## Đừng bê nguyên cách gom nhóm của TÀI LIỆU NGUỒN +Cấu trúc epic/chương/phần trong BRD/SRS/Excel nguồn thường là **góc trình bày / PM** (theo thứ tự soạn, theo phòng ban, theo màn hình) — KHÔNG phải cấu trúc domain gắn kết. Bê nguyên 9 "epic" của file nguồn ra 9 nhánh = mirror cấu trúc nguồn, phân tích hời hợt. +- ⚠️ **Bẫy:** nguồn cũng hay đặt tên theo "tính năng/value" → dễ tưởng đã đúng trục giá trị. Phép thử THẬT là **cohesion** (cùng trả lời một câu hỏi nghiệp vụ), KHÔNG phải "nghe giống value". +- **Re-derive theo cohesion:** 2 yêu cầu cùng trả lời MỘT câu hỏi nghiệp vụ → cùng một nhánh, **dù nằm khác chương nguồn**. (Vd thực tế: Suppression + Preference + Scoring + Hygiene rải 3 epic nguồn nhưng cùng là "sức khỏe danh sách" → gom về 1 epic.) +- **Chủ động soi chéo:** quét TOÀN BỘ yêu cầu, gom theo *danh từ domain* (đối tượng nhận / nội dung / chiến dịch / theo dõi / quản trị…), rồi đối chiếu với cách nguồn gom — chỗ lệch chính là nơi nguồn gom theo góc PM, cần cắt lại. + ## 3 cấp CỨNG — không vi phạm ``` theme (type="theme", không parent_id) @@ -99,6 +105,7 @@ Sai dải / sai cấp = lỗi. Đọc `fare://system-attributes` trước khi tr ## Anti-patterns - ❌ Tìm tool `add_module`/`update_module`/`list_modules` — đã bị gỡ. Dùng `add_plan_item`/`update_plan_item`/`list_plan_items`. - ❌ Chia cây theo **trục code** (module kỹ thuật/DDD) thay vì trục giá trị. +- ❌ **Mirror y nguyên cách gom nhóm (epic/chương) của tài liệu nguồn** — đó là góc PM/trình bày, không phải cohesion domain. Re-derive lại. - ❌ **Story là bước kỹ thuật** ("tạo bảng X", "gọi API Y") — đó là task của một story giá trị. - ❌ **Story gói nhiều giá trị** (tên có dấu "+" / liệt kê nhiều việc) — tách. - ❌ **Tên story mô tả cơ chế** ("quay Draft + báo người tạo") — đổi thành [động từ]+[đối tượng], đẩy chi tiết xuống nghiệm thu. @@ -112,6 +119,7 @@ Sai dải / sai cấp = lỗi. Đọc `fare://system-attributes` trước khi tr ## Tự kiểm - [ ] Đã `list_plan_items(projectCode)` trước khi tạo bất cứ thứ gì (§3). - [ ] Chia theo trục giá trị, không mirror module code. +- [ ] Khung nhánh derive theo cohesion domain, KHÔNG copy cách gom của tài liệu nguồn; đã soi FR cùng bản chất nằm rải khác chương. - [ ] Mọi Story là đơn vị nghiệm thu được (không phải task); gán được C/S/Cl. - [ ] Mọi Story có Epic cha hợp lệ, mọi Epic có Theme cha hợp lệ (đủ đúng 3 tầng). - [ ] Nhánh nông: tầng mỏng có tên nhóm giá trị/mảng năng lực THẬT (không tầng giả). diff --git a/.agent/skills/fare-plan-versioning/SKILL.md b/.agent/skills/fare-plan-versioning/SKILL.md index 86d71b1..3fc2b07 100644 --- a/.agent/skills/fare-plan-versioning/SKILL.md +++ b/.agent/skills/fare-plan-versioning/SKILL.md @@ -7,6 +7,10 @@ description: Hiểu & vận hành mô hình Plan của FARE — master plan vs m Dùng khi: PM cần tạo / cập nhật month plan cho sprint mới, hoặc cần hiểu plan/version trước khi `create_tasks` (vì task có thể gắn `plan_month_id`). +## Tiền đề +- Chữ ký tool (`list_plans`, `upsert_plan`) & cách gắn `plan_month_id`: xem `fare-mcp-integration` (nguồn chân lý duy nhất về tool). +- Mọi thao tác ghi (`upsert_plan`) tuân `rules/fare-rules.md` — §2 Confirmation Gate, §4 (chỉ truyền field thay đổi), §7 (publish là quyết định con người). + ## Mô hình Plan của FARE — đọc qua một lần để khỏi nhầm ``` diff --git a/.agent/skills/fare-self-verify/SKILL.md b/.agent/skills/fare-self-verify/SKILL.md index 3799ab7..399f40f 100644 --- a/.agent/skills/fare-self-verify/SKILL.md +++ b/.agent/skills/fare-self-verify/SKILL.md @@ -93,8 +93,8 @@ Câu hỏi cho QA: ### Bước 5 — Update lifecycle User OK → 2 gọi tuần tự: -1. `update_task(taskId, meta_status="VERIFYING", actual_effort=6)` (actual_effort là giờ — không nhầm man-days của module). -2. `add_comment(taskId, comment=)`. +1. `update_task(taskId, meta_status="VERIFYING")`. ⚠️ Giờ thực tế (`actual_effort`) ghi qua **worklog trên UI FARE** — `update_task` KHÔNG có field `actual_effort` (truyền vào → lỗi `-32602`). +2. `add_comment(projectCode, entityType="task", entityId=taskId, content=)`. KHÔNG gộp evidence vào field khác — comment là log chính của task lifecycle. @@ -126,7 +126,7 @@ Báo User: - ❌ Bỏ qua re-impact analysis khi impact ban đầu là HIGH — caller có thể break sau khi sửa. - ❌ Sửa scope nhiều mà không `add_comment` lý do — PM/QA không hiểu vì sao file đụng khác plan. - ❌ Quên cập nhật `api_doc` / `erd` khi đổi contract — phá hợp đồng cho FE / QA. -- ❌ 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. ## Tự kiểm @@ -136,7 +136,7 @@ Báo User: - [ ] Impact analysis re-check nếu ban đầu HIGH/CRITICAL — caller d=1 không break. - [ ] api_doc / erd cập nhật nếu contract đổi (hoặc bàn giao writer). - [ ] User chốt handoff TRƯỚC khi `update_task` + `add_comment` (§2). -- [ ] `actual_effort` là GIỜ (không nhầm man-days của module). +- [ ] KHÔNG truyền `actual_effort` vào `update_task` (tool không có field này — ghi qua worklog UI). - [ ] KHÔNG tự `DONE` (§6). - [ ] Đã check bug INTRINSIC open (`list_tasks(type="BUG", bug_origin="INTRINSIC", linked_task_id=)`) + TC `failed` — báo rõ nếu còn chặn DONE. - [ ] Bug phát hiện khi làm task này → INTRINSIC + link task này; bug ngoài scope → EXTRINSIC, không link. Cả hai đều qua §5 (hỏi User). diff --git a/.agent/skills/fare-spec-authoring/SKILL.md b/.agent/skills/fare-spec-authoring/SKILL.md index 1e46bf0..8f04c98 100644 --- a/.agent/skills/fare-spec-authoring/SKILL.md +++ b/.agent/skills/fare-spec-authoring/SKILL.md @@ -26,15 +26,16 @@ Không tự quyết loại — hỏi User. Cùng một tính năng có thể c > **Use-case:** mô hình hoá use-case (actor + luồng main/alternative/exception) → viết **`richtext`** (`srs` / `requirement`); cần sơ đồ trực quan → doc_type **`diagram`** (drawio). ## Quy trình -1. **Khám phá ngữ cảnh** (`fare-context-discovery`) — module / chức năng liên quan, tài liệu anh em, ERD. +1. **Khám phá ngữ cảnh** (`fare-context-discovery`) — plan item / chức năng liên quan, tài liệu anh em, ERD. 2. **Socratic Gate** (`§5`) — yêu cầu thường thiếu: actor phụ, edge case, ngưỡng/giới hạn, hậu điều kiện lỗi. Hỏi ≥2 câu, **CHỜ** User trả lời. KHÔNG tự suy ra (`§7`). 3. **Soạn nội dung** đúng schema/khuôn loại đã chọn — đọc `references/{loại}.md`. Mọi câu truy được về điều User cung cấp; chỗ thiếu → `⚠️` + hỏi, KHÔNG bịa actor / flow / acceptance criteria / business rule. -4. **Vị trí đẩy** — khảo sát resource `knowledge-tree` + `list_plan_items`; đề xuất vị trí + **CHỜ User chốt** (`§2`). KHÔNG mặc định. Lưu ý: `glossary` thường nằm ở `scope="project"` (1 doc / project); `brd` thường ở `scope="project"`; `srs` / `user_story` thường gắn `plan_item_id` cấp Function (rule §1). -5. **Tạo** — `create_document(doc_type=..., purpose=..., content=..., status="draft")`: +4. **Vị trí đẩy** — khảo sát resource `knowledge-tree` + `list_plan_items`; đề xuất vị trí + **CHỜ User chốt** (`§2`). KHÔNG mặc định. Lưu ý: `glossary` thường nằm ở `scope="project"` (1 doc / project); `brd` thường ở `scope="project"`; `srs` / `user_story` thường gắn `plan_item_id` cấp story (rule §1). +5. **Tạo** — `create_document(doc_type=..., purpose=..., content=..., title=...)` — doc mới **mặc định `status=draft`**; `create_document` KHÔNG nhận param `status` (truyền vào → lỗi `-32602`): - Structured (`user_story`, `glossary`) → content là JSON; KHÔNG truyền `purpose` / `content_format` (FARE tự set). - - Richtext (`brd` / `srs` / `prd`) → để `content` TRỐNG cho FARE inject template hệ thống; sau đó `edit_document` điền từng block. + - **`srs` theo chức năng** (case thường gặp, gắn story) → **tự viết `content` Markdown** theo format use-case + **truyền `title` có nghĩa**. KHÔNG để trống (template hệ thống sẽ ghi đè title thành "SRS" + sai format). Khuôn: `references/requirement.md` (ô ⚠️ đầu file) → `../fare-doc-normalize/references/use-case-spec.md`. + - `brd` / `prd` (hoặc `srs` cấp hệ thống) → có thể để `content` TRỐNG cho FARE inject template, **rồi `update_document(title=...)` đặt lại tên** (template ghi đè title) + `edit_document` điền từng block. - Richtext khác (`requirement` / `analysis` / `meeting-notes`) → tự viết Markdown theo khuôn trong `references/requirement.md`. - Trả URI `fare://documents/{id}` cho User. + Báo cho User: **tiêu đề + breadcrumb vị trí** (`Project {code} › Module: {tên plan item} ({code}) | Project Documents | Custom › {folder}` › tiêu đề) + URI `fare://documents/{id}` — để User định vị được trên UI, KHÔNG trả id trần (rule §4). 6. **Gợi ý xếp chỗ trong cây plan item (nếu spec trải nhiều story/epic)** — sau khi spec đã đẩy: nếu là BRD/SRS/PRD mô tả một mảng giá trị lớn trải nhiều story, agent **đề xuất** với User: "Spec này trải nhiều tính năng — muốn dựng/hoàn thiện nhánh `theme › epic › story` để gắn spec & task đúng chỗ không?" → bàn giao BA `/fare-plan` (`fare-plan-breakdown`). KHÔNG tự dựng cây ở đây. Bỏ qua nếu spec chỉ cấp 1 story đơn lẻ (đã có chỗ gắn `plan_item_id`). ## Tự kiểm @@ -42,5 +43,6 @@ Không tự quyết loại — hỏi User. Cùng một tính năng có thể c - [ ] Mọi nội dung truy được về yêu cầu User cung cấp — không bịa actor / flow / AC / business rule / story point / glossary term. - [ ] Điểm thiếu / mơ hồ đã `⚠️` + hỏi User, không tự điền. - [ ] Với `glossary`: đã kiểm tra project chưa có doc nào trùng (1 doc / project). -- [ ] Với `brd`/`srs`/`prd`: đã dùng template hệ thống (content trống khi create) thay vì gõ tay từ đầu. -- [ ] `status="draft"` — KHÔNG `approved`. Vị trí đã được User chốt (không mặc định). +- [ ] Với `srs` theo chức năng: viết content use-case trực tiếp + `title` có nghĩa (KHÔNG để trống → mất title + sai format). Với `brd`/`prd`/`srs` cấp hệ thống dùng template: đã `update_document` đặt lại title sau khi tạo. +- [ ] `title` mọi doc có nghĩa & định vị được — KHÔNG để tên mặc định "SRS"/"BRD"/"PRD" (rule §4). +- [ ] Doc ở `draft` (mặc định — KHÔNG truyền `status` lúc create). Gửi soát thì `update_document(status="in_review")`; KHÔNG tự `approved`. Vị trí đã được User chốt (không mặc định). diff --git a/.agent/skills/fare-spec-authoring/references/glossary.md b/.agent/skills/fare-spec-authoring/references/glossary.md index 035ccab..5b481b3 100644 --- a/.agent/skills/fare-spec-authoring/references/glossary.md +++ b/.agent/skills/fare-spec-authoring/references/glossary.md @@ -22,7 +22,7 @@ Sổ thuật ngữ domain — định nghĩa các từ vựng nghiệp vụ proj ## Quy tắc -- **Mỗi project 1 doc.** Trước khi `create_document` → `list_documents(query="glossary", kind="glossary")` kiểm tra. Đã có → `read_document` lấy JSON, bổ sung term mới, `update_document` gửi lại FULL JSON (KHÔNG patch — structured doc không có patch block). +- **Mỗi project 1 doc.** Trước khi `create_document` → `list_documents(kind="glossary")` kiểm tra (lọc theo `kind`, KHÔNG kèm `query` — `query` lọc theo *tiêu đề*, sẽ trượt nếu glossary đặt tên tiếng Việt). Đã có → `read_document` lấy JSON, bổ sung term mới, `update_document` gửi lại FULL JSON (KHÔNG patch — structured doc không có patch block). - **`term`** — danh từ chính xác như nghiệp vụ dùng. Ưu tiên tiếng Việt; tiếng Anh chỉ giữ khi nguồn dùng đúng từ đó (vd "Campaign", "Backlog", "OKR"). - **`definition`** — 1 câu (≤ 25 từ) súc tích, theo nghĩa domain CỦA PROJECT NÀY, không phải nghĩa chung của từ điển. Có ví dụ ngắn càng tốt. - **`tags`** — phân loại: `process | role | data | metric | technical`... Dùng nhất quán; tag mới → bàn với User trước khi thêm. @@ -30,7 +30,7 @@ Sổ thuật ngữ domain — định nghĩa các từ vựng nghiệp vụ proj - **Không trùng lặp:** trước khi thêm term mới, scan glossary hiện có (case-insensitive) — biến thể hoa/thường, có/không dấu coi như trùng. - **Đồng nghĩa / từ viết tắt** — KHÔNG tạo entry riêng. Thêm vào `definition` dạng "Còn gọi: ...; viết tắt: ...". - **Trung thực §7:** chỉ thêm term có trong nguồn (BRD / SRS / use case / user phỏng vấn). KHÔNG bịa thuật ngữ project chưa dùng đến. -- Cập nhật `status="draft"`. KHÔNG `approved`. +- Doc mặc định `draft` (create KHÔNG nhận param `status`). KHÔNG `approved`. ## Khi nào thêm term mới (heuristic) - Soạn / soát một spec mới → quét danh từ chuyên biệt → đối chiếu glossary → term chưa có → đề xuất bổ sung. diff --git a/.agent/skills/fare-spec-authoring/references/requirement.md b/.agent/skills/fare-spec-authoring/references/requirement.md index e4f3ba2..287168d 100644 --- a/.agent/skills/fare-spec-authoring/references/requirement.md +++ b/.agent/skills/fare-spec-authoring/references/requirement.md @@ -4,14 +4,39 @@ `create_document(doc_type="richtext", purpose=, content=)` — `content_format` FARE tự set `tiptap`. -> Mẹo: với `purpose ∈ {srs, brd, prd}` FARE có **template hệ thống**. Tạo doc với `content` bỏ trống → FARE tự inject khuôn chuẩn (ISO 29148 / BABOK v3 / Cagan). Sau đó dùng `edit_document` điền nội dung từng block. Tránh việc tự gõ lại template. +> ## ⚠️ SRS theo chức năng (case hay gặp NHẤT) → viết content trực tiếp, ĐỪNG để trống +> +> Đặc tả SRS cho **một chức năng/màn hình cụ thể** (gắn `plan_item_id` cấp story) — team viết theo **format use-case** (Tổng quan / Luồng chính / Hậu điều kiện / Quy tắc nghiệp vụ). Khuôn đầy đủ: **`../../fare-doc-normalize/references/use-case-spec.md`** (cùng khuôn normalize dùng — viết mới & làm sạch ra cùng một dạng). Với case này: +> - **TỰ viết `content` Markdown** theo khuôn use-case-spec + **truyền `title` có nghĩa** ("SRS - {Tên chức năng}"). KHÔNG để `content` trống. +> - **TUYỆT ĐỐI KHÔNG** dùng template hệ thống cho case này: template `srs` là khung ISO 29148 cấp hệ thống (generic, NFR ISO 25010…) — KHÁC format use-case của team, và **ghi đè `title` thành "SRS"** (lấy H1 template) → doc trùng tên, không định vị được trên UI (rule §4). +> +> Mẫu use-case rút gọn (chi tiết + quy tắc trình bày: xem `use-case-spec.md`): +> ```markdown +> # {số} {Tên chức năng} +> +> ## Tổng quan +> - **Mô tả:** … · **Tác nhân:** … · **Tiền điều kiện:** … +> +> ## Luồng chính +> **Bước 1:** … +> +> **Bước 2:** … ← mỗi "Bước N" là MỘT đoạn, cách nhau dòng trống +> +> ## Hậu điều kiện +> … +> +> ## Quy tắc nghiệp vụ +> - … +> ``` + +> Mẹo (chỉ cho SRS/BRD/PRD **cấp hệ thống/dự án**, KHÔNG cho SRS-theo-chức-năng ở trên): FARE có **template hệ thống** (ISO 29148 / BABOK v3 / Cagan). Tạo doc với `content` bỏ trống → FARE inject khuôn chuẩn, rồi `edit_document` điền từng block. **Lưu ý:** template ghi đè `title` thành tên mặc định ("SRS"/"BRD"/"PRD") — sau khi tạo phải `update_document(title=...)` đặt lại tên có nghĩa, kẻo không định vị được trên UI (rule §4). ## Chọn purpose — KHÔNG dùng chung | purpose | Audience chính | Khi nào | Có template hệ thống? | |---|---|---|---| | `brd` | Sponsor / stakeholder kinh doanh | Business need ở cấp khởi tạo dự án — "vấn đề gì, vì sao làm, đo bằng KPI nào" (theo IIBA BABOK v3) | ✅ Có | -| `srs` | Engineering team | Yêu cầu phần mềm chi tiết, testable, gồm NFR theo ISO 25010 (theo ISO/IEC/IEEE 29148:2018) | ✅ Có | +| `srs` | Engineering team | **Theo chức năng** (gắn story) → format use-case, tự viết content (xem ô ⚠️ trên). **Cấp hệ thống** → khung ISO 29148, NFR ISO 25010 | ✅ Có (chỉ cấp hệ thống) | | `prd` | Product / Eng / Design / GTM | Yêu cầu sản phẩm theo style Cagan/SVPG — outcome + metric + scope MoSCoW | ✅ Có | | `requirement` | Mọi vai | **Fallback** khi chưa rõ là BRD/SRS/PRD, hoặc yêu cầu nhẹ. Khi nội dung trưởng thành → đổi `purpose` cho đúng audience | ❌ Không | | `analysis` | BA / kiến trúc | Nghiên cứu / so sánh phương án (CHƯA phải decision) — khác `adr` | ❌ Không | @@ -19,11 +44,13 @@ KHÔNG tự quyết — hỏi User chọn 1 trong các purpose ở trên (Socratic Gate §5). -## Quy trình ưu tiên (khi có template hệ thống) +## Quy trình ưu tiên — template hệ thống (CHỈ cho BRD/PRD, hoặc SRS cấp hệ thống) +> KHÔNG dùng cho SRS-theo-chức-năng — case đó viết content use-case trực tiếp (ô ⚠️ ở đầu file). 1. `create_document(doc_type="richtext", purpose="")` — bỏ `content` để FARE inject template. -2. `read_document(id)` — đọc lại các block (dùng `mode="blocks"` để có ID ổn định). -3. `edit_document(id, ops=[...])` — điền từng block (replace text trong placeholder `<...>`). -4. Mục nào yêu cầu không có → **xóa hẳn block** đó. KHÔNG để lại "N/A" hay placeholder trống. +2. `update_document(id, title="...")` — **đặt lại title** (template đã ghi đè thành "SRS"/"BRD"/"PRD"; tên mặc định = không định vị được trên UI, rule §4). +3. `read_document(id, mode="blocks")` — đọc lại các block (có ID ổn định). +4. `edit_document(id, ops=[...])` — điền từng block (replace text trong placeholder `<...>`). +5. Mục nào yêu cầu không có → **xóa hẳn block** đó. KHÔNG để lại "N/A" hay placeholder trống. ## Khi không có template (`requirement` / `analysis` / `meeting-notes`) @@ -31,7 +58,7 @@ Phải tự cung cấp `content` Markdown. Khuôn rút gọn tham khảo dưới ### `purpose=requirement` — Yêu cầu chung (fallback) ```markdown -# {Tên tính năng / module} +# {Tên tính năng / phân hệ} ## 1. Mục tiêu nghiệp vụ Vấn đề kinh doanh đang giải quyết + kết quả kỳ vọng (đo được). @@ -61,7 +88,7 @@ Vấn đề kinh doanh đang giải quyết + kết quả kỳ vọng (đo đư - **Khả dụng:** {uptime / RTO / RPO} ## 7. Phụ thuộc & Tài liệu liên quan -- `fare://documents/{id}` — {tên doc}, vai trò. *(URI trần tự thành chip mention bấm được; muốn nhãn riêng → chip HTML `…` — phải đủ `data-type="mention"` kẻo bị nhân đôi; xem `fare-mcp-integration`. KHÔNG markdown link.)* +- {tên doc}, vai trò → **chip HTML đầy đủ**: `{tên doc}`. *(Đây là THÂN tài liệu → URI trần `fare://documents/{id}` KHÔNG tự thành chip, chỉ là text thuần; phải đủ `data-type="mention"` kẻo bị nhân đôi; xem `fare-mcp-integration`. KHÔNG markdown link.)* ## 8. Vấn đề mở - ⚠️ {câu hỏi chờ stakeholder trả lời} @@ -123,5 +150,5 @@ Nêu phương án đề xuất + lý do. ⚠️ Đây CHƯA phải decision — - **MoSCoW** enum cho ưu tiên: `Must | Should | Could | Won't`. - **Mục không có nội dung** → BỎ HẲN heading. KHÔNG "N/A". - **Vấn đề mở (Open Questions)** — bắt buộc nếu Socratic Gate còn chưa được trả lời. Đừng xóa khi chưa giải quyết. -- **`status`:** `draft` khi viết xong; `in_review` khi gửi soát (FARE enum `draft | in_review | approved | outdated | archived` — agent chỉ set `draft` / `in_review`, KHÔNG `approved`). +- **`status`:** doc mới **mặc định `draft`** (`create_document` KHÔNG nhận param `status`). Gửi soát → `update_document(status="in_review")`. Enum agent set được qua `update_document` chỉ `draft | in_review`; `approved` / `archived` là việc của con người (UI), agent KHÔNG set. - Trung thực §7: yêu cầu nguồn không nêu → ⚠️ + hỏi User, KHÔNG bịa. diff --git a/.agent/skills/fare-task-breakdown/SKILL.md b/.agent/skills/fare-task-breakdown/SKILL.md index 483cf48..ffa6dd8 100644 --- a/.agent/skills/fare-task-breakdown/SKILL.md +++ b/.agent/skills/fare-task-breakdown/SKILL.md @@ -87,15 +87,15 @@ Khai báo qua `links: [{ target_task_id, link_type: "blocks" }]` — NHƯNG `tar ### Nguyên tắc - `task.est_effort` đơn vị **GIỜ** (decimal: 0.5 = 30 phút, 8 = 1 ngày công). KHÁC `story.effort` (plan item) đơn vị MAN-DAYS. -- **Bottom-up:** ước MỖI task từ đặc điểm task đó (lượng code thật, validate, integration, test). KHÔNG chia story effort theo tỷ trọng layer (sai phương pháp — story.effort_est là *judgment cấp cao*, không phản ánh task chi tiết). -- **Story.effort_est là CEILING SANITY-CHECK** (Bước 3.3), KHÔNG phải input để chia. +- **Bottom-up:** ước MỖI task từ đặc điểm task đó (lượng code thật, validate, integration, test). KHÔNG chia story effort theo tỷ trọng layer (sai phương pháp — story.effort là *judgment cấp cao* suy từ matrix complexity/scope/clarity, không phản ánh task chi tiết). +- **Story.effort là CEILING SANITY-CHECK** (Bước 3.3), KHÔNG phải input để chia. (Lưu ý: story dùng `effort` matrix-derived; `effort_est` là của EPIC — story luôn null.) - User là người chốt số cuối — agent đề xuất *khoảng* dựa heuristic, KHÔNG gán cứng. ### 3.0 — Lấy 3 mẩu data ngữ cảnh từ FARE (đọc TRƯỚC khi nháp) | Cần | Resource | Dùng làm gì | |---|---|---| -| `hours_per_day` của project | `fare://projects/{code}` → field `hours_per_day` | Quy đổi `story.effort_est` (man-days) → giờ ở Bước 3.3 | +| `hours_per_day` của project | `fare://projects/{code}` → field `hours_per_day` | Quy đổi `story.effort` (man-days) → giờ ở Bước 3.3 | | Task hiện có trong story này | `fare://plan-items/{story_id}/task-effort-summary` → `total.sum_est_hours` + `total.count` | Biết story đã có bao nhiêu task + effort đang chiếm → chỉ ước phần *còn lại*, không double-count | | Velocity team (auto-calibrate factor) | `fare://projects/{code}/velocity` → `window_90d.median` (ưu tiên) hoặc `window_30d.median` (current) | Hiệu chỉnh factor heuristic theo lịch sử team: nếu median > 1.0 → team thường ước thấp → nhân `est_effort` thêm factor `velocity_median` | @@ -175,16 +175,16 @@ User có thể chỉnh thủ công bất kỳ task nào — nếu chỉnh > 2× ### 3.3 — Ceiling check (sau khi mỗi task có est) -Sum `task.est_effort` (mọi task vừa nháp) **cộng với task đã có** từ Bước 3.0 (`task-effort-summary.total.sum_est_hours`) → đối chiếu với `story.effort_est` quy hours. +Sum `task.est_effort` (mọi task vừa nháp) **cộng với task đã có** từ Bước 3.0 (`task-effort-summary.total.sum_est_hours`) → đối chiếu với `story.effort` quy hours. **Quy đổi man-days → hours:** - `hours_per_day` đã đọc ở Bước 3.0 từ `fare://projects/{code}`. Default 8 nếu null. **Tính ratio:** ``` -ratio = (sum_new_task_est + summary.total.sum_est_hours) / (story.effort_est × hours_per_day) +ratio = (sum_new_task_est + summary.total.sum_est_hours) / (story.effort × hours_per_day) ``` -Nếu `story.effort_est = 0` (chưa estimate) → bỏ ceiling check, báo PM chạy `fare-effort-estimation` ngược sau breakdown (input sum tasks làm sanity). +Nếu `story.effort = 0` (story chưa gán complexity/scope/clarity) → bỏ ceiling check, báo PM chạy `fare-effort-estimation` ngược sau breakdown (input sum tasks làm sanity). **Thang mức vượt → số phương án đề xuất:** @@ -193,14 +193,14 @@ Nếu `story.effort_est = 0` (chưa estimate) → bỏ ceiling check, báo PM ch | **< 0.8** | 🟩 Dư buffer | (a) Chấp nhận, giữ buffer · (b) Thêm 1 task buffer (refactor / doc / monitoring) tận dụng capacity sprint | | **0.8 – 1.1** | 🟩 Khớp tốt | Báo OK, không cần đề xuất gì. | | **1.1 – 1.25** | 🟨 Vượt nhẹ | (a) Chấp nhận overrun + note lý do · (b) Trim scope nhẹ 1 task không critical | -| **1.25 – 1.5** | 🟧 Vượt trung | + (c) Re-estimate story effort_est (BA/PM `/fare-pm`) · (d) Defer 1 task qua sprint sau | +| **1.25 – 1.5** | 🟧 Vượt trung | + (c) Re-estimate story effort qua chỉnh complexity/scope/clarity (`fare-effort-estimation`, route `/fare-pm`) · (d) Defer 1 task qua sprint sau | | **1.5 – 2.0** | 🟥 Vượt nhiều | + (e) Chia thêm task để parallel (gán nhiều assignee) · (f) Split story thành 2 (BA reassess scope qua `/fare-change`) | | **> 2.0** | 🟥🟥 NGHIÊM TRỌNG | Cảnh báo: spec / scope có vấn đề. DỪNG breakdown. Bàn giao BA `/fare-change` re-spec hoặc `/fare-audit-spec`; PM `/fare-pm` re-plan toàn story. KHÔNG batch task. | **Mẫu báo cáo cho tier > 0.8 ceiling:** ``` ## Ceiling check -Story "Thêm nhân viên" (id=120): effort_est = 5 md × hours_per_day=8 = 40h +Story "Thêm nhân viên" (id=120): effort = 5 md × hours_per_day=8 = 40h Task hiện có trong story (từ task-effort-summary): 2 task, sum_est = 8h Sum task mới (5 task): 44h Tổng sau breakdown: 52h @@ -209,17 +209,17 @@ Ratio: 52 / 40 = 1.30 → 🟧 Vượt trung (25–50%) Phương án đề xuất: (a) Chấp nhận overrun 12h, note "validate phức tạp hơn ước ban đầu" vào description. (b) Trim TASK-5 [Infra] (4h, không critical sprint này) → còn 48h, ratio 1.20. -(c) Re-estimate story effort_est từ 5 md lên 7 md (BA/PM /fare-pm). +(c) Re-estimate story effort từ 5 md lên 7 md (chỉnh complexity/scope/clarity qua fare-effort-estimation, route /fare-pm). (d) Defer TASK-5 qua sprint sau. Đánh giá theo tình hình: Validate phức tạp là phát hiện chính đáng khi đọc spec sâu. (c) hợp lý nhất — -ước ban đầu quá lạc quan, sửa effort_est sẽ giúp velocity team chính xác hơn về sau. +ước ban đầu quá lạc quan, sửa effort story (qua attributes) sẽ giúp velocity team chính xác hơn về sau. (b) nguy hiểm vì infra cuối cùng cũng phải làm. (a)/(d) chỉ giấu vấn đề. Đề xuất chính: (c). User chốt? ``` -**Khi story CHƯA có `effort_est`** (BA-light không estimate): bỏ ceiling check, vẫn bottom-up từng task. Báo PM: sau breakdown có thể chạy `fare-effort-estimation` ngược (input sum_task_est làm sanity-check cho story). +**Khi story CHƯA có `effort`** (BA-light không estimate / chưa gán complexity·scope·clarity): bỏ ceiling check, vẫn bottom-up từng task. Báo PM: sau breakdown có thể chạy `fare-effort-estimation` ngược (input sum_task_est làm sanity-check cho story). ### 3.5 — Sau khi User chốt batch task @@ -258,9 +258,9 @@ Sau khi batch trả về với id của từng task → gọi `update_task(add_l ## Bước 5 — Báo cáo & bàn giao Báo gọn: -- Đã tạo N task — liệt kê id + title + URL. +- Đã tạo N task — trình bảng **mã task (vd FC-188) + title + vị trí** (`Module: {tên story} ({code story})`), KHÔNG liệt kê id trần (rule §4 — User tra mã task trên UI). - Task nào chưa có spec đầy đủ → đánh dấu cần BA bổ sung. -- Task type=TEST → bàn giao QA (khi vai QA có) viết TC chi tiết. +- Task type=TEST → bàn giao QA `/fare-test` viết TC chi tiết. - Task BE/FE → sẵn cho Dev pickup. Trạng thái mặc định `TODO`. KHÔNG tự assign owner trừ khi User chỉ định rõ — assignee thường do team tự pickup. @@ -273,8 +273,8 @@ KHÔNG tự assign owner trừ khi User chỉ định rõ — assignee thường - ❌ Description không URI doc — dev không biết tham chiếu spec nào. - ❌ Tạo task từng cái trong vòng lặp — phải `create_tasks` batch một lần (§4). - ❌ Tự set `meta_status="DONE"` ngay khi tạo — task mới luôn TODO (§6). -- ❌ Truyền nhầm `est_effort` man-days vào task (task là GIỜ, module là MAN-DAYS). -- ❌ **Chia `story.effort_est` theo tỷ trọng layer** rồi gán xuống task (top-down). Phải bottom-up từng task theo bản chất task; story effort chỉ là ceiling sanity-check. +- ❌ Truyền nhầm `est_effort` man-days vào task (task là GIỜ, story là MAN-DAYS). +- ❌ **Chia `story.effort` theo tỷ trọng layer** rồi gán xuống task (top-down). Phải bottom-up từng task theo bản chất task; story effort chỉ là ceiling sanity-check. - ❌ Gán `est_effort` cứng từ bảng base mà KHÔNG nhân factor AI level × Dev level. - ❌ Ép sum tasks khớp ceiling (giảm task effort xuống chỉ để khớp story effort) — giấu vấn đề, sẽ overrun thật trong sprint. - ❌ Bỏ qua ceiling check (>0.8 ratio) — không báo User để chốt phương án xử lý. diff --git a/.agent/skills/fare-task-pickup/SKILL.md b/.agent/skills/fare-task-pickup/SKILL.md index fd275ad..3cf0e3b 100644 --- a/.agent/skills/fare-task-pickup/SKILL.md +++ b/.agent/skills/fare-task-pickup/SKILL.md @@ -23,7 +23,7 @@ Hỏi & CHỜ (nếu chưa rõ): ## Bước 1 — Lấy danh sách & xếp ưu tiên -`list_tasks(projectCode, meta_status="TODO", plan_month_id?, type="TASK")`: +`list_tasks(projectCode, status="TODO", plan_month_id?, type="TASK")`: - KHÔNG mặc định filter `assignee_id` — backlog có thể có task chưa assign mà dev pickup được. Xếp danh sách theo heuristic (trừ khi User chỉ đích danh): @@ -89,7 +89,7 @@ Cây WBS: Theme "Quản lý nhân viên" → Epic "Hồ sơ nhân viên" → Sto User đồng ý → `update_task(taskId, meta_status="IN_PROGRESS", assignee_id= nếu chưa assign)`. -Ngay sau đó `add_comment(taskId, comment=)`: +Ngay sau đó `add_comment(projectCode, entityType="task", entityId=taskId, content=)`: ``` [Pickup] Đang chuẩn bị làm phạm vi: - Tạo POST /employees endpoint diff --git a/.agent/skills/fare-tech-doc-authoring/SKILL.md b/.agent/skills/fare-tech-doc-authoring/SKILL.md new file mode 100644 index 0000000..ba6fcd8 --- /dev/null +++ b/.agent/skills/fare-tech-doc-authoring/SKILL.md @@ -0,0 +1,44 @@ +--- +name: fare-tech-doc-authoring +description: Viết MỚI tài liệu kỹ thuật structured trên FARE — API doc, ERD (và diagram) — đúng JSON schema. Dùng khi technical-writer cần tạo các loại doc này từ ngữ cảnh kỹ thuật, KHÔNG phải richtext văn xuôi. +--- + +# fare-tech-doc-authoring — Viết tài liệu kỹ thuật structured + +Dùng khi: cần **viết mới** một tài liệu kỹ thuật dạng cấu trúc trên FARE — `api_doc`, `erd`, `diagram`. +(Richtext kỹ thuật — `specification` / `guide` / `adr` / `runbook` — viết Markdown thẳng, không cần khuôn JSON; xem mô tả `purpose` của `create_document`.) + +## Tiền đề +- Đã có **Bản đồ ngữ cảnh** (`fare-context-discovery`) — KHÔNG viết biệt lập. +- Tuân `rules/fare-rules.md`: §1 (gắn `plan_item_id` story), §7 Content Fidelity (không bịa endpoint / bảng / cột), §2 Confirmation Gate (chốt vị trí đẩy). + +## Chọn loại & khuôn +| doc_type | Khi nào | Khuôn | content_format | +|---|---|---|---| +| `api_doc` | Hợp đồng REST API — group › endpoint › method/path/params/body/response | `references/api-doc.md` | FARE tự set `json` | +| `erd` | Mô hình dữ liệu — entity + field + quan hệ (SQL/NoSQL) | `references/erd.md` | FARE tự set `json` | +| `diagram` | Sơ đồ trực quan (use-case, sequence, flow, kiến trúc) | `references/diagram.md` | `drawio` (mặc định) | + +> **Structured = JSON, KHÔNG Markdown.** `api_doc` / `erd` bắt buộc truyền `content` là JSON hợp lệ đúng schema (rule §4). Gửi Markdown cho structured = sai. + +## Quy trình (SOP) +1. **Khám phá ngữ cảnh** (`fare-context-discovery`) — story liên quan, ERD/api anh em, tài liệu nguồn. `search_rag` / `list_documents` kiểm tra doc trùng / liên quan. +2. **Soạn JSON** đúng `references/{loại}.md`. Mọi entity/field/endpoint truy được về nguồn User cung cấp hoặc tài liệu đã có; chỗ thiếu → hỏi User, KHÔNG bịa (§7). +3. **Chốt vị trí đẩy** (§2) — `api_doc` / `erd` đặc tả 1 chức năng → gắn `plan_item_id` story (§1); model dữ liệu cấp dự án → `scope="project"`. Đề xuất + **CHỜ User chốt**. +4. **Tạo** — `create_document(doc_type=..., content=, title=..., plan_item_id=...)`. Doc mới **mặc định `draft`** — `create_document` KHÔNG nhận param `status` (truyền vào → lỗi `-32602`). KHÔNG truyền `purpose` / `content_format` cho structured (FARE tự set). + - **Diagram:** theo `references/diagram.md` — `create_document(doc_type="diagram", content=)` rồi vẽ qua **`edit_diagram`** (per-cell, lossless). KHÔNG resend XML qua `update_document`/`edit_document`; KHÔNG gửi Mermaid. +5. **Báo cáo** — **tiêu đề + breadcrumb vị trí + URI** (rule §4 — định vị được trên UI), KHÔNG id/URI trần. + +## Sửa sau khi tạo +- `api_doc` / `erd` (structured) → `edit_document(ops=[{op:"replace_all", content:}])`. Structured KHÔNG có block op / patch — luôn gửi FULL JSON. +- `diagram` → `edit_diagram` (KHÔNG `edit_document`). +- Đổi metadata / move / status → `update_document` (status agent set được chỉ `draft|in_review`; `approved` là việc của người). + +## Tự kiểm +- [ ] `content` là JSON hợp lệ đúng `references/{loại}.md` — đủ field bắt buộc, enum đúng (method / type / relation). +- [ ] Mọi endpoint / entity / field / quan hệ truy được về nguồn — KHÔNG bịa. +- [ ] `uid` (api_doc) / `id` (erd) nhất quán nội bộ: `relations.source/target` trỏ đúng `entities.id`; `sourceField/targetField` trỏ đúng `fields.id`. +- [ ] (erd) mỗi entity có `position: {x,y}` **giãn toạ độ** — KHÔNG để trống (mọi entity sẽ đè tại `{0,0}`). +- [ ] Đã gắn `plan_item_id` story (hoặc `scope="project"` nếu model cấp dự án) — User đã chốt vị trí. +- [ ] KHÔNG truyền `status` lúc create (doc mặc định `draft`); KHÔNG `approved`. +- [ ] Báo User tiêu đề + breadcrumb (rule §4), không id trần. diff --git a/.agent/skills/fare-tech-doc-authoring/references/api-doc.md b/.agent/skills/fare-tech-doc-authoring/references/api-doc.md new file mode 100644 index 0000000..9f08d14 --- /dev/null +++ b/.agent/skills/fare-tech-doc-authoring/references/api-doc.md @@ -0,0 +1,51 @@ +# Khuôn: doc_type = api_doc + +Đặc tả hợp đồng REST API — nhóm endpoint, từng endpoint kèm method/path/params/body/response. +`create_document(doc_type="api_doc", content=)` — `content_format` FARE tự set `json`. KHÔNG truyền `purpose`. + +> Schema lấy từ mô tả tool `create_document` (nguồn canonical) — nếu FARE đổi, tra lại ở đó. + +## Schema +```json +{ + "groups": [ + { + "uid": "grp-xxx", + "name": "Quản lý nhân viên", + "description": "Các endpoint CRUD nhân viên", + "endpoints": [ + { + "uid": "ep-xxx", + "method": "POST", + "path": "/api/v1/employees", + "name": "Thêm mới nhân viên", + "description": "Tạo một bản ghi nhân viên mới", + "headers": [{ "key": "Authorization", "value": "Bearer {token}" }], + "query_params": [{ "key": "lang", "type": "string", "required": false }], + "body_type": "json", + "body_content": "{ \"full_name\": \"string\", \"email\": \"string\" }", + "responses": [ + { "status": 201, "description": "Tạo thành công", "body": "{ \"id\": 1 }" }, + { "status": 422, "description": "Dữ liệu không hợp lệ", "body": "{ \"errors\": [] }" } + ] + } + ] + } + ] +} +``` + +## Quy tắc +- **`method`** enum: `GET | POST | PUT | PATCH | DELETE`. Đúng động từ HTTP theo nghiệp vụ (đọc → GET, tạo → POST, thay toàn phần → PUT, vá một phần → PATCH, xóa → DELETE). +- **`path`** — đường dẫn thật, có version + tham số path (`/api/v1/employees/{id}`). KHÔNG để path giả định nếu nguồn chưa nêu → hỏi User (§7). +- **`body_type`** enum: `json | form-data | raw | none`. `none` cho GET/DELETE không body. `body_content` là string mẫu (JSON để dạng string escape như ví dụ). +- **`query_params[].required`** — boolean. `type` ghi kiểu dữ liệu (`string` / `integer` / `boolean` / `date`...). +- **`responses[]`** — tối thiểu liệt kê mã thành công + các mã lỗi nghiệp vụ quan trọng (`422` validate, `401` auth, `404` not found). `status` là số. +- **`uid`** — bỏ trống thì FARE tự sinh; chỉ tự đặt khi cần tham chiếu chéo. +- **Gom nhóm theo tài nguyên / chức năng** (`groups[].name`), không trộn mọi endpoint vào một group. +- **Trung thực §7:** chỉ ghi endpoint / field / mã lỗi có trong nguồn (spec, code contract, OpenAPI nguồn, mô tả User). KHÔNG bịa endpoint, không tự "chuẩn hóa" path/field mà nguồn không nói. +- **Vị trí:** API của một chức năng → gắn `plan_item_id` story; API cấp hệ thống dùng chung → `scope="project"`. +- Doc mặc định `draft` (create KHÔNG nhận `status`). KHÔNG `approved`. + +## Sửa sau khi tạo +Structured KHÔNG có block op — sửa bằng `edit_document(ops=[{op:"replace_all", content:}])`. Đọc `read_document` lấy JSON hiện tại trước, sửa, gửi lại TRỌN bộ. diff --git a/.agent/skills/fare-tech-doc-authoring/references/diagram.md b/.agent/skills/fare-tech-doc-authoring/references/diagram.md new file mode 100644 index 0000000..8c9fc98 --- /dev/null +++ b/.agent/skills/fare-tech-doc-authoring/references/diagram.md @@ -0,0 +1,61 @@ +# Khuôn: doc_type = diagram (drawio mxGraph) + +Sơ đồ trực quan — use-case, sequence, luồng (flowchart), kiến trúc/component. FARE lưu dưới dạng **drawio mxGraph XML**, render bằng editor drawio nhúng. + +`create_document(doc_type="diagram", content=)` — `content_format` mặc định `drawio` (bỏ qua được). KHÔNG truyền `purpose`. + +> ⛔ **KHÔNG gửi Mermaid / PlantUML string.** FARE không parse các cú pháp đó — chỉ nhận mxGraph XML. Gửi Mermaid = doc rỗng / hỏng. + +## Quy trình 2 bước (BẮT BUỘC) +1. **Tạo container** — `create_document(doc_type="diagram", content=)`. Chấp nhận: + - tối thiểu: `` + - hoặc đầy đủ bọc `…`. +2. **Vẽ nội dung qua `edit_diagram`** (per-cell, lossless, live) — KHÔNG resend XML qua `update_document` / `edit_document`. Có thể tạo container đầy đủ ngay ở bước 1 nếu sơ đồ nhỏ; sơ đồ lớn → tạo khung rồi `edit_diagram` thêm từng cell. + +## Khung mxGraphModel +```xml + + + + + + + + + + + + + + +``` + +## Quy tắc chung +- **`id` duy nhất** mọi cell; node/edge đều `parent="1"` (cell `0`/`1` là layer mặc định, GIỮ nguyên). +- **Vertex** (`vertex="1"`) phải có ``. **Edge** (`edge="1"`) phải có `source` + `target` trỏ đúng `id` node đã có; geometry `relative="1"`. +- **Bố cục:** đặt `x/y` giãn cách để không chồng (node ~120×40, cách nhau ≥ 60px). Không cần hoàn hảo — drawio cho User kéo lại. +- **Trung thực §7:** chỉ vẽ actor / bước / thành phần / quan hệ có trong nguồn. KHÔNG bịa node cho "đẹp sơ đồ". +- Doc mặc định `draft` (create KHÔNG nhận `status`). KHÔNG `approved`. Gắn `plan_item_id` story (hoặc `scope` phù hợp), báo User tiêu đề + breadcrumb (rule §4). + +## Công thức theo loại sơ đồ + +### Use-case (actor + use-case + boundary) +- **Actor:** `style="shape=umlActor;html=1;"` (node hẹp cao ~30×60). +- **Use-case:** `style="ellipse;whiteSpace=wrap;html=1;"` — mỗi UC một ellipse. +- **Boundary** (khung hệ thống bao các UC): `style="rounded=0;html=1;verticalAlign=top;"` node lớn, các UC đặt bên trong. +- **Quan hệ:** actor→UC = association `style="endArrow=none;html=1;"`. Giữa UC: `«include»` / `«extend»` = nét đứt `style="endArrow=open;dashed=1;html=1;"`, `value="«include»"`. +- Gắn Mã UC (UC-XXX-0N) vào `value` để nối chip mention với spec. + +### Sequence (tuần tự) +- **Lifeline:** `style="shape=umlLifeline;html=1;"` mỗi actor/đối tượng một cột dọc. +- **Message:** edge ngang giữa 2 lifeline — đồng bộ `endArrow=block`; trả về `dashed=1;endArrow=open`. `value` = tên message theo thứ tự thời gian (trên → dưới). + +### Flowchart (luồng xử lý) +- **Bắt đầu/Kết thúc:** `style="ellipse;..."`. **Bước:** `rounded=1;...`. **Điều kiện:** `style="rhombus;..."` (nhánh `value="Có"/"Không"` trên edge). +- Edge `endArrow=block` theo chiều luồng. + +### Kiến trúc / Component +- **Thành phần:** `rounded=1` hoặc `shape=component`. **Nhóm/layer:** node container `verticalAlign=top`. **Phụ thuộc:** edge có hướng + `value` mô tả (giao thức/loại gọi). + +## Sửa sau khi tạo +**`edit_diagram`** — thêm/sửa/xóa từng cell (lossless, giữ vị trí User đã kéo). TUYỆT ĐỐI KHÔNG `update_document` / `edit_document` cho diagram (ghi đè cả XML, mất layout). diff --git a/.agent/skills/fare-tech-doc-authoring/references/erd.md b/.agent/skills/fare-tech-doc-authoring/references/erd.md new file mode 100644 index 0000000..4521bb0 --- /dev/null +++ b/.agent/skills/fare-tech-doc-authoring/references/erd.md @@ -0,0 +1,61 @@ +# Khuôn: doc_type = erd + +Mô hình dữ liệu — thực thể (entity) + trường (field) + quan hệ (relation). Dùng cho thiết kế DB của một chức năng hoặc toàn hệ thống. +`create_document(doc_type="erd", content=)` — `content_format` FARE tự set `json`. KHÔNG truyền `purpose`. + +> Schema lấy từ mô tả tool `create_document` (nguồn canonical) — nếu FARE đổi, tra lại ở đó. + +## Schema +```json +{ + "mode": "sql", + "entities": [ + { + "id": "ent-user", + "name": "users", + "description": "Tài khoản người dùng", + "color": "#4F46E5", + "position": { "x": 40, "y": 40 }, + "fields": [ + { "id": "fld-user-id", "name": "id", "type": "BIGINT", "isPK": true, "nullable": false, "unique": true }, + { "id": "fld-user-email", "name": "email", "type": "VARCHAR(255)", "isPK": false, "nullable": false, "unique": true, "indexed": true }, + { "id": "fld-user-org", "name": "org_id", "type": "BIGINT", "isFK": true, "nullable": false, "description": "FK → organizations.id" } + ] + }, + { + "id": "ent-org", + "name": "organizations", + "position": { "x": 400, "y": 40 }, + "fields": [ + { "id": "fld-org-id", "name": "id", "type": "BIGINT", "isPK": true, "nullable": false } + ] + } + ], + "relations": [ + { + "id": "rel-user-org", + "source": "ent-user", "target": "ent-org", + "sourceField": "fld-user-org", "targetField": "fld-org-id", + "type": "N:M", "style": "solid", "label": "thuộc về" + } + ] +} +``` + +## Quy tắc +- **`mode`** enum: `sql | nosql`. SQL → field có `type` kiểu cột (`BIGINT`, `VARCHAR(255)`, `TEXT`, `BOOLEAN`, `TIMESTAMP`...); NoSQL → kiểu document/field tương ứng. +- **`entities[].id` & `fields[].id`** — định danh nội bộ ổn định (vd `ent-user`, `fld-user-email`). **Quan hệ trỏ bằng các id này**, KHÔNG bằng tên — sai id = đường nối vỡ. +- **Field flags** (boolean, chỉ thêm khi đúng): `isPK`, `isFK`, `nullable`, `required`, `unique`, `indexed`. `defaultValue`, `description` optional. (FARE tự bù đủ cờ mặc định khi lưu — không cần liệt kê hết cờ `false`.) +- **`position: {x, y}`** — BẮT BUỘC đặt cho mỗi entity, **giãn toạ độ** (vd cách nhau ~300px ngang, ~250px dọc; xếp lưới theo cụm liên quan). BỎ TRỐNG → FARE mặc định `{0,0}` cho TẤT CẢ → mọi entity nằm đè tại gốc canvas, User phải kéo tách thủ công. Đây là điểm hay bỏ sót khi đẩy qua MCP. +- **`relations[]`** — `source`/`target` trỏ `entities.id`; `sourceField`/`targetField` trỏ `fields.id`. **`type`** enum quan hệ: `1:1 | 1:N | N:M`. `style`: `solid | dashed`. `label` optional. +- **FK nhất quán:** field `isFK:true` nên có quan hệ tương ứng trong `relations[]` (và ngược lại) — đừng để FK mồ côi. +- **Tên bảng/cột** theo đúng quy ước nguồn (snake_case hay camelCase) — KHÔNG tự đổi. +- **Trung thực §7:** chỉ mô hình entity/field/quan hệ có trong nguồn (schema thật, migration, spec, mô tả User). KHÔNG bịa bảng, không tự thêm cột "cho đầy đủ", không suy ra quan hệ nguồn không nêu → hỏi User. +- **Vị trí:** ERD của một chức năng → gắn `plan_item_id` story; model dữ liệu cấp hệ thống → `scope="project"`. +- Doc mặc định `draft` (create KHÔNG nhận `status`). KHÔNG `approved`. + +## ERD (dữ liệu, doc_type=erd) ≠ Sơ đồ ERD (hình vẽ, doc_type=diagram) +`erd` lưu **mô hình dữ liệu có cấu trúc** (FARE tự render được). Nếu User muốn một **hình vẽ** ERD tùy biến để nhúng → đó là `doc_type="diagram"` (drawio), khác doc. Đừng nhầm hai loại. + +## Sửa sau khi tạo +Structured KHÔNG có block op — sửa bằng `edit_document(ops=[{op:"replace_all", content:}])`. Đọc `read_document` lấy JSON hiện tại trước, sửa, gửi lại TRỌN bộ. diff --git a/.agent/skills/fare-test-authoring/SKILL.md b/.agent/skills/fare-test-authoring/SKILL.md index b4bfda9..ffd2e15 100644 --- a/.agent/skills/fare-test-authoring/SKILL.md +++ b/.agent/skills/fare-test-authoring/SKILL.md @@ -19,7 +19,7 @@ KHÔNG thuộc skill này: chạy verify TC (→ `fare-test-execution`); báo bu Hỏi & CHỜ: - **Spec mục tiêu:** id US / UC / SRS cụ thể. Hoặc id task `type=TEST` từ PM → tra ngược URI spec trong description. - **Phạm vi coverage:** *full* (mọi AC + boundary + negative) · *smoke* (chỉ positive flow chính) · *regression* (chỉ AC bị động bởi change-request). Hỏi User. -- **Doc test_case container:** dùng doc đã có (`list_documents(kind="test_case", plan_item_id=)`) hay tạo mới? Mặc định: 1 doc test_case / 1 function — kiểm trùng trước. +- **Doc test_case container:** dùng doc đã có (`list_documents(kind="test_case", plan_item_id=)`) hay tạo mới? Mặc định: 1 doc test_case / 1 story — kiểm trùng trước. Đọc spec (paginated tới hết): - `read_document(id)` — US → `stories[].acceptance_criteria[]`; UC → `flows[]` (main/alt/exception); SRS → bảng FR/NFR. @@ -85,11 +85,11 @@ Description PHẢI có ≥1 URI spec — KHÔNG để rỗng (vi phạm §4). ## Bước 3 — Đảm bảo có doc test_case container -`list_documents(projectCode, kind="test_case", plan_item_id=)`: -- **Đã có doc test_case cho function này** → dùng `document_id` đó. KHÔNG tạo trùng. +`list_documents(projectCode, kind="test_case", plan_item_id=)`: +- **Đã có doc test_case cho story này** → dùng `document_id` đó. KHÔNG tạo trùng. - **Chưa có** → đề xuất + **CHỜ User chốt** (§2): ``` - Tạo doc test_case: title="TC - {Tên function}", plan_item_id=, status=draft + Tạo doc test_case: title="TC - {Tên story}", plan_item_id= ``` Sau khi User chốt → `create_document(doc_type="test_case", title=..., plan_item_id=..., content=[])` với content array rỗng (TC thêm sau qua `create_test_cases`). @@ -165,4 +165,4 @@ Báo gọn: - [ ] `description` có URI `fare://documents/{id}` tới AC gốc (§4). - [ ] `type` đúng enum ISTQB (positive/negative/boundary/equivalence_class/state_transition/error_guessing — KHÔNG edge_case). - [ ] Mỗi TC mapping 1-1 về 1 AC / flow / rule cụ thể (§7). -- [ ] `status="draft"` (không tự ready). Dùng `create_test_cases` batch. +- [ ] TC mới để authoring status mặc định `draft` — KHÔNG tự bump `ready` (`create_test_cases` không nhận `status`; đổi qua `update_test_case(status="ready")`). Dùng `create_test_cases` batch. diff --git a/.agent/skills/fare-traceability/SKILL.md b/.agent/skills/fare-traceability/SKILL.md index 9254ebd..103c8b7 100644 --- a/.agent/skills/fare-traceability/SKILL.md +++ b/.agent/skills/fare-traceability/SKILL.md @@ -5,12 +5,12 @@ description: Xây ma trận truy vết requirement ↔ use_case ↔ user_story # fare-traceability — Ma trận truy vết & phát hiện gap -Dùng khi User muốn kiểm: **mọi yêu cầu nghiệp vụ đã có use case / user story / test case / module phủ chưa**, hoặc ngược lại — code/test có đang phục vụ yêu cầu nào không. +Dùng khi User muốn kiểm: **mọi yêu cầu nghiệp vụ đã có use case / user story / test case / plan item (story) phủ chưa**, hoặc ngược lại — code/test có đang phục vụ yêu cầu nào không. KHÔNG dùng để: viết spec mới (→ `fare-spec-authoring`); soát blind spot trong 1 spec (→ `fare-spec-reviewer`). ## Tiền đề -- Đã có **Bản đồ ngữ cảnh** (`fare-context-discovery`) — biết project / module / artifact mỏ neo. +- Đã có **Bản đồ ngữ cảnh** (`fare-context-discovery`) — biết project / plan item / artifact mỏ neo. - Tuân `rules/fare-rules.md`: §3 Context First (không bịa ID), §7 Content Fidelity (không bịa link trace), §9 (trình bày gọn). ## Phạm vi truy vết — User chọn @@ -42,17 +42,17 @@ Quy tắc liên kết: - `use_case`: `read_document(id)` → liệt kê `actors`, `use_cases[].uid`, `flows[]`. - `user_story`: `read_document(id)` → liệt kê `stories[].uid` + số `acceptance_criteria`. 3. **Quét artifact phủ:** - - `list_test_cases(projectCode, plan_item_id|document_id)` → ánh xạ theo `linked_uc_uid` / `linked_story_uid` / `linked_ac_uid` (đọc field tham chiếu thực tế qua mô tả tool). + - `list_test_cases(projectCode, document_id=...)` rồi `list_test_cases(id=)` lấy chi tiết. **TC KHÔNG có field link AC/US/UC cấu trúc** (`linked_ac_uid` v.v. không tồn tại — đã kiểm schema sống). Ánh xạ TC ↔ spec dựng theo 3 nguồn thật: (a) **doc test_case container** gắn `plan_item_id` = story → TC thuộc story nào; (b) **TC→AC mịn**: parse `fare://documents/{us_id} → AC-x` trong `description` của TC (cách `fare-test-authoring` ghi link); (c) **TC→task**: `verify_history[].linked_task_id` và `task.test_case_ids`. - `list_tasks(projectCode, plan_item_id)` → quét `description` cho URI `fare://documents/{id}` để xâu task ↔ spec. - `list_plan_items(projectCode)` (lọc `type="epic"`) → biết cây theme/epic/story; muốn gom task theo epic: `list_tasks(projectCode, plan_item_ids=[], include_descendants=true)`. - `search_rag(query="FR-001")` / `search_rag(query="")` — fallback khi link không tường minh. 4. **Dựng ma trận.** Một bảng cho mỗi cặp lớp; cell ghi ID + URI (hoặc `⚠️ MISSING`). 5. **Liệt kê gap** ngay dưới ma trận — phân loại theo mức rủi ro (xem dưới). 6. **Đề xuất hành động** cho mỗi gap (KHÔNG tự thực thi — chờ User chốt, §2; nhiều việc bàn giao vai khác): - - Yêu cầu thiếu UC/US → đề xuất `create_document(doc_type="use_case"|"user_story")` (qua `fare-spec-authoring`). + - Yêu cầu thiếu UC/US → đề xuất tạo `user_story` (`create_document(doc_type="user_story")`), hoặc đặc tả use-case dạng `richtext` (srs/requirement) — đều qua `fare-spec-authoring`. (Lưu ý: FARE đã bỏ `doc_type="use_case"` để tạo mới — use-case viết bằng richtext, sơ đồ dùng `diagram`.) - UC/US thiếu test → bàn giao **QA** `/fare-test` viết TC. Nếu PM cần task chứa TC → bàn giao PM `/fare-breakdown` tạo task `type=TEST` trước. - Story thiếu task implement → bàn giao **PM** `/fare-breakdown` (KHÔNG tự `create_tasks` — đó là vai PM). - - Spec không gắn module → đề xuất `update_document(plan_item_id=...)`. + - Spec không gắn plan item → đề xuất `update_document(plan_item_id=...)`. - Task không trỏ doc → bàn giao **PM** `/fare-groom` (PM dùng skill `fare-backlog-grooming` xử lý mồ côi spec). ## Mức rủi ro gap @@ -71,12 +71,12 @@ Quy tắc liên kết: ## Ma trận truy vết — {phạm vi} ({hướng}) ### 1. Requirement → Use Case / User Story -| FR ID | Mô tả ngắn | Use Case | User Story | Module | +| FR ID | Mô tả ngắn | Use Case | User Story | Plan item (story) | |---|---|---|---|---| -| FR-001 | ... | `fare://documents/12` | `fare://documents/45` | M1.1 | +| FR-001 | ... | `fare://documents/12` | `fare://documents/45` | S43 | | FR-002 | ... | ⚠️ MISSING | ⚠️ MISSING | — | -> Ô trỏ tài liệu = **chip mention**: ghi URI trần `fare://documents/{id}` (tự thành chip bấm được), hoặc chip HTML có nhãn riêng — xem `fare-mcp-integration`. KHÔNG dùng markdown link `[..](fare://..)` (không bấm được). +> Ô trỏ tài liệu = **chip mention**. Nếu ma trận này đẩy lên FARE thành tài liệu (thân richtext) → dùng **chip HTML đầy đủ** `{nhãn}` (URI trần KHÔNG tự thành chip trong thân doc — xem `fare-mcp-integration`). Nếu chỉ là báo cáo Markdown trong chat → URI trần `fare://documents/{id}` là đủ. KHÔNG dùng markdown link `[..](fare://..)`. ### 2. Use Case / Story → Test Case | Spec | AC count | Test cases | Phủ | @@ -97,11 +97,11 @@ Quy tắc liên kết: ## Gap phát hiện 🟥 BLOCKER (2): -- FR-002 không có UC/US — đề xuất tạo use_case "{tên}" trong story S1.1. +- FR-002 không có UC/US — đề xuất tạo user_story "{tên}" trong story S1.1. - S-1.1.2 chưa có task — đề xuất tạo task "Implement cập nhật nhân viên". 🟧 HIGH (1): -- UC-1 thiếu test cho AC-3 — đề xuất create_test_cases (acceptance, linked_ac_uid="ac-3"). +- UC-1 thiếu test cho AC-3 — bàn giao QA `/fare-test` viết TC, ghi link AC vào `description` (`fare://documents/{us_id} → AC-3`). KHÔNG có field `linked_ac_uid` để truyền. ## Đề xuất hành động — chờ User chốt 1. {hành động cụ thể} → tool {tên} với payload {tóm tắt} diff --git a/.agent/workflows/fare-ba.md b/.agent/workflows/fare-ba.md index 8f05b87..07f8285 100644 --- a/.agent/workflows/fare-ba.md +++ b/.agent/workflows/fare-ba.md @@ -10,11 +10,15 @@ description: Phân tích yêu cầu nghiệp vụ → viết Use Case / User Sto **Đầu vào người dùng:** $ARGUMENTS **Agent phụ trách:** `fare-business-analyst` (chạy theo SOP trong file agent đó). +## Tiền điều kiện +- **Project phải tồn tại** (có project code, `list_projects` thấy). Tạo project là việc người (UI FARE) → chưa có thì **DỪNG**, đề nghị User tạo rồi đưa code. KHÔNG tự khởi tạo project. +- **Spec cần chỗ gắn:** nếu tính năng chưa có nhánh `plan_item_id` (story) trong cây → chạy `/fare-plan` dựng cây trước (rule §1, không doc mồ côi). Có thể nháp local trong `docs/outputs/` trước khi có chỗ gắn. + ## Luồng 1. Kích hoạt agent `fare-business-analyst`. 2. Xác định **chế độ vận hành** (Substitute / Assistant — `rules/operating-mode.md`) nếu ngữ cảnh chưa rõ. 3. Agent chạy SOP: khám phá ngữ cảnh (skill `fare-context-discovery`) → Socratic Gate → viết đặc tả nghiệp vụ. Nếu là tách / chuẩn hóa tài liệu có sẵn → dùng skill `fare-doc-split`. -4. Đồng bộ FARE (`status="draft"`, gắn `plan_item_id`), trả URI tài liệu cho User. +4. Đồng bộ FARE (doc mặc định `draft`, gắn `plan_item_id`), báo User **tiêu đề + breadcrumb vị trí** (rule §4), KHÔNG trả URI trần. ## Bàn giao Gợi ý bước kế: `/fare-audit-spec` để soát đặc tả vừa viết. diff --git a/.agent/workflows/fare-breakdown.md b/.agent/workflows/fare-breakdown.md index 6574ee3..7946681 100644 --- a/.agent/workflows/fare-breakdown.md +++ b/.agent/workflows/fare-breakdown.md @@ -1,12 +1,12 @@ --- name: fare-breakdown -description: Chia 1 Function (đã có spec đầy đủ) thành n task implementable cho dev pickup — theo layer BE/FE/DB/test/infra, batch tạo qua MCP. +description: Chia 1 Story (đã có spec đầy đủ) thành n task implementable cho dev pickup — theo layer BE/FE/DB/test/infra, batch tạo qua MCP. --- # /fare-breakdown — Chia story thành task -**Việc:** đẩy task chi tiết lên backlog cho 1 function đã có spec. -**Cú pháp:** `/fare-breakdown [mã project] [id function] [chiến lược?]` +**Việc:** đẩy task chi tiết lên backlog cho 1 story đã có spec. +**Cú pháp:** `/fare-breakdown [mã project] [id story] [chiến lược?]` **Đầu vào người dùng:** $ARGUMENTS - `[chiến lược?]` (tùy chọn): `layer` (mặc định) · `slice` (vertical theo feature) · `dependency`. **Agent phụ trách:** `fare-project-manager` (chạy skill `fare-task-breakdown`). @@ -14,10 +14,10 @@ description: Chia 1 Function (đã có spec đầy đủ) thành n task implemen ## Luồng 1. Kích hoạt agent `fare-project-manager`. 2. Xác định **chế độ vận hành** (`rules/operating-mode.md`) nếu ngữ cảnh chưa rõ. -3. Agent chạy SOP: kiểm spec function đã đủ chưa → nháp danh sách task (5 layer) → trình bảng + **CHỜ User chốt** → `create_tasks` batch → gắn `links` blocks/relates_to. +3. Agent chạy SOP: kiểm spec story đã đủ chưa → nháp danh sách task (5 layer) → trình bảng + **CHỜ User chốt** → `create_tasks` batch → gắn `links` blocks/relates_to. ## Tiền đề CỨNG -Function mục tiêu phải có spec (UC/US/SRS/api_doc/erd) gắn `plan_item_id`. Spec mỏng → agent DỪNG và bàn giao `/fare-ba` trước. KHÔNG break task khi spec trống. +Story mục tiêu phải có spec (UC/US/SRS/api_doc/erd) gắn `plan_item_id`. Spec mỏng → agent DỪNG và bàn giao `/fare-ba` trước. KHÔNG break task khi spec trống. ## Bàn giao - Task `type=TASK` (BE/FE/DB) → sẵn cho **Dev** pickup qua `/fare-dev` (`fare-developer`). diff --git a/.agent/workflows/fare-groom.md b/.agent/workflows/fare-groom.md index df937fc..808fa6e 100644 --- a/.agent/workflows/fare-groom.md +++ b/.agent/workflows/fare-groom.md @@ -20,4 +20,4 @@ description: Grooming backlog — quét task lệch trạng thái, bug chưa tri ## Bàn giao - Bug mới phát hiện cần track → hỏi User trước khi tạo BUG task (rule §5). - Stale IN_PROGRESS do dev nghỉ → bàn giao team lead reassign. -- DONE chưa verify (BLOCKER) → bàn giao QA (khi vai QA có) hoặc dev cung cấp evidence. +- DONE chưa verify (BLOCKER) → bàn giao QA `/fare-verify` hoặc dev cung cấp evidence. diff --git a/.agent/workflows/fare-handoff.md b/.agent/workflows/fare-handoff.md index a8212e3..fde89bf 100644 --- a/.agent/workflows/fare-handoff.md +++ b/.agent/workflows/fare-handoff.md @@ -13,7 +13,7 @@ description: Sau khi dev code xong, self-verify đối chiếu DoD + TC linked, ## Luồng 1. Kích hoạt agent `fare-developer`. 2. Xác định **chế độ vận hành** (`rules/operating-mode.md`) nếu ngữ cảnh chưa rõ. -3. Agent chạy SOP: đọc lại DoD + TC linked → self-checklist (DoD / TC / impact recheck / spec contract) → gom evidence (commit, branch, file) → trình tóm tắt → **CHỜ User chốt** → `update_task(meta_status="VERIFYING", actual_effort=)` + `add_comment` evidence → bàn giao QA. +3. Agent chạy SOP: đọc lại DoD + TC linked → self-checklist (DoD / TC / impact recheck / spec contract) → gom evidence (commit, branch, file) → trình tóm tắt → **CHỜ User chốt** → `update_task(meta_status="VERIFYING")` (giờ thực tế ghi qua worklog UI, KHÔNG qua MCP) + `add_comment` evidence → bàn giao QA. ## Tiền đề CỨNG - Task đang `IN_PROGRESS` của dev. diff --git a/.agent/workflows/fare-plan.md b/.agent/workflows/fare-plan.md index 66ade46..7c8ba70 100644 --- a/.agent/workflows/fare-plan.md +++ b/.agent/workflows/fare-plan.md @@ -10,6 +10,9 @@ description: Dựng / hoàn thiện cây plan item theme › epic › story (3 c **Đầu vào người dùng:** $ARGUMENTS **Agent phụ trách:** `fare-business-analyst` (chạy skill `fare-plan-breakdown`). +## Tiền điều kiện +- **Project phải tồn tại** (User đưa được project code, `list_projects` thấy). Tạo project là việc người (trên UI FARE — xem ARCHITECTURE) → chưa có thì **DỪNG**, đề nghị User tạo project rồi đưa code. KHÔNG tự bịa/khởi tạo project. + ## Luồng 1. Kích hoạt agent `fare-business-analyst`. 2. Xác định **chế độ vận hành** (`rules/operating-mode.md`) nếu ngữ cảnh chưa rõ. diff --git a/.agent/workflows/fare-pm.md b/.agent/workflows/fare-pm.md index e18c4bf..ac10ebe 100644 --- a/.agent/workflows/fare-pm.md +++ b/.agent/workflows/fare-pm.md @@ -13,16 +13,16 @@ description: Entry chung cho vai PM — agent route theo việc User nói (statu ## Luồng 1. Kích hoạt agent `fare-project-manager`. 2. Xác định **chế độ vận hành** (`rules/operating-mode.md`) nếu ngữ cảnh chưa rõ. -3. Agent chạy `fare-context-discovery` tầng "Trạng thái công việc / tiến độ" — đọc plan + module + task hiện có. +3. Agent chạy `fare-context-discovery` tầng "Trạng thái công việc / tiến độ" — đọc plan + plan item + task hiện có. 4. Agent định tuyến việc User mô tả vào skill phù hợp: - "Tạo sprint mới / month plan tháng X" → `fare-plan-versioning` - "Ước effort cho epic/story Y" → `fare-effort-estimation` - - "Chia task cho function Z" → `fare-task-breakdown` (gợi ý gõ `/fare-breakdown` cho rõ) + - "Chia task cho story Z" → `fare-task-breakdown` (gợi ý gõ `/fare-breakdown` cho rõ) - "Cho tôi status sprint / health-check / grooming" → `fare-backlog-grooming` (gợi ý gõ `/fare-groom`) - Không rõ → hỏi User chọn 1 trong các việc trên. ## Khi nào nên gõ workflow khác thay vì /fare-pm -- Đã rõ việc là **breakdown function cụ thể** → gõ thẳng `/fare-breakdown [project] [function id]` — đỡ 1 round-trip route. +- Đã rõ việc là **breakdown story cụ thể** → gõ thẳng `/fare-breakdown [project] [story id]` — đỡ 1 round-trip route. - Đã rõ việc là **grooming cuối sprint** → gõ thẳng `/fare-groom [project]`. - Cần **viết / sửa spec** → KHÔNG dùng `/fare-pm`; dùng `/fare-ba` hoặc `/fare-change` (vai BA). diff --git a/.agent/workflows/fare-qa.md b/.agent/workflows/fare-qa.md index e51e01d..11dfbb9 100644 --- a/.agent/workflows/fare-qa.md +++ b/.agent/workflows/fare-qa.md @@ -15,10 +15,10 @@ description: Entry chung cho vai QA — agent route theo việc User nói (viế 2. Xác định **chế độ vận hành** (`rules/operating-mode.md`) nếu ngữ cảnh chưa rõ. 3. Agent chạy `fare-context-discovery` (tầng "Trạng thái QA / TC / campaign") — đọc TC hiện có, campaign, task `type=TEST` đang mở. 4. Agent định tuyến việc User mô tả vào skill phù hợp: - - "Viết TC cho [spec / function]" → `fare-test-authoring` (gợi ý gõ `/fare-test`) + - "Viết TC cho [spec / story]" → `fare-test-authoring` (gợi ý gõ `/fare-test`) - "Chạy verify [doc/campaign/task TEST]" → `fare-test-execution` (gợi ý gõ `/fare-verify`) - "Báo bug [hiện tượng]" → `fare-bug-reporting` - - "Soát coverage TC cho [module]" → `fare-test-authoring` + bàn giao BA `/fare-trace` + - "Soát coverage TC cho [story]" → `fare-test-authoring` + bàn giao BA `/fare-trace` - Không rõ → hỏi User chọn 1 trong các việc trên. ## Khi nào nên gõ workflow khác thay vì /fare-qa diff --git a/.agent/workflows/fare-test.md b/.agent/workflows/fare-test.md index 79d5afd..0752980 100644 --- a/.agent/workflows/fare-test.md +++ b/.agent/workflows/fare-test.md @@ -18,7 +18,7 @@ description: Viết test case từ spec đã có (US/UC/SRS) — map AC → n TC ## Tiền đề CỨNG - Spec mục tiêu PHẢI có AC (Given-When-Then) hoặc flows chi tiết. Spec mỏng → agent DỪNG, bàn giao BA `/fare-ba` bổ sung. -- Mọi TC gắn vào 1 doc `test_case` thuộc đúng `plan_item_id` của function (rule §1). +- Mọi TC gắn vào 1 doc `test_case` thuộc đúng `plan_item_id` của story (rule §1). ## Bàn giao - TC tạo xong → bàn giao **executor** chạy `/fare-verify`. diff --git a/.agent/workflows/fare-trace.md b/.agent/workflows/fare-trace.md index ae39539..494e7d5 100644 --- a/.agent/workflows/fare-trace.md +++ b/.agent/workflows/fare-trace.md @@ -1,12 +1,12 @@ --- name: fare-trace -description: Xây ma trận truy vết requirement ↔ use_case ↔ user_story ↔ test_case ↔ module ↔ task; phát hiện gap trước khi go-live / bàn giao QA. +description: Xây ma trận truy vết requirement ↔ use_case ↔ user_story ↔ test_case ↔ plan item (theme/epic/story) ↔ task; phát hiện gap trước khi go-live / bàn giao QA. --- # /fare-trace — Ma trận truy vết & gap -**Việc:** quét phạm vi User chọn (project / module / 1 doc), xâu chuỗi từ yêu cầu nghiệp vụ tới task/test, liệt kê chỗ thiếu phủ. -**Cú pháp:** `/fare-trace [mã project] [module|doc id?] [forward|backward?]` +**Việc:** quét phạm vi User chọn (project / plan item / 1 doc), xâu chuỗi từ yêu cầu nghiệp vụ tới task/test, liệt kê chỗ thiếu phủ. +**Cú pháp:** `/fare-trace [mã project] [plan item id|doc id?] [forward|backward?]` **Đầu vào người dùng:** $ARGUMENTS **Agent phụ trách:** `fare-business-analyst` (chạy skill `fare-traceability`). @@ -17,5 +17,5 @@ description: Xây ma trận truy vết requirement ↔ use_case ↔ user_story ## Bàn giao - Gap loại spec thiếu (🟥/🟧): chuyển `/fare-ba` để bổ sung use_case / user_story. -- Gap loại test thiếu (🟧): bàn giao QA (khi vai QA được xây). +- Gap loại test thiếu (🟧): bàn giao QA `/fare-test` viết TC. - Gap loại task/link thiếu (🟨): bàn giao PM hoặc dev chạy `update_task`. diff --git a/.agent/workflows/fare-write-doc.md b/.agent/workflows/fare-write-doc.md index 8b47fa3..2b44e9c 100644 --- a/.agent/workflows/fare-write-doc.md +++ b/.agent/workflows/fare-write-doc.md @@ -6,14 +6,14 @@ description: Viết tài liệu kỹ thuật (API doc, ERD, diagram, specificati # /fare-write-doc — Viết tài liệu kỹ thuật **Việc:** viết / cập nhật một tài liệu kỹ thuật trên FARE. -**Cú pháp:** `/fare-write-doc [mã project] [loại tài liệu?] [module?]` +**Cú pháp:** `/fare-write-doc [mã project] [loại tài liệu?] [plan item id?]` **Đầu vào người dùng:** $ARGUMENTS **Agent phụ trách:** `fare-technical-writer` (chạy theo SOP trong file agent đó). ## Luồng 1. Kích hoạt agent `fare-technical-writer`. 2. Xác định **chế độ vận hành** (`rules/operating-mode.md`) nếu ngữ cảnh chưa rõ. -3. Agent chạy SOP: xác nhận loại tài liệu + module đích → khảo sát ngữ cảnh (skill `fare-context-discovery`) → viết đúng format / schema → đồng bộ FARE (`status="draft"`). +3. Agent chạy SOP: xác nhận loại tài liệu + plan item đích → khảo sát ngữ cảnh (skill `fare-context-discovery`) → viết đúng format / schema → đồng bộ FARE (doc mặc định `draft`). ## Bàn giao Gợi ý bước kế: `/fare-audit-spec` để soát tài liệu vừa viết. diff --git a/CHANGELOG.md b/CHANGELOG.md index 00e28ad..ca98798 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,32 @@ Format theo [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/); vers ## [Unreleased] +## [2.0.1] - 2026-06-29 + +> Rà soát chất lượng skill pack đối chiếu trực tiếp với MCP server FARE thật (probe live từng tool/resource). Sửa loạt bug "im lặng" khiến agent gọi MCP fail hoặc tạo artifact không định vị được — không breaking, an toàn nâng cấp từ 2.0.0. + +### Added +- **Skill `fare-tech-doc-authoring`** cho vai `fare-technical-writer` — khuôn JSON cho `api_doc` / `erd` + cách tạo `diagram` (drawio), gồm 3 reference (`api-doc.md` · `erd.md` · `diagram.md`). Trước đây technical-writer không có skill viết tài liệu kỹ thuật nào (chỉ dựa mô tả tool). Wire vào agent + `ARCHITECTURE`. +- **Nhánh greenfield** trong `fare-context-discovery` — xử lý đầu vào là file ngoài (Word/PDF/Excel) cho feature chưa có trên FARE (không có artifact mỏ neo `read_document`), kèm biến thể mẫu Bản đồ ngữ cảnh. +- **Tiền điều kiện "project phải tồn tại"** ở `/fare-plan` + `/fare-ba`. + +### Fixed +- **Param `status` lúc `create_document` → lỗi `-32602`** (tool không nhận `status`; doc mặc định `draft`). Bỏ khỏi mọi ví dụ create (spec-authoring, doc-split, test-authoring, technical-writer, business-analyst, workflows). `update_document` status enum đúng là `draft|review` — sửa `in_review` (không tồn tại) ở requirement.md, change-request. +- **`update_task(actual_effort=…)` → lỗi `-32602`** (tool không có field này; giờ thực tế ghi qua worklog UI). Sửa self-verify, developer, effort-estimation, workflow handoff. +- **Chữ ký `add_comment` đã đổi** → `(projectCode, entityType, entityId, content-HTML)`. Sửa các ví dụ `add_comment(taskId, comment=…)` ở self-verify, impact-analysis, task-pickup + làm giàu reference trung tâm. +- **Chip-mention trong THÂN tài liệu richtext:** URI trần `fare://documents/{id}` KHÔNG tự thành chip (lưu thành text thuần — verify round-trip) → bắt buộc chip HTML đầy đủ. Sửa mcp-integration, requirement.md, traceability (phân biệt với `description` task/comment nơi URI trần auto-chip). +- **SRS theo chức năng:** hướng dẫn cũ (`content` trống → template hệ thống) làm mất title (→ "SRS") + sai format (ISO 29148 generic thay vì use-case của team). Đổi sang viết content use-case trực tiếp + title có nghĩa; cảnh báo template ghi đè title. +- **Glossary dedup** dùng `list_documents(query=…, kind=…)` — `query` lọc theo tiêu đề nên trượt glossary đặt tên tiếng Việt → bỏ `query`, chỉ `kind="glossary"`. +- **Thuật ngữ "module"/"Module/Function" đời cũ** còn sót → "plan item (theme/epic/story)" ở traceability, doc-split, backlog-grooming, context-discovery, các workflow (trace/qa/write-doc). +- **`effort_est` (field dẫn xuất) ghi như set được** → `effort_est_level` (project-manager). +- **Tàn dư "(khi vai QA được xây)"** (vai QA đã tồn tại) → bàn giao thẳng `/fare-test` `/fare-verify` (spec-reviewer, trace, groom, change-request, task-breakdown). +- **Ranh giới vai:** Dev được ngụ ý tự cập nhật api_doc/erd (không có tool) → bàn giao technical-writer; `fare-traceability` xếp nhầm vào "skill chính" của QA → bàn giao BA. + +### Changed +- **`fare-plan-breakdown`:** thêm cảnh báo "đừng mirror cách gom nhóm của tài liệu nguồn — regroup theo cohesion domain" (nguồn thường phrasing theo value nên dễ tưởng đúng trục). +- **Chuẩn hóa khuôn agent** PM/QA/Dev: thêm header "Nhận đầu vào từ / Bàn giao cho" (đồng bộ với BA/technical-writer/spec-reviewer) để soi handoff dễ. +- **Linter `bin/check-tools.mjs`:** thêm `query_params` (field schema api_doc) vào allowlist `NON_TOOL` — tránh dương tính giả. + ## [2.0.0] - 2026-06-26 > **BREAKING:** đồng bộ với API MCP FARE bản mới — bỏ mô hình Module/Epic đời cũ, đổi tên param `module_id` → `plan_item_id`. Skill/prompt pin theo tên tool hoặc param cũ cần cập nhật. diff --git a/bin/check-tools.mjs b/bin/check-tools.mjs index 60cf653..0c3057e 100644 --- a/bin/check-tools.mjs +++ b/bin/check-tools.mjs @@ -34,11 +34,11 @@ const CANONICAL = new Set([ // Tồn tại nhưng KHÔNG nên dùng nữa → cảnh báo, không fail. const DEPRECATED = { - patch_document: 'edit_document (block ops y hệt, patch_document chỉ giữ tương thích ngược)', }; // Tool ĐỜI CŨ đã bị server FARE gỡ bỏ → fail kèm gợi ý thay thế. const REMOVED = { + patch_document: 'edit_document (block ops y hệt — patch_document đã gỡ khỏi MCP)', add_module: 'add_plan_item (type=theme|epic|story)', update_module: 'update_plan_item', list_modules: 'list_plan_items', @@ -65,6 +65,7 @@ const TOKEN_RE = new RegExp(`\\b${VERB}_[a-z][a-z0-9_]+`, 'g'); // tránh dương tính giả. add_links/remove_test_case_ids là param của update_task… const NON_TOOL = new Set([ 'add_links', 'remove_test_case_ids', 'update_at', 'create_at', 'list_view', + 'query_params', // field của schema api_doc (create_document), không phải tool ]); // Chỉ quét tài liệu FARE — bỏ qua skill office (docx/pdf/xlsx) vốn có tên hàm diff --git a/package.json b/package.json index b6a9e4b..3c37c62 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "fare-skill-pack", - "version": "2.0.0", - "description": "Antigravity / Claude Code skill pack for FARE — 6 agents (BA · PM · QA · Dev · technical-writer · spec-reviewer), 23 skills, 18 workflows operating FARE via MCP.", + "version": "2.0.2", + "description": "Antigravity / Claude Code skill pack for FARE — 6 agents (BA · PM · QA · Dev · technical-writer · spec-reviewer), 24 skills, 18 workflows operating FARE via MCP.", "type": "module", "bin": { "fare-skill-pack": "bin/fare-skill.mjs",