@manhd_d/ai-harness 0.7.0 → 0.9.0

package/docs/getting-started.md

@@ -1,110 +1,78 @@
 # Bắt đầu với AI Harness
 
-**Cài một lần → ghi context dự án → giao việc cho AI → kiểm tra kết quả.**
-
-Cần Node.js **22+**, Git và một repository ứng dụng đã tồn tại. AI IDE/assistant phải đọc được file trong repository; cách tự nạp `AGENTS.md` và skills phụ thuộc AI host. CLI `aih` quản lý hướng dẫn, không chạy LLM hay tạo ứng dụng.
+**Cài vào project → mở AI → giao việc → review kết quả.** Cần Node.js **22+** và một thư mục project. Với dự án mới, tạo thư mục/repository trước; Harness không tạo ứng dụng hay chạy model.
 
 ## 1. Cài vào project
 
+Chạy tại thư mục gốc của project:
+
 ```bash
-npm install -g @manhd_d/ai-harness
-cd /path/to/existing-project
-aih init --adapters java-spring
-aih check
+npx --yes @manhd_d/ai-harness init --detect
 ```
 
-Chọn module theo nhu cầu, không cần cài cả bộ:
+Lệnh nhận diện stack từ file ở thư mục gốc và cài hướng dẫn tương ứng. Nếu báo chưa nhận diện được, thay `--detect` theo bảng; bỏ `--detect` để chỉ cài quy tắc chung (Core):
 
-| Nhu cầu | Tham số cho `aih init` |
+| Project / nhu cầu | Tham số cho `init` |
 | --- | --- |
-| Spring Boot API | `--adapters java-spring` |
-| React/Next.js + UI | `--adapters react-nextjs --capabilities uiux` |
-| Astro tool nhỏ | `--adapters astro` |
-| Website có quảng cáo | `--adapters astro --capabilities monetization` |
-| Viết tài liệu từ ý tưởng hoặc tài liệu BA | `--capabilities product` |
-| Spring + tài liệu + Kubernetes | `--adapters java-spring,kubernetes --capabilities product,devops` |
-
-`aih list` xem toàn bộ module. `aih init --dry-run` xem trước thay đổi với cùng tham số đã chọn. Với project đã cài, đổi module trong `.harness/project.json` rồi dùng `aih update`, không chạy lại `init` với lựa chọn khác.
+| Spring Boot | `--adapters java-spring` |
+| React / Next.js | `--adapters react-nextjs` |
+| React Native / Expo | `--adapters react-native` |
+| Python AI / RAG | `--adapters ai-python` |
+| Astro tool / website | `--adapters astro` |
+| Spring + Next.js | `--adapters java-spring,react-nextjs` |
+| Viết tài liệu BA | `--capabilities product` |
 
-## 2. Ghi context và bắt đầu giao việc
+Ví dụ vừa code Spring vừa viết tài liệu:
 
-Chạy `aih setup` rồi nhờ AI đọc workflow `project-setup`. Đây là gợi ý cho AI host, không phải wizard
-nhập liệu của CLI. AI đọc repo trước, chỉ hỏi 1–3 câu A/B/C cho điểm còn thiếu, có đề xuất và lý do.
-Không cần xác nhận lại thông tin hoặc quyền triển khai đã có.
-
-Điền `.harness/local.md` bằng thông tin thực của project:
+```bash
+npx --yes @manhd_d/ai-harness init --adapters java-spring --capabilities product
+```
 
-- Mục tiêu, phạm vi và quy tắc nghiệp vụ quan trọng.
-- Stack/phiên bản, database, cấu trúc service/module.
-- Lệnh build/test đã xác nhận chạy được.
-- Đường dẫn tài liệu BA, conventions và những ràng buộc cần giữ.
+Thêm `--capabilities uiux` khi cần UI/UX; `monetization` cho website có quảng cáo. [Danh mục đầy đủ](cli.md).
+Với project đã cài, đổi lựa chọn trong `.harness/project.json` rồi dùng `update`.
 
-Mở project trong AI IDE và giao yêu cầu, ví dụ:
+## 2. Mở AI và giao việc
 
-> Đọc AGENTS.md và .harness/local.md, chỉ nạp skill liên quan. Thêm API tìm kiếm khách hàng theo yêu cầu này: … Làm rõ điểm chưa chắc chắn, đề xuất acceptance scenarios; sau khi thống nhất scope, triển khai, chạy test phù hợp và báo cáo kết quả thực chạy.
+Mở thư mục project trong công cụ AI, rồi gửi:
 
-Bạn không cần gọi từng role/skill thủ công. Nếu host không tự phát hiện hướng dẫn, yêu cầu assistant đọc các đường dẫn trên. `aih skills` xem danh sách; `aih skill <tên>` đọc một skill khi cần.
+> Đọc AGENTS.md và .harness/local.md. Khảo sát code, tài liệu và lệnh test hiện có;
+> ghi context còn thiếu vào .harness/local.md, chỉ hỏi phần chưa rõ.
+> Thực hiện yêu cầu: [mô tả công việc]. Chạy test phù hợp, báo cáo kết quả và phần chưa kiểm chứng.
 
-Review diff và kết quả test, rồi commit `AGENTS.md`, `.harness/`, `.agents/skills/` và tài liệu thay đổi cùng project. Sửa quy tắc riêng trong `.harness/local.md`; giữ nguyên snapshot do Harness quản lý.
+Bạn có thể giao ý tưởng, tài liệu BA hoặc task code. Không cần gọi từng agent/skill.
+Với web/mobile, giao màn hình hoặc tính năng theo common/API/state/navigation hiện có; [skills đã có](frontend-mobile.md).
+Nếu công cụ chưa tự nạp hướng dẫn, xem [cách cấu hình công cụ AI](tool-setup/README.md).
+Lệnh `setup` chỉ xuất gợi ý thiết lập, không phải bước bắt buộc để bắt đầu.
 
