Nâng cao

GSD-2 cung cấp một số cơ chế nâng cao cho phép bạn kiểm soát chi tiết quá trình thực thi - từ việc phân lập tác vụ trong git worktree riêng biệt, định nghĩa executor agent tùy chỉnh, đến cấu hình hàng đợi thực thi tự động. Phần này dành cho người dùng muốn khai thác tối đa những khả năng mà GSD-2 cung cấp.

Worktree Isolation

Khi bật chế độ Worktree Isolation, mỗi task sẽ chạy trong một git worktree riêng biệt được tạo tự động từ commit hiện tại. Toàn bộ thay đổi của task diễn ra trong worktree đó; sau khi task hoàn thành, GSD ghi lại các thay đổi dưới dạng patch và merge trở lại nhánh chính. Cơ chế này ngăn chặn hoàn toàn việc các task chạy song song hoặc tuần tự gây xung đột lên nhau.

Để bật Worktree Isolation, thêm taskIsolation.mode: 'worktree' vào PREFERENCES.md hoặc settings.json trong thư mục .gsd/. Tính năng này đặc biệt hữu ích khi dự án có nhiều file được nhiều task cùng chỉnh sửa, hoặc khi bạn muốn có khả năng rollback từng task một cách độc lập mà không ảnh hưởng đến các task khác đã hoàn thành.

# .gsd/PREFERENCES.md

taskIsolation:
  mode: worktree   # bật phân lập worktree cho mỗi task

# Khi bật, mỗi task sẽ chạy trong một git worktree riêng.
# Sau khi task hoàn thành, các thay đổi được ghi lại dưới dạng
# patch và merge trở lại nhánh chính - không có xung đột chéo task.

Custom Executor Agents

GSD-2 cho phép bạn thay thế executor agent mặc định bằng cách đặt file Markdown vào thư mục .gsd/agents/. Agent tùy chỉnh nhận toàn bộ task plan làm context, bao gồm mô tả bước thực hiện, danh sách file đầu vào, đầu ra kỳ vọng, và lệnh xác minh. Bạn có thể dùng agent tùy chỉnh để áp đặt quy ước code, ngôn ngữ ghi chú, hoặc công cụ bắt buộc phải sử dụng trong dự án.

Tên file (không có đuôi .md) là tên agent được nhận diện bởi GSD. Agent trong .gsd/agents/ có độ ưu tiên cao hơn agent toàn cục trong ~/.gsd/agent/agents/, cho phép các dự án khác nhau dùng executor khác nhau trên cùng một máy mà không xung đột.

<!-- .gsd/agents/my-executor.md -->
# My Custom Executor Agent

Bạn là executor chuyên biệt cho dự án ACME.
Khi thực thi task, ưu tiên kiểm tra thư mục packages/ trước.

## Quy ước bắt buộc
- Dùng pnpm thay cho npm khi cài dependency
- Chạy pnpm lint trước khi hoàn thành task
- Ghi chú bằng tiếng Việt trong task summary

Quality Gates

Quality gates là các câu hỏi đánh giá có cấu trúc được GSD-2 sử dụng để phát hiện rủi ro trước khi chúng trở thành lỗi thực sự. Có hai nhóm gate: Q3–Q8 được đánh giá trong quá trình lập kế hoạch slice (slice planning), còn MV01–MV04 được đánh giá khi validate milestone. Kết quả của từng gate được lưu vào database và render ra file VALIDATION.md để có thể kiểm tra và truy vết.

Mỗi gate có verdict là pass (không có vấn đề), flag (có vấn đề cần chú ý), hoặc omitted (không áp dụng cho slice này). Khi một gate trả về flag, GSD ghi nhận phát hiện chi tiết vào trường findings để executor agent có thể xử lý trong quá trình thực thi.

# Các gate được đánh giá trong slice planning (Q3–Q8)
# và trong milestone validation (MV01–MV04).

# Ví dụ: lưu kết quả gate Q5 (failure modes) sau khi đánh giá
gsd_save_gate_result({
  milestoneId: "M001",
  sliceId: "S02",
  taskId: "T01",
  gateId: "Q5",
  verdict: "pass",
  rationale: "Tất cả các điểm thất bại đã được xử lý với fallback rõ ràng.",
  findings: "## Failure Modes\n- Timeout API: trả về lỗi 503 sau 10s\n- DB offline: queue request"
})

Hàng đợi Auto Mode

Thay vì gọi lại /gsd start sau mỗi slice, bạn có thể cấu hình một hàng đợi slice trong PREFERENCES.md để auto-mode thực thi tuần tự mà không cần can thiệp thủ công. GSD-2 sẽ lần lượt hoàn thành từng slice trong queue, dừng lại khi hết queue hoặc khi gặp blocker yêu cầu quyết định từ người dùng.

Hàng đợi đặc biệt hữu ích khi bạn cần chạy nhiều slice liên tiếp qua đêm hoặc trong CI/CD. Mỗi phần tử trong queue có dạng MilestoneID/SliceID. Nếu một slice trong queue gặp escalation, auto-mode tạm dừng tại đó và chờ phản hồi trước khi tiếp tục slice kế tiếp.

# .gsd/PREFERENCES.md

autoMode:
  queue:
    - M001/S03
    - M001/S04
    - M001/S05
  # Các slice trong queue sẽ được thực thi tuần tự mà không cần
  # gọi lại /gsd start sau mỗi slice. Auto-mode dừng lại
  # khi hết queue hoặc khi gặp blocker yêu cầu can thiệp.