cowork-local/agent/README.md

Agent Library — UI/UX Bug Fixing cho Cowork Local

Bộ instruction chuyên biệt để xử lý bug UI/UX do người dùng báo trong Cowork Local (PySide6 desktop, 4-tier Clean Architecture).

Thiết kế theo Production Agent Architecture (FSG AI Core — Instruction Engineering Training): mỗi agent có Role → Mission → Input → Process → Output → Quality Gate → Self Review, và dùng chung một lớp system/ (guardrail), knowledge/ (project knowledge), checklist/, output/ (contract), examples/.

---

1. Vì sao tách như thế này

Anti-pattern mà bộ này cố tình tránh (mục 10 của tài liệu training):

Anti-pattern	Cách bộ agent này xử lý
Hard-code theo project	Rule chung nằm ở roles/, tri thức riêng của Cowork Local nằm ở knowledge/
Prompt quá dài	Mỗi role là 1 file; knowledge được tham chiếu, không copy vào từng role
Không có Output Contract	Mọi output đi qua template trong output/
Không có Quality Gate	Mỗi role có Quality Gate riêng + checklist/ dùng chung
Không có example	examples/good_fix.md và examples/bad_fix.md

Sáu role không bị tách thành 7 file nhỏ mỗi role (role/task/process/...). Lý do: phần bị lặp giữa các role chính là guardrail, knowledge và checklist — chúng đã được tách ra thành module dùng chung. Phần còn lại của mỗi role gắn chặt với nhau (process quyết định output contract, output contract quyết định quality gate), tách ra chỉ tạo thêm chỗ để lệch nhau.

---

2. Cấu trúc

agent/
├─ README.md                 ← bạn đang ở đây: index + routing map
├─ system/
│  ├─ guardrail.md           ← luật bất biến cho MỌI agent
│  ├─ security.md            ← xử lý log/screenshot/PII người dùng gửi lên
│  └─ response_policy.md     ← ngôn ngữ, format, khi nào được hỏi lại
├─ knowledge/
│  ├─ project_map.md         ← ui/ vs presentation/, tầng nào gọi được tầng nào
│  ├─ theme_tokens.md        ← luật màu sắc: KHÔNG file nào ngoài theme/ được đặt tên màu
│  ├─ i18n_rules.md          ← tr(), on_language_changed, 3 ngôn ngữ
│  ├─ screen_map.md          ← map câu chữ người dùng → màn hình → file:line
│  ├─ qt_pitfalls.md         ← 20 nguyên nhân gốc hay gặp của bug UI PySide6
│  ├─ secrets_and_config.md  ← SecretStore, schema migration, bẫy .get() trên config merge
│  └─ quality_gates.md       ← CASAN gate, lệnh chạy, test headless
├─ roles/                    ← 7 agent chuyên biệt
│  ├─ 1_ui_bug_triage.md
│  ├─ 2_ui_visual_fixer.md
│  ├─ 3_ux_flow_fixer.md
│  ├─ 4_i18n_a11y_fixer.md
│  ├─ 5_fix_implementer.md
│  ├─ 6_regression_reviewer.md
│  └─ 7_security_defect_fixer.md
├─ workflow/
│  ├─ intake_to_fix.md       ← pipeline end-to-end, ai làm gì ở bước nào
│  └─ handoff_contract.md    ← envelope truyền giữa các agent
├─ checklist/
│  ├─ ui_review.md
│  ├─ ux_review.md
│  └─ pr_readiness.md
├─ output/
│  ├─ defect_record.md       ← template hồ sơ lỗi (output của Triage)
│  ├─ fix_plan.md            ← template phương án sửa (output của Fixer)
│  ├─ fix_report.md          ← template báo cáo sau khi sửa (output của Implementer)
│  └─ pr_body.md             ← template PR khớp .gitea/PULL_REQUEST_TEMPLATE.md
└─ examples/
   ├─ good_fix.md
   └─ bad_fix.md

---

3. Bảy agent và khi nào dùng

