@manhd_d/ai-harness 0.7.0 → 0.9.0

package/core/workflows/project-setup.md

@@ -1,16 +1,24 @@
 # First-run project setup
 
 Read AGENTS.md, local.md, actual build files and existing environment configuration first.
+For project/MVP/architecture decisions, apply `solution-framing.md` at the appropriate depth.
 Use `aih setup` for structured suggestions; it never interviews the user or writes answers.
 Do not ask about facts already established in the repository or current conversation.
 
 1. Identify project scope, source documents, build/test commands and environment constraints.
+   Apply `.harness/core/rules/project-conventions.md`: classify each affected module as new, maintain
+   or mixed; inspect configured conventions, comparable code and public shared APIs. Adapter detection
+   is stack evidence, not a project-mode decision. For a new project, propose the relevant adapter's
+   minimal conventions; for maintenance, preserve the applicable project conventions.
 2. Ask only missing consequential choices using the clarification workflow. Ask 1–3 questions
    per turn, with A/B/C options where suitable, a grounded recommendation and a free-text option.
 3. For Java, inspect Maven/Gradle wrappers before proposing PATH or a custom tool. A wrapper is
    a recommendation only when present and consistent with project policy; do not switch corporate
    tools or download a replacement without authorization.
-4. Record shared facts and decisions in `.harness/local.md`. Define exact tool IDs, argument arrays
+4. Record shared facts and decisions in `.harness/local.md`: scope/mode, authoritative source paths,
+   layout and dependency boundaries, reusable common APIs, naming/error/test conventions, commands
+   and approved exceptions. Link existing documentation instead of duplicating it. Keep missing facts
+   explicit; do not overwrite previous answers. Define exact tool IDs, argument arrays
    and required file paths in `.harness/environment.json`. Record evidence/source, not guessed versions.
 5. For a machine-specific executable/file location, use `.harness/machine.json` or an environment
    reference. The machine file can only override declared paths. It does not override permissions,

package/core/workflows/solution-framing.md

@@ -0,0 +1,33 @@
+# Project overview, MVP and architecture fit
+
+Apply before new-project implementation or consequential feature/architecture changes, and during
+impact review. Size the work to the request; an existing clear bugfix needs a short source/reuse note,
+not a fresh BRD, architecture pack or planning interview.
+
+1. Read the user request, local facts, authoritative docs/ADRs and affected source/tests. Establish
+   new/maintain/mixed scope, actual revision and relevant modules/integrations/trust/data boundaries.
+   Reuse approved decisions and inspect only the context needed; do not fabricate an unseen project map.
+2. For a product/new journey, establish actor/problem, complete user outcome, in/out MVP scope, AC and
+   minimum safety/data quality. Prototype and MVP are distinct goals. Missing scope/behavior questions
+   go to the actual owner; explicit existing authorization still covers routine implementation choices.
+3. Establish consequential quality constraints and testable NFR scenarios. Unknown traffic, latency,
+   recovery, budget or capacity stays explicit until confirmed. Avoid unsupported numeric targets.
+4. Compare 2–3 viable architecture options only when a real decision is open; evaluate complexity,
+   operations, testability, costs and reversibility against requirements/team context. Recommend a
+   grounded minimal fit. For maintenance preserve existing boundaries unless the agreed change requires more.
+5. Separate application/deployment architecture from feature patterns. Ports and Adapters defines
+   boundaries; Factory addresses creation. Strategy/Adapter/State require actual variation or state
+   needs. Direct code is valid; do not add interfaces, engines or layers for hypothetical future scale.
+6. Describe affected public module/data/API/event ownership and important success/failure flows, reuse,
+   dependency direction and rollout/rollback constraints. Record significant decisions with alternatives,
+   owner/status and reconsideration trigger; compact notes suffice for reversible details.
+7. Keep a source-linked overview/map or pointers in local.md. On a later change inspect touched entries
+   for drift, update only verified/decided context and preserve superseded decisions. Do not flood context.
+8. Use installed Product product-to-solution, Architecture discovery-to-design/change-review and
+   Delivery planning/execution-change workflows when selected. Absent modules, apply the compact
+   equivalent in existing OpenSpec design/tasks; do not auto-install optional modules.
+9. Handoff source revisions, requirement/AC/NFR/ADR IDs, decisions/status, code/public boundaries,
+   dependencies, verification and risks to Core/selected adapters, UIUX and DevOps where relevant.
+   Return gaps to the owning role; role documents do not launch agents or self-approve decisions.
+10. Review implementation against accepted scope/design and actual tests. Model behavior evaluations,
+    manual review and application checks are separate evidence. Structural ready is not approval.

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

@@ -2,15 +2,17 @@
 
 | Stage | Input | Output and gate |
 | --- | --- | --- |
