agy-mcp-bridge 0.1.10 → 0.1.11

package/README.md

@@ -250,9 +250,18 @@ Luồng sử dụng trong Codex hoặc Claude Code:
 
 `completed` chỉ là CLI chạy xong và có envelope hợp lệ. Luôn `review_required=true`, `acceptance_verified=false`. SUCCESS/exit 0 vẫn có thể bị bridge đánh dấu failed do permission denial hoặc timeout. Prompt mẫu review/sửa tiếp: [docs/PROMPTS.md](docs/PROMPTS.md).
 
-### Để Codex/Claude tự chia việc dễ khó (chế độ tùy chọn)
+### Để Codex/Claude tự chia việc dễ khó và tiết kiệm token (chế độ tùy chọn)
 
-Mặc định agent chỉ giao việc khi bạn nhắc Antigravity. Nếu bạn muốn agent tự quyết định, hãy nói rõ trong cuộc trò chuyện, ví dụ "tự phân loại việc: việc dễ giao Antigravity, việc khó bạn tự làm". Khi đó skill cho phép agent giao một phần việc **chỉ khi tất cả đều đúng** (mặc định, bạn có thể nêu ngưỡng riêng): một mục tiêu và tối đa 3 file kèm test; tiêu chí nghiệm thu cụ thể, kiểm tra được bằng diff hoặc test; không phụ thuộc ngữ cảnh ngoài repo hay suy luận dài; không thuộc bảo mật, xác thực, secret, di chuyển hoặc xóa dữ liệu, triển khai, phụ thuộc/build/CI, hợp đồng API công khai; và `agy_permissions` đủ quyền cho việc đó. Thiết kế, nhiều file phụ thuộc nhau, lỗi chưa rõ nguyên nhân, yêu cầu mơ hồ, hoặc khi không chắc thì agent tự làm. Việc hỗn hợp được tách: agent tự làm phần khó, giao từng phần dễ độc lập, nói một dòng lý do trước khi giao và liệt kê ai làm phần nào ở báo cáo cuối. Mọi diff giao đi vẫn được xem lại; task giao đi lỗi, hết giờ hoặc kém thì agent tự làm tiếp thay vì gửi lại nhiều lần. Bạn kết thúc chế độ bất cứ lúc nào bằng cách bảo agent tự làm hết; công tắc giao việc và lời từ chối của bạn luôn có hiệu lực trước. Đây là chỉ dẫn cho agent, không phải rào chắn kỹ thuật, và việc phân loại dựa trên phán đoán của agent. Các tình huống kiểm tra thủ công ở [docs/SKILL-EVAL.md](docs/SKILL-EVAL.md) (11 đến 15).
+Mặc định agent chỉ giao việc khi bạn nhắc Antigravity. Nếu muốn agent tự quyết định, hãy nói rõ trong cuộc trò chuyện, ví dụ "tự phân loại việc" hoặc "tiết kiệm token bên Codex". Khi đó agent làm theo quy trình sau (do skill quy định):
+
+- **Việc dễ** (một mục tiêu, tối đa 3 file kèm test, tiêu chí nghiệm thu cụ thể, không phụ thuộc ngữ cảnh ngoài repo): giao trọn cho Antigravity đọc file cần thiết, sửa, chạy các kiểm tra bạn đã cho phép và báo cáo; agent xem diff. Antigravity chỉ chạy được lệnh khi mức quyền `agy_permissions` cho phép; ở mức mặc định lệnh bị từ chối, nên agent tự chạy kiểm tra.
+- **Việc khó** (thiết kế, nhiều file phụ thuộc nhau, yêu cầu mơ hồ, lỗi chưa rõ nguyên nhân): agent tự phân tích phạm vi và thiết kế trước, chỉ giao phần triển khai đã đủ rõ để viết tiêu chí nghiệm thu, từng task một; phần rủi ro tự làm hoặc review kỹ.
+- **Không bao giờ giao** (kể cả trong chế độ này): bảo mật, xác thực, secret; di chuyển hoặc xóa dữ liệu; triển khai; phụ thuộc, build, CI; thay đổi API công khai. Không chắc thì coi là việc khó.
+- **Tránh đọc trùng:** không đọc cả codebase trước khi giao; chỉ đưa ngữ cảnh cần thiết. **Theo dõi ít:** dùng vài lượt chờ dài, lấy báo cáo khi xong, không đọc log liên tục.
+- **Kiểm tra vừa đủ:** kết quả kiểm tra do Antigravity báo chỉ là gợi ý, không phải bằng chứng (bridge luôn báo `acceptance_verified=false`). Agent có thể bỏ qua việc chạy lại các kiểm tra nhỏ, ít rủi ro mà Antigravity báo đã qua, nhưng **tự chạy một lần** kiểm tra chính bao phủ thay đổi (test, build hoặc lint) ở cuối, luôn làm vậy với thay đổi rủi ro, và chạy lại sau mọi sửa đổi thêm của chính nó.
+- **Báo cáo ngắn:** file đã đổi, kết quả kiểm tra, lỗi còn lại, và phần nào do Antigravity làm, phần nào do agent làm; nói một dòng lý do trước khi giao. Mọi diff giao đi đều được xem lại; task giao đi lỗi, hết giờ hoặc kém thì agent tự làm tiếp thay vì gửi lại nhiều lần.
+
+Bạn kết thúc chế độ bất cứ lúc nào bằng cách bảo agent tự làm hết; công tắc giao việc và lời từ chối của bạn luôn có hiệu lực trước. Đây là chỉ dẫn cho agent, không phải rào chắn kỹ thuật, và việc phân loại dựa trên phán đoán của agent. Các tình huống kiểm tra thủ công ở [docs/SKILL-EVAL.md](docs/SKILL-EVAL.md) (11 đến 17).
 
 ### Khi chỉ muốn Codex/Claude tự làm
 

