@manhd_d/ai-harness 0.8.0 → 0.10.0

package/docs/agent-handoffs.md

@@ -3,6 +3,10 @@
 AI Harness hiện có **role contracts**, không tạo các agent chạy tự động hoặc agent-to-agent queue. Một assistant có thể đảm nhiệm nhiều vai trò theo thứ tự, nhưng phải tách evidence, quyền hạn và human approval. Dùng cùng [Full SDLC](end-to-end-workflow.md) và [Skill matrix](skill-matrix.md).
 
 ## Trách nhiệm theo vai trò
+For React/Next.js and React Native implementation/testing, use the selective skill routing in
+[Frontend/mobile coding](frontend-mobile.md). Handoff AC → route/screen → API/state → test evidence,
+including reused public APIs and unavailable browser/native checks; retain the same Core roles.
+
 
 | Role contract trong source | Nhận | Bàn giao | Không được làm |
 | --- | --- | --- | --- |

package/docs/architecture.md

@@ -137,3 +137,12 @@ the snapshot. agents.json is project-owned and preserved. agents.js validates/re
 namespaced roles; setup supplies an advisory host plan with availability unverified. No provider calls,
 native writes, orchestration, usage meter or automatic escalation. Old alternate sources use the packaged
 default when absent; old consumers without config remain valid. See [Agent configuration](agent-configuration.md).
+
+## Project artifact and integration contracts
+Project-owned artifacts.json/integrations.json use schema 1 independently of project/lock schemas.
+The installer seeds absent configs, validates before writes, and preserves custom bytes. The shared
+JSON reader does not echo parse input. artifacts.js validates local paths/refs/dependencies and
+provides a read-only host plan; no provider registry, connector runtime, secrets store or discovery.
+new-doc routes to an explicit docs folder or returns an external template handoff without fallback
+copies. OpenSpec stays repository-owned; configured outputs add structural artifact-impact coverage
+and completion to readiness. See [Artifact contract](artifact-contract.md).

package/docs/artifact-contract.md

