@manhd_d/ai-harness 0.12.0 → 0.14.0

package/docs/agent-configuration.md

@@ -27,7 +27,7 @@ with a field-level error; it is not reset automatically. Keep credentials in hos
 ## Contract and precedence
 Schema version 1 uses provider, defaultModel, defaultReasoning, models, agents and execution, with
 optional hosts. Role IDs are namespace:role: core:planner, product:project-manager and
- delivery:project-manager remain distinct. Defaults cover all current roles; only installed selected
+ delivery:project-manager retain distinct configuration IDs but alias the canonical core:project-manager responsibility. Defaults cover all current roles; only installed selected
 roles are active. Unknown/custom role IDs can be declared but are not asserted to have a host contract.
 Future unmapped installed roles inherit project defaults and are listed by setup.
 
@@ -41,10 +41,10 @@ explicit role mappings. enabled:false disables a dedicated route, not required r
 ```json
 {
   "schema_version": 1,
-  "provider": "openai",
-  "defaultModel": "gpt-6.1-sol",
+  "provider": "host",
+  "defaultModel": "host-default",
   "defaultReasoning": "medium",
-  "models": { "economy": "gpt-6-luna", "balanced": "gpt-6.1-sol", "premium": "gpt-6-astra" },
+  "models": { "economy": "host-default", "balanced": "host-default", "premium": "host-default" },
   "agents": {
     "core:orchestrator": { "model": "@balanced", "reasoning": "high" },
     "core:implementer": { "model": "@balanced", "reasoning": "medium" },
@@ -56,7 +56,7 @@ explicit role mappings. enabled:false disables a dedicated route, not required r
 ```
 This is a partial example; omitted registered roles inherit defaults. The shipped default covers Core,
 Product, Architecture and Delivery roles. Orchestrator/Planner/Architect/Reviewer/Security Reviewer
-use Sol high; BA/PO/PM/Implementer/Test Engineer use Sol medium; Documentation uses Luna low.
+use declared high/medium reasoning preferences; new seeds retain host-selected models and documentation uses low reasoning. Explicit provider/model examples below illustrate configuration and are not defaults.
 Economy is Luna low with single-agent/one concurrent session; it is a preference, not a cost guarantee.
 
 Reasoning levels structurally accepted: none, minimal, low, medium, high, xhigh, max, ultra. Actual
@@ -97,3 +97,7 @@ controls vary by client. No role JSON automatically creates a native subagent or
 one lead plus at most one independent helper when supported. Keep inputs scoped, load skill metadata
 before one needed body and checkpoint unresolved work. Actual usage/quotas come from the host; no fake
 budget meter is inferred from model tiers, maxRounds or concurrency. See [Agent handoffs](agent-handoffs.md).
+
+## Agent-first defaults and declarations (unreleased)
+
+New seeds use host/host-default so the actual host model remains selected; old agents.json is preserved. Claude host init offers native aliases only when absent. aih agents resolves canonical role IDs and required/optional skill preferences. Optional execution.autonomy and execution.budget are validated declarations, not execution permission or quota enforcement. Checkpoint real usage or unknown; never infer cost or auto-escalate. See [Agent-first guide](agent-first.md).

package/docs/agent-first.md

