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

```text
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)

```text
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:

```text
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/`:

```bash
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 |