@manhd_d/ai-harness 0.6.0 → 0.6.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/CHANGELOG.md +28 -0
  2. package/README.md +40 -298
  3. package/bin/aih.js +0 -0
  4. package/cli/main.js +7 -2
  5. package/docs/architecture.md +1 -1
  6. package/docs/cli.md +7 -2
  7. package/docs/getting-started.md +64 -112
  8. package/docs/npm-release.md +38 -51
  9. package/docs/release-policy.md +1 -1
  10. package/docs/versioning.md +11 -4
  11. package/harness.yaml +1 -1
  12. package/package.json +1 -1
  13. package/templates/AGENTS.md +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,16 @@
1
1
  # Changelog
2
2
 
3
+ ## Unreleased — Simpler onboarding and release regression coverage
4
+ - Start with npm install, minimal module selection and project context; clarify advisory commands and the two-step CLI/snapshot update.
5
+ - Link progressive context rules from the generated AGENTS entry point; retain project ownership and runtime boundaries.
6
+ - Exercise legacy migrations against both the current and next patch version; document recovery from a failed immutable release tag.
7
+
8
+ ## Unreleased — Release validation compatibility
9
+ - Accept Release Please's linked version headings for version 0.6.1 in both validation commands while retaining strict matching of the current distribution version.
10
+
11
+ ## Unreleased — Release migration tests
12
+ - Fix legacy upgrade tests to assert the current Harness source version rather than hardcoding 0.6.0, allowing Release Please version PRs to pass CI without weakening migration checks.
13
+
3
14
  ## Unreleased — npm 12 pack metadata compatibility
4
15
  - Make package smoke tests support both npm 10/11 array-form and npm 12 package-keyed JSON output from `npm pack --json`.
5
16
  - Validate archive metadata before accessing `files`, with explicit diagnostics instead of an undefined-property crash.
@@ -42,6 +53,23 @@
42
53
  - Check release metadata consistency and establish single-release-PR version discipline; retain v0.6.0 until a dedicated release PR.
43
54
 
44
55
 
