@manhd_d/ai-harness 0.0.0-stage → 0.6.0

package/docs/documentation-workflows.md

@@ -0,0 +1,71 @@
+# Documentation workflows — developer idea or existing BA documentation
+
+AI Harness intentionally supports **two entry points feeding one engineering pipeline**. The Product capability supplies role contracts, skills and drafts to an authorized AI host; the `aih` CLI never performs conversations, web research, ingestion, writes to Confluence or automatic approval.
+
+## Bắt đầu nhanh — ví dụ đầy đủ
+
+- [Walkthrough A: Từ ý tưởng developer đến spec và PR](examples/idea-driven-project.md): lệnh CLI, prompt thảo luận/research, cách review và chuyển sang OpenSpec.
+- [Walkthrough B: Dự án có BRD/PRD/SRS của BA](examples/document-driven-project.md): đọc đúng nguồn, kiểm tra gap, tránh viết lại tài liệu chính thức và tạo OpenSpec theo approved AC.
+
+Để thử tài liệu chưa merge, cài CLI từ **branch PR #10 đã review** thay vì mặc định `main` (xem [Getting started](getting-started.md)).
+
+## Mode A — Idea-driven (developer → BA/PM/PO)
+
+1. Install with `aih init --capabilities product` (add optional UI/UX/adapters only if needed).
+2. Use `aih skill harness-product-idea-discovery` to instruct the AI host to preserve the original idea, clarify user problem and discuss MVP options iteratively.
+3. Use `aih skill harness-product-product-research` and permitted search tools to support market/competitive/feasibility decisions. Record citations and dates; mark unavailable research as pending.
+4. Draft the **minimum necessary** documentation:
+   - Solo developer/small scope: `aih new-doc idea`, `aih new-doc research` (optional), `aih new-doc prd-lite`.
+   - Larger/product or enterprise scope: `aih new-doc brd`, `aih new-doc prd`, `aih new-doc srs`, `aih new-doc use-cases`, backlog, AC and traceability as needed.
+5. AI proposes and reviews; **developer or explicitly authorized owner** records accepted decisions and approval. Continue discussion when important UNKNOWNs affect scope.
+6. Feed approved requirement IDs and acceptance criteria into `aih new-change <id>` plus the appropriate adapter; a human reviews specs and PRs.
+
+This is not an automatic document-writing command: each `new-doc` simply copies a pinned template into the **consumer** repository. An AI assistant with filesystem permissions must populate the draft; the human reviews.
+
+## Mode B — Document-driven (existing BA sources → engineering)
+
+1. Register official BRD, PRD, SRS, Confluence page URLs/revisions, owners and permission scopes in `docs/product/source-register.md`.
+2. Use the `document-driven` workflow in the installed Product capability to inspect authorized input and build requirements / AC traceability. If an official SRS already exists, do **not** generate a competing one by default.
+3. Create only missing artifacts or project-specific derived docs; identify contradictions/staleness and obtain explicit owner decisions.
+4. Approved source-linked requirements → UI/UX if applicable → OpenSpec change → implementation/testing/PR review. Carry source/version and FR/US/AC IDs through each handoff.
+5. When upstream BA documents change, run change-impact analysis and propose diffs; do not rewrite approved BA sources or code without review.
+
+## Storage and ownership
+
+| Artifact | Canonical location | Notes |
+| --- | --- | --- |
+| Harness roles, skills, workflows, templates | `ai-harness/capabilities/product/` | Versioned framework source; not real customer requirements |
+| Original developer idea and evidence summary | Consumer `docs/discovery/` | Project-owned, Git versioned; `idea.md`, `research.md` |
+| Project product artifacts | Consumer `docs/product/` | BRD/PRD/PRD-lite/SRS/UC/backlog/AC/traceability |
+| Source enterprise Confluence/BA documents | Existing authorized external system | Canonical source; keep URLs/revisions and permission scope, avoid copying confidential content |
+| Technical change specifications | Consumer `openspec/` | OpenSpec design/tasks/delta specs linked to approved requirement IDs |
+| UI designs | Figma or approved system of record | Store screen-to-URL/node ID mapping, not copies of entire design |
+| Large binary documentation | Authorized object storage | Store references rather than large sensitive binaries in Git |
+
+A product spanning many services should ideally have a single product-owned documentation home, with service-local OpenSpec/architecture and links back to approved requirements. If multiple repositories are used, explicitly designate the system of record and prevent parallel editing of copies.
+
+## Metadata and quality
+
+Every derived artifact should identify owner, status (`draft`, `pending-review`, `approved`), version/source revision, review history and stable IDs. Facts from external sources require anchors; AI inferences, proposals and unverified assumptions are labeled separately. Unavailable evidence or approvals remain UNKNOWN/pending; do not invent them.
+
+Review checks: source freshness and access authorization; conflicting statements; missing FR/NFR to story/AC mapping; unsupported quantitative NFR; duplicate IDs; orphaned stories/screens/OpenSpec; missing review decisions; no claims of unexecuted validation. The current `aih verify` emits advisory checks, not executed document verification.
+
+## Confluence export/publishing contract (future host integration)
+
+Confluence is a **publication platform**, not a file type interchangeable with SRS/PRD. For Confluence imports, record space/page ID, URL, version, access class and section links, and reconcile against local derived docs. For exports, prepare Markdown/Confluence-friendly pages and a mapping from stable document ID → Confluence page ID/version. Require explicit target-page selection, write permission, diff preview and human approval before creating/updating pages. Use version checks and refuse unknown concurrent changes; avoid duplicate pages and unapproved overwrites. The CLI does not integrate with Atlassian APIs.
+
+Future permission-scoped indexing/RAG may improve retrieval for very large corpora, but Git/Confluence remains canonical. Do not require an embeddings database to use either mode.
+
+## Example handoff
+
+```text
+Mode: idea-driven (or document-driven)
+Source: IDEA-001 (or SRC-001 revision 5)
+Status: pending-review (until human approval)
+Requirements: FR-001, NFR-001, US-001, AC-US-001-01
+Artifacts: docs/product/prd.md; docs/product/srs.md (if applicable)
+Proposed OpenSpec change: add-expense-categorization
+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
+```

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