-Lệnh/tool chung thuộc `.harness/environment.json`; đường dẫn máy riêng thuộc file ignored
-`.harness/machine.json`. `aih doctor` kiểm tra tham chiếu biến và sự hiện diện công cụ, không chạy chúng.
-Xem [cấu hình Maven nội bộ](project-configuration.md).
+Review diff và test, rồi commit `AGENTS.md`, `.harness/`, `.agents/skills/` cùng code.
+Quy tắc riêng sửa trong `.harness/local.md`; giữ nguyên file do Harness quản lý.
+Lệnh/tool chung lưu trong `.harness/environment.json`; đường dẫn riêng máy trong `.harness/machine.json` được Git ignore. [Cấu hình Maven/JDK](project-configuration.md).
+Cấu hình model là tùy chọn trong `.harness/agents.json`; chọn model tương thích với công cụ AI: [hướng dẫn](agent-configuration.md).
 
-## 3. Tài liệu và spec khi cần
+## 3. Thêm tài liệu khi cần
 
-Với capability `product`:
+Với `product` đã cài, tạo bản nháp yêu cầu:
 
 ```bash
-aih new-doc prd-lite
+npx --yes @manhd_d/ai-harness new-doc prd-lite
 ```
 
-Lệnh tạo template `docs/product/prd-lite.md`; bạn và AI điền nội dung, nguồn và acceptance criteria. Chọn [Idea-driven](examples/idea-driven-project.md) nếu bắt đầu từ ý tưởng; chọn [Document-driven](examples/document-driven-project.md) nếu đã có tài liệu BA/Confluence.
-
-Khi một tính năng cần proposal/design/tasks/spec riêng:
+Tính năng cần spec riêng: dùng `new-change <id>`; [hướng dẫn spec](change-readiness.md).
+Task nhỏ không cần bộ tài liệu đầy đủ. Không cần cài OpenSpec CLI để tạo bản nháp.
 
-```bash
-aih new-change add-customer-search
-```
+## 4. Kiểm tra và cập nhật
 
-Đây là bản nháp trong `openspec/changes/add-customer-search/`, chưa phải spec được duyệt.
-AI ghi câu trả lời thực tế trong `decisions.json`; kiểm tra bằng `aih ready add-customer-search --stage implement`.
-Sau code, ghi bằng chứng trong `verification.json` và chạy với `--stage review`. Xem [Change readiness](change-readiness.md). Sửa nhỏ, ít rủi ro có thể bỏ qua full spec với lý do rõ ràng; không bắt mọi task tạo đủ BRD/PRD/SRS.
+`check` kiểm tra file Harness; `verify` xuất checklist. Code cần **test của project** và review thực tế.
 
-`aih new-change` không cần OpenSpec CLI. Chỉ cài OpenSpec riêng khi cần validator/archive của công cụ đó; xem [OpenSpec](openspec.md).
-
-## 4. Kiểm tra đúng thứ
-
-| Lệnh | Ý nghĩa |
-| --- | --- |
-| `aih check` | Kiểm tra integrity của file Harness; không kiểm thử ứng dụng |
-| `aih doctor` | Kiểm tra công cụ và environment đã cấu hình; không chạy build/test |
-| `aih verify --scope all` | Xuất checklist, `executed: false`; không chạy build/test |
-| `aih eval --scope all` | Xuất tình huống và báo cáo chưa chấm; không gọi model |
-| Lệnh test của project | Do bạn, AI host hoặc CI thực chạy để xác minh code |
-
-Một lần `aih check` thành công không có nghĩa tính năng đã đúng. Ghi lệnh test thực chạy, kết quả và phần chưa kiểm chứng trong PR. Xem [đánh giá hành vi AI](../evals/README.md) nếu muốn đo hiệu quả Harness.
-
-## 5. Cập nhật: CLI trước, project sau
-
-Trên branch riêng, commit trạng thái hiện tại trước. Với cách cài global ở trên:
+Trước cập nhật, tạo branch và commit trạng thái hiện tại. Xem trước, áp dụng rồi kiểm tra:
 
 ```bash
-npm install -g @manhd_d/ai-harness@latest
-aih --version
-aih check
-aih update --dry-run
-aih update
-aih check
+npx --yes @manhd_d/ai-harness@latest update --dry-run
+npx --yes @manhd_d/ai-harness@latest update
+npx --yes @manhd_d/ai-harness@latest check
 ```
 
-`aih --version` là phiên bản CLI; `aih check` trả phiên bản snapshot trong project. `aih update` lấy bundle từ CLI đang cài (hoặc `--source`), **không tự tải npm**. Review diff, chạy test ứng dụng và commit snapshot/lock cùng nhau. Nếu báo drift, giữ lại thay đổi trong Git, chuyển tùy chỉnh sang `.harness/local.md` và khôi phục managed files trước khi update.
-
-Nếu cài local trong project, dùng `npm install --save-dev @manhd_d/ai-harness@latest` và `npx aih` thay cho `aih`.
-
-## Đọc thêm theo nhu cầu
+Review diff và chạy test project trước khi commit. Nếu có conflict, xem [cách xử lý](cli.md).
+Dùng thường xuyên có thể cài global: `npm install -g @manhd_d/ai-harness`, rồi dùng `aih` thay cho `npx --yes @manhd_d/ai-harness`. Nâng CLI global trước khi `aih update`.
 
-- [CLI reference](cli.md) · [Full SDLC](end-to-end-workflow.md) · [Skill matrix](skill-matrix.md) · [Agent handoffs](agent-handoffs.md).
-- [Spring Boot API](examples/spring-boot-api.md) · [Full-stack](examples/fullstack-web.md) · [React Native](examples/react-native-app.md) · [Python AI/RAG](examples/ai-rag-service.md).
-- [Astro micro-tools](examples/astro-micro-tools.md) · [Astro + AdSense](examples/astro-adsense-microtools.md).
-- [Release guide](npm-release.md): dành cho maintainer; merge source không đồng nghĩa npm đã có bản mới.
+[Tra cứu & ví dụ theo nhu cầu](README.md).

package/docs/harness-maintenance.md