-| Discover | Request, repository, linked sources | Scope, uncertainties, affected repos and risks; use clarification workflow for consequential unknowns |
+| Discover | Request, repository, linked sources | Scope/mode, affected repos and risks, convention sources, comparable code and reuse candidates; clarify consequential unknowns |
 | Specify | Agreed behavior | proposal, design, delta specs and vertical tasks |
 | Review spec | Acceptance scenarios and design | Owner agreement for consequential choices; explicit task authorization may already cover routine choices |
-| Implement | One task with a public test boundary | Failing meaningful test, minimal implementation, green test |
+| Implement | One task with a public test boundary and reuse plan | Failing meaningful test, minimal implementation, green test; established boundaries and rationale for new components |
 | Verify | Changed behavior | Relevant automated checks and honest skipped-check list |
-| Review | Diff plus spec | Findings on correctness, security, compatibility and requirements |
+| Review | Diff plus spec and convention sources | Findings on correctness, security, compatibility, reuse, placement and unnecessary abstraction |
 | Deliver | Reviewed branch | PR with change ID, evidence, residual risks and rollback plan |
 | Archive | All associated PRs merged | Sync accepted specs and archive via OpenSpec in a separate reviewed change if needed |
 
+For new projects or consequential features, follow `solution-framing.md`: source-linked overview,
+MVP/NFR, justified architecture/pattern choices and delivery dependencies feed OpenSpec design/tasks.
 For first use, read `project-setup.md` in this workflow directory. Before implementing consequential
 unknowns, follow `clarification.md`: inspect existing answers, ask 1–3 A/B/C questions with grounded
 recommendations, and record answers/source in the change's decisions.json. Do not ask again once