@@ -0,0 +1,116 @@
+# 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).
+
+> **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.
+
+## Monetization: tùy chọn business/marketing
+
+Website miễn phí kiếm tiền quảng cáo có thể cài `--capabilities monetization` cùng Astro/React/Next.js. Sau khi xây các tool hữu ích và được phê duyệt về product, workflow của `monetization` xử lý SEO, publisher policy, consent, ad placement, hiệu quả quảng cáo và Page RPM; qua human approval trước mọi thay đổi ad/deploy. Đọc [Monetization](monetization.md) và [Astro + AdSense walkthrough](examples/astro-adsense-microtools.md). Không được giả định AdSense đã duyệt hoặc tự phát sinh traffic/clicks.
+
+## Astro micro-tools: một stack tùy chọn
+
+Website tiện ích nhỏ có thể chọn riêng adapter `astro` để theo hướng static-first và chỉ thêm React Islands, API/Cloudflare Workers hoặc tách Micro Frontend khi có nhu cầu thật. Product/UX vẫn là optional capabilities như các stack khác. Đọc [Astro walkthrough](examples/astro-micro-tools.md). Không cần backend hay Kubernetes cho tool xử lý hoàn toàn trong trình duyệt.
+
+## Hai chế độ bắt đầu
+
+- **Idea-driven:** developer trình bày ý tưởng → thảo luận và nghiên cứu có nguồn → PRD-lite hoặc BRD/PRD/SRS/use cases tùy độ phức tạp → human approval → OpenSpec.
+- **Document-driven:** BA/PO đã có BRD/PRD/SRS/Confluence → lập source register với URL/revision/quyền, gap/traceability → chỉ tạo artifact còn thiếu → human approval → OpenSpec.
+
+Cả hai chế độ đều dùng chung các stage phía dưới và không bắt buộc cài mọi capability. Xem [Documentation workflows](documentation-workflows.md).
+
+## 0. Chọn module và xác định ownership
+
+~~~bash
+cd /path/to/existing-repository
+aih resolve --adapters java-spring,react-nextjs,kubernetes --capabilities product,uiux,devops
+aih init --adapters java-spring,react-nextjs,kubernetes --capabilities product,uiux,devops --dry-run
+aih init --adapters java-spring,react-nextjs,kubernetes --capabilities product,uiux,devops
+aih check
+aih skills
+~~~
+
+Lệnh trên là **ví dụ một repo chứa BE/FE/manifests**; nếu frontend/backend thuộc nhiều repo, `aih init` được chạy tại từng repo và chỉ chọn module phù hợp. `aih resolve` không tự bổ sung module được recommend. Không dùng `--detect` như công cụ quét toàn monorepo.
+
+**Project input:** `AGENTS.md`, `.harness/local.md`, source repo, scope và branch, quyền truy cập nguồn; tạo `change-id` và xác định nguồn của từng artifact.
+
+## 1. Các stage, outputs và human gates
+
+| Stage | Input và việc phải làm | Module / skills & roles | Output / điều kiện bàn giao |
+| --- | --- | --- | --- |
+| **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 |
+| **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** |
+| **7. Delivery** | PR đã review/CI và artifact định danh | DevOps: `ci-cd`, `docker`, `deployment`, `infrastructure`; Kubernetes: workload/Helm/rollout skills | Build provenance, deploy/rollback runbook, staging evidence; **Gate E: approve artifact + production environment** |
+| **Optional: Monetization** | Website/tool hoạt động hợp lệ, có traffic, quyền publisher | `monetization`: `adsense-integration`, `ad-placement-ux`, `seo-growth`, `analytics-revenue`, `publisher-compliance` | Plan ads.txt/consent, ads UX and revenue scenarios; **Gate: owner approves provider/production changes** |
+| **8. Operations** | Authorized release, metrics/logs/traces và runbooks | DevOps: `observability`, `incident-response`; Kubernetes khi liên quan | SLO signals, incident timeline/postmortem, follow-up changes; không tự động thay đổi production |
+
+**Nhớ:** bảng stage sử dụng tên kỹ năng viết gọn; sử dụng [skill-matrix.md](skill-matrix.md) để lấy **ID chính xác** và command `aih skill <name>`. Technical architecture hiện là trách nhiệm của Core + adapter, chưa có capability Architecture chuyên biệt.
+
+## 2. Luồng thực tế qua các handoff
+
+1. **Discover**: BA/PM ghi `SRC-001` từ nguồn có phiên bản và kiểm tra quyền, tạo `BR-001`, `FR-001`, `NFR-001` trong BRD. Không lấy tài liệu ngoài phạm vi để làm prompt.
+2. **Product gate**: PO xác nhận `US-001`, `AC-US-001-01` và trace tới `FR-001`; bản nháp chỉ chuyển sang Ready sau khi người có thẩm quyền chấp thuận.
+3. **Design gate**: UI/UX ánh xạ `US-001` đến screen `SCR-001`, mô tả loading/error/empty/accessibility. Figma chỉ được ghi khi được phê duyệt đúng file/node; giữ node-ID để review.
+4. **Spec gate**: planner và `harness-spec` tạo change (ví dụ `add-customer-api`) mang lại `FR-001`/`AC-US-001-01`, API semantics và test plan. Nếu dùng OpenSpec CLI riêng, chạy `openspec validate add-customer-api --strict` sau khi hoàn thiện TODO.
+5. **Implementation & QA**: từng nhiệm vụ dùng `harness-tdd` và skill adapter phù hợp, bảo vệ tenancy/auth, test failures và DB migration; reviewer kiểm tra diff theo approved AC.
+6. **PR**: branch riêng, PR có change ID, source/spec links, tests thực chạy, tests còn thiếu, plan rollback; không tự merge.
+7. **Release**: DevOps dùng artifact immutable + explicit human production gate; người vận hành hoặc runtime đã cấp quyền mới có thể deploy. Sau đó thu thập latency/errors/traffic/saturation và cập nhật postmortem nếu cần.
+
+**Traceability mẫu (đây là ví dụ, không phải dữ liệu thật):**
+
+~~~text
+SRC-001 (Confluence page, revision)
+  → BR-001 / FR-001 → PRD-001
+  → US-001 / AC-US-001-01
+  → SCR-001 / Figma node (nếu có UI)
+  → openspec/changes/add-customer-api/
+  → source/tests/commit SHA
+  → PR / CI evidence
+  → artifact digest / approved release / observed SLO
+~~~
+
+Project tự sở hữu các file `docs/product/` và cập nhật `traceability.md`. Không có automation nào tự cập nhật trace ID giữa Figma, Jira, code và release.
+
+## 3. Thực thi từ AI IDE theo stage (prompts mẫu)
+
+**Business phase:**
+
+> Đọc AGENTS.md, tài liệu nguồn được phép truy cập và capability Product đã cài. Sử dụng knowledge-analysis → BRD/PRD → stories/AC/traceability. Ghi nguồn và revision cho mọi fact, tách suy luận và quyết định. Tạo draft trong docs/product/ và yêu cầu BA/PO review, không tự approve.
+
+**Design phase (tùy chọn):**
+
+> Dùng các requirement ID đã được phê duyệt, lập UX flow và screen inventory với trạng thái lỗi/rỗng/loading. Chờ duyệt trước mọi thay đổi Figma; chỉ thao tác trên file được cấp quyền. Ghi screen-to-node mapping.
+
+**Implement phase:**
+
+> Dựa trên approved OpenSpec change, chọn chính xác Core/adapter skill cần dùng; thực hiện test-first slice nhỏ, không đụng file ngoài scope. Báo kết quả tests đã chạy, cập nhật requirement-to-test evidence, mở PR để review, không tự merge.
+
+**Release phase:**
+
+> Lập CI/CD, container, deployment và rollback plan với các signal có thể đo. Chỉ đề xuất thao tác production; không deploy/rollback nếu chưa có phê duyệt riêng cho artifact và environment.
+
+## 4. Khi thay đổi không cần cả vòng đời
+
+- **Bugfix nhỏ:** đọc [bugfix workflow](../core/workflows/bugfix.md), tái hiện lỗi → regression test → patch → PR. Không tự tạo BRD/PRD mới khi không cần.
+- **Refactor/upgrade:** theo [upgrade workflow](../core/workflows/upgrade.md), inventory tương thích, baseline và rollback, giữ public contracts.
+- **Backend-only:** bỏ UI/UX; dùng Product nếu cần xác nhận nghiệp vụ, Java/AI adapter khi implement.
+- **Mobile-only:** dùng React Native adapter và UI/UX; không cài Kubernetes cho app di động chỉ vì cần release.
+- **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
+
+~~~bash
+aih verify --scope all
+aih eval --scope all
+aih check
+~~~
+
+`aih verify` **không chạy** lint/build/test; `aih eval` tạo report chưa chấm, không chạy model. Chạy các lệnh build/test từ repo bằng công cụ tương ứng, đính kèm evidence và run scenarios với mô hình thật nếu có nhu cầu. Chỉ khi đã ghi điểm có căn cứ mới dùng `aih eval --scope all --report /path/to/report.json` để tổng hợp.
+
+**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).