@@ -0,0 +1,80 @@
+# Nâng cấp AI Harness không bỏ sót thành phần
+
+Đây là đầu mối dành cho người và AI sửa **repository AI Harness**, không phải quy trình phát triển
+ứng dụng của consumer. Đọc tài liệu này trước khi sửa Harness. Giữ thông tin chuyên biệt ở tài liệu
+gốc được liên kết bên dưới; không sao chép quy tắc thành nhiều bản có thể mâu thuẫn.
+
+## Bản đồ trách nhiệm và liên kết
+
+| Thành phần | Nguồn chính | Nơi được sử dụng / kiểm chứng |
+| --- | --- | --- |
+| Core | [Rules](../core/rules/), [policies](../core/policies/) | [AGENTS template](../templates/AGENTS.md) → [workflows](../core/workflows/) → [roles](../core/agents/), [skills](../core/skills/) → [checks](../core/checks/verification.json), [evals](../core/evals/cases.json) |
+| Adapter | [Registry](../harness.yaml), [adapter contract](adapters.md), [adapter assets](../adapters/) | Manifest `rules/skills/verification/evaluation` → [bundle/install](../cli/harness.js) → [installed verify/eval](../cli/adapters.js) |
+| Capability / skill | [Capability assets](../capabilities/), [schema/loader](../cli/capabilities.js) | Workflow/role bàn giao → exposed skill → [skill matrix](skill-matrix.md), [handoffs](agent-handoffs.md), [composition evals](../core/evals/composition.json) |
+| CLI / config | [CLI reference](cli.md), [implementation](../cli/), [templates](../templates/) | [Architecture/ownership](architecture.md), [project configuration](project-configuration.md), [tests](../tests/), [package smoke](../scripts/smoke-package.js) |
+| Agent preferences | [Canonical default](../config/agents.default.json), [configuration contract](agent-configuration.md) | Project-owned `agents.json` → read-only setup plan → [routing workflow](../core/workflows/agent-routing.md) → [host setup](tool-setup/README.md); tests verify preservation, not live model availability |
+| Quy trình sử dụng | [Getting started](getting-started.md), [full SDLC](end-to-end-workflow.md) | [Examples](examples/), [README](../README.md), [documentation workflows](documentation-workflows.md) |
+| Release / migration | [Versioning](versioning.md), [release policy](release-policy.md) | [Changelog](../CHANGELOG.md), [npm release](npm-release.md), [release workflow](../.github/workflows/npm-publish.yml) |
+
+Một quy tắc chỉ hoàn chỉnh khi xác định được: **nơi khai báo → nơi đóng gói → điểm AI đọc → bước áp dụng
+→ cách review/kiểm chứng → hướng dẫn sử dụng**. Thành phần không áp dụng bước nào phải ghi rõ lý do;
+không tạo thêm file chỉ để đủ hình thức.
+
+## Quy trình cho mỗi lần nâng cấp
+
+1. Xác nhận Git root, base commit và đọc [AGENTS](../AGENTS.md), kiến trúc, quy định versioning cùng
+   thay đổi liên quan. Khảo sát implementation và test tương tự trước khi thiết kế mới.
+2. Với thay đổi có ý nghĩa về hành vi/chính sách, tạo OpenSpec proposal/design/tasks/specs theo
+   [quy trình hiện có](../core/workflows/spec-to-code.md). Ghi phân tích ảnh hưởng vào `design.md`
+   hoặc sao chép [mẫu impact](templates/harness-change-impact.md) vào change. Sửa typo/đường dẫn nhỏ
+   có thể ghi ngay trong PR; không bắt một bộ OpenSpec đầy đủ.
+3. Duyệt từng hàng của ma trận bên dưới. Ban đầu dùng `pending` cho mục cần sửa; khi hoàn tất chuyển
+   `done` kèm đường dẫn/bằng chứng. `not-applicable` cần lý do cụ thể. Không bỏ trống hàng và không coi
+   “đã nghĩ đến” là “đã cập nhật”. Hỏi lại chỉ khi có lựa chọn quan trọng chưa được quyết định.
+4. Triển khai theo phạm vi; đồng bộ nơi khai báo, đường dẫn consumer sau cài đặt, nơi gọi và tài liệu.
+   Khi đổi tên/xóa, tìm mọi tham chiếu cũ và xem xét snapshot cũ, không chỉ source mới.
+5. Chạy các kiểm tra bắt buộc, kiểm tra diff cài mới/update khi payload hoặc ownership thay đổi,
+   và ghi kết quả thực tế. Báo riêng kiểm tra bị chặn, kết quả manual và live-agent eval chưa chạy.
+6. Điền [PR template](../.github/pull_request_template.md), liên kết impact/OpenSpec và evidence.
+   Còn `pending` thì nêu rõ và dùng draft nếu phần triển khai chưa xong; không báo hoàn tất.
+7. Human review/merge; [Release Please](release-policy.md) quản lý version phân phối và PR phát hành
+   riêng. Không auto-merge, tự tag hoặc publish từ feature PR. Archive chỉ sau khi PR liên quan đã merge.
+
+## Ma trận ảnh hưởng bắt buộc rà soát
+
+Mỗi lần nâng cấp rà soát **tất cả hàng**, nhưng chỉ sửa phần bị ảnh hưởng. Một thay đổi có thể chạm
+nhiều nhóm. Liên kết evidence vào impact record thay vì chép lại cùng nội dung trong PR.
+
+| ID | Khi có thay đổi | Những nơi phải đối chiếu |
+| --- | --- | --- |
+| core | Rule/policy dùng chung | Điểm đọc trong AGENTS template, workflow/role/skill liên quan, precedence, checks và behavioral evals |
+| adapter | Adapter / convention | Registry, adapter manifest và schema; rules index; skills; checks/evals; detection nếu liên quan; module_version khi contract đổi |
+| capability-skill | Capability hoặc skill | Manifest, input/output/constraints, workflow kích hoạt, bàn giao, đường dẫn installed/exposed, skill matrix và composition |
+| cli-config | CLI, config, template | Validation, help/reference, project-owned vs managed files, install/update/dry-run/conflict, tương thích snapshot cũ, migration và package allowlist |
+| workflow | Quy trình / bàn giao | Điều kiện vào, output, owner/bước nhận tiếp, role/skill, acceptance/readiness, SDLC/examples liên quan |
+| documentation | Hướng dẫn sử dụng | README/getting-started, tài liệu chuyên biệt và đường dẫn; không quảng cáo khả năng chưa có hoặc kết quả chưa đo |
+| verification | Kiểm chứng | Tests đúng rủi ro, validate, package smoke, CI matrix; eval scenarios khi hướng dẫn hành vi đổi; actual logs/manual limitations |
+| release-migration | Phát hành / tương thích | Changelog Unreleased, migration/rollback khi cần, module contract version; version phân phối chỉ do release PR quản lý |
+
+Ví dụ thêm convention Java: manifest khai báo `rules/conventions.md` → bundle cài file vào
+`.harness/adapters/java-spring/` → rules index dẫn AI đọc → Core code/review áp dụng → checklist/eval
+kiểm tra → guide hướng dẫn. Nếu chỉ có file convention mà thiếu đường đọc, thay đổi chưa đầy đủ.
+
+## Điều kiện hoàn thành và giới hạn tự động hóa
+
+- Chạy `npm test`, `npm run validate`, `npm run test:package`. CI chạy các gate theo
+  [Harness CI](../.github/workflows/harness.yml); khi liên quan release chạy cả `npm run check:release`.
+- Tests về [maintenance links](../tests/maintenance.test.js) kiểm tra các điểm vào tài liệu, đường đọc
+  Core và rule index của mọi adapter được đăng ký. Các [documentation tests](../tests/documentation.test.js)
+  kiểm tra skill matrix/handoffs; validate kiểm tra đường dẫn Markdown; package smoke dùng tarball thật.
+- Khi đổi payload: xác minh asset được chọn/không được chọn, lock và conflict, project-owned content
+  không bị ghi đè, đường dẫn exposed skill hợp lệ. Dùng test hiện có và chỉ thêm test cho rủi ro mới.
+- Khi đổi instructions: cập nhật kịch bản [behavioral evaluation](../evals/README.md) nếu hành vi kỳ vọng
+  thay đổi; giữ unscored nếu chưa chạy host thật. Passing CLI tests không chứng minh AI tuân thủ.
+- CI kiểm tra cấu trúc và liên kết đã khai báo, **không tự kết luận impact analysis đầy đủ hoặc các tài
+  liệu nhất quán về nghĩa**. PR checklist là hợp đồng review, không phải parser cưỡng chế PR body.
+  Người/AI review đối chiếu diff với ma trận, lý do not-applicable và bằng chứng thực tế.
+
+Thêm nhóm thành phần mới thì cập nhật bản đồ và ma trận tại đây, mẫu impact và PR template nếu cần;
+chỉ mở rộng kiểm tra tự động cho các liên kết có thể xác minh đáng tin cậy. Không tạo registry thứ hai
+cho adapter/skill: `harness.yaml` và module manifests vẫn là nguồn đăng ký chính.