#	Agent	Pattern	Nhận vào	Trả ra
1	UI Bug Triage	Reviewer	Lời kể lộn xộn của user, ảnh chụp màn hình, log	defect_record.md + phân loại + route
2	UI Visual Fixer	Generator	defect_record (loại visual)	fix_plan.md — layout/QSS/theme/icon/DPI
3	UX Flow Fixer	Generator	defect_record (loại flow)	fix_plan.md — luồng, trạng thái, phản hồi
4	i18n & A11y Fixer	Generator	defect_record (loại i18n/a11y)	fix_plan.md — tr(), tràn chữ, contrast, bàn phím
5	Fix Implementer	Generator	fix_plan.md	Patch thật + fix_report.md
6	Regression Reviewer	Reviewer	Patch + fix_report	Verdict PASS/FAIL + pr_body.md
7	Security Defect Fixer	Generator	defect_record (loại security)	fix_plan.md — credential, secret, migration

Đây là Multi-Agent Pattern: Triage (Planner) → Specialist → Implementer (Executor) → Reviewer. Không bỏ bước. Đặc biệt không bỏ bước 1: 80% bug UI báo lên là mô tả triệu chứng, không phải nguyên nhân.

Agent 7 là specialist thứ tư, ngang hàng 2/3/4 trong pipeline, nhưng khác ở hai điểm: nó được phép chạm config.py, infrastructure/, core/ (ba role kia bị chặn ở tầng presentation), và nó không được tự quyết chính sách bảo mật — bốn câu hỏi bắt buộc trả về cho Cowork Team.

Routing rule (Triage quyết định)

Người dùng báo lỗi
   │
   ├─ "nhìn sai / lệch / mất chữ / màu lạ / bị che"        → 2. UI Visual Fixer
   ├─ "bấm không ăn / không biết đang chạy / mất dữ liệu"  → 3. UX Flow Fixer
   ├─ "chữ tiếng Nhật bị tràn / đổi ngôn ngữ không đổi"    → 4. i18n & A11y Fixer
   ├─ "mật khẩu nằm trong code / mở khoá bằng ô trống"     → 7. Security Defect Fixer
   └─ "app crash / sai số liệu / sai nghiệp vụ"            → KHÔNG phải bug UI.
                                                             Trả về, mở issue type:bug thường.

Nhóm `security` THẮNG mọi nhóm khác: lỗi vừa lệch layout vừa lộ credential thì đi 7 trước.

---

4. Cách dùng

4.1 Dùng thủ công (mọi trợ lý AI)

Nạp theo đúng thứ tự này rồi dán bug report của user vào:

agent/system/guardrail.md
agent/system/security.md
agent/system/response_policy.md
agent/roles/<role đang dùng>.md
+ các file knowledge/ mà role đó liệt kê ở mục "KNOWLEDGE"

4.2 Dùng trong Claude Code (subagent)

Mỗi file trong roles/ có sẵn YAML frontmatter name + description. Để biến thành subagent, copy sang .claude/agents/:

mkdir -p .claude/agents
cp agent/roles/*.md .claude/agents/

Sau đó gọi bằng tên: ui-bug-triage, ui-visual-fixer, ux-flow-fixer, i18n-a11y-fixer, fix-implementer, regression-reviewer, security-defect-fixer.

4.3 Chạy cả pipeline

Xem workflow/intake_to_fix.md.

---

5. Versioning

Bộ instruction này được version bằng Git cùng source. Khi sửa một role, ghi lý do trong commit message — instruction cũng là code.

Version	Ngày	Thay đổi
1.0	2026-09-07	Bản đầu: 6 role, 6 knowledge module, 4 output contract
1.1	2026-09-07	Thêm role 7 security-defect-fixer + knowledge/secrets_and_config.md. Lý do: bộ v1.0 chỉ phủ UI/UX, nên credential hardcode phát hiện qua màn Settings bị rơi vào not-ui và không ai nhận
1.2	2026-09-07	Nạp bài học từ lần chạy thật đầu tiên (SEC-20260907-01). Bản vá của bước 5 mang một blocker mà không mục nào trong bộ v1.1 bắt được — reviewer tìm ra bằng tay. Bổ sung: secrets_and_config.md §9 (chặn rỗng, compare_digest + ASCII, và luật "API an toàn hơn thường có miền đầu vào hẹp hơn"); 6_regression_reviewer.md Bước 2.1 (ràng buộc miền đầu vào) và 4.1 (test rỗng ruột); 5_fix_implementer.md + quality_gates.md (baseline bằng comm -13 trên tên test, guard git add, và thực tế suite vốn đã đỏ 11+66); bad_fix.md ca 11-12 — hai ví dụ có thật đầu tiên trong file