@manhd_d/ai-harness 0.0.0-stage → 0.6.2

package/docs/examples/astro-micro-tools.md

@@ -0,0 +1,125 @@
+# Walkthrough — Astro micro-tools, SEO, React Islands and future MFE
+
+**Tình huống:** bạn muốn xây website gồm nhiều công cụ nhỏ như QR generator, JSON formatter, image compressor và có thể thêm các tool phức tạp hơn. Mục tiêu là deploy nhẹ, SEO tốt và có đường nâng cấp lên MFE *nếu thực sự cần*, không phải triển khai micro frontend từ ngày đầu.
+
+## 1. Chuẩn bị Astro project
+
+Cần Node.js 22+, Git, một repo Astro đã tạo hoặc đã checkout và `aih` CLI bản nguồn chứa Astro adapter. Nếu chưa có Astro repo, tạo bằng **Astro CLI chính thức** rồi chọn TypeScript theo nhu cầu; lệnh sau là ví dụ tương tác, phải kiểm tra phiên bản hướng dẫn hiện hành:
+
+```bash
+npm create astro@latest
+cd /path/to/astro-project
+# Nếu sử dụng React islands, cài @astrojs/react theo tài liệu Astro
+# npx astro add react
+```
+
+Không cần React để viết đa số tool cơ bản. `aih` là bộ hướng dẫn AI, **không** tạo Astro source code và không cài các dependencies này.
+
+## 2. Cài Harness vào repo
+
+```bash
+aih resolve --adapters astro --capabilities product,uiux
+aih init --adapters astro --capabilities product,uiux --dry-run
+aih init --adapters astro --capabilities product,uiux
+aih check
+aih skills
+aih skill harness-astro-project-architecture
+aih skill harness-astro-seo
+```
+
+`product,uiux` đều **tùy chọn**; dự án chỉ cần Core + Astro có thể dùng `aih init --adapters astro`. Trong repo *đã cài Harness*, chỉnh `.harness/project.json` để thêm `astro`, sau đó `aih update --dry-run`, `aih update`, `aih check`. Không chạy lại init với cấu hình khác khi có file snapshot.
+
+Để thử detector an toàn:
+
+```bash
+aih detect
+aih init --detect --dry-run
+```
+
+Detector chỉ đọc dependencies của `package.json` ngay trong thư mục hiện tại. `astro` được nhận diện từ dependency tên `astro`; `react-dom` do React islands **không tự động** khiến detector thêm `react-nextjs` nếu không có `next`. Nếu app dùng `next` thật hoặc muốn đồng thời cài cả hai adapter, có thể chọn thủ công.
+
+## 3. Tổ chức tools kiểu static-first
+
+```text
+src/
+  layouts/
+    ToolLayout.astro
+  pages/
+    index.astro
+    tools/
+      qr-generator.astro
+      json-formatter.astro
+      image-compressor.astro
+  components/
+    ImageEditor.tsx      # chỉ khi có React thực sự cần thiết
+  lib/
+    qr/
+      validation.ts
+      encode.ts
+    image/
+      transform.ts
+```
+
+Một công cụ đơn giản nên chạy ngay trên trình duyệt, không gửi dữ liệu riêng tư lên server. Đặt validation và functions riêng, tránh tool này import trạng thái tool khác. Các API có quyền/secret mới cần Worker/server xử lý theo authorization rõ ràng.
+
+Prompt ví dụ trong Codex/IDE/Work đã được cấp quyền repo:
+
+> Đọc AGENTS.md và skill harness-astro-project-architecture + harness-astro-seo. Tôi muốn làm 3 tools: QR generator, JSON formatter và image compressor. Lập kế hoạch UI, route và ưu tiên xử lý dữ liệu ngay trên trình duyệt. Kiểm tra scripts/dependencies trước khi sửa, không tự cài backend, database, auth hay React. Tạo vertical slice cho QR generator với validation, trạng thái lỗi và accessible keyboard labels. Sau khi tôi duyệt spec, triển khai và chạy các test/build scripts thực có. Trả về diff và kết quả thực tế, không tự deploy.
+
+## 4. Thêm React Islands khi cần
+
+Chỉ hydrate React cho phần có tương tác đủ phức tạp. Nếu đã cài `@astrojs/react` phù hợp, ví dụ nhúng React component vào Astro page:
+
+```astro
+---
+import ImageEditor from '../../components/ImageEditor.tsx';
+---
+
+<h1>Image Editor</h1>
+<ImageEditor client:visible />
+```
+
+Chọn `client:load` nếu cần tương tác ngay ở phần đầu trang, `client:visible` khi tool nằm dưới fold; kiểm tra timing/hydration trong browser. Đừng nhúng React cho toàn bộ landing page chỉ để có một nút.
+
+**Islands không phải MFE.** Hiện tại tất cả trang và island của Astro project vẫn build/deploy cùng nhau.
+
+## 5. Cloudflare và deployment
+
+- Với các tool hoàn toàn chạy trong browser: build Astro ra static files, phục vụ từ CDN/host hỗ trợ static; **không cần Cloudflare Workers** chỉ để chạy website.
+- Nếu cần API dùng secrets, xử lý server hoặc điều phối dữ liệu được phép truy cập: đánh giá Cloudflare Workers và adapter/runtime theo **phiên bản Astro hiện dùng**. Với dự án mới, kiểm tra tài liệu Cloudflare Workers chính thức trước khi chọn thiết lập.
+- Không để private keys trong `PUBLIC_*` biến môi trường hoặc phía frontend. Nếu tính năng fetch URL của người dùng, phải xét SSRF, redirect, private IP, quotas và quyền nội dung; không triển khai arbitrary URL proxy thiếu kiểm soát.
+- `aih verify` chỉ đưa ra checklist, không chạy build. Chỉ chạy các lệnh **thực có trong package.json**, ví dụ `npm run build`, `npm run check` nếu có, cùng browser UX tests. Con người duyệt trước bất kỳ cloud deployment/DNS thay đổi nào.
+
+## 6. Scale lên Micro Frontend khi cần
+
+**Giai đoạn 1:** một Astro repository, các route/tool độc lập.
+
+**Giai đoạn 2:** các React Islands hoặc shared UI packages được phép dùng, vẫn trong một build/deploy. Có thể dùng monorepo khi cần quản lý code dùng chung, nhưng chưa phải MFE.
+
+**Giai đoạn 3:** khi một tool cần team, release cadence hoặc runtime riêng, tách **một route** (ví dụ `/tools/image-editor`) ra ứng dụng deploy riêng qua routing/proxy phù hợp. Kiểm tra domain, deep links, assets, CSP/cookies/auth, analytics, SEO/canonicals, lỗi và rollback trước cut-over. Không mặc định Module Federation.
+
+Prompt ra quyết định:
+
+> Dựa vào docs, ownership và deploy hiện tại, đánh giá tách image-editor thành MFE hay giữ Astro Island. So sánh khả năng deploy độc lập, SEO, routing, caching, cookie/auth, bundle và chi phí vận hành. Chỉ đề xuất kiến trúc sau khi có nhu cầu thực; ghi ADR/approval và migration steps, chưa tự triển khai.
+
+## Optional: AdSense revenue model
+
+Nếu mục tiêu website là quảng cáo, có thể cài capability `monetization` bên cạnh adapter Astro. Dự án đã cài hãy cập nhật `.harness/project.json` và dùng `aih update` sau khi review. Đọc [Astro + AdSense walkthrough](astro-adsense-microtools.md) để phân biệt build tool với publisher compliance, đặt quảng cáo tránh Generate/Download và đo Page RPM. `aih` không tự nhúng script, tạo ad account hay cam kết doanh thu.
+
+## 7. Test và PR review
+
+```bash
+aih verify --scope all  # advisory, không thực thi test
+aih eval --scope all    # dataset/review template, không gọi model
+aih check
+```
+
+Dùng Core review/TDD và `harness-astro-performance` để ghi bằng chứng build/browser thực chạy, cùng `harness-astro-microfrontend` khi đánh giá split. Hoàn tất spec → code → tests → human PR review. Harness không deploy/merge tự động.
+
+## Tài liệu chính thức
+
+- [Astro islands và framework components](https://docs.astro.build/en/guides/framework-components/)
+- [Astro + Cloudflare deployment](https://docs.astro.build/en/guides/deploy/cloudflare/)
+- [Astro sitemap integration](https://docs.astro.build/en/guides/integrations-guide/sitemap/)
+- [Astro adapter](../../adapters/astro/README.md)
+- [Full SDLC](../end-to-end-workflow.md)

package/docs/examples/document-driven-project.md

@@ -0,0 +1,62 @@
+# Walkthrough B — dự án đã có tài liệu BA/Confluence → OpenSpec → code
+
+Dùng chế độ **Document-driven** cho dự án doanh nghiệp hoặc bất kỳ codebase nào đã có BRD/PRD/SRS/Confluence/Jira. Tài liệu gốc tiếp tục do hệ thống/chủ sở hữu hiện tại quản lý; AI **không cần tạo lại BRD hay PRD** chỉ để code.
+
+## 1. Cài Harness trong repository hiện có
+
+Ví dụ một backend Spring Boot đã được checkout. Cần Node.js 22+, Git và `aih` đã cài từ bản nguồn được review.
+
+```bash
+cd /path/to/existing-spring-project
+git switch -c feat/customer-search
+aih init --adapters java-spring --capabilities product --dry-run
+aih init --adapters java-spring --capabilities product
+aih check
+aih skills
+aih skill harness-product-knowledge-analysis
+```
+
+Nếu repository **đã cài** Harness, chỉnh `.harness/project.json` nếu cần thêm capability rồi `aih update --dry-run`, `aih update`, `aih check`. Không thực hiện init chồng lên bộ cài do dự án đã quản lý.
+
+## 2. Cung cấp tài liệu có quyền truy cập
+
+Chia sẻ **đường dẫn/trang được cấp phép** (Confluence, Git files) hoặc export được phép. Agent phải ghi ID trang, URL, revision, owner, phạm vi quyền và approval status; không suy diễn rằng mọi trang đều mới nhất hoặc đã được duyệt.
+
+```bash
+aih new-doc source-register
+aih new-doc traceability
+```
+
+Prompt dùng với AI host có quyền đọc project và nguồn:
+
+> Đọc AGENTS.md, Product workflow document-driven và các tài liệu BA tôi cho phép. Tác vụ: triển khai tìm kiếm khách hàng có phân quyền. Đầu tiên xác định BRD/PRD/SRS nào là nguồn chuẩn, ghi source IDs, URL và phiên bản trong docs/product/source-register.md. Liệt kê FR/NFR/US/AC liên quan, kiểm tra mâu thuẫn và thông tin còn thiếu. Không bịa nội dung chưa đọc được, không viết lại tài liệu BA đã approved. Hoàn thiện traceability draft và đưa tôi review trước khi tạo technical spec.
+
+Nếu Confluence chưa kết nối trong AI host, agent phải báo là **không thể đọc**, yêu cầu export/phạm vi được phép; `aih` không tự truy cập Confluence.
+
+## 3. Gap analysis và phê duyệt
+
+- Tài liệu BA có sẵn và hợp lệ: chỉ tạo `source-register`, `traceability`, decision log hoặc các artifact thiếu.
+- SRS chưa có hoặc thiếu chi tiết thực sự: có thể chạy `aih new-doc srs` và `aih new-doc use-cases`, nhờ AI điền **draft** từ những requirement đã xác nhận.
+- Có source conflict, thiếu AC hoặc yêu cầu chưa rõ: AI ghi UNKNOWN và chờ BA/PO hoặc chủ dự án có quyền quyết định; không tự gắn nhãn approved.
+
+## 4. Tạo OpenSpec từ phạm vi đã duyệt
+
+```bash
+aih new-change customer-search
+# Điền TODO trong openspec/changes/customer-search/ rồi review.
+```
+
+Prompt handoff:
+
+> Dựa vào các requirement IDs đã approved và source revisions trong docs/product/traceability.md, dùng core harness-spec và skill adapter java-spring phù hợp để lập proposal/design/tasks/spec cho customer-search. Chỉ mô tả hành vi có bằng chứng, test cases gồm authorization deny-other-tenant, input validation, no-result/error cases nếu phù hợp với yêu cầu nguồn. Đánh dấu NFR còn thiếu; không tự duyệt. Sau khi tôi chốt spec, implement trên branch hiện tại, chạy test thực tế, tạo PR để review và không tự merge/deploy.
+
+Nếu dùng OpenSpec upstream thì pin và cài CLI riêng, sau đó có thể chạy `openspec validate customer-search --strict` khi bản nháp đã hoàn thiện.
+
+## 5. Lưu trữ và bảo mật
+
+- Tài liệu BA chính thức vẫn ở Confluence/Drive/repo được chỉ định; trong repository kỹ thuật giữ URL/revision và những tài liệu dẫn xuất được phép lưu.
+- `docs/product/` chứa traceability, source register và các bản draft phục vụ dự án; `openspec/` chứa technical spec và change liên kết FR/US/AC.
+- Không đưa tài liệu khách hàng mật, secrets hoặc export nguyên bản vào repo không được phép. Không publish Confluence hay sửa PRD gốc nếu chưa được phê duyệt.
+- Khi tài liệu BA đổi revision, dùng change-impact analysis và review delta thay vì ghi đè code/spec.
+
+**Giới hạn:** skills và role contracts không tự biến thành agent runtime; CI/test/OpenSpec validation thực tế phải do host/IDE và công cụ liên quan chạy, có kết quả kiểm chứng.

package/docs/examples/fullstack-web.md

@@ -0,0 +1,80 @@
+# Walkthrough 2 — Full-stack Spring Boot + Next.js + Product + Figma
+
+**Tình huống giả định:** xây hành trình tạo ticket (backend Spring Boot + frontend Next.js) trong **một repo chứa cả hai module**, bắt đầu từ product idea hoặc Confluence. Đây là runbook minh họa; không có ứng dụng nào được tạo tự động.
+
+## 1. Chọn modules cho repo
+
+~~~bash
+cd /path/to/existing-fullstack-repository
+aih resolve --adapters java-spring,react-nextjs --capabilities product,uiux,devops
+aih init --adapters java-spring,react-nextjs --capabilities product,uiux,devops --dry-run
+aih init --adapters java-spring,react-nextjs --capabilities product,uiux,devops
+aih check
+aih skills
+~~~
+
+Chỉ thêm `kubernetes` nếu repo cũng sở hữu manifest/chart. Nếu backend/frontend nằm **hai Git repository** độc lập, cài `aih` riêng từng repo theo stack tương ứng, liên kết hai PR bằng cùng change ID; không cố ép cả hai vào một Git root. `aih detect` không quét lồng `apps/web` / `services/api`.
+
+## 2. Product discovery và gate
+
+~~~bash
+aih new-doc brd
+aih new-doc prd
+aih new-doc backlog
+aih new-doc acceptance-criteria
+aih new-doc traceability
+aih skill harness-product-knowledge-analysis
+aih skill harness-product-brd-generation
+aih skill harness-product-user-stories
+aih skill harness-product-document-review
+~~~
+
+BA xác nhận nguồn/timestamps; PM chốt mục tiêu, PO duyệt `US-001`/`AC-US-001-01`; requirements reviewer kiểm tra truy vết. Confluence là **nguồn dữ liệu**, không cấp quyền tự động. Các draft chưa phê duyệt không được tự đánh dấu Approved.
+
+## 3. UI/UX & design gate
+
+~~~bash
+aih skill harness-uiux-user-flow
+aih skill harness-uiux-screen-planning
+aih skill harness-uiux-design-system
+aih skill harness-uiux-figma-design
+aih skill harness-uiux-design-review
+~~~
+
+Từ approved PRD/AC, lập screen inventory (create, success, validation error, permission denial, loading, empty), responsive/keyboard/accessibility states. Nếu UI/UX cần trích nguồn riêng, dùng `harness-uiux-requirements-analysis` nhưng **không tạo lại ID cạnh tranh với Product**.
+
+Figma MCP phải được cấu hình ngoài `aih`; **Gate A:** người phụ trách duyệt flow/screen trước quyền ghi Figma; **Gate B:** duyệt review findings và Figma nodes trước implementation. Không có kết nối Figma thì bàn giao screen specs bằng Markdown, không khẳng định đã tạo frames.
+
+## 4. Spec → implementation
+
+~~~bash
+aih new-change add-ticket-creation
+aih skill harness-spec
+aih skill harness-tdd
+aih skill harness-java-spring-spring-api
+aih skill harness-react-nextjs-accessible-ui
+aih skill harness-react-nextjs-server-boundaries
+~~~
+
+Spec phải chứa contract `POST /...` thực tế đã review, authorization, error envelope, loading/empty/errors, client/server boundaries, cache invalidation và contract tests. Implement thành vertical slice API + UI cùng acceptance IDs. Đối với giao diện frontend, kiểm tra SSR/client boundary và tránh đưa credentials ra browser.
+
+Ví dụ kiểm tra **chỉ nếu repo có tương ứng**:
+
+~~~bash
+# Backend, chạy từ module sở hữu Maven wrapper:
+./mvnw test
+# Frontend, chạy từ module Next.js có script:
+npm test
+npm run build
+~~~
+
+Không coi dòng lệnh minh họa là bằng chứng đã chạy. Với multi-repo, mỗi repo có CI, owner và PR riêng.
+
+## 5. PR → release & feedback
+
+- Review dùng `harness-review`, `test-engineer`, `security-reviewer`, trace `AC → API/FE tests → PR` và Figma node IDs.
+- `aih verify --scope all` và `aih eval --scope all` **chỉ trả kế hoạch/dataset**, không tự chạy tests.
+- `harness-devops-ci-cd` + `harness-devops-deployment` cung cấp rollout/rollback plan, `harness-devops-observability` chỉ rõ SLI/SLO/alert.
+- Staging/production cần phê duyệt environment và artifact riêng; user hoặc operator quyết định merge/deploy.
+
+**Deliverables:** approved PRD/AC → user-flow/screen-spec/Figma reference → OpenSpec change → backend + frontend diff/tests → reviewed PR(s) → telemetry evidence.

package/docs/examples/idea-driven-project.md

@@ -0,0 +1,71 @@
+# Walkthrough A — từ ý tưởng của developer tới tài liệu và code
+
+Đây là **ví dụ thực hành** của chế độ **Idea-driven**, không gắn với một dự án CRM hay công nghệ cụ thể. `aih` chỉ cài hướng dẫn/skills và tạo **template trống**; AI host như Codex, IDE assistant hoặc ChatGPT Work có quyền repo mới có thể phân tích và ghi nội dung. Trong Chat thông thường, bạn vẫn có thể thảo luận ý tưởng, nhưng việc ghi file cần công cụ và quyền truy cập phù hợp.
+
+## 1. Chuẩn bị dự án và cài Harness
+
+Yêu cầu: Node.js 22+, Git, CLI `aih` đã cài từ bản nguồn được review, và một thư mục dự án tồn tại. Xem [Getting started](../getting-started.md) để cài CLI từ source; bản tính năng này nằm trong PR cho tới khi merge.
+
+```bash
+mkdir expense-app
+cd expense-app
+git init
+aih init --capabilities product
+aih new-doc idea
+aih new-doc decision-log
+aih check
+aih skills
+aih skill harness-product-idea-discovery
+aih skill harness-product-product-research
+```
+
+Nếu dự án đã cài Harness, sửa `.harness/project.json` để thêm `product` vào `capabilities`, rồi dùng `aih update --dry-run && aih update && aih check` trên branch riêng; **không** chạy lại init với lựa chọn không tương thích.
+
+## 2. Giao AI thảo luận thay vì bắt đầu code
+
+Dán prompt này vào AI host có quyền đọc repository (hoặc thảo luận trước trong Chat):
+
+> Đọc AGENTS.md và skill harness-product-idea-discovery đã cài. Ý tưởng ban đầu của tôi: “Ứng dụng quản lý chi tiêu cá nhân cho phép nhập giao dịch, AI đề xuất phân loại, có báo cáo theo tháng”. Hãy giữ nguyên ý tưởng gốc, đóng vai BA/PM/PO và thảo luận từng nhóm vấn đề quan trọng với tôi. Đề xuất user personas, MVP, non-goals và trade-off; không tự cho rằng các đề xuất là quyết định của tôi. Phân biệt FACT / INFERENCE / DECISION / UNKNOWN. Chưa code hay tự duyệt scope.
+
+Sau mỗi vòng thảo luận, AI host cập nhật các file đã tạo trước đó: `docs/discovery/idea.md` và `docs/product/decision-log.md` (nếu được cấp quyền). Bạn là người chốt mục tiêu và MVP, không cần có BA/PM/PO riêng cho dự án cá nhân.
+
+## 3. Tạo draft tài liệu có cấu trúc
+
+```bash
+aih new-doc research
+aih new-doc prd-lite
+aih new-doc acceptance-criteria
+aih new-doc traceability
+aih check
+```
+
+`idea.md` và `decision-log.md` đã tạo tại bước 1; không chạy lại. Các lệnh chỉ chạy **một lần trên mỗi file** và sẽ từ chối ghi đè. Khi đã có file, AI host điền nội dung vào đúng file dựa trên thảo luận, không chạy lại `new-doc`.
+
+Prompt mẫu:
+
+> Đọc AGENTS.md và skill harness-product-product-research đã cài. Nếu có công cụ web được cấp phép, hãy tìm các sản phẩm tương tự và ghi nguồn, ngày kiểm tra, điểm mạnh/yếu vào docs/discovery/research.md; nếu không có công cụ thì đánh dấu chưa nghiên cứu, không bịa nguồn. Từ các quyết định tôi đã duyệt, hoàn thiện docs/product/prd-lite.md, acceptance-criteria.md và traceability.md. Chỉ ghi draft/pending-review đối với thông tin chưa phê duyệt, rồi gửi diff để tôi review.
+
+Khi cần chi tiết hơn (đa actor, nghiệp vụ phức tạp, nhiều tích hợp), tạo thêm `aih new-doc brd`, `aih new-doc prd`, `aih new-doc srs`, `aih new-doc use-cases` theo **mức độ cần thiết**, không bắt mọi dự án phải có tất cả.
+
+## 4. Human approval và OpenSpec
+
+Sau khi duyệt scope, cập nhật trạng thái/decision record thật của owner. Chỉ khi requirements và AC cho một thay đổi đã được duyệt, mới chuyển sang OpenSpec:
+
+```bash
+aih new-change add-expense-categorization
+# Chỉ là các file proposal/design/tasks/spec dạng TODO, chưa được phê duyệt.
+```
+
+Prompt handoff:
+
+> Đọc approved scope trong docs/product/ và requirement IDs; dùng core harness-spec để hoàn thiện openspec/changes/add-expense-categorization/, bao gồm test scenarios, rủi ro bảo mật dữ liệu, xử lý lỗi và những điểm còn thiếu. Không tự triển khai nếu scope chưa được duyệt. Sau khi tôi review, dùng adapter phù hợp để implement/test và tạo PR, không tự merge.
+
+Nếu dùng OpenSpec upstream, cài/pin CLI riêng và chạy `openspec validate add-expense-categorization --strict` sau khi điền nội dung. Harness không tự cài hay chạy OpenSpec CLI.
+
+## 5. Lưu trữ và thay đổi về sau
+
+- `docs/discovery/` lưu ý tưởng và research đã ghi nguồn; `docs/product/` lưu tài liệu yêu cầu của **project**, không lưu trong source `ai-harness`.
+- `openspec/` lưu technical change và trace ID. Review tài liệu, code và CI trên PR, sau đó con người quyết định merge.
+- Khi ý tưởng thay đổi, dùng `workflows/change-impact-analysis.md` và yêu cầu AI tạo diff; không tự ghi đè tài liệu approved.
+
+**Giới hạn:** `aih verify --scope all` / `aih eval --scope all` chỉ cho checklist/eval advisory; không chứng minh đã thực sự chạy test, nghiên cứu hoặc review.

package/docs/examples/react-native-app.md

@@ -0,0 +1,57 @@
+# Walkthrough 3 — React Native/Expo: permission, offline và release
+
+**Tình huống giả định:** thêm màn hình lưu nháp khi offline và đồng bộ lại khi có mạng trong ứng dụng React Native/Expo đã tồn tại. Đây là hướng dẫn công việc, **không** scaffold app, không dùng Kubernetes cho ứng dụng di động.
+
+## 1. Init
+
+~~~bash
+cd /path/to/existing-react-native-app
+aih resolve --adapters react-native --capabilities product,uiux
+aih init --adapters react-native --capabilities product,uiux --dry-run
+aih init --adapters react-native --capabilities product,uiux
+aih check
+aih skills
+~~~
+
+Nếu chỉ sửa một lỗi offline đã có ticket/AC duyệt, có thể bỏ Product và UI/UX không cần thiết, giữ Core + React Native. `aih detect` có thể nhận React Native/Expo tại thư mục target chứa `package.json`, không tự quét monorepo.
+
+## 2. Requirements & UX
+
+- BA/PO mô tả business rule: trạng thái draft, server authoritative fields, replay/dedupe, login/logout giữa chừng, đa thiết bị, mất mạng và dữ liệu nhạy cảm.
+- Tạo draft Product theo [getting started](../getting-started.md); duyệt story/AC trước khi design.
+- `harness-uiux-user-flow` và `harness-uiux-screen-planning` mô tả offline banner, pending queue, syncing, conflict, retry, auth expired và error accessibility.
+- Figma chỉ ghi khi có MCP quyền hợp lệ và gate. Khi không có Figma, Markdown screen specs vẫn là bàn giao hợp lệ.
+
+## 3. Spec và code
+
+~~~bash
+aih new-change offline-draft-sync
+aih skill harness-spec
+aih skill harness-tdd
+aih skill harness-react-native-offline-sync
+aih skill harness-react-native-device-permissions
+~~~
+
+- `offline-sync`: định nghĩa local persistence encryption/retention, idempotency key, queue/retry backoff, conflict resolution và đồng bộ lại khi token hết hạn.
+- `device-permissions`: chỉ cần nếu feature có camera/location/notification/deep link; kiểm tra iOS và Android riêng, fallback khi từ chối permission.
+- Spec chứa test matrix: airplane mode, offline restart, duplicate request, conflict, revoke session, low storage và app update.
+- Không log token/customer payload, không giả định AsyncStorage/SecureStore đã được chọn; dùng stack đang có.
+
+**Verification** — tùy project scripts/toolchain, không được Harness thực thi:
+
+~~~bash
+# Chỉ chạy sau khi xác nhận có scripts tương ứng trong package.json
+npm test
+# Expo / device build và kiểm thử emulator/thiết bị cần setup riêng
+~~~
+
+Ngoài unit tests, report thiết bị/OS và test thật trên iOS/Android, permissions denied, offline transitions và accessibility evidence.
+
+## 4. PR và phát hành
+
+- `harness-review` và `security-reviewer` kiểm tra mã hóa/scope lưu local, auth và routing.
+- `aih verify --scope all` chỉ tạo checklist; đính kèm kết quả build/device tests thực chạy.
+- Nếu dùng `devops`, đây là **release planning** chung, không phải auto publish App Store/Play Store. Approval theo signing credentials/store policy nằm ngoài `aih`.
+- Nếu app phụ thuộc backend API, xác nhận contract tương thích và liên kết PR khác repo; không stage backend từ repo mobile.
+
+**Handoff:** approved user stories/AC → offline flows → OpenSpec → persistence/sync implementation → device test evidence → reviewed PR → authorized mobile release.

package/docs/examples/spring-boot-api.md

@@ -0,0 +1,100 @@
+# Walkthrough 1 — Spring Boot API từ yêu cầu tới release
+
+**Tình huống giả định:** thêm REST API tra cứu khách hàng theo tenant vào một **repo Spring Boot hiện có**, có PostgreSQL/Oracle tùy dự án, có thể thêm Kafka Outbox và Kubernetes **nếu thật sự có**. Không có source thực tế trong walkthrough này; endpoint, SQL và lệnh test là **đề xuất cần đối chiếu với project**.
+
+**Modules:** Core + `java-spring` + `product`, bổ sung `devops,kubernetes` chỉ khi sở hữu pipeline/manifests. Xem [full SDLC](../end-to-end-workflow.md), [skills](../skill-matrix.md).
+
+## 1. Setup & input
+
+~~~bash
+cd /path/to/existing-spring-service
+aih resolve --adapters java-spring,kubernetes --capabilities product,devops
+aih init --adapters java-spring,kubernetes --capabilities product,devops --dry-run
+aih init --adapters java-spring,kubernetes --capabilities product,devops
+aih check
+aih skills
+~~~
+
+Trong service không triển khai trên Kubernetes thì **bỏ `kubernetes`**; không dùng `aih detect` thay cho việc xác nhận stack. `aih init` chỉ chép Harness, không scaffold Spring Boot.
+
+Input: source revision, business owner, endpoint contract đang có, auth/tenant rules, schema migration policy, test/build tool, environment/approver. Ghi fact và unknown trong `.harness/local.md` hoặc change riêng, không thay Core managed files.
+
+## 2. BA/PO → reviewed requirements
+
+~~~bash
+aih new-doc brd
+aih new-doc prd
+aih new-doc backlog
+aih new-doc acceptance-criteria
+aih new-doc traceability
+aih skill harness-product-business-analysis
+aih skill harness-product-prd-generation
+aih skill harness-product-acceptance-criteria
+~~~
+
+AI IDE đọc nguồn được cấp quyền, đề xuất `FR-001`: tenant chỉ xem dữ liệu của mình; `AC-US-001-01`: tenant khác trả 403/404 tùy contract đã duyệt. **Chưa có xác nhận của PO thì đây vẫn là draft.** Reviewer dùng `harness-product-document-review` để phát hiện lỗ hổng; BA/PO là người xác nhận.
+
+## 3. OpenSpec & technical review
+
+~~~bash
+aih new-change add-customer-lookup
+aih skill harness-spec
+~~~
+
+Từ approved `FR/AC`, hoàn thiện `openspec/changes/add-customer-lookup/{proposal,design,tasks}.md` và delta specs. Nội dung cần có: API status/body, JWT/LDAP principal→tenant, authorization ở service/data access, error mapping, pagination, audit, DB indexes và backward compatibility. Không suy đoán dialect hoặc thông số tải.
+
+Nếu OpenSpec CLI được cài **riêng** và version tương thích với project:
+
+~~~bash
+openspec validate add-customer-lookup --strict
+~~~
+
+Lệnh `new-change` **chỉ tạo draft**, không validate/approve spec. Gate: reviewer duyệt API/security/data boundaries.
+
+## 4. Code theo adapter skills
+
+~~~bash
+aih skill harness-java-spring-spring-api
+aih skill harness-tdd
+aih skill harness-java-spring-database-migration
+aih skill harness-java-spring-kafka-outbox
+~~~
+
+- `spring-api`: controller/service/repository theo pattern hiện có, tenant-scope server-side, DTO và HTTP contract.
+- `database-migration`: chỉ dùng **khi đổi schema**; thiết kế expand → compatible deploy → contract, rollback/data-loss risk.
+- `kafka-outbox`: chỉ dùng **khi có event publication**; transactional write, duplicate consumer delivery, retry/dead-letter.
+- `harness-tdd`: negative auth test, missing resource, validation, successful request, regression. Không tạo implementation Kafka/DB nếu requirement không cần.
+
+Lệnh verify ứng dụng **tùy repo** — dưới đây chỉ là ví dụ nếu có Maven wrapper:
+
+~~~bash
+# Kiểm tra wrapper và profile của repo trước khi chạy
+./mvnw test
+# ./mvnw verify  # nếu project cấu hình integration tests phù hợp
+~~~
+
+`aih verify --scope all` xuất checklist **không chạy Maven**. Nếu không chạy được integration test do thiếu DB, báo blocker; không ghi Pass.
+
+## 5. PR → staging → production
+
+~~~bash
+aih verify --scope all
+aih eval --scope all
+aih check
+~~~
+
+Reviewer sử dụng `harness-review` + `security-reviewer`; PR gắn change ID, approved AC, diff, actual test logs, migration sequence, unrun checks, release/rollback plan. Không tự merge.
+
+Nếu có pipeline/manifests: `harness-devops-ci-cd` → `harness-devops-docker` → `harness-kubernetes-workload-review`, `harness-kubernetes-helm-release` (nếu Helm) → `harness-devops-deployment` / `harness-kubernetes-rollout-safety`. Chỉ người/runtime được phép và có approval theo artifact/environment mới deploy; sau rollout kiểm chứng readiness + actual error/latency data.
+
+## Expected handoff (mẫu, không phải kết quả đã chạy)
+
+| Stage | Output cần bàn giao |
+| --- | --- |
+| Product | `docs/product/brd.md`, `prd.md`, `backlog.md`, `acceptance-criteria.md`, `traceability.md` approved |
+| Spec | `openspec/changes/add-customer-lookup/` reviewed |
+| Code | Endpoint + auth/contract tests + migration/event tests nếu có |
+| Review | PR, CI/test evidence, risk list, human decision |
+| Release | Image digest, environment approval, rollback steps, measured health |
+
+**Sau khi PR đã merge:** upstream OpenSpec archive/sync nếu dự án sử dụng OpenSpec; không archive khi change vẫn chưa merge.

package/docs/getting-started.md

@@ -0,0 +1,100 @@
+# 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.
+
+## 1. Cài vào project
+
+```bash
+npm install -g @manhd_d/ai-harness
+cd /path/to/existing-project
+aih init --adapters java-spring
+aih check
+```
+
+Chọn module theo nhu cầu, không cần cài cả bộ:
+
+| Nhu cầu | Tham số cho `aih 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.
+
+## 2. Ghi context và bắt đầu giao việc
+
+Điền `.harness/local.md` bằng thông tin thực của project:
+
+- 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ữ.
+
+Mở project trong AI IDE và giao yêu cầu, ví dụ:
+
+> Đọ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.
+
+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.
+
+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ý.
+
+## 3. Tài liệu và spec khi cần
+
+Với capability `product`:
+
+```bash
+aih 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:
+
+```bash
+aih new-change add-customer-search
+```
+
+Đây là bản nháp trong `openspec/changes/add-customer-search/`, chưa phải spec được duyệt. 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.
+
+`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` | Thêm kiểm tra sự hiện diện của công cụ; không xác nhận công cụ chạy được |
+| `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:
+
+```bash
+npm install -g @manhd_d/ai-harness@latest
+aih --version
+aih check
+aih update --dry-run
+aih update
+aih 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
+
+- [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.