@manhd_d/ai-harness 0.13.0 → 0.15.0

package/docs/python-installation.md

@@ -0,0 +1,85 @@
+# npm, pip và cài offline
+
+Hai kênh dùng cùng Core, Agents, Skills, Workflows, Adapters và CLI JavaScript. npm cần Node.js 22+;
+pip cần Python 3.9+ **và Node.js 22+**. Wheel không tải Node, không phụ thuộc package Python khác,
+không chạy npm/npx và không kết nối mạng khi chạy `aih`. Host AI có yêu cầu mạng riêng.
+
+PyPI name: `manhd-ai-harness`. Đây là kênh bổ sung của bản phát hành tiếp theo; không coi feature
+PR là package đã xuất bản. Maintainer phải đăng ký tên/Trusted Publisher trước lần publish đầu.
+
+## Cài và dùng
+
+Trong virtualenv đã kích hoạt (khuyến nghị `.venv` hoặc virtualenv ngoài project):
+
+```bash
+python -m pip install manhd-ai-harness
+aih init --host codex
+aih check
+```
+
+Chọn host `codex`, `claude-code`, `cursor`, `copilot`, `gemini-cli` hoặc `kiro`. Mở session AI,
+gọi skill harness-start nếu host nhận diện; nếu không, gửi prompt đọc
+`.agents/skills/harness-start/SKILL.md`. Xem [setup đa IDE](tool-setup/README.md).
+
+Không cần npm. Nếu `aih` chưa nằm trong PATH, kích hoạt virtualenv hoặc dùng
+`python -m ai_harness.launcher`. Đặt `AIH_NODE` tới file `node`/`node.exe` khi Node không có trong PATH.
+Ví dụ PowerShell: `$env:AIH_NODE = 'D:\tools\node\node.exe'`.
+Không cài cả npm global và pip vào cùng PATH nếu không muốn lựa chọn executable mơ hồ;
+`Get-Command aih` (PowerShell) hoặc `command -v aih` xác định launcher đang dùng.
+
+## Công ty chặn npm và PyPI
+
+Trên máy có Internet, tải wheel của phiên bản đã phát hành:
+
+```bash
+python -m pip download --only-binary=:all: --no-deps manhd-ai-harness -d wheelhouse
+```
+
+Chuyển wheel, Python và Node portable/installer phù hợp OS/CPU vào máy công ty qua kênh được phép.
+Wheel là pure Python, dùng chung các OS; Node portable phải đúng nền tảng.
+Tại máy offline, kích hoạt virtualenv và chỉ định **đúng tên wheel đã tải**:
+
+```bash
+python -m pip install --no-index --no-deps wheelhouse/manhd_ai_harness-X.Y.Z-py3-none-any.whl
+aih init --host kiro --adapters java-spring
+aih check
+```
+
+X.Y.Z là placeholder cho release thực tế. `pip --no-index` không hỏi registry; `.whl` đã chứa toàn bộ
+payload nên không cần build tool hoặc dependencies. Không cần OpenSpec CLI để tạo draft.
+Package không thay cấu hình proxy/TLS của công ty. Nếu PyPI được phép và chỉ npm bị chặn, dùng pip
+trực tiếp. Có thể dùng mirror PyPI nội bộ đã được tổ chức phê duyệt.
+
+## Cập nhật
+
+```bash
+python -m pip install --upgrade manhd-ai-harness
+aih --version
+aih backup
+aih update --dry-run
+aih update
+aih check
+```
+
+Offline: thay lệnh đầu bằng `python -m pip install --no-index --no-deps --upgrade /path/to/new.whl`.
+pip cập nhật CLI; `aih update` cập nhật snapshot của **từng project**, không tải gì. Hai bước khác nhau.
+User config được giữ nguyên; managed drift vẫn chặn update. Backup + Git giữ khả năng rollback.
+Trong cùng release npm/pip dùng version từ package.json; không có version Python độc lập.
+
+## Build và phát hành
+
+`python scripts/build-python.py` tạo wheel/sdist bằng thư viện chuẩn. Backend PEP 517 trong
+pyproject.toml có `requires = []`; `python -m pip wheel --no-index --no-deps .` cũng build được offline.
+Không nhân bản source: payload lấy từ files allowlist của package.json, gồm cả hidden OpenSpec template.
+`python scripts/smoke-python.py` kiểm từng byte, cài wheel trong .venv, CLI, update/reinstall,
+Node thiếu, và rebuild sdist offline. Không gọi npm để build/install wheel.
+
+Workflow [npm-publish.yml](../.github/workflows/npm-publish.yml) build/test cả hai kênh từ cùng tag
+Release Please, publish npm rồi publish PyPI bằng wheel đã kiểm. Maintainer cấu hình PyPI Trusted
+Publisher: owner `manh0303`, repository `ai-harness`, workflow `npm-publish.yml`, environment `pypi`.
+Đặt environment review theo chính sách repo. Theo [PyPA guide](https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/).
+
+Hai registry không có transaction chung: npm có thể thành công còn PyPI lỗi. Rerun **job publish-pypi**
+của release đó khi đã sửa cấu hình, dùng cùng artifact; không đổi version để chữa lỗi xác thực.
+Artifact có thời hạn lưu của Actions; nếu hết hạn, rebuild từ đúng tag và kiểm payload/version trước
+khi publish phần thiếu. Feature PR không tự tag, merge hoặc publish.