@@ -0,0 +1,66 @@
+# Agent-first delivery and migration from 0.12.0
+
+Unreleased additions require a reviewed source bundle until published. Distribution stays release-PR owned.
+
+## Responsibility and scope
+Core Orchestrator selects only needed BA, PO/Product Manager, SA, PM, Developer and QA/Reviewer perspectives. Single host performs them sequentially; independent workers require actual host delegation. Inspect scope, approved requirements/ADRs and existing conventions first. Open architecture/technology choices go to SA with alternatives/trade-offs and actual owner decision. Reuse accepted choices without asking again. Adapters implement accepted designs; they do not choose infrastructure.
+
+Core-only works on unsupported stacks. Registered detection is metadata, not a supported-stack restriction or runtime readiness guarantee. All remaining adapter skills take approved SA decisions as input. The Java outbox/migration and Astro Cloudflare/microfrontend recipes are retired; old IDs return migration guidance after update. Existing old snapshots still contain their old locked skills until reviewed update. Edited managed retired files block the whole update rather than being deleted silently.
+
+## Selective capabilities and compatibility
+Analysis exposes 11 canonical Product skills for requirements/domain/AC/traceability/TechSpec. Discovery exposes 5 for idea/research/MVP/PRD/outcomes. product remains the 16-skill compatibility bundle. Select either or both without duplicate skill IDs. Canonical Product assets are vendored to retain shared references and old template paths; this controls exposed context, not npm download size. There are no new npm packages.
+
+```sh
+aih init --capabilities analysis,architecture,delivery
+aih agents
+aih skills
+aih new-doc srs --capability analysis
+```
+
+For existing consumers edit project.json capabilities on a branch and use update --dry-run/update/check. Product new-doc routes stay usable when the selected profile declares that template. Profile-specific routes default to docs/<profile>; existing artifact outputs take precedence. No existing document is moved.
+
+core:project-manager is canonical. product:project-manager and delivery:project-manager remain configured role aliases with their model overrides; canonical_id identifies the same responsibility. Delivery-plan aliases resolve to one locked template but preserve old output routes and old user docs.
+
+## Models, autonomy and budgets
+New seeds keep the host-selected model (provider host, model host-default). Existing agents.json bytes are preserved. init --host claude-code seeds Anthropic native aliases sonnet/haiku/opus only when absent; aliases do not verify account access. Explicit mappings/premium choice still require actual host support. Optional execution.autonomy declares assisted/autopilot, actions and repositories; autopilot needs explicit nonempty action/repository scope. Optional budget declares maxTokens or maxCost/currency. These settings neither grant user authorization nor enforce permissions/quota. Defaults remain assisted by absence; this repository's no-auto-merge rule applies to its own development.
+
+Example optional declaration:
+```json
+{"mode":"autopilot","actions":["read","edit","test","commit","create-pr"],"repositories":["team/project"]}
+```
+
+This is execution.autonomy, not a complete agents.json replacement. Merge/release/deploy/source-write need explicit action scope and actual user authorization plus host/repository rules. Do not manufacture quota or auto-switch to paid models.
+
+## Brownfield and Claude
+```sh
+aih init --detect --host claude-code --link-claude --claude-skills
+aih doctor
+```
+
+Default init/update preserves CLAUDE.md. --link-claude appends only a managed @AGENTS.md import, preserving BOM/line endings/user text; existing active imports are left alone. The managed block is drift-checked and subsequent updates preserve it. --claude-skills installs locked wrappers directing the host to full canonical .agents skills; custom native skills/settings survive and collisions abort before writes. Verify actual loading with Claude /context and invoke a wrapper in an authorized session. CLI tests do not prove live skill loading.
+
+Doctor examines root CLAUDE.md/CLAUDE.local.md and .claude/CLAUDE.md, excluding imports mentioned inside code/comments. It warns about possible instruction shadowing, not a proven host failure. Claude version, ancestor/global files, plugins and settings remain unverified. Official documentation: https://code.claude.com/docs/en/memory and https://code.claude.com/docs/en/skills .
+
+Maven detection follows declared module paths at most two levels, 64 POMs, 1 MiB per file and 4 MiB total. Evidence identifies each POM; missing/deeper modules produce warnings. Unsafe paths/symlinks, XML entities/CDATA and interpolation fail rather than being resolved. This is a bounded metadata reader, not general XML/profile/interpolation resolution. Other monorepos need host discovery.
+
+Team-owned .agents/.claude skills outside Harness names are preserved and excluded from the Harness catalog/check. check validates locked files, not user skill semantics. The host can load those skills normally. Unowned collisions at a Harness destination fail; no global scanning or adoption occurs.
+
+## Meaningful-step checkpoint and recovery
+Use existing OpenSpec design/tasks/decisions/evidence as authoritative work records. Save a compact machine checkpoint after meaningful steps and before external side effects; do not copy chat history or secrets. See the [checkpoint fixture](examples/checkpoint.json).
+
+```sh
+aih checkpoint change-id --report handoff.json
+aih resume change-id
+aih checkpoint change-id --report next-handoff.json --expected <prior-checkpoint-sha256>
+```
+
+Checkpoint requires an existing change and intact installation. Baseline/evidence paths are project-relative, local regular files with SHA-256 and 1 MiB limits. Completed tasks/operations need evidence; receipts are producer-declared. Replacements require the observed previous digest and preserve previous bytes in checkpoint-history. This is trusted-workspace compare-before-write, not a cross-host database transaction.
+
+Resume is read-only: flag stale baseline and unknown/prepared side effects; check actual source/remote state before retry. Do not recreate PRs/publications whose outcome is unknown. External source revisions are declarations and need host reconciliation. Omit usage or use null when unknown; measured cost needs source/currency. Evidence drift blocks recovery until reconciled. Interrupted work before a checkpoint may still need reconstruction.
+
+## Verification, evaluation and rollback
+Use existing adaptive verification/report/TechSpec contracts and source-write policy. UAT and operational feedback update the existing backlog/proposal, not accepted scope automatically. BA domain work includes glossary/data dictionary/state/decision tables when relevant. Required runtime/source publication checks stay BLOCKED/NOT_RUN when inaccessible.
+
+Local tests and real tarball smoke validate contracts, preservation, drift, alias routes and recovery; live agents remain unscored until authorized host/model/budget. For 18-run manually entered comparison use [real-task protocol](../evals/real-task-comparison.md) and scripts/compare-tasks.js; missing observations remain null.
+
+Review update --dry-run/update/check, snapshot Git diff and changed catalog. No custom configs, source documents, native settings or work records are automatically migrated. Re-export eval reports because bundle/dataset hashes change. Revert the consumer snapshot commit to roll back. Suggested next release is minor with retained old module/role/template routes and explicit retired-skill migration; consumers depending on retired recipes must review this behavioral change before upgrading.

package/docs/agent-handoffs.md

@@ -104,3 +104,7 @@ scoped context, round checkpoint and actual checks; do not claim JSON enforced t
 ## Resume and lifecycle
 
 Use [Continuous development](continuous-development.md). Store baseline/tested revisions, decisions, blockers, remaining work and next action in the existing OpenSpec tasks handoff. Re-read actual sources on resume and invalidate affected stale evidence. Keep implementation complete, merged and released distinct; supplied feedback remains proposed scope until accepted.
+
+## Agent-first routing and PM aliases
+
+[Canonical Project Manager](../core/agents/project-manager.md) owns delivery. Product/Delivery PM IDs are compatibility aliases; route by canonical_id, not separate workers. Analysis/Discovery agents use canonical Product contracts above. Preferred skills are explicit; optional perspectives need not be installed. See [Agent-first migration](agent-first.md).

package/docs/architecture.md

@@ -152,3 +152,17 @@ See [Adaptive verification and TechSpec](adaptive-verification.md) for read-only
 ## Continuous development
 
 The [continuous-development workflow](continuous-development.md) composes existing Core and optional Product/Architecture/Delivery contracts. Baseline/impact and handoff sections extend existing OpenSpec Markdown templates; no schema, runtime, state store or CLI command is added. Hosts reconcile revisions and perform authorized section edits; structural readiness cannot enforce semantic freshness.
+
+## Agent-first changes (unreleased)
+
+Optional capability profiles declare asset_owner for a canonical owner; loading validates subset membership, and installation vendors canonical assets while exposing selected skills once. Optional agent/template aliases retain old IDs/routes. Root CLAUDE managed import and native skill wrappers are opt-in locked payloads; external native settings remain project-owned. Checkpoint commands store declarations/history and compute local drift without a runtime/state server. See [Agent-first migration](agent-first.md).
+
+## Guided intake and portable configuration
+
+start uses terminal prompts or a non-TTY plan with saved user-owned start.json; canonical source/output
+declarations remain artifacts.json. backup exports an allowlisted, bounded UTF-8 config archive only.
+restore validates schema/digests/configs/paths, previews conflicts, requires explicit replacement and
+saves a before-backup through the same installation guard/rollback machinery. Transfer copies only
+project/agent preferences and removes repository autonomy. No credentials, machine paths, locked
+payload, custom skills or checkpoint/document contents are exported. Full repo recovery remains Git
+and external-source backup. See [Configuration backup](configuration-backup.md).

package/docs/cli.md

@@ -159,3 +159,24 @@ local fallback. Configured output contracts require reviewed artifact-impact.jso
 review stage requires declared completion/evidence. No remote calls, source writes or approval claims.
 
 See [Adaptive verification and TechSpec](adaptive-verification.md) for read-only discovery, evidence reports and selective technical documentation.
+
+## Agent-first additions (unreleased)
+
+aih agents shows canonical IDs, skill preferences and model declarations. init --host claude-code seeds a native preset only when agents.json is absent. init/update --link-claude and --claude-skills opt in to managed import/wrappers; native settings remain user-owned. checkpoint <id> --report saves project-owned recovery state; --expected supplies prior digest for replacement. resume <id> is read-only. See [Agent-first guide](agent-first.md). No command launches agents, probes providers, merges or measures quota.
+
+## Start, backup và restore (bản nâng cấp này)
+
+| Lệnh | Hành vi |
+| --- | --- |
+| `aih start` | Terminal: intake ngắn; không TTY: read-only plan; trả host_prompt |
+| `aih start --goal docs --task "Implement requirements" --input docs/requirements --output docs/specs` | Lưu task và seed nguồn/output còn thiếu |
+| `aih backup [--output backups/config.json]` | Export 8 file cấu hình dùng chung; không ghi đè archive |
+| `aih restore --from config.json --dry-run` | Kiểm tra schema/digest và xem file/conflict trước ghi |
+| `aih restore --from config.json [--replace]` | Phục hồi cùng dự án, tự backup trước thay file khác nội dung |
+| `aih restore --from config.json --transfer` | Chuyển module/model; bỏ repo autonomy và nguồn/task/domain/command cũ |
+
+Tất cả nhận --target. Đường dẫn --from/--output tính từ project root. --host dùng với start;
+--change chỉ cho start --goal resume. Các flags sai command bị từ chối. Lệnh --dry-run thuộc restore
+không đổi target hoặc chờ stdin. Fresh repo restore trước init; installed repo update/check sau khi
+selection đổi. Đọc [Start](start.md) và [Configuration backup](configuration-backup.md) cho giới hạn,
+phục hồi checkpoint và rollback. Các lệnh không truy cập remote, chạy model, cấp quyền hay auto-merge.

package/docs/configuration-backup.md

@@ -0,0 +1,122 @@
+# Lưu cấu hình, backup và chuyển dự án
+
+Các lệnh dưới đây dùng `aih` khi đã cài global. Nếu dùng npx, thay `aih` bằng
+`npx --yes @manhd_d/ai-harness`. Những lệnh start/backup/restore thuộc bản nâng cấp này;
+chỉ dùng với bản đã phát hành có các lệnh đó, hoặc checkout/package đã review.
+
+## Thông tin của bạn nằm ở đâu?
+
+Ở **repo dự án áp dụng Harness**, phần cấu hình dùng chung nằm trong `.harness/`:
+
+| File | Thông tin người dùng | Khi update |
+| --- | --- | --- |
+| `.harness/project.json` | Adapter/capability đã chọn | Giữ nguyên |
+| `.harness/agents.json` | Agent → provider/model/reasoning, execution preferences | Giữ nguyên |
+| `.harness/start.json` | Mục tiêu, task, ID change cần tiếp tục | Giữ nguyên |
+| `.harness/artifacts.json` | Đường dẫn/link input, nơi ghi output, owner, revision, write policy | Giữ nguyên |
+| `.harness/integrations.json` | Tên kết nối của host và phạm vi khai báo | Giữ nguyên |
+| `.harness/environment.json` | Tool/lệnh test và tham chiếu biến môi trường | Giữ nguyên |
+| `.harness/local.md` | Nghiệp vụ, convention và quyết định đã chốt | Giữ nguyên |
+| `openspec/config.yaml` | Cấu hình OpenSpec của dự án | Giữ nguyên |
+| `.harness/machine.json` | Đường dẫn chỉ dùng trên máy này | Giữ nguyên, Git ignore; không vào backup cấu hình |
+| `openspec/changes/<id>/` | Spec, tiến độ, checkpoint/history và evidence | Giữ nguyên; backup cùng repo |
+
+**Input/output thực tế nằm ở nơi `artifacts.json` chỉ định**, ví dụ `docs/requirements/`,
+`docs/specs/`, Confluence hoặc Figma. Cấu hình lưu liên kết; không sao chép nội dung nguồn bên ngoài.
+Các skill riêng và native config của AI tool cũng cần giữ cùng cơ chế backup phù hợp của bạn.
+
+`.harness/core/`, `adapters/`, `capabilities/`, `templates/`, `integrations/` và `lock.json`
+là snapshot do Harness quản lý. Không sửa các file này để tùy biến. Giữ toàn bộ repo trong Git
+để rollback snapshot chính xác; bản backup cấu hình chỉ chứa các file được liệt kê bên dưới.
+Không lưu API key/token/password trong cấu hình; host/secret manager quản lý chúng riêng.
+
+## Backup trước update hoặc cài lại
+
+```bash
+aih backup
+```
+
+CLI trả đường dẫn `.harness/backups/config-<timestamp>-<id>.json`. **Copy file này ra nơi riêng
+ngoài repo/máy**, ví dụ ổ backup hoặc kho riêng của bạn; file ở máy hiện tại chưa bảo vệ khỏi mất máy.
+Muốn tên dễ nhớ:
+
+```bash
+aih backup --output backups/harness-config.json
+```
+
+Đường dẫn CLI tính từ project root; không dùng đường dẫn tuyệt đối. CLI từ chối ghi đè backup đã có.
+Archive JSON giữ nguyên bytes UTF-8 của 8 file dùng chung ở bảng (nếu hiện có), kèm schema version,
+CLI version và SHA-256 từng file. Digest phát hiện sửa nhầm, không xác thực nguồn backup.
+Review file trước khi chia sẻ; bản backup là plain text và không tự dò/xóa mọi secret bạn có thể đã ghi nhầm.
+Folder mặc định `.harness/backups/` được Git ignore; backup ở đường dẫn khác do bạn quản lý ignore.
+
+**Không có trong archive:** machine.json, biến môi trường/credentials, host login/native settings,
+snapshot/lock, custom skills, code, nội dung docs/UI bên ngoài, OpenSpec changes/checkpoints/history/evidence.
+Muốn phục hồi toàn bộ công việc, backup **repo + các nguồn/tài khoản ngoài repo** bằng cơ chế của bạn.
+
+Update thông thường bảo toàn file dùng chung; không cần restore mỗi lần:
+
+```bash
+aih backup
+aih update --dry-run
+aih update
+aih check
+```
+
+Trước đó hãy nâng CLI global lên phiên bản đã review nếu cần. CLI không tải bản mới khi chạy update.
+
+## Phục hồi cùng dự án
+
+Copy archive vào project root thành `harness-config.json`, rồi xem trước:
+
+```bash
+aih restore --from harness-config.json --dry-run
+aih restore --from harness-config.json
+```
+
+File giống hệt được giữ nguyên, file thiếu được tạo. File khác nội dung **không bị ghi đè** nếu chưa
+chọn `--replace`. Nếu muốn khôi phục bản cũ thay cho cấu hình hiện tại:
+
+```bash
+aih restore --from harness-config.json --dry-run --replace
+aih restore --from harness-config.json --replace
+```
+
+Trước thay file, CLI tự tạo archive cấu hình hiện tại trong `.harness/backups/`; kết quả trả đường dẫn.
+Không xóa file người dùng không có trong archive. Validation/schema/digest/path/conflict được kiểm tra
+trước ghi; lỗi ghi thông thường rollback. Gián đoạn tiến trình/mất điện không phải transaction nhiều
+file an toàn tuyệt đối: kiểm tra trạng thái và phục hồi từ backup/Git trước khi tiếp tục.
+
+Với repo chưa có snapshot, **restore trước `init`** để bộ cài dùng đúng module và model đã lưu:
+
+```bash
+aih restore --from harness-config.json
+aih init
+aih check
+aih doctor
+aih start
+```
+
+Với repo đã cài, dùng `update --dry-run`, `update`, `check` sau restore nếu selection đổi.
+Restore không sửa snapshot hỏng; phục hồi snapshot qua Git hoặc cài bundle đã review vào repo sạch.
+Nếu goal đã lưu là resume, phục hồi OpenSpec changes/evidence trước khi chạy start/resume.
+Schema archive/config chưa được hỗ trợ bị từ chối; không tự đổi schema hay hạ phiên bản. OpenSpec
+config được giữ dạng text; correctness thuộc upstream OpenSpec validator.
+
+## Mang sang dự án khác
+
+Copy archive vào repo mới, dùng chế độ transfer:
+
+```bash
+aih restore --from harness-config.json --transfer --dry-run
+aih restore --from harness-config.json --transfer
+aih init
+aih start
+```
+
+Transfer mang **project.json + agents.json**: adapter/capability và model/reasoning/execution preferences.
+Khai báo autonomy gắn repo cũ bị loại bỏ. Task, domain facts, nguồn input/output, connection aliases,
+commands, OpenSpec config và state không được chuyển. `start` giúp khai báo lại theo dự án mới.
+Nếu repo mới đã có cấu hình khác, review conflict và chỉ dùng --replace khi muốn thay chúng.
+Model đã khai báo vẫn cần host hỗ trợ; restore không đăng nhập, cấp quyền hoặc gọi API/provider.
+Muốn dùng lại nguồn tài liệu cũ, khai báo rõ nguồn/revision/quyền truy cập tại dự án mới sau review.

package/docs/continuous-development.md

@@ -86,3 +86,7 @@ records. `aih eval --scope all` exports scenarios; it does not run a model. Prod
 its optional document templates/TechSpec skill. Existing docs/configs/changes are preserved on update;
 add missing baseline/handoff sections selectively, do not regenerate old changes. Revert the consumer
 installation commit to roll back; re-export evaluations after bundle hashes change.
+
+## Agent-first checkpoint additions (unreleased)
+
+Use aih agents for canonical responsibilities and preferred skills; load only needed perspectives. For a machine-readable meaningful-step handoff use aih checkpoint <id> --report file.json and aih resume <id>. Keep design/tasks/decisions and evidence authoritative; checkpoint references them instead of copying chat. Reconcile baseline drift and unknown side effects before retry; quota/usage remains unknown without actual host data. See [Agent-first guide](agent-first.md).

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

@@ -114,7 +114,7 @@ aih eval --scope all    # dataset/review template, không gọi model
 aih check
 ```
 
-Dùng Core review/TDD và `harness-astro-performance` để ghi bằng chứng build/browser thực chạy, cùng `harness-astro-microfrontend` khi đánh giá split. Hoàn tất spec → code → tests → human PR review. Harness không deploy/merge tự động.
+Dùng Core review/TDD và `harness-astro-performance` để ghi bằng chứng build/browser thực chạy, và SA/approved ADR khi có yêu cầu deployment độc lập. Hoàn tất spec → code → tests → human PR review. Harness không deploy/merge tự động.
 
 ## Tài liệu chính thức
 

package/docs/examples/checkpoint.json

@@ -0,0 +1,20 @@
+{
+  "schema_version": 1,
+  "change_id": "change-id",
+  "phase": "implementation",
+  "summary": "Draft handoff; replace with actual evidence",
+  "timestamp": "2026-10-13T10:00:00Z",
+  "baseline": [],
+  "completed": [],
+  "pending": [
+    {
+      "id": "task-1",
+      "summary": "Continue scoped work"
+    }
+  ],
+  "in_progress": null,
+  "blockers": [],
+  "next_action": "Inspect actual baseline and populate references",
+  "external_sources": [],
+  "operations": []
+}

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

@@ -56,13 +56,11 @@ Lệnh `new-change` **chỉ tạo draft**, không validate/approve spec. Gate: r
 ~~~bash
 aih skill harness-java-spring-spring-api
 aih skill harness-tdd
-aih skill harness-java-spring-database-migration
-aih skill harness-java-spring-kafka-outbox
+aih skill harness-review
 ~~~
 
 - `spring-api`: controller/service/repository theo pattern hiện có, tenant-scope server-side, DTO và HTTP contract.
-- `database-migration`: chỉ dùng **khi đổi schema**; thiết kế expand → compatible deploy → contract, rollback/data-loss risk.
-- `kafka-outbox`: chỉ dùng **khi có event publication**; transactional write, duplicate consumer delivery, retry/dead-letter.
+- Schema, messaging và deployment choices theo approved SA/ADR và tooling thực tế. Khi chưa có quyết định quan trọng, SA đưa alternatives/trade-offs và hỏi owner trước implementation; không dùng recipe từ adapter.
 - `harness-tdd`: negative auth test, missing resource, validation, successful request, regression. Không tạo implementation Kafka/DB nếu requirement không cần.
 
 Lệnh verify ứng dụng **tùy repo** — dưới đây chỉ là ví dụ nếu có Maven wrapper:

package/docs/getting-started.md

@@ -1,6 +1,6 @@
 # Bắt đầu với AI Harness
 
-**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.
+**Cài vào project → start → mở AI làm 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
 
@@ -31,9 +31,10 @@ npx --yes @manhd_d/ai-harness init --adapters java-spring --capabilities product
 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`.
 
-## 2. Mở AI và giao việc
+## 2. Start và mở AI làm việc
 
-Mở thư mục project trong công cụ AI, rồi gửi:
+Chạy `npx --yes @manhd_d/ai-harness start`: trả lời mục tiêu/input/output còn thiếu, rồi gửi
+`host_prompt` từ kết quả vào AI tool đang mở project. [Luồng start](start.md). Nếu đã biết task, có thể gửi thẳng:
 
 > Đọ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õ.
@@ -41,7 +42,8 @@ Mở thư mục project trong công cụ AI, rồi gửi:
 
 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).
+Xem [setup theo AI tool](tool-setup/README.md) cho Codex, Claude Code, Cursor, Copilot, Gemini CLI và Kiro:
+phân biệt cài tool, cài Harness và kiểm tra instructions đã được đọc.
 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.
 
 Review diff và test, rồi commit `AGENTS.md`, `.harness/`, `.agents/skills/` cùng code.
@@ -64,7 +66,8 @@ Task nhỏ không cần bộ tài liệu đầy đủ. Không cần cài OpenSpe
 
 `check` kiểm tra file Harness; `verify` xuất checklist. Code cần **test của project** và review thực tế.
 
-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:
+Trước cập nhật, tạo branch và commit trạng thái hiện tại. Chạy `npx --yes @manhd_d/ai-harness backup`
+và copy JSON được trả về ra nơi riêng ngoài repo. [Lưu ở đâu, cài lại và chuyển dự án](configuration-backup.md). Xem trước, áp dụng rồi kiểm tra:
 
 ```bash
 npx --yes @manhd_d/ai-harness@latest update --dry-run
@@ -80,6 +83,6 @@ Dùng thường xuyên có thể cài global: `npm install -g @manhd_d/ai-harnes
 ## 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).
+`npx --yes @manhd_d/ai-harness artifacts` shows declarations. See [Artifact contract](artifact-contract.md).
 
 For successive features, bugfixes or a resumed session, give the host a normal request. It follows [Continuous development](continuous-development.md), rechecks the baseline and maintains only affected docs.

package/docs/i18n/README.es.md

@@ -0,0 +1,35 @@
+# AI Harness
+
+[English](../../README.md) · [Tiếng Việt](README.vi.md) · [简体中文](README.zh-CN.md) · **Español**
+
+Agent workflows reutilizables para desarrollar software: **Requirements → Design → Code → Test → Review.**
+
+Entrega una idea, docs existentes o un change request a tu AI coding tool. Harness ayuda a inspeccionar el proyecto, aclarar decisiones, implementar el scope aceptado y mantener los spec/docs afectados. Carga solo los roles y skills necesarios.
+
+Los Core workflows sirven para cualquier proyecto. El stack support es opcional y no elige infrastructure ni architecture.
+
+Requiere Node.js 22+. Ejecuta en el directorio del proyecto:
+
+```bash
+npx --yes @manhd_d/ai-harness init
+npx --yes @manhd_d/ai-harness start
+```
+
+Ejecuta `start` para comenzar con tus entradas y envía `host_prompt` a tu herramienta de IA. [Configuración, copia de seguridad y transferencia](../configuration-backup.md).
+
+`npx` no instala el command global `aih`. Comprueba con `npx --yes @manhd_d/ai-harness check` y abre el mismo proyecto en tu AI tool. [Setup común](../tool-setup/README.md).
+
+> Read AGENTS.md. Inspect this project and its approved decisions. Implement [task], run appropriate checks and maintain affected docs.
+
+El host ejecuta tests y controla tools, delegation y permissions. MCP/connector/API pueden aportar input con acceso autorizado. init --detect identifica stacks compatibles; check comprueba la integrity de Harness.
+
+| AI tool | Setup |
+| --- | --- |
+| **Codex** | [Guía](../tool-setup/codex.md) |
+| **Claude Code** | [Guía](../tool-setup/claude-code.md) |
+| **Cursor** | [Guía](../tool-setup/cursor.md) |
+| **GitHub Copilot** | [Guía](../tool-setup/copilot.md) |
+| **Gemini CLI** | [Guía](../tool-setup/gemini-cli.md) |
+| **Kiro** | [Guía](../tool-setup/kiro.md) |
+
+[Docs y ejemplos](../README.md) · [Getting started](../getting-started.md) · [Input/output](../artifact-contract.md) · [Agent configuration](../agent-configuration.md) · [Continuous development](../continuous-development.md) · [MIT](../../LICENSE)

package/docs/i18n/README.vi.md

@@ -1,57 +1,35 @@
 # AI Harness
 
-[English](../../README.md) · **Tiếng Việt**
+[English](../../README.md) · **Tiếng Việt** · [简体中文](README.zh-CN.md) · [Español](README.es.md)
 
-**Bộ hướng dẫn cho AI phát triển project theo workflow: Requirements → Code → Test → Review.**
+Agent workflows tái sử dụng cho phát triển phần mềm: **Requirements → Design → Code → Test → Review.**
 
-Cài bộ hướng dẫn vào project, rồi giao việc cho công cụ AI bạn đang dùng.
+Đưa ý tưởng, docs có sẵn hoặc change request cho AI coding tool. Harness giúp AI đọc project, làm rõ quyết định, triển khai scope đã chấp nhận và maintain spec/docs liên quan. Chỉ dùng roles và skills cần cho task.
 
-## Hỗ trợ workflow nào?
+Core workflows dùng được với mọi project. Stack support là tùy chọn; không tự chọn infrastructure hay architecture.
 
-| Workflow | Outputs |
-| --- | --- |
-| **BA / PO — Business analysis & product** | Từ ý tưởng hoặc docs có sẵn đến BRD, PRD, SRS, user stories và acceptance criteria. |
-| **SA — Solution architecture** | Architecture, non-functional requirements, technical decisions và change-impact analysis. |
-| **PM — Delivery planning** | Delivery phases, dependencies, risks và scope changes. |
-| **Dev / QA — Implementation & testing** | Feature implementation, debugging, tests và code review theo project conventions. |
-| **UI/UX & DevOps** | UI design, CI/CD, deployment và operations guidance khi cần. |
-
-Hỗ trợ Spring Boot, React/Next.js, React Native/Expo, Python AI/RAG, Astro và Kubernetes.
-Chỉ chọn phần cần dùng; task nhỏ không cần đủ bộ docs hay spec. [Chọn stack & module](../../docs/getting-started.md).
-
-## Chạy ở đâu?
-
-| Công cụ AI | Cách sử dụng | Hướng dẫn |
-| --- | --- | --- |
-| **Codex** | CLI hoặc extension trong IDE | [Cài đặt & thiết lập](../../docs/tool-setup/codex.md) |
-| **Claude Code** | Chạy `claude` trong terminal của project | [Cài đặt & thiết lập](../../docs/tool-setup/claude-code.md) |
-| **Cursor** | Mở project, giao việc trong Agent | [Cài đặt & thiết lập](../../docs/tool-setup/cursor.md) |
-| **GitHub Copilot** | Agent trong IDE hoặc Copilot CLI | [Cài đặt & thiết lập](../../docs/tool-setup/copilot.md) |
-| **Gemini CLI** | Chạy `gemini` trong terminal của project | [Cài đặt & thiết lập](../../docs/tool-setup/gemini-cli.md) |
-
-Harness cài hướng dẫn; công cụ AI thực hiện công việc. Cách nạp hướng dẫn tùy công cụ, theo link trên.
-
-## Quick start
-
-Cần **Node.js 22+** và một công cụ AI ở bảng trên. Chạy trong thư mục project:
+Cần Node.js 22+. Chạy trong project:
 
 ```bash
-npx --yes @manhd_d/ai-harness init --detect
+npx --yes @manhd_d/ai-harness init
+npx --yes @manhd_d/ai-harness start
 ```
 
-Mở công cụ AI tại cùng project, rồi gửi:
-
-> Đọc AGENTS.md, khảo sát project và ghi context cần thiết vào .harness/local.md.
-> Thực hiện yêu cầu: [mô tả công việc]. Chạy test phù hợp và báo cáo kết quả.
+Chạy `start` để được hướng dẫn theo input hiện có, rồi gửi `host_prompt` cho AI. [Cấu hình, backup và chuyển dự án](../configuration-backup.md).
 
-Bạn giao việc bình thường, không cần gọi từng agent, skill hay mở chat riêng cho từng vai.
-Nếu `--detect` chưa nhận diện được stack, [chọn module thủ công](../../docs/getting-started.md).
-`aih check` chỉ kiểm tra file Harness; tính năng đúng hay chưa cần test của project và review.
+`npx` không cài global command `aih`. Kiểm tra bằng `npx --yes @manhd_d/ai-harness check`, rồi mở cùng project trong AI tool. [Setup chung](../tool-setup/README.md).
 
-[Getting started](../../docs/getting-started.md) · [Docs & examples](../../docs/README.md) · [Input/output & integrations](../../docs/artifact-contract.md) · [Model/agent configuration](../../docs/agent-configuration.md)
+> Read AGENTS.md. Inspect this project and its approved decisions. Implement [task], run appropriate checks and maintain affected docs.
 
-Đóng góp: [Contributing](../../CONTRIBUTING.md) · [Bảo trì Harness](../../docs/harness-maintenance.md) · [MIT](../../LICENSE).
+Host chạy tests và quản lý tools, delegation, permissions. MCP/connector/API có thể cung cấp input khi host có quyền truy cập. init --detect nhận diện stack hỗ trợ; check kiểm tra integrity của Harness.
 
-[Adaptive verification & TechSpec](../adaptive-verification.md): verification plan theo project, evidence và cập nhật docs theo scope.
-
-[Continuous development](../continuous-development.md): phát triển qua nhiều changes, kiểm tra lại baseline và duy trì đúng phần tài liệu bị ảnh hưởng.
+| AI tool | Setup |
+| --- | --- |
+| **Codex** | [Hướng dẫn](../tool-setup/codex.md) |
+| **Claude Code** | [Hướng dẫn](../tool-setup/claude-code.md) |
+| **Cursor** | [Hướng dẫn](../tool-setup/cursor.md) |
+| **GitHub Copilot** | [Hướng dẫn](../tool-setup/copilot.md) |
+| **Gemini CLI** | [Hướng dẫn](../tool-setup/gemini-cli.md) |
+| **Kiro** | [Hướng dẫn](../tool-setup/kiro.md) |
+
+[Docs & examples](../README.md) · [Getting started](../getting-started.md) · [Input/output](../artifact-contract.md) · [Agent configuration](../agent-configuration.md) · [Continuous development](../continuous-development.md) · [MIT](../../LICENSE)

package/docs/i18n/README.zh-CN.md

@@ -0,0 +1,35 @@
+# AI Harness
+
+[English](../../README.md) · [Tiếng Việt](README.vi.md) · **简体中文** · [Español](README.es.md)
+
+可复用的软件开发 Agent workflows: **Requirements → Design → Code → Test → Review.**
+
+把想法、已有 docs 或 change request 交给 AI coding tool。Harness 帮助 AI 检查项目、澄清待定决策、实现已确认的 scope，并维护相关 spec/docs。只加载任务需要的 roles 和 skills。
+
+Core workflows 可用于任何项目。Stack support 是可选的，不会自动选择 infrastructure 或 architecture。
+
+需要 Node.js 22+。在项目目录运行：
+
+```bash
+npx --yes @manhd_d/ai-harness init
+npx --yes @manhd_d/ai-harness start
+```
+
+运行 `start` 获取引导，然后将 `host_prompt` 发送给 AI 工具。[配置备份与项目迁移](../configuration-backup.md)。
+
+`npx` 不会安装全局 `aih` command。使用 `npx --yes @manhd_d/ai-harness check` 检查，然后在 AI tool 中打开同一项目。[通用 Setup](../tool-setup/README.md)。
+
+> Read AGENTS.md. Inspect this project and its approved decisions. Implement [task], run appropriate checks and maintain affected docs.
+
+Host 执行 tests，并控制 tools、delegation 和 permissions。MCP/connector/API 可在 host 获得访问权限后提供 input。init --detect 用于支持的 stack；check 检查 Harness integrity。
+
+| AI tool | Setup |
+| --- | --- |
+| **Codex** | [使用指南](../tool-setup/codex.md) |
+| **Claude Code** | [使用指南](../tool-setup/claude-code.md) |
+| **Cursor** | [使用指南](../tool-setup/cursor.md) |
+| **GitHub Copilot** | [使用指南](../tool-setup/copilot.md) |
+| **Gemini CLI** | [使用指南](../tool-setup/gemini-cli.md) |
+| **Kiro** | [使用指南](../tool-setup/kiro.md) |
+
+[Docs 与示例](../README.md) · [Getting started](../getting-started.md) · [Input/output](../artifact-contract.md) · [Agent configuration](../agent-configuration.md) · [Continuous development](../continuous-development.md) · [MIT](../../LICENSE)

package/docs/project-configuration.md

@@ -2,6 +2,7 @@
 
 | File | Nội dung | Git |
 | --- | --- | --- |
+| `.harness/start.json` | Mục tiêu/task và ID checkpoint nếu tiếp tục | Commit |
 | `.harness/project.json` | Adapter/capability | Commit |
 | `.harness/agents.json` | Provider/model/reasoning theo role, execution preferences và host mappings | Commit |
 | `.harness/artifacts.json` | Input/output/storage, canonical ownership và source-write policy | Commit |
@@ -10,7 +11,7 @@
 | `.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 |
 
-Init/update tạo environment rỗng nếu chưa có và thêm `/machine.json` vào cuối
+Init/update tạo environment rỗng nếu chưa có và thêm `/backups/` và `/machine.json` vào cuối
 `.harness/.gitignore`. File đã được Git track vẫn được track: ignore không xóa khỏi index/history.
 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ụ.
@@ -91,3 +92,10 @@ local.md đã trả lời. Setup không phải wizard nhập liệu và không t
 Xem [Artifact contract](artifact-contract.md). `aih artifacts` báo khai báo; `aih setup` gợi ý hỏi
 nơi lưu docs/UI nếu chưa biết. Các file này project-owned và được bảo toàn khi update; chúng không
 kết nối MCP, cấp quyền hay chạy tool. Credentials và native host config nằm ngoài Git.
+
+## Backup và dùng lại
+
+Chạy `aih start` để lưu intake. File được bảo toàn khi update. Chạy `aih backup`, copy archive ngoài
+repo; `aih restore --from <file> --dry-run` xem trước phục hồi. Dùng --transfer ở repo mới để chỉ
+chuyển module/model, tránh nguồn/tiến độ cũ. [Hướng dẫn đầy đủ](configuration-backup.md) mô tả các
+file được lưu, những gì không có trong backup, conflict/backup-before-replace và cách cài lại.