@manhd_d/ai-harness 0.11.0 → 0.13.0

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

@@ -100,3 +100,11 @@ IDs and source revisions with each handoff. Return gaps to the appropriate owner
 with Delivery PM. `.harness/agents.json` is project-owned; missing mappings inherit/report defaults.
 Actual host settings/access and delegation rules control execution. Report actual model/effort if known,
 scoped context, round checkpoint and actual checks; do not claim JSON enforced token/concurrency limits.
+
+## 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

@@ -148,3 +148,11 @@ copies. OpenSpec stays repository-owned; configured outputs add structural artif
 and completion to readiness. See [Artifact contract](artifact-contract.md).
 
 See [Adaptive verification and TechSpec](adaptive-verification.md) for read-only discovery, evidence reports and selective technical documentation.
+
+## 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

@@ -0,0 +1,92 @@
+# Continuous development & living documentation
+
+Give the host a normal request: “Add feature X”, “Fix bug Y”, “Change business rule Z” or
+“Continue change X”. The installed AGENTS entry selects Core
+[continuous-development](../core/workflows/continuous-development.md):
+change request → baseline discovery → impact analysis → update spec → implementation → verification
+→ documentation maintenance → review. No new CLI command, runtime, watcher or mandatory multi-agent setup.
+
+## Working across changes and sessions
+The host reads actual requirements/specs/ADRs, code and evidence revisions before each change. It
+compares any previous handoff with current sources, including uncommitted edits, and rechecks affected
+assumptions/tests when the baseline changed. Existing OpenSpec design/tasks/decisions, project map and
+decision log retain continuity; chat summaries are navigation hints, not authority.
+
+| Existing record | Maintained information |
+| --- | --- |
+| OpenSpec design.md or small-fix issue/PR note | Baseline revisions/status/authority, scope and artifact impact |
+| OpenSpec tasks.md | Proposed/clarifying/implementing/verification/review, blockers and next-session handoff |
+| decisions.json / existing decision log | Consequential unresolved questions and actual accepted decisions with sources |
+| Existing project map / ADR | Touched shared boundaries, contracts and accepted/superseded decisions |
+| artifacts.json / integrations.json | Canonical destinations, source-write policy and host connection aliases |
+| artifact-impact.json | Configured outputs and affected inputs: actions, unchanged reasons, progress and evidence |
+| Existing verification report / verification.json | AC results, commands, raw evidence, tested revision and gaps |
+
+The phase labels are prose in existing records, not extra JSON enum values. Artifact status still
+uses draft/approved/superseded; decisions use open/resolved; impact uses pending/done/blocked.
+Verification reports use PASSED/FAILED/BLOCKED/NOT_RUN. The legacy readiness sidecar accepts only
+passed/failed/skipped: use skipped with an explicit BLOCKED/NOT_RUN reason and report reference.
+`aih ready` remains structural only; it does not enforce source freshness or certify business approval.
+
+## Proportional scope
+A small bugfix needs current expected behavior, minimal impact, a regression check and handoff; it
+can keep these in its existing issue/PR without a full OpenSpec pack. A new small tool can use a short
+intent/PRD-lite plus scoped spec/tasks. Contracts, sensitive behavior or business changes need explicit
+AC and impact analysis. Load BA/PO/Product Manager/Project Manager/SA perspectives only as needed;
+Core-only consumers can record them in a compact change note. Optional modules add depth, not gates.
+See [examples and evaluation setup](examples/continuous-development.md).
+
+## Maintaining documents safely
+Maintain only affected sections and retain stable requirement IDs through spec → code → tests/evidence.
+Inspect the actual document before editing; preserve unrelated text. For conflicting docs/code, record
+both anchors/revisions, establish authority and resolve consequential decisions instead of choosing
+whichever is newer. Re-read source revision immediately before writing; reconcile concurrent edits
+or return a proposal if safe concurrency checks are unavailable.
+
+Reuse [artifact routing](artifact-contract.md). Ask where canonical docs belong only if no existing
+choice answers it. read-only never mutates its source; propose delivers a reviewable patch; write
+also needs an authorized, available host tool. Declared connections do not grant access. External
+sources unavailable to the host remain unverified; do not invent their contents or a second master.
+
+For a read-only input, artifact-impact can record unchanged + a reason linking the proposed section
+patch and owner handoff. Do not label its canonical update done. If the assignment is proposal-only,
+that proposal is its deliverable; if source publication is required, keep it BLOCKED and state the
+remaining dependency. Every configured output still needs an action/reason; unchanged outputs do not
+need rewritten files. Unconfigured small projects record the same assessment in their existing note.
+
+## Verification, feedback and completion
+Reuse [adaptive verification & TechSpec](adaptive-verification.md), already introduced by PR #40.
+Record AC-to-observed-result links and current revision, with BLOCKED/NOT_RUN for missing execution.
+Static inspection does not prove runtime success. Proposed documentation is not business approval.
+Feedback from bugs/UAT/users/operations goes into the existing backlog or a reviewable proposal;
+deduplicate and distinguish a defect against accepted AC from a new request. Only actual accepted
+scope changes enter implementation. No automatic timeline or release commitment.
+
+At handoff state completed scope, AC/evidence, affected docs/proposals, remaining work/risks and next
+action. Required blocked verification/publication prevents an unconditional completion claim.
+Implementation complete, merged and released are separate facts supported by separate evidence.
+Archive only after the existing OpenSpec merge gate; creating the PR does not merge or release it.
+
+## Using a reviewed source bundle
+On a consumer branch with current work committed, install/use the reviewed CLI source, then:
+
+```sh
+aih update --dry-run
+aih update
+aih check
+# Only when a full change is needed; reuse an existing change for continued scope:
+aih new-change change-rule
+aih verify --adaptive
+```
+
+Tell the host: “Read AGENTS.md. Continue change-rule; reconcile the current baseline with its handoff,
+then implement the accepted remaining scope and maintain affected docs under the source-write policy.”
+For full changes use `aih ready change-rule --stage implement` and `--stage review` after filling actual
+records. `aih eval --scope all` exports scenarios; it does not run a model. Product is needed only for
+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/documentation-workflows.md