package/docs/session-onboarding.md

@@ -0,0 +1,215 @@
+# Session onboarding và context đã lưu
+
+[Kiro quick start](tool-setup/kiro.md): `init --host kiro` → session đầu tiên → `/harness-start`.
+Core harness-start cũng dùng được khi host khác đọc canonical skill. Host hiểu dự án/hỏi/điền
+cấu hình; CLI không gọi model. `start --host kiro` luôn trả plan, không interview cả khi có TTY.
+Terminal intake cho các host khác tiếp tục được giữ.
+
+## Structured local.md
+
+YAML frontmatter subset hoặc JSON-compatible YAML schema 1; prose giữ bên dưới:
+
+```yaml
+---
+schema_version: 1
+stack:
+  language: java
+  version: "21"
+  framework: spring-boot
+  framework_version: "3.5.11"
+build:
+  tool: maven
+approved_deviations:
+  - id: approved-error-contract
+    rule: "Preserve the approved error contract"
+    reason: "Existing approved convention"
+    source: docs/backend-conventions.md
+sources:
+  - pom.xml
+  - docs/backend-conventions.md
+---
+```
+
+Phiên bản chỉ là ví dụ; host đọc dependency thực tế. stack/build là map string; quote versions.
+Mỗi deviation có id/rule/reason, source tùy chọn. sources là file local tương đối đã đọc, không
+`.env`, machine.json, Git nội bộ hoặc credentials. Không tự coi inferred deviation là approved.
+Parser hỗ trợ mapping, sequence, scalar, inline JSON; không anchors/aliases/tags, block scalar
+(`|`, `>`), implicit dates hay YAML phức tạp. Duplicate/unsupported/schema errors bị từ chối.
+Legacy prose vẫn hợp lệ, init/update giữ nguyên; host thêm frontmatter khi seed và bảo toàn prose.
+Cấu trúc này không bảo đảm hai model suy luận giống nhau.
+
+Đường dẫn máy ở ignored machine.json. Dùng `tools.maven.executable`, `files.maven-settings.path`
+và command ID như `commands.get-token`; không thêm `tools.maven.settings` hay underscore ID vào
+schema hiện có. [Maven example](project-configuration.md).
+
+## Seed và freshness
+
+```bash
+aih seed
+aih seed --record
+aih seed --check
+```
+
+seed read-only liệt kê nguồn cho host inspect. record yêu cầu structured local.md có ít nhất một
+nguồn đã đọc và tồn tại; ghi hash sau reconciliation. check không ghi, exit 1 khi missing/stale,
+exit 0 khi current. CLI không tự tạo tri thức hoặc xác nhận summary đúng.
+
+Theo dõi build manifests, AGENTS/README/OVERVIEW/conventions/testing/workflow files tối đa 4 tầng,
+cộng local.md.sources cho nguồn sâu hơn/tên riêng. Bỏ Git/vendor/build/cache và thư mục Harness/host.
+Giới hạn: 10000 entries, 256 auto sources, 128 explicit sources, 1 MiB/file; symlink không làm nguồn.
+Hash bao gồm source/context digests và bundle digest. Thêm/xóa/sửa nguồn báo stale; code thông thường
+không ép re-seed, trừ khi được khai báo làm nguồn. Refresh đúng assumptions bị ảnh hưởng rồi record lại.
+Remote revisions cần host kiểm tra; scoped AGENTS vẫn phải đọc dù hash current.
+
+knowledge.json project-owned, nằm ngoài managed lock, không có source text hoặc hash machine.json.
+Setup gián đoạn giữ partial facts; chỉ record cache sau khi đã đối chiếu. Hash phát hiện drift,
+không chứng minh factual correctness hay độ tin cậy của nguồn.
+
+## Skill prerequisites
+
+Skill frontmatter có requires tùy chọn:
+
+```yaml
+requires:
+  machine:
+    - tools.maven.executable
+  environment:
+    - files.maven-settings.path
+    - commands.get-token
+  mcp:
+    - project-db
+```
+
+`aih skills` xuất metadata này. `aih doctor --skill <name>` kiểm tra local references/presence,
+báo missing không in giá trị. Tìm explicit custom skill ở `.agents/skills/<name>/SKILL.md`,
+`.kiro/skills/<name>/SKILL.md` hoặc `plugins/<name>/SKILL.md`.
+Machine requirement cần override đã khai báo; dùng environment requirement nếu PATH/wrapper được
+chấp nhận. Không ép Maven cho skill không cần nó. MCP declaration vẫn unverified, host kiểm tra
+actual tools/quyền. Passing doctor không chứng minh build thành công.
+
+## Role extensions
+
+Trong map agents của agents.json:
+
+```json
+"core:security-reviewer": {
+  "model": "@balanced",
+  "reasoning": "high",
+  "extensions": ["plugins/project/agents/security-reviewer.md"]
+}
+```
+
+aih agents trả contract_load_order: canonical contract trước, extensions theo thứ tự. Host đọc
+và áp dụng chúng; CLI không ghép prose hay tạo agent. Extension bổ sung domain/conventions,
+không cấp quyền hoặc làm yếu core security. Missing file chặn role; contradictory facts cần đối chiếu
+nguồn/owner. Tối đa 16 project-owned Markdown, 64 KiB/file, không traversal/symlink.
+Transfer bỏ extension paths gắn repo cũ. Field delegate không thuộc schema; nếu đã dùng workaround
+đó, chuyển đường dẫn Markdown sang extensions và bỏ delegate trước update. CLI không tự đoán migration.
+
+## MCP alias discovery
+
+```bash
+aih sync-integrations --host kiro --dry-run
+aih sync-integrations --host kiro
+```
+
+Đọc user `~/.kiro/settings/mcp.json` rồi project `.kiro/settings/mcp.json`; project disabled override
+loại server khỏi discoveries. `--from <file>` đọc một config riêng, hỗ trợ absolute path.
+Chỉ thêm enabled server names vào integrations.json, read-only declaration. Không credentials,
+endpoint, command/env, autoApprove; không xóa/ghi đè declarations cũ. Alias collisions thêm suffix.
+Config không có actual tool inventory: host phải discovery tools/quyền và lưu evidence riêng.
+Read-only declaration không cưỡng chế permission; CLI không kết nối hoặc chạy server.
+
+## Propose sidecars
+
+aih new-change đã tạo sidecars từ locked templates. Với Kiro/upstream propose bên ngoài,
+`aih change-sidecars <id>` thêm `.openspec.yaml`, decisions.json, verification.json và
+artifact-impact.json còn thiếu, giữ file cũ. Workflow Harness dùng helper; không patch upstream CLI.
+
+## Backup / migration
+
+Shared context/config tiếp tục vào config backup. knowledge.json là cache tái tạo, không ở archive
+allowlist; full repo backup giữ nó. Machine/credentials không export. Extensions và custom host
+files backup cùng repo. Transfer giữ module/model preferences, bỏ repo autonomy và extensions.
+Update giữ configs/prose/cache; edited locked wrappers/hook chặn update. Rollback snapshot qua Git,
+rồi reconcile cache. Các lệnh này cần reviewed source/release; feature PR không tự bump/publish npm.
+Live Kiro/model loading và token savings chưa đo; local tests không thay phiên thực tế.
+
+## Clone repo và setup còn thiếu
+
+Giữ luồng chính `init --host kiro` → chat → `/harness-start`. Thành viên mới reuse tri thức dùng
+chung trong repo, chỉ bổ sung machine.json và thông tin còn thiếu. `aih setup` vẫn read-only:
+
+```bash
+aih setup --apply --dry-run
+aih setup --apply
+aih setup --greenfield
+aih start --compact --host kiro
+```
+
+`--apply` chỉ tạo shared config thiếu từ snapshot/templates đã cài, giữ bundle/lock/config cũ.
+Không điền đường dẫn máy, task hay knowledge cache. Nếu project.json thiếu, dựng lại selection từ
+lock; selection hiện có khác lock thì phải update. Schema/path/drift errors chặn trước ghi;
+ordinary write errors rollback. --dry-run cần --apply và không ghi target. Không recovery được
+câu trả lời tùy chỉnh đã mất: dùng Git/backup. `--greenfield` chọn guidance, không chốt kiến trúc.
+Không có CLI trong host: đọc templates để tạo file thiếu, báo CLI checks NOT_RUN. “Không cần tự
+gõ terminal” phụ thuộc host có quyền file/shell; clone không tự cài CLI hoặc đăng nhập host.
+Compact trả JSON task/stack/module để định hướng, bỏ source scan/interview; freshness là unchecked.
+
+## Quyết định dùng chung và phạm vi
+
+`.harness/decisions.json` dùng schema 1; không thay decisions.json của từng OpenSpec change:
+
+```json
+{
+  "schema_version": 1,
+  "decisions": [{
+    "id": "D-001",
+    "scope": "module:billing",
+    "status": "confirmed",
+    "question": "Which error contract applies?",
+    "answer": "Preserve the accepted module contract",
+    "reason": "Compatibility with existing consumers",
+    "source": "docs/billing-contract.md"
+  }]
+}
+```
+
+Scope là `project` hoặc `module:<slug>` (cho phép phân cấp như module:services/billing).
+Status proposed chỉ là đề xuất; confirmed cần answer/reason/source; superseded giữ các trường đó
+và superseded_by trỏ tới quyết định cùng scope đã confirmed hoặc superseded. Không duplicate ID,
+self-reference, cycle, missing/cross-scope/proposed replacement. Tối đa 256 quyết định; ID 64 ký tự,
+text 4096 ký tự, single-line. File không có trên snapshot cũ vẫn hợp lệ. CLI kiểm tra cấu trúc,
+không tự xác nhận nguồn có thực sự được phê duyệt; host/owner chịu trách nhiệm đối chiếu.
+
+`aih decisions --scope module:billing` trả project choices cộng đúng scope được chọn; không tự
+inherit các module cha/con. Host chọn thêm scope liên quan khi cần và xử lý mâu thuẫn, không tự
+cho module override project/security. Trước khi hỏi đọc các quyết định applicable rồi change-local
+decisions. Reuse confirmed khi nguồn/phạm vi còn hiệu lực; đổi nguồn/phạm vi có thể cần hỏi lại.
+do_not_ask_again boolean tùy chọn không khóa quyết định vĩnh viễn và không cấp quyền merge/deploy.
+Save từng câu trả lời/quan sát để resume; chỉ seed --record sau đối chiếu. Hash đổi khi decisions
+đổi; hash không chứng minh facts đúng. Legacy choices trong prose vẫn đọc được, không tự chuyển
+inference thành confirmed. Backup cùng dự án giữ file này; transfer sang dự án khác loại bỏ nó.
+
+## Kiểm chứng bằng host thật
+
+Local tests/package smoke kiểm tra CLI và file; chưa chứng minh model tuân thủ hoặc skill menu/hook
+đã hoạt động trên Kiro. Chạy trên workspace thử, ghi source commit, CLI/snapshot/host version, OS,
+model và invocation. Không dùng dữ liệu khách hàng hay credentials trong evidence.
+
+| Scenario | Quan sát bắt buộc |
+| --- | --- |
+| Dự án mới | /harness-start đọc idea/docs, chỉ hỏi thiếu; không ép stack/CI khi chưa cần |
+| Existing repo | Đọc scoped instructions và code mẫu; source-linked facts, machine paths riêng |
+| Clone thành viên mới | Reuse facts/quyết định chung, tạo file thiếu không đổi bundle/lock |
+| Đổi convention | seed báo stale, AI đọc nguồn đổi và cập nhật assumptions bị ảnh hưởng |
+| Ngắt giữa interview | Session sau reuse answers đã lưu; chưa ghi cache hoàn thành giả |
+| Quyết định được thay thế | Không áp dụng đáp án superseded/proposed; hỏi lại chỉ phần material |
+| Thiếu CLI/MCP/VPN | Nêu đúng blocker; không khẳng định access hoặc test đã pass |
+| Update/restore | Custom config giữ nguyên; backup/restore giữ history, transfer bỏ domain choices |
+
+Lưu raw transcript/command output và diff trước/sau (redacted), outcome PASS/FAIL/BLOCKED/NOT_RUN.
+Đo riêng số câu hỏi lặp, files/tool calls đã đọc, thời gian setup và token do host báo. Trường hợp
+host không cung cấp usage ghi unknown; không ước lượng thành số đo. So sánh cold start và session
+sau trên cùng fixture/model/host, ghi số lần chạy và biến động; chưa có baseline thì không công bố
+“18K → 2K” hoặc “45 phút → 5 phút”. Core eval scenarios tiếp tục unscored cho tới khi chạy thật.