@@ -0,0 +1,197 @@
+# Project artifacts and integrations
+
+Define **Input → Output → Storage → Ownership → Maintenance** once per project.
+The AI host executes tools; Harness validates declarations and provides workflows.
+
+| Project-owned file | Purpose |
+| --- | --- |
+| .harness/artifacts.json | Input/output locations, source revisions, canonical ownership, write policy and dependencies |
+| .harness/integrations.json | Dynamic connection IDs, host bindings, purpose, intended access and scope |
+| .harness/environment.json | Existing executable/file/build/test contract; unchanged |
+
+Init/update seed empty contracts if absent and preserve existing bytes. No secrets, native MCP
+server configuration or account credentials belong in these files.
+
+## Quick setup
+
+Ask the AI:
+> Read AGENTS.md and inspect existing sources. If unknown, ask where docs and UI/UX should be
+> stored and maintained. Record only the outputs this project needs, their canonical owner and
+> source-write scope. Reuse established decisions and authorization.
+
+`aih setup` suggests missing storage choices; `aih artifacts` reports the declarations.
+Neither interviews the user, writes answers, connects accounts, retrieves docs nor discovers MCP.
+An empty/unconfigured contract keeps old projects usable without forcing a new documentation phase.
+
+For idea-driven work, select Product when its templates help; a small app can use PRD-lite + spec/tasks.
+For existing docs, preserve approved sources and create only needed derived technical outputs.
+
+## Repository example
+
+.harness/artifacts.json:
+```json
+{
+  "schema_version": 1,
+  "mode": "idea-driven",
+  "inputs": {
+    "idea": {
+      "kind": "idea",
+      "location": { "path": "docs/discovery/idea.md" },
+      "owner": "project-owner",
+      "write_policy": "propose"
+    }
+  },
+  "outputs": {
+    "product": {
+      "kind": "docs",
+      "capability": "product",
+      "location": { "path": "docs/requirements" },
+      "owner": "project-owner",
+      "canonical": true,
+      "sources": ["idea"],
+      "write_policy": "propose"
+    },
+    "spec": {
+      "kind": "spec",
+      "location": { "path": "openspec" },
+      "canonical": true,
+      "depends_on": ["product"],
+      "write_policy": "propose"
+    }
+  }
+}
+```
+
+After installing Product, `aih new-doc prd-lite` now creates
+`docs/requirements/prd-lite.md` and refuses overwrite. A configured contract must declare a docs
+destination for the requested capability. For unconfigured/legacy contracts, the original
+docs/discovery and docs/product (or other capability) defaults remain.
+
+## External sources and arbitrary tools
+
+Example .harness/integrations.json:
+```json
+{
+  "schema_version": 1,
+  "connections": {
+    "requirements-tool": {
+      "via": "connector",
+      "binding": "atlassian",
+      "purpose": "Read project requirements and issues",
+      "access": "read-only",
+      "scope": ["space/APP", "project/APP"]
+    },
+    "design-tool": {
+      "via": "mcp",
+      "binding": "figma",
+      "purpose": "Review project UI",
+      "access": "read-only",
+      "scope": ["approved-file-id"]
+    },
+    "test-db": {
+      "via": "mcp",
+      "binding": "postgres",
+      "purpose": "Inspect test schema",
+      "access": "read-only",
+      "scope": ["test-database"]
+    }
+  }
+}
+```
+
+Connection IDs/bindings are aliases, not a fixed Figma/Jira/Confluence/DB registry. Map them to actual
+authorized host tools; manual access can use via: manual. Runtime credentials and host configuration
+stay outside Git. All reported availability is unverified until the host checks it.
+
+An external input or output uses a location such as:
+```json
+{
+  "kind": "docs",
+  "capability": "product",
+  "location": {
+    "url": "https://example.atlassian.net/wiki/pages/123",
+    "connection": "requirements-tool"
+  },
+  "owner": "product-owner",
+  "revision": "17",
+  "canonical": true,
+  "write_policy": "read-only"
+}
+```
+
+Use it under inputs for an existing source. An output uses its chosen target and usually propose;
+do not mark a derived output canonical for the same kind/capability as its canonical input.
+`aih new-doc` with an external output returns status planned, the actual locked template and
+destination metadata, with executed false. It creates no local copy and performs no remote write.
+The host prepares/reviews the draft or publishes only within existing explicit scope authorization.
+
+## Schema and defaults
+
+- Schema 1 has mode (unconfigured / idea-driven / document-driven), inputs and outputs maps.
+  Unconfigured maps are empty. IDs and kinds are lowercase hyphenated slugs.
+- Each artifact has kind and exactly one location path or HTTPS URL. Local inputs can name files
+  or directories; local output paths are directories. Paths stay inside the project, without
+  symlinks, traversal or managed/private output folders (.git/.harness/.agents/node_modules/AGENTS.md).
+- Optional owner/revision are recorded facts; status is draft/approved/superseded. Defaults are draft,
+  not business approval. canonical defaults false; at most one canonical artifact per kind/capability.
+  Use different kinds for distinct authoritative artifacts or a collection input for a source set.
+- Outputs may name input IDs in sources and output IDs in depends_on. Unknown refs, self/cyclic
+  dependencies, conflicting canonical owners and duplicate docs routes are rejected.
+- docs output capability defaults product; only one docs route per capability. spec output must
+  point to repository openspec; OpenSpec CLI readiness/archive remains local. External specs can
+  be input or host-managed exports.
+- write_policy is read-only/propose/write. Git defaults propose; external inputs default read-only;
+  outputs default propose. Propose is a reviewable patch/PR/handoff, not permission to mutate an
+  external canonical page. Read-only sources remain unchanged.
+- Connection fields: via (mcp/connector/manual), binding alias, purpose, optional access and scope.
+  Access defaults read-only. Write requires nonempty scope. External write artifacts also require
+  a write connection and observed revision/snapshot reference. URL credentials and credential
+  query parameters are rejected. Config validation cannot detect every secret; never place secrets here.
+- Declarations do not grant permissions or enforce connector calls. Verify host tools, user authorization,
+  current revisions and optimistic concurrency before a write. A changed/unavailable revision must
+  be reconciled; do not overwrite or infer successful publication.
+
+## Spec-driven maintenance
+
+`aih new-change <id>` adds artifact-impact.json with its other draft templates:
+```json
+{
+  "schema_version": 1,
+  "reviewed": true,
+  "items": [
+    {
+      "artifact": "output:product",
+      "action": "update",
+      "status": "pending",
+      "reason": "Add acceptance criteria for this feature"
+    },
+    {
+      "artifact": "output:spec",
+      "action": "create",
+      "status": "pending",
+      "reason": "Specify the new behavior"
+    }
+  ]
+}
+```
+
+Replace reasons with actual impact; use input:<id> for affected sources. Cover every configured output;
+use unchanged with a reason when unaffected. Before implement, reviewed impact must not be blocked
+or request changes to read-only artifacts. Before review, every item is done and changed artifacts
+have concrete evidence (diff/PR/page/node/source revision/test log). Record remote publication evidence
+and sync direction; pending/blocked required maintenance is not completion.
+
+`aih ready` activates this gate only for configured contracts with outputs. It validates structure
+and declared completion, not semantic correctness, actual permissions or truthful evidence.
+The host reviews requirements → spec → UI/code → verification and updates affected artifacts in
+the same change. Reuse prior approval within scope. Sync accepted specs/archive only after merge.
+
+## Update and rollback
+
+Update seeds missing contracts without rewriting configured artifacts, agents.json, local docs or
+external sources. Old changes without artifact-impact.json remain usable when no outputs are configured;
+when opting in, copy the installed impact template and review actual change coverage. Project/lock
+schemas remain 1. Review update --dry-run, then update/check and application tests; rollback via Git.
+
+[Project configuration](project-configuration.md) · [Change readiness](change-readiness.md) ·
+[Documentation workflows](documentation-workflows.md) · [MCP contract](../integrations/mcp/README.md).