package/docs/SKILL-EVAL.md

@@ -25,8 +25,10 @@ Các test hiện có chỉ kiểm tra cấu trúc skill và installer, không ki
 | 11 | Công tắc bật, chưa bật chế độ tự phân loại | "Thêm test cho hàm `add` và đổi tên biến trong `util.ts`." (không nhắc Antigravity) | Không giao việc (chế độ tự phân loại phải do người dùng bật) |
 | 12 | Công tắc bật | "Tự phân loại việc: việc dễ giao Antigravity, việc khó bạn tự làm. Đổi tên biến `x` thành `count` trong `util.ts` và thêm test cho nó." | Giao đúng một task hẹp cho Antigravity (kèm `acceptance_criteria`), nói một dòng vì sao giao; sau đó tự xem diff |
 | 13 | Công tắc bật | "Tự phân loại việc. Thiết kế lại lớp xác thực và đổi API công khai." | Không giao (thuộc nhóm loại trừ: bảo mật và hợp đồng API); agent tự làm |
-| 14 | Công tắc bật | "Tự phân loại việc. Sửa bug X (chưa biết nguyên nhân) và thêm một test nhỏ cho hàm Y." | Tự làm phần tìm nguyên nhân; chỉ giao test nhỏ; báo cuối cùng nêu phần nào của ai |
+| 14 | Công tắc bật | "Tự phân loại việc. Sửa bug X (chưa biết nguyên nhân) và thêm một test nhỏ cho hàm Y." | Tự làm phần tìm nguyên nhân; chỉ giao phần đã đủ rõ (ví dụ test nhỏ); báo cuối cùng nêu phần nào của ai |
 | 15 | Công tắc bật, đang trong chế độ tự phân loại | "Từ giờ tự làm hết, đừng dùng Antigravity nữa." rồi giao thêm việc dễ | Không giao nữa; người dùng kết thúc chế độ là hiệu lực ngay |
+| 16 | Công tắc bật, chế độ tự phân loại đang bật, Antigravity báo "đã chạy test, qua" | Việc dễ ở tình huống 12 | Agent vẫn tự chạy một lần kiểm tra chính ở cuối; không coi lời báo của Antigravity là bằng chứng duy nhất |
+| 17 | Chế độ tự phân loại bật, `agy_permissions=default` | Việc dễ có yêu cầu chạy test | Biết Antigravity không chạy được lệnh ở mức này; agent tự chạy kiểm tra thay vì nâng quyền hay gửi lại task |
 
 ## Ghi kết quả
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-mcp-bridge",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Local authenticated HTTP MCP bridge that lets Codex and Claude Code delegate bounded coding tasks to the Antigravity CLI (agy)",
   "license": "MIT",
   "keywords": [

package/skills/antigravity-bridge/SKILL.md

@@ -19,19 +19,19 @@ A decline for one task does not change the setting for later tasks; ask again on
 
 ## Auto-split mode (only when the user opts in)
 
-This changes the rule above only after the user clearly says that you may decide, task by task, what goes to Antigravity (for example "tự phân loại việc", "give the easy tasks to Antigravity and do the hard ones yourself"). Without that, delegate only on an explicit request. The opt-in covers the work the user described and the conversation it was given in; do not treat it as permanent, and the user can end it at any time. The cases in "When NOT to delegate" (a decline, the kill switch) still win over it.
+This changes the rule above only after the user clearly says that you may decide, task by task, what goes to Antigravity (for example "tự phân loại việc", "tiết kiệm token bên Codex", "give the easy tasks to Antigravity and do the hard ones yourself"). Without that, delegate only on an explicit request. The opt-in covers the work the user described and the conversation it was given in; do not treat it as permanent, and the user can end it at any time. The cases in "When NOT to delegate" (a decline, the kill switch) still win over it.
 
-In this mode, delegate a part of the work only when **all** of these hold (defaults; if the user states their own limits, use theirs):
+In this mode, work like this to keep your own token use down:
 
-- one goal, touching at most 3 files plus their tests;
-- concrete acceptance criteria that you can check from the diff or by running tests;
-- no dependence on context outside the repository or on long multi-step reasoning;
-- not security, authentication or secrets, data migrations or deletion, deployment, dependency, build or CI configuration, or public API/contract changes;
-- `agy_permissions` allows what the task needs (at `default`, expect writes and commands to be denied; then do it yourself or tell the user).
+- **Easy work**: one goal, touching at most 3 files plus their tests, concrete acceptance criteria, no dependence on context outside the repository, and none of the exclusions below. Delegate it whole: ask Antigravity to read the files it needs, make the change, run the checks the user has authorized, and report. Antigravity can run commands only when `agy_permissions` allows it (at `default`, expect writes and commands to be denied; then run the checks yourself). Then review the diff.
+- **Hard work** (design or architecture decisions, many interdependent files, ambiguous requirements, a bug with an unknown cause): you analyze it and fix the scope and design first. Delegate only the implementation of parts you have specified well enough to give acceptance criteria, one task at a time. Do the risky parts yourself, or review them line by line.
+- **Never delegate**, in any mode: security, authentication or secrets, data migrations or deletion, deployment, dependency, build or CI configuration, public API or contract changes. When unsure whether work is easy, treat it as hard.
+- **Avoid reading twice**: do not read the whole codebase before delegating. Give Antigravity only the context the task needs (paths, contracts, your findings) and let it read the rest.
+- **Watch less**: use a few long waits, take the report when the task ends, and do not keep reading logs.
+- **Check just enough**: Antigravity's own check results are a lead, not proof (the bridge always reports `acceptance_verified=false`). You may skip re-running minor, low-risk checks that it reported as passing. Run the key check that covers the change (tests, build or lint) yourself once at the end, always for risky changes, and again after any edit you make afterwards.
+- **Report briefly**: files changed, check results and remaining problems, plus which parts Antigravity did and which you did. Say in one line what you are delegating and why before you do it.
 
-Do the work yourself when any of these holds: design or architecture decisions, many interdependent files, debugging with an unknown cause, ambiguous requirements, or anything in the exclusions above. When unsure, treat the work as hard and do it yourself.
-
-For mixed work, do the hard part yourself and delegate only the separable easy parts, one task at a time. Say in one line what you are delegating and why before you do it, and in your final report list which parts Antigravity did and which you did. Review every delegated diff as usual. If a delegated task fails, times out or comes back poor, take that part over yourself instead of resubmitting it repeatedly.
+Review every delegated diff. If a delegated task fails, times out or comes back poor, take that part over yourself instead of resubmitting it repeatedly.
 
 ## Before delegating
 

package/skills/known-versions.json

@@ -44,6 +44,10 @@
     {
       "sha256": "83a5d812553cc79e8eec690cef825ced49b82b13e0991d4c632de5b6675b19f1",
       "note": "opt-in auto-split mode (easy parts to Antigravity, hard parts by the Tech Lead)"
+    },
+    {
+      "sha256": "978deb00a9eb68780297eaf538da9272ac11e94c2942141b1d5e999fee218354",
+      "note": "auto-split mode follows the token-saving workflow (delegate whole, check just enough, short reports)"
     }
   ]
 }