package/docs/monetization.md

@@ -28,7 +28,7 @@ For React/Next.js, substitute `--adapters react-nextjs`. Add `product,uiux` only
 6. If approved to publish, use the actual Google-provided ad integration and owner-authorized publisher details. `ads.txt` at the root domain is **highly recommended, not universally mandatory**; never invent an account/seller ID.
 7. Human reviews actual changed pages, ad/no-fill/adblocked/consent UX and production release scope before deploy. `aih` cannot publish ads or deploy.
 
-Project-owned artifacts: `docs/monetization/site-monetization-plan.md`, `ad-placement-review.md`, `privacy-consent-checklist.md`. The templates are installed at `.harness/capabilities/monetization/templates/` and must be copied into consumer docs by your authorized editor **without overwrite**; `aih new-doc` creates **Product-only** templates.
+Project-owned artifacts: `docs/monetization/site-monetization-plan.md`, `ad-placement-review.md`, `privacy-consent-checklist.md`. The templates are installed at `.harness/capabilities/monetization/templates/` and can be scaffolded with `aih new-doc <type> --capability monetization` **without overwrite**; the default new-doc owner remains Product.
 
 ## Workflow B — traffic → financial learning
 

package/docs/project-configuration.md

@@ -3,6 +3,7 @@
 | File | Nội dung | Git |
 | --- | --- | --- |
 | `.harness/project.json` | Adapter/capability | Commit |
+| `.harness/agents.json` | Provider/model/reasoning theo role, execution preferences và host mappings | Commit |
 | `.harness/local.md` | Nghiệp vụ, kiến trúc, nguồn và quyết định chung | Commit |
 | `.harness/environment.json` | Công cụ, lệnh, file cần có | Commit |
 | `.harness/machine.json` | Đường dẫn riêng của máy, tùy chọn | Ignore |
@@ -12,6 +13,9 @@ Init/update tạo environment rỗng nếu chưa có và thêm `/machine.json` v
 CLI không tạo file machine và không đọc nội dung Maven settings. Không ghi mật khẩu/token vào các
 file Harness; credentials thuộc cơ chế quản lý riêng của công cụ.
 
+[Agent configuration](agent-configuration.md) mô tả preset và cấu hình model. `aih setup --host codex`
+chỉ đưa ra kế hoạch khai báo; update bảo toàn `agents.json` và không ghi config native của AI host.
+
 ## Ví dụ Maven nội bộ
 
 Cấu hình chung:

package/docs/project-conventions.md

