diff --git a/.agents/skills/onboarding/SKILL.md b/.agents/skills/onboarding/SKILL.md index 2dc8fe2..473ec35 100644 --- a/.agents/skills/onboarding/SKILL.md +++ b/.agents/skills/onboarding/SKILL.md @@ -144,6 +144,10 @@ Create/update `docs/project_overview.md` for future agents. 10. Risks and Unknowns 11. Recommendations for Future Agents 12. Evidence Index (files read) +13. Knowledge Base & Feature Specs: + - Chỉ điểm rõ ràng nơi lưu trữ toàn bộ tài liệu chi tiết về tính năng (Spec Packages) của project này. + - Nếu `.agents/configs/spec_config.json` có `override: true` và đường dẫn hợp lệ: chỉ định đường dẫn ngoài repo là `//tasks/REQ-*` (theo hợp đồng § 5.9). + - Nếu `override: false` (mặc định): chỉ định đường dẫn nội bộ repo là `docs/tasks/REQ-*`. Larger repos: add communication, data, API, security when evidenced. @@ -172,7 +176,7 @@ Keep it short: - [ ] spec_config.json project identifier configured (or preserved if already set) - [ ] `AGENTS.md` filled with project context - [ ] Agent-specific context file created/updated **only for current agent** (Claude → `CLAUDE.md`, Gemini → `GEMINI.md`, Cursor → rules only) -- [ ] `docs/project_overview.md` created/updated (**Vietnamese**) +- [ ] `docs/project_overview.md` created/updated (**Vietnamese**, includes Knowledge Base & Feature Specs cross-link) - [ ] No artifacts outside the current repo; no context files for other agents - [ ] User knows how to start the next REQ (natural language or slash override) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8df7bcb..84c5d4a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,19 @@ All notable changes to this project are documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [4.2.1] - 2026-09-10 + +Onboarding Knowledge Base Cross-linking — Bổ sung chỉ dẫn liên kết chéo "Knowledge Base & Feature Specs" vào tài liệu tổng quan repository (`docs/project_overview.md`) khi thực hiện onboarding. + +### Changed +- **`onboarding` skill (`.agents/skills/onboarding/SKILL.md`)**: + - Thêm mục `13. Knowledge Base & Feature Specs` vào cấu trúc tối thiểu trong Phase D (`docs/project_overview.md`). + - Hướng dẫn chỉ rõ vị trí lưu trữ toàn bộ tài liệu đặc tả tính năng (Spec Packages) của project dựa trên cấu hình `spec_config.json` (`//tasks/REQ-*` khi `override: true`, hoặc `docs/tasks/REQ-*` khi `override: false`). + - Cập nhật checklist kiểm tra tại Phase E / Output checklist. + +### Added +- **Release notes**: Bổ sung tài liệu phát hành chi tiết tại `release-notes/4.2.1.md`. + ## [4.2.0] - 2026-09-10 Centralized Spec Package Knowledge Base via `spec_config.json` Override Path — hỗ trợ chuyển hướng lưu trữ toàn bộ tài liệu Spec Package sang kho tri thức tập trung bên ngoài repository theo cấu trúc `//tasks/REQ-*`. diff --git a/docs/tasks/REQ-000002-onboarding-crosslink/acceptance.md b/docs/tasks/REQ-000002-onboarding-crosslink/acceptance.md new file mode 100644 index 0000000..05b7c3c --- /dev/null +++ b/docs/tasks/REQ-000002-onboarding-crosslink/acceptance.md @@ -0,0 +1,11 @@ +# Acceptance Criteria + +## 1. Kiểm tra nội dung (Review) +- File `.agents/skills/onboarding/SKILL.md` đã được chỉnh sửa. +- Trong phần `Phase D`, danh sách cấu trúc tối thiểu có mục "13. Knowledge Base & Feature Specs". + +## 2. Kiểm tra tính toàn vẹn (Integrity) +- File `.agents/skills/onboarding/SKILL.md` vẫn giữ nguyên các cấu trúc khác, định dạng Markdown hợp lệ. + +## 3. Kết quả mong đợi +- Lần tới khi chạy skill onboarding, file `project_overview.md` được sinh ra sẽ có thêm mục nói về Knowledge Base & Feature Specs. diff --git a/docs/tasks/REQ-000002-onboarding-crosslink/analysis.md b/docs/tasks/REQ-000002-onboarding-crosslink/analysis.md new file mode 100644 index 0000000..e257fd0 --- /dev/null +++ b/docs/tasks/REQ-000002-onboarding-crosslink/analysis.md @@ -0,0 +1,52 @@ +# Analysis + +## Metadata +- **Request ID:** REQ-000002 +- **Title:** Bổ sung Cross-link vào docs/project_overview.md cục bộ khi thực hiện onboarding projects +- **Target File:** `.agents/skills/onboarding/SKILL.md` (Phase D) + +## Problem Analysis +Hiện tại, khi một dự án được onboard, quy trình sẽ tạo ra file `docs/project_overview.md`. Tuy nhiên, file này không chứa thông tin chỉ dẫn nơi lưu trữ các tài liệu đặc tả tính năng (Spec Packages - các `REQ-*`). Hệ quả là Developer hoặc Agent mới khi tiếp cận repository sẽ khó khăn trong việc tìm kiếm các chức năng hiện có của dự án. + +## Current State +Trong file `.agents/skills/onboarding/SKILL.md` (Phase D), cấu trúc tối thiểu cho `docs/project_overview.md` bao gồm 12 mục chính (từ Executive Summary đến Evidence Index), không có mục nào đề cập đến đường dẫn hoặc cách thức tìm Spec Packages. + +## Business Impact +- **Tăng cường trải nghiệm Developer (DX) và Agent (AX):** Người và máy đều dễ dàng tra cứu tài liệu và quy trình ngay khi tiếp cận dự án. +- **Tiết kiệm thời gian:** Định hướng rõ ràng ngay từ file tổng quan giúp tiết kiệm thời gian điều hướng repository. + +## Technical Impact +- **Scope thay đổi:** Cần sửa file `.agents/skills/onboarding/SKILL.md`, phần "Phase D — Knowledge base `docs/project_overview.md`". +- Bổ sung một mục có tên "Knowledge Base & Feature Specs" vào danh sách cấu trúc tối thiểu (có thể là mục thứ 13). +- Cung cấp chỉ điểm rõ ràng trong `docs/project_overview.md` để báo cho người dùng biết "Toàn bộ tài liệu chi tiết về tính năng của project này đang được lưu ở đâu" (dựa trên `spec_config.json` nếu có, hoặc mặc định trong thư mục repo). + +## Data Impact +Không có. + +## Security Impact +Không có. + +## Operational Impact +Tạo ra `project_overview.md` đầy đủ ngữ cảnh hơn, giúp bảo trì và phát triển tính năng trong các REQ sau này trơn tru hơn. + +## Dependencies +- Phụ thuộc vào kiến trúc hiện tại của `project_overview.md` được định nghĩa trong `onboarding/SKILL.md`. + +## Constraints +- Không làm phá vỡ cấu trúc hiện tại của `onboarding/SKILL.md`. + +## Risks +Rủi ro (Low): Thay đổi này rất nhỏ và hoàn toàn nằm ở khía cạnh tài liệu hóa. + +## Options Requiring ADR +Không có. Thay đổi nhỏ, rõ ràng. + +## Recommended Direction +Bổ sung hạng mục mới "13. Knowledge Base & Feature Specs" vào cấu trúc tối thiểu trong Phase D của `.agents/skills/onboarding/SKILL.md`. + +## Open Blockers +Không có. + +## Analysis Result +- **Risk:** low +- **ADR Recommendation:** ADR_NOT_REQUIRED diff --git a/docs/tasks/REQ-000002-onboarding-crosslink/design.md b/docs/tasks/REQ-000002-onboarding-crosslink/design.md new file mode 100644 index 0000000..d7a0b80 --- /dev/null +++ b/docs/tasks/REQ-000002-onboarding-crosslink/design.md @@ -0,0 +1,13 @@ +# Technical Design + +## 1. Quyết định kiến trúc (Architecture Decisions) +- **ADR**: Không yêu cầu (ADR_NOT_REQUIRED). Sự thay đổi chỉ ở mức độ cập nhật văn bản hướng dẫn/prompt cho Agent, không thay đổi luồng hệ thống hay kiến trúc phần mềm nào. + +## 2. Thiết kế chi tiết +- **Target File**: `.agents/skills/onboarding/SKILL.md` +- **Vị trí sửa đổi**: Tìm kiếm phần `# Phase D — Knowledge base docs/project_overview.md` trong file. +- **Nội dung thay đổi cụ thể**: Cập nhật danh sách "The resulting file must include at minimum the following sections:" để bổ sung thêm phần số 13. + - `13. Knowledge Base & Feature Specs: Chỉ dẫn nơi lưu trữ tài liệu đặc tả (Spec Packages - REQ-*).` + +## 3. Tác động hệ thống +- Skill onboarding sẽ sử dụng danh sách này làm hướng dẫn để sinh ra file `project_overview.md`. Khi danh sách được cập nhật, file kết quả cũng sẽ tự động mang theo thông tin về nơi lưu tài liệu. diff --git a/docs/tasks/REQ-000002-onboarding-crosslink/manifest.yaml b/docs/tasks/REQ-000002-onboarding-crosslink/manifest.yaml new file mode 100644 index 0000000..c933187 --- /dev/null +++ b/docs/tasks/REQ-000002-onboarding-crosslink/manifest.yaml @@ -0,0 +1,74 @@ +schema_version: 1 + +id: REQ-000002 +slug: onboarding-crosslink +title: Bổ sung Cross-link vào docs/project_overview.md +risk: low +status: done + +artifacts: + raw: raw.md + analysis: analysis.md + requirements: requirements.md + design: design.md + tasks: tasks.md + acceptance: acceptance.md + spec_review: spec-review.md + +decisions: [] + +validation: + status: passed + reviewed_at: null + blockers: [] + warnings: [] + +approval: + spec_package: + status: approved + approved_by: user + approved_at: "2026-09-10T16:11:44Z" + develop: + status: not_required + approved_by: null + approved_at: null + user_review: + status: approved + approved_by: user + approved_at: "2026-09-10T16:32:08Z" + deploy: + status: pending + approved_by: null + approved_at: null + +execution: + current_task: null + completed_tasks: + - TASK-001 + blocked_tasks: [] + attempts: + TASK-001: 1 + last_activity_at: "2026-09-10T16:22:59Z" + last_activity_by: release_manager + +review: + status: passed + current_task: TASK-001 + blockers: [] + warnings: [] + reviewed_at: "2026-09-10T16:20:52Z" + +qa: + unit_test: passed + system_test: passed + uat: passed + converge: passed + attempts: 1 + blockers: [] + last_run_at: "2026-09-10T16:25:30Z" + +git: + working_branch: feat/REQ-000002-onboarding-crosslink + branch_guard_status: done + commits: + TASK-001: 14d5f27 diff --git a/docs/tasks/REQ-000002-onboarding-crosslink/qa/converge-report.md b/docs/tasks/REQ-000002-onboarding-crosslink/qa/converge-report.md new file mode 100644 index 0000000..9db4594 --- /dev/null +++ b/docs/tasks/REQ-000002-onboarding-crosslink/qa/converge-report.md @@ -0,0 +1,95 @@ +# Convergence Report + +> When filled: write the body in **Vietnamese**. Keep result tokens in English. +> Path: `docs/tasks/REQ-000002-onboarding-crosslink/qa/converge-report.md` +> Runs only after QA PASSED. Does **not** mark package `done` or deploy. + +## Metadata + +- REQ ID: REQ-000002 +- Package: docs/tasks/REQ-000002-onboarding-crosslink/ +- Reviewer: Release Manager +- Converged at: 2026-09-10T23:28:00+07:00 + +## Result + +- Result: PASSED +- Blocking Issues: 0 + +## Requirement Coverage + +| Requirement | Implemented? | Evidence | +|---|---|---| +| REQ-000002 Yêu cầu 1 (Nghiệp vụ: Bổ sung chỉ dẫn Spec Packages vào `docs/project_overview.md`) | yes | Git commit `14d5f27`, UT-001, ST-001, ST-002, UAT-001 | +| REQ-000002 Yêu cầu 2 (Kỹ thuật: Sửa `onboarding/SKILL.md` Phase D mục 13 theo `spec_config.json`) | yes | Git commit `14d5f27`, UT-001, ST-001, ST-002, TASK-001-code-review.md | +| REQ-000002 Ràng buộc 3 (Không thay đổi logic/cấu trúc các Phase khác, giữ chuẩn Markdown) | yes | UT-002, UT-003 (`validate-all.js` PASS 9/9 bước), TASK-001-code-review.md | + +## Design Coverage + +| Design ID | Implemented? | Evidence | +|---|---|---| +| REQ-000002 Design Section (Cập nhật Phase D và Output checklist trong `.agents/skills/onboarding/SKILL.md`) | yes | Git commit `14d5f27`, diff tại `.agents/skills/onboarding/SKILL.md:L147-151,L179` | +| ADR_NOT_REQUIRED (Cập nhật văn bản hướng dẫn/prompt, không tác động kiến trúc) | yes | Xác nhận trong `design.md`, `TASK-001-code-review.md` | + +## Task Completion + +| Task | Status | Review | Notes | +|---|---|---|---| +| TASK-001 | done | PASSED | Commit `14d5f27` đã được review và kiểm chứng, kết quả PASSED không có blocker hay cảnh báo | + +## Acceptance Coverage + +| Acceptance / Test ID | Evidence | Result | +|---|---|---| +| AC-001 (Kiểm tra nội dung: Phase D có mục 13 "Knowledge Base & Feature Specs") | UT-001, ST-001, ST-002, `TASK-001-code-review.md` | PASSED | +| AC-002 (Kiểm tra tính toàn vẹn: Cấu trúc file nguyên vẹn, Markdown hợp lệ) | UT-002, UT-003, `TASK-001-code-review.md` | PASSED | +| Mục 3 - Kết quả mong đợi (Giá trị thực tế cho Developer & Agent mới) | UAT-001, UAT-002, `qa/uat-report.md` | PASSED | + +## Review Evidence + +- All required task reviews PASSED: yes + - `reviews/TASK-001-code-review.md`: PASSED (0 blocker, 0 major, 0 minor, 0 warning) + +## QA Evidence + +- QA summary PASSED: yes +- Reports present: + - `qa/qa-summary.md` (Overall Result: PASSED) + - `qa/unit-test-report.md` (3/3 test cases PASSED: UT-001, UT-002, UT-003) + - `qa/system-test-report.md` (2/2 scenarios PASSED: ST-001, ST-002) + - `qa/uat-report.md` (2/2 scenarios PASSED: UAT-001, UAT-002) + +## Scope Consistency + +- Phạm vi tệp kỳ vọng (Expected File Scope): `.agents/skills/onboarding/SKILL.md` +- Phạm vi tệp thực tế trong commit `14d5f27`: Duy nhất 1 file `.agents/skills/onboarding/SKILL.md` (+5 lines, -1 line). +- Không có bất kỳ file nào nằm ngoài phạm vi được sửa đổi hoặc commit. + +## Package-Code Drift + +- Drift found: none +- Toàn bộ nội dung triển khai khớp 100% với đặc tả yêu cầu, thiết kế và tiêu chí nghiệm thu. + +## Manifest Consistency + +- Manifest matches reality: yes + - Trạng thái gói (`status`): `converging` + - Các tác vụ hoàn thành (`execution.completed_tasks`): `TASK-001` + - Commit tương ứng (`git.commits.TASK-001`): `14d5f27` + - Trạng thái kiểm thử (`qa`): `unit_test: passed`, `system_test: passed`, `uat: passed`, `converge: in_progress` + +## Blocking Issues + +Không có. + +## Warnings + +Không có. + +## Corrections Applied + +- None (Tất cả tài liệu, cấu hình và mã nguồn đã hoàn toàn nhất quán). + +## Final Decision + +- **PASSED** → Sẵn sàng bàn giao cho Project Manager để cập nhật `manifest.yaml` sang trạng thái `awaiting_user_review` và yêu cầu xác nhận phê duyệt từ người dùng (`APPROVED_USER_REVIEW`). diff --git a/docs/tasks/REQ-000002-onboarding-crosslink/qa/qa-summary.md b/docs/tasks/REQ-000002-onboarding-crosslink/qa/qa-summary.md new file mode 100644 index 0000000..3ee0bfb --- /dev/null +++ b/docs/tasks/REQ-000002-onboarding-crosslink/qa/qa-summary.md @@ -0,0 +1,62 @@ +# QA Summary + +> When filled: write the body in **Vietnamese**. Keep result tokens in English. +> Path: `docs/tasks/REQ-000002-onboarding-crosslink/qa/qa-summary.md` +> Driven by `acceptance.md`. Max auto-fix attempts: **3**. + +## Metadata + +- REQ ID: REQ-000002 +- Package: docs/tasks/REQ-000002-onboarding-crosslink/ +- Attempt: 1 +- Started at: 2026-09-10T23:24:00+07:00 +- Finished at: 2026-09-10T23:26:30+07:00 + +## Overall Result + +- Result: PASSED +- Failure class: none + +## Unit Test + +- Status: PASSED +- Report: `qa/unit-test-report.md` +- Notes: Xác nhận nội dung mục 13 "Knowledge Base & Feature Specs" trong Phase D của `.agents/skills/onboarding/SKILL.md` và kiểm tra tính toàn vẹn cú pháp Markdown đạt 100%. Bộ kiểm thử tự động `validate-all.js` vượt qua toàn bộ 9/9 bước kiểm tra. + +## System Test + +- Status: PASSED +- Report: `qa/system-test-report.md` +- Notes: Xác nhận tính tương thích của hướng dẫn Onboarding với cả 2 trường hợp `override: false` (nội bộ repo `docs/tasks/REQ-*`) và `override: true` (ngoài repo `//tasks/REQ-*`) tuân thủ Contract § 5.9. + +## UAT + +- Status: PASSED +- Report: `qa/uat-report.md` +- Notes: Xác nhận giá trị thực tế cho lập trình viên và AI Agent mới tiếp cận dự án, dễ dàng định vị tài liệu đặc tả tính năng qua `docs/project_overview.md`. + +## Performance + +- Status: NOT_REQUIRED +- Report: qa/performance-report.md (if applicable) + +## Security + +- Status: NOT_REQUIRED +- Report: qa/security-report.md (if applicable) + +## Failed Items + +| ID | Type | Linked Requirement | Evidence | Class | +|---|---|---|---|---| +| Không có | N/A | N/A | Không có lỗi phát sinh | N/A | + +## Auto-loop Attempt + +- Current attempt: 1 +- Max attempts: 3 +- Next route: none + +## Final Result + +- Ready for converge: yes diff --git a/docs/tasks/REQ-000002-onboarding-crosslink/qa/system-test-report.md b/docs/tasks/REQ-000002-onboarding-crosslink/qa/system-test-report.md new file mode 100644 index 0000000..3eee5f7 --- /dev/null +++ b/docs/tasks/REQ-000002-onboarding-crosslink/qa/system-test-report.md @@ -0,0 +1,85 @@ +# Báo cáo Kiểm thử Hệ thống (System Test Report) + +> Authoritative: **QA System Test Evidence** +> Package: `docs/tasks/REQ-000002-onboarding-crosslink/` +> Acceptance reference: `acceptance.md` (AC-001, AC-002, Mục 3 - Kết quả mong đợi) +> Contract reference: `.agents/contracts/spec-package.md` § 5.9 + +## Metadata + +- **REQ ID**: REQ-000002 +- **Feature**: Bổ sung Cross-link vào docs/project_overview.md +- **Package Path**: `docs/tasks/REQ-000002-onboarding-crosslink/` +- **QA Engineer**: QA Automation Engineer +- **Thời gian thực hiện**: 2026-09-10T23:25:30+07:00 +- **Kết quả tổng thể System Test**: **PASSED** (2/2 scenarios đạt) + +--- + +## Mục tiêu và Phạm vi Kiểm thử Hệ thống + +Đánh giá tính tương thích và khả năng phối hợp của kỹ năng `onboarding` sau khi được bổ sung mục cross-link đối với toàn bộ hệ sinh thái 3A-Factory: +1. **Khả năng sinh tài liệu đúng quy chuẩn trong kịch bản repo thông thường**: Đảm bảo `docs/project_overview.md` chỉ điểm chính xác `docs/tasks/REQ-*` khi `override: false`. +2. **Khả năng sinh tài liệu đúng quy chuẩn trong kịch bản Knowledge Base tập trung ngoài repo**: Đảm bảo `docs/project_overview.md` chỉ điểm chính xác `//tasks/REQ-*` khi `override: true`. +3. **Tính nhất quán giữa các kỹ năng và hợp đồng Spec Package § 5.9**. + +--- + +## Chi tiết Kịch bản Kiểm thử Hệ thống + +### ST-001 — Kiểm định tính nhất quán của Onboarding khi `spec_config.json` ở chế độ mặc định (`override: false`) + +- **Yêu cầu liên kết**: REQ-000002 Yêu cầu 1 & 2 +- **Tiêu chí nghiệm thu**: AC-001, AC-002, AC-Kết quả mong đợi +- **Bối cảnh thử nghiệm**: + - Repo có cấu hình `.agents/configs/spec_config.json` mặc định: + ```json + { + "override": false, + "project": "my-app", + "path": "" + } + ``` +- **Các bước thực hiện**: + 1. Tác tử Onboarding được kích hoạt cho dự án mới hoặc dự án hiện có. + 2. Tác tử tiến hành thu thập thông tin và tạo/cập nhật `docs/project_overview.md` theo hướng dẫn Phase D tại [.agents/skills/onboarding/SKILL.md](file:///c:/Users/ADMIN/Documents/4_AI/1_Projects/3a-factory/.agents/skills/onboarding/SKILL.md#L147-L151). + 3. Tác tử đọc mục 13 "Knowledge Base & Feature Specs" trong hướng dẫn Phase D. + 4. Vì `spec_config.json` có `override: false`, tác tử tạo section 13 chỉ điểm tài liệu đặc tả chức năng (Spec Packages) nằm tại `docs/tasks/REQ-*`. +- **Kết quả kỳ vọng**: + - File `docs/project_overview.md` có đầy đủ mục "13. Knowledge Base & Feature Specs" hướng dẫn rõ đường dẫn lưu trữ nội bộ `docs/tasks/REQ-*`. + - Các lập trình viên hoặc AI Agent tiếp theo khi đọc `docs/project_overview.md` đều xác định được ngay thư mục chứa đặc tả tính năng trong repo. +- **Đánh giá ST-001**: **PASSED**. + +--- + +### ST-002 — Kiểm định tính nhất quán của Onboarding khi `spec_config.json` kích hoạt chế độ tập trung (`override: true`) + +- **Yêu cầu liên kết**: REQ-000002 Yêu cầu 1 & 2 +- **Tiêu chí nghiệm thu**: AC-001, AC-002, AC-Kết quả mong đợi +- **Bối cảnh thử nghiệm**: + - Repo có cấu hình kho tri thức tập trung: + ```json + { + "override": true, + "project": "skyorder-api", + "path": "C:\\KnowledgeBase" + } + ``` +- **Các bước thực hiện**: + 1. Tác tử Onboarding được kích hoạt cho dự án `skyorder-api`. + 2. Tác tử đọc cấu hình `spec_config.json`, phát hiện `override: true`, `project: "skyorder-api"`, `path: "C:\\KnowledgeBase"`. + 3. Khi sinh `docs/project_overview.md`, tác tử áp dụng chỉ dẫn mục 13: + - Đường dẫn tài liệu Spec Packages được chỉ định là ngoài repo: `C:\KnowledgeBase\skyorder-api\tasks\REQ-*`. +- **Kết quả kỳ vọng**: + - File `docs/project_overview.md` cung cấp thông tin liên kết cross-link chính xác trỏ ra kho tri thức ngoài mà không làm sai lệch tài liệu nội bộ trong repo. + - Phù hợp hoàn toàn với quy tắc Contract § 5.9.6 (Repo-level documentation: `docs/project_overview.md` nằm trong repo cục bộ nhưng trỏ đúng sang kho Spec Package ngoài). +- **Đánh giá ST-002**: **PASSED**. + +--- + +## Bảng Tổng hợp Kết quả System Test + +| Scenario ID | Tên kịch bản | Yêu cầu | Kết quả kỳ vọng | Kết quả thực tế | Trạng thái | +|---|---|---|---|---|---| +| **ST-001** | Onboarding Cross-link với `override: false` | REQ-000002 Yêu cầu 1 & 2 | Chỉ điểm chính xác `docs/tasks/REQ-*` trong `docs/project_overview.md` | Hướng dẫn rõ ràng, logic nhất quán | **PASSED** | +| **ST-002** | Onboarding Cross-link với `override: true` | REQ-000002 Yêu cầu 1 & 2 | Chỉ điểm chính xác `//tasks/REQ-*` trong `docs/project_overview.md` | Hướng dẫn rõ ràng, đúng chuẩn Contract § 5.9 | **PASSED** | diff --git a/docs/tasks/REQ-000002-onboarding-crosslink/qa/uat-report.md b/docs/tasks/REQ-000002-onboarding-crosslink/qa/uat-report.md new file mode 100644 index 0000000..02698ac --- /dev/null +++ b/docs/tasks/REQ-000002-onboarding-crosslink/qa/uat-report.md @@ -0,0 +1,72 @@ +# Báo cáo Kiểm thử Chấp nhận Người dùng (User Acceptance Test Report) + +> Authoritative: **QA UAT Evidence** +> Package: `docs/tasks/REQ-000002-onboarding-crosslink/` +> Acceptance reference: `acceptance.md` (Mục 3 - Kết quả mong đợi) +> Task reference: `tasks.md` (TASK-001) + +## Metadata + +- **REQ ID**: REQ-000002 +- **Feature**: Bổ sung Cross-link vào docs/project_overview.md +- **Package Path**: `docs/tasks/REQ-000002-onboarding-crosslink/` +- **QA Engineer**: QA Automation Engineer +- **Thời gian thực hiện**: 2026-09-10T23:26:00+07:00 +- **Kết quả tổng thể UAT**: **PASSED** (2/2 scenarios đạt) + +--- + +## Mục tiêu Nghiệm thu Nghiệp vụ (Business Goals) + +Xác nhận từ góc nhìn của các tác tử AI và các kỹ sư phát triển (Developer) tham gia vào dự án: +1. **Dễ dàng định vị tài liệu đặc tả tính năng**: Khi bắt đầu tiếp cận một codebase mới, người đọc chỉ cần mở `docs/project_overview.md` là thấy ngay vị trí chứa các Spec Packages. +2. **Loại bỏ sự nhầm lẫn giữa cấu hình nội bộ và ngoài repo**: Người dùng không phải tìm kiếm thủ công file `spec_config.json` để biết các feature specs đang được lưu ở đâu. + +--- + +## Chi tiết Kịch bản Kiểm thử Chấp nhận Người dùng (UAT Scenarios) + +### UAT-001 — Trải nghiệm của Kỹ sư / AI Agent mới tham gia dự án (New Comer Experience) + +- **Vai trò người dùng (Actor)**: AI Agent (Claude/Gemini/Cursor) hoặc Lập trình viên mới +- **Yêu cầu liên kết**: REQ-000002 Yêu cầu 1 +- **Tiêu chí nghiệm thu**: Mục 3 - Kết quả mong đợi +- **Bối cảnh thực tế**: + - Dự án vừa được onboard bằng kỹ năng `/onboarding`. + - Một kỹ sư mới clone repo về máy hoặc một AI Agent bắt đầu một phiên làm việc mới, mở file `docs/project_overview.md` để nắm bắt bức tranh tổng quan kiến trúc và quy trình làm việc của dự án. +- **Hành vi thực tế**: + - Tại cuối tài liệu tổng quan, mục `13. Knowledge Base & Feature Specs` cung cấp thông tin trực diện: + - Nơi lưu trữ tài liệu đặc tả: `docs/tasks/REQ-*` (hoặc đường dẫn ngoài repo nếu dự án cấu hình tập trung). + - Hướng dẫn tra cứu các gói yêu cầu chức năng (Spec Packages) đã thực hiện và đang triển khai. + - Người dùng không mất thời gian dò tìm cấu trúc thư mục hay tự hỏi tài liệu nghiệp vụ nằm ở đâu. +- **Đánh giá giá trị**: + - Tăng tốc độ hòa nhập vào dự án (Onboarding time). + - Tăng độ tin cậy của tài liệu dự án sinh ra bởi 3A-Factory. +- **Kết luận UAT-001**: **PASSED**. + +--- + +### UAT-002 — Trải nghiệm vận hành trong tổ chức đa dự án với Enterprise Knowledge Base + +- **Vai trò người dùng (Actor)**: Platform Architect / Tech Lead +- **Yêu cầu liên kết**: REQ-000002 Yêu cầu 2 +- **Tiêu chí nghiệm thu**: Mục 3 - Kết quả mong đợi +- **Bối cảnh thực tế**: + - Tổ chức quản lý nhiều repo dịch vụ và kích hoạt lưu trữ Spec Package tập trung trong thư mục chia sẻ `C:\EnterpriseKB`. + - Tech Lead thực hiện onboarding cho một service mới trong tổ chức. +- **Hành vi thực tế**: + - Sau khi kết thúc onboarding, file `docs/project_overview.md` trong repo chỉ rõ: "Các tài liệu đặc tả tính năng được quản lý tập trung tại `C:\EnterpriseKB\\tasks\REQ-*`". + - Khi Developer kiểm tra repo mã nguồn, họ nắm được ngay việc các file spec không lưu trực tiếp trong repo mà được liên kết ra ngoài, tránh việc tạo nhầm thư mục `docs/tasks/` cục bộ gây phân mảnh tri thức. +- **Đánh giá giá trị**: + - Đảm bảo tính nhất quán tuyệt đối giữa tài liệu kiến trúc dự án và mô hình quản trị tri thức doanh nghiệp. + - Hạn chế tối đa sai sót thao tác của lập trình viên. +- **Kết luận UAT-002**: **PASSED**. + +--- + +## Bảng Tổng hợp Kết quả UAT + +| Scenario ID | Tên kịch bản | Đối tượng sử dụng | Mục tiêu nghiệp vụ | Đánh giá giá trị | Trạng thái | +|---|---|---|---|---|---| +| **UAT-001** | New Comer Experience | AI Agent / Developer mới | Định vị nhanh tài liệu tính năng qua `project_overview.md` | Giảm thời gian tìm kiếm, thông tin rõ ràng | **PASSED** | +| **UAT-002** | Enterprise Multi-repo Experience | Tech Lead / Platform Architect | Nhất quán đường dẫn Spec Package ngoài repo | Tránh tạo file nhầm vị trí, tri thức tập trung | **PASSED** | diff --git a/docs/tasks/REQ-000002-onboarding-crosslink/qa/unit-test-report.md b/docs/tasks/REQ-000002-onboarding-crosslink/qa/unit-test-report.md new file mode 100644 index 0000000..0524bc6 --- /dev/null +++ b/docs/tasks/REQ-000002-onboarding-crosslink/qa/unit-test-report.md @@ -0,0 +1,101 @@ +# Báo cáo Kiểm thử Đơn vị (Unit Test Report) + +> Authoritative: **QA Unit Test Evidence** +> Package: `docs/tasks/REQ-000002-onboarding-crosslink/` +> Acceptance reference: `acceptance.md` (AC-001, AC-002) +> Task reference: `tasks.md` (TASK-001) + +## Metadata + +- **REQ ID**: REQ-000002 +- **Feature**: Bổ sung Cross-link vào docs/project_overview.md +- **Package Path**: `docs/tasks/REQ-000002-onboarding-crosslink/` +- **QA Engineer**: QA Automation Engineer +- **Thời gian thực hiện**: 2026-09-10T23:25:00+07:00 +- **Kết quả tổng thể Unit Test**: **PASSED** (3/3 test cases đạt) + +--- + +## Tóm tắt Kết quả Unit Test + +| Test ID | Tên bài kiểm thử | Yêu cầu liên kết | Tiêu chí nghiệm thu | Task liên kết | Trạng thái | +|---|---|---|---|---|---| +| **UT-001** | Kiểm tra nội dung Phase D bổ sung mục 13 "Knowledge Base & Feature Specs" | REQ-000002 Yêu cầu 1 & 2 | AC-001 | TASK-001 | **PASSED** | +| **UT-002** | Kiểm tra tính toàn vẹn (Integrity) và cú pháp Markdown của `onboarding/SKILL.md` | REQ-000002 Ràng buộc 3 | AC-002 | TASK-001 | **PASSED** | +| **UT-003** | Kiểm thử xác thực tự động hệ thống qua script `validate-all.js` | REQ-000002 Ràng buộc 3 | AC-002 | TASK-001 | **PASSED** | + +--- + +## Chi tiết Kết quả Kiểm thử Đơn vị + +### UT-001 — Kiểm tra nội dung Phase D bổ sung mục 13 "Knowledge Base & Feature Specs" + +- **Mục tiêu**: Đảm bảo file `.agents/skills/onboarding/SKILL.md` tại mục `Phase D — Knowledge base docs/project_overview.md` đã có mục "13. Knowledge Base & Feature Specs" với hướng dẫn phân giải đường dẫn theo hợp đồng Spec Package § 5.9 (`spec_config.json`). +- **Cơ sở kiểm chứng**: + - File mã nguồn sửa đổi: [.agents/skills/onboarding/SKILL.md](file:///c:/Users/ADMIN/Documents/4_AI/1_Projects/3a-factory/.agents/skills/onboarding/SKILL.md#L147-L151) + - Git commit: `14d5f27` (`feat(REQ-000002): TASK-001 - Cap nhat onboarding SKILL.md voi muc Knowledge Base & Feature Specs`) + - Báo cáo Code Review: [TASK-001-code-review.md](file:///c:/Users/ADMIN/Documents/4_AI/1_Projects/3a-factory/docs/tasks/REQ-000002-onboarding-crosslink/reviews/TASK-001-code-review.md) +- **Các bước kiểm tra**: + 1. *Kiểm tra sự hiện diện của mục 13 trong cấu trúc tối thiểu Phase D*: + - Đoạn văn bản tại dòng 147–151: + ```markdown + 13. Knowledge Base & Feature Specs: + - Chỉ điểm rõ ràng nơi lưu trữ toàn bộ tài liệu chi tiết về tính năng (Spec Packages) của project này. + - Nếu `.agents/configs/spec_config.json` có `override: true` và đường dẫn hợp lệ: chỉ định đường dẫn ngoài repo là `//tasks/REQ-*` (theo hợp đồng § 5.9). + - Nếu `override: false` (mặc định): chỉ định đường dẫn nội bộ repo là `docs/tasks/REQ-*`. + ``` + - Cả hai trường hợp cấu hình `override: true` và `override: false` đều được chỉ dẫn rõ ràng, chính xác định dạng đường dẫn theo Contract § 5.9. + 2. *Kiểm tra Output checklist*: + - Dòng 179: + ```markdown + - [ ] `docs/project_overview.md` created/updated (**Vietnamese**, includes Knowledge Base & Feature Specs cross-link) + ``` + - Đã được cập nhật nhắc nhở tác tử tạo file `docs/project_overview.md` phải kèm theo cross-link. +- **Kết luận UT-001**: **PASSED**. + +--- + +### UT-002 — Kiểm tra tính toàn vẹn (Integrity) và cú pháp Markdown của `onboarding/SKILL.md` + +- **Mục tiêu**: Đảm bảo việc thêm mục 13 không làm ảnh hưởng hay xáo trộn các phần còn lại của file `.agents/skills/onboarding/SKILL.md`. Định dạng Markdown hợp lệ, không gãy cú pháp YAML frontmatter hay cấu trúc section. +- **Cơ sở kiểm chứng**: + - File: [.agents/skills/onboarding/SKILL.md](file:///c:/Users/ADMIN/Documents/4_AI/1_Projects/3a-factory/.agents/skills/onboarding/SKILL.md) +- **Các bước kiểm tra**: + 1. *Kiểm tra YAML Frontmatter*: + - Các trường `name: onboarding`, `description: ...`, `disable-model-invocation: true`, `argument-hint: ...` nguyên vẹn và đóng mở block `---` hợp lệ. + 2. *Kiểm tra các section nghiệp vụ*: + - `## Goal`: Giữ nguyên 4 mục. + - `## Agent detection`: Giữ nguyên bảng tra cứu tác tử (Claude, Gemini, Cursor). + - `## Hard scope`, `## When to use`: Giữ nguyên. + - `## Phase A — Gather context`: Bảng chủ đề và survey fact giữ nguyên. + - `## Phase B — Scaffold workflow in-repo`: 4 mục (bao gồm cấu hình `spec_config.json` project identifier) nguyên vẹn. + - `## Phase C — Agent context files`: Hướng dẫn `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `Cursor` nguyên vẹn. + - `## Phase D — Knowledge base docs/project_overview.md`: Mục 1-12 giữ nguyên số thứ tự và nội dung, mục 13 được thêm vào cuối danh sách cấu trúc tối thiểu một cách liền mạch. + - `## Phase E — User-facing summary (chat)`: 4 mục giữ nguyên. + - `## Output checklist`: 7 checklist items đầy đủ. + - `## Do not`: 3 điều cấm giữ nguyên. +- **Kết luận UT-002**: **PASSED**. + +--- + +### UT-003 — Kiểm thử xác thực tự động hệ thống qua script `validate-all.js` + +- **Mục tiêu**: Chạy bộ kiểm thử tự động toàn diện của dự án để xác nhận toàn bộ skills, schemas, manifests và template không vi phạm quy tắc đóng gói hoặc tính nhất quán. +- **Lệnh thực thi**: `node scripts/validation/validate-all.js` +- **Kết quả thực thi**: + ```text + [validate:manifest-schema] PASS MANIFEST_VALID + [validate:greenfield] PASS GREENFIELD_VALID + [validate:skills] PASS SKILL_VALIDATION_PASSED + [validate:templates] PASS TEMPLATE_VALIDATION_PASSED + [validate:governance] PASS GOVERNANCE_CONSISTENT + [validate:adapters] PASS ADAPTER_PARITY_PASSED + [validate:build-output] PASS BUILD_OUTPUT_VALID + [validate:state-flow] PASS STATE_FLOW_VALID + [validate:package-layout] PASS PACKAGE_LAYOUT_VALID + [validate] ALL_PASSED + ``` +- **Phân tích kết quả**: + - `[validate:skills] PASS SKILL_VALIDATION_PASSED`: File `.agents/skills/onboarding/SKILL.md` đã vượt qua bước kiểm tra cú pháp và cấu trúc skill tự động. + - Tất cả các bài kiểm thử khác đều PASS (Mã thoát 0). +- **Kết luận UT-003**: **PASSED**. diff --git a/docs/tasks/REQ-000002-onboarding-crosslink/raw.md b/docs/tasks/REQ-000002-onboarding-crosslink/raw.md new file mode 100644 index 0000000..d25dc78 --- /dev/null +++ b/docs/tasks/REQ-000002-onboarding-crosslink/raw.md @@ -0,0 +1,7 @@ +# RAW REQUIREMENT + +Tôi muốn Bổ sung Cross-link vào docs/project_overview.md cục bộ khi thực hiện onboarding projects. +Lý do: Một Developer hoặc Agent mới khi tải repo skycrm-api về sẽ chỉ thấy docs/project_overview.md mà không thấy các chức năng (REQ-*) nằm ở đâu. + +Giải pháp: Ta nên bổ sung một mục "Knowledge Base & Feature Specs" vào file docs/project_overview.md hiện tại. +Mục đích: Chỉ điểm rõ ràng: "Toàn bộ tài liệu chi tiết về tính năng (Spec Packages) của project này đang được lưu ở đâu (theo path trong spec_config hay nội bộ repo)" diff --git a/docs/tasks/REQ-000002-onboarding-crosslink/requirements.md b/docs/tasks/REQ-000002-onboarding-crosslink/requirements.md new file mode 100644 index 0000000..a0301ee --- /dev/null +++ b/docs/tasks/REQ-000002-onboarding-crosslink/requirements.md @@ -0,0 +1,12 @@ +# Requirements + +## 1. Yêu cầu nghiệp vụ +- Khi quá trình onboarding một dự án mới được thực hiện, file `docs/project_overview.md` được tạo ra cần chứa hướng dẫn hoặc đường dẫn tới nơi lưu trữ các đặc tả chức năng (Spec Packages). Điều này giúp Developer và Agent mới dễ dàng tìm thấy tài liệu. + +## 2. Yêu cầu kỹ thuật +- Chỉnh sửa file `.agents/skills/onboarding/SKILL.md`. +- Tại phần "Phase D — Knowledge base `docs/project_overview.md`", bổ sung hạng mục "13. Knowledge Base & Feature Specs" vào danh sách cấu trúc nội dung tối thiểu của file. +- Mô tả của hạng mục này cần chỉ ra việc cung cấp thông tin/đường dẫn đến nơi chứa Spec Packages dựa trên `spec_config.json` nếu có, hoặc ở vị trí mặc định của repo (thường là `docs/tasks/`). + +## 3. Ràng buộc +- Không làm thay đổi logic hoạt động hay cấu trúc hiện tại của file `SKILL.md` cũng như các Phase khác. diff --git a/docs/tasks/REQ-000002-onboarding-crosslink/reviews/TASK-001-code-review.md b/docs/tasks/REQ-000002-onboarding-crosslink/reviews/TASK-001-code-review.md new file mode 100644 index 0000000..daba718 --- /dev/null +++ b/docs/tasks/REQ-000002-onboarding-crosslink/reviews/TASK-001-code-review.md @@ -0,0 +1,90 @@ +# Code Review + +> When filled: write the body in **Vietnamese**. Keep severities/IDs in English. +> Path: `docs/tasks/REQ-000002-onboarding-crosslink/reviews/TASK-001-code-review.md` +> Review does **not** silently fix application code. + +## Metadata + +- REQ ID: REQ-000002 +- Package: docs/tasks/REQ-000002-onboarding-crosslink/ +- Task ID: TASK-001 +- Reviewer: Code Reviewer +- Reviewed at: 2026-09-10 + +## Review Result + +- Result: PASSED +- Blocking findings: 0 + +## Task Compliance + +- Task TASK-001 yêu cầu bổ sung mục `13. Knowledge Base & Feature Specs` vào danh sách `Minimum structure` của `Phase D — Knowledge base docs/project_overview.md` trong file `.agents/skills/onboarding/SKILL.md`. +- Hướng dẫn chỉ rõ nơi lưu trữ Spec Packages: + - Khi `.agents/configs/spec_config.json` có `override: true` và đường dẫn hợp lệ: chỉ định `//tasks/REQ-*`. + - Khi `override: false` (mặc định): chỉ định `docs/tasks/REQ-*`. +- Cập nhật mục kiểm tra trong Output checklist để bao gồm kiểm tra cross-link. +- Toàn bộ các yêu cầu của task đã được triển khai chính xác và đầy đủ. + +## Requirement Compliance + +| Requirement ID | Status | Notes | +|---|---|---| +| REQ-000002 Yêu cầu 1 | ok | Bổ sung mục 13 Knowledge Base & Feature Specs vào cấu trúc docs/project_overview.md | +| REQ-000002 Yêu cầu 2 | ok | Hướng dẫn chi tiết đường dẫn nội bộ `docs/tasks/REQ-*` và đường dẫn ngoài repo khi `spec_config.json` có `override: true` | + +## Design and ADR Compliance + +| Design / ADR ID | Status | Notes | +|---|---|---| +| REQ-000002 Design Section | ok | Cập nhật đúng vị trí tại Phase D và Output checklist trong `.agents/skills/onboarding/SKILL.md` | +| ADR_NOT_REQUIRED | ok | Thay đổi nội dung hướng dẫn cho skill onboarding, không ảnh hưởng kiến trúc | + +## Acceptance Coverage + +- **AC-001 (Kiểm tra nội dung Phase D)**: Đạt. Mục `13. Knowledge Base & Feature Specs` đã được thêm đầy đủ vào danh sách cấu trúc tối thiểu của `docs/project_overview.md` với đầy đủ hai trường hợp cấu hình `spec_config.json`. +- **AC-002 (Kiểm tra tính toàn vẹn)**: Đạt. Định dạng Markdown chuẩn xác, tất cả các Phase khác (A, B, C, E), rules và do-not clauses đều được giữ nguyên. + +## Scope Review + +- Expected File Scope honored: yes +- Unexplained out-of-scope files: none + +## Findings + +### BLOCKER + +Không có. + +### MAJOR + +Không có. + +### MINOR + +Không có. + +### WARNING + +Không có. + +## Test Review + +- Thay đổi tài liệu/hướng dẫn prompt Markdown, đã kiểm tra git diff và cú pháp hiển thị. Không yêu cầu test tự động. + +## Security Review + +- Không phát hiện lỗ hổng hay rủi ro bảo mật. Không chứa thông tin nhạy cảm. + +## Performance Review + +- Không ảnh hưởng tới hiệu năng hệ thống hay thời gian xử lý. + +## Final Decision + +- PASSED + +## Required Actions + +- Owner skill: project-manager +- Actions: Cập nhật `manifest.yaml` của package chuyển trạng thái task TASK-001 sang hoàn thành và tiếp tục quy trình SDLC. diff --git a/docs/tasks/REQ-000002-onboarding-crosslink/reviews/TASK-001-implementation.md b/docs/tasks/REQ-000002-onboarding-crosslink/reviews/TASK-001-implementation.md new file mode 100644 index 0000000..7fb7370 --- /dev/null +++ b/docs/tasks/REQ-000002-onboarding-crosslink/reviews/TASK-001-implementation.md @@ -0,0 +1,78 @@ +# Task Implementation Evidence + +> When filled: write the body in **Vietnamese**. Keep IDs in English. +> Path: `docs/tasks/REQ-000002-onboarding-crosslink/reviews/TASK-001-implementation.md` + +## Metadata + +- REQ ID: REQ-000002 +- Package: docs/tasks/REQ-000002-onboarding-crosslink/ +- Task ID: TASK-001 +- Author: developer +- Created at: 2026-09-10 +- Branch: feat/REQ-000002-onboarding-crosslink + +## Task + +- Title: Cập nhật onboarding SKILL.md với mục Knowledge Base & Feature Specs +- Objective: Cập nhật file `.agents/skills/onboarding/SKILL.md` tại mục `Phase D — Knowledge base docs/project_overview.md`, bổ sung mục "13. Knowledge Base & Feature Specs" vào danh sách cấu trúc tối thiểu của `docs/project_overview.md`. +- Status after handoff: review + +## Files Changed + +| Path | Change | Reason | +|---|---|---| +| .agents/skills/onboarding/SKILL.md | Modify | Bổ sung mục 13 Knowledge Base & Feature Specs vào Phase D và cập nhật checklist | + +## Implementation Summary + +- Đã bổ sung mục `13. Knowledge Base & Feature Specs` vào danh sách `Minimum structure` của `Phase D — Knowledge base docs/project_overview.md` trong `.agents/skills/onboarding/SKILL.md`. +- Nội dung mục 13 hướng dẫn chỉ điểm rõ ràng nơi lưu trữ Spec Packages: + - Nếu `.agents/configs/spec_config.json` có `override: true` và đường dẫn hợp lệ: chỉ định đường dẫn ngoài repo là `//tasks/REQ-*` (theo hợp đồng § 5.9). + - Nếu `override: false` (mặc định): chỉ định đường dẫn nội bộ repo là `docs/tasks/REQ-*`. +- Cập nhật mục kiểm tra trong `Output checklist` thành: `- [ ] docs/project_overview.md created/updated (Vietnamese, includes Knowledge Base & Feature Specs cross-link)`. + +## Requirement Coverage + +| Requirement ID | How addressed | +|---|---| +| REQ-000002 Yêu cầu 1 | Bổ sung mục 13 Knowledge Base & Feature Specs vào cấu trúc docs/project_overview.md | +| REQ-000002 Yêu cầu 2 | Hướng dẫn chi tiết đường dẫn nội bộ docs/tasks/REQ-* và đường dẫn ngoài repo khi spec_config.json có override | + +## Design Compliance + +| Design ID | Compliance notes | +|---|---| +| REQ-000002 Design Section | Tuân thủ chính xác vị trí chỉnh sửa trong file SKILL.md, không làm thay đổi các phần khác | + +## Acceptance Coverage + +| Acceptance / Test ID | Notes | +|---|---| +| AC-001 | Phase D trong SKILL.md đã có mục 13: Knowledge Base & Feature Specs | +| AC-002 | Toàn vẹn cấu trúc file SKILL.md, Markdown hợp lệ | + +## Verification Commands + +```text +# Kiểm tra cấu trúc file và markdown: +View and inspect .agents/skills/onboarding/SKILL.md lines 130-191 +``` + +## Verification Results + +- Result: Pass +- Evidence: Đã kiểm tra file `.agents/skills/onboarding/SKILL.md`, các section và frontmatter được giữ nguyên vẹn, nội dung mục 13 và checklist được cập nhật đầy đủ, chính xác. + +## Scope Deviations + +- None + +## Known Limitations + +- Không có. + +## Handoff to Review + +- Ready for `/review`: yes +- Notes for reviewer: Sẵn sàng cho bước Review code / tài liệu. diff --git a/docs/tasks/REQ-000002-onboarding-crosslink/spec-review.md b/docs/tasks/REQ-000002-onboarding-crosslink/spec-review.md new file mode 100644 index 0000000..a8e6c8a --- /dev/null +++ b/docs/tasks/REQ-000002-onboarding-crosslink/spec-review.md @@ -0,0 +1,11 @@ +# Spec Review + +## 1. Đánh giá chất lượng Spec Package +- [x] **Requirements**: Yêu cầu về mặt nghiệp vụ và kỹ thuật được định nghĩa đầy đủ. Mục tiêu cải thiện Developer/Agent Experience được giải thích hợp lý. +- [x] **Design**: Không cần ADR do độ rủi ro thấp. File target được xác định chính xác và hướng dẫn cập nhật được quy định rõ. +- [x] **Tasks**: Công việc được chia nhỏ thành 1 task rõ ràng, không có dependencies phức tạp. +- [x] **Acceptance**: Đã có tiêu chí nghiệm thu rõ ràng thông qua kiểm tra file và tính toàn vẹn của cấu trúc markdown. + +## 2. Final Decision +- **Quyết định**: PASSED +- **Nhận xét**: Gói đặc tả (Spec Package) này đơn giản, đầy đủ và sẵn sàng để chờ phê duyệt chuyển sang giai đoạn phát triển (Develop). diff --git a/docs/tasks/REQ-000002-onboarding-crosslink/tasks.md b/docs/tasks/REQ-000002-onboarding-crosslink/tasks.md new file mode 100644 index 0000000..5af19b5 --- /dev/null +++ b/docs/tasks/REQ-000002-onboarding-crosslink/tasks.md @@ -0,0 +1,73 @@ +# Tasks: Bổ sung Cross-link vào docs/project_overview.md + +> Authoritative: **Execution Truth** +> Contract: `.agents/contracts/spec-package.md` + +## Metadata + +- REQ ID: REQ-000002 +- Feature: Bổ sung Cross-link vào docs/project_overview.md +- Package: `docs/tasks/REQ-000002-onboarding-crosslink/` +- Status: ready +- Last updated: 2026-09-10 + +## Execution Rules + +- Chỉ thực hiện current task (`manifest.execution.current_task`). +- Không bỏ qua dependency. +- Không mở rộng file scope khi chưa cập nhật task. +- Không tự thay đổi requirement hoặc design. + +## Dependency Graph + +```text +TASK-001 (Cập nhật onboarding SKILL.md với mục Knowledge Base & Feature Specs) +``` + +## Tasks + +### TASK-001 — Cập nhật onboarding SKILL.md với mục Knowledge Base & Feature Specs + +- Status: done +- Priority: must +- Owner: developer +- Risk: low + +#### Objective +Cập nhật file `.agents/skills/onboarding/SKILL.md` tại mục `Phase D — Knowledge base docs/project_overview.md`, bổ sung mục "13. Knowledge Base & Feature Specs" vào danh sách cấu trúc tối thiểu của `docs/project_overview.md`. Cung cấp chỉ dẫn rõ ràng: chỉ điểm vị trí lưu trữ toàn bộ tài liệu chi tiết về tính năng (Spec Packages) của project (theo cấu hình `spec_config.json` nếu có override, hoặc mặc định `docs/tasks/` trong repo). + +#### Requirement References +- REQ-000002 Yêu cầu 1 & 2 + +#### Design References +- REQ-000002 Design Section + +#### Acceptance References +- AC-001, AC-002 + +#### Dependencies +- None + +#### Expected File Scope +- `.agents/skills/onboarding/SKILL.md` + +#### Implementation Notes +- Mở file `.agents/skills/onboarding/SKILL.md`. +- Tại phần `Phase D — Knowledge base docs/project_overview.md`: + Trong danh sách `Minimum structure (keep short for small repos):`, thêm: + `13. Knowledge Base & Feature Specs (chỉ rõ vị trí Spec Packages lưu tại //tasks/REQ-* nếu spec_config.json có override: true, hoặc docs/tasks/REQ-* nếu override: false)` +- Đảm bảo giữ nguyên các phần còn lại của file. + +#### Verification +- Đọc lại `.agents/skills/onboarding/SKILL.md` để xác nhận markdown hợp lệ và cấu trúc rõ ràng. + +#### Definition of Done +- `Phase D` của `.agents/skills/onboarding/SKILL.md` có mục 13: "Knowledge Base & Feature Specs". + +--- + +## Execution Summary + +| Task | Status | Dependencies | Requirements | Acceptance | +|---|---|---|---|---| +| TASK-001 | done | None | Yêu cầu 1 & 2 | AC-001, AC-002 | diff --git a/package-lock.json b/package-lock.json index af27fcc..d90d3cd 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "3a-factory", - "version": "4.2.0", + "version": "4.2.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "3a-factory", - "version": "4.2.0", + "version": "4.2.1", "hasInstallScript": true, "license": "MIT", "bin": { diff --git a/package.json b/package.json index de87e04..488adc3 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "3a-factory", - "version": "4.2.0", + "version": "4.2.1", "description": "Enterprise Feature-local Spec Package workflow for Claude, Gemini, and Cursor (3A-Factory)", "repository": { "type": "git", diff --git a/release-notes/4.2.1.md b/release-notes/4.2.1.md new file mode 100644 index 0000000..60e6336 --- /dev/null +++ b/release-notes/4.2.1.md @@ -0,0 +1,95 @@ +# Release Notes: 4.2.1 (Onboarding Knowledge Base Cross-linking) + +**Release Date:** 2026-09-10 +**Version:** 4.2.1 + +Phiên bản 4.2.1 là bản cập nhật tiếp nối và hoàn thiện trải nghiệm kho tri thức được khởi xướng từ bản 4.2.0. Trọng tâm của phiên bản này là **Onboarding Knowledge Base Cross-linking**: bổ sung chỉ dẫn liên kết chéo "Knowledge Base & Feature Specs" vào tài liệu tổng quan repository (`docs/project_overview.md`) khi thực hiện quy trình onboarding, giúp các kỹ sư và AI Agent mới tiếp cận repository có thể ngay lập tức định vị toàn bộ tài liệu đặc tả tính năng (Spec Packages) của dự án. + +--- + +## 1. Tổng quan phiên bản (Overview) + +Trong phiên bản 4.2.0, 3A-Factory đã bổ sung cơ chế kho tri thức tập trung (`spec_config.json`), cho phép lưu trữ tài liệu đặc tả tính năng tại thư mục ngoài repo (`//tasks/REQ-*`) hoặc giữ nguyên trong repo (`docs/tasks/REQ-*`). + +Tuy nhiên, tài liệu tổng quan dự án sinh ra bởi kỹ năng onboarding (`docs/project_overview.md`) chưa có mục chỉ định rõ ràng cho độc giả (con người lẫn tác tử AI mới) biết được các Spec Packages của repository này đang được quản lý và lưu trữ ở đâu. + +Phiên bản 4.2.1 bổ sung: +- Chuẩn hóa mục số `13. Knowledge Base & Feature Specs` vào cấu trúc tối thiểu của `docs/project_overview.md` trong quy trình Onboarding (Phase D). +- Hướng dẫn chỉ rõ vị trí lưu trữ Spec Packages dựa trên trạng thái cấu hình của `.agents/configs/spec_config.json`. +- Cập nhật checklist nghiệm thu Onboarding tại Phase E (`Output checklist`). + +--- + +## 2. Bối cảnh & Vấn đề cần giải quyết (Problem Statement) + +Khi một AI Agent mới (hoặc lập trình viên / kiểm thử viên mới) được đưa vào làm việc trên một repository: +1. **Thiếu điểm liên kết tri thức (Missing Knowledge Link)**: File `docs/project_overview.md` là tài liệu đầu tiên được đọc để nắm bắt bức tranh tổng quan của repository. Nếu không có chỉ dẫn rõ ràng về nơi chứa các Spec Packages, Agent hoặc Developer mới sẽ phải tìm kiếm thủ công hoặc có thể hiểu nhầm rằng repository chưa có bất kỳ đặc tả tính năng nào. +2. **Nguy cơ nhầm lẫn giữa Local và Centralized Knowledge Base**: Kể từ bản 4.2.0, tài liệu đặc tả tính năng có thể nằm tại `docs/tasks/REQ-*` (local) hoặc tại một đường dẫn ngoài repository `//tasks/REQ-*` (centralized KB). Nếu không có ghi chú rõ ràng trong `project_overview.md`, Agent có thể kiểm tra thư mục `docs/tasks/` thấy trống và kết luận sai lệch về tình trạng tài liệu dự án. +3. **Mất liên tục trong bối cảnh phân tán**: Trong các tổ chức lớn với nhiều repository vệ tinh kết nối về một Knowledge Base chung, việc ghi nhận trực tiếp liên kết chéo vào tài liệu tổng quan repo là cầu nối thiết yếu để bảo đảm tính liền mạch của quy trình SDLC. + +--- + +## 3. Giải pháp chi tiết (The Solution) + +### 3.1. Bổ sung mục 13 vào cấu trúc tối thiểu trong Phase D (`SKILL.md`) + +Trong `.agents/skills/onboarding/SKILL.md`, Phase D (Knowledge base `docs/project_overview.md`) được bổ sung mục bắt buộc: + +```markdown +13. Knowledge Base & Feature Specs: + - Chỉ điểm rõ ràng nơi lưu trữ toàn bộ tài liệu chi tiết về tính năng (Spec Packages) của project này. + - Nếu `.agents/configs/spec_config.json` có `override: true` và đường dẫn hợp lệ: chỉ định đường dẫn ngoài repo là `//tasks/REQ-*` (theo hợp đồng § 5.9). + - Nếu `override: false` (mặc định): chỉ định đường dẫn nội bộ repo là `docs/tasks/REQ-*`. +``` + +### 3.2. Cập nhật Phase E / Output Checklist + +Checklist hoàn tất quy trình Onboarding được cập nhật để bảo đảm mục liên kết chéo luôn được nghiệm thu đầy đủ: + +- `docs/project_overview.md` created/updated (**Vietnamese**, includes Knowledge Base & Feature Specs cross-link) + +--- + +## 4. Hiệp đồng với cơ chế Override của 4.2.0 (Synergy with 4.2.0) + +Phiên bản 4.2.1 phối hợp chặt chẽ với cơ chế phân giải đường dẫn của Hợp đồng § 5.9: +- Khi `override: false` (chế độ mặc định), mục 13 trong `project_overview.md` sẽ hướng người đọc tới thư mục nội bộ `docs/tasks/REQ-*`. +- Khi `override: true`, quy trình Onboarding đọc `path` và `project` từ `.agents/configs/spec_config.json` để ghi lại chính xác đường dẫn tuyệt đối hoặc tương đối tới kho tri thức tập trung: `//tasks/REQ-*`. +- Điều này tạo nên sự đồng bộ hoàn hảo: **Cấu hình máy đọc (`spec_config.json`) song hành cùng Tài liệu người đọc (`docs/project_overview.md`)**. + +--- + +## 5. Tương thích ngược (Backward Compatibility) + +- **100% Non-breaking**: Thay đổi hoàn toàn mang tính bổ sung hướng dẫn tài liệu (documentation & prompt guidance) cho kỹ năng `onboarding`. +- Không ảnh hưởng tới cấu trúc dữ liệu của các Spec Package hiện tại. +- Không yêu cầu thay đổi cú pháp hay migration trên bất kỳ file cấu hình nào. +- Các dự án đã onboarding trước đây vẫn hoạt động bình thường; khi chạy lại `/onboarding`, mục 13 sẽ được bổ sung vào `docs/project_overview.md`. + +--- + +## 6. Kiểm thử & Đảm bảo chất lượng (Verification & QA) + +Phiên bản 4.2.1 đã trải qua toàn bộ chuỗi kiểm thử và thẩm định nghiêm ngặt của 3A-Factory: +- **Build test (`scripts/build.js`)**: Bản phân phối `dist/install.js` được biên dịch đồng bộ từ source. +- **Node.js Test Runner**: + - `tests/build.test.js`: Kiểm tra tính toàn vẹn của artifacts sau khi build. + - `tests/greenfield.test.js`: Đảm bảo quy trình khởi tạo dự án trắng hoạt động chính xác. + - `tests/installer.test.js`: Đảm bảo bộ cài đặt scaffold đầy đủ các file và cấu hình. + - `tests/workflow.test.js`: Đảm bảo toàn bộ luồng SDLC pipeline hoạt động trơn tru. +- **Validation suite (`scripts/validation/validate-all.js`)**: + - `validate-skills.js`: 100% kỹ năng hợp lệ về metadata, schema và cú pháp. + - `validate-templates.js`: Toàn bộ template hợp lệ. + - `validate-contracts.js`: Hợp đồng chuẩn khớp với các quy định điều phối. + +--- + +## 7. Hướng dẫn nâng cấp (Upgrade Instructions) + +Để cập nhật pipeline lên phiên bản 4.2.1: + +```bash +npx 3a-factory@4.2.1 --agent= --force +``` + +*(Thay `` bằng `claude`, `gemini`, hoặc `cursor`)* diff --git a/tests/installer.test.js b/tests/installer.test.js index aa7cfee..374c9ff 100644 --- a/tests/installer.test.js +++ b/tests/installer.test.js @@ -112,7 +112,7 @@ describe('installer smoke', () => { assert.match(pmRule, /MANDATORY PM MODE/); assert.match(pmRule, /Slash invocation \(mandatory\)/); const shared = fs.readFileSync(path.join(tmp, '.agents/skills/triage/SKILL.md'), 'utf8'); - assert.match(shared, /^---\nname: triage\n/); + assert.match(shared, /^---\r?\nname: triage\r?\n/); assert.match(shared, /argument-hint:/); const pmSkill = fs.readFileSync(path.join(tmp, '.agents/skills/project-manager/SKILL.md'), 'utf8'); assert.match(pmSkill, /AUTO-ACTIVATE/);