package/docs/examples/ai-rag-service.md

@@ -0,0 +1,60 @@
+# Walkthrough 4 — Python AI/RAG service có kiểm soát truy cập
+
+**Tình huống giả định:** API hỏi đáp tri thức doanh nghiệp (Confluence/PDF) với quyền theo tenant/nhóm, citations, tool calling có giới hạn và AI quality gates. Nếu tài liệu ít, **không cần RAG**; trước tiên đo chất lượng retrieval và quyết định phương án phù hợp.
+
+## 1. Init theo phạm vi
+
+~~~bash
+cd /path/to/existing-python-ai-service
+aih resolve --adapters ai-python --capabilities product,devops
+aih init --adapters ai-python --capabilities product,devops --dry-run
+aih init --adapters ai-python --capabilities product,devops
+aih check
+aih skills
+~~~
+
+Nếu AI application triển khai trên Kubernetes, cân nhắc thêm adapter `kubernetes`. Các framework Python, vector DB và API key **không** được `aih` cài/cấp. Dùng `java-spring` thêm nếu service thực tế viết bằng Spring Boot thay vì Python; `ai-python` không phải bắt buộc cho mọi AI application.
+
+## 2. Business/data intake và security gate
+
+- BA/PO ghi nguồn tài liệu, owner, tenant/scope, revision, retention, consent và loại dữ liệu nhạy cảm; output là `source-register` và các `FR/NFR/AC` được duyệt.
+- Design nêu rõ boundary: caller identity → authorized retrieval filter → chunk/citation → grounded answer, deny-by-default và audit metadata tối thiểu.
+- Test scenarios: tenant A tìm thấy document B có độ giống cao vẫn **không lộ nội dung B**, missing access claim, prompt injection trong retrieved text, stale sources, no-evidence abstention, latency/cost budgets.
+- Không upload tài liệu bí mật vào eval fixtures; dùng synthetic corpus với auth giả lập.
+
+## 3. Spec & implementation
+
+~~~bash
+aih new-change authorized-knowledge-search
+aih skill harness-spec
+aih skill harness-tdd
+aih skill harness-ai-python-rag-access
+aih skill harness-ai-python-tool-safety
+aih skill harness-ai-evaluation
+~~~
+
+- `rag-access`: filter ACL **trước khi tài liệu được trả về model**, kết quả có source chunk/revision, giữ cross-tenant isolation; không dựa vào prompt "đừng tiết lộ".
+- `tool-safety`: schema, allowlist, scoped credentials, bounded timeout/token/cost, human approval cho mutation, test denied actions.
+- `harness-ai-evaluation`: versioned datasets, recall/groundedness/citation accuracy, denied leakage, regressions, latency/cost. Define measurement trước khi thử provider.
+- Với project có nhiều trang tài liệu mới cần index hoặc phân vùng semantic search, tách pipeline ingestion/retention và ACL ở storage/retriever. Mô tả nguồn nào thực sự truy cập được.
+
+## 4. Tests và LLM evaluation
+
+~~~bash
+# Thực hiện ở môi trường disposable sau khi xác nhận tool/test deps của repo:
+# python -m pytest  # chỉ khi dependency pytest đã cài và repo sử dụng nó
+aih verify --scope all
+aih eval --scope all
+aih check
+~~~
+
+`aih eval --scope all` cung cấp cases/report chưa chấm; chạy model/tập dữ liệu kiểm thử **bên ngoài CLI**, ghi trace đã redact và reviewer điền report. Báo real pass/fail; **không dùng synthetic score của unit test như bằng chứng model đạt chất lượng**. Kịch bản cross-module DevOps xuất hiện nếu chọn và phù hợp.
+
+## 5. PR → deployment/operations
+
+- PR chứa OpenSpec change, ACL tests, retrieved citation evidence, eval threshold results, cost/latency assumptions, prompt-injection defense và failures.
+- `harness-devops-ci-cd` / `harness-devops-deployment` lên kế hoạch artifact/staging/rollback. `harness-devops-observability` nêu access-deny counters, retrieval failures, token/cost, latency, errors, SLO.
+- Secrets thuộc secret manager/runtime, không hardcode vào prompts, report hoặc Git. Production deploy chỉ khi có authorization riêng.
+- Sau rollout, theo dõi drift source revision, tenant leak alerts và versioned dataset regressions.
+
+**Handoff:** approved data-use rules → retrieval design → OpenSpec → ACL-enforced RAG and tool wrappers → human-reviewed model evidence → PR → controlled deployment/monitoring.

