Nelson Freight · Internal Architecture Brief

MiniMax Full-Power Harness
+ 11 Sub-Agent Workflow

Tận dụng toàn bộ gói Token Plan MiniMax (vlm + search + image + speech, không chỉ M2.7) cho 11 sub-agent — bao phủ toàn bộ ERP, Email Pipeline, Dashboard. Kèm thiết kế /ck:llms auto-snapshot để MiniMax đọc hệ thống ít tốn token nhất.

Ngày: 2026-04-26 Status: Design proposal — chờ Sếp approve Đối tượng: Nelson + dev team Document: Educational A1
01

Token Plan — quota live status

Đây là dữ liệu live từ api.minimax.io/v1/token_plan/remains tại 2026-04-26. Sếp đang trả tiền cho cả gói nhưng chỉ dùng 1 model. Các quota tô vàng = chưa khai thác.

MiniMax-M2.7 (coding)
44,434 / 45,000 tuần
✓ Active · 1.3% used
coding-plan-vlm (vision)
45,000 / 45,000 tuần
⚠ Chưa dùng — đọc screenshot, mockup
coding-plan-search (RAG)
45,000 / 45,000 tuần
⚠ Chưa dùng — code + web search
speech-hd (TTS)
28,000 / tuần
⚠ Chưa dùng — voice memo
image-01 (text→image)
350 / tuần
⚠ Chưa dùng — UI mockup
Hailuo-2.3 video
0 quota
— Chưa enable
music-2.6 / lyrics
700 each
— Không cần freight

Insight: Sếp trả tiền cho ít nhất 5 quota lớn nhưng chỉ tận dụng 1. Nếu mở full-power → 11 sub-agent có thể consume parallel ~163,000 requests/tuần thay vì 45,000. Đây là core value proposition của design này.

02

Harness Engineering — 10 yếu tố cốt lõi

"Harness" = bộ khung infrastructure để build AI agent system. Khác với "11-agent" (là policy, một cách dùng cụ thể). Hai tầng khác nhau, không thay thế lẫn nhau.

🔧 1. Tool Layer Infra

Tools agent có thể call: Read, Write, Bash, Glob, Grep, WebFetch... Quyết định khả năng vật lý.

🧠 2. Memory Layer Infra

Persist state across turn/session. Memory file của Sếp ở ~/.claude/projects/.../memory/.

🎯 3. Routing Layer Infra

Quyết định model nào xử task nào. Hiện tại: Opus vs M2.7. Đề xuất: + vlm + search + image-01.

👥 4. Sub-agent Dispatcher Infra

Spawn parallel/sequential agents qua Agent tool. Sub-agent kế thừa model parent.

📦 5. Skill Layer Infra

Modular capability packages (158+ skills). Auto-load via SKILL.md. Sếp có cook, fix, debug...

🔒 6. Permission Layer Infra

Allow/deny tool calls. Cấu hình trong settings.json. Guardrail an toàn.

📋 7. Context Layer Infra

CLAUDE.md auto-load + system reminders + memory injection. Quyết định agent biết gì.

8. Hook Layer Infra

Automated triggers (pre-tool, post-tool, stop). Cách thực thi "mỗi khi X thì Y".

📊 9. Plan/Task Layer Infra

TaskCreate/Update tracking + plan.md với YAML frontmatter (status, dependencies).

📄 10. Artifact Layer Infra

Files output: reports, llms.txt, mockup.html. Đây là nơi /ck:llms sống.

💡 So sánh: Harness vs 11-Agent
Khía cạnhHarness Engineering11 Sub-Agent Workflow
Bản chấtInfrastructure — bộ khungPolicy — 1 cách config
Phạm viÁp dụng mọi workflow5-phase dev workflow cụ thể
Thay đổi tần suấtHiếm (kiến trúc nền)Thường xuyên (theo nhu cầu)
Quan hệ11-agent là MỘT INSTANCE chạy trên harness. Sếp đổi 11 → 15 agent vẫn dùng cùng harness.
03

11 Sub-Agent — vai trò & routing hiện tại

Workflow 5-phase của Nelson. Routing hiện tại (v2.0) chỉ chia 2 nhóm: Opus (judgment) vs M2.7 (mechanical). Đề xuất mới: phân hoá xuống 5 model trong Token Plan.

