@manhd_d/ai-harness 0.7.0 → 0.8.0

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

@@ -1,6 +1,6 @@
 # Full SDLC — Idea → Product → UI/UX → Spec → Code → Test → PR → Release → Operate
 
-Tài liệu này là **bản đồ điều phối** toàn bộ Core + Product + UI/UX + technology adapters + DevOps. Mỗi module vẫn có workflow riêng; chỉ **kích hoạt module đã cài và thật sự liên quan**, không bắt buộc dùng đủ tất cả cho một change. Bắt đầu với [Getting started](getting-started.md); xem [ma trận 53 skills](skill-matrix.md) và [role handoffs](agent-handoffs.md).
+Tài liệu này là **bản đồ điều phối** toàn bộ Core + Product + Architecture + Delivery + UI/UX + technology adapters + DevOps. Mỗi module vẫn có workflow riêng; chỉ **kích hoạt module đã cài và thật sự liên quan**, không bắt buộc dùng đủ tất cả cho một change. Bắt đầu với [Getting started](getting-started.md); xem [ma trận 64 skills](skill-matrix.md) và [role handoffs](agent-handoffs.md).
 
 > **Ranh giới thực thi:** `aih` cài/gợi ý rules, templates, skills và check/eval **advisory**. AI host/IDE và các công cụ bên ngoài thực hiện phân tích, code, test và tương tác hệ thống trong phạm vi được cấp quyền. Không có `aih run` hay `aih deploy`; các hành động ghi Figma, production hoặc merge phải có phê duyệt.
 
@@ -41,6 +41,8 @@ Lệnh trên là **ví dụ một repo chứa BE/FE/manifests**; nếu frontend/
 | **1. Intake** | Ý tưởng, ticket, Confluence/PDF được phép đọc, version/source, scope | Product: `knowledge-analysis`, `business-analysis`; BA | Source register, FACT/INFERENCE/UNKNOWN, AS-IS/TO-BE, quyết định còn thiếu |
 | **2. Business & Product** | Nguồn có traceability, mục tiêu, rules, NFR | Product: `brd-generation`, `prd-generation`, `user-stories`, `acceptance-criteria`, `backlog-prioritization`, `document-review`, `traceability`; PM/PO/requirements reviewer | PRD-lite hoặc BRD/PRD/SRS/UC khi cần, story IDs, AC, backlog; **Gate A: stakeholder duyệt**, không gắn nhãn Approved bởi AI |
 | **3. UX/UI (nếu cần)** | Approved PRD/stories/AC; Figma file và quyền (nếu dùng) | UI/UX: `requirements-analysis` (chỉ khi cần), `user-flow`, `screen-planning`, `design-system`, `figma-design`, `design-review` | User flows, screen specs, component/tokens, Figma node IDs; **Gate B trước ghi Figma**, gate sau design review |
+| **3a. Solution architecture (when material)** | Reviewed MVP/AC, existing decisions and constraints | Architecture skills/SA and reviewer | Source-linked context, NFR scenarios, module/data/contracts, ADRs and critical failure flows |
+| **3b. Delivery planning (when material)** | Accepted scope/design, known estimates/dependencies | Delivery skills/Project Manager | Value slices, owners, risks, checkpoints and actual estimate authority |
 | **4. Technical spec** | Approved requirements, API constraints, architecture, DB/event contracts | Core: `harness-spec`, planner; tech adapter phù hợp; OpenSpec | `openspec/changes/<change-id>/` (proposal, design, tasks, delta specs), measurable AC; **Gate C: duyệt thay đổi có ảnh hưởng** |
 | **5. Implementation** | Change được duyệt, kiến trúc, repo, tests | Core: `harness-tdd`, `harness-debugging` khi sửa lỗi; Spring/React/Native/AI adapter theo stack; implementer | Minimal code diff, unit/integration/contract tests, migration plans, không thay đổi unrelated files |
 | **6. Verify & code review** | Diff, specs, test logs thực chạy | Core: `harness-review`, `harness-ai-evaluation` nếu AI; test-engineer/security-reviewer; `aih verify/eval --scope all` (chỉ plan) | Evidence của test chạy thực tế, scope chưa test, security findings, trace requirement → test; **Gate D: human PR review** |