@@ -18,6 +20,12 @@ scope and authorization are already clear. Run `aih ready <id> --stage implement
 record actual checks in verification.json and use `--stage review` before handoff. These commands
 check structure, not business approval or the truth of test evidence.
 
+Apply `.harness/core/rules/project-conventions.md` even when a full spec is unnecessary. Before adding
+code, record inspected paths, reused public APIs, intended placement and reasons for new components
+in the task note or existing change. Preserve each module's conventions in mixed repositories. Review
+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
 an observed defect. Agents are roles, not automatically spawned workers; a single assistant can perform
 them sequentially. Respect the host's delegation rules.

package/docs/README.md

@@ -0,0 +1,39 @@
+# Tra cứu AI Harness
+
+Mới bắt đầu: [Cài đặt và giao task đầu tiên](getting-started.md).
+Chỉ đọc phần phù hợp với công việc đang làm.
+
+## Sử dụng
+
+| 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) |
+| 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) |
+| Từ ý tưởng / tài liệu BA đến yêu cầu | [Documentation workflows](documentation-workflows.md) · [Confluence](../integrations/confluence/README.md) |
+| Đi từ yêu cầu đến vận hành | [Full SDLC](end-to-end-workflow.md) · [BA/PO/SA/PM](solution-workflow.md) |
+| Spec trước code / review | [Change readiness](change-readiness.md) · [OpenSpec](openspec.md) |
+| Tra skill và bàn giao agent | [Skill matrix](skill-matrix.md) · [Agent handoffs](agent-handoffs.md) |
+| Kiểm tra code và đánh giá kết quả AI | [Verification](verification.md) · [Behavioral evaluations](../evals/README.md) |
+
+[Code React/Next.js & React Native/Expo](frontend-mobile.md) · [Monetization capability](../capabilities/monetization/README.md).
+
+## Ví dụ
+
+| Loại project | Hướng dẫn |
+| --- | --- |
+| Spring Boot API | [Backend](examples/spring-boot-api.md) |
+| Spring + Next.js | [Full-stack](examples/fullstack-web.md) |
+| React Native | [Mobile](examples/react-native-app.md) |
+| Python AI/RAG | [AI service](examples/ai-rag-service.md) |
+| Astro tool nhỏ | [Micro-tools](examples/astro-micro-tools.md) · [Adapter](../adapters/astro/README.md) |
+| Website có quảng cáo | [Astro + AdSense](examples/astro-adsense-microtools.md) · [Monetization](monetization.md) |
+| Bắt đầu từ ý tưởng | [Idea-driven](examples/idea-driven-project.md) |
+| Đã có tài liệu BA | [Document-driven](examples/document-driven-project.md) |
+
+## Đóng góp và phát hành
+
+[Contributing](../CONTRIBUTING.md) · [Bảo trì & ma trận ảnh hưởng](harness-maintenance.md) · [Kiến trúc](architecture.md) · [Thêm adapter](adapters.md).
+[Release policy](release-policy.md) · [Phát hành npm](npm-release.md) · [Versioning & migration](versioning.md) · [Changelog](../CHANGELOG.md).

package/docs/adapters.md

@@ -1,18 +1,22 @@
 # Adapter capabilities
 
+Maintainer entry point: [Harness maintenance and impact matrix](harness-maintenance.md).
+
 An adapter is a versioned instruction bundle, not an executable plugin. Core owns TDD, debugging,
 review and the general workflow. Adapter skills address technology-specific decisions and reuse Core.
 
 | Adapter | Skills |
 | --- | --- |
 | java-spring | Spring API, Kafka outbox, database migration |
-| react-nextjs | Accessible UI, server/client authorization and caching |
+| react-nextjs | Feature slices, behavior testing, accessible UI, server/client authorization and caching |
 | astro | Static-first micro-tools, islands, SEO, performance, Cloudflare and optional MFE migration |
-| react-native | Offline synchronization, permissions and deep links |
+| react-native | Screen/navigation slices, behavior/platform testing, offline synchronization, permissions and deep links |
 | ai-python | RAG access filtering, model tool safety |
 | kubernetes | Workload review, Helm release and safe rollout planning |
 
 ## Source contract
+For setup, skill choice and examples see [Frontend/mobile coding](frontend-mobile.md).
+
 adapter.yaml uses **JSON-compatible YAML 1.2**, parsed with JSON.parse. Arbitrary YAML syntax is not supported.
 The CLI rejects unknown fields and unsupported schemas rather than guessing. Required fields:
 
@@ -81,3 +85,7 @@ Add rules and a concrete technology skill with testable inputs/outputs; avoid du
 Declare metadata/checks/cases and register new adapter IDs. Include detection positive/negative fixtures,
 install/removal/drift cases, and report validation tests. Run npm test, npm run validate and npm run
 test:package. Version changes and review installed snapshots before release.
+
+## Project coding conventions
+
+Core owns new/maintain/mixed mode, precedence, discovery/reuse and diff-review rules for every adapter. Java/Spring, React/Next.js and React Native declare `rules/conventions.md` for stack defaults; existing project decisions take precedence. See [Project conventions](project-conventions.md). Checks remain advisory/manual and do not enforce application architecture.

package/docs/agent-configuration.md

@@ -0,0 +1,99 @@
+# Agent configuration and model routing
+
+Harness declares preferences; the AI host performs model selection and execution. No provider calls,
+automatic native configuration, agent creation, token enforcement or usage tracking is supplied.
+
+## Setup
+```bash
+aih init --adapters java-spring --capabilities product,architecture,delivery
+# Or, for a new consumer:
+aih init --agent-preset economy
+aih setup --host codex
+aih check
+```
+Run only the init variant appropriate to a new consumer. Existing installs use reviewed update
+--dry-run/update/check. Recommended is the default; custom seeds the same valid starting file for
+editing. An explicit preset against existing agents.json refuses overwrite. setup prints A/B/C choices
+and resolved routes; it never interviews or writes answers. No new aih config command is necessary.
+
+## Ownership
+Canonical recommendation: config/agents.default.json in the package/source. It is copied as locked
+.harness/templates/agents.default.json. Project-owned .harness/agents.json is seeded on init or the
+first reviewed update and then preserved byte-for-byte, outside the managed lock. Editing it is expected.
+Old snapshots without agents.json remain readable. An older alternate --source without the new default
+uses the installed CLI's canonical seed; no source files are changed. Invalid custom config blocks writes
+with a field-level error; it is not reset automatically. Keep credentials in host-managed secrets, not here.
+
+## 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
+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.
+
+Models are explicit native/opaque IDs or @alias references. models values are strings or
+{provider, model} descriptors; alias graphs must be finite, declared and acyclic. A bare balanced is
+an opaque model ID, while @balanced is an alias; this avoids silently accepting alias typos.
+Resolution: role model → project default model; role provider → alias descriptor provider → project
+provider; role reasoning → project default reasoning. Changing only defaultModel does not override
+explicit role mappings. enabled:false disables a dedicated route, not required review/security policies.
+
+```json
+{
+  "schema_version": 1,
+  "provider": "openai",
+  "defaultModel": "gpt-6.1-sol",
+  "defaultReasoning": "medium",
+  "models": { "economy": "gpt-6-luna", "balanced": "gpt-6.1-sol", "premium": "gpt-6-astra" },
+  "agents": {
+    "core:orchestrator": { "model": "@balanced", "reasoning": "high" },
+    "core:implementer": { "model": "@balanced", "reasoning": "medium" },
+    "core:documentation": { "model": "@economy", "reasoning": "low" }
+  },
+  "execution": { "mode": "hybrid", "maxConcurrentAgents": 2, "maxRounds": 3, "autoEscalateToPremium": false },
+  "hosts": {}
+}
+```
+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.
+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
+supported levels vary by model/client. Mode is single-agent, hybrid or multi-agent; concurrency is
+integer 1–32, rounds 1–20, and single-agent requires concurrency 1. These are schema bounds and advisory
+requests, not runtime capacity claims. Automatic premium escalation must be false; explicitly select
+@premium or another native model if desired. JSON max size 1 MiB; no shell text is executed.
+
+## Cross-provider and host mapping
+For Claude, choose an available Anthropic model and provider explicitly; OpenAI model IDs do not
+become Claude models. Gemini likewise needs an available Google/Vertex model. A role override may use:
+```json
+{ "provider": "anthropic", "model": "native-model-id-from-your-host", "reasoning": "medium" }
+```
+The placeholder is not an availability assertion. Alias descriptors allow the same explicit provider/model
+choice across several roles. Supported vendor transport/authentication must be configured in the host.
+
+Optional hosts.<host>.models maps provider/model to an explicit native replacement, and hosts.<host>.reasoning
+maps logical effort to native values. These are user-selected substitutions, not claims of equivalent
+models. For example, after inspecting the real Claude picker, replace this illustrative mapping target:
+```json
+{ "models": { "openai/gpt-6.1-sol": "native-claude-model-id" }, "reasoning": { "medium": "medium" } }
+```
+Put it inside hosts.claude-code. Configure every active request that needs translation, including Luna
+for documentation if used; unmapped incompatible routes are reported. setup marks availability unverified
+and runtime_verified:false even when a mapping is supplied. Unknown hosts also require verification.
+
+## Actual native integration
+[Tool setup](tool-setup/README.md) explains project-owned bridges. [Codex](tool-setup/codex.md),
+[Claude Code](tool-setup/claude-code.md) and [Gemini CLI](tool-setup/gemini-cli.md) contain model/native
+configuration references. Copy only a reviewed mapping into existing native config; do not overwrite it.
+CLI/IDE single sessions may retain one model while playing many roles; per-role preferences require
+supported native agents or deliberate separate sessions. Cursor/Copilot availability and reasoning
+controls vary by client. No role JSON automatically creates a native subagent or changes current session.
+
+## Lightweight execution
+[Routing workflow](../core/workflows/agent-routing.md) sizes execution to the task. Hybrid defaults to
+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).

package/docs/agent-handoffs.md

@@ -3,6 +3,10 @@
 AI Harness hiện có **role contracts**, không tạo các agent chạy tự động hoặc agent-to-agent queue. Một assistant có thể đảm nhiệm nhiều vai trò theo thứ tự, nhưng phải tách evidence, quyền hạn và human approval. Dùng cùng [Full SDLC](end-to-end-workflow.md) và [Skill matrix](skill-matrix.md).
 
 ## Trách nhiệm theo vai trò
+For React/Next.js and React Native implementation/testing, use the selective skill routing in
+[Frontend/mobile coding](frontend-mobile.md). Handoff AC → route/screen → API/state → test evidence,
+including reused public APIs and unavailable browser/native checks; retain the same Core roles.
+
 
 | Role contract trong source | Nhận | Bàn giao | Không được làm |
 | --- | --- | --- | --- |
@@ -11,6 +15,11 @@ AI Harness hiện có **role contracts**, không tạo các agent chạy tự đ
 | [product-owner](../capabilities/product/agents/product-owner.md) | Approved requirements | Epics/stories/AC, backlog readiness | Tự đánh dấu Ready khi còn thiếu phê duyệt |
 | [project-manager](../capabilities/product/agents/project-manager.md) | Scope và phụ thuộc | Timeline/risks/RAID theo nguồn | Bịa estimate/commitment |
 | [requirements-reviewer](../capabilities/product/agents/requirements-reviewer.md) | BRD/PRD, nguồn và stories | Review report, missing trace, human gate | Gọi draft là Approved |
+| [solution-architect](../capabilities/architecture/agents/solution-architect.md) | MVP/requirements, actual source/NFR | Overview, public boundaries/contracts, options/ADRs and verification | Self-approve decisions or impose patterns |
+| [architecture-reviewer](../capabilities/architecture/agents/architecture-reviewer.md) | Design/diff, ADRs and actual checks | Source-linked findings, drift/quality and residual risk | Claim independent approval of own work |
+| [delivery project-manager](../capabilities/delivery/agents/project-manager.md) | Reviewed scope/solution, actual capacity | Value slices, dependencies, risks and change assessment | Invent dates/progress or message stakeholders |
+| [orchestrator](../core/agents/orchestrator.md) | Authorized task, preferences and host capabilities | Scoped coordination and consolidated evidence | Auto-escalate premium or claim native workers exist |
+| [documentation](../core/agents/documentation.md) | Verified sources and decisions | Source-linked document diff and quality evidence | Invent approval or unperformed verification |
 | [planner](../core/agents/planner.md) | Scope, approved requirements, repo map | OpenSpec design/tasks/test outline | Implement ngoài scope |
 | [implementer](../core/agents/implementer.md) | Spec, tasks, repo, adapter | Code slice và actual test evidence | Merge/deploy |
 | [test-engineer](../core/agents/test-engineer.md) | AC, diff, contracts | Test scenarios, executed results/gaps | Tuyên bố pass khi chưa chạy |
@@ -77,3 +86,17 @@ Next gate: security-reviewer and human PR review
 ~~~
 
 Đây là mẫu handoff, không phải report của một task đã chạy.
+
+## Product and solution delivery
+
+Product Manager owns value/outcomes; Project Manager coordinates delivery. The existing Product PM
+role/template remains a compatibility entry; the Delivery capability supplies deeper planning.
+Use [Solution workflow](solution-workflow.md) and [tool setup](tool-setup/README.md); carry MVP/AC/NFR/ADR
+IDs and source revisions with each handoff. Return gaps to the appropriate owner and keep approval factual.
+
+## Model and execution preferences
+
+[Agent configuration](agent-configuration.md) resolves namespace:role without conflating Product PM
+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.

package/docs/architecture.md

@@ -1,5 +1,7 @@
 # Architecture and scope
 
+Maintainer entry point: [Harness maintenance and impact matrix](harness-maintenance.md).
+
 AI Harness is a versioned instruction and workflow distribution framework. Its executable part is a
 local installer and integrity checker. It is not an LLM gateway, an orchestration server or a sandbox.
 
@@ -54,7 +56,7 @@ own model-backed runtime; actual permissions, cost limits and network allowlists
 
 ## Advertising monetization capability
 
-`capabilities/monetization/` is an optional, stack-neutral guide for legitimate publisher readiness, safe ad UX, SEO and revenue analysis. It does not install provider SDKs, access Google accounts, claim consent compliance or guarantee approval/revenue. Templates are vendored into the selected consumer under `.harness/capabilities/monetization/templates/`; `aih new-doc` still only scaffolds Product documents. Owners copy monetization templates to project-owned `docs/monetization/` using authorized filesystem tools. Review [Monetization guide](monetization.md).
+`capabilities/monetization/` is an optional, stack-neutral guide for legitimate publisher readiness, safe ad UX, SEO and revenue analysis. It does not install provider SDKs, access Google accounts, claim consent compliance or guarantee approval/revenue. Templates are vendored into the selected consumer under `.harness/capabilities/monetization/templates/`; `aih new-doc` defaults to Product; explicit `--capability monetization` selects a declared installed template into project-owned `docs/monetization/`. Review [Monetization guide](monetization.md).
 
 ## Astro static-first adapter
 
@@ -116,3 +118,22 @@ DevOps is an optional stack-neutral capability for release procedures and SRE; t
 ## Documented end-to-end usage
 
 The cross-module route is described in [Getting started](getting-started.md), [Full SDLC](end-to-end-workflow.md), [Skill matrix](skill-matrix.md) and [Agent handoffs](agent-handoffs.md). All roles/skills remain instruction contracts. The four [stack walkthroughs](examples/spring-boot-api.md) illustrate permitted integrations, not a runnable scaffold or orchestration engine.
+
+## Solution delivery capabilities
+
+Product 1.2.0 adds MVP/outcomes and explicit template/example/quality/handoff sections. Optional
+Architecture and Delivery schema-1 modules use existing roles/templates/checks/evals and locked
+installation; soft recommendations never auto-select them. Core solution-framing provides proportional
+overview/MVP/NFR/architecture/impact context without requiring every capability or document.
+new-doc gains explicit --capability (default Product), validating installed metadata and declared
+templates and preserving project-owned outputs. See [Solution workflow](solution-workflow.md).
+Host configuration bridges are user-owned recipes in [tool setup](tool-setup/README.md); no host
+account configuration, native-agent installation, new dependency or orchestration engine is supplied.
+
+## Agent configuration boundary
+
+config/agents.default.json is the canonical recommendation, locked as templates/agents.default.json in
+the snapshot. agents.json is project-owned and preserved. agents.js validates/resolves aliases and
+namespaced roles; setup supplies an advisory host plan with availability unverified. No provider calls,
+native writes, orchestration, usage meter or automatic escalation. Old alternate sources use the packaged
+default when absent; old consumers without config remain valid. See [Agent configuration](agent-configuration.md).

package/docs/cli.md

@@ -12,14 +12,14 @@ Exit 0 means the requested operation succeeded; 1 means validation/I/O/drift fai
 | resolve | --source; --adapters a,b; --capabilities a,b | Validate module selection and compatibility; read-only |
 | verify | --scope adapters/core/capabilities/all | Read installed advisory checks; executed false, no subprocesses |
 | eval | --scope adapters/core/capabilities/all; --report FILE | Emit unscored template or aggregate reviewed report; no model calls |
-| init | --detect OR --adapters a,b; --capabilities a,b; --source; --dry-run; --allow-major | Install a snapshot; exact rerun is idempotent |
+| init | --detect OR --adapters a,b; --capabilities a,b; --agent-preset recommended/economy/custom; --source; --dry-run; --allow-major | Install a snapshot and seed project agent preferences; exact rerun without explicit preset is idempotent |
 | update | --source; --dry-run; --allow-major | Update unedited owned files and seed missing project files |
 | check | none | Compare installed files/block with lock and selection; no writes |
 | doctor | none | check plus configured environment/path diagnostics and generic PATH hints; no execution |
-| setup | none | Read-only host-facing question plan; skips tool-selection suggestions when tools are configured |
+| setup | --host codex/claude-code/gemini-cli/cursor/copilot/custom-ID (optional) | Read-only question and agent-routing plan; skips tool-selection suggestions when tools are configured |
 | ready ID | --stage implement/review | Structural readiness; blocked returns exit 1, ready returns exit 0; no business approval |
 | new-change ID | none | Create an unapproved OpenSpec draft using installed templates |
-| new-doc TYPE | none | Copy a selected locked Product template to `docs/discovery/` (idea, research) or `docs/product/` (other types) without overwriting |
+| new-doc TYPE | --capability ID (default product) | Copy one selected locked template into the owner's project docs without overwrite; Product idea/research use `docs/discovery/`, other Product types use `docs/product/` |
 | skills | none | List installed skill metadata only |
 | skill NAME | none | Read one installed, locked skill |
 
@@ -36,7 +36,7 @@ Selection changes belong in .harness/project.json; unknown or duplicate adapters
 
 ## Optional monetization capability
 
-`aih init --capabilities monetization` installs five stack-independent advertising/revenue skills and 2 Markdown workflows with 4 templates. Combine with `--adapters astro` or `react-nextjs`; `product` and `uiux` are optional. `aih verify --scope capabilities` gives an unexecuted manual publisher policy/consent checklist. `aih new-doc` is **Product-only**; the editor may copy installed monetization Markdown templates to user-owned `docs/monetization/` with explicit no-overwrite review. No Google account access, ads publishing or metrics APIs are provided. See [Monetization guide](monetization.md).
+`aih init --capabilities monetization` installs five stack-independent advertising/revenue skills and 2 Markdown workflows with 4 templates. Combine with `--adapters astro` or `react-nextjs`; `product` and `uiux` are optional. `aih verify --scope capabilities` gives an unexecuted manual publisher policy/consent checklist. `aih new-doc` defaults to Product; explicitly choose `--capability monetization` to scaffold a declared installed template into project-owned `docs/monetization/` without overwrite. No Google account access, ads publishing or metrics APIs are provided. See [Monetization guide](monetization.md).
 
 ## Project environment and clarification
 
@@ -123,3 +123,28 @@ See [Getting started](getting-started.md) for CLI boundaries, [Full SDLC](end-to
 With the optional `product` capability selected, `aih new-doc idea` and `aih new-doc research` safely create `docs/discovery/<type>.md` in the consumer repository. Other names including `prd-lite`, `srs` and `use-cases` create `docs/product/<type>.md`.
 
 All types must be declared templates in the installed, hash-locked Product manifest. Commands refuse unknown names, traversal, overwrite, collisions and installation drift. These are **blank templates only**, not AI-generated content. Read [Documentation workflows](documentation-workflows.md) for the two intake paths and approvals.
+
+### Convention setup guidance
+
+`aih setup` suggests a new/maintain/mixed scope question for unconfigured environments without guessing an answer. Regardless of suggested questions, the host must inspect existing conventions and reuse opportunities; a configured tool does not establish project mode. Answers stay in project-owned `.harness/local.md`. See [Project conventions](project-conventions.md). No application scanning, scaffolding or commands are executed.
+
+## Architecture and Delivery drafts
+
+`aih new-doc <type>` still defaults to Product (idea/research remain under docs/discovery).
+Use `aih new-doc overview --capability architecture`, `aih new-doc adr --capability architecture` or
+`aih new-doc delivery-plan --capability delivery` for a declared template in that installed capability.
+Output is project-owned docs/<capability>/<type>.md; locked metadata/templates are required, drift and
+overwrite are refused, and no draft is filled or approved. --capability is supported only by new-doc.
+The historical Product delivery-plan path remains supported; do not duplicate an accepted plan.
+See [Solution workflow](solution-workflow.md) and [host setup](tool-setup/README.md).
+
+## Agent preferences
+
+`aih init --agent-preset recommended|economy|custom` seeds project-owned agents.json non-interactively;
+existing files are validated/preserved and explicit preset overwrite is refused. `aih setup --host codex`
+(or claude-code/gemini-cli/cursor/copilot/custom ID) exports resolved roles and compatibility limitations
+without probing models or editing host files. No extra config command, runtime or usage tracking.
+See [Agent configuration](agent-configuration.md).
+Setup exit 0 means the read-only plan was produced, not that all models are usable. Inspect the nested
+agent_configuration.status and active route availability; host-incompatible/unverified requests require
+actual host checks before execution.

package/docs/documentation-workflows.md

@@ -69,3 +69,10 @@ Risks/unknowns: threshold and privacy requirements pending decision
 Permissions: read/write authorized project branch only; no external publish or merge
 Human reviewer: developer or named BA/PO
 ```