# Phase Sub-agent Vai trò Routing hiện tại Routing đề xuất
1Designdesign-finder Tìm UI inspiration từ Dribbble/Awwwards Opus vlm + search
2Reviewux-reviewer WCAG, responsive, screenshot analysis Opus vlm (đọc UI screenshot)
3Reviewcode-reviewer Logic, TypeScript, security surface Opus M2.7 (+ Opus final gate optional)
4Reviewsecurity-auditor OWASP Top 10, secrets, auth Opus M2.7 + Opus 2-pass
5Reviewperf-analyzer Bundle size, N+1, Core Web Vitals Opus M2.7 + search
6Executemaster-executor Apply fixes từ review reports M2.7 M2.7 (giữ nguyên)
7Processtest-writer Unit/integration/e2e test gen M2.7 M2.7 (giữ nguyên)
8Processdoc-writer JSDoc, README, API docs M2.7 M2.7 + image-01 (diagrams)
9Processtech-debt-tracker TODO/FIXME scan, register Opus M2.7
10Finalizegit-commit Conventional commit message M2.7 M2.7 (giữ nguyên)
11i18n-checker Translation key audit N/A Không dùng (Email = English only)
04

Quota → Sub-agent allocation matrix

Mapping cụ thể từng quota Token Plan với sub-agent phù hợp. Đây là cách "nạp full power" cho 11 agent.

VLM coding-plan-vlm — Vision Language Model

45,000 req/tuần · chưa dùng 1 request

Phục vụ:

  • ux-reviewer — đọc screenshot UI, check spacing, hierarchy
  • design-finder — analyze inspiration images từ Dribbble
  • doc-writer — đọc diagram screenshot, sinh ra docs giải thích
  • ERP review — đọc screenshot ribbon, Quote sheet, đề xuất layout fix
SRC coding-plan-search — Coding + Web Search

45,000 req/tuần · chưa dùng 1 request

Phục vụ:

  • perf-analyzer — lookup latest best-practice từ Vercel/web.dev
  • tech-debt-tracker — search known antipatterns
  • design-finder — search Awwwards + freight industry sites
  • backend research — latest FastAPI/Pandas/DuckDB patterns
IMG image-01 — Text-to-Image

350 req/tuần · chưa dùng 1 request

Phục vụ:

  • design-finder — sinh UI mockup nhanh (alt cho Gemini Nano Banana)
  • doc-writer — diagram architecture, flowchart
  • email pipeline — generate header banner cho weekly blast
TTS speech-hd — Text-to-Speech

28,000 req/tuần · chưa dùng 1 request

Phục vụ (offline, không phải sub-agent):

  • Voice daily report — biến tech-debt report thành audio để Sếp nghe khi lái xe
  • Email campaign QA — TTS đọc draft trước khi gửi để check tone
  • Onboarding 6 mentees Life OS — voice walkthrough
M2.7 MiniMax-M2.7 — Core Coding Executor

44,434 req/tuần còn lại · 566 đã dùng

Default cho mọi task không match 4 model trên: master-executor, test-writer, code-reviewer, security-auditor (1st pass), git-commit, tech-debt-tracker. Bao gồm cả ERP/Excel COM/email pipeline (safety override LIFTED theo approval Sếp 2026-04-26).

05

/ck:llms auto-snapshot flow

Sau mỗi plan execution, Opus auto-sinh 1 file llms.txt nén toàn bộ context hệ thống thành ≤5K tokens. MiniMax đọc 1 file = hiểu trọn bộ system, thay vì grep nhiều file (đốt token).

1
Opus complete plan
master-executor xong, all reports apply
trigger
2
PostToolUse hook fire
settings.json hook detect plan completion
automation
3
Skill /ck:llms run
Scan code, contract, recent diff
extract
4
Compress & format
Theo llmstxt.org spec, ≤5K tokens
compress
5
Write 2 files
plans/<slug>/llms.txt + project root
artifact
6
MiniMax sẵn sàng
Lần delegation kế tiếp đọc llms.txt = hiểu hệ thống
ready
📐 Cấu trúc llms.txt đề xuất
# Nelson Freight System Snapshot # Generated: 2026-04-26 14:30 · Plan: phase-3-quote-redesign ## Architecture (3-tier) - CODE: D:/NELSON/2. Areas/Engine_test - DATA: D:/OneDrive/NelsonData/{erp,email,pricing,bot} - LOCAL: Engine_test/*/data (gitignored) ## Key contracts - intelligence/builder.build_email() → Email SOT - shared/paths.py → resolver - ERP/erp-v14-*.bas → VBA modules ## Recent changes (last 5 commits) - 0dd4095 fix: reefer QuoteImage empty rates - c393b54 chore: VBA R1-R9 lint pass - ... ## Active skills (top 10) - erp-governance, cook, fix, debug, ... ## Known issues - Smart Send bug (DOMAIN_MODEL.md §7)
⚙️ Hook config (settings.json)
// ~/.claude/settings.json { "hooks": { "PostToolUse": [{ "matcher": "Agent.*master-executor", "hooks": [{ "type": "command", "command": "bash ~/.claude/bin/gen-llms.sh" }] }], "Stop": [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/bin/gen-llms.sh --root" }] }] } }