@@ -114,3 +116,10 @@ aih check
 **Checklist hoàn thành một change:** scope và approved AC rõ; diff có trace; tests thực chạy với kết quả chính xác; security/permissions đã review; CI xanh; PR được human quyết định; deployment (nếu có) có artifact/environment approval; OpenSpec archive/sync **chỉ sau khi các PR liên quan đã merge**, thông qua upstream CLI/human được quyền.
 
 Xem [handoff contracts](agent-handoffs.md), [OpenSpec integration](openspec.md), [DevOps PR-to-production](../capabilities/devops/workflows/pr-to-production.md) và các [ví dụ theo stack](getting-started.md#ví-dụ-thực-hành).
+
+For new/material journeys use [Solution workflow](solution-workflow.md); for existing clear fixes keep
+a compact source/impact note. Set up the host with [Coding tools](tool-setup/README.md).
+
+Before assigning roles, apply [Agent configuration](agent-configuration.md) and Core routing workflow.
+Use one session for simple work, hybrid only for independent authorized work with host support, and
+carry short source/evidence handoffs. User preferences do not grant runtime permissions or model access.

package/docs/getting-started.md

@@ -108,3 +108,20 @@ Nếu cài local trong project, dùng `npm install --save-dev @manhd_d/ai-harnes
 - [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.
+
+## Coding conventions
+
+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õ.
+
+## BA/PO/SA/PM and coding tools
+
+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.
+
+## Agent model and execution preferences
+
+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.

package/docs/harness-maintenance.md

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

package/docs/monetization.md

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

package/docs/project-configuration.md

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

package/docs/project-conventions.md

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

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

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

package/docs/skill-matrix.md

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

package/docs/solution-workflow.md

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

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

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

package/docs/tool-setup/README.md

@@ -0,0 +1,70 @@
+# Setup AI Harness with coding tools
+
+Official discovery docs reviewed 2026-10-12. Authenticate/install the chosen host with its official
+instructions, then run Harness in the actual repository. Host/version/account capabilities vary;
+these are setup recipes, not a claim that native client behavior was tested in this workspace.
+
+## Common setup
+```bash
+npm install -g @manhd_d/ai-harness
+aih init --adapters java-spring --capabilities product,architecture,delivery
+aih check
+aih setup
+aih doctor
+aih skills
+```
+Node.js 22+ is required by Harness; app stack remains independent. Replace adapter selection with
+react-nextjs/react-native/astro as appropriate. A coding-only maintain task can use just Core + adapter.
+For an existing install, edit .harness/project.json and reviewed update --dry-run/update/check.
+
+Fill .harness/local.md with mode, source docs/MVP/ADRs, public boundaries and actual commands; use
+[project configuration](../project-configuration.md) for Maven/JDK/settings and ignored machine paths.
+Do not bypass runtime permission policy or publish credentials. Configure GitHub/Figma/Confluence MCP
+only when needed, with the host's official setup and authorized access; Harness does not connect accounts.
+
+| Host | Project entry | Skill handling | Guide |
+| --- | --- | --- | --- |
+| Codex CLI/IDE | AGENTS.md and applicable nested/override instructions | .agents/skills native discovery | [Codex](codex.md) |
+| Claude Code | Direct AGENTS support varies with current configuration/version; CLAUDE.md import fallback | .claude/skills wrapper when native slash invocation is desired; manual canonical read always possible | [Claude Code](claude-code.md) |
+| Cursor | AGENTS.md; existing .cursor/rules may also apply | .agents/skills discovery | [Cursor](cursor.md) |
+| Copilot | Client-specific AGENTS support or .github/copilot-instructions.md pointer | CLI supports .agents/skills; IDE support depends on client/version | [Copilot](copilot.md) |
+| Gemini CLI | GEMINI.md import or context.fileName includes AGENTS.md | .agents/skills workspace alias | [Gemini CLI](gemini-cli.md) |
+
+Preserve existing host files; merge only a reviewed pointer/import, never replace the whole config.
+Bridges are project-owned and not managed by aih. Keep one canonical skill body in .agents/skills;
+never copy every rule into each host config or advertise markdown role files as native agents.
+
+## Read-only setup smoke test
+Ask the host:
+```text
+Read the applicable AGENTS.md and .harness/local.md. Do not modify files or execute commands.
+State the selected adapters/capabilities and exact installed paths for solution-framing and one
+relevant skill. Summarize current project mode, known MVP/architecture decisions and missing facts.
+Explain which declarations the configured test command comes from; do not claim any test ran.
+```
+Expected: actual source paths, correct selection and no fabricated file/command/result. If automatic
+skill discovery fails, explicitly ask to read .agents/skills/<installed-name>/SKILL.md. `aih skills`
+is a catalog, and `aih skill <name>` prints canonical instructions; neither invokes an AI model.
+
+## Start prompts
+| Task | Prompt |
+| --- | --- |
+| Idea → MVP | Read Product product-to-solution; clarify the useful user journey, in/out scope and minimum quality before proposing architecture. |
+| Existing BA docs | Use the approved source/revision, extract only this change's requirements and gaps; preserve authoritative docs. |
+| SA design | Read Architecture discovery-to-design; compare minimal viable options, NFRs and justified feature patterns with actual decision sources. |
+| Maintain | Inspect touched module/code/tests and public common APIs; follow existing architecture and update only affected project-map entries. |
+| Delivery | Plan value slices/dependencies using real team estimates; unknown dates remain unknown; link AC/ADRs/OpenSpec. |
+
+## Update and troubleshoot
+Update the global CLI, then review snapshot update --dry-run/update/check. Restart/reload host discovery
+where required; read-only smoke again after setup changes. Keep custom host bridges and local.md.
+If a managed file conflicts, reconcile with Git rather than editing lock hashes. Check workspace root,
+nested override precedence, host context/trust settings, module selection and installed skill paths.
+Private VPN/tool access may be unavailable remotely; report blocked builds rather than inventing success.
+No logged-in host/MCP or live-agent smoke was run for these docs; follow each linked official guide.
+
+## Agent/model preferences
+
+Review [Agent configuration](../agent-configuration.md) and run `aih setup --host <id>` for a declared
+routing plan. Validate native model/effort in the actual picker/client; no account availability is
+probed or host config overwritten. Incompatible defaults need your explicit provider/model mapping.

package/docs/tool-setup/claude-code.md

@@ -0,0 +1,57 @@
+# Claude Code
+
+Install/authenticate with [official setup](https://code.claude.com/docs/en/setup), then follow
+[common setup](README.md) and launch `claude` at the repository root.
+
+## Instructions
+Current Claude documentation describes direct AGENTS.md support with version/configuration conditions.
+If direct discovery is unavailable, add the following import to an existing project CLAUDE.md, or
+create the file if absent, without discarding any other content:
+```markdown
+@AGENTS.md
+```
+Check the host's loaded project instructions and nested/global files. Keep one canonical AGENTS;
+do not add a hook that prints a duplicate copy. The import remains a documented compatibility option.
+
+## Skills
+Claude documents .claude/skills for project skills. Harness does not assume .agents/skills is a native
+Claude skill location. Manual canonical loading from AGENTS instructions works without slash registration.
+If you want native invocation for a selected skill, create a small project-owned wrapper at
+.claude/skills/harness-product-mvp-definition/SKILL.md:
+```markdown
+---
+name: harness-product-mvp-definition
+description: Define an MVP using this project's installed AI Harness instructions.
+---
+Read the applicable AGENTS.md and then the canonical project file
+.agents/skills/harness-product-mvp-definition/SKILL.md. Follow its procedure and handoff;
+keep actual owner decisions and verification status explicit.
+```
+Then use `/harness-product-mvp-definition` in a supporting session. This wrapper is a pointer,
+not a copied skill body; maintain only needed wrappers and preserve existing native skills.
+
+## Verify and use
+Run the [read-only smoke prompt](README.md) before an implementation task. Check actual paths and
+known decisions, then use the idea/document/SA/maintain prompts on that page. If discovery is missing,
+ask to read the exact installed `.agents/skills/harness-*/SKILL.md` relevant to the task; do not paste
+all skill bodies. Application commands come from local.md/environment.json and actual build files.
+Follow host permission settings; no instruction creates missing account, network or tool access.
+
+## Update / troubleshooting
+Use the common reviewed CLI/snapshot update procedure. Preserve existing project/global host config,
+review nested instructions and restart/reload the host when discovery changes. A Harness integrity
+check is separate from host discovery, app build or behavioral compliance. Native client login/setup
+was not exercised here; official references below establish the documented discovery mechanism.
+
+## Official references (checked 2026-10-12)
+- [Memory, AGENTS and imports](https://code.claude.com/docs/en/memory)
+- [Project skills and invocation](https://code.claude.com/docs/en/skills)
+
+## Native model configuration
+Use [Agent preferences](../agent-configuration.md) with an explicitly available Anthropic model or
+reviewed host mapping. OpenAI Sol/Astra preferences cannot run directly in Claude Code. Native model
+selection follows [official model config](https://code.claude.com/docs/en/model-config); use /model and
+client-supported effort controls, preserving existing settings/authentication. Native per-role agents
+use [official subagent format](https://code.claude.com/docs/en/sub-agents) in .claude/agents with model
+and supported effort settings. Role contracts can be referenced by a short instruction. aih does not
+write these files, infer account access or equate native Claude reasoning with OpenAI reasoning.

package/docs/tool-setup/codex.md

@@ -0,0 +1,44 @@
+# Codex CLI and IDE
+
+Install/authenticate Codex from [official CLI](https://developers.openai.com/codex/cli/) or
+[IDE extension](https://developers.openai.com/codex/ide/), then follow [common setup](README.md).
+Launch `codex` or open the IDE at the initialized repository root.
+
+## Instructions and skills
+Codex reads AGENTS.md through its project hierarchy and can prefer AGENTS.override.md. Inspect
+applicable global/nested overrides when behavior differs; do not overwrite user defaults.
+Harness exposes declared skills in .agents/skills, the documented repository skill path. Start a new
+session after setup/update if needed; ask for one installed skill by name or canonical path.
+Markdown role contracts in .harness/core/agents and selected capabilities are read by the host;
+they are not automatically installed as native Codex subagents. .harness/local.md remains project context.
+
+## Verify and use
+Run the [read-only smoke prompt](README.md) before an implementation task. Check actual paths and
+known decisions, then use the idea/document/SA/maintain prompts on that page. If discovery is missing,
+ask to read the exact installed `.agents/skills/harness-*/SKILL.md` relevant to the task; do not paste
+all skill bodies. Application commands come from local.md/environment.json and actual build files.
+Follow host permission settings; no instruction creates missing account, network or tool access.
+
+## Update / troubleshooting
+Use the common reviewed CLI/snapshot update procedure. Preserve existing project/global host config,
+review nested instructions and restart/reload the host when discovery changes. A Harness integrity
+check is separate from host discovery, app build or behavioral compliance. Native client login/setup
+was not exercised here; official references below establish the documented discovery mechanism.
+
+## Official references (checked 2026-10-12)
+- [AGENTS discovery](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
+- [Skill discovery](https://learn.chatgpt.com/docs/build-skills)
+
+## Native model configuration
+Follow [Agent preferences](../agent-configuration.md), then verify model access and supported effort.
+The official [config guide](https://learn.chatgpt.com/docs/config-file/config-basic) supports a reviewed
+merge into .codex/config.toml for CLI/IDE:
+```toml
+model = "gpt-6.1-sol"
+model_reasoning_effort = "medium"
+```
+For deliberate native agents use the current [subagent guide](https://learn.chatgpt.com/docs/agent-configuration/subagents).
+Standalone .codex/agents/*.toml uses name, description and developer_instructions, with optional model
+and model_reasoning_effort. Keep a small instruction pointing to the installed role/skill, not duplicated
+bodies. No files are generated/applied by aih; actual schema/client/account and thread-limit semantics
+must be checked. A normal session does not switch model automatically per Harness role.