package/docs/examples/astro-adsense-microtools.md

@@ -0,0 +1,80 @@
+# Walkthrough — Astro micro-tools with AdSense monetization
+
+Scenario: a free website with QR Generator, JSON Formatter and Image Compressor, aiming for **legitimate search traffic + advertising**. No guarantee of publisher approval, SEO ranking or earnings. Build useful tools first; ad placement is a secondary concern.
+
+## 1. Prerequisites and selection
+
+Node.js 22+, Git, an existing Astro app, and an `aih` CLI bundle including the optional monetization capability. If you need an Astro starter use the upstream Astro CLI separately; Harness installs only rules/skills.
+
+```bash
+cd /path/to/astro-utilities
+aih resolve --adapters astro --capabilities product,uiux,monetization
+aih init --adapters astro --capabilities product,uiux,monetization --dry-run
+aih init --adapters astro --capabilities product,uiux,monetization
+aih check
+aih skills
+aih skill harness-astro-project-architecture
+aih skill harness-monetization-adsense-integration
+aih skill harness-monetization-seo-growth
+```
+
+Product/UIUX are optional; the smallest setup is `aih init --adapters astro --capabilities monetization`. An existing installation must update `.harness/project.json` and use `aih update` instead.
+
+## 2. Start with product and SEO, no ad code
+
+Example route layout:
+
+```text
+src/pages/index.astro
+src/pages/tools/qr-generator.astro
+src/pages/tools/json-formatter.astro
+src/pages/tools/image-compressor.astro
+src/lib/qr/
+src/lib/json/
+src/lib/image/
+docs/monetization/
+```
+
+First ask the AI host to inspect the project and plan tool-specific pages with useful original content, accessible forms/error handling and local processing. Example prompt:
+
+> Read AGENTS.md plus harness-astro-project-architecture and harness-monetization-seo-growth. Plan three public micro-tools focused on real search intent, good mobile UX and static/browser-only processing. Separate verified keyword data, inference and unknowns. Do not add backend, database, web scraping, advertising scripts, ad account credentials or mock visitor counts. Propose routes, validation and meaningful descriptions; request my approval before code changes.
+
+If Product is selected, use `aih new-doc prd-lite` for the product scope if needed. The monetization documents are **not** supported by `aih new-doc`; review and copy named installed templates into project-owned `docs/monetization/` once with a permitted filesystem tool.
+
+## 3. Publisher readiness and policy review
+
+Check the actual AdSense account/site approval status, original site content, user trust pages, privacy disclosures, intended visitors and third-party rights. Use `harness-monetization-publisher-compliance`. Do not publish provider tags or claim Google approval without account access/owner authorization.
+
+Example prompt:
+
+> Read installed monetization skills and workflow site-to-adsense. Create or complete docs/monetization/site-monetization-plan.md and privacy-consent-checklist.md from supplied evidence. Read current Google policies if web is enabled, recording URLs and check dates. Confirm which visitors need a certified CMP and flag gaps. Do not assume I already have an AdSense account or a publisher ID, and do not publish anything externally.
+
+## 4. Review slots and add authorized ads only after approval
+
+Draft mobile/desktop page designs with safe ad placement around, **not inside**, Generate/Download flows. Avoid accidental taps, misleading download-like labels and layout shift; confirm tool works when ads are blocked/not filled or required consent is absent.
+
+Before production, confirm provider approval/permissions, account-supplied `ads.txt` content, deploy root path `/ads.txt`, correct CMP choice and actual deployment environment. Use `aih skill harness-monetization-ad-placement-ux`. For `ads.txt`, copy **only** a real seller line from the publisher account; Google highly recommends but does not universally require ads.txt.
+
+Review actual responsive pages, consent choices, script loading, privacy and accessibility. Test production build using **scripts that exist** in the Astro project. `aih verify --scope all` is only advisory and no cloud/Google writes occur through CLI.
+
+## 5. Measure and improve when real data exists
+
+After launch and account authorization, use analytics/Search Console exports and provider earnings for the **same time window**; compare legitimate organic traffic by tool, Page RPM, cost of hosting/API and qualitative task completion. If access is absent, label metrics UNKNOWN and use explicit assumptions rather than fabricated earnings.
+
+Example prompt:
+
+> Read harness-monetization-analytics-revenue. Using only authorized metric exports with source dates, prepare docs/monetization/analytics-report.md. Separate actual earnings from scenarios; calculate Page RPM only if earnings and page views share a window, list hosting/API costs and propose one measurable SEO/UX improvement with a stop rule. No growth hacks that generate clicks or fake ad impressions.
+
+```bash
+aih verify --scope all
+aih eval --scope all
+aih check
+```
+
+`aih eval` emits an unscored evaluation dataset; it does not test Google compliance or call a model. Human review, real site/browser tests and publisher console observations are separate activities.
+
+## 6. Scaling decisions
+
+Keep a single Astro website with many routes until independent teams/deployments or very different runtimes require an MFE split. Monetization is stack-independent and follows your site/business across Astro/React changes. Never use MFE, Kubernetes or backend services simply because the website earns ad revenue.
+
+Review [Monetization guide](../monetization.md), [Astro micro-tools](astro-micro-tools.md) and [Monetization capability](../../capabilities/monetization/README.md) for reusable procedures.

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

@@ -0,0 +1,125 @@
+# Walkthrough — Astro micro-tools, SEO, React Islands and future MFE
+
+**Tình huống:** bạn muốn xây website gồm nhiều công cụ nhỏ như QR generator, JSON formatter, image compressor và có thể thêm các tool phức tạp hơn. Mục tiêu là deploy nhẹ, SEO tốt và có đường nâng cấp lên MFE *nếu thực sự cần*, không phải triển khai micro frontend từ ngày đầu.
+
+## 1. Chuẩn bị Astro project
+
+Cần Node.js 22+, Git, một repo Astro đã tạo hoặc đã checkout và `aih` CLI bản nguồn chứa Astro adapter. Nếu chưa có Astro repo, tạo bằng **Astro CLI chính thức** rồi chọn TypeScript theo nhu cầu; lệnh sau là ví dụ tương tác, phải kiểm tra phiên bản hướng dẫn hiện hành:
+
+```bash
+npm create astro@latest
+cd /path/to/astro-project
+# Nếu sử dụng React islands, cài @astrojs/react theo tài liệu Astro
+# npx astro add react
+```
+
+Không cần React để viết đa số tool cơ bản. `aih` là bộ hướng dẫn AI, **không** tạo Astro source code và không cài các dependencies này.
+
+## 2. Cài Harness vào repo
+
+```bash
+aih resolve --adapters astro --capabilities product,uiux
+aih init --adapters astro --capabilities product,uiux --dry-run
+aih init --adapters astro --capabilities product,uiux
+aih check
+aih skills
+aih skill harness-astro-project-architecture
+aih skill harness-astro-seo
+```
+
+`product,uiux` đều **tùy chọn**; dự án chỉ cần Core + Astro có thể dùng `aih init --adapters astro`. Trong repo *đã cài Harness*, chỉnh `.harness/project.json` để thêm `astro`, sau đó `aih update --dry-run`, `aih update`, `aih check`. Không chạy lại init với cấu hình khác khi có file snapshot.
+
+Để thử detector an toàn:
+
+```bash
+aih detect
+aih init --detect --dry-run
+```
+
+Detector chỉ đọc dependencies của `package.json` ngay trong thư mục hiện tại. `astro` được nhận diện từ dependency tên `astro`; `react-dom` do React islands **không tự động** khiến detector thêm `react-nextjs` nếu không có `next`. Nếu app dùng `next` thật hoặc muốn đồng thời cài cả hai adapter, có thể chọn thủ công.
+
+## 3. Tổ chức tools kiểu static-first
+
+```text
+src/
+  layouts/
+    ToolLayout.astro
+  pages/
+    index.astro
+    tools/
+      qr-generator.astro
+      json-formatter.astro
+      image-compressor.astro
+  components/
+    ImageEditor.tsx      # chỉ khi có React thực sự cần thiết
+  lib/
+    qr/
+      validation.ts
+      encode.ts
+    image/
+      transform.ts
+```
+
+Một công cụ đơn giản nên chạy ngay trên trình duyệt, không gửi dữ liệu riêng tư lên server. Đặt validation và functions riêng, tránh tool này import trạng thái tool khác. Các API có quyền/secret mới cần Worker/server xử lý theo authorization rõ ràng.
+
+Prompt ví dụ trong Codex/IDE/Work đã được cấp quyền repo:
+
+> Đọc AGENTS.md và skill harness-astro-project-architecture + harness-astro-seo. Tôi muốn làm 3 tools: QR generator, JSON formatter và image compressor. Lập kế hoạch UI, route và ưu tiên xử lý dữ liệu ngay trên trình duyệt. Kiểm tra scripts/dependencies trước khi sửa, không tự cài backend, database, auth hay React. Tạo vertical slice cho QR generator với validation, trạng thái lỗi và accessible keyboard labels. Sau khi tôi duyệt spec, triển khai và chạy các test/build scripts thực có. Trả về diff và kết quả thực tế, không tự deploy.
+
+## 4. Thêm React Islands khi cần
+
+Chỉ hydrate React cho phần có tương tác đủ phức tạp. Nếu đã cài `@astrojs/react` phù hợp, ví dụ nhúng React component vào Astro page:
+
+```astro
+---
+import ImageEditor from '../../components/ImageEditor.tsx';
+---
+
+<h1>Image Editor</h1>
+<ImageEditor client:visible />
+```
+
+Chọn `client:load` nếu cần tương tác ngay ở phần đầu trang, `client:visible` khi tool nằm dưới fold; kiểm tra timing/hydration trong browser. Đừng nhúng React cho toàn bộ landing page chỉ để có một nút.
+
+**Islands không phải MFE.** Hiện tại tất cả trang và island của Astro project vẫn build/deploy cùng nhau.
+
+## 5. Cloudflare và deployment
+
+- Với các tool hoàn toàn chạy trong browser: build Astro ra static files, phục vụ từ CDN/host hỗ trợ static; **không cần Cloudflare Workers** chỉ để chạy website.
+- Nếu cần API dùng secrets, xử lý server hoặc điều phối dữ liệu được phép truy cập: đánh giá Cloudflare Workers và adapter/runtime theo **phiên bản Astro hiện dùng**. Với dự án mới, kiểm tra tài liệu Cloudflare Workers chính thức trước khi chọn thiết lập.
+- Không để private keys trong `PUBLIC_*` biến môi trường hoặc phía frontend. Nếu tính năng fetch URL của người dùng, phải xét SSRF, redirect, private IP, quotas và quyền nội dung; không triển khai arbitrary URL proxy thiếu kiểm soát.
+- `aih verify` chỉ đưa ra checklist, không chạy build. Chỉ chạy các lệnh **thực có trong package.json**, ví dụ `npm run build`, `npm run check` nếu có, cùng browser UX tests. Con người duyệt trước bất kỳ cloud deployment/DNS thay đổi nào.
+
+## 6. Scale lên Micro Frontend khi cần
+
+**Giai đoạn 1:** một Astro repository, các route/tool độc lập.
+
+**Giai đoạn 2:** các React Islands hoặc shared UI packages được phép dùng, vẫn trong một build/deploy. Có thể dùng monorepo khi cần quản lý code dùng chung, nhưng chưa phải MFE.
+
+**Giai đoạn 3:** khi một tool cần team, release cadence hoặc runtime riêng, tách **một route** (ví dụ `/tools/image-editor`) ra ứng dụng deploy riêng qua routing/proxy phù hợp. Kiểm tra domain, deep links, assets, CSP/cookies/auth, analytics, SEO/canonicals, lỗi và rollback trước cut-over. Không mặc định Module Federation.
+
+Prompt ra quyết định:
+
+> Dựa vào docs, ownership và deploy hiện tại, đánh giá tách image-editor thành MFE hay giữ Astro Island. So sánh khả năng deploy độc lập, SEO, routing, caching, cookie/auth, bundle và chi phí vận hành. Chỉ đề xuất kiến trúc sau khi có nhu cầu thực; ghi ADR/approval và migration steps, chưa tự triển khai.
+
+## Optional: AdSense revenue model
+
+Nếu mục tiêu website là quảng cáo, có thể cài capability `monetization` bên cạnh adapter Astro. Dự án đã cài hãy cập nhật `.harness/project.json` và dùng `aih update` sau khi review. Đọc [Astro + AdSense walkthrough](astro-adsense-microtools.md) để phân biệt build tool với publisher compliance, đặt quảng cáo tránh Generate/Download và đo Page RPM. `aih` không tự nhúng script, tạo ad account hay cam kết doanh thu.
+
+## 7. Test và PR review
+
+```bash
+aih verify --scope all  # advisory, không thực thi test
+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.
+
+## Tài liệu chính thức
+
+- [Astro islands và framework components](https://docs.astro.build/en/guides/framework-components/)
+- [Astro + Cloudflare deployment](https://docs.astro.build/en/guides/deploy/cloudflare/)
+- [Astro sitemap integration](https://docs.astro.build/en/guides/integrations-guide/sitemap/)
+- [Astro adapter](../../adapters/astro/README.md)
+- [Full SDLC](../end-to-end-workflow.md)

package/docs/examples/document-driven-project.md

@@ -0,0 +1,62 @@
+# Walkthrough B — dự án đã có tài liệu BA/Confluence → OpenSpec → code
+
+Dùng chế độ **Document-driven** cho dự án doanh nghiệp hoặc bất kỳ codebase nào đã có BRD/PRD/SRS/Confluence/Jira. Tài liệu gốc tiếp tục do hệ thống/chủ sở hữu hiện tại quản lý; AI **không cần tạo lại BRD hay PRD** chỉ để code.
+
+## 1. Cài Harness trong repository hiện có
+
+Ví dụ một backend Spring Boot đã được checkout. Cần Node.js 22+, Git và `aih` đã cài từ bản nguồn được review.
+
+```bash
+cd /path/to/existing-spring-project
+git switch -c feat/customer-search
+aih init --adapters java-spring --capabilities product --dry-run
+aih init --adapters java-spring --capabilities product
+aih check
+aih skills
+aih skill harness-product-knowledge-analysis
+```
+
+Nếu repository **đã cài** Harness, chỉnh `.harness/project.json` nếu cần thêm capability rồi `aih update --dry-run`, `aih update`, `aih check`. Không thực hiện init chồng lên bộ cài do dự án đã quản lý.
+
+## 2. Cung cấp tài liệu có quyền truy cập
+
+Chia sẻ **đường dẫn/trang được cấp phép** (Confluence, Git files) hoặc export được phép. Agent phải ghi ID trang, URL, revision, owner, phạm vi quyền và approval status; không suy diễn rằng mọi trang đều mới nhất hoặc đã được duyệt.
+
+```bash
+aih new-doc source-register
+aih new-doc traceability
+```
+
+Prompt dùng với AI host có quyền đọc project và nguồn:
+
+> Đọc AGENTS.md, Product workflow document-driven và các tài liệu BA tôi cho phép. Tác vụ: triển khai tìm kiếm khách hàng có phân quyền. Đầu tiên xác định BRD/PRD/SRS nào là nguồn chuẩn, ghi source IDs, URL và phiên bản trong docs/product/source-register.md. Liệt kê FR/NFR/US/AC liên quan, kiểm tra mâu thuẫn và thông tin còn thiếu. Không bịa nội dung chưa đọc được, không viết lại tài liệu BA đã approved. Hoàn thiện traceability draft và đưa tôi review trước khi tạo technical spec.
+
+Nếu Confluence chưa kết nối trong AI host, agent phải báo là **không thể đọc**, yêu cầu export/phạm vi được phép; `aih` không tự truy cập Confluence.
+
+## 3. Gap analysis và phê duyệt
+
+- Tài liệu BA có sẵn và hợp lệ: chỉ tạo `source-register`, `traceability`, decision log hoặc các artifact thiếu.
+- SRS chưa có hoặc thiếu chi tiết thực sự: có thể chạy `aih new-doc srs` và `aih new-doc use-cases`, nhờ AI điền **draft** từ những requirement đã xác nhận.
+- Có source conflict, thiếu AC hoặc yêu cầu chưa rõ: AI ghi UNKNOWN và chờ BA/PO hoặc chủ dự án có quyền quyết định; không tự gắn nhãn approved.
+
+## 4. Tạo OpenSpec từ phạm vi đã duyệt
+
+```bash
+aih new-change customer-search
+# Điền TODO trong openspec/changes/customer-search/ rồi review.
+```
+
+Prompt handoff:
+
+> Dựa vào các requirement IDs đã approved và source revisions trong docs/product/traceability.md, dùng core harness-spec và skill adapter java-spring phù hợp để lập proposal/design/tasks/spec cho customer-search. Chỉ mô tả hành vi có bằng chứng, test cases gồm authorization deny-other-tenant, input validation, no-result/error cases nếu phù hợp với yêu cầu nguồn. Đánh dấu NFR còn thiếu; không tự duyệt. Sau khi tôi chốt spec, implement trên branch hiện tại, chạy test thực tế, tạo PR để review và không tự merge/deploy.
+
+Nếu dùng OpenSpec upstream thì pin và cài CLI riêng, sau đó có thể chạy `openspec validate customer-search --strict` khi bản nháp đã hoàn thiện.
+
+## 5. Lưu trữ và bảo mật
+
+- Tài liệu BA chính thức vẫn ở Confluence/Drive/repo được chỉ định; trong repository kỹ thuật giữ URL/revision và những tài liệu dẫn xuất được phép lưu.
+- `docs/product/` chứa traceability, source register và các bản draft phục vụ dự án; `openspec/` chứa technical spec và change liên kết FR/US/AC.
+- Không đưa tài liệu khách hàng mật, secrets hoặc export nguyên bản vào repo không được phép. Không publish Confluence hay sửa PRD gốc nếu chưa được phê duyệt.
+- Khi tài liệu BA đổi revision, dùng change-impact analysis và review delta thay vì ghi đè code/spec.
+
+**Giới hạn:** skills và role contracts không tự biến thành agent runtime; CI/test/OpenSpec validation thực tế phải do host/IDE và công cụ liên quan chạy, có kết quả kiểm chứng.

package/docs/examples/fullstack-web.md

@@ -0,0 +1,80 @@
+# Walkthrough 2 — Full-stack Spring Boot + Next.js + Product + Figma
+
+**Tình huống giả định:** xây hành trình tạo ticket (backend Spring Boot + frontend Next.js) trong **một repo chứa cả hai module**, bắt đầu từ product idea hoặc Confluence. Đây là runbook minh họa; không có ứng dụng nào được tạo tự động.
+
+## 1. Chọn modules cho repo
+
+~~~bash
+cd /path/to/existing-fullstack-repository
+aih resolve --adapters java-spring,react-nextjs --capabilities product,uiux,devops
+aih init --adapters java-spring,react-nextjs --capabilities product,uiux,devops --dry-run
+aih init --adapters java-spring,react-nextjs --capabilities product,uiux,devops
+aih check
+aih skills
+~~~
+
+Chỉ thêm `kubernetes` nếu repo cũng sở hữu manifest/chart. Nếu backend/frontend nằm **hai Git repository** độc lập, cài `aih` riêng từng repo theo stack tương ứng, liên kết hai PR bằng cùng change ID; không cố ép cả hai vào một Git root. `aih detect` không quét lồng `apps/web` / `services/api`.
+
+## 2. Product discovery và gate
+
+~~~bash
+aih new-doc brd
+aih new-doc prd
+aih new-doc backlog
+aih new-doc acceptance-criteria
+aih new-doc traceability
+aih skill harness-product-knowledge-analysis
+aih skill harness-product-brd-generation
+aih skill harness-product-user-stories
+aih skill harness-product-document-review
+~~~
+
+BA xác nhận nguồn/timestamps; PM chốt mục tiêu, PO duyệt `US-001`/`AC-US-001-01`; requirements reviewer kiểm tra truy vết. Confluence là **nguồn dữ liệu**, không cấp quyền tự động. Các draft chưa phê duyệt không được tự đánh dấu Approved.
+
+## 3. UI/UX & design gate
+
+~~~bash
+aih skill harness-uiux-user-flow
+aih skill harness-uiux-screen-planning
+aih skill harness-uiux-design-system
+aih skill harness-uiux-figma-design
+aih skill harness-uiux-design-review
+~~~
+
+Từ approved PRD/AC, lập screen inventory (create, success, validation error, permission denial, loading, empty), responsive/keyboard/accessibility states. Nếu UI/UX cần trích nguồn riêng, dùng `harness-uiux-requirements-analysis` nhưng **không tạo lại ID cạnh tranh với Product**.
+
+Figma MCP phải được cấu hình ngoài `aih`; **Gate A:** người phụ trách duyệt flow/screen trước quyền ghi Figma; **Gate B:** duyệt review findings và Figma nodes trước implementation. Không có kết nối Figma thì bàn giao screen specs bằng Markdown, không khẳng định đã tạo frames.
+
+## 4. Spec → implementation
+
+~~~bash
+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-accessible-ui
+aih skill harness-react-nextjs-server-boundaries
+~~~
+
+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.
+
+Ví dụ kiểm tra **chỉ nếu repo có tương ứng**:
+
+~~~bash
+# Backend, chạy từ module sở hữu Maven wrapper:
+./mvnw test
+# Frontend, chạy từ module Next.js có script:
+npm test
+npm run build
+~~~
+
+Không coi dòng lệnh minh họa là bằng chứng đã chạy. Với multi-repo, mỗi repo có CI, owner và PR riêng.
+
+## 5. PR → release & feedback
+
+- Review dùng `harness-review`, `test-engineer`, `security-reviewer`, trace `AC → API/FE tests → PR` và Figma node IDs.
+- `aih verify --scope all` và `aih eval --scope all` **chỉ trả kế hoạch/dataset**, không tự chạy tests.
+- `harness-devops-ci-cd` + `harness-devops-deployment` cung cấp rollout/rollback plan, `harness-devops-observability` chỉ rõ SLI/SLO/alert.
+- Staging/production cần phê duyệt environment và artifact riêng; user hoặc operator quyết định merge/deploy.
+
+**Deliverables:** approved PRD/AC → user-flow/screen-spec/Figma reference → OpenSpec change → backend + frontend diff/tests → reviewed PR(s) → telemetry evidence.