Lưu ý: Hook chạy bất đồng bộ với Claude. Không block conversation. Fail-soft: nếu skill error, log warning thay vì crash.

06

Implementation roadmap (3 sprints)

Em chia 3 phase nhỏ để giảm risk. Mỗi phase có exit criteria cụ thể, có thể rollback nếu fail.

P1 Sprint 1 — VLM + Search wire

Effort: 1 ngày

  • Tạo wrapper script mm-vlm.sh, mm-search.sh bên cạnh mm-claude.sh
  • Update ck:workflow v2.1: route ux-reviewer→vlm, perf-analyzer→search
  • Test end-to-end với 1 task pilot (đọc Quote sheet screenshot)

Exit: 1 successful vlm call + 1 search call, log @ mm-wf-runs.log

P2 Sprint 2 — /ck:llms skill + hook

Effort: 2 ngày

  • Build skill .claude/skills/ck-llms/SKILL.md (extract + compress)
  • Build helper ~/.claude/bin/gen-llms.sh
  • Wire PostToolUse + Stop hooks trong settings.json
  • Test: chạy 1 plan demo, verify llms.txt sinh đúng format llmstxt.org

Exit: M2.7 đọc llms.txt (1 read) → answer "where is rate predictor?" đúng, không grep

P3 Sprint 3 — ERP unlock + benchmark

Effort: 2 ngày

  • Lift ERP/VBA safety override (theo Sếp approve)
  • Pilot test: M2.7 sửa 3 VBA function nhỏ, verify-erp.bat phải pass 7/7
  • Benchmark Opus vs M2.7 trên 5 task: code review, security audit, test gen, doc write, perf analyze
  • Update routing rule cuối cùng dựa trên data thực

Exit: Benchmark report HTML, decision matrix updated

07

Risk + mitigation

Em phải nói thẳng — thay đổi này tăng power nhưng cũng tăng risk. Mỗi risk có cách giảm thiểu.

🔴 Security false-negative
M2.7 SWE-Pro 56% → có thể bỏ sót 44% security issue phức tạp (auth bypass, XSS sneaky, prototype pollution).
Mitigation: 2-pass — M2.7 quét first → Opus final gate cho security-auditor. Tăng cost nhưng giữ safety.
🔴 ERP VBA compile fail
VBA có 9 gotchas (R1-R9). M2.7 chưa được benchmark VBA. Compile fail im lặng → ERP_Master.xlsm vỡ.
Mitigation: Bắt buộc verify-erp.bat sau mỗi VBA edit. Fail → auto-rollback git + escalate Opus.
🟡 Vision misread Quote sheet
vlm có thể đọc sai số trong Excel screenshot, nhầm column. Risk khi tạo quote dựa trên vision input.
Mitigation: Vision chỉ dùng cho UX review (layout, spacing), KHÔNG cho data extraction. Số liệu vẫn đọc từ parquet/SQLite.
🟡 llms.txt drift
Snapshot tạo lúc T, nhưng code thay đổi sau T → MiniMax đọc llms.txt bị stale, suggest sai.
Mitigation: Hook auto-regenerate sau mỗi master-executor + Stop. Header llms.txt có timestamp, M2.7 check >24h thì re-grep.
🟡 Quota burn nhanh
11 agent × auto-trigger × parallel = quota đốt nhanh. 45K/tuần có thể hết trong 2 ngày nếu run sprint dày.
Mitigation: Daily quota check via API. >80% used → throttle về Opus. Alert Sếp qua Telegram bot khi >90%.
🔵 Hook crash break Claude
Nếu hook script crash → có thể block tool execution. Đặc biệt với Stop hook chạy lúc cuối session.
Mitigation: Hook script wrap trong set +e, log to file thay vì stdout, exit 0 luôn. Fail-soft pattern.
08

Approval checklist — Sếp tick để bắt đầu

Em cần Sếp confirm 5 điểm trước khi implement (em đã save vào memory feedback_minimax_full_power.md):

Quyết định kế tiếp

A · GO ALL
Approve cả 5 — Sprint 1+2+3
Total ~5 ngày dev. Em launch workflow ngay sau khi Sếp confirm.
B · GO PARTIAL
Chỉ Sprint 1+2 (skip ERP unlock)
An toàn hơn — giữ ERP trên Opus. ~3 ngày dev.
C · PILOT FIRST
Chỉ Sprint 1 — VLM/Search benchmark
Test 1 sprint, đánh giá chất lượng vlm/search trước khi mở rộng.