# Multi-agent SOLUTION_ERP — Master Coordination Guide (12-agent)

> **Architecture:** 12 sub-agents **all-inherit top-tier (Harness-8 2026-06-16 — thay thế two-tier Harness-4)** + em main **Fable 5 (1M) Max** coordinator — **10 product/quality** (7 core + frontend-designer pink S47 + database-agent read-advisory S52 + 📄 office-document S107) + **2 monitor INFORM-only** (`tooling-auditor` H1 + `harvest-curator` H2, 2026-06-07 Harness 1). Tier: **toàn bộ 12 sub `model: inherit`** (ăn top-tier model của lead — **runtime = per-session (Fable ↔ Opus, outage-driven; Fable DOWN → H5-fallback Opus tự-kích revert-free KHÔNG sửa frontmatter, Fable UP → tự về); lịch-sử flip-chain đầy-đủ (S98→nay) = canonical [`docs/STATUS.md` §Sub-agents]** (🔴 S106 gộp 1-chain per anh-confirm — reader này KHÔNG enumerate/cập-nhật mỗi flip; BƯỚC 0.6 probe mỗi phiên xác-định runtime SỐNG, per-session KHÔNG steady-state) · effort **Max** (env machine-wide). SE KHÔNG có lớp helper/gopher rẻ (cả 12 đều substantive memory-bearing → cả 12 lên inherit). *(Trước H8: 4 promote inherit + 7 demote pin `claude-opus-4-8` — lịch sử ở Upgrade 2026-06-10 + S66 dưới.)*
> **Upgrade S52 (2026-06-08 — AI_INFRA broadcast `2026-06-08-Agent-database-codebase-agents`):** **+database-agent (read-advisory DB specialist, floor DB1–DB11)** — schema/query/migration-design-review/perf/concurrency (DB11 RowVersion vá lost-update S43). Tailor READ-tier (implementer-backend vẫn author) · color OMIT (8 standard hết) · `store_memory` strip. `codebase-agent` = **SKIP n-a** (investigator-codebase đã cover grep/audit + `csharp-lsp` Windows no-op). ✅ **verified-runtime** — spawned OK S53 (first real spawn, caught Mig 46 committed-but-unapplied-local drift) + S56 2× (pre-golive-verify schema-stream + golive-harden design+review). DB11 lost-update fix landed S56 (atomic ExecuteUpdate + Serializable tx, gotcha #58).
> Pattern: Anthropic Building Effective Agents orchestrator-workers + Cognition "writes single-threaded" hybrid + post-deploy automated watchdog.
> **Upgrade S39 (2026-05-29):** 4→7 agent (split investigator + implementer, +test-specialist) + budget +50% + 5 RAG MCP per agent. Reference BVAAU 7-agent config (adapted, NOT copied — SOLUTION_ERP 2-FE-app fit + 6 skill proven battle-test 38 session). Prior: S20t12 initial 3 + S21t1 +cicd-monitor.
> **Upgrade S47 (2026-06-02):** **+frontend-designer (8th sub, pink)** — FD1–FD10 visual-verification design floor (forked AI_INFRA canonical, broadcast `Agent-frontend-designer-floor`). + **`store_memory` STRIPPED khỏi MỌI sub → lead = sole RAG-writer** (broadcast `Memory-store-memory-strip-global`); sub ghi finding → MEMORY.md (file). adap-reports: `docs/governance/adap-reports/`.
> **Upgrade 2026-06-07 (Harness 1·2·3 adopt — AI_INFRA broadcast):** **+2 monitor sub INFORM-only** `tooling-auditor` (H1 tooling/docs-freshness 4-mặt) + `harvest-curator` (H2 harvest-integrity 5-trục) → roster 8→10, **TÁCH BIỆT** per anh-mandate (H1≠H2 "hay quên+nhầm"). + **wave-folder memory-isolation** (Harness 2 — `hmw.js` wave-mode + `.claude/workflows/wave-*/` gitignored, B1–B6). + **email channel** `broadcasts/` (Harness 3 — cross-project comms, self-id=`se`). KHÔNG copy-paste AI_INFRA — tailor SE roster/stack.
> **Upgrade 2026-06-10 (Harness-4 two-tier model — AI_INFRA broadcast `harness-4-model-tier-promotion` + `model-fable-5-max`):** lead = **Fable 5 (1M) Max** (user-level machine-wide, SE không project-pin) · sub two-tier theo tiêu chí H4.3 (a gate≥writer · b verdict-nuôi-quyết-định · c chống-rubber-stamp · d 1M-thật): **promote 4 giữ `inherit`** (reviewer·investigator-codebase·database-agent·harvest-curator) + **demote 7 pin `claude-opus-4-8`** (full-id no-suffix — gotcha #37 cấm `[1m]`; runtime resolve `[1m]` 1M trên máy chung per AI_INFRA s20). `hmw.js` tier-map H4.5 (role-less → `'opus'` · per-task `tier:'fable'|'opus'` override). Email-back AI_INFRA H4.7 BẮT BUỘC. Justification per-vị-trí: adap-report `2026-06-10-Governance-harness-4-model-tier-promotion.md`.
> **Upgrade S63 (2026-06-15 — Harness-5 + 6 adopt):** **H5 model-fallback** — ⚠️ Fable 5/Mythos 5 **suspended 2026-06-12 no-ETA** → lead SE tạm **Opus 4.8 (1M) Max** (promote `inherit` tự theo → two-tier collapse single-tier Opus; demote-pin giữ; **revert-FREE** khi Fable về: đổi lead lại + spawn-test). KHÔNG sửa frontmatter · external-outage blameless KHÔNG RCA · session-start BƯỚC 0.6 check. **H6 governed-ultracode** — mode-ON: substantive task TỰ chạy HMW (KHÔNG đợi keyword "workflow"); workflow-agent default = **inherit lead** (`hmw.js` role-less `'opus'`→inherit) · role-fidelity (agentType ∈ VALID_ROLES) + memory-fidelity (memoryDelta→đúng agent-memory single-writer) ĐÃ sẵn từ HMW-engine. adap-report `2026-06-13-Governance-harness-5-...` + `2026-06-15-Agent-harness-6-...`.
> **Upgrade S64 (2026-06-15 — Harness-7 writing-quality adopt):** sàn chất lượng viết **hướng ra ngoài** (email · broadcast · adap-report · tài-liệu-sister · **câu trả lời lead cho anh**) phải tiếng Việt rõ nghĩa, câu hoàn chỉnh, đủ dấu câu, đúng ngữ pháp (O1); nội bộ giữ lối nén §6.4/§6.5 (O2 — bất đối xứng); reviewer +**Category 6** writing-quality (O3, verified-pending-restart). Rule canonical `docs/rules.md §1.1`. adap-report `2026-06-15-Governance-harness-7-writing-quality.md`. body-hash `a4580ea9…` verified-MATCH (lesson gotcha #61: verify body-hash PHẢI đọc UTF-8 tường minh, PS5.1 default mis-decode tiếng Việt → false-mismatch).
> **Upgrade S66 (2026-06-16 — Harness-8 all-inherit + workflow-fastest adopt):** 🔴 BẮT BUỘC (anh-chốt, mọi sister; chất lượng trên chi phí). **H8.1** — toàn bộ 11 sub-agent có memory → `model: inherit` (ăn top-tier lead), **GỠ cơ chế demote two-tier của Harness-4** (7 sub pin `claude-opus-4-8` đã flip `inherit`: 2 implementer · test-specialist · cicd-monitor · investigator-api · frontend-designer · tooling-auditor; 4 đã-inherit giữ nguyên reviewer·investigator-codebase·database-agent·harvest-curator). SE KHÔNG có helper/gopher rẻ để chừa → cả 11 lên inherit. Escape-hatch per-task `tier:'opus'` (hmw.js) GIỮ cho sweep/cost. **H8.2** — chạy workflow nhanh nhất: **song song tối đa + xuất nhanh + lead auto-HMW** cho task substantive (theo H6) — "nhanh" = parallelism, **KHÔNG phải hạ model**. **Caveat (trung thực):** runtime HIỆN KHÔNG đổi (inherit = Opus 4.8 1M vì Fable suspended H5 — trùng two-tier đã collapse); khác biệt thật khi Fable về (cả đội tự lên Fable 5 không sửa frontmatter) + H5.6 restore gọn hơn (chỉ đổi lead). Frontmatter no hot-reload → **executed-file → runtime-verified S98** (2026-07-02 Fable-restore: inherit-chain spawn-test ×2 self-report `claude-fable-5` — "cả đội tự lên Fable, 0 sửa frontmatter" xảy ra đúng thiết kế). `[1m]` cấm trong frontmatter `model` (gotcha #37). adap-report `2026-06-16-Governance-harness-8-all-inherit-workflow-fastest.md`.
> **Upgrade S70 (2026-06-17 — Harness-9 L2-recovery + adap 2-workflow adopt):** **(1) PROCESS-mandate 🔴 BẮT BUỘC (PART 2/3, áp MỌI adap từ nay):** mỗi adap 1 Harness = **2 workflow tách biệt** (IMPLEMENT + REVIEW double-check RIÊNG) + REPORT về AI_INFRA kèm **run-id** bằng chứng; task ngắn-nhưng-cần-confirm VẪN phải review-workflow. Codify `.claude/commands/adap-apply.md`. **(2) L2 dark-matter recovery (PART 1, tailored):** archive `agent-memory/<sub>/archive/*.md` KHÔNG vào RAG → build `archive/_INDEX.md` (mục-lục 1-dòng/bản-ghi + con-trỏ **substring** sha-keyed, fallback Ctrl-F, KHÔNG line-hint) + `<period>.gist.md` (nén 4-field ADDITIVE, `distill-gen` counter, verbatim FROZEN) + `memory-budget.json` (seed-by-measure qua `scripts/measure-agent-memory.ps1`) + budget-audit @session-start (§2.1.2) + `.ragignore` guard. Rollout S70 (đầy-đủ-nhất, stage investigate→implement→audit qua 3 Workflow run-id): 4 over-cap sub (cicd-monitor · investigator-codebase · reviewer · implementer-backend). adap-report `2026-06-17-Governance-harness-9-l2-recovery-and-adap-workflow.md`.
> **Upgrade S72 (2026-06-18 — Harness-10 flat-refine + checklist-v2 adopt):** run-trace SUBFOLDER→**FLAT** (file phẳng cùng cấp: `sub-<role>-<i>.md` raw + `<stage>-synthesis.md` verified, KHÔNG `sub-md/`/`harvest/` subdir) — `hmw.js` (`:103` subMd path) + `workflows/README` + `runs/README` + session-start/end + decision-tree (dòng dưới) repoint. **C8 migration:** 5 run cũ S71 GIỮ subfolder (đừng rewrite history); close-gate dual-accept cả hai dạng. **+`/sleep-recovery-memory-l2`** (đóng A8 — port §J2-tailored SE-only: sleep-compress L2 gist additive, INFORM-only ≥7d). **Anti-bypass detector (refine b): TAILORED-OUT** — SE dùng Anthropic Workflow tool (no CLI-launcher bypass-surface), containment = git-diff + run-folder TRACKED + ledger orphan-scan (G-015). 3 run-id bằng-chứng: audit `wf_13868efb-ea7` · implement `wf_ac43b5ff-7d1` · review (pending). adap-report `2026-06-18-Governance-harness-10-flat-refine-checklist-v2.md` (pending).
> **Upgrade S75 (2026-06-18 — Harness-11 engine bộ-nhớ-và-governance TỰ-BẢO-TRÌ adopt):** engine tự-DÒ toàn-diện (luôn tươi báo cờ) + AUTO chỉ semantic-null git-diff + **single-writer bar-KHÔNG-hạ (D9)** + đổi-luật owner-approve (D7). 🔑 Canonical → [`docs/governance/harness-11-engine.md`](../../docs/governance/harness-11-engine.md) (**KHÔNG copy luật ở đây — B1 dogfood**). Artifact MỚI: `scripts/governance-detectors.ps1` (C1 broken-pointer + C2/B3 staleness + C3 vocab-fork + C4 self-exclusion, NO-API DÒ+FLAG-only, **runtime-proven** bắt drift root CLAUDE.md mig53→55 + 0 self-match; số flag động → run-trace) + `scripts/memory-archive-gate.ps1` (PHẦN A hysteresis 0.85/keep-floor 5/2-strike/A7 NO-API L1-eval) + budget.json `archive_gate`. 3-tier D5(AUTO)/D6(DÒ+FLAG)/D7(owner-approve) + one-direction-lock D8 (canonical→derived) codify ở engine-doc. Cadence wired: D1 session-start §2.1.3 (chạy detector) · D2 session-end §L.b(c) (archive-gate). Áp qua workflow: audit `wf_7fdc3bd5-930` + implement `wf_c5e5844e-7c1` + review `wf_d7ca1ff8-942` + double-check `wf_a0b68d2f-30e`. adap-report `docs/governance/adap-reports/2026-06-18-Governance-harness-11.md`.
> **Upgrade S79 (2026-06-20 — User-Mark H-12/13 canonical §P + Harness-14 Eval/Budget/Outcome adopt):** áp **canonical §P đầy-đủ** (P1-P10) khi anh gõ `/user-mark-active-high` "áp đầy-đủ chính-xác nhất theo AI_INFRA". Artifact: **4 lệnh** `.claude/commands/user-mark-{active-high,active,medium,disable}.md` (DACI report-before-stamp) + ledger `.claude/governance/ACTIVE-MARKS.md` (4 cấp Active-High/Active/Medium/Disable + display-filter) + `harness-11-engine.md §E` (cơ-chế P1-P10) **+§F** (Harness-14 3-mức maturity) + `rules.md §6.6` (objective-criteria: KHÔNG quy-mô-đội / KHÔNG thời-gian-tuổi) + session-start §2.1.4 / session-end §L.b(h) mark-display. **3 mark Active-High stamped** anh-confirm S79 (`RC-pqhuy1987-20-06-2026-10-29-09/10/11`). completeness-gate H-6→H-13 ĐẠT (H-8 11/11 inherit no-`[1m]`). 4 workflow: invest `wf_82337f7f-95c` + review `wf_a7cbe93e-912` + align-re-review `wf_9d3beebb-a95` + H14-review `wf_4d4eba6f-8a0`. ⚠️ restart CLI (lệnh/session no hot-reload). adap-report 3× (`…rc-signature` + `…harness-all-update` + `2026-06-20-Governance-harness-14`).
> **Upgrade S93 (2026-06-29 — Harness-16 MFE adopt):** **memory-fidelity-EVAL** (đo nạp-vs-nhớ-vs-dùng bằng SỐ ĐO, KHÁC H6.7 `memoryDelta`-routing-fidelity). Artifact: `scripts/mfe-eval.ps1` (deterministic NO-API: LEAD coverage-FIT token-RANGE + age-band flag-not-cut + Goodhart-anchor strikes/RCA · SUB per-role coverage ĐO-THẬT prose-only→N/A · sub-workflow N/A) + `eval/mfe/` (seed sample-questions stable-id-anchored + README) + `memory-budget.json:mfe` config + engine **§H** + artifact-row. Judge recall/apply = **SCAFFOLD-only** (chờ age-maturity + independent-judge). Wire **opt-in** `session-start §2.1.6` + `session-end §L.b(c)` (param `eval`, no-param=như cũ). 🔴 **READS-not-writes** `token_governor` (owner-authority). C3 alias-map recorded §H (KHÔNG seed $aliasSets). 2-workflow: WF1 implement-investigate `wf_4c63e1bd-99e` + WF2 review `wf_13e3d35a-023` (3-lane PASS: code-gate denom-29-re-derived + cross-harness 0-conflict + honesty 5-floor). adap-report `2026-06-29-Governance-harness-16-mfe.md` + email AI_INFRA. ⚠️ restart CLI.
> **Upgrade S107 (2026-07-10 — +office-document, 12th sub):** **+office-document (📄 Office document WRITE specialist)** — anh giao trực tiếp S107 ("Sub chính" mảng Office). Floor **OD1–OD10** (skill-first · 🔴 fidelity-to-template 100% · extract-không-bịa · round-trip verify · file-mới-không-đè-gốc · boundary-code ⟂ implementer-backend). Skill nạp: bộ 4 Office standalone (`docx`·`xlsx`·`pptx`·`pdf`) + `form-engine` (project). VALID_ROLES `hmw.js` 9→**10**. Use-case SE: extract spec Excel/Word anh gửi (Database NCC → Supplier Phase B khi unpark) · chuẩn hóa template 8 form placeholder · document deliverable · screenshot→docx #74 · verify render form-engine. ✅ **verified-runtime S107 CÙNG PHIÊN** — registry HOT-RELOAD agent MỚI giữa phiên (harness mới; ⚠️ **ENV-DEPENDENT** — hub experiment 2026-07-11 NGƯỢC kết quả [0 notice + spawn not-found ×2] → KHÔNG fleet-generalize, restart = default an toàn; S27 restart-lesson giữ cho EDIT agent hiện có, chưa re-verify) + spawn-test PASS (OD1 skill invoke · OD4 extract-honest — finding: 2 template `wwwroot/templates` **0 placeholder `{{field}}`**, mẫu blank "…………..", mapping ở render-engine hoặc chưa placeholder-hóa · OD5 round-trip 37KB VN-dấu · OD7 gốc nguyên vẹn).

---

## 🎯 Architecture (12 agent)

> ⓘ **Diagram dưới = 7 core lane (pre-S47 snapshot).** Roster THẬT = **12 sub**: 7 core (diagram) + 🩷 frontend-designer (S47) + 🔵 database-agent (S52) + 📄 office-document (S107) + 🟫 tooling-auditor H1 + ⬜ harvest-curator H2 (2026-06-07 Harness 1) — xem skill matrix + decision tree + tool grant dưới. (Cosmetic ASCII chưa vẽ lại — tooling-auditor H1 sẽ flag drift này @session-start.)

```
┌──────────────────────────────────────────────────────────────┐
│ EM (Main) — Fable 5 (1M) Max                                  │
│ • Reasoning + write code (single-threaded principle)          │
│ • Schema/UX/architecture decision + cross-stack tight coupling│
│ • Coordinate 12 sub-agents via spawn + SendMessage            │
│ • Synthesize cross-agent findings + commit/push (em main only)│
│ • Fallback solo nếu spawn fail (gotcha #53 truncate / 529)    │
└──────────────────────────────────────────────────────────────┘
        ↓ spawn + keep-alive (Harness-8 all-inherit: cả 12 sub `model: inherit` = top-tier lead — Max; per-task tier:'opus' escape-hatch giữ)
  ── RESEARCH (READ) ──────────  ── IMPLEMENT (WRITE) ────────────  ── QUALITY ──────────
  ┌──────────────────┐ ┌───────┐ ┌─────────────────┐ ┌──────────┐ ┌────────┐ ┌─────────┐ ┌────────┐
  │investigator-     │ │invest-│ │implementer-     │ │implement-│ │test-   │ │reviewer │ │cicd-   │
  │codebase          │ │igator-│ │backend          │ │er-       │ │special-│ │         │ │monitor │
  │                  │ │api    │ │                 │ │frontend  │ │ist     │ │         │ │        │
  │ INTERNAL audit   │ │EXTERN-│ │ .NET Domain+App │ │ FE 2 app │ │ tests/ │ │adversa- │ │post-   │
  │ SQL/EF/grep/     │ │AL docs│ │ +Infra+Api      │ │cookie-   │ │dedica- │ │rial pre-│ │deploy  │
  │ reference mirror │ │CVE/lib│ │ entity/CQRS/Mig │ │cutter    │ │ted     │ │commit + │ │Gitea + │
  │                  │ │/cross-│ │ /Controller     │ │mirror    │ │xUnit   │ │live curl│ │bundle  │
  │                  │ │project│ │                 │ │SHA256    │ │        │ │         │ │+ smoke │
  └──────────────────┘ └───────┘ └─────────────────┘ └──────────┘ └────────┘ └─────────┘ └────────┘
       cyan              blue       yellow              orange       purple      red         green
```

---

## 🚨 RULE BẮT BUỘC (S39 updated)

**Em main BẮT BUỘC phân việc cho sub-agent đúng vai trò khi ACCEPT criteria match. Budget +50% → lean toward delegate + parallel, ít em main solo fallback.**

**Workflow forward S39+:**
- Trước mọi task → classify qua decision tree dưới
- Read-only research → **split**: internal codebase audit → `investigator-codebase` · external docs/CVE/lib → `investigator-api` (có thể spawn parallel cả 2)
- WRITE scaffold → **split**: .NET backend → `implementer-backend` · FE 2 app → `implementer-frontend` (parallel khi independent — vd BE entity + FE types cùng lúc)
- Test → **`test-specialist`** dedicated (KHÔNG để implementer kiêm)
- Deploy claim → `cicd-monitor` sau push (skip docs-only gotcha #41)
- Heavy diff / security / wire BE claim → `reviewer` pre-commit

**Em main solo CHỈ khi:** schema/UX/architecture decision · cross-stack tight coupling · bug fix reasoning chain · gotcha #53 fallback (spawn truncate/529 → em main solo reliable, proven S37 BE 700 LOC + FE 4 file).

**Anti-truncation rules (gotcha #53 — 5× occurrence S35-S37):**
- **Spawn prompt = RICH, fill-to-budget (H15-v3 S83 — supersedes old "≤8K brief"):** nạp INPUT tới token-budget của sub (mem-sub **60K** / wf-sub **50K** per `memory-budget.json:spawn_fill_directive`) bằng context GIÁ-TRỊ cao (relevant gotchas + state + full task-context + docs/memory liên-quan) — KHÔNG padding. Truncation #53 = rủi-ro RETURN của agent (vá bằng lean `memoryDelta` return + em-main recover-disk), **KHÔNG** vá bằng starve INPUT. *(Heuristic "≤8K brief" cũ = guard thời context-nhỏ S36, nay nghỉ.)*
- Tiered Memory v1: L1 HOT soft-cap ~30KB + L2 archive on-demand + L3 RAG just-in-time (per AI_INFRA policy). Investigator 32KB S37 truncate = lesson; soft-cap ~30KB tránh tái diễn.
- Agent keep entry ≤ 1.5K chars (frontmatter rule mỗi agent).
- Em main grep verify manual nếu agent return truncated mid-task.
- 529 Overload transient → em main solo fallback (KHÔNG retry loop).

---

## 🔄 Invocation decision tree (em main apply)

```
├── Read-only INTERNAL audit (codebase/SQL/EF diff/grep > 5 files)?
│     → investigator-codebase (cyan)
│
├── Read-only EXTERNAL (official docs / NuGet-npm CVE / lib eval / cross-project ref)?
│     → investigator-api (blue)
│     → Cả 2 investigator parallel OK khi task cần both (vd "audit current + research best practice")
│
├── DB schema-design / migration design-review / perf audit (N+1·index·projection) / transaction-concurrency (RowVersion lost-update)?
│     → database-agent (read-advisory, floor DB1–DB11) — DESIGN/REVIEW/PERF/CONCURRENCY-advise; implementer-backend AUTHOR sau
│     ⟂ vs investigator-codebase: deep DB-layer (introspection/query-plan/concurrency) vs broad codebase grep/audit
│     ⓘ Schema-design quyết-định-cuối vẫn em main solo; database-agent = deep-DB lens hỗ trợ + review implementer output
│
├── OFFICE DOCUMENT (đọc/tạo/sửa/convert docx·xlsx·pptx·pdf / extract spec file anh gửi / template form placeholder / báo cáo document / screenshot→docx #74)?
│     → office-document (📄) [OD1–OD10; skill docx·xlsx·pptx·pdf + form-engine]
│     ⟂ vs implementer-backend: C# render-engine (OpenXml/ClosedXML/LibreOffice service trong src/) = implementer-backend · office-document = FILE-level document/template/spec-extract (KHÔNG đụng src/·fe-*·tests/)
│
├── WRITE .NET backend (entity/EF Config/Mig/CQRS/Controller/DbInit)?
│     ✓ Spec deterministic · pattern proven >1× · >30min · ≤2 layer
│     → implementer-backend (yellow) [Case 1/2/3/5]
│
├── WRITE FE 2 app (page/types/component cookie-cutter mirror)?
│     ✓ UX flow chốt by em main · spec deterministic
│     → implementer-frontend (orange) [Case 1/2]
│     → BE + FE parallel khi independent (em main chốt DTO shape first)
│
├── WRITE FE DESIGN/REDESIGN (đẹp thật / UX mới / greenfield visual — KHÔNG mechanical mirror)?
│     ✓ design-system-first + visual-verification loop (Playwright screenshot ≥2 viewport → rubric → fix)
│     → frontend-designer (pink) [FD1–FD10 floor]
│     ⟂ vs implementer-frontend: đẹp/UX/thiết kế → frontend-designer · cookie-cutter SHA256 mirror theo spec → implementer-frontend (KHÔNG double-touch 1 file UI)
│
├── WRITE test (xUnit Domain policy / Infra handler / authz regression)?
│     → test-specialist (purple) [test-before bug/critical, test-after feature UAT]
│
├── After push code commit (NOT docs-only)?
│     → cicd-monitor (green) — Gitea poll + bundle hash + Mig prod + smoke
│
├── Adversarial pre-commit / heavy diff / wire BE claim / security?
│     → reviewer (red) — Smart Friend 5-category + live curl
│
├── @session-start/@session-end TOOLING-FRESHNESS audit (skill·sub-role·plugin·docs 4-mặt + drift)?
│     → tooling-auditor (H1 monitor, INFORM-only) — báo state+diff @start · chốt+new-alloc @end · em main APPEND
│
├── @session-end HARVEST-INTEGRITY gate (5-trục Coverage/Completeness/Fidelity/Placement/Corruption) / run-folder harvest (`runs/<run-id>/<stage>-synthesis.md` ← `sub-<role>-<i>.md` phẳng, Harness-10 h10-refine; run cũ S71 `harvest/`←`sub-md/`) / @session-start harvest mới?
│     → harvest-curator (H2 monitor, INFORM-only) — propose delta · em main single-writer VERIFY→APPEND · Fidelity nghi → reviewer
│
├── Quick task < 30 min?  → Em solo direct
│
└── Schema/UX/architecture/cross-stack tight/bug reasoning chain?
      → Em solo (Cognition) + investigator pre-flight optional + reviewer pre-commit
```

---

## 📋 Phân việc matrix — split boundary (CRITICAL)

| Layer / File | Owner |
|---|---|
| `src/Backend/SolutionErp.{Domain,Application,Infrastructure,Api}/**` | **implementer-backend** |
| `fe-admin/src/**` + `fe-user/src/**` (cookie-cutter mirror scaffold theo spec) | **implementer-frontend** |
| FE **design/UX/redesign** (aesthetic · new visual · design-system · a11y polish) | **frontend-designer** (self-gate rubric FD4 trước reviewer) |
| `tests/**` | **test-specialist** |
| Mig design / FK strategy / discriminator / schema | **em main solo** (database-agent deep-DB design-review/concurrency-advise optional + implementer-backend scaffold sau khi chốt) |
| DB schema introspection / query-perf (N+1·index) / migration design-review / concurrency RowVersion | **database-agent** (read-advisory — DESIGN/REVIEW/ADVISE, KHÔNG author file) |
| File Office (docx/xlsx/pptx/pdf) — template 8 form + spec-extract file anh gửi + document deliverable + screenshot→docx | **office-document** (📄 FILE-level — KHÔNG đụng `src/`·`fe-*`·`tests/`; render-engine code = implementer-backend) |
| UX flow (drawer/tab/modal) / page structure | **em main solo** (implementer-frontend scaffold sau khi chốt) |
| Internal SQL/EF/grep audit | **investigator-codebase** |
| External docs/CVE/lib/cross-project | **investigator-api** |
| Pre-commit verify | **reviewer** (NEVER write) |
| Post-deploy verify | **cicd-monitor** (NEVER write) |

**Boundary dứt khoát:** implementer-backend KHÔNG touch FE · implementer-frontend KHÔNG touch BE (chỉ Read DTO shape) · cả 2 implementer KHÔNG viết test (→ test-specialist) · test-specialist reveal prod bug → REPORT em main KHÔNG fix · **frontend-designer = design/UX/đẹp (FE-only, KHÔNG BE/DB) ⟂ implementer-frontend = mechanical mirror theo spec — KHÔNG double-touch cùng 1 file UI (chồng lấn → escalate em main).** **office-document = FILE Office (docx/xlsx/pptx/pdf · template · spec-extract) ⟂ implementer-backend = C# render-engine trong `src/` — file-level vs code-level, KHÔNG double-touch.**

---

## 🛠️ Skill assignment (6 skill, re-distributed S39)

| Agent | Skills |
|---|---|
| investigator-codebase | `contract-workflow` + `permission-matrix` + `ef-core-migration` |
| investigator-api | `dependency-audit-erp` |
| implementer-backend | `ef-core-migration` + `permission-matrix` + `contract-workflow` + `form-engine` |
| implementer-frontend | `permission-matrix` |
| test-specialist | `contract-workflow` + `permission-matrix` |
| reviewer | `dependency-audit-erp` + `contract-workflow` + `permission-matrix` |
| cicd-monitor | `iis-deploy-runbook` + `dependency-audit-erp` + `ef-core-migration` |
| frontend-designer | `frontend-design` + `senior-frontend` + `brand-guidelines` + `theme-factory` + `webapp-testing` (FD2 loop) + `web-artifacts-builder` |
| database-agent (read-advisory S52) | `sql-database-assistant` (SQL Server first-class — KHÔNG cover EF-Core) + `ef-core-migration` (EF Core 10 pin + 3-file rule) |
| office-document (📄 S107) | `docx` + `xlsx` + `pptx` + `pdf` (bộ 4 Office standalone `~/.claude/skills/` — duplicate namespaced `anthropic-skills:*` → dùng standalone) + `form-engine` (project — template 8 form HĐ `{{field}}` + PDF LibreOffice + RG-001) |
| tooling-auditor (monitor H1) | ref-only — reads skill registry, KHÔNG dùng domain skill |
| harvest-curator (monitor H2) | none — deterministic 5-trục scan + Fidelity-escalate `reviewer` |

## 🔧 Tool grant (S39 — +3 RAG MCP per agent)

All 12 agent có **4 RAG-READ MCP**: `search_memory` + `search_code` (BM25, prefer over Read full file — tiết kiệm token) + `cross_project_search` + `list_projects`. Base tools per role (READ: Read/Grep/Glob/Bash [+WebFetch/Search cho api] · WRITE: +Edit/Write/Skill).

> **2 monitor sub (tooling-auditor H1 + harvest-curator H2 — 2026-06-07):** read-only toolset = `[Read, Grep, Glob, Bash, +4 RAG-read]`, **NO `store_memory`, NO Write/Edit** (mirror investigator read-set). INFORM-only — propose → em main single-writer VERIFY→APPEND (B3). 🔴 **G-015 accuracy (Harness-10 run-trace model, `runs/README.md §Containment` — 🧊 `_ledger.md` retired H18-B S100):** run-folder `runs/<run-id>/` được git **TRACKED** → mọi write HIỆN trong git-diff = audit trực-tiếp. Containment: tracked-change NGOÀI `runs/<run-id>/` VÀ NGOÀI code-disjoint đã giao = vi-phạm (thay model Harness-2 B6 "mọi tracked-change = vi-phạm"). G-015 no-overclaim: TRACKED ≠ read-only-enforced — sub vẫn giữ `Bash` (write-channel mở qua shell/curl) → containment THẬT = em main single-writer + git-diff(in-repo) + chunk-count (RAG), KHÔNG allowlist đơn-độc.

> ⚠️ **`store_memory` GỠ khỏi MỌI sub (2026-06-02 — AI_INFRA broadcast `Memory-store-memory-strip-global`, adap-report cùng id).** → **lead (em main) = sole RAG-writer** (mechanized failure-safe: sub vật-lý không gọi được `store_memory`). Sub tìm thấy finding/pattern mới → ghi **MEMORY.md** (file); lead + re-index đưa vào RAG. *Accuracy (G-015): đây KHÔNG = sub "read-only" — sub vẫn giữ `Bash` (+ vai write giữ `Write/Edit`); containment thật = defense-in-depth git-diff + Qdrant chunk-count, chưa phải allowlist đơn độc.*

---

## 🔌 External skill/plugin mapping (H3 — Harness 1 adopt 2026-06-07)

> Floor H3: nạp đúng skill/plugin hợp stack, **gộp-vai KHÔNG phình roster**. Audit (investigator-api 2026-06-07; tooling-auditor H1 re-count S53): **18** plugin registered (15 enabled / 3 disabled) user-global (`~/.claude/settings.json` — +csharp-lsp +typescript-lsp +session-report vs S49's 15) + ~23 standalone skill (`~/.claude/skills/`). **0 agent mới** — mọi cái = skill→gộp-vai-hiện-có. Nấc: enabled/available → **assigned** (bảng dưới = doc) → used (per-session auto-trigger). tooling-auditor (H1) rà new-alloc mỗi session-end.

| Skill/plugin (nguồn) | Value-locus | Map → vai | Ghi chú |
|---|---|---|---|
| `sql-database-assistant` (standalone) | skill-only | investigator-codebase + implementer-backend | SQL/EF query; đọc kèm `ef-core-migration` (KHÔNG override pin EF Core 10 / dbo single-schema) |
| `frontend-design` (standalone, KHÔNG enable plugin trùng) | skill-only | frontend-designer | duplicate plugin↔standalone → chọn standalone |
| `skill-creator` | skill-only | mọi sub (khi tạo skill project) | additive |
| `claude-md-management` (`claude-md-improver`) | skill+cmd | em main | doc-maintenance |
| `pr-review-toolkit` (silent-failure-hunter / type-design-analyzer / comment-analyzer / pr-test-analyzer) | agent-bearing | reviewer (tham-chiếu .md như CHECKLIST, KHÔNG enable agent) | giữ roster `reviewer` canonical |
| `session-report` (node `.mjs`, Win-OK Node 20) | skill-only | em main / cicd-monitor | optional — token/spawn-cost observability |

**🔴 KHÔNG enable (tránh phình roster + name-collision — H3.3):**
- `code-modernization` (5 agent: legacy-analyst/security-auditor/test-engineer…) — SE = .NET 10 greenfield, agent-set trùng test-specialist/reviewer/investigator. Chỉ cmd `modernize-assess/map` ad-hoc khi port NamGroup module.
- `code-reviewer` (×3 nguồn: pr-review-toolkit + feature-dev + standalone skill) collide roster `reviewer` → **giữ `reviewer` canonical**, KHÔNG dùng plugin code-reviewer.
- `csharp-lsp` — **Windows no-op** (`csharp-ls` không trên PATH; cần `dotnet tool install --global csharp-ls` trước). Defer (Bash dotnet build + grep symbol đủ).
- `commit-commands/commit-push-pr` — giả định GitHub `gh`; SE = Gitea → partial no-op (chỉ `commit.md` dùng được).

---

## 🚦 HMW-mode — Workflow fan-out governance (S49, broadcast `ultracode-hmw-mem-governance`)

> Áp dụng KHI chạy **Workflow runtime fan-out** (`.claude/workflows/hmw.js`). Vận hành thường (Agent-tool spawn lẻ / parallel-trong-1-message) KHÔNG đổi — decision-tree trên vẫn chuẩn. Toggle: `/ultra-on` · `/ultra-off`.

- **Toggle 2-lệnh = on-ramp DUY NHẤT (T1/T2):** `/ultra-on` tạo marker `.claude/hmw-mode.on` (gitignored) + vào mode · `/ultra-off` xóa. Marker = single-source-of-truth, persist qua session/compact. `/session-start` đọc marker → BÁO ON/OFF (T3).
- **Keyword = QUYỀN, KHÔNG lệnh (T4):** "workflow"/"ultracode" mở quyền hỏi, KHÔNG auto-run. Mode-OFF + "chạy workflow" → TỪ CHỐI + nhắc `/ultra-on`. CẤM native `/effort ultracode`. *(Bài học 515K-token false-trigger.)*
- **Scope (S1):** Workflow fan-out CHỈ repo SOLUTION_ERP — KHÔNG fan-out repo/corpus khác.
- **Checkpoint (S2):** `hmw.js` **throw** nếu `checkpointApproved≠true` (mechanized tripwire anti-accidental). Em main BÁO {số agent·vai·task} @inform → set cờ → fan-out (KHÔNG chờ confirm từng lần; marker-ON=consent). Sub KHÔNG spawn sub (S3).
- **VALID_ROLES (12 — whitelist `hmw.js`, đủ roster):** `investigator-codebase` · `investigator-api` · `implementer-backend` · `implementer-frontend` · `test-specialist` · `reviewer` · `cicd-monitor` · `frontend-designer` · `database-agent` (+S57 — S56 đã dùng 3× qua fail-soft WARN) · `office-document` (+S107 — Office WRITE OD1–OD10) · `tooling-auditor` + `harvest-curator` (+S110 anh-directed — H21 roster-parity lệnh-B; monitor vẫn INFORM-only, lane RETURN-only). Role lạ ∉ VALID_ROLES → `hmw.js` THROW (STOP-HARD) + báo owner (S4c, DIRECTED REC-3 2026-07-13); role-less null → inherit lead.
- **Memory governance (M1–M5 + R1):** B1 slice-inject (agent ← slice MEMORY của đúng vai qua `args`) · M2 return-delta-only (`memoryDelta{task,verdict,learned,surprise}`) · B3 lead single-writer VERIFY→APPEND-only (no-overwrite-unverified) · B2 harvest-LIỀN sau mỗi workflow vào `agent-memory/<role>` · M5 `store_memory` strip (đã S47). **Containment = defense-in-depth** (git-diff + Qdrant chunk-count post-P2), KHÔNG allowlist đơn-độc (G-015: sub vẫn giữ Bash/Write — KHÔNG "read-only").

> Floor T/S/M/R đầy đủ → `.claude/commands/ultra-on.md`. adap-report → `docs/governance/adap-reports/2026-06-03-Agent-ultracode-hmw-mem-governance.md`.

---

## 💾 Memory discipline

Each agent `.claude/agent-memory/<name>/MEMORY.md` persistent diary. Spawn auto-inject first 200 lines/25KB. Update BEFORE return (BẮT BUỘC, entry ≤ 1.5K chars). 12 folder: investigator-codebase · investigator-api · implementer-backend · implementer-frontend · test-specialist · reviewer · cicd-monitor · frontend-designer · database-agent · office-document · tooling-auditor · harvest-curator.

**Tiered Memory Policy v1** (adopt AI_INFRA bulletin 2026-05-29 — thay ngưỡng cứng ">25KB archive" bằng tiered + just-in-time; size to ≠ chất lượng, context-rot):
- **L1 HOT** = `MEMORY.md` soft-cap **~30KB** (role + patterns + anti-patterns + 5-8 entry gần nhất) → auto-inject mỗi spawn
- **L2 COLD** = `archive/<YYYY-MM>.md` verbatim (activity cũ) → Read on-demand. **Harness-9 (S70):** `archive/_INDEX.md` mục-lục 1-dòng/bản-ghi (con-trỏ **substring** sha-keyed, fallback Ctrl-F, frozen-additive) = **inject "tấm bản-đồ"**; verbatim + `archive/<period>.gist.md` (nén 4-field, `distill-gen` counter) = đọc-theo-nhu-cầu. "Inject mục-lục, KHÔNG inject lãnh-thổ." Budget-audit @session-start (§2.1.2 session-start.md) chống quên chỉnh ngân sách.
- **L3 SEARCHABLE** = RAG `search_memory` → just-in-time
- Discipline: search L3 / Read L2 TRƯỚC khi deep-dive (đừng nhồi L1). Agent nhớ vô hạn qua L2+L3, context spawn vẫn gọn. Curate khi L1 > ~30KB (KHÔNG còn hard 25KB).

**End-of-session:** em main SendMessage mỗi agent flush MEMORY → đọc 7 update → synthesize cross-agent → integrate project memory/session log → commit/push.

---

## 📊 Cost reality (budget +50% S39)

| Component | Effective tokens billed (after caching) |
|---|---|
| 7 sub-agents spawn setup | ~1.1M (7 × ~155K cache WRITE) |
| SendMessages cached | ~500K |
| Em main session | ~250K |
| **Total per heavy session** | **~1.85M (~9× solo)** |
| **Optimized (compact + cache + skip trivial + parallel)** | **~1.05M (~5× solo)** |

**+50% budget** (vs prior ~700K opt / ~1.35M heavy → now ~1.05M opt / ~2M heavy ceiling). Max 20× plan absorbs ~5× comfortable. Trade-off justify: split nhẹ hơn mỗi spawn (giảm gotcha #53 truncate) + parallel BE+FE+test (giảm wall-clock) + test-specialist clear coverage gap backlog (quality).

---

## 🎯 Project tunings (SOLUTION_ERP)

**Stack:** .NET 10 Clean Arch + CQRS MediatR + EF Core 10 + SQL Server + 2 React 19 Vite 8 FE + Gitea CI + Windows IIS.

**State (S38 — 2026-05-28):** 40 mig · 84 tables · ~223 endpoints · 53 FE pages · 130 test PASS · 53 gotchas · 27 memory · 6 skills · **7 sub-agents** · Phase 10 COMPLETE 11/11 Plan G-*.

**Windows MAX_PATH:** project path nested + Dropbox-managed → implementer KHÔNG dùng `isolation: worktree`. Default branch OK.

**UAT live mode (Phase 9):** `feedback_uat_skip_verify` — skip `dotnet test` mỗi chunk, vẫn `npm run build` × 2. test-specialist test-after khi UAT confirm; test-before cho bug/critical algo.

---

## 🔗 References
- [Anthropic Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents)
- [Cognition "Don't Build Multi-Agents"](https://cognition.ai/blog/dont-build-multi-agents)
- BVAAU 7-agent reference: `D:\Dropbox\CONG_VIEC\BENHVIEN_A_AU\SOURCE_CODDE\.claude\agents\` (adapted S39 — split trục + 5 RAG tool; SOLUTION_ERP giữ 6 skill + backend/frontend split thay domain/infra cho 2-FE-app fit)
- Memory: `feedback_per_chunk_commit` · `feedback_uat_skip_verify` · `feedback_audit_reuse_before_clone` · `feedback_implementer_truncation_mitigation` (gotcha #53)

## ⚠️ CLI restart required
Agent definition change (S39 split 4→7) → **anh main restart Claude Code CLI** để registry hot-reload (per S27 lesson — model:inherit + new agent files). Verify post-restart: spawn smoke test mỗi agent mới (investigator-api / implementer-frontend / test-specialist) confirm load OK.
> **Cập nhật S107 (2026-07-10):** harness hiện tại **HOT-RELOAD agent file MỚI giữa phiên** (office-document tạo + spawn-test PASS cùng phiên, 0 restart). S27 lesson thu hẹp còn: **EDIT agent đang tồn tại** + command `.md` (chưa re-verify hot-reload) → restart vẫn là default an toàn cho 2 ca đó.
> ⚠️ **ENV-DEPENDENT (S110 2026-07-11 — triage-reply S5 hub):** hub chạy CÙNG experiment ADD-agent-mới → kết quả NGƯỢC (0 system-notice + spawn "not found" ×2 qua turn-boundary) ⇒ hot-reload-ADD-mới KHÔNG fleet-proof, chỉ verified trên env SE tại S107; **restart = default an toàn MỌI ca** khi nghi ngờ.