56
+ ## [0.6.2](https://github.com/manh0303/ai-harness/compare/v0.6.1...v0.6.2) (2026-10-11)
57
+
58
+
59
+ ### Bug Fixes
60
+
61
+ * **release:** support linked Release Please changelog headings ([8084940](https://github.com/manh0303/ai-harness/commit/80849408a349305ef5cdfb0c0eb0206ea8242eb8))
62
+ * simplify onboarding and guard release version migrations ([43efbb2](https://github.com/manh0303/ai-harness/commit/43efbb24e26d190b7a2b8dd2fbd5a9a5ee5368a1))
63
+ * **test:** unblock Release Please version bump CI ([63ba179](https://github.com/manh0303/ai-harness/commit/63ba17974cafad40e6ff5b483c126afdfc49df44))
64
+
65
+ ## [0.6.1](https://github.com/manh0303/ai-harness/compare/v0.6.0...v0.6.1) (2026-10-11)
66
+
67
+
68
+ ### Bug Fixes
69
+
70
+ * **release:** automate npm publishing with Release Please and OIDC ([d39f284](https://github.com/manh0303/ai-harness/commit/d39f2843bd2700d9be8f70981135b8502b691303))
71
+ * **release:** automate npm releases with Release Please and OIDC ([0b293c5](https://github.com/manh0303/ai-harness/commit/0b293c520601cf2f21ed10d0dd3973f659647cc0))
72
+
45
73
  ## 0.6.0 — DevOps capability and Kubernetes adapter candidate
46
74
  - Add `devops` capability with six namespaced CI/CD, Docker, deployment, infrastructure, observability and incident-response skills plus two review-gated workflows.
47
75
  - Add `kubernetes` adapter with Helm/workload/rollout skills, advisory verification checks and two safety evaluation scenarios.
package/README.md CHANGED
@@ -1,329 +1,71 @@
1
- # ai-harness
1
+ # AI Harness
2
2
 
3
- Framework tái sử dụng để hướng dẫn AI làm việc theo **Spec → Code → Test → Review** trong nhiều dự án.
4
- Core dùng chung; adapter chứa quy chuẩn công nghệ; CLI cài một bản có version vào từng repository.
3
+ **Bộ quy tắc, skills và workflows tái sử dụng để AI hỗ trợ phát triển phần mềm theo quy trình _Spec → Code → Test → Review_.**
5
4
 
6
- **Trạng thái:** 0.6.0 candidate; 6 adapters, 4 optional capabilities, 53 skills và CLI Node.js 22+ với lệnh `aih`, không cần Python hay thư viện runtime ngoài.
7
- Gói `@manhd_d/ai-harness` chưa phát hành lên npm registry; hiện cài từ repository private hoặc tarball.
8
- Harness không tự gọi LLM, không tự sinh ứng dụng, không tạo agent runtime, không tự merge/deploy.
9
- Các role/skill hướng dẫn assistant đang dùng; quyền thực tế do IDE/runtime, Git và CI kiểm soát.
5
+ AI Harness cài context vào từng repository qua CLI `aih`. Có thể kết hợp các technology adapters và capabilities theo nhu cầu; không phụ thuộc một IDE hay mô hình AI cụ thể.
10
6
 
11
- ## Hướng dẫn quy trình phát triển phần mềm (full SDLC)
7
+ > Yêu cầu **Node.js 22+**. CLI không tự chạy LLM, viết code, phê duyệt tài liệu, merge PR hoặc deploy.
12
8
 
13
- Nếu lần đầu sử dụng, đọc theo thứ tự: **Cài → Product/BA/PO → UI/UX → OpenSpec → Code → Test/Review → CI/CD → Vận hành**.
14
-
15
- - **[Getting started](docs/getting-started.md)** — cài CLI, chọn module, tạo change và kiểm tra.
16
- - **[Hai luồng tài liệu](docs/documentation-workflows.md)** — idea-driven và document-driven, lưu trữ, version và handoff.
17
- - **[Full SDLC: Idea → Production](docs/end-to-end-workflow.md)** — input/output, approval gate, cách phối hợp capabilities/adapters.
18
- - **[Ma trận 53 skills](docs/skill-matrix.md)** — tra cứu skills theo stage/công nghệ và ID thật.
19
- - **[Agent handoffs](docs/agent-handoffs.md)** — roles, trách nhiệm, ownership, evidence và bàn giao.
20
- - **Walkthrough:** [Spring Boot API](docs/examples/spring-boot-api.md) · [Full-stack Next.js + Spring](docs/examples/fullstack-web.md) · [React Native](docs/examples/react-native-app.md) · [Python AI/RAG](docs/examples/ai-rag-service.md) · [Astro micro-tools](docs/examples/astro-micro-tools.md) · [Astro + AdSense](docs/examples/astro-adsense-microtools.md).
21
-
22
- Harness cung cấp hướng dẫn cho AI runtime, **không** tự điều phối AI agent, tạo code, chạy test, merge hay deploy.
23
-
24
- ## Bắt đầu
25
-
26
- **Để thử adapter Astro trước khi PR được merge**, checkout branch `feat/astro-lightweight-adapter` trước `npm pack`. Sau merge, ưu tiên commit/tag chính thức đã review. CLI vẫn báo 0.6.0 vì adapter mới chưa được phát hành qua release PR riêng.
27
-
28
- Cài từ source đã review bằng tài khoản có quyền repository private:
9
+ ## Cài đặt và dùng nhanh
29
10
 
30
11
  ```bash
31
- git clone git@github.com:manh0303/ai-harness.git
32
- cd ai-harness
33
- # Nếu thử các tính năng chưa merge trong PR #10:
34
- git switch feat/astro-lightweight-adapter
35
- # Sau khi merge, ưu tiên tag/commit đã review thay vì feature branch.
36
- npm pack
37
- npm install -g ./manhd_d-ai-harness-0.6.0.tgz
12
+ npm install -g @manhd_d/ai-harness
38
13
 
39
- cd /path/to/my-backend
40
- aih init --adapters java-spring --dry-run
14
+ # Chạy trong một project đã tồn tại
41
15
  aih init --adapters java-spring
42
16
  aih check
43
- aih new-change add-order
44
17
  ```
45
18
 
46
- Sau khi cài, dùng `aih` từ bất kỳ repository ứng dụng nào. Đích mặc định là thư mục hiện tại;
47
- `--target /path/to/project` vẫn được hỗ trợ. Thư mục đích phải tồn tại.
48
- `aih --help` xem lệnh, `aih --version` xem phiên bản công cụ.
49
-
50
- Khi chủ sở hữu đã phát hành npm package công khai, cách cài sẽ là
51
- `npm install -g @manhd_d/ai-harness@0.6.0`. **Lệnh registry này chưa dùng được chỉ vì PR đã merge.**
52
- Có thể cài tarball vào devDependencies rồi dùng `npx --no-install aih init` nếu không muốn cài global.
53
- Xem [hướng dẫn đóng gói/phát hành](docs/npm-release.md).
19
+ Tiếp theo, ghi stack, nghiệp vụ và lệnh test vào `.harness/local.md`; mở project trong AI IDE và yêu cầu assistant đọc `AGENTS.md` trước khi làm việc. Bạn giao task bình thường, AI đọc skill liên quan và báo cáo test thực chạy.
54
20
 
55
- Đây là cài **quy trình và context**, không scaffold source code Spring/React và không sửa build file.
56
-
57
- ## Hai chế độ tài liệu — Idea-driven / Document-driven
58
-
59
- **Idea-driven:** Từ ý tưởng của developer → thảo luận → nghiên cứu có nguồn → PRD-lite hoặc BRD/PRD/SRS/use cases → duyệt → OpenSpec. **Document-driven:** Từ BRD/PRD/SRS/Confluence đã có của BA → kiểm tra source version, gap và traceability → technical spec và code. Không tự ghi đè tài liệu BA đã duyệt. Hai chế độ có thể sử dụng luân phiên trong cùng một dự án.
60
-
61
- Xem hai hướng dẫn thực hành: [Bắt đầu từ ý tưởng](docs/examples/idea-driven-project.md) · [Dự án đã có tài liệu BA](docs/examples/document-driven-project.md). Xem thêm [Documentation workflows](docs/documentation-workflows.md) và [Confluence integration contract](integrations/confluence/README.md). `aih` only creates templates and ships instructions; AI host handles research/content, and external publishing requires independently authorized tooling.
62
-
63
- ```bash
64
- aih init --capabilities product
65
- aih new-doc idea # docs/discovery/idea.md
66
- aih new-doc research # docs/discovery/research.md
67
- aih new-doc prd-lite # docs/product/prd-lite.md
68
- aih new-doc srs # docs/product/srs.md
69
- aih new-doc use-cases # docs/product/use-cases.md
70
- ```
71
-
72
- ## Product documentation capability — BA / PM / PO
73
-
74
- Capability `product` cung cấp 5 role contracts, 13 skills, 5 workflows và 16 templates
75
- để chuyển ý tưởng hoặc nguồn Confluence được cấp quyền thành BRD, PRD, user stories,
76
- acceptance criteria và requirement traceability. Mọi tài liệu hoàn thiện là dữ liệu
77
- **do dự án sở hữu**, nằm trong `docs/discovery/` (ý tưởng, nghiên cứu) hoặc `docs/product/` (yêu cầu) của repository ứng dụng.
78
-
79
- ```bash
80
- # Khởi tạo dự án mới chỉ cần Product
81
- aih init --capabilities product
82
- # Kết hợp Product + UI/UX + React
83
- aih init --capabilities product,uiux --adapters react-nextjs
84
- # Tạo file mẫu để AI điền bằng tài liệu được cấp phép, không tự điền nội dung
85
- aih new-doc brd
86
- aih new-doc prd
87
- aih new-doc backlog
88
- aih new-doc acceptance-criteria
89
- aih new-doc traceability
90
- aih skills
91
- aih skill harness-product-prd-generation
92
- aih check
93
- ```
94
-
95
- Dự án đã cài đặt cần sửa `.harness/project.json`, bổ sung `product` vào
96
- `capabilities` rồi chạy `aih update --dry-run`, `aih update`, `aih check`.
97
- CLI chỉ tạo **bản mẫu** khi dùng `new-doc`. Việc phân tích và điền nội dung cần
98
- AI runtime có quyền đọc nguồn, kiểm tra bằng chứng và được BA/PM/PO phê duyệt.
99
- Xem [Product capability](capabilities/product/README.md).
100
-
101
- ## Astro cho micro-tools, React Islands và Cloudflare
102
-
103
- Chọn [adapter Astro](adapters/astro/README.md) nếu bạn làm trang công cụ nhỏ, SEO landing page hoặc portfolio nhiều utilities. **Static-first:** TypeScript/browser xử lý trước; React Islands chỉ cho UI tương tác; Cloudflare Workers/API và MFE chỉ khi có nhu cầu thực. Astro Islands không phải các micro frontend deploy độc lập. Xem [walkthrough đầy đủ](docs/examples/astro-micro-tools.md).
104
-
105
- ```bash
106
- cd /path/to/existing-astro-project
107
- aih resolve --adapters astro --capabilities product,uiux
108
- aih init --adapters astro --capabilities product,uiux --dry-run
109
- aih init --adapters astro --capabilities product,uiux
110
- aih check
111
- aih skills
112
- aih skill harness-astro-project-architecture
113
- aih skill harness-astro-islands
114
- aih skill harness-astro-cloudflare
115
- aih verify --scope all # advisory; không tự chạy build/deploy
116
- ```
117
-
118
- Không bắt buộc Product/UIUX; nếu chỉ cần code, dùng `aih init --adapters astro`. Trong dự án đã cài Harness: sửa `.harness/project.json` và chạy `aih update --dry-run`, `aih update`, `aih check`. `aih detect` nhận diện `astro` từ `package.json`; `react-dom` vì React Islands không tự khiến CLI cài `react-nextjs` trừ khi dự án còn dùng `next`. CLI chỉ cài rules/skills, **không** tạo Astro app, cài React hay deploy lên Cloudflare.
119
-
120
- ## Monetization — kiếm tiền hợp lệ từ quảng cáo
121
-
122
- Capability `monetization` độc lập với Astro, React/Next.js và các adapter khác. Với website micro-tools miễn phí, ưu tiên **giá trị sản phẩm → SEO → kiểm tra AdSense/consent → ad placement an toàn → đo traffic và Page RPM thực tế**. Năm skills giúp phân tích các bước; không tự tạo tài khoản, xin duyệt site, nhúng ad code hoặc kéo doanh thu từ Google.
123
-
124
- ```bash
125
- # Website Astro có mục tiêu doanh thu quảng cáo
126
- aih resolve --adapters astro --capabilities monetization
127
- aih init --adapters astro --capabilities monetization --dry-run
128
- aih init --adapters astro --capabilities monetization
129
- aih check
130
- aih skill harness-monetization-adsense-integration
131
- aih skill harness-monetization-ad-placement-ux
132
- aih skill harness-monetization-analytics-revenue
133
- aih verify --scope capabilities # manual checklist, không chạy provider checks
134
- ```
135
-
136
- Nếu cần Product + UI/UX thì chọn `--capabilities product,uiux,monetization`. Dự án đã cài Harness phải sửa `.harness/project.json`, rồi `aih update --dry-run`, `aih update`, `aih check`. Templates monetization nằm trong `.harness/capabilities/monetization/templates/`; tự copy vào `docs/monetization/` khi được quyền — `aih new-doc` chỉ dùng cho Product.
137
-
138
- Hướng dẫn: [Monetization](docs/monetization.md) · [Astro + AdSense walkthrough](docs/examples/astro-adsense-microtools.md) · [Capability README](capabilities/monetization/README.md). Không hứa AdSense sẽ phê duyệt hay đảm bảo thu nhập; quảng cáo phải tuân thủ chính sách và không được nhầm với nút tool.
139
-
140
- ## Optional UI/UX capability
141
-
142
- UI/UX là **capability** độc lập với technology adapter. Chọn khi cần chuyển ý tưởng, PRD hoặc
143
- Confluence thành requirement, UX flow, screen inventory rồi tạo Figma bằng agent đã kết nối.
144
- Không tự động gọi LLM, đọc Confluence hay viết Figma. Phải cấp quyền MCP cho host và duyệt trước
145
- khi chỉnh sửa file Figma hoặc màn hình đã được duyệt.
146
-
147
- ```bash
148
- # Dự án chỉ cần design, không cần adapter công nghệ
149
- aih init --capabilities uiux
150
-
151
- # Dự án vừa React vừa thiết kế UI/UX
152
- aih init --adapters react-nextjs --capabilities uiux
153
-
154
- # Sau khi cài, xem metadata kỹ năng trước, chỉ nạp nội dung khi cần
155
- aih skills
156
- aih skill harness-uiux-figma-design
157
-
158
- # Bổ sung UI/UX vào một project đã cài: sửa mảng capabilities
159
- # trong .harness/project.json, sau đó:
160
- aih update --dry-run
161
- aih update
162
- aih check
163
- ```
21
+ Thêm `--capabilities product` khi cần tài liệu BA; `aih new-doc prd-lite` tạo template, `aih new-change <id>` tạo spec nháp khi cần. Không bắt mọi task tạo đủ tài liệu. Xem [Getting started](docs/getting-started.md) và [CLI reference](docs/cli.md).
164
22
 
165
- `aih list` liệt kê cả adapters và capabilities; `aih skills` chỉ trả tên + mô tả,
166
- `aih skill <name>` mới trả nội dung đầy đủ của skill đã cài và được lock. Không có network
167
- download độc lập: npm tarball vẫn chứa mọi capability, nhưng dự án chỉ nhận capability đã chọn.
168
- Xem [tài liệu capability](capabilities/uiux/README.md) và [quy trình docs-to-figma](capabilities/uiux/workflows/docs-to-figma.md).
23
+ **Phân biệt:** `aih check` kiểm tra file Harness; `aih verify` xuất checklist; build/test ứng dụng do AI host hoặc CI thực chạy. CLI không bảo đảm AI sẽ tuân thủ hướng dẫn; xem [đánh giá hành vi](evals/README.md).
169
24
 
170
- ## DevOps capability + Kubernetes adapter
25
+ ## Thành phần
171
26
 
172
- `devops` cung cấp 6 skills cho CI/CD, Docker, release, infrastructure review,
173
- observability và incident response, cùng 2 workflows có cổng phê duyệt.
174
- `kubernetes` là adapter riêng cho manifest, Helm và rollout safety.
175
-
176
- ```bash
177
- aih init --adapters java-spring,kubernetes --capabilities devops
178
- # Kết hợp cả Product + UI/UX + DevOps
179
- aih init --adapters java-spring,kubernetes --capabilities product,uiux,devops
180
- aih skills
181
- aih skill harness-devops-deployment
182
- aih verify # chỉ gợi ý kiểm tra, không chạy
183
- aih check
184
- ```
185
-
186
- Các lệnh không gọi cloud API, không triển khai production hay cấp quyền kết nối.
187
- Xem [DevOps capability](capabilities/devops/README.md) và [quy tắc adapters](docs/adapters.md).
188
-
189
- ## Module composition & evaluation (unreleased)
190
-
191
- Module manifests có `module_version` và các metadata phụ thuộc, khuyến nghị, xung đột. Kiểm tra trước khi cài:
192
-
193
- ```bash
194
- aih resolve --adapters java-spring,kubernetes --capabilities product,uiux,devops
195
- aih verify --scope all # checklist tư vấn, không chạy
196
- aih eval --scope all # báo cáo chưa chấm, không gọi model
197
- ```
198
-
199
- Chế độ mặc định không có `--scope` vẫn chỉ gồm adapters. Foundation Hardening đã có trong source; đây vẫn là source candidate, chưa chứng minh npm registry có bản phát hành. Xem [release policy](docs/release-policy.md).
200
-
201
- ## Chọn adapter
202
-
203
- | Dự án | `--adapters` |
27
+ | Nhóm | Hỗ trợ |
204
28
  | --- | --- |
205
- | Java / Spring Boot | `java-spring` |
206
- | React hoặc Next.js | `react-nextjs` |
207
- | Astro micro-tools / static SEO | `astro` |
208
- | React Native / Expo | `react-native` |
209
- | Python AI, agent hoặc RAG | `ai-python` |
210
- | Kubernetes / Helm workloads | `kubernetes` |
211
- | Full-stack trong cùng repository | `java-spring,react-nextjs` |
212
- | Chỉ core rules và workflow | Bỏ tùy chọn `--adapters` |
213
-
214
- AI bằng Java có thể dùng `java-spring` cùng skill `harness-ai-evaluation`; không bắt buộc chuyển sang Python.
215
- Với multi-repo, cài vào từng repo có thực hiện công việc. Ghi danh sách repo và thứ tự merge trong change.
29
+ | **Core** | Rules, agent roles, skills, workflows, review & verification |
30
+ | **Adapters** | Java Spring Boot, React/Next.js, React Native, Python AI/RAG, Kubernetes, Astro |
31
+ | **Capabilities** | Product/BA/PO, UI/UX & Figma, DevOps, Monetization/AdSense |
32
+ | **OpenSpec** | Template cho proposal, design, tasks và spec có review |
216
33
 
217
- ## Nhận diện stack và dùng adapter
34
+ Bạn chỉ chọn module cần dùng, ví dụ `aih init --adapters astro --capabilities monetization` cho website công cụ nhỏ có quảng cáo. Xem [Astro adapter](adapters/astro/README.md) và [Monetization capability](capabilities/monetization/README.md).
218
35
 
219
- ```bash
220
- aih list
221
- aih detect
222
- aih init --detect --dry-run
223
- aih init --detect
224
- aih verify
225
- aih eval
226
- ```
36
+ ## Hai luồng làm việc
227
37
 
228
- `detect` báo adapter đề xuất kèm bằng chứng; chỉ đọc file ngay trong thư mục đích, không quét đệ quy
229
- monorepo. Dùng `--target apps/backend` cho từng module. Spring cần dấu hiệu Spring Boot trong Maven/Gradle;
230
- React Native được phân biệt với web; AI/Python dựa trên tên thư viện trong pyproject/requirements.
231
- Đây là heuristic: có thể bỏ sót dependency gián tiếp hoặc khớp comment. Review kết quả trước khi cài.
232
- `init --detect` là lựa chọn chủ động; không tìm thấy stack thì dừng. `init` không có flag vẫn cài core-only.
233
- Có thể dùng `--adapters` để chọn chính xác. Update giữ lựa chọn trong project.json, không tự nhận diện lại.
38
+ - **Idea-driven:** Ý tưởng → thảo luận/nghiên cứu → BRD/PRD/SRS → UI/UX → spec → code.
39
+ - **Document-driven:** BRD/PRD/SRS/Confluence đã có → phân tích gap → technical spec → code.
234
40
 
235
- Mỗi adapter có `adapter.yaml`, `rules/`, `skills/`, `checks/verification.yaml` và `evals/cases.json`.
236
- Skills của adapter đã chọn được cài vào `.agents/skills/harness-<adapter>-*`; Core giữ TDD/debug/review dùng chung.
237
- `aih verify` chỉ xuất checklist và lệnh gợi ý, **không chạy test/build**. `aih eval` xuất tình huống và mẫu
238
- báo cáo chưa chấm; `aih eval --report report.json` tổng hợp điểm có bằng chứng, **không gọi model**.
239
- Xem [hướng dẫn adapter và đánh giá](docs/adapters.md) trước khi điền báo cáo.
41
+ Chi tiết: [Documentation workflows](docs/documentation-workflows.md) · [Confluence integration](integrations/confluence/README.md).
240
42
 
241
- ## Dự án nhận những gì?
43
+ ## Tài liệu
242
44
 
243
- | Đường dẫn | Cách quản lý |
45
+ | Mục đích | Hướng dẫn |
244
46
  | --- | --- |
245
- | `AGENTS.md` | Thêm/cập nhật một block có marker; giữ nguyên nội dung bên ngoài |
246
- | `.harness/core/`, `adapters/`, `integrations/`, `templates/` | Snapshot framework, được lock bằng hash |
247
- | `.agents/skills/harness-*/` | Skill dùng trong project; cách kích hoạt tùy assistant |
248
- | `.harness/lock.json` | Version, adapters và SHA-256 của nội dung được quản lý |
249
- | `.harness/project.json` | Dự án sở hữu; chọn adapter |
250
- | `.harness/local.md` | Dự án sở hữu; domain, build command, convention riêng |
251
- | `openspec/config.yaml` | Chỉ tạo nếu chưa có; giữ cấu hình hiện tại |
252
- | `openspec/changes/<id>/` | Chỉ tạo khi gọi `new-change`; còn TODO cần hoàn thiện |
253
-
254
- Commit các file đã cài vào repository ứng dụng để cả team dùng đúng một phiên bản. Không commit secrets.
255
- Hãy hướng assistant đọc `AGENTS.md`; việc tự phát hiện file/skill phụ thuộc công cụ bạn sử dụng.
256
- CLI không cấu hình tài khoản, plugin cá nhân hoặc MCP server của assistant.
257
-
258
- ## Tùy biến và cập nhật
259
-
260
- Cài phiên bản công cụ mới trước, rồi chạy `aih update` trong từng dự án để cập nhật snapshot.
261
- Lockfile từ CLI Python 0.1 vẫn được hỗ trợ; xem [migration](docs/versioning.md).
262
-
263
- Thêm quy ước vào `.harness/local.md` hoặc phần ngoài marker trong `AGENTS.md`.
264
- Muốn đổi stack: chỉnh mảng `adapters` trong `.harness/project.json`, rồi chạy update.
265
-
266
- ```bash
267
- aih update --dry-run
268
- aih update
269
- aih check
270
- aih doctor
271
- ```
272
-
273
- Source mặc định là package đã cài chứa CLI; có thể dùng `--source /path/to/reviewed-checkout` với init/update.
274
- Cập nhật dừng khi file managed bị sửa, không có chế độ force. Đưa tùy biến sang local.md rồi restore
275
- file managed từ commit cài trước đó. Major upgrade cần `--allow-major`; downgrade dùng Git revert.
276
- Dry-run không để lại thay đổi file, nhưng tạo/xóa marker khóa trong lúc lập kế hoạch nên cần quyền ghi.
277
- Doctor chỉ kiểm tra tool có trên PATH; không xác nhận version hay build chạy thành công.
278
-
279
- ## OpenSpec
280
-
281
- Framework tạo cấu trúc tương thích workflow `spec-driven` và không cài OpenSpec thay bạn.
282
- `new-change` tạo proposal/design/tasks/delta spec bằng template đã pin trong project; đây là bản nháp.
283
- Hoàn thiện TODO, review yêu cầu, rồi dùng OpenSpec CLI do dự án cài và pin phiên bản:
284
-
285
- ```bash
286
- # Chạy tại repository ứng dụng sau khi cài OpenSpec theo hướng dẫn upstream.
287
- openspec validate add-order --strict
288
- ```
47
+ | Bắt đầu | [Getting started](docs/getting-started.md) |
48
+ | Phát triển end-to-end | [Full SDLC](docs/end-to-end-workflow.md) · [Agent handoffs](docs/agent-handoffs.md) |
49
+ | Tra cứu kỹ năng | [Skill matrix](docs/skill-matrix.md) · [CLI reference](docs/cli.md) |
50
+ | Tài liệu sản phẩm | [Idea-driven example](docs/examples/idea-driven-project.md) · [Document-driven example](docs/examples/document-driven-project.md) |
51
+ | Ví dụ backend/full-stack | [Spring Boot API](docs/examples/spring-boot-api.md) · [Spring + Next.js](docs/examples/fullstack-web.md) |
52
+ | Ví dụ mobile/AI | [React Native](docs/examples/react-native-app.md) · [Python AI/RAG](docs/examples/ai-rag-service.md) |
53
+ | Micro-tools/website | [Astro micro-tools](docs/examples/astro-micro-tools.md) · [Astro + AdSense](docs/examples/astro-adsense-microtools.md) · [Monetization](docs/monetization.md) |
54
+ | Phát hành npm | [Release guide](docs/npm-release.md) · [Changelog](CHANGELOG.md) |
289
55
 
290
- Xem [docs/openspec.md](docs/openspec.md). Chỉ archive sau khi mọi PR liên quan đã merge.
291
-
292
- ## Kiểm thử
56
+ ## Kiểm tra và cập nhật
293
57
 
294
58
  ```bash
59
+ # Trong repository AI Harness (maintainer)
295
60
  npm test
296
61
  npm run validate
297
62
  npm run test:package
298
- ```
299
-
300
- Test CLI chạy offline trên thư mục tạm: cài/update, preservation, drift, collision, traversal/symlink,
301
- adapter selection, version guard, reproducibility, rollback và tạo change. CI cấu hình Node.js 22/24 trên Linux và Windows.
302
- [evals/README.md](evals/README.md) có bộ tình huống và công cụ tổng hợp đánh giá hành vi AI riêng.
303
- Test CLI pass không có nghĩa đã chạy Spring/Next/native build hay live evaluation của LLM.
304
63
 
305
- ## License
306
-
307
- Dự án được cấp phép theo [MIT License](LICENSE) — cho phép sử dụng, sửa đổi và phân phối (kể cả thương mại) theo các điều kiện trong giấy phép. Repository vẫn **private** và package npm đã cấu hình `public`; việc thêm license không tự thay đổi quyền truy cập hoặc phát hành package.
308
-
309
- ## Tài liệu
310
-
311
- - [Getting started](docs/getting-started.md)
312
- - [Documentation workflows](docs/documentation-workflows.md)
313
- - [Walkthrough Idea-driven](docs/examples/idea-driven-project.md)
314
- - [Walkthrough Document-driven](docs/examples/document-driven-project.md)
315
- - [Astro micro-tool walkthrough](docs/examples/astro-micro-tools.md)
316
- - [Website advertising monetization](docs/monetization.md)
317
- - [Astro + AdSense walkthrough](docs/examples/astro-adsense-microtools.md)
318
- - [Full SDLC](docs/end-to-end-workflow.md)
319
- - [Skill matrix](docs/skill-matrix.md)
320
- - [Agent handoffs](docs/agent-handoffs.md)
321
- - [Kiến trúc và ranh giới trách nhiệm](docs/architecture.md)
322
- - [Versioning và migration](docs/versioning.md)
323
- - [CLI contract](docs/cli.md)
324
- - [Phân tích workspace tham khảo](docs/reference-analysis.md)
325
- - [Hướng dẫn đóng góp](CONTRIBUTING.md)
326
- - [Thay đổi phiên bản](CHANGELOG.md)
64
+ # Nâng CLI global, rồi cập nhật snapshot trong project
65
+ npm install -g @manhd_d/ai-harness@latest
66
+ aih update --dry-run
67
+ aih update
68
+ aih check
69
+ ```
327
70
 
328
- `harness.yaml` cố ý dùng JSON-compatible YAML 1.2 để CLI đọc bằng `JSON.parse`. Không dùng cú pháp YAML
329
- khác cho file này. `openspec/config.yaml` vẫn là YAML thông thường do OpenSpec đọc.
71
+ **License:** [MIT](LICENSE). GitHub source có thể private; package `@manhd_d/ai-harness` được phát hành công khai qua npm.
package/bin/aih.js CHANGED
File without changes
package/cli/main.js CHANGED
@@ -16,8 +16,8 @@ Usage: aih <command> [options]
16
16
  verify Show installed advisory checks (does not execute)
17
17
  eval Emit evaluation template, or score --report <file>
18
18
  init Install rules and selected adapters
19
- update Update the installed snapshot, preserving project content
20
- check Check installed file hashes and adapter selection
19
+ update Apply the installed CLI bundle to the project (no download)
20
+ check Check Harness file integrity, not application tests
21
21
  doctor Check installation and tool presence
22
22
  new-change <id> Create an OpenSpec draft using installed templates
23
23
  new-doc <type> Scaffold a Product/Discovery document draft (requires product capability)
@@ -35,6 +35,11 @@ Options:
35
35
  -h, --help Show help
36
36
  -v, --version Show installed CLI version
37
37
 
38
+ Start: init → fill .harness/local.md → ask your AI host to read AGENTS.md.
39
+ The host runs application tests; verify only prints a checklist.
40
+ Update a global CLI with npm install -g @manhd_d/ai-harness@latest,
41
+ then run aih update --dry-run, aih update, and aih check in the project.
42
+
38
43
  Examples:
39
44
  aih init --adapters java-spring --capabilities uiux
40
45
  aih init --adapters astro --capabilities product,uiux
package/docs/architecture.md CHANGED
@@ -104,4 +104,4 @@ DevOps is an optional stack-neutral capability for release procedures and SRE; t
104
104
 
105
105
  ## Documented end-to-end usage
106
106
 
107
- The cross-module route is described in [Getting started](getting-started.md), [Full SDLC](end-to-end-workflow.md), [48-skill matrix](skill-matrix.md) and [Agent handoffs](agent-handoffs.md). All roles/skills remain instruction contracts. The four [stack walkthroughs](examples/spring-boot-api.md) illustrate permitted integrations, not a runnable scaffold or orchestration engine.
107
+ The cross-module route is described in [Getting started](getting-started.md), [Full SDLC](end-to-end-workflow.md), [Skill matrix](skill-matrix.md) and [Agent handoffs](agent-handoffs.md). All roles/skills remain instruction contracts. The four [stack walkthroughs](examples/spring-boot-api.md) illustrate permitted integrations, not a runnable scaffold or orchestration engine.
package/docs/cli.md CHANGED
@@ -12,7 +12,7 @@ Exit 0 means the requested operation succeeded; 1 means validation/I/O/drift fai
12
12
  | resolve | --source; --adapters a,b; --capabilities a,b | Validate module selection and compatibility; read-only |
13
13
  | verify | --scope adapters/core/capabilities/all | Read installed advisory checks; executed false, no subprocesses |
14
14
  | eval | --scope adapters/core/capabilities/all; --report FILE | Emit unscored template or aggregate reviewed report; no model calls |
15
- | init | --detect OR --adapters a,b; --source; --dry-run; --allow-major | Install a snapshot; exact rerun is idempotent |
15
+ | init | --detect OR --adapters a,b; --capabilities a,b; --source; --dry-run; --allow-major | Install a snapshot; exact rerun is idempotent |
16
16
  | update | --source; --dry-run; --allow-major | Update unedited owned files and seed missing project files |
17
17
  | check | none | Compare installed files/block with lock and selection; no writes |
18
18
  | doctor | none | check plus executable presence on PATH; no execution |
@@ -22,10 +22,15 @@ Exit 0 means the requested operation succeeded; 1 means validation/I/O/drift fai
22
22
  | skill NAME | none | Read one installed, locked skill |
23
23
 
24
24
  All commands default --target to the current directory. --source defaults to the installed package.
25
+ For a global install, upgrade the CLI with `npm install -g @manhd_d/ai-harness@latest` before
26
+ `aih update --dry-run` and `aih update`. Update never fetches npm. `aih --version` reports the CLI
27
+ version; `aih check` reports the project snapshot version. For a local install, update the local
28
+ dependency and use `npx aih`. Application tests must be executed separately.
25
29
  --help/-h and --version/-v are available. Unknown, duplicate and inapplicable flags fail.
26
30
  Source and target cannot contain one another, except source inside target/node_modules for local npm installs. Symlinks in roots, source
27
31
  payload or destination paths are rejected. IDs are lowercase hyphenated slugs; archive is reserved.
28
- Astro projects are detected from `astro` in package.json dependencies; `react-dom` used only for Astro islands is not a standalone React/Next.js detection when `next` is absent. Explicit `--adapters astro,react-nextjs` remains valid. `aih init --adapters astro` installs static-first rules/skills but no Astro packages or Cloudflare deployment.\nSelection changes belong in .harness/project.json; unknown or duplicate adapters fail validation.
32
+ Astro projects are detected from `astro` in package.json dependencies; `react-dom` used only for Astro islands is not a standalone React/Next.js detection when `next` is absent. Explicit `--adapters astro,react-nextjs` remains valid. `aih init --adapters astro` installs static-first rules/skills but no Astro packages or Cloudflare deployment.
33
+ Selection changes belong in .harness/project.json; unknown or duplicate adapters fail validation.
29
34
 
30
35
  ## Optional monetization capability
31
36
 
package/docs/getting-started.md CHANGED
@@ -1,148 +1,100 @@
1
- # Getting started — cài và sử dụng AI Harness
1
+ # Bắt đầu với AI Harness
2
2
 
3
- AI Harness phân phối **rules, role contracts, skills và workflows** tới repository ứng dụng. Lệnh `aih` là CLI chạy offline, không phải AI agent runner: nó không tạo ứng dụng, đọc Confluence, tạo Figma, chạy test, gọi LLM, merge PR hay deploy.
3
+ **Cài một lần → ghi context dự án → giao việc cho AI → kiểm tra kết quả.**
4
4
 
5
- **Đọc theo thứ tự:** [Full SDLC](end-to-end-workflow.md) → [Skill matrix](skill-matrix.md) → [Agent handoffs](agent-handoffs.md) → [Ví dụ theo stack](#ví-dụ-thực-hành).
5
+ 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.
6
6
 
7
- ## 1. Chuẩn bị
7
+ ## 1. Cài vào project
8
8
 
9
- - Node.js >=22, Git và npm (cần quyền repository private chỉ khi cài từ source).
10
- - Một **repository ứng dụng đã tồn tại** và AI IDE/assistant có thể đọc file trong repository đó.
11
- - Chỉ kết nối GitHub, Confluence, Figma hay nền tảng khác trong AI host khi cần, theo quyền đã phê duyệt.
12
- - **OpenSpec CLI là tùy chọn**: `aih new-change` tạo bản nháp offline, còn `openspec validate` cần OpenSpec CLI cài riêng. Xem [OpenSpec](openspec.md).
13
- - Bản nguồn hiện tại là candidate; chưa mặc định có một bản `@manhd_d/ai-harness` được phát hành trên npm registry. Xem [npm release](npm-release.md).
14
-
15
- ## 2. Cài một lần từ source đã review
16
-
17
- ~~~bash
18
- git clone git@github.com:manh0303/ai-harness.git
19
- cd ai-harness
20
- # Nếu thử PR Astro chưa merge, chọn branch đã review:
21
- git switch feat/astro-lightweight-adapter
22
- # Sau khi merge, ưu tiên commit/tag chính thức đã review.
23
- npm test
24
- npm run validate
25
- npm run test:package
26
- npm pack
27
- npm install -g ./manhd_d-ai-harness-0.6.0.tgz
28
- aih --version
29
- ~~~
30
-
31
- Nếu package đã được publish công khai thì có thể cài bằng `npm install -g @manhd_d/ai-harness`; **đừng coi lệnh cài registry là dùng được trước khi xác minh việc phát hành**. Cài bộ `aih` không tự cài OpenSpec hay dependency Spring/React/Python cho ứng dụng.
32
-
33
- ## 3. Cài Harness vào repository ứng dụng
34
-
35
- Ví dụ service Spring Boot có nhu cầu làm tài liệu sản phẩm và triển khai Kubernetes:
36
-
37
- ~~~bash
38
- cd /path/to/existing-spring-service
39
- aih resolve --adapters java-spring,kubernetes --capabilities product,devops
40
- aih init --adapters java-spring,kubernetes --capabilities product,devops --dry-run
41
- aih init --adapters java-spring,kubernetes --capabilities product,devops
9
+ ```bash
10
+ npm install -g @manhd_d/ai-harness
11
+ cd /path/to/existing-project
12
+ aih init --adapters java-spring
42
13
  aih check
43
- aih skills
44
- ~~~
14
+ ```
45
15
 
46
- - `aih resolve`: kiểm tra dependency/compatibility và cảnh báo recommendation; **không cài module**.
47
- - `aih init --dry-run`: xem diff dự kiến, **không cài đặt lâu dài**.
48
- - `aih init`: cài snapshot đã chọn trong `.harness/`, tạo AGENTS block, ghi lock và expose skills trong `.agents/skills/`.
49
- - `aih check`: kiểm tra integrity của file do Harness quản lý, **không kiểm thử source code ứng dụng**.
50
- - `aih skills`: liệt kê metadata. `aih skill <tên>`: đọc **một** skill đã cài, không tự kích hoạt agent.
16
+ Chọn module theo nhu cầu, không cần cài cả bộ:
51
17
 
52
- **Các lựa chọn phổ biến:**
53
-
54
- | Dự án | Lựa chọn |
18
+ | Nhu cầu | Tham số cho `aih init` |
55
19
  | --- | --- |
56
- | API Spring | `--adapters java-spring` |
57
- | Web React/Next.js | `--adapters react-nextjs --capabilities uiux` |
58
- | Astro web tools (static-first) | `--adapters astro` (tùy chọn `--capabilities product,uiux`) |
59
- | Astro/React + advertising | `--adapters astro --capabilities monetization` (hoặc `react-nextjs`) |
60
- | React Native/Expo | `--adapters react-native --capabilities product,uiux` |
61
- | Python AI/RAG | `--adapters ai-python --capabilities product` |
62
- | Full-stack một repo | `--adapters java-spring,react-nextjs,kubernetes --capabilities product,uiux,devops` |
63
- | Chỉ BA/PO | `--capabilities product` |
64
- | Core-only | Không truyền adapters/capabilities |
65
-
66
- `aih detect` kiểm tra heuristic các file trực tiếp ở target, không tìm đệ quy monorepo. Với mỗi microservice/repository độc lập, cài riêng và chỉ chọn những module thực sự cần.
20
+ | Spring Boot API | `--adapters java-spring` |
21
+ | React/Next.js + UI | `--adapters react-nextjs --capabilities uiux` |
22
+ | Astro tool nhỏ | `--adapters astro` |
23
+ | Website có quảng cáo | `--adapters astro --capabilities monetization` |
24
+ | Viết tài liệu từ ý tưởng hoặc tài liệu BA | `--capabilities product` |
25
+ | Spring + tài liệu + Kubernetes | `--adapters java-spring,kubernetes --capabilities product,devops` |
67
26
 
68
- ## Astro cho web tools nhỏ
27
+ `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.
69
28
 
70
- Nếu xây nhiều tiện ích như QR, JSON hoặc image tools: dùng [Astro micro-tools walkthrough](examples/astro-micro-tools.md) với lệnh `aih init --adapters astro` và skill islands, SEO, performance, Cloudflare. `astro` được nhận diện từ dependencies. React Islands không bắt buộc; MFE/Workers không được cài tự động.
29
+ ## 2. Ghi context và bắt đầu giao việc
71
30
 
72
- ## Website công cụ miễn phí có quảng cáo
31
+ Điền `.harness/local.md` bằng thông tin thực của project:
73
32
 
74
- Nếu mục tiêu là traffic SEO và doanh thu AdSense, chọn optional `monetization` **không phụ thuộc Astro**; website có thể dùng Next.js. Xem [Monetization guide](monetization.md), [walkthrough Astro + AdSense](examples/astro-adsense-microtools.md) và `aih skill harness-monetization-adsense-integration`. Các hướng dẫn chỉ giúp chuẩn bị, không tự tạo tài khoản AdSense hoặc kết nối Analytics.
33
+ - Mục tiêu, phạm vi và quy tắc nghiệp vụ quan trọng.
34
+ - Stack/phiên bản, database, cấu trúc service/module.
35
+ - Lệnh build/test đã xác nhận chạy được.
36
+ - Đường dẫn tài liệu BA, conventions và những ràng buộc cần giữ.
75
37
 
76
- ## Hai hướng dẫn theo loại dự án
38
+ Mở project trong AI IDE và giao yêu cầu, ví dụ:
77
39
 
78
- - [Idea-driven — có ý tưởng và muốn AI cùng thảo luận, nghiên cứu, viết tài liệu](examples/idea-driven-project.md).
79
- - [Document-driven — có BRD/PRD/SRS từ BA, cần AI đưa vào phát triển phần mềm](examples/document-driven-project.md).
40
+ > Đọ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.
80
41
 
81
- **Lưu ý:** khi PR chứa tính năng chưa merge, cần checkout đúng branch/commit đã review trước khi `npm pack`; cài từ `main` không mặc định có các tính năng chỉ có trong PR.
42
+ 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.
82
43
 
83
- ## 4. Bắt đầu một thay đổi có traceability
44
+ 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ý.
84
45
 
85
- Hai workflow tài liệu: `idea-driven` khi bắt đầu từ ý tưởng thô, `document-driven` khi đã có BRD/PRD/SRS/Confluence do BA cung cấp. Cả hai dùng chung pipeline, approval và OpenSpec. Xem [Documentation workflows](documentation-workflows.md).
46
+ ## 3. Tài liệu và spec khi cần
86
47
 
48
+ Với capability `product`:
87
49
 
88
- ~~~bash
89
- # Chỉ dùng được khi đã chọn capability product:
90
- aih new-doc brd
91
- aih new-doc prd
92
- aih new-doc backlog
93
- aih new-doc acceptance-criteria
94
- aih new-doc traceability
95
- aih new-doc idea # docs/discovery/
96
- aih new-doc research # docs/discovery/
97
- aih new-doc prd-lite # docs/product/
98
- aih new-doc srs # docs/product/
99
- aih new-doc use-cases # docs/product/
50
+ ```bash
51
+ aih new-doc prd-lite
52
+ ```
100
53
 
101
- # Tạo change bản nháp OpenSpec — không cần cài OpenSpec CLI:
102
- aih new-change add-customer-api
54
+ 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.
103
55
 
104
- # Đọc từng skill cần thiết:
105
- aih skill harness-product-prd-generation
106
- aih skill harness-spec
107
- aih skill harness-tdd
108
- ~~~
56
+ Khi một tính năng cần proposal/design/tasks/spec riêng:
109
57
 
110
- Các lệnh `new-doc` chỉ copy template trống sang `docs/product/`; AI host/BA/PO phải điền theo nguồn đáng tin cậy và duyệt. `new-change` chỉ tạo proposal/design/tasks/spec có TODO; **không phải spec đã được approve**. Trước khi yêu cầu IDE implement, hướng assistant đọc `AGENTS.md` và `.harness/local.md` của dự án.
58
+ ```bash
59
+ aih new-change add-customer-search
60
+ ```
111
61
 
112
- **Prompt mẫu gửi cho assistant:**
62
+ Đâ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.
113
63
 
114
- > Hãy đọc AGENTS.md, .harness/local.md và các skill phù hợp đã cài. Phân tích yêu cầu theo source ID, nêu các điểm chưa rõ, soạn OpenSpec change và test scenarios. Chỉ implement khi scope được duyệt; báo cáo tests thực chạy và tạo PR để tôi review, không tự merge hoặc deploy.
64
+ `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).
115
65
 
116
- ## 5. Verify / evaluate và release
66
+ ## 4. Kiểm tra đúng thứ
117
67
 
118
- ~~~bash
119
- aih verify --scope all
120
- aih eval --scope all
121
- aih check
122
- ~~~
68
+ | Lệnh | Ý nghĩa |
69
+ | --- | --- |
70
+ | `aih check` | Kiểm tra integrity của file Harness; không kiểm thử ứng dụng |
71
+ | `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 |
72
+ | `aih verify --scope all` | Xuất checklist, `executed: false`; không chạy build/test |
73
+ | `aih eval --scope all` | Xuất tình huống và báo cáo chưa chấm; không gọi model |
74
+ | Lệnh test của project | Do bạn, AI host hoặc CI thực chạy để xác minh code |
123
75
 
124
- - `verify`: checklist advisory, `executed: false`. Dùng bằng chứng chạy build/test **bên ngoài CLI**.
125
- - `eval`: dataset và report để con người chạy bài test với một AI runtime được cấp quyền rồi chấm; **không gọi model, không tự chấm**.
126
- - `--scope all`: Core + capability + adapter và scenario ghép module phù hợp. Không có scope thì mặc định chỉ là adapter.
127
- - Production approval phải chỉ rõ artifact, environment và người phê duyệt; CI xanh không cấp quyền deploy.
76
+ 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.
128
77
 
129
- Đọc các [approval gates trong Full SDLC](end-to-end-workflow.md) và [DevOps runbook](../capabilities/devops/workflows/pr-to-production.md).
78
+ ## 5. Cập nhật: CLI trước, project sau
130
79
 
131
- ## 6. Update bộ Harness đã cài
80
+ 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:
132
81
 
133
- ~~~bash
134
- # Trên branch của consumer, commit trạng thái hiện tại trước.
135
- # Thay đổi adapters/capabilities trong .harness/project.json nếu cần.
82
+ ```bash
83
+ npm install -g @manhd_d/ai-harness@latest
84
+ aih --version
85
+ aih check
136
86
  aih update --dry-run
137
87
  aih update
138
88
  aih check
139
- ~~~
89
+ ```
90
+
91
+ `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.
140
92
 
141
- Không chỉnh file snapshot dưới `.harness/core|adapters|capabilities` hoặc skill do Harness quản lý; nội dung riêng của dự án thuộc `.harness/local.md`. Nếu có drift, khôi phục từ Git và review diff; không sửa lock hash để che lỗi.
93
+ Nếu cài local trong project, dùng `npm install --save-dev @manhd_d/ai-harness@latest` và `npx aih` thay cho `aih`.
142
94
 
143
- ## Ví dụ thực hành
95
+ ## Đọc thêm theo nhu cầu
144
96
 
145
- - [Spring Boot REST API với Kafka/DB/Kubernetes](examples/spring-boot-api.md)
146
- - [Full-stack Spring + Next.js + Figma](examples/fullstack-web.md)
147
- - [React Native/Expo có offline-sync](examples/react-native-app.md)
148
- - [Python AI/RAG với kiểm soát truy cập](examples/ai-rag-service.md)
97
+ - [CLI reference](cli.md) · [Full SDLC](end-to-end-workflow.md) · [Skill matrix](skill-matrix.md) · [Agent handoffs](agent-handoffs.md).
98
+ - [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).
99
+ - [Astro micro-tools](examples/astro-micro-tools.md) · [Astro + AdSense](examples/astro-adsense-microtools.md).
100
+ - [Release guide](npm-release.md): dành cho maintainer; merge source không đồng nghĩa npm đã có bản mới.
package/docs/npm-release.md CHANGED
@@ -1,70 +1,57 @@
1
- # npm installation and release
1
+ # npm publishing — automated releases
2
2
 
3
- The public npm package is `@manhd_d/ai-harness` (executable: `aih`). The private GitHub repository stays `manh0303/ai-harness`. Different npm and GitHub usernames are expected.
3
+ The public distribution is `@manhd_d/ai-harness` (CLI command `aih`). The GitHub source stays **private** at `manh0303/ai-harness`. First version `0.6.0` was published manually by its owner.
4
4
 
5
- **Changing this configuration and merging a PR does not publish a package.** Public npm publication makes every file inside the npm tarball publicly accessible, regardless of GitHub repository visibility.
5
+ ## One-time npm Trusted Publisher setup
6
6
 
7
- ## First publication: manual, maintainer-controlled
7
+ In [npm package settings](https://www.npmjs.com/package/@manhd_d/ai-harness) → Trusted Publisher select **GitHub Actions** with:
8
8
 
9
- 1. Confirm the verified npm account is `manhd_d`, with 2FA enabled, and the publishing machine uses the official npm registry.
10
- 2. Merge the reviewed PR. Check out the approved `main` commit. Review `npm pack --dry-run` for secrets before sharing the archive.
11
- 3. Run:
9
+ | Field | Value |
10
+ | --- | --- |
11
+ | Organization or user | `manh0303` |
12
+ | Repository | `ai-harness` |
13
+ | Workflow filename | `npm-publish.yml` |
14
+ | Environment | Leave empty |
15
+ | Allowed actions | **Allow npm publish** (required) |
12
16
 
13
- ```bash
14
- git switch main
15
- git pull --ff-only
16
- npm login
17
- npm whoami
18
- npm config get registry
19
- npm ci --ignore-scripts --no-audit --no-fund
20
- npm test
21
- npm run validate
22
- npm run check:release
23
- npm run test:package
24
- npm pack --dry-run
25
- npm publish --access public
26
- npm view @manhd_d/ai-harness version
27
- ```
17
+ Use **npm CLI >= 11.5.1** and Node 22.14+ for OIDC; this workflow runs Node 24 and installs npm 11. No `NPM_TOKEN` or OTP is required in GitHub Actions. Keep npm 2FA on for account security. Because the GitHub repository is private, npm provenance attestations are unavailable and the workflow disables provenance while retaining OIDC.
28
18
 
29
- `npm whoami` must return `manhd_d`. The expected first package version is `0.6.0`, if the maintainer has approved that release and the version is not already published. Publishing may require browser/2FA confirmation. Never commit npm credentials or tokens.
19
+ **Repository setting required:** GitHub → `manh0303/ai-harness` → Settings → Actions → General → Workflow permissions → ensure **Allow GitHub Actions to create and approve pull requests** is enabled. This grants Release Please permission to open Release PRs (which are still reviewed by a human). GitHub does not validate the npm Trusted Publisher mapping when it is saved; the first OIDC release run proves it works.
30
20
 
31
- A successful publish is independently verifiable with `npm view`. You can add an annotated git tag `v0.6.0` to the exact commit afterwards, but **do not create/publish a GitHub Release for a version already published manually**.
21
+ ## End-to-end workflow
32
22
 
33
- ## Later releases: npm Trusted Publishing via GitHub Actions
23
+ 1. Feature/fix PRs use Conventional Commits or squash titles: `feat: ...` (minor), `fix: ...` (patch), `feat!: ...` / `BREAKING CHANGE` (breaking). Do **not** bump `package.json`, `package-lock.json`, `harness.yaml` or the Release Please manifest on feature branches.
24
+ 2. CI runs tests; **you review and merge** the feature PR into `main`.
25
+ 3. `.github/workflows/npm-publish.yml` runs CI on `main` then Release Please. It opens/updates a separate **Release PR**, proposing version/changelog changes. It also explicitly dispatches `harness.yml` for the generated Release PR branch; the `GITHUB_TOKEN` does not trigger arbitrary downstream workflows.
26
+ 4. **You review and merge the Release PR** once satisfied. That `main` push triggers the same workflow. After tests pass, Release Please creates a `vX.Y.Z` Git tag and GitHub Release.
27
+ 5. The **same** `npm-publish.yml` run checks out that tag, checks ancestry on `main`, verifies scope/manifest/changelog, runs tests and an actual npm tarball smoke test, then executes `npm publish --access public` with GitHub OIDC.
28
+ 6. Confirm the new version with `npm view @manhd_d/ai-harness version`. npm processing can take a few minutes. Consumers run `npm install -g @manhd_d/ai-harness@latest`, then `aih update --dry-run`, `aih update` and `aih check` inside each project.
34
29
 
35
- After the first successful manual publication, go to [npm](https://www.npmjs.com) → package `@manhd_d/ai-harness` → Settings → Trusted publishing and configure a GitHub Actions publisher:
30
+ **Why one workflow?** Release Please uses `GITHUB_TOKEN`. GitHub usually suppresses new workflow runs in response to events created by `GITHUB_TOKEN`, including its `release.published` event. Publishing in the same `push main` workflow avoids silently skipping npm publication. For a **manually published** GitHub Release, the same file also supports `release.published` as a fallback, with matching version and main-ancestry guards. Do not create a manual GitHub Release for a version already present on npm; npm versions cannot be overwritten.
36
31
 
37
- | Field | Value |
38
- | --- | --- |
39
- | GitHub user/organization | `manh0303` |
40
- | Repository | `ai-harness` |
41
- | Workflow file | `npm-publish.yml` |
42
- | Environment | Leave empty (workflow does not use an environment) |
32
+ ## Bootstrap from manually published v0.6.0
43
33
 
44
- Select direct **npm publish** permissions if npm offers a stage-only option. Configure the trusted publisher shortly before the next release if npm applies an initial activation deadline. No long-lived `NPM_TOKEN` is required.
34
+ `.release-please-manifest.json` starts at `{".":"0.6.0"}` and `release-please-config.json` pins `bootstrap-sha` to the main commit from which v0.6.0 was published. This prevents replaying all historical changes or treating an older branch's releases as new. For the root npm package Release Please uses:
45
35
 
46
- For each subsequent version: use a dedicated release PR to update `package.json`, `package-lock.json`, `harness.yaml` and `CHANGELOG.md` together, run CI, review and merge. Create a tag `vX.Y.Z` at the tested main commit and **publish the corresponding GitHub Release**. Only this Release publication triggers `.github/workflows/npm-publish.yml`. The workflow checks that the commit is reachable from main, that the tag matches the package version, and that tests and tarball smoke checks pass before attempting OIDC-based publication.
36
+ - `release-type: node` to update `package.json`, `package-lock.json`, and `CHANGELOG.md`.
37
+ - `include-v-in-tag: true` and `include-component-in-tag: false` to create tags like `v0.6.1`.
38
+ - **`extra-files` type `json` for `harness.yaml`**, because despite its .yaml name, this file must stay valid JSON and is parsed with `JSON.parse`; a YAML updater would break the CLI.
47
39
 
48
- A private GitHub source repository does not support npm provenance attestation even though the public package can use OIDC. Do not enable npm provenance for this private repository. See [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/).
40
+ `scripts/check-release.js` blocks mismatched versions across the three distribution metadata files and Release Please manifest, and accepts old and Release Please-generated changelog version headings. Feature PRs should not edit `bootstrap-sha`; it becomes irrelevant after the first automated release.
49
41
 
50
- ## Local installation before npm publication
42
+ ## Security and recovery
51
43
 
52
- ```bash
53
- npm pack
54
- npm install -g ./manhd_d-ai-harness-0.6.0.tgz
55
- aih --version
56
- ```
44
+ No workflow automatically merges a PR. The release job uses only `contents: read` and `id-token: write`; the Release Please job has separately scoped permissions to open PRs/create releases. GitHub-hosted runners are required for npm OIDC. If a Release PR appears without CI checks, use the explicitly dispatched CI run linked from Actions. Never merge an unreviewed release PR.
57
45
 
58
- ## Installation after verified npm publication
46
+ If the Release Please job fails to create a PR, check repository Actions workflow permissions and the workflow logs. If npm returns E403, check Trusted Publisher's **workflow filename exactly `npm-publish.yml`**, allowed action `npm publish`, and that the connection is active. Do not add bypass-2FA tokens as a workaround. An expired/unverified publisher binding may require recreating it in npm settings.
59
47
 
60
- ```bash
61
- npm install -g @manhd_d/ai-harness
62
- aih --version
63
- cd /path/to/existing-project
64
- aih init --adapters java-spring
65
- aih check
66
- ```
48
+ If GitHub Release exists but npm publish failed, **do not bump the version blindly or create another GitHub Release for the same tag**. Diagnose the failed job. Re-running the workflow is appropriate only when npm still has no published version and the error is resolved. A documented manual recovery is possible after verifying the tag and credentials.
67
49
 
68
- Existing consumers can update the CLI with `npm update -g @manhd_d/ai-harness`. Use `aih update --dry-run`, `aih update`, `aih check` to update a consumer project's snapshot on a branch. CLI installation does not install OpenSpec, an AI runtime or application dependencies.
50
+ If the failure is in code/tests stored in the release tag, fixing `main` does not fix that immutable
51
+ tag. Do not move or overwrite it. Merge the repair, let Release Please prepare a new patch Release PR,
52
+ verify CI on its exact head, then review/merge it. Re-running the old tag will reproduce the old defect.
53
+ For example, v0.6.1 failed before publication because two migration tests expected 0.6.0.
54
+ Main now compares against the source version; the regression suite also exercises the next patch
55
+ version. Publish the reviewed follow-up release rather than changing v0.6.1.
69
56
 
70
- Read [Getting started](getting-started.md) and [Release policy](release-policy.md).
57
+ Official docs: [Release Please](https://github.com/googleapis/release-please-action), [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/), [GitHub Actions event triggering](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow).
package/docs/release-policy.md CHANGED
@@ -7,7 +7,7 @@ Distribution version is `harness.yaml` + `package.json` + `package-lock.json`. O
7
7
  2. Each module maintainer changes `module_version` only for real contract changes, describing compatibility impact in the PR.
8
8
  3. One **release PR** assigns the next distribution version, updates all three metadata files, and moves Unreleased notes into a version heading.
9
9
  4. Check CI on Linux/Windows and Node 22/24; run behavioral agent evaluations when instructions change, not just synthetic unit tests.
10
- 5. A human merges the release PR and separately approves npm publication: first version is manually published; subsequent versions require a human-published matching GitHub Release. No publishing merely on merge or tag.
10
+ 5. A human reviews/merges the feature PR, then reviews/merges the auto-generated Release Please PR. The second approval authorizes the workflow to tag/release and publish npm through OIDC, after tests. No publishing from feature PRs, and no publish-on-tag alone.
11
11
 
12
12
  ## Compatibility
13
13
  - Existing schema-1 config and locks remain valid. Optional module contract fields are additive.
package/docs/versioning.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # Versioning and migration
2
2
 
3
3
  Framework version is in harness.yaml and package.json; keep both and package-lock.json synchronized. Use three-part SemVer releases and Git tags vX.Y.Z after review.
4
- 0.6.0 is a DevOps/Kubernetes candidate (0.5.0 added the Product documentation capability), not a claim of a registry publication or Git tag. Do not publish from a feature PR.
4
+ 0.6.0 was initially published manually to npm. Future versions are prepared by Release Please after human PR review; do not publish directly from a feature PR.
5
5
 
6
6
  - Patch: compatible corrections to instructions or installer defects.
7
7
  - Minor: backward-compatible adapter, skill or CLI additions.
@@ -16,13 +16,20 @@ It does not fetch releases or silently follow main. Pass a reviewed local checko
16
16
  See [release policy](release-policy.md) for independently versioned module contracts and single release-PR version ownership.
17
17
 
18
18
  ## Release procedure
19
+
20
+ **Current automation (after v0.6.0):** Release Please maintains the root distribution version, changelog and JSON-formatted harness.yaml. The human review/merge of its generated Release PR is the explicit publishing approval. See [npm release](npm-release.md).
19
21
  1. Update harness.yaml, CHANGELOG and migration notes. Review policy/behavior changes as code.
20
22
  2. Run structural validation and CLI tests on the supported Node.js 22/24 and OS matrix, including actual npm package smoke tests.
21
23
  3. Run the behavioral evaluation suite with the intended agent/model if prompts materially changed.
22
24
  4. Inspect the install/update diff in a sample consumer; document source commit and limitations.
23
- 5. Merge by human decision. First npm publication is manual. Subsequent releases use an approved GitHub Release triggering npm Trusted Publishing; merge or tag alone never publishes.
25
+ 5. Merge feature PR by human decision. Release Please opens a separate version/changelog PR; after human review and merge, the release workflow creates the tag and GitHub Release and publishes npm from the same workflow through OIDC. Merge of feature PR alone does not publish.
24
26
 
25
27
  ## Consumer update
28
+ For global npm installs, first run `npm install -g @manhd_d/ai-harness@latest`.
29
+ For local installs, update the local dependency and use `npx aih`.
30
+ `aih --version` identifies the CLI; `aih check` identifies the installed project snapshot.
31
+ `aih update` applies the installed CLI bundle (or explicit `--source`), without fetching releases.
32
+
26
33
  Create a branch, commit current state, obtain the reviewed source commit/tag and inspect CHANGELOG.
27
34
  Run update --dry-run; resolve conflicts by moving custom rules into .harness/local.md and restoring
28
35
  managed files from the last installation commit. Apply update and run check plus application tests.
@@ -82,8 +89,8 @@ Do not treat raw Confluence data, drafts or AI review as approved business decis
82
89
 
83
90
  ## 0.5 → 0.6 migration
84
91
 
85
- No new configuration/lock schema version: 0.5 Product templates, `aih new-doc`, UI/UX and all earlier adapter selections stay compatible. New DevOps and Kubernetes modules are opt-in. On a consumer branch, pin a reviewed 0.6 source/package, add `"devops"` to `.harness/project.json` capabilities and/or `"kubernetes"` to adapters, then run `aih update --dry-run`, `aih update` and `aih check`. Unmodified installed payload updates safely; any drift still blocks update. Application DevOps workflows remain instruction-only and do not deploy production workloads; a separate repository-level npm workflow publishes only after a human-approved GitHub Release.
92
+ No new configuration/lock schema version: 0.5 Product templates, `aih new-doc`, UI/UX and all earlier adapter selections stay compatible. New DevOps and Kubernetes modules are opt-in. On a consumer branch, pin a reviewed 0.6 source/package, add `"devops"` to `.harness/project.json` capabilities and/or `"kubernetes"` to adapters, then run `aih update --dry-run`, `aih update` and `aih check`. Unmodified installed payload updates safely; any drift still blocks update. Application DevOps workflows remain instruction-only and do not deploy production workloads; a separate repository-level npm workflow publishes only after a human-approved Release Please PR creates a tagged GitHub Release.
86
93
 
87
94
  ## Foundation hardening (unreleased after 0.6)
88
95
 
89
- Module contracts gain optional version and dependency fields without changing config/lock schema 1. Existing consumer snapshots retain default adapter-only verify/eval. After a reviewed update, `--scope all` enables locked Core/capability/composition evaluation, and `--scope core` works in core-only projects. Feature branches retain distribution version 0.6.0; release PR chooses the next number. Use tagged releases for other consumers rather than interpreting an unreleased commit as a published update.
96
+ Module contracts gain optional version and dependency fields without changing config/lock schema 1. Existing consumer snapshots retain default adapter-only verify/eval. After a reviewed update, `--scope all` enables locked Core/capability/composition evaluation, and `--scope core` works in core-only projects. Feature branches keep the latest release version; Release Please's generated PR chooses and synchronizes the next number. Use tagged releases for other consumers rather than interpreting an unreleased commit as a published update.
package/harness.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "schema_version": 1,
3
3
  "name": "ai-harness",
4
- "version": "0.6.0",
4
+ "version": "0.6.2",
5
5
  "adapters": [
6
6
  "java-spring",
7
7
  "react-nextjs",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@manhd_d/ai-harness",
3
- "version": "0.6.0",
3
+ "version": "0.6.2",
4
4
  "description": "Reusable AI development rules, skills and workflows with a safe local installer",
5
5
  "type": "module",
6
6
  "bin": {
package/templates/AGENTS.md CHANGED
@@ -1,7 +1,7 @@
1
1
  <!-- ai-harness:start -->
2
2
  ## AI Harness {{version}}
3
3
 
4
- 1. Read `.harness/core/rules/foundations.md` and `.harness/core/policies/security.md`.
4
+ 1. Read `.harness/core/rules/foundations.md`, `.harness/core/rules/context.md` and `.harness/core/policies/security.md`.
5
5
  2. Read `.harness/core/policies/permissions.md` and `.harness/core/workflows/spec-to-code.md`.
6
6
  3. Read `.harness/local.md` for project facts and reviewed exceptions.
7
7
  4. Load only the adapter and skills needed for the current task: