solution-erp/.claude/agents/README.md

Multi-agent SOLUTION_ERP — Master Coordination Guide

Architecture: 3 sub-agents Opus 4.7 1M Max + em main coordinator. Pattern: Anthropic Building Effective Agents orchestrator-workers + Cognition "writes single-threaded" hybrid. Setup: Session 20 turn 12 (2026-05-11) — empirical-grounded từ NAMGROUP s41-s43 trial curve.

---

🎯 Architecture

┌─────────────────────────────────────────────────────────┐
│ EM (Main) — Opus 4.7 1M Max                             │
│ • Reasoning + write code (single-threaded principle)    │
│ • User dialog + architectural decisions                 │
│ • Coordinate 3 sub-agents via SendMessage               │
│ • Synthesize cross-agent findings end-of-session        │
└─────────────────────────────────────────────────────────┘
                ↓ spawn + keep-alive (Opus 4.7 1M Max each)
  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
  │ Investigator │  │  Implementer │  │   Reviewer   │
  │   READ only  │  │  WRITE strict│  │   READ only  │
  │              │  │ classification│  │              │
  │  Research +  │  │ Cookie-cutter│  │ Adversarial  │
  │   Audit +    │  │  + Multi-file│  │ pre-commit + │
  │   External   │  │  independent │  │ live verify  │
  │   research   │  │     ONLY     │  │              │
  └──────────────┘  └──────────────┘  └──────────────┘
        cyan             yellow              red

---

🔄 Invocation decision tree (em main apply)

Task input → classify task type:

├── Read-only research / audit / scan > 5 files / external fetch?
│     → Spawn Investigator (always safe)
│
├── Adversarial pre-commit verify / heavy diff / deploy claim?
│     → Spawn Reviewer (always before push critical)
│
├── Cookie-cutter mechanical (N independent files same pattern, deterministic spec)?
│     ✓ N >= 5 files
│     ✓ Spec deterministic (no implicit decisions)
│     ✓ Pattern proven > 1× prior
│     → Spawn Implementer (Case 1 Anthropic verified)
│
├── Multi-file independent changes (different modifications per file)?
│     ✓ Each file verifiable independently
│     ✓ Files NOT cross-stack tight coupling
│     → Spawn Implementer (Case 2 orchestrator-workers)
│
├── Test generation for isolated methods?
│     → Spawn Implementer (Case 3 verified)
│
├── Mass code migration (framework upgrade, per-file deterministic)?
│     → Spawn Implementer (Case 5 verified)
│
├── Quick task < 30 min (overhead spawn không xứng)?
│     → Em solo direct
│
├── Schema design / UX flow / architectural decision / cross-stack tight coupling?
│     → Em solo (Cognition "writes single-threaded")
│     → Investigator pre-flight optional
│     → Reviewer pre-commit always
│
└── Bug fix tightly coupled (cross BE/FE/DB, reasoning chain)?
      → Em solo (Anthropic warning: "tightly interdependent coding")
      → Investigator pre-flight optional
      → Reviewer pre-commit always

---

📋 Implementer task classification — CRITICAL rules

Em main MUST self-check before spawning Implementer:

✅ ACCEPT criteria (ALL must be true)

1. ✅ Spec deterministic (no implicit decisions left for agent)
2. ✅ Files independent (modifications don't depend on each other)
3. ✅ Pattern repeatable (proven > 1× prior session — reference memory entries)
4. ✅ Estimated effort > 30 min (overhead worth)
5. ✅ Max 2 layers cross-stack (NOT BE entity + DTO + FE wire 3-layer)
6. ✅ Each file output verifiable independently

❌ REFUSE criteria (ANY triggers refusal)

1. ❌ Schema design decisions needed
2. ❌ UX flow decisions needed
3. ❌ Cross-stack > 2 layers tight coupling
4. ❌ Bug fix involving reasoning chain
5. ❌ Integration testing involving multiple components
6. ❌ < 30 min trivial task
7. ❌ First time pattern (no prior precedent)
8. ❌ Spec ambiguity > 20%

Implementer agent ALSO has self-check trong system prompt → auto-refuse out-of-scope.

---

💾 Memory consult discipline

Each agent has .claude/agent-memory/<name>/MEMORY.md persistent diary:

• Spawn: Auto-inject first 200 lines / 25KB của MEMORY.md
• During work: Agent may Read full MEMORY.md if task complex
• Before return: Agent MUST update MEMORY.md với findings (BẮT BUỘC)
• Cross-session: MEMORY.md persists on disk

Em main routine end-of-session:

SendMessage Investigator: "Flush MEMORY.md với findings session này. Format:
  1-2 sentences per finding. Categories: patterns / anti-patterns / gotchas
  discovered / external research summary."

SendMessage Implementer: "Flush MEMORY.md với patterns applied + ambiguities
  encountered + scope refusals."

SendMessage Reviewer: "Flush MEMORY.md với anti-patterns observed + gotcha
  regressions caught + claim verification results."

Em read 3 MEMORY.md updates → synthesize cross-agent learnings → integrate
  vào project memory / session log.

Em proceed normal close-out: STATUS update + commit + push.

---

🛠️ SendMessage discipline

Cost optimization:

• Within 5min cache TTL window khi possible (90% discount cached prefix)
• Compact prompts (~5K new content each) thay vì dump (~24K)
• Skip spawn cho task < 30min

Context discovery preservation:

• Include explicit "Include surprising findings + edge cases discovered" trong spec
• Periodic checkpoint mỗi 1-2h heavy work: prompt agents flush MEMORY.md
• Session crash → MEMORY.md preserved on disk, in-session context lost

---

🎯 Project-specific tunings (SOLUTION_ERP)

Stack: .NET 10 Clean Architecture + CQRS MediatR + EF Core 10 + SQL Server + 2 React 19 Vite 8 FE (admin + user) + Gitea Actions CI + Windows IIS.

Current state (Session 20 turn 12): 27 migrations · 59 DB tables · ~142 endpoints · 34 FE pages · 81 test pass · 44 gotchas · 14 memory entries · 6 skills · 30 demo user · 3 prod domain *.solutions.com.vn.

Skills preload mỗi sub-agent:

• Investigator: contract-workflow + permission-matrix + ef-core-migration (research patterns + schema audit)
• Implementer: ef-core-migration + permission-matrix + form-engine (scaffold + 3-file rule + permission seed)
• Reviewer: dependency-audit-erp + iis-deploy-runbook + contract-workflow (security/deploy/workflow audit)

Context paste session start (em main responsibility):

• docs/STATUS.md current state
• docs/CLAUDE.md root tech context
• Latest 2 session logs docs/changelog/sessions/
• Active gotchas docs/gotchas.md
• Memory entries C:\Users\pqhuy\.claude\projects\D--Dropbox-CONG-VIEC-SOLUTION\memory\MEMORY.md

→ Auto-inject baseline ~80-150K per agent. Plus task-specific Read on-demand.

Windows MAX_PATH pitfall: Project path D:\Dropbox\CONG_VIEC\SOLUTION\SOLUTION_ERP\ đã nested 51 chars + Dropbox-managed. Implementer frontmatter KHÔNG dùng isolation: worktree (per Pitfall 1 template). Default branch isolation OK.

UAT live mode (Phase 9 active): Memory feedback_uat_skip_verify — skip dotnet test mỗi chunk, vẫn npm run build × 2 app. Reviewer khi spawn pre-commit cần áp rule này (không yêu cầu test increment cho UAT iteration), VẪN verify wire BE + security + anti-fiddle.

---

📊 Cost reality

Component	Effective tokens billed (after caching)
3 sub-agents spawn setup	~564K (3 × 188K cache WRITE)
10 SendMessages each ~24K new	~450K (10 × 45K equivalent với cache READ)
Em main session	~200K
Total per heavy session	~1.2M (~6× solo)
Optimized (compact + cache + skip trivial)	~600K (~3× solo)

Max 20× plan absorbs ~3× solo cost comfortable.

---

🧪 Trial workflow (2-4 tuần evaluate)

• Week 1: Setup + Plan trial cookie-cutter (Case 1 verified). SOLUTION_ERP candidate: Contract V2 wire Mig 28+29 mirror PE pattern — pattern proven 1× S17-S19 (PE V2). ~600+ LOC, 2 mig + Service + Controller + FE × 2 app.
• Week 2-3: Feature wire (Solo em + Inv pre-flight + Rev pre-commit) — phân quyền strict V2 + drop legacy V1.
• Week 4: Evaluate quality vs cost real numbers.
  • Pass criteria: Rev catch ≥ 2 wire bugs trước commit + time saving ≥ 25% Case 1+2 + Max 20× quota comfortable
  • Fail criteria: any of above unmet → rollback solo, agents archived

---

🔗 References

• Anthropic Building Effective Agents
• Cognition "Multi-Agents Working"
• Anthropic Sub-agents docs
• Memory entries (C:\Users\pqhuy\.claude\projects\D--Dropbox-CONG-VIEC-SOLUTION\memory\):
  • feedback_per_chunk_commit.md — per-chunk discipline reference cho Implementer pattern
  • feedback_uat_skip_verify.md — Reviewer rule trong Phase 9
  • feedback_drastic_refactor_scope.md — Implementer refuse criteria reference
  • feedback_audit_reuse_before_clone.md — Investigator audit-first pattern