@manhd_d/ai-harness 0.12.0 → 0.13.0

package/core/workflows/agent-routing.md

@@ -1,28 +1,29 @@
-# Agent preferences, model routing and execution
+# Agent-first task routing
 
-Read project-owned .harness/agents.json when present. On legacy installs, absence means no declared
-routing preference; use actual host settings and report the gap. `aih setup --host <id>` resolves the
-contract without probing models or writing native host config. Source defaults are a recommendation,
-not evidence of model/account availability. Runtime permissions and the user's current model choice win.
+Read project-owned agents.json and actual host capabilities. aih agents resolves installed contracts,
+canonical aliases and preferred skills without spawning workers or probing providers.
 
-1. Select only relevant workflow/skills/source. Resolve namespaced role IDs against installed Core and
-   selected capability contracts; inactive or disabled routing cannot remove required quality/security checks.
-2. Model aliases use @name, provider/model/reasoning can be overridden per role. Missing role mappings
-   inherit project defaults and must be reported; never silently substitute another provider or premium.
-3. Verify requested/native model ID, reasoning support, authentication and delegation in the actual host.
-   Host-incompatible or unverified choices need a grounded user decision/check before model-dependent
-   execution. Explicit user mappings are declarations, not proof that a native model is available.
-4. Single-agent: one session performs sequential roles and relevant skills. Hybrid: one lead and an
-   independent helper only when useful, authorized and supported. Multi-agent: use separate contracts
-   and concise handoffs only when runtime supports it. Follow the host's actual delegation rules.
-5. Keep simple edits/clear bugfixes in one session. For parallel work isolate responsibilities/paths,
-   share only scope, source references, decisions, AC and blockers; do not send every skill/doc to each worker.
-6. Treat maxConcurrentAgents and maxRounds as requested caps, never counters enforced by this CLI.
-   Count the lead in concurrency planning; translate native worker/thread limits only after checking
-   their semantics. When a round limit is reached, checkpoint unresolved work instead of claiming done.
-7. Premium/Astra is allowed only through the user's explicit model/tier selection; automatic escalation
-   must remain false. An economy preference does not waive correctness/security or mandatory review.
-8. No real token budget or usage meter is supplied. Read real host usage when available; report unknown
-   cost/availability. Preserve existing model settings until the user agrees a native change.
-9. Handoff task/role ID, actual model/effort if known, files/revision, decisions, performed checks, remaining
-   questions and next owner. A same-session author review is not independent review.
+1. Orchestrator scopes the request, existing decisions, sources and affected repositories. Keep small
+   clear edits in one session; roles are perspectives unless actual delegation is supported/authorized.
+2. BA handles requirements/domain/AC gaps. PO/Product Manager handles value, scope and feedback.
+   SA handles open architecture/technology choices. PM handles dependencies, risks and handoff.
+   Developer implements accepted contracts; QA/Reviewer checks actual behavior and evidence.
+3. Approved SA/ADR decisions > scoped project conventions > adapter defaults, subject to actual
+   user/host permission and security. Do not select a broker, cache, provider, layout or pattern because
+   an adapter exists. SA proposes 2–3 viable options/trade-offs only for real open decisions, and
+   records the user's choice before consequential implementation. Do not ask again about approved facts.
+4. Load only relevant preferred skills by description; optional skills may be absent. Product is the
+   compatibility bundle; analysis/discovery expose selected canonical skills. PM role IDs are aliases
+   of core:project-manager. Contracts with the same canonical_id are one responsibility, not workers.
+5. Host-native model is the default. init --host claude-code seeds native Anthropic aliases only when
+   agents.json is absent; existing model choices are preserved. Requested effort/model/access remains
+   unverified until checked in the host. Never escalate to paid/premium automatically.
+6. execution mode/concurrency/rounds, optional autonomy and budget are declarations, not enforcement.
+   An autopilot declaration needs explicit actions/repository scope and actual user delegation; it
+   cannot override host denials, branch protection, source-write policy or this repository's rules.
+7. When budget/rounds/access prevents progress, checkpoint completed evidence, pending tasks, blockers
+   and next action. Record usage/quota only from an actual host source; unknown remains unknown.
+8. Handoff scope, baseline revisions, AC/ADR/decisions, authorized actions, actual evidence, side-effect
+   receipts and next owner. Reconcile checkpoint and current source/remote state before retries.
+
+Use continuous-development.md for full changes/resume. No CLI orchestration runtime or paid model calls.

package/core/workflows/continuous-development.md

@@ -96,3 +96,6 @@ mandatory checks or required publication prevent an unconditional completion cla
 completed scope and limitations, not simply “done”. Update the existing tasks.md handoff with current
 baseline, decisions, evidence revision, blockers, remaining work, next action/owner and distinct
 implementation/merge/release status. On the next session, start again at baseline discovery.
+
+## Meaningful-step recovery
+Use agent-routing.md for scoped perspectives. Keep the existing design/tasks/decisions/evidence current, then save a compact project-owned checkpoint after meaningful steps and before external side effects. aih checkpoint/resume supplies validation and local freshness hints, not execution. Record task/evidence IDs, baseline digests, completed/pending work, blockers, operation identity/status and next action; never copy chat or secrets. If interrupted, reconcile actual sources and unknown/prepared remote operations before retrying. Read real host usage/quota only when available; otherwise record unknown and retain user model settings. Use explicit actions/repository scope for an authorized autopilot; host/repo permission rules still apply.

package/core/workflows/spec-to-code.md

@@ -31,7 +31,7 @@ in the task note or existing change. Preserve each module's conventions in mixed
 the diff against those facts and run configured lint/type/build/tests and available boundary checks;
 report manual review where automated architecture coverage is absent.
 