package/docs/change-readiness.md

@@ -65,3 +65,9 @@ kết quả. Ít nhất một check hoặc manual review đã pass phải đư
 Change cũ không bị tự sửa. Nếu muốn dùng ready, copy hai template từ
 `.harness/templates/openspec/` sau khi update, chỉ khi file đích chưa có; điền theo thực tế.
 Sửa nhỏ, ít rủi ro không cần full change: ghi rationale và bằng chứng ngay trong PR.
+
+## Artifact maintenance
+With configured outputs in .harness/artifacts.json, readiness also reads artifact-impact.json.
+Cover each output plus affected input IDs, record reviewed impact/reasons and respect read-only
+sources. Implement allows pending plans; review requires done items and evidence for changes.
+Unconfigured/legacy projects keep their existing readiness behavior. See [Artifact contract](artifact-contract.md).

package/docs/cli.md

@@ -12,14 +12,15 @@ Exit 0 means the requested operation succeeded; 1 means validation/I/O/drift fai
 | resolve | --source; --adapters a,b; --capabilities a,b | Validate module selection and compatibility; read-only |
 | verify | --scope adapters/core/capabilities/all | Read installed advisory checks; executed false, no subprocesses |
 | eval | --scope adapters/core/capabilities/all; --report FILE | Emit unscored template or aggregate reviewed report; no model calls |
-| init | --detect OR --adapters a,b; --capabilities a,b; --source; --dry-run; --allow-major | Install a snapshot; exact rerun is idempotent |
+| init | --detect OR --adapters a,b; --capabilities a,b; --agent-preset recommended/economy/custom; --source; --dry-run; --allow-major | Install a snapshot and seed project agent preferences; exact rerun without explicit preset is idempotent |
 | update | --source; --dry-run; --allow-major | Update unedited owned files and seed missing project files |
 | check | none | Compare installed files/block with lock and selection; no writes |
 | doctor | none | check plus configured environment/path diagnostics and generic PATH hints; no execution |
-| setup | none | Read-only host-facing question plan; skips tool-selection suggestions when tools are configured |
+| setup | --host codex/claude-code/gemini-cli/cursor/copilot/custom-ID (optional) | Read-only question and agent-routing plan; skips tool-selection suggestions when tools are configured |
+| artifacts | none | Report declared inputs/outputs/storage/write policy and host connection aliases; no discovery or tool calls |
 | ready ID | --stage implement/review | Structural readiness; blocked returns exit 1, ready returns exit 0; no business approval |
 | new-change ID | none | Create an unapproved OpenSpec draft using installed templates |
-| new-doc TYPE | none | Copy a selected locked Product template to `docs/discovery/` (idea, research) or `docs/product/` (other types) without overwriting |
+| new-doc TYPE | --capability ID (default product) | Copy one selected locked template into the owner's project docs without overwrite; Product idea/research use `docs/discovery/`, other Product types use `docs/product/` |
 | skills | none | List installed skill metadata only |
 | skill NAME | none | Read one installed, locked skill |
 