+
+## Product → solution → delivery
+
+For new/material journeys, reuse existing BA documents and continue with [Solution workflow](solution-workflow.md).
+PO defines a usable MVP and evidence-backed outcomes, SA evaluates quality/architecture/contracts,
+PM sequences dependent value slices. Accepted decisions and requirement IDs feed OpenSpec and adapters.
+Depth scales to the task; no mandatory full document set for small fixes. Use [tool setup](tool-setup/README.md).

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

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

package/docs/examples/fullstack-web.md

@@ -52,11 +52,15 @@ aih new-change add-ticket-creation
 aih skill harness-spec
 aih skill harness-tdd
 aih skill harness-java-spring-spring-api
+aih skill harness-react-nextjs-feature-delivery
 aih skill harness-react-nextjs-accessible-ui
 aih skill harness-react-nextjs-server-boundaries
+aih skill harness-react-nextjs-behavior-testing
 ~~~
 
 Spec phải chứa contract `POST /...` thực tế đã review, authorization, error envelope, loading/empty/errors, client/server boundaries, cache invalidation và contract tests. Implement thành vertical slice API + UI cùng acceptance IDs. Đối với giao diện frontend, kiểm tra SSR/client boundary và tránh đưa credentials ra browser.
+Chỉ đọc skill body cần cho task; reuse client/query/FormField hiện có. Skills delivery/testing bao phủ
+route/form/API/state và AC-linked component/browser evidence; không ép plain React dùng Next.js.
 
 Ví dụ kiểm tra **chỉ nếu repo có tương ứng**:
 