@@ -0,0 +1,67 @@
+# Coding conventions: dự án mới và maintain
+
+Harness yêu cầu AI đọc cấu trúc và tìm phần tái sử dụng trước khi code. Core áp dụng cho mọi stack;
+Java/Spring, React/Next.js và React Native có thêm bộ convention mặc định. Đây là hướng dẫn cho AI
+host, không phải công cụ tự phân tích hoặc cưỡng chế kiến trúc ứng dụng.
+
+| Phạm vi | Cách làm |
+| --- | --- |
+| New | Đề xuất cấu trúc tối thiểu và convention theo adapter; chốt lựa chọn có ảnh hưởng trước khi dựng |
+| Maintain | Theo quy định và pattern nhất quán của module đang sửa; giữ public contract và dùng common phù hợp |
+| Mixed | Module mới kế thừa quy định chung của repo; chỉ quyết định mới cho phần nội bộ chưa có chuẩn |
+
+Một tính năng mới trong module cũ vẫn là maintain. Có `pom.xml` hay `package.json` chưa đủ để kết luận
+mode; `aih detect` chỉ đưa gợi ý stack. AI kiểm tra scope và quyết định đã có, không hỏi lại toàn bộ.
+
+## Quy trình sử dụng
+
+1. Chạy `aih setup`; AI đọc `AGENTS.md`, `.harness/local.md`, build/lint/format và code tương tự.
+2. Nếu thiếu lựa chọn quan trọng, AI hỏi A/B/C có trade-off và gợi ý dựa trên bằng chứng. Quyết định
+   thông thường đã được scope/convention bao phủ không cần hỏi lại.
+3. Lưu các nguồn và quyết định bền vững vào `.harness/local.md`, hoặc liên kết tới tài liệu đang có.
+4. Trước mỗi task, AI ghi ngắn: đã đọc đâu, tái sử dụng symbol nào, code mới đặt đâu, vì sao cần tạo mới.
+   Đặt ghi chú trong change/PR hiện tại; sửa nhỏ không bắt tạo thêm một bộ tài liệu.
+5. Review diff và chạy các kiểm tra của dự án. `aih verify --scope all` xuất checklist gồm Core,
+   còn `aih eval --scope all` xuất các tình huống để đánh giá AI thực tế; không lệnh nào tự chạy model.
+
+## Thứ tự ưu tiên
+
+Trong phạm vi quyền và an toàn hiện có: quy định riêng đã thống nhất → cấu hình và pattern nhất quán
+trong module → mặc định adapter cho chỗ còn thiếu. Nếu tài liệu và code mâu thuẫn, AI nêu nguồn và
+hỏi khi ảnh hưởng đáng kể. Không lấy một file legacy làm chuẩn, không sao chép lỗi bảo mật để đồng bộ.
+
+Ví dụ nội dung ngắn trong `.harness/local.md` (thay bằng đường dẫn thật đã kiểm tra):
+
+```markdown
+## Development conventions
+- Scope: maintain module customer; new feature follows that module's layout.
+- Sources: link the actual team guide, formatter config and comparable endpoint/tests.
+- Boundaries: describe the allowed dependency direction and supported shared APIs.
+- Reuse: link the actual error contract, pagination, mapper/client/components that apply.
+- Checks: link declared project commands and existing architecture tests.
+- Exceptions: record reason, scope and decision source; leave unknowns explicit.
+```
+
+## Nội dung theo stack
+
+| Adapter | Chuẩn và điểm tái sử dụng |
+| --- | --- |
+| [Java/Spring](../adapters/java-spring/rules/conventions.md) | Package/naming, injection, DTO, transaction, error/logging, mapper, pagination, test |
+| [React/Next.js](../adapters/react-nextjs/rules/conventions.md) | Feature/routes, naming, typed contracts, client/hooks/state, forms, design tokens, UI states |
+| [React Native](../adapters/react-native/rules/conventions.md) | Screen/navigation, state, API/device boundaries, theme, secure storage, permission, platform checks |
+
+Không tự tạo thêm `ApiResponse`, HTTP client, theme hoặc permission manager nếu dự án đã có bản phù hợp.
+Không ép tái sử dụng bằng cách gọi nội bộ module khác, tạo vòng dependency hoặc đưa nghiệp vụ riêng vào
+common. Dependency, base class hoặc abstraction mới cần nhu cầu thật và lý do; thay đổi kiến trúc ngoài
+scope cần quyết định của người dùng. Không cài lint/framework mới chỉ vì adapter đề cập tên công cụ.
+
+## Update và giới hạn kiểm chứng
+
+Sau khi phiên bản chứa thay đổi được phát hành, nâng CLI rồi chạy `aih update --dry-run`, `aih update`,
+`aih check` trên nhánh consumer. Có thể kiểm thử trước bằng `--source /path/to/reviewed/ai-harness`.
+Update giữ nguyên `.harness/local.md`, environment và các tài liệu dự án; host bổ sung thông tin còn
+thiếu vào file cũ thay vì ghi đè. Không có schema mới, auto-scaffold ứng dụng hay migration kiến trúc.
+
+`aih check` xác minh snapshot Harness; `aih verify` chỉ lập kế hoạch. Lint, test, build và kiểm tra ranh
+giới thực tế do AI host/CI chạy. Khi chưa có kiểm tra kiến trúc tự động, báo kết quả review thủ công
+và giới hạn. Các bài test CLI không chứng minh AI luôn tuân thủ convention; xem [đánh giá](../evals/README.md).

package/docs/research/solution-workflow-sources.md

