# Agent Teamwork

**Một sếp lập kế hoạch, nhiều nhân viên thực thi, sếp kiểm chứng và tích hợp.**
Mặc định: GPT-6.1 Sol quản lý trong Codex, Gemini 3.8 Flash (High) làm việc qua
Antigravity CLI. Vai trò không khóa vào tên model; các phiên worker độc lập với
chat đang mở trong Antigravity IDE.

Đưa link repo này cho một agent có terminal trên máy và nói:

> Đọc SETUP.md của repo này, cài kết nối và skill teamwork trên máy hiện tại,
> kiểm tra bằng doctor. Chỉ bắt đầu teamwork khi tôi gọi /teamwork hoặc $teamwork.

## Cài nhanh

Yêu cầu: Git, [uv](https://docs.astral.sh/uv/getting-started/installation/),
[Antigravity CLI](https://www.antigravity.google/docs/cli/install/) đã đăng nhập.
Python 3.11+ được uv quản lý. Nếu dùng Codex tự đăng ký MCP, cần Codex CLI.

```sh
git clone https://github.com/xuankhanh24/agent-teamwork.git
cd agent-teamwork
uv sync --locked
uv run python install.py --register-codex
uv run python install.py --doctor --online
```

Mở lại chat hoặc reload MCP/skills nếu host chưa nhận tool. Agent có thể dùng client
cục bộ ngay mà không cần chờ reload. Xem [SETUP.md](SETUP.md) cho Windows, Linux/macOS,
host MCP khác, gỡ cài đặt và khôi phục bản trước. Đăng nhập mới cần người dùng hoàn tất.

## Dùng

```text
/teamwork thêm chức năng X, chia việc và kiểm tra trước khi tích hợp
$teamwork điều tra lỗi Y rồi giao Gemini sửa phần đã xác định
/teamwork status
/teamwork monitor
/teamwork stop
/teamwork resume <session-id>
```

Codex dùng `$teamwork` để gọi skill. `/teamwork` là câu lệnh văn bản được skill hiểu
khi host chuyển nó tới agent; không phải host nào cũng thêm một mục slash command.
Skill có `allow_implicit_invocation: false` và server yêu cầu phiên active trước khi
giao việc. Cài đặt không tự gọi model. Việc nhận biết ý định người dùng do manager đảm
nhiệm; MCP không xác thực được câu lệnh của con người từ một session ID.

```mermaid
flowchart TD
    U[Người dùng: mục tiêu và ưu tiên] --> M[Sếp: phân tích, kế hoạch, mentor]
    M --> B[MCP cục bộ + SQLite + nhật ký]
    B --> W1[Nhân viên A / worktree A]
    B --> W2[Nhân viên B / worktree B]
    W1 --> R[Sếp: theo dõi tiến độ + kiểm tra sản phẩm thật]
    W2 --> R
    R -->|Cần sửa| B
    R -->|Đạt| I[Sếp: tích hợp + kiểm tra lại]
    I --> U
```

## Khả năng và giới hạn

Skill và bộ định tuyến `/teamwork` được cài toàn cục cho người dùng Codex; dùng
project của chat hiện tại, không cần cài lại từng repo. Git subfolder được nhận diện
về repo root. Project chưa có Git/commit vẫn dùng được với read_only hoặc bản sao
các file được chọn; bridge không tự khởi tạo Git.

`/teamwork monitor` mở bảng theo dõi trực tiếp, tự cập nhật mỗi 2 giây:

- Mục tiêu, plan và nhiệm vụ của từng project.
- Sếp giao gì, yêu cầu sửa gì, đánh giá tiến độ và quyết định gì.
- Nhân viên đang dùng công cụ nào, thông số gọi công cụ, kết quả và lỗi.
- Heartbeat, thời gian không có sự kiện mới, báo cáo công khai.
- Tiêu chí sản phẩm sếp đã kiểm chứng và bằng chứng thực tế.

Sếp phải theo dõi tiến độ và trực tiếp kiểm tra sản phẩm theo mục tiêu: thao tác UI,
chạy luồng API, xem output đã render hoặc kiểm tra hành vi phù hợp. Approval yêu cầu
từng tiêu chí đạt với fingerprint của sản phẩm hiện tại; file đổi thì phải kiểm tra lại.
Các lời giải thích và lý do quyết định công khai được hiển thị. Suy luận nội bộ riêng
tư không được lưu/hiển thị. Heartbeat không chứng minh sản phẩm đã tiến triển.

Xem [hướng dẫn bảng theo dõi](docs/MONITORING.md).

| Thành phần | Hành vi |
|---|---|
| Kích hoạt | Chỉ theo yêu cầu rõ ràng; start, stop, resume, complete |
| Phân công | Mục tiêu, phạm vi file, tiêu chí nghiệm thu, plan lưu bền |
| Nhiều nhân viên | Mặc định 2, cấu hình 1–8; chặn phạm vi chỉnh sửa chồng nhau |
| Phụ thuộc | Chỉ giao phần sau khi phần trước được tích hợp; manager điều phối |
| Kiểm chứng | Scope audit, báo tool bị từ chối, duyệt kèm bằng chứng và fingerprint |
| Phục hồi | SQLite WAL, log từng attempt, nhận diện process bằng PID + thời gian tạo |
| Chống giao trùng | request_key ổn định trong một session khi kết nối lại |
| Giới hạn | 900 giây/attempt, 3 attempt/task, 20 task/session; không phải ngân sách USD/token cứng |
| Đổi model | Profile cấu hình; mỗi task giữ model/executable/limits lúc giao |
| Tích hợp | Manager thực hiện; bridge chỉ ghi nhận, không tự merge/push/deploy |

Worker có thể hoàn thành sau khi đóng chat. Sếp không tự thức dậy hoặc giám sát 24/7.
Worktree và `plan`/`accept-edits` là cơ chế tổ chức và quyền công cụ, không phải sandbox
hệ điều hành. Scope audit phát hiện thay đổi sau khi chạy, không ngăn truy cập hệ thống.
Chỉ adapter Antigravity được triển khai; model khác có trong `agy models` dùng cùng
adapter, provider khác cần adapter mới. Một agent chỉ có chat trên cloud cần local
executor/MCP host trước khi có thể chạy cầu nối này.

## Tài liệu

- [Cài đặt cho agent](SETUP.md)
- [Quy trình sếp–nhân viên](skills/teamwork/references/workflow.md)
- [Tình huống teamwork](docs/TEAMWORK-SCENARIOS.md)
- [Thiết kế, API và lựa chọn kỹ thuật](docs/ARCHITECTURE.md)
- [Ví dụ giao việc](examples/assignment.json)
- [Kiểm chứng bản phát hành](docs/VALIDATION.md)

State/config/log nằm ngoài source repo; không chứa credentials trong mã nguồn.
Không sửa AGENTS.md của dự án khác khi cài. MIT license.