@damphuquy/agent-init 1.4.4 → 2.0.0

package/templates/vi/process/development-protocols/orchestration.md

@@ -1,24 +1,101 @@
-# Giao Thức Phân Công & Điều Phối Subagent (Orchestration Protocol)
+# Giao Thức Phân Công & Điều Phối Subagent (Subagent Orchestration Protocol)
 
-<orchestration_protocol version="1.0">
+<orchestration_protocol version="2.0">
 
 <description>
-  Hướng dẫn phân công nhiệm vụ, cách ly và phối hợp subagent trong các task phức tạp.
+  Hướng dẫn kỹ thuật phân công nhiệm vụ, cô lập phạm vi và phối hợp subagent trong các tác vụ phức tạp nhiều giai đoạn. Dùng chung cho mọi dự án.
 </description>
 
-## 1. Nguyên Tắc Phân Công (Delegation Principles)
-<delegation_rules>
-  <rule id="explicit_scope">
-    Luôn chỉ định danh sách file chính xác, chữ ký hàm (function signatures) và định dạng đầu ra có cấu trúc kỳ vọng.
+---
+
+## 1. Tiêu Chí Phân Công & Phân Luồng Tác Vụ (Delegation Criteria)
+
+<delegation_criteria>
+  Subagent chỉ nên được khởi tạo có chủ đích cho các tác vụ con có ranh giới rõ ràng, đòn bẩy cao. TUYỆT ĐỐI KHÔNG khởi tạo subagent cho các bước thực thi nhỏ nhặt, tầm thường.
+
+  ### Khi nào NÊN ủy quyền cho Subagent:
+  - **Khảo sát chuyên sâu độc lập (Research Spikes):** Tìm hiểu thư viện lạ, kiểm toán hệ thống cũ (legacy), hoặc đọc tài liệu mà không làm rác cửa sổ ngữ cảnh của Agent cha.
+  - **Kiểm toán chất lượng chuyên biệt:** Kiểm toán lỗ hổng bảo mật độc lập, đánh giá khả năng tiếp cận (accessibility - a11y), hoặc rà soát lint/format nghiêm ngặt.
+  - **Viết kiểm thử trực giao độc lập:** Viết các bài kiểm thử đơn vị độc lập hoặc fixtures khung test cho một hợp đồng giao diện đã được đóng băng.
+  - **Thực thi các lát cắt song song, không chồng chéo:** Triển khai các thành phần độc lập tác động lên các ranh giới tệp riêng biệt hoàn toàn.
+
+  ### Khi nào Agent cha BẮT BUỘC tự thực hiện (KHÔNG phân công):
+  - **Đánh đổi & Ra quyết định kiến trúc:** Soạn thảo các phương án trong `decision.md` và trình ký Gate 1.
+  - **Hợp đồng Task Master & Lập kế hoạch:** Định nghĩa `task.md`, hợp đồng lát cắt trong `plan.md` và trình ký Gate 2.
+  - **Cổng chất lượng & Phê duyệt của người dùng:** Thực hiện kiểm toán Gate 3 và sinh bản bàn giao cuối cùng `handoff.md`.
+  - **Tương tác làm rõ với người dùng:** Bất kỳ trao đổi nào cần sự định hướng hoặc phê duyệt trực tiếp từ con người.
+</delegation_criteria>
+
+---
+
+## 2. Ranh Giới Ngữ Cảnh & Quy Tắc Khoanh Vùng (Context Containment)
+
+<context_containment>
+  <rule id="explicit_file_manifest">
+    Luôn cung cấp cho subagent danh sách đường dẫn tệp cụ thể cần đọc hoặc chỉnh sửa. Tuyệt đối không ra lệnh mơ hồ như "hãy khám phá dự án" hay "quét toàn bộ codebase".
+  </rule>
+
+  <rule id="port_and_interface_focus">
+    Giới hạn dữ liệu đầu vào của subagent trong phạm vi các giao diện cổng (port interfaces), thực thể domain và bộ test đi kèm. Tránh đưa các chi tiết hạ tầng không cần thiết vào prompt của subagent.
+  </rule>
+
+  <rule id="structured_output_contract">
+    Luôn yêu cầu định dạng đầu ra có cấu trúc từ subagent (ví dụ: unified git diff, danh sách phát hiện phân loại theo Confirmed/Observed/Hypothesized, hoặc bảng markdown).
+  </rule>
+</context_containment>
+
+---
+
+## 3. Đồng Thời, Cách Ly & Quyền Ghi File (Concurrency & Isolation)
+
+<concurrency_and_isolation>
+  <rule id="zero_write_collision">
+    Nhiều subagent TUYỆT ĐỐI KHÔNG BAO GIỜ được cấp quyền ghi vào cùng một file hoặc cùng một bảng cơ sở dữ liệu đồng thời. Sửa đè file gây ra xung đột merge và lỗi hồi quy âm thầm.
+  </rule>
+
+  <rule id="read_only_by_default">
+    Mặc định subagent ở chế độ CHỈ ĐỌC (read-only) bất cứ khi nào có thể (khảo sát, đọc code, kiểm toán). Chỉ cấp quyền ghi khi các file mục tiêu hoàn toàn độc lập và thuộc quyền quản lý của riêng subagent đó.
+  </rule>
+
+  <rule id="workspace_isolation">
+    Nếu môi trường hỗ trợ không gian làm việc cách ly (branch hoặc worktree mode), hãy sử dụng để thử nghiệm các spike thăm dò nhằm bảo vệ cây làm việc chính luôn sạch sẽ.
+  </rule>
+</concurrency_and_isolation>
+
+---
+
+## 4. Đồng Bộ Trạng Thái & Tích Hợp Lại Về Agent Cha (State Synchronization)
+
+<state_synchronization>
+  <rule id="parent_owns_master_state">
+    Subagent TUYỆT ĐỐI KHÔNG trực tiếp chỉnh sửa các artifact quản lý của Agent cha (`task.md`, `state.md`, `review.md`). Chỉ Agent cha mới có thẩm quyền tổng hợp kết quả của subagent vào các tệp trạng thái master.
+  </rule>
+
+  <rule id="verification_before_acceptance">
+    Khi subagent trả về mã nguồn đã sửa đổi hoặc kết quả khảo sát, Agent cha phải trực tiếp kiểm tra git diff và chạy lệnh verifier của lát cắt tương ứng trước khi chấp nhận kết quả.
+  </rule>
+
+  <rule id="evidence_crystallization">
+    Trích xuất các bằng chứng đã xác minh từ báo cáo của subagent và ghi vào `state.md > <verification_evidence>`. Loại bỏ các log hội thoại tạm thời của subagent để bảo vệ sự tinh gọn của ngữ cảnh.
+  </rule>
+</state_synchronization>
+
+---
+
+## 5. Điều Phối Phản Ứng, Giới Hạn & Phục Hồi Lỗi (Coordination & Recovery)
+
+<coordination_and_recovery>
+  <rule id="no_polling_loops">
+    Tuyệt đối không viết vòng lặp kiểm tra trạng thái (`while true; sleep 5; check_status`) để chờ subagent. Dựa vào cơ chế đánh thức qua tin nhắn phản ứng (reactive message wakeup) của hệ thống khi subagent hoàn thành.
   </rule>
 
-  <rule id="context_containment">
-    Không cấp quyền truy cập repository không giới hạn; giới hạn ngữ cảnh của subagent trong phạm vi các bộ test suite liên quan và hợp đồng giao diện cổng.
+  <rule id="retry_budget_enforcement">
+    Nếu subagent gặp lỗi công cụ hoặc thất bại lặp đi lặp lại, áp dụng nghiêm ngặt ngân sách thử lại tối đa 3 lần. Nếu cạn ngân sách, ghi dấu vết lỗi vào `state.md > <failure_memory>` và dừng lại báo cáo người dùng.
   </rule>
 
-  <rule id="no_polling">
-    Dựa vào cơ chế đánh thức qua tin nhắn phản ứng (reactive message wakeup) của hệ thống khi subagent hoàn thành việc thực thi.
+  <rule id="teardown_and_cleanup">
+    Giải phóng sạch sẽ các subagent nhàn rỗi hoặc bị lỗi. Đảm bảo toàn bộ tệp nháp tạm thời (scratch) hoặc branch thử nghiệm do subagent tạo ra được dọn dẹp trước khi hoàn thành lát cắt.
   </rule>
-</delegation_rules>
+</coordination_and_recovery>
 
 </orchestration_protocol>