solution-erp/.claude/agents

Multi-agent SOLUTION_ERP — Master Coordination Guide (10-agent)

Architecture: 10 sub-agents Opus 4.8 1M Max + em main coordinator — 8 product/quality (7 core + frontend-designer pink, S47) + 2 monitor INFORM-only (tooling-auditor H1 + harvest-curator H2, 2026-06-07 Harness 1). 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.

---

🎯 Architecture (10 agent)

ⓘ Diagram dưới = 7 core lane (pre-S47 snapshot). Roster THẬT = 10 sub: 7 core (diagram) + 🩷 frontend-designer (S47) + 🟫 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) — Opus 4.8 1M Max                                   │
│ • Reasoning + write code (single-threaded principle)          │
│ • Schema/UX/architecture decision + cross-stack tight coupling│
│ • Coordinate 10 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 (Opus 4.8 1M Max inherit each)
  ── 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):

• Brief WRITE agent ≤ 8K (heavy spec ~10K → truncate risk). FE tight brief proven 0 truncation S36.
• 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")
│
├── 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) / wave-folder gom (Harness 2 B5) / @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 (implementer-backend scaffold sau khi chốt)
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).

---

🛠️ 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
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 10 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: đây KHÔNG = "read-only enforced" — sub vẫn giữ Bash (write-channel mở qua shell/curl). Containment thật = em main single-writer + git-diff + chunk-count post-session (defense-in-depth), 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 S50): 18 plugin enabled 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 (8 — whitelist hmw.js): investigator-codebase · investigator-api · implementer-backend · implementer-frontend · test-specialist · reviewer · cicd-monitor · frontend-designer. Role lạ → default subagent + WARN (fail-soft, S4c).
• 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). 8 folder: investigator-codebase · investigator-api · implementer-backend · implementer-frontend · test-specialist · reviewer · cicd-monitor · frontend-designer.

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 (activity cũ) → Read on-demand
• 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
• Cognition "Don't 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.