coordination

Files (2)

• SKILL.md
• package.json

SKILL.md (first lines)

# Coordination Skill

## Vai trò của Coordinator

Coordinator không trực tiếp implement — Coordinator:
1. Phân tích yêu cầu và phân rã thành tasks rõ ràng
2. Phân công task cho đúng agent/người
3. Theo dõi tiến độ và unblock khi có vấn đề
4. Tổng hợp kết quả và báo cáo lên

## Quy trình điều phối

### Bước 1: Phân tích yêu cầu

Trước khi tạo task:
- Xác định **output cuối cùng** cần đạt được
- Liệt kê **dependencies** — cái gì phải xong trước cái gì
- Ước tính **complexity** và **risk** của từng phần
- Xác định ai/agent nào có đủ khả năng cho từng task

### Bước 2: Phân rã task

Mỗi task phải đáp ứng:
- **Atomic**: một đơn vị công việc có thể hoàn thành độc lập
- **Verifiable**: có tiêu chí rõ ràng để biết đã done
- **Sized right**: không quá nhỏ (overhead lớn) và không quá lớn (khó track)
- **Clear owner**: đúng một agent/người chịu trách nhiệm

```
# Task tốt
title: "Implement POST /api/vault/tasks endpoint"
acceptance_criteria:
  - Returns 201 với task object
  - Validates required fields (title, column)
  - Writes file vào vault/shared/tasks/
  - Unit test coverage ≥ 80%

# Task xấu  
title: "Build the backend"
```

### Bước 3: Xác định dependency graph

```
task-A ──► task-B ──► task-D
task-C ──────────────►task-D
```

- Tasks không có dependency: chạy song song
- Tasks có dependency: chạy tuần tự
- Tránh circular dependency

### Bước 4: Dispatch và monitoring

- Assign task với đầy đủ context: links, specs, examples
- Heartbeat check định kỳ (~10 phút) — đừng để agent bị block im lặng
- Unblock chủ động: nếu agent hỏi → trả lời ngay, không để pending

### Bước 5: Handoff và tổng hợp

Khi nhận kết quả từ agent:
1. Verify output có đáp ứng acceptance criteria không
2. Test smoke nhanh nếu là code/API
3. Note lại bất kỳ deviation nào từ spec
4. Tổng hợp kết quả từ nhiều agents thành coherent whole

## Xử lý blockers

| Tình huống | Hành động |
|---|---|
| Agent blocked vì thiếu info | Cung cấp ngay, update task với context mới |
| Agent blocked vì dependency chưa xong | Requeue sau khi dependency done |
| Agent conflict (hai agent cùng edit) | Dùng optimistic lock, agent sau đọc lại state mới |
| Agent fail / không respond | Unassign, reassign hoặc escalate |
| Scope creep | Reject — tạo task mới cho phần bổ sung |

## Conflict Resolution

Khi hai agents làm việc trên cùng resource:
1. Vault dùng optimistic lock (`locked_by`, `lock_expires_at`)
2. Agent sau phải đọc lại state hiện tại trước khi apply changes
3. Merge conflict trong markdown: lấy version mới hơn làm base, apply diff

## Communication protocol

- **Claim**: khi bắt đầu task → cập nhật status `in-progress`
- **Heartbeat**: mỗi 10 phút khi active → signal "còn sống"
- **Request approval**: khi cần human review → dừng, không tự tiếp tục
- **Done**: khi xong → update progress 100, cung cấp result summary

## Metrics để track

- **Cycle time**: từ `todo` đến `done` mỗi task
- **Block rate**: % tasks bị blocked / tổng tasks
- **Approval rate**: % tasks cần re-review
- **Parallel utilization**: số agents chạy song song / capacity

## Checklist trước khi dispatch

- [ ] Task có acceptance criteria rõ ràng
- [ ] Dependencies đã resolved hoặc được ghi rõ
- [ ] Agent có đủ context (links, specs, examples)
- [ ] Không có ambiguity về scope
- [ ] Đã estimate effort / deadline nếu có

From amas-nghia/relayhq, MIT.

More from amas-nghia/relayhq