package/docs/examples/react-native-app.md

@@ -28,14 +28,18 @@ Nếu chỉ sửa một lỗi offline đã có ticket/AC duyệt, có thể bỏ
 aih new-change offline-draft-sync
 aih skill harness-spec
 aih skill harness-tdd
+aih skill harness-react-native-screen-delivery
 aih skill harness-react-native-offline-sync
 aih skill harness-react-native-device-permissions
+aih skill harness-react-native-behavior-testing
 ~~~
 
 - `offline-sync`: định nghĩa local persistence encryption/retention, idempotency key, queue/retry backoff, conflict resolution và đồng bộ lại khi token hết hạn.
 - `device-permissions`: chỉ cần nếu feature có camera/location/notification/deep link; kiểm tra iOS và Android riêng, fallback khi từ chối permission.
 - Spec chứa test matrix: airplane mode, offline restart, duplicate request, conflict, revoke session, low storage và app update.
 - Không log token/customer payload, không giả định AsyncStorage/SecureStore đã được chọn; dùng stack đang có.
+- Dùng screen-delivery để reuse navigation/theme/client/form và behavior-testing cho test matrix;
+  chỉ nạp offline/permissions khi task chạm rủi ro đó. JS mocks không chứng minh native/device behavior.
 
 **Verification** — tùy project scripts/toolchain, không được Harness thực thi:
 