@@ -0,0 +1,30 @@
+# Source review: product and solution delivery
+
+Reviewed 2026-10-12. These are method references, not installed engines or vendored upstream assets.
+Harness skills/templates were independently authored. Existing MIT distribution and no-runtime-dependency
+contract continue; upstream trademarks/endorsement are not implied.
+
+| Primary source / reviewed revision | Verified license | Method considered | Harness decision |
+| --- | --- | --- | --- |
+| [BMAD stable v6.12.2 README](https://github.com/bmad-code-org/BMAD-METHOD/blob/v6.12.2/README.md), [release](https://github.com/bmad-code-org/BMAD-METHOD/releases/tag/v6.12.2) | [MIT](https://github.com/bmad-code-org/BMAD-METHOD/blob/v6.12.2/LICENSE) | Proportional planning, durable context and explicit decisions/handoffs | Core solution-framing and optional Product/Architecture/Delivery workflows; no installer/runtime adoption |
+| [PM-Skills README](https://github.com/phuryn/pm-skills/blob/c68487d721e419ec87af1ae6412a842978eab785/README.md), [create-prd skill](https://github.com/phuryn/pm-skills/blob/c68487d721e419ec87af1ae6412a842978eab785/pm-execution/skills/create-prd/SKILL.md) | [MIT](https://github.com/phuryn/pm-skills/blob/c68487d721e419ec87af1ae6412a842978eab785/LICENSE) | Task-oriented skills, lean decision-ready output and source-grounded questions | Add independent templates/examples/quality/handoff sections; retain Harness authorization and ambiguity rules |
+| [arc42 overview](https://arc42.org/overview/), [license](https://arc42.org/license/) | CC BY-SA 4.0 for template structure/text; own project content remains owned by its author | Communicate context, boundaries, quality and operating reality at the necessary depth | Original compact overview/NFR/project-map/solution templates; no copied 12-section template or explanatory text |
+| [MADR 4.0.0](https://github.com/adr/madr/tree/4.0.0), [docs](https://adr.github.io/madr/), [license](https://github.com/adr/madr/blob/4.0.0/LICENSE) | MIT OR CC0-1.0 | Trace decisions, alternatives and consequences near code | Original ADR draft with authority/status, revision, rollback and reconsideration triggers |
+
+arc42 creators: Gernot Starke and Peter Hruschka. This reference acknowledges their documentation
+method; it does not claim endorsement or import their licensed template into MIT assets.
+
+BMAD main described v7 as preview alpha at review time. The stable v6.12.2 tag was the research baseline;
+no alpha workflow or future release promise is a dependency. PM-Skills refers specifically to phuryn's
+repo and the pinned revision above, not every similarly named marketplace.
+
+## Fit and limits
+Harness keeps OpenSpec as the change record and a single manifest-driven instruction distribution.
+Core applies a compact overview/impact check; capabilities add depth when selected. Product Manager
+owns product value; Project Manager owns delivery coordination; role names do not make approvals.
+No workflow engine, upstream prompt bundle, provider credentials or public account data was copied.
+
+Research proves source/format availability, not Harness model effectiveness. Behavioral cases remain
+unscored until real host runs and reviewed traces exist. Native host configuration references below
+were checked against official docs; installed-client behavior still requires the smoke procedure in
+[tool setup](../tool-setup/README.md). Recheck sources before changing host discovery recommendations.

package/docs/skill-matrix.md

@@ -1,12 +1,14 @@
-# Skill matrix — 53 skills, 11 nhóm module
+# Skill matrix — 68 skills, 13 nhóm module
 
-Đây là bảng tra cứu **ID thật** theo `SKILL.md` trong source trên `main` (5 Core, 30 capability, 18 adapter). Dùng khi cần chuyển từ [Full SDLC](end-to-end-workflow.md) tới một skill cụ thể, không nạp toàn bộ 53 skill vào prompt.
+Đây là bảng tra cứu **ID thật** theo `SKILL.md` trong source trên `main` (5 Core, 41 capability, 22 adapter). Dùng khi cần chuyển từ [Full SDLC](end-to-end-workflow.md) tới một skill cụ thể, không nạp toàn bộ 68 skill vào prompt.
 
 **Cách dùng:** `aih skills` xem skills đã cài, sau đó `aih skill harness-...` lấy nội dung. Danh mục này mô tả chức năng; **không** có nghĩa `aih` thực thi skills hoặc agent. Tech adapters và capabilities chỉ xuất hiện trong consumer khi được chọn; Core dùng chung.
 
 | Stage | Chọn module | Vai trò/output mong đợi |
 | --- | --- | --- |
 | Discovery → Product | `product` | Source register, BRD/PRD, AC, backlog, traceability |
+| Product → Solution | `architecture` | Context, NFR, module/data/contracts, ADR, architecture review |
+| Solution → Delivery | `delivery` | Value slices, dependencies, owned risks and scope-change assessment |
 | UX → Figma | `uiux` | Flows, screen specs, tokens, design review |
 | Spec → Code → Review | Core + adapter theo stack | OpenSpec, tests, changes, review evidence |
 | Release → Operate | `devops`, `kubernetes` khi phù hợp | CI, container, manifests, rollout và SLO plan |
@@ -22,7 +24,7 @@
 | [`harness-spec`](../core/skills/harness-spec/SKILL.md) | Technical design | Soạn OpenSpec proposal/design/tasks/delta specs | OpenSpec change và các quyết định còn thiếu |
 | [`harness-tdd`](../core/skills/harness-tdd/SKILL.md) | Implementation | Red → green → refactor trên slice nhỏ | Code + test evidence |
 
-## Product capability (13)
+## Product capability (15)
 
 | Skill ID (nguồn) | Khi nào dùng | Mục đích | Output mong đợi |
 | --- | --- | --- | --- |
@@ -35,11 +37,12 @@
 | [`harness-product-prd-generation`](../capabilities/product/skills/harness-product-prd-generation/SKILL.md) | Product | Soạn PRD với scope, outcome và metrics | `docs/product/prd.md` |
 | [`harness-product-traceability`](../capabilities/product/skills/harness-product-traceability/SKILL.md) | Change impact | Liên kết nguồn → stories → UI → spec | `docs/product/traceability.md` |
 | [`harness-product-user-stories`](../capabilities/product/skills/harness-product-user-stories/SKILL.md) | Backlog | Phân rã epics/stories theo yêu cầu duyệt | `docs/product/backlog.md` |
-
 | [`harness-product-idea-discovery`](../capabilities/product/skills/harness-product-idea-discovery/SKILL.md) | Idea-driven | Cùng developer làm rõ ý tưởng, phương án, MVP và quyết định | `docs/discovery/idea.md` |
 | [`harness-product-product-research`](../capabilities/product/skills/harness-product-product-research/SKILL.md) | Research | Tìm và phân loại bằng chứng đáng tin cậy, trade-offs | `docs/discovery/research.md` |
 | [`harness-product-srs-generation`](../capabilities/product/skills/harness-product-srs-generation/SKILL.md) | Software requirements | Đặc tả FR/NFR, giao diện, luồng lỗi có trace ID | `docs/product/srs.md` |
 | [`harness-product-use-case-generation`](../capabilities/product/skills/harness-product-use-case-generation/SKILL.md) | Detailed flows | Viết UC chính/phụ/lỗi liên kết FR/US/AC | `docs/product/use-cases.md` |
+| [`harness-product-mvp-definition`](../capabilities/product/skills/harness-product-mvp-definition/SKILL.md) | MVP scope | Explicit product decisions and traceability | Usable journey, in/out scope and minimum quality |
+| [`harness-product-product-outcomes`](../capabilities/product/skills/harness-product-product-outcomes/SKILL.md) | Success measures | Explicit product decisions and traceability | Evidence-backed metrics and experiments |
 
 ## Monetization capability (5)
 
@@ -81,17 +84,21 @@
 | [`harness-java-spring-kafka-outbox`](../adapters/java-spring/skills/harness-java-spring-kafka-outbox/SKILL.md) | Async events | Outbox transaction và consumer dedupe | Event implementation + failure tests |
 | [`harness-java-spring-spring-api`](../adapters/java-spring/skills/harness-java-spring-spring-api/SKILL.md) | Backend API | Authorization resource scoped, API contract | Endpoint + auth/contract tests |
 
-## React / Next.js adapter (2)
+## React / Next.js adapter (4)
 
 | Skill ID (nguồn) | Khi nào dùng | Mục đích | Output mong đợi |
 | --- | --- | --- | --- |
+| [`harness-react-nextjs-feature-delivery`](../adapters/react-nextjs/skills/harness-react-nextjs-feature-delivery/SKILL.md) | Feature implementation | Reuse route/screen, UI/form and API/state boundaries | AC-linked diff/checks, actual results and explicit limits |
+| [`harness-react-nextjs-behavior-testing`](../adapters/react-nextjs/skills/harness-react-nextjs-behavior-testing/SKILL.md) | Behavior testing | Component/integration and actual browser/server evidence | AC-linked tests, actual results and explicit limits |
 | [`harness-react-nextjs-accessible-ui`](../adapters/react-nextjs/skills/harness-react-nextjs-accessible-ui/SKILL.md) | Frontend | UI states và semantic accessibility | UI + accessibility/browser evidence |
 | [`harness-react-nextjs-server-boundaries`](../adapters/react-nextjs/skills/harness-react-nextjs-server-boundaries/SKILL.md) | Frontend security | Server actions, auth/caching boundaries | Server/client diff + auth/cache tests |
 
-## React Native adapter (2)
+## React Native adapter (4)
 
 | Skill ID (nguồn) | Khi nào dùng | Mục đích | Output mong đợi |
 | --- | --- | --- | --- |
+| [`harness-react-native-screen-delivery`](../adapters/react-native/skills/harness-react-native-screen-delivery/SKILL.md) | Screen implementation | Reuse route/screen, UI/form and API/state boundaries | AC-linked diff/checks, actual results and explicit limits |
+| [`harness-react-native-behavior-testing`](../adapters/react-native/skills/harness-react-native-behavior-testing/SKILL.md) | Behavior testing | JS/navigation and separate platform/device evidence | AC-linked tests, actual results and blocked native checks |
 | [`harness-react-native-device-permissions`](../adapters/react-native/skills/harness-react-native-device-permissions/SKILL.md) | Mobile | Permissions + deep links theo OS | Permission/nav changes + platform tests |
 | [`harness-react-native-offline-sync`](../adapters/react-native/skills/harness-react-native-offline-sync/SKILL.md) | Mobile | Offline queue, retries, conflict resolution | Persistence/sync + edge-case tests |
 
@@ -132,3 +139,24 @@
 - `harness-ai-evaluation` đánh giá **hành vi AI thực tế**; `aih eval` chỉ xuất và tổng hợp report do reviewer điền.
 
 Đối chiếu [Agent handoffs](agent-handoffs.md), [adapters](adapters.md) và [full workflow](end-to-end-workflow.md). Khi thêm skill mới, hãy cập nhật một hàng trong bảng; test tài liệu sẽ báo thiếu/trùng.
+
+## Architecture capability (6)
+
+| Skill ID (nguồn) | Khi nào dùng | Mục đích | Output mong đợi |
+| --- | --- | --- | --- |
+| [`harness-architecture-project-context`](../capabilities/architecture/skills/harness-architecture-project-context/SKILL.md) | project-context | Map verified system context, module ownership and source-linked architecture for new or existing projects. | Project-owned docs/architecture or compact task note |
+| [`harness-architecture-quality-attributes`](../capabilities/architecture/skills/harness-architecture-quality-attributes/SKILL.md) | quality-attributes | Translate NFRs into measurable quality scenarios and verification plans with evidence-backed targets. | Project-owned docs/architecture or compact task note |
+| [`harness-architecture-solution-design`](../capabilities/architecture/skills/harness-architecture-solution-design/SKILL.md) | solution-design | Compare architectures and local design patterns against MVP, NFRs and existing project boundaries. | Project-owned docs/architecture or compact task note |
+| [`harness-architecture-decision-records`](../capabilities/architecture/skills/harness-architecture-decision-records/SKILL.md) | decision-records | Record traceable architecture decisions with alternatives, consequences and reconsideration triggers. | Project-owned docs/architecture or compact task note |
+| [`harness-architecture-change-impact`](../capabilities/architecture/skills/harness-architecture-change-impact/SKILL.md) | change-impact | Assess change impact and architecture drift using a source-linked living project map. | Project-owned docs/architecture or compact task note |
+| [`harness-architecture-review`](../capabilities/architecture/skills/harness-architecture-review/SKILL.md) | review | Review solution and implemented boundaries against MVP, NFRs, ADRs and actual verification evidence. | Project-owned docs/architecture or compact task note |
+
+## Delivery capability (3)
+
+| Skill ID (nguồn) | Khi nào dùng | Mục đích | Output mong đợi |
+| --- | --- | --- | --- |
+| [`harness-delivery-planning`](../capabilities/delivery/skills/harness-delivery-planning/SKILL.md) | planning | Plan value-bearing delivery slices and dependencies from reviewed scope and team-supplied estimates. | Project-owned docs/delivery or compact task note |
+| [`harness-delivery-risk-management`](../capabilities/delivery/skills/harness-delivery-risk-management/SKILL.md) | risk-management | Maintain owned delivery risks, assumptions, blockers and dependencies with response triggers. | Project-owned docs/delivery or compact task note |
+| [`harness-delivery-scope-change`](../capabilities/delivery/skills/harness-delivery-scope-change/SKILL.md) | scope-change | Evaluate scope changes across product value, architecture, dependencies and delivery before re-planning. | Project-owned docs/delivery or compact task note |
+
+Product → Architecture → Delivery → Core/adapter uses [Solution workflow](solution-workflow.md); source revisions, requirement/AC/NFR/ADR IDs and actual decisions travel together. See [host setup](tool-setup/README.md).

package/docs/solution-workflow.md

@@ -0,0 +1,67 @@
+# BA → PO → SA → PM → Dev/QA
+
+Product contains BA/PO analysis and documents; optional Architecture adds Solution Architect context,
+NFRs/ADRs/design/review; optional Delivery adds Project Manager planning/risks/scope changes.
+Roles are instructions for a host and can be performed sequentially. User/stakeholder decisions keep
+actual authority. No new workflow engine is installed; OpenSpec owns change proposal/design/tasks/specs.
+
+## Choose proportional depth
+| Work | Minimum sufficient context | Optional deeper outputs |
+| --- | --- | --- |
+| Small clear fix | Existing source/decisions, affected boundary/reuse and regression note | Only new consequential decisions |
+| New small product | Actor/problem, usable MVP journey/AC, minimum NFR, minimal solution and slices | Short overview and a significant ADR |
+| Material/enterprise change | Source versions, MVP/requirements, module/data/contracts, NFR/failure impact | Project map, ADRs, risk register, rollout plan |
+
+```bash
+aih init --adapters java-spring --capabilities product,architecture,delivery
+aih setup
+aih skills
+aih new-doc mvp
+aih new-doc overview --capability architecture
+aih new-doc nfr --capability architecture
+aih new-doc delivery-plan --capability delivery
+aih new-change customer-search
+aih verify --scope all
+aih eval --scope all
+```
+
+Blank templates only. Use existing approved BA/Confluence documents instead of re-creating them.
+For an existing Harness install, edit selected capabilities in project.json and use reviewed update
+--dry-run/update/check. `resolve` validates and warns; it does not install soft recommendations.
+
+## Responsibilities and handoff
+| Role / module | Owns | Receives / passes |
+| --- | --- | --- |
+| BA / Product | Problem, business rules, source authority and requirement gaps | Idea/docs → versioned FR/US/AC/NFR and contradictions |
+| PO / Product | MVP value, in/out scope, acceptance and priorities | BA → reviewed journey, outcomes and actual scope decisions |
+| SA / Architecture | Context, quality scenarios, solution trade-offs, public boundaries | Scope → NFR/ADR/contracts/failure flows and verification |
+| PM / Delivery | Sequencing, dependencies, estimates/risks and status | Accepted scope/design → value slices, owners, blockers and checkpoints |
+| Dev/QA / Core + adapters | Implementation and actual tests | OpenSpec/decisions → minimal code, test evidence and findings |
+| DevOps / optional capability | Operational release/recovery detail | Agreed constraints → reviewed rollout/rollback/telemetry |
+
+Carry source revision, requirement/AC/NFR/ADR IDs, output paths, decisions/status, unresolved questions,
+actual verification and next owner. Scope changes return to PO; technical conflicts to SA; delivery
+risks to PM. UX and implementation feedback can revise the plan; this is not a one-way document conveyor.
+
+## MVP and architecture judgment
+MVP must let a target actor complete a useful journey. A customer-search MVP can defer bulk import
+but must include resource authorization, data integrity and agreed duplicate behavior.
+Compare architectures on actual constraints; styles may combine. Ports and Adapters concerns boundaries;
+Factory concerns object construction. Add Strategy/Adapter/State only for concrete variation or state
+requirements. Direct code is a valid minimal choice. Do not promise enterprise scale from a diagram.
+
+Record important decisions with evidence and owner status, not inferred approval. NFR targets/load,
+cost and delivery estimates remain unknown when evidence is absent. Keep the living project-map
+linked to actual source; refresh touched entries when code/requirements change instead of loading all docs.
+
+## Templates and reading paths
+- [Product handoff](../capabilities/product/workflows/product-to-solution.md): MVP/outcomes, existing BA skills.
+- [Architecture entry](../capabilities/architecture/workflows/discovery-to-design.md), [change review](../capabilities/architecture/workflows/change-review.md).
+- [Delivery planning](../capabilities/delivery/workflows/planning.md), [execution/change](../capabilities/delivery/workflows/execution-change.md).
+- [Core framing](../core/workflows/solution-framing.md), [skill matrix](skill-matrix.md), [agent handoffs](agent-handoffs.md).
+- [Research/provenance](research/solution-workflow-sources.md), [coding tool setup](tool-setup/README.md).
+
+`aih new-doc adr --capability architecture` produces one draft; move the populated file to a stable
+project-owned `docs/architecture/decisions/adr-NNN.md` path and link it before making the next ADR.
+`aih new-doc delivery-plan` keeps its historical Product path; explicitly select Delivery for the richer
+plan. Do not duplicate/migrate an accepted plan automatically.

package/docs/templates/harness-change-impact.md

@@ -0,0 +1,30 @@
+# Harness change impact
+
+Maintainer-only template. Copy into the active OpenSpec design/change or use the table in a small PR.
+Do not install this as a mandatory consumer application template.
+
+- Change / objective: record the actual request and scope.
+- Base commit / affected modules: record verified values.
+- Decision sources: link existing decisions; list consequential unresolved questions.
+
+Use `pending`, `done`, or `not-applicable`. Every row needs paths/evidence or a specific reason.
+Keep pending work visible; no blanket not-applicable statement for the whole change.
+
+| Area | Status | Affected paths and evidence / reason not applicable |
+| --- | --- | --- |
+| core | pending | Assess rule, entry point, policy and related behavior |
+| adapter | pending | Assess registry, manifest, index, assets and module version |
+| capability-skill | pending | Assess declaration, exposure, workflow and handoff |
+| cli-config | pending | Assess schema, ownership, install/update and package contents |
+| workflow | pending | Assess inputs, outputs, gates and receiving stage |
+| documentation | pending | Assess usage guides, examples and links |
+| verification | pending | Record actual commands/results; separate manual/live-agent evidence |
+| release-migration | pending | Assess Unreleased notes, compatibility, rollback and version ownership |
+
+## Link chain
+Record declaration → distribution → discovery → use → review/check → documentation for affected
+behavior. Explain any stage that does not apply. For a removal/rename, list old references reconciled.
+
+## Validation and remaining work
+Record commands actually run, outcomes, skipped checks with reasons, pending items and next owner.
+Do not claim model compliance from file/link tests. Keep shared instructions in their canonical docs.