package/docs/skill-matrix.md

@@ -1,6 +1,6 @@
-# Skill matrix — 66 skills, 15 nhóm module
+# Skill matrix — 68 skills, 15 nhóm module
 
-Đây là bảng tra cứu **ID thật** theo `SKILL.md` trong source trên `main` (6 Core, 42 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ộ 66 skill vào prompt.
+Đây là bảng tra cứu **ID thật** theo `SKILL.md` trong source trên `main` (8 Core, 42 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ộ 68 skill vào prompt.
 
 **Cách dùng:** `aih skills` xem skills đã cài, sau đó `aih skill harness-...` lấy nội dung. Danh mục này mô tả chức năng; **không** có nghĩa `aih` thực thi skills hoặc agent. Tech adapters và capabilities chỉ xuất hiện trong consumer khi được chọn; Core dùng chung.
 
@@ -14,10 +14,12 @@
 | Release → Operate | `devops`, `kubernetes` khi phù hợp | CI, container, manifests, rollout và SLO plan |
 | Traffic → Publisher Revenue | `monetization` (optional) | SEO growth, AdSense readiness, UX/consent checks, Page RPM review |
 
-## Core (6)
+## Core (8)
 
 | Skill ID (nguồn) | Khi nào dùng | Mục đích | Output mong đợi |
 | --- | --- | --- | --- |
+| [`harness-start`](../core/skills/harness-start/SKILL.md) | First session / setup / resume | Inspect before asking, save context/task | local/environment/start and knowledge freshness |
+| [`harness-end-user-testing`](../core/skills/harness-end-user-testing/SKILL.md) | End-user QA | Thao tác giao diện thật và kiểm tra luồng nghiệp vụ | AC → outcome/evidence, real/mocked scope, blockers |
 | [`harness-ai-evaluation`](../core/skills/harness-ai-evaluation/SKILL.md) | QA, AI eval | Đánh giá kết quả AI với dataset và ngưỡng đã review | Report chất lượng AI, regressions, release decision |
 | [`harness-debugging`](../core/skills/harness-debugging/SKILL.md) | Bugfix | Tái hiện và phân tích lỗi trước khi sửa | Reproduction, root-cause evidence, regression |
 | [`harness-review`](../core/skills/harness-review/SKILL.md) | Review | Đối chiếu diff với spec và rủi ro bảo mật | Severity findings, test coverage, recommendation |

package/docs/start.md

@@ -0,0 +1,43 @@
+# Bắt đầu một nhiệm vụ
+
+**Kiro: init --host kiro → session đầu tiên → /harness-start.**
+Kiro tự khảo sát và hỏi trong chat; [cài/upgrade/offline](tool-setup/kiro.md).
+`start --host kiro` trả plan, không phỏng vấn trong terminal. Session sau kiểm tra freshness
+và chỉ bổ sung context bị ảnh hưởng. [Seed và contracts](session-onboarding.md).
+
+**Host khác: init → start → làm việc trong AI tool.** Sau cài đặt, chạy trong project root:
+
+```bash
+npx --yes @manhd_d/ai-harness start
+```
+
+Terminal tương tác hỏi mục tiêu và task, input còn thiếu, nơi lưu draft docs khi cần.
+Có cấu hình input/output thì không hỏi lại. Có task đã lưu thì chọn tiếp tục hoặc nhiệm vụ mới;
+model/agent giữ mặc định của host trừ khi bạn muốn cấu hình khác. Lựa chọn được lưu trong
+`.harness/start.json` và `.harness/artifacts.json`; thay cấu hình hiện có tạo backup trước.
+
+Không có TTY (CI/pipe), `start` chỉ xuất JSON plan và không chờ stdin hoặc tự ghi lựa chọn.
+Có thể lưu lựa chọn bằng flags:
+
+```bash
+aih start --goal docs --task "Implement approved requirements" --input docs/requirements --output docs/specs
+aih start --goal change --task "Fix pagination"
+aih start --goal resume --task "Continue the reviewed task" --change add-order
+```
+
+Goal: `idea`, `docs`, `change`, `resume`. Resume cần checkpoint/evidence đã có, kiểm tra freshness và
+side effects trước tiếp tục. --input nhận đường dẫn tương đối hoặc HTTPS URL không chứa credentials;
+--output chỉ nhận folder docs tương đối. Flags input/output chỉ seed khi chưa có khai báo; muốn sửa
+nguồn cũ, review artifacts.json trực tiếp. Start không tự đọc tài liệu ngoài repo, không phê duyệt
+nghiệp vụ hay thực thi command/model. Metadata discovery không chứng minh nội dung nguồn đúng.
+
+Copy `host_prompt` từ kết quả vào AI tool đang mở cùng project. Host đọc task, cấu hình, nguồn và code;
+hỏi tối đa 1–3 quyết định còn thiếu mỗi lượt với phương án và đề xuất có lý do. Dùng workflow/agent/skill
+phù hợp đã cài; module thiếu phải được đề xuất rõ trước thay selection. Tiếp tục thực hiện khi scope và
+quyền đã đủ. Root-file probes không thay thế khảo sát monorepo hoặc đọc tài liệu trong host.
+
+Nếu bạn có nguồn/link/mô tả tự do hoặc cần output bên ngoài, đưa cho AI trong cuộc thảo luận và lưu
+quyết định vào artifacts.json/integrations.json/local.md. Terminal hỏi đáp ngắn; phần BA/thiết kế nằm
+trong AI tool. Core skill harness-start là điểm vào onboarding; menu slash native phụ thuộc host.
+
+[File cấu hình, backup, cài lại và chuyển dự án](configuration-backup.md) · [AI tool setup](tool-setup/README.md).

package/docs/tool-setup/README.md

@@ -1,7 +1,8 @@
 # Set up AI Harness in your AI tool
 
 Harness installs project instructions; it does not install an IDE, start an AI model or connect accounts.
-You need Node.js 22+, your chosen AI tool and a project folder.
+You need Node.js 22+, your chosen AI tool and a project folder. pip additionally needs Python 3.9+;
+see [pip/offline setup](../python-installation.md). npm and pip use the same onboarding.
 
 ## 1. Install Harness in your project
 
@@ -30,27 +31,25 @@ Install/sign in through its official guide, open this same project and follow th
 | **Cursor** | [Install](https://cursor.com/docs) | `AGENTS.md`; native `.agents/skills` | [Setup](cursor.md) |
 | **GitHub Copilot** | [Install](https://docs.github.com/en/copilot) | Client-specific instructions; CLI native `.agents/skills` | [Setup](copilot.md) |
 | **Gemini CLI** | [Install](https://geminicli.com/docs/) | `GEMINI.md` import; native `.agents/skills` alias | [Setup](gemini-cli.md) |
-| **Kiro** | [IDE / CLI](https://kiro.dev/docs/getting-started/installation/) | `AGENTS.md`; read canonical skills explicitly or use optional native pointers | [Setup](kiro.md) |
+| **Kiro** | [IDE / CLI](https://kiro.dev/docs/getting-started/installation/) | `init --host kiro`; first session `/harness-start`, managed wrappers + SessionStart | [Setup](kiro.md) |
 
 Existing instructions/settings remain yours. Do not replace host configs or copy the whole Harness into
 them. Host/version/account capabilities vary; these guides are not live-client compatibility results.
 
-## 3. Check loading, then give a task
+## 3. Start the first session
 
-Send this **read-only prompt** in the AI chat:
+Invoke **harness-start** if your client discovers the installed skill, or send this same prompt:
 
-> Read AGENTS.md and .harness/local.md. Do not change files or run commands.
-> State the selected adapters/capabilities from .harness/project.json, the project's known decisions,
-> and one relevant installed skill with its exact path. Report anything you cannot read.
+> Read .agents/skills/harness-start/SKILL.md and follow it for this project. My task: [task].
 
-Compare the answer with the actual files; a model's assertion alone does not prove loading.
-If skills are not discovered, ask it to read the needed `.agents/skills/<installed-name>/SKILL.md`.
-The tool guides show additional native loading checks. `check` verifies Harness files, not AI behavior.
+Kiro exposes `/harness-start`. Other clients have native discovery/import differences in the guides;
+reading the canonical skill is the common fallback. It asks only missing consequential questions and
+saves answers incrementally. `aih start --compact --host <host>` returns read-only orientation; use
+`start`/host_prompt if terminal intake is preferred. Reuse the existing npm, pip or offline CLI.
 
-Then give your normal task:
-
-> Read AGENTS.md. Inspect the project and approved decisions. Implement [task], run appropriate
-> project tests and maintain affected specs/docs. Report actual results and anything blocked.
+For a loading-only check, ask the host to report selected adapters/capabilities and one exact relevant
+installed skill path without executing anything; compare with project.json and actual files. Client
+claims are not live compatibility evidence. `check` verifies the snapshot, not model behavior.
 
 You do not need to configure models, native subagents or MCP to begin. Harness role files are contracts,
 not automatically created native agents. See [Agent configuration](../agent-configuration.md) when needed.

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

@@ -47,3 +47,13 @@ Checked 2026-10-13; no logged-in Claude client or live-agent smoke was run.
 - [Memory, AGENTS conditions and imports](https://code.claude.com/docs/en/memory)
 - [Native skills](https://code.claude.com/docs/en/skills)
 - [Models](https://code.claude.com/docs/en/model-config)
+
+## Common first-session onboarding
+
+npm and pip/offline use the same `aih init --host claude-code` bundle and canonical harness-start.
+Invoke the native skill when available (Kiro: `/harness-start`), or send:
+
+> Read .agents/skills/harness-start/SKILL.md and follow it for this project. My task: [task].
+
+Reuse saved answers; do not start a second terminal interview. Client-specific imports/discovery above
+still apply. [pip/offline prerequisites and updates](../python-installation.md).

package/docs/tool-setup/codex.md

@@ -30,3 +30,13 @@ Checked 2026-10-13; no logged-in Codex client or live-agent smoke was run.
 
 - [AGENTS discovery and verification](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
 - [Skill discovery](https://learn.chatgpt.com/docs/build-skills)
+
+## Common first-session onboarding
+
+npm and pip/offline use the same `aih init --host codex` bundle and canonical harness-start.
+Invoke the native skill when available (Kiro: `/harness-start`), or send:
+
+> Read .agents/skills/harness-start/SKILL.md and follow it for this project. My task: [task].
+
+Reuse saved answers; do not start a second terminal interview. Client-specific imports/discovery above
+still apply. [pip/offline prerequisites and updates](../python-installation.md).

package/docs/tool-setup/copilot.md

@@ -37,3 +37,13 @@ Checked 2026-10-13; no logged-in Copilot client or live-agent smoke was run.
 
 - [Instructions by IDE](https://docs.github.com/en/copilot/how-tos/copilot-in-your-ide/customize-copilot/configure-custom-instructions/add-repository-instructions-in-your-ide)
 - [CLI skill paths and loading checks](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills)
+
+## Common first-session onboarding
+
+npm and pip/offline use the same `aih init --host copilot` bundle and canonical harness-start.
+Invoke the native skill when available (Kiro: `/harness-start`), or send:
+
+> Read .agents/skills/harness-start/SKILL.md and follow it for this project. My task: [task].
+
+Reuse saved answers; do not start a second terminal interview. Client-specific imports/discovery above
+still apply. [pip/offline prerequisites and updates](../python-installation.md).

package/docs/tool-setup/cursor.md

@@ -27,3 +27,13 @@ Checked 2026-10-13; no logged-in Cursor client or live-agent smoke was run.
 
 - [Rules and AGENTS](https://cursor.com/docs/rules)
 - [Skills, discovery and cloud scope](https://cursor.com/docs/skills)
+
+## Common first-session onboarding
+
+npm and pip/offline use the same `aih init --host cursor` bundle and canonical harness-start.
+Invoke the native skill when available (Kiro: `/harness-start`), or send:
+
+> Read .agents/skills/harness-start/SKILL.md and follow it for this project. My task: [task].
+
+Reuse saved answers; do not start a second terminal interview. Client-specific imports/discovery above
+still apply. [pip/offline prerequisites and updates](../python-installation.md).

package/docs/tool-setup/gemini-cli.md

@@ -35,3 +35,13 @@ Checked 2026-10-13; no logged-in Gemini client or live-agent smoke was run.
 
 - [Context files, imports and memory checks](https://geminicli.com/docs/cli/gemini-md/)
 - [Skill aliases and loading checks](https://geminicli.com/docs/cli/skills/)
+
+## Common first-session onboarding
+
+npm and pip/offline use the same `aih init --host gemini-cli` bundle and canonical harness-start.
+Invoke the native skill when available (Kiro: `/harness-start`), or send:
+
+> Read .agents/skills/harness-start/SKILL.md and follow it for this project. My task: [task].
+
+Reuse saved answers; do not start a second terminal interview. Client-specific imports/discovery above
+still apply. [pip/offline prerequisites and updates](../python-installation.md).