package/docs/frontend-mobile.md

@@ -0,0 +1,76 @@
+# Code React/Next.js và React Native
+
+Adapter có rules/conventions và skills cho implementation, kiểm thử cùng các rủi ro chuyên biệt.
+Không cần thêm bộ skills ngoài để bắt đầu. Chỉ cài module phù hợp; AI đọc một skill khi task cần nó.
+
+## Init và bắt đầu
+
+Trong repository ứng dụng đã tạo, chọn **một** lệnh theo stack:
+
+```bash
+# React web hoặc Next.js
+aih init --adapters react-nextjs
+# React Native hoặc Expo
+aih init --adapters react-native
+```
+
+Sau đó chạy `aih check`, `aih setup --host codex` (đổi host theo công cụ thực tế), mở AI tool và giao:
+
+> Đọc AGENTS.md và workflow project-setup. Khảo sát router, versions, common components, API client,
+> form/state/navigation và test setup. Dự án này cần [tính năng]. Hỏi phần còn thiếu, đề xuất slice/MVP
+> và kiến trúc phù hợp, sau đó implement theo conventions hiện có và báo cáo checks thực chạy.
+
+Core đã có TDD/debug/review. Nếu cần thiết kế UX/Figma, thêm `--capabilities uiux` khi init mới.
+Nếu cần khám phá ý tưởng/MVP/kiến trúc/kế hoạch, thêm `product,architecture,delivery`; không bắt task nhỏ
+tạo đủ tài liệu. Dự án đã cài đổi `.harness/project.json` rồi review update, không re-init với lựa chọn khác.
+Harness không tạo app/framework, cài libraries hoặc cấu hình Figma/native AI host.
+
+## Chọn skill theo việc
+
+| Việc | React/Next.js | React Native/Expo |
+| --- | --- | --- |
+| Route/screen, form, CRUD/search, API và state | `harness-react-nextjs-feature-delivery` | `harness-react-native-screen-delivery` |
+| Test hành vi và luồng | `harness-react-nextjs-behavior-testing` | `harness-react-native-behavior-testing` |
+| Rủi ro chuyên biệt | `harness-react-nextjs-accessible-ui`, `harness-react-nextjs-server-boundaries` khi có Next server | `harness-react-native-offline-sync`, `harness-react-native-device-permissions` khi cần |
+
+`aih skills` liệt kê metadata; `aih skill <id>` đọc một body. AI có thể chọn skill qua description và
+đọc `.agents/skills/<id>/SKILL.md`, không cần bạn gọi từng role. Xem [Skill matrix](skill-matrix.md).
+Skill IDs dưới namespace react-nextjs cũng dùng cho React web; plain React không bị ép chuyển Next.js.
+
+## Dự án mới và maintain
+
+Với maintain, đọc feature tương tự trước: reuse UI public APIs, theme, form schema, client/query keys,
+auth/state/router và test helpers. Không tạo thêm HTTP client, store, navigation container hay wrappers
+khi common hiện tại đáp ứng. Với dự án mới, đề xuất cấu trúc feature và state/data boundaries vừa đủ;
+so sánh các lựa chọn quan trọng trước khi chốt. Ports/adapters, factory hay global state cần vấn đề cụ thể,
+không áp như checklist. Xem [Project conventions](project-conventions.md) và [Solution workflow](solution-workflow.md).
+
+Web: xác định router/version; tách state UI/form/server, xử lý stale responses và pending mutations.
+Next server phải validate/authorize mỗi operation, giữ credentials và private caches đúng boundary.
+Mobile: xác định Expo/bare và platforms; giữ navigation/auth/account boundaries, keyboard/safe areas,
+lifecycle và secure storage. Offline queue/permissions chỉ thêm khi yêu cầu thực tế cần chúng.
+
+## Ví dụ đầu ra
+
+- Web search: route dùng client/query/FormField hiện có; loading/empty/error/latest-result; tests gắn AC,
+  keyboard/focus và build/browser evidence thực có. Không thêm Next.js vào React SPA.
+- Mobile profile: screen dùng navigator/theme/client đã có; validation/save/expiry/back/account changes;
+  JS/native/device matrix phân biệt Android và iOS, ghi rõ checks bị chặn.
+
+Đây là output minh họa, không phải kết quả đã chạy. [Full-stack example](examples/fullstack-web.md) và
+[React Native example](examples/react-native-app.md) liên kết skills vào luồng spec → code → review.
+
+## Kiểm chứng và nguồn
+
+Chạy lint/type/test/build theo scripts thực của ứng dụng. Browser checks phải có browser/server thật;
+mocked component test không chứng minh SSR/authorization. Với native, JS tests không xác minh iOS/Android;
+ghi simulator/device/build result riêng. `aih verify/eval` chỉ xuất checklist/dataset và không chạy chúng.
+Không có trial ứng dụng/browser/native hoặc live-model benchmark trong nâng cấp Harness này.
+
+Đối chiếu official docs theo version dự án (tham khảo ngày 2026-10-12):
+- [React state structure](https://react.dev/learn/choosing-the-state-structure): tránh duplicate/derived state lưu dư.
+- [Next.js testing](https://nextjs.org/docs/app/guides/testing): chọn đúng unit/component/E2E boundary;
+  kiểm tra runner support cho async Server Components.
+- [React Native testing](https://reactnative.dev/docs/testing-overview): tách JS component và native/device evidence.
+- [React Navigation auth flow](https://reactnavigation.org/docs/auth-flow/): chỉ áp dụng khi app đang dùng
+  React Navigation; giữ version-specific auth/back behavior, không mặc định cài router đó.