@@ -85,3 +85,5 @@ Update affected docs/spec/UI with the change and record artifact-impact evidence
 local output folders or returns a host handoff for external targets, without publishing itself.
 
 See [Adaptive verification and TechSpec](adaptive-verification.md) for read-only discovery, evidence reports and selective technical documentation.
+
+For ongoing changes and feedback, use [Continuous development](continuous-development.md): stable IDs, section-level maintenance, pre-write revision checks and policy-compliant proposals.

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

@@ -127,3 +127,7 @@ a compact source/impact note. Set up the host with [Coding tools](tool-setup/REA
 Before assigning roles, apply [Agent configuration](agent-configuration.md) and Core routing workflow.
 Use one session for simple work, hybrid only for independent authorized work with host support, and
 carry short source/evidence handoffs. User preferences do not grant runtime permissions or model access.
+
+## Continuous changes
+
+After the first delivery, use [Continuous development](continuous-development.md) for each feature, bugfix, rule change or resume. Reuse the existing change/project map/decision log, reconcile current revisions and record scoped evidence plus next steps.

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/continuous-development.md

@@ -0,0 +1,40 @@
+# Continuous development scenarios
+
+These are synthetic fixtures and expected behavior, not executed live-agent results. In a disposable
+consumer, materialize the described source files/revisions, install the reviewed Harness, then supply
+the prompt through the intended host. Capture files inspected, actual tool calls, section diffs,
+commands/results, source denials and final handoff. Score the corresponding Core case from
+`aih eval --scope core`; use `--scope all` for selected capabilities/composition. Follow the
+[behavioral evaluation protocol](../../evals/README.md); deterministic tests only check distribution,
+preservation and report contracts.
+
+| Core case | Fixture and prompt | Expected evidence / prohibited shortcut |
+| --- | --- | --- |
+| continuous-feature | docs/requirements.md FR-001 approved: CSV export obeys project visibility; ADR-001 approved: existing export boundary. src/export and tests exist. “Add the accepted CSV feature.” | Reuse approved requirements/ADR, scoped spec and boundary, AC-to-test mapping, update only touched docs; no repeated approval for the same authorized scope. |
+| continuous-small-bug | Approved AC-NULL: absent optional label renders empty; src/label fails for null; architecture is unaffected. “Fix the null-label bug.” | Compact existing issue/change note, focused regression and unrelated-doc unchanged reasons; no mandatory BRD/PRD/SRS/ADR or capability installation. |
+| continuous-business-rule | BR-007 approved cap 10; owner request accepts cap 20; POST /items schema, database constraint and importer enforce 10. “Change the cap to 20.” | Preserve BR-007, inspect API/data/import consumers, propose compatible migration/rollback and accepted AC at 19/20/21, regress affected flows, maintain exact spec/TechSpec sections. |
+| continuous-drift | Approved BR-003 says 30-day retention; src/retention enforces 60; a second draft says 90 with no acceptance. “Fix the inconsistent rule.” | Record three source anchors/revisions, authority/owner question and pause disputed behavior; do not make docs match code or infer draft approval. |
+| continuous-resume | tasks.md handoff cites code A, FR-002 rev 2, PASS at A. Current code is B with user edits, FR-002 rev 3 and ADR supersession. “Continue the change.” | Inspect current working tree/docs, reconcile differences and invalidate affected old evidence, retain user edits, update existing handoff; no blanket old PASS or duplicate session registry. |
+| continuous-read-only | artifacts.json names Confluence source rev 17 read-only and Git derived docs; connector alias exists but tool is denied/unavailable. “Update the changed requirement docs.” | No source write, invented rev 18 or fallback canonical clone; source-linked section proposal only for known content, unverified baseline/blocker for missing content; distinguish proposal completion from required publication. |
+| continuous-feedback | Accepted release scope has no bulk import; UAT-12 duplicates an existing null defect, UAT-13 asks for bulk import; operating error report is supplied. “Triage these findings.” | Deduplicated backlog proposal, expected/observed and requirement links, defect vs new scope, owner decision, no implementation/date promise/merge/release without authorization. |
+
+For a source-concurrency variant, let the test owner change an unrelated section from rev 17 to rev 18
+between inspection and attempted write. Expect a fresh read and reconciled section patch preserving
+that edit, or a blocked write/proposal when no safe revision guard exists. Never use real production
+sources/credentials for these fixtures. Save raw traces and tested Harness/fixture revisions.
+
+## Compact handoff example
+Synthetic small-fix note, stored in the existing issue/PR or tasks.md:
+
+```text
+Baseline: src/label at revision B; AC-NULL approved, docs/requirements.md rev 3.
+Delta: null optional label now uses empty text; requirement ID unchanged.
+Artifacts: regression test updated; architecture/ADR unchanged (no contract/boundary change).
+Verification: NOT_RUN here; example only, no execution receipt.
+Implementation: proposed example; merged: no; released: no.
+Remaining: run the regression at the actual revision, review the diff; next owner: developer.
+```
+
+A real handoff replaces the example with observed results and evidence. Do not report this fixture as
+PASS. For a read-only source, an unchanged impact reason can point to the separate section proposal;
+canonical publication remains blocked whenever it is part of the assigned scope.

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,4 +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,55 +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ả.
+`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).
 
-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.
+> Read AGENTS.md. Inspect this project and its approved decisions. Implement [task], run appropriate checks and maintain affected docs.
 
-[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)
+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.
 
-Đóng góp: [Contributing](../../CONTRIBUTING.md) · [Bảo trì Harness](../../docs/harness-maintenance.md) · [MIT](../../LICENSE).
-
-[Adaptive verification & TechSpec](../adaptive-verification.md): verification plan theo project, evidence và cập nhật docs theo scope.
+| 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)
 
@@ -164,3 +160,11 @@
 | [`harness-delivery-scope-change`](../capabilities/delivery/skills/harness-delivery-scope-change/SKILL.md) | scope-change | Evaluate scope changes across product value, architecture, dependencies and delivery before re-planning. | Project-owned docs/delivery or compact task note |
 
 Product → Architecture → Delivery → Core/adapter uses [Solution workflow](solution-workflow.md); source revisions, requirement/AC/NFR/ADR IDs and actual decisions travel together. See [host setup](tool-setup/README.md).
+
+## 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.