@@ -145,3 +146,14 @@ existing files are validated/preserved and explicit preset overwrite is refused.
 (or claude-code/gemini-cli/cursor/copilot/custom ID) exports resolved roles and compatibility limitations
 without probing models or editing host files. No extra config command, runtime or usage tracking.
 See [Agent configuration](agent-configuration.md).
+Setup exit 0 means the read-only plan was produced, not that all models are usable. Inspect the nested
+agent_configuration.status and active route availability; host-incompatible/unverified requests require
+actual host checks before execution.
+
+## Artifact contract
+[Input/output/storage and integrations](artifact-contract.md) are project-owned configs. Init/update
+seed absent configs and preserve existing bytes; check validates schemas/references before writes.
+`aih artifacts` is read-only; setup suggests missing storage decisions. Explicit docs routes override
+legacy new-doc folders; external routes return a template/host handoff with executed false and no
+local fallback. Configured output contracts require reviewed artifact-impact.json coverage in ready;
+review stage requires declared completion/evidence. No remote calls, source writes or approval claims.

package/docs/documentation-workflows.md

@@ -76,3 +76,10 @@ For new/material journeys, reuse existing BA documents and continue with [Soluti
 PO defines a usable MVP and evidence-backed outcomes, SA evaluates quality/architecture/contracts,
 PM sequences dependent value slices. Accepted decisions and requirement IDs feed OpenSpec and adapters.
 Depth scales to the task; no mandatory full document set for small fixes. Use [tool setup](tool-setup/README.md).
+
+## Input/output storage and source maintenance
+Use [Artifact contract](artifact-contract.md) before authoring: reuse known locations or ask where
+docs/UI should be maintained, record canonical owner and source revisions, then use proportional
+templates. Existing sources are read-only/propose/write as declared; host authorization still applies.
+Update affected docs/spec/UI with the change and record artifact-impact evidence. new-doc respects
+local output folders or returns a host handoff for external targets, without publishing itself.

package/docs/end-to-end-workflow.md

@@ -104,6 +104,10 @@ Project tự sở hữu các file `docs/product/` và cập nhật `traceability
 - **No code yet:** Product + UI/UX có thể dừng sau design gate, không tạo PR implementation giả.
 
 ## 5. Verify, eval và hồ sơ release
+Web/mobile implementation and testing use [Frontend/mobile coding](frontend-mobile.md): select the
+feature/screen skill plus relevant testing/boundary skills, preserve existing common APIs and hand off
+actual browser/server or per-platform native evidence. Load only needed skill bodies for simple tasks.
+
 
 ~~~bash
 aih verify --scope all

package/docs/examples/fullstack-web.md

@@ -52,11 +52,15 @@ 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-feature-delivery
 aih skill harness-react-nextjs-accessible-ui
 aih skill harness-react-nextjs-server-boundaries
+aih skill harness-react-nextjs-behavior-testing
 ~~~
 
 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.
+Chỉ đọc skill body cần cho task; reuse client/query/FormField hiện có. Skills delivery/testing bao phủ
+route/form/API/state và AC-linked component/browser evidence; không ép plain React dùng Next.js.
 
 Ví dụ kiểm tra **chỉ nếu repo có tương ứng**:
 

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

@@ -28,14 +28,18 @@ Nếu chỉ sửa một lỗi offline đã có ticket/AC duyệt, có thể bỏ
 aih new-change offline-draft-sync
 aih skill harness-spec
 aih skill harness-tdd
+aih skill harness-react-native-screen-delivery
 aih skill harness-react-native-offline-sync
 aih skill harness-react-native-device-permissions
+aih skill harness-react-native-behavior-testing
 ~~~
 
 - `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ó.
+- Dùng screen-delivery để reuse navigation/theme/client/form và behavior-testing cho test matrix;
+  chỉ nạp offline/permissions khi task chạm rủi ro đó. JS mocks không chứng minh native/device behavior.
 
 **Verification** — tùy project scripts/toolchain, không được Harness thực thi:
 

package/docs/frontend-mobile.md

@@ -0,0 +1,76 @@
+# Code React/Next.js và React Native
+
+Adapter có rules/conventions và skills cho implementation, kiểm thử cùng các rủi ro chuyên biệt.
+Không cần thêm bộ skills ngoài để bắt đầu. Chỉ cài module phù hợp; AI đọc một skill khi task cần nó.
+
+## Init và bắt đầu
+
+Trong repository ứng dụng đã tạo, chọn **một** lệnh theo stack:
+
+```bash
+# React web hoặc Next.js
+aih init --adapters react-nextjs
+# React Native hoặc Expo
+aih init --adapters react-native
+```
+
+Sau đó chạy `aih check`, `aih setup --host codex` (đổi host theo công cụ thực tế), mở AI tool và giao:
+
+> Đọc AGENTS.md và workflow project-setup. Khảo sát router, versions, common components, API client,
+> form/state/navigation và test setup. Dự án này cần [tính năng]. Hỏi phần còn thiếu, đề xuất slice/MVP
+> và kiến trúc phù hợp, sau đó implement theo conventions hiện có và báo cáo checks thực chạy.
+
+Core đã có TDD/debug/review. Nếu cần thiết kế UX/Figma, thêm `--capabilities uiux` khi init mới.
+Nếu cần khám phá ý tưởng/MVP/kiến trúc/kế hoạch, thêm `product,architecture,delivery`; không bắt task nhỏ
+tạo đủ tài liệu. Dự án đã cài đổi `.harness/project.json` rồi review update, không re-init với lựa chọn khác.
+Harness không tạo app/framework, cài libraries hoặc cấu hình Figma/native AI host.
+
+## Chọn skill theo việc
+
+| Việc | React/Next.js | React Native/Expo |
+| --- | --- | --- |
+| Route/screen, form, CRUD/search, API và state | `harness-react-nextjs-feature-delivery` | `harness-react-native-screen-delivery` |
+| Test hành vi và luồng | `harness-react-nextjs-behavior-testing` | `harness-react-native-behavior-testing` |
+| Rủi ro chuyên biệt | `harness-react-nextjs-accessible-ui`, `harness-react-nextjs-server-boundaries` khi có Next server | `harness-react-native-offline-sync`, `harness-react-native-device-permissions` khi cần |
+
+`aih skills` liệt kê metadata; `aih skill <id>` đọc một body. AI có thể chọn skill qua description và
+đọc `.agents/skills/<id>/SKILL.md`, không cần bạn gọi từng role. Xem [Skill matrix](skill-matrix.md).
+Skill IDs dưới namespace react-nextjs cũng dùng cho React web; plain React không bị ép chuyển Next.js.
+
+## Dự án mới và maintain
+
+Với maintain, đọc feature tương tự trước: reuse UI public APIs, theme, form schema, client/query keys,
+auth/state/router và test helpers. Không tạo thêm HTTP client, store, navigation container hay wrappers
+khi common hiện tại đáp ứng. Với dự án mới, đề xuất cấu trúc feature và state/data boundaries vừa đủ;
+so sánh các lựa chọn quan trọng trước khi chốt. Ports/adapters, factory hay global state cần vấn đề cụ thể,
+không áp như checklist. Xem [Project conventions](project-conventions.md) và [Solution workflow](solution-workflow.md).
+
+Web: xác định router/version; tách state UI/form/server, xử lý stale responses và pending mutations.
+Next server phải validate/authorize mỗi operation, giữ credentials và private caches đúng boundary.
+Mobile: xác định Expo/bare và platforms; giữ navigation/auth/account boundaries, keyboard/safe areas,
+lifecycle và secure storage. Offline queue/permissions chỉ thêm khi yêu cầu thực tế cần chúng.
+
+## Ví dụ đầu ra
+
+- Web search: route dùng client/query/FormField hiện có; loading/empty/error/latest-result; tests gắn AC,
+  keyboard/focus và build/browser evidence thực có. Không thêm Next.js vào React SPA.
+- Mobile profile: screen dùng navigator/theme/client đã có; validation/save/expiry/back/account changes;
+  JS/native/device matrix phân biệt Android và iOS, ghi rõ checks bị chặn.
+
+Đây là output minh họa, không phải kết quả đã chạy. [Full-stack example](examples/fullstack-web.md) và
+[React Native example](examples/react-native-app.md) liên kết skills vào luồng spec → code → review.
+
+## Kiểm chứng và nguồn
+
+Chạy lint/type/test/build theo scripts thực của ứng dụng. Browser checks phải có browser/server thật;
+mocked component test không chứng minh SSR/authorization. Với native, JS tests không xác minh iOS/Android;
+ghi simulator/device/build result riêng. `aih verify/eval` chỉ xuất checklist/dataset và không chạy chúng.
+Không có trial ứng dụng/browser/native hoặc live-model benchmark trong nâng cấp Harness này.
+
+Đối chiếu official docs theo version dự án (tham khảo ngày 2026-10-12):
+- [React state structure](https://react.dev/learn/choosing-the-state-structure): tránh duplicate/derived state lưu dư.
+- [Next.js testing](https://nextjs.org/docs/app/guides/testing): chọn đúng unit/component/E2E boundary;
+  kiểm tra runner support cho async Server Components.
+- [React Native testing](https://reactnative.dev/docs/testing-overview): tách JS component và native/device evidence.
+- [React Navigation auth flow](https://reactnavigation.org/docs/auth-flow/): chỉ áp dụng khi app đang dùng
+  React Navigation; giữ version-specific auth/back behavior, không mặc định cài router đó.

package/docs/getting-started.md

@@ -1,127 +1,83 @@
 # Bắt đầu với AI Harness
 
-**Cài một lần → ghi context dự án → giao việc cho AI → kiểm tra kết quả.**
-
-Cần Node.js **22+**, Git và một repository ứng dụng đã tồn tại. AI IDE/assistant phải đọc được file trong repository; cách tự nạp `AGENTS.md` và skills phụ thuộc AI host. CLI `aih` quản lý hướng dẫn, không chạy LLM hay tạo ứng dụng.
+**Cài vào project → mở AI → giao việc → review kết quả.** Cần Node.js **22+** và một thư mục project. Với dự án mới, tạo thư mục/repository trước; Harness không tạo ứng dụng hay chạy model.
 
 ## 1. Cài vào project
 
+Chạy tại thư mục gốc của project:
+
 ```bash
-npm install -g @manhd_d/ai-harness
-cd /path/to/existing-project
-aih init --adapters java-spring
-aih check
+npx --yes @manhd_d/ai-harness init --detect
 ```
 
-Chọn module theo nhu cầu, không cần cài cả bộ:
+Lệnh nhận diện stack từ file ở thư mục gốc và cài hướng dẫn tương ứng. Nếu báo chưa nhận diện được, thay `--detect` theo bảng; bỏ `--detect` để chỉ cài quy tắc chung (Core):
 
-| Nhu cầu | Tham số cho `aih init` |
+| Project / nhu cầu | Tham số cho `init` |
 | --- | --- |
-| Spring Boot API | `--adapters java-spring` |
-| React/Next.js + UI | `--adapters react-nextjs --capabilities uiux` |
-| Astro tool nhỏ | `--adapters astro` |
-| Website có quảng cáo | `--adapters astro --capabilities monetization` |
-| Viết tài liệu từ ý tưởng hoặc tài liệu BA | `--capabilities product` |
-| Spring + tài liệu + Kubernetes | `--adapters java-spring,kubernetes --capabilities product,devops` |
-
-`aih list` xem toàn bộ module. `aih init --dry-run` xem trước thay đổi với cùng tham số đã chọn. Với project đã cài, đổi module trong `.harness/project.json` rồi dùng `aih update`, không chạy lại `init` với lựa chọn khác.
-
-## 2. Ghi context và bắt đầu giao việc
-
-Chạy `aih setup` rồi nhờ AI đọc workflow `project-setup`. Đây là gợi ý cho AI host, không phải wizard
-nhập liệu của CLI. AI đọc repo trước, chỉ hỏi 1–3 câu A/B/C cho điểm còn thiếu, có đề xuất và lý do.
-Không cần xác nhận lại thông tin hoặc quyền triển khai đã có.
-
-Điền `.harness/local.md` bằng thông tin thực của project:
-
-- 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ý.
+| Spring Boot | `--adapters java-spring` |
+| React / Next.js | `--adapters react-nextjs` |
+| React Native / Expo | `--adapters react-native` |
+| Python AI / RAG | `--adapters ai-python` |
+| Astro tool / website | `--adapters astro` |
+| Spring + Next.js | `--adapters java-spring,react-nextjs` |
+| Viết tài liệu BA | `--capabilities product` |
 
-Lệnh/tool chung thuộc `.harness/environment.json`; đường dẫn máy riêng thuộc file ignored
-`.harness/machine.json`. `aih doctor` kiểm tra tham chiếu biến và sự hiện diện công cụ, không chạy chúng.
-Xem [cấu hình Maven nội bộ](project-configuration.md).
-
-## 3. Tài liệu và spec khi cần
-
-Với capability `product`:
+Ví dụ vừa code Spring vừa viết tài liệu:
 
 ```bash
-aih new-doc prd-lite
+npx --yes @manhd_d/ai-harness init --adapters java-spring --capabilities product
 ```
 
-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:
+Thêm `--capabilities uiux` khi cần UI/UX; `monetization` cho website có quảng cáo. [Danh mục đầy đủ](cli.md).
+Với project đã cài, đổi lựa chọn trong `.harness/project.json` rồi dùng `update`.
 
-```bash
-aih new-change add-customer-search
-```
+## 2. Mở AI và giao việc
 
-Đây là bản nháp trong `openspec/changes/add-customer-search/`, chưa phải spec được duyệt.
-AI ghi câu trả lời thực tế trong `decisions.json`; kiểm tra bằng `aih ready add-customer-search --stage implement`.
-Sau code, ghi bằng chứng trong `verification.json` và chạy với `--stage review`. Xem [Change readiness](change-readiness.md). Sửa nhỏ, ít rủi ro có thể bỏ qua full spec với lý do rõ ràng; không bắt mọi task tạo đủ BRD/PRD/SRS.
+Mở thư mục project trong công cụ AI, rồi gửi:
 
-`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).
+> Đọc AGENTS.md và .harness/local.md. Khảo sát code, tài liệu và lệnh test hiện có;
+> ghi context còn thiếu vào .harness/local.md, chỉ hỏi phần chưa rõ.
+> Thực hiện yêu cầu: [mô tả công việc]. Chạy test phù hợp, báo cáo kết quả và phần chưa kiểm chứng.
 
-## 4. Kiểm tra đúng thứ
+Bạn có thể giao ý tưởng, tài liệu BA hoặc task code. Không cần gọi từng agent/skill.
+Với web/mobile, giao màn hình hoặc tính năng theo common/API/state/navigation hiện có; [skills đã có](frontend-mobile.md).
+Nếu công cụ chưa tự nạp hướng dẫn, xem [cách cấu hình công cụ AI](tool-setup/README.md).
+Lệnh `setup` chỉ xuất gợi ý thiết lập, không phải bước bắt buộc để bắt đầu.
 
-| Lệnh | Ý nghĩa |
-| --- | --- |
-| `aih check` | Kiểm tra integrity của file Harness; không kiểm thử ứng dụng |
-| `aih doctor` | Kiểm tra công cụ và environment đã cấu hình; không chạy build/test |
-| `aih verify --scope all` | Xuất checklist, `executed: false`; không chạy build/test |
-| `aih eval --scope all` | Xuất tình huống và báo cáo chưa chấm; không gọi model |
-| Lệnh test của project | Do bạn, AI host hoặc CI thực chạy để xác minh code |
+Review diff và test, rồi commit `AGENTS.md`, `.harness/`, `.agents/skills/` cùng code.
+Quy tắc riêng sửa trong `.harness/local.md`; giữ nguyên file do Harness quản lý.
+Lệnh/tool chung lưu trong `.harness/environment.json`; đường dẫn riêng máy trong `.harness/machine.json` được Git ignore. [Cấu hình Maven/JDK](project-configuration.md).
+Cấu hình model là tùy chọn trong `.harness/agents.json`; chọn model tương thích với công cụ AI: [hướng dẫn](agent-configuration.md).
 
-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.
+## 3. Thêm tài liệu khi cần
 
-## 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:
+Với `product` đã cài, tạo bản nháp yêu cầu:
 
 ```bash
-npm install -g @manhd_d/ai-harness@latest
-aih --version
-aih check
-aih update --dry-run
-aih update
-aih check
+npx --yes @manhd_d/ai-harness new-doc prd-lite
 ```
 
-`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
+Tính năng cần spec riêng: dùng `new-change <id>`; [hướng dẫn spec](change-readiness.md).
+Task nhỏ không cần bộ tài liệu đầy đủ. Không cần cài OpenSpec CLI để tạo bản nháp.
 
-- [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.
+## 4. Kiểm tra và cập nhật
 
-## Coding conventions
+`check` kiểm tra file Harness; `verify` xuất checklist. Code cần **test của project** và review thực tế.
 
-Trước code, áp dụng [Project conventions](project-conventions.md): xác định new/maintain/mixed theo module, đọc chuẩn hiện có, tìm common và ghi lý do tạo mới. AI lưu nguồn và quyết định trong `.harness/local.md`; không hỏi lại thông tin đã rõ.
+Trước cập nhật, tạo branch và commit trạng thái hiện tại. Xem trước, áp dụng rồi kiểm tra:
 
-## BA/PO/SA/PM and coding tools
+```bash
+npx --yes @manhd_d/ai-harness@latest update --dry-run
+npx --yes @manhd_d/ai-harness@latest update
+npx --yes @manhd_d/ai-harness@latest check
+```
 
-For a material new project choose `--capabilities product,architecture,delivery` with the actual adapter.
-Read [Solution workflow](solution-workflow.md) and the [setup guide for your coding tool](tool-setup/README.md).
-Skills/templates are selective context; use existing approved documents and compact notes when sufficient.
+Review diff và chạy test project trước khi commit. Nếu có conflict, xem [cách xử lý](cli.md).
+Dùng thường xuyên có thể cài global: `npm install -g @manhd_d/ai-harness`, rồi dùng `aih` thay cho `npx --yes @manhd_d/ai-harness`. Nâng CLI global trước khi `aih update`.
 
-## Agent model and execution preferences
+[Tra cứu & ví dụ theo nhu cầu](README.md).
 
-New installs seed `.harness/agents.json`: Sol recommended, hybrid/two concurrent agents only when
-supported; Luna low documentation, no automatic Astra escalation. Edit provider/model/reasoning and
-execution for your actual host. Use `aih setup --host codex` and [Agent configuration](agent-configuration.md).
-For a new economy consumer use `aih init --agent-preset economy`; never overwrite an existing config.
+## Docs/UI destinations
+For idea-driven or existing-doc work, ask the AI to reuse or clarify input/output destinations,
+canonical owners and source-write scope. Record them in project-owned artifacts.json/integrations.json;
+`aih artifacts` shows declarations. See [Artifact contract](artifact-contract.md).

package/docs/harness-maintenance.md

@@ -12,6 +12,7 @@ gốc được liên kết bên dưới; không sao chép quy tắc thành nhi
 | Adapter | [Registry](../harness.yaml), [adapter contract](adapters.md), [adapter assets](../adapters/) | Manifest `rules/skills/verification/evaluation` → [bundle/install](../cli/harness.js) → [installed verify/eval](../cli/adapters.js) |
 | Capability / skill | [Capability assets](../capabilities/), [schema/loader](../cli/capabilities.js) | Workflow/role bàn giao → exposed skill → [skill matrix](skill-matrix.md), [handoffs](agent-handoffs.md), [composition evals](../core/evals/composition.json) |
 | CLI / config | [CLI reference](cli.md), [implementation](../cli/), [templates](../templates/) | [Architecture/ownership](architecture.md), [project configuration](project-configuration.md), [tests](../tests/), [package smoke](../scripts/smoke-package.js) |
+| Artifact / integration contracts | [Artifact contract](artifact-contract.md), [loader](../cli/artifacts.js), [seeds](../templates/artifacts.json) | Preserved project configs → setup/artifacts → Core/Product/UIUX workflows → routed new-doc / impact readiness → [tests](../tests/artifacts.test.js) and package smoke |
 | Agent preferences | [Canonical default](../config/agents.default.json), [configuration contract](agent-configuration.md) | Project-owned `agents.json` → read-only setup plan → [routing workflow](../core/workflows/agent-routing.md) → [host setup](tool-setup/README.md); tests verify preservation, not live model availability |
 | Quy trình sử dụng | [Getting started](getting-started.md), [full SDLC](end-to-end-workflow.md) | [Examples](examples/), [README](../README.md), [documentation workflows](documentation-workflows.md) |
 | Release / migration | [Versioning](versioning.md), [release policy](release-policy.md) | [Changelog](../CHANGELOG.md), [npm release](npm-release.md), [release workflow](../.github/workflows/npm-publish.yml) |