-Use the harness-spec skill to draft and harness-tdd to implement. Use harness-debugging when diagnosing
+Use harness-spec to draft, harness-tdd to implement and harness-review for the review stage. Use harness-debugging when diagnosing
 an observed defect. Agents are roles, not automatically spawned workers; a single assistant can perform
 them sequentially. Respect the host's delegation rules.
 Small documentation edits or obvious low-risk fixes may skip a full spec with a rationale in the PR.

package/docs/README.md

@@ -8,7 +8,7 @@ Chỉ đọc phần phù hợp với công việc đang làm.
 | Cần làm gì? | Đọc ở đâu? |
 | --- | --- |
 | Tra lệnh, chọn module, xử lý conflict | [CLI](cli.md) · [Adapters](adapters.md) |
-| Kết nối công cụ AI | [Codex, Claude Code, Cursor, Copilot, Gemini CLI](tool-setup/README.md) |
+| Kết nối công cụ AI | [Codex, Claude Code, Cursor, Copilot, Gemini CLI, Kiro](tool-setup/README.md) |
 | Chọn model và cách chạy agent | [Agent configuration](agent-configuration.md) |
 | Khai báo build/test, Maven/JDK riêng | [Project configuration](project-configuration.md) |
 | Áp dụng coding conventions | [Project conventions](project-conventions.md) |
@@ -43,3 +43,5 @@ Chỉ đọc phần phù hợp với công việc đang làm.
 See [Adaptive verification and TechSpec](adaptive-verification.md) for read-only discovery, evidence reports and selective technical documentation.
 
 [Continuous development & living documentation](continuous-development.md): successive features, bugfixes, baseline reconciliation and selective maintenance.
+
+- [Agent-first delivery and 0.12 migration](agent-first.md): proportional roles, selective Product profiles, retired recipes, brownfield/Claude/Maven and checkpoint recovery.

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,7 @@ 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).

package/docs/cli.md

@@ -159,3 +159,7 @@ 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.

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

@@ -41,7 +41,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.
@@ -80,6 +81,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,32 @@
+# 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` 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,32 @@
 # 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
 ```
 
-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ả.
-
-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,32 @@
+# 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` 不会安装全局 `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/skill-matrix.md

@@ -1,6 +1,6 @@
-# Skill matrix — 70 skills, 13 nhóm module
+# Skill matrix — 66 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, 22 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ộ 70 skill vào prompt.
+Đâ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.
 
 **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.
 
@@ -84,8 +84,6 @@
 
 | Skill ID (nguồn) | Khi nào dùng | Mục đích | Output mong đợi |
 | --- | --- | --- | --- |
-| [`harness-java-spring-database-migration`](../adapters/java-spring/skills/harness-java-spring-database-migration/SKILL.md) | DB change | Expand/migrate/contract theo release tương thích | Versioned migration và recovery evidence |
-| [`harness-java-spring-kafka-outbox`](../adapters/java-spring/skills/harness-java-spring-kafka-outbox/SKILL.md) | Async events | Outbox transaction và consumer dedupe | Event implementation + failure tests |
 | [`harness-java-spring-spring-api`](../adapters/java-spring/skills/harness-java-spring-spring-api/SKILL.md) | Backend API | Authorization resource scoped, API contract | Endpoint + auth/contract tests |
 
 ## React / Next.js adapter (4)
@@ -114,7 +112,7 @@
 | [`harness-ai-python-tool-safety`](../adapters/ai-python/skills/harness-ai-python-tool-safety/SKILL.md) | Agent tools | Bounded tools, explicit auth, no escalation | Policy wrapper + security tests |
 
 
-## Astro adapter (6)
+## Astro adapter (4)
 
 | Skill ID (nguồn) | Khi nào dùng | Mục đích | Output mong đợi |
 | --- | --- | --- | --- |
@@ -122,8 +120,6 @@
 | [`harness-astro-islands`](../adapters/astro/skills/harness-astro-islands/SKILL.md) | React Islands | Hydrate tương tác có chọn lọc, không nhầm Islands với MFE | Island component và UX tests |
 | [`harness-astro-seo`](../adapters/astro/skills/harness-astro-seo/SKILL.md) | SEO | Metadata, sitemap, nội dung hữu ích và a11y | Trang có metadata và kiểm chứng HTML |
 | [`harness-astro-performance`](../adapters/astro/skills/harness-astro-performance/SKILL.md) | Performance | JS budget, lazy loading, Web Vitals thực đo | Benchmark/build evidence |
-| [`harness-astro-cloudflare`](../adapters/astro/skills/harness-astro-cloudflare/SKILL.md) | Deploy | Static/CDN trước, Workers khi cần backend có kiểm soát | Kế hoạch Cloudflare và approval |
-| [`harness-astro-microfrontend`](../adapters/astro/skills/harness-astro-microfrontend/SKILL.md) | Scale | Lộ trình tách công cụ thành deploy riêng nếu thực cần | ADR/MFE migration checklist |
 
 ## Kubernetes adapter (3)
 
@@ -168,3 +164,7 @@ Product → Architecture → Delivery → Core/adapter uses [Solution workflow](
 ## Continuous development
 
 [Continuous development](continuous-development.md) composes existing Core spec/debugging/tdd/verification/review with Product business-analysis/acceptance-criteria/traceability/backlog/TechSpec, Architecture change-impact and Delivery scope-change skills. Only affected perspectives are loaded; no new role or skill is required.
+
+## Selective Product profiles
+
+Analysis exposes 11 and Discovery 5 canonical Product skills. IDs and source ownership stay Product; selecting both or the compatibility product bundle exposes each skill once. Profiles add module choices, not duplicate skill IDs. Canonical assets are vendored for valid shared references; this is selective context, not a smaller npm download.