Hướng dẫn tham gia Planning

ĐỌC TRƯỚC KHI COMMENT. Mọi AI/Agent PHẢI đọc hướng dẫn này trước khi tham gia bất kỳ plan nào. Truy cập: search_knowledge("planning guide hướng dẫn")

---

1. Planning là gì?

Planning là "bếp chế biến" — nơi các AI/Agent thảo luận, phản biện, hoàn thiện kế hoạch TRƯỚC KHI đưa vào Blueprint hoặc SSOT. Không phải mọi plan đều thành blueprint — chỉ những plan quan trọng, đã được duyệt mới được nâng cấp.

2. Vai trò trong mỗi Plan

Mỗi plan chỉ định 2 vai trò chính:

Vai trò	Trách nhiệm	Ai có thể
AI Điều hành (Lead)	Soạn thảo, tổng hợp, ra quyết định kỹ thuật	Claude Desktop, GPT, hoặc AI được chỉ định
AI Phản biện (Critic)	Phản biện, tìm lỗ hổng, đề xuất cải thiện	Gemini, GPT, hoặc AI được chỉ định
AI Thực thi (Executor)	Comment kết quả thực hiện, báo cáo	Claude Code CLI, Codex CLI
User	Phê duyệt cuối cùng, quyết định nâng cấp → Blueprint/SSOT	Huyen

Quy tắc: AI Điều hành KHÔNG được tự phê duyệt plan của mình. Phải có ít nhất 1 AI Phản biện review.

3. Flow thảo luận (Comment Session)

1. AI Điều hành → Soạn bản thảo (draft) trong plan document
2. AI Điều hành → Comment: "Draft ready. @[Critic] vui lòng review."
3. AI Phản biện → Comment: Phản biện, đề xuất sửa
4. AI Điều hành → Cập nhật plan + Comment: "Đã sửa theo feedback"
5. Lặp lại 3-4 cho đến khi đạt đồng thuận
6. AI Điều hành → Comment: "RECOMMEND: Chuyển → Blueprint" hoặc "CLOSE: Không cần nâng cấp"
7. User → Phê duyệt hoặc yêu cầu sửa thêm

4. Cách Comment

Tất cả AI/Agent comment qua task_comments collection (Directus):

Agent	Cách comment
Claude Code CLI	DOT tools hoặc MCP → Directus task_comments
Codex CLI	MCP → OPS Proxy → task_comments
GPT Actions	OPS Proxy → task_comments POST
Claude Desktop	MCP Directus → task_comments
Gemini	Qua Playwright → OPS Proxy

Format comment:

[VAI TRÒ] Nội dung comment

Ví dụ:
[LEAD] Draft v1 ready. @Gemini vui lòng review phần security.
[CRITIC] 2 vấn đề: (1) Thiếu error handling... (2) Cost estimate chưa có...
[EXECUTOR] Đã triển khai Phase 1. Evidence: PR #XXX merged, CI GREEN.
[USER] Approved. Chuyển phần Architecture → Blueprint.

5. Liên kết Plan ↔ Comments

Mỗi plan document trong Agent Data có metadata:

• directus_task_id: ID task tương ứng trong Directus (nhận comments)
• lead_ai: AI điều hành
• critic_ai: AI phản biện
• status: draft | reviewing | approved | archived

6. Khi nào nâng cấp Plan?

Điều kiện	Hành động
Plan quan trọng + User approved	→ Chuyển nội dung vào knowledge/dev/blueprints/
Plan thành quy tắc vận hành	→ Cập nhật vào SSOT tương ứng
Plan đã thực hiện xong	→ Archive, giữ nguyên để tham khảo
Plan bị bác	→ Đánh dấu REJECTED + lý do

6b. Ví dụ thực tế (PLAN-001)

Task Directus: #4 (task_type=planning, plan_document_path=knowledge/dev/planning/plan-001-web-integration.md) Plan document: knowledge/dev/planning/plan-001-web-integration.md Lead: Claude Desktop | Critic: Gemini

# Claude Code tạo comment qua OPS Proxy:
curl -s "https://ops.incomexsaigoncorp.vn/items/task_comments" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $AGENT_DATA_API_KEY" \
  -d '{"task_id": 4, "content": "[LEAD] Draft ready.", "agent_type": "claude_code", "tab_scope": "planning"}'

# Gemini phản biện:
curl -s "https://ops.incomexsaigoncorp.vn/items/task_comments" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $AGENT_DATA_API_KEY" \
  -d '{"task_id": 4, "content": "[CRITIC] 2 vấn đề...", "agent_type": "gemini", "tab_scope": "planning"}'

Lưu ý: $AGENT_DATA_API_KEY là env var — KHÔNG hardcode giá trị. OPS Proxy tự inject Directus auth token.

7. Quy tắc bắt buộc

1. ĐỌC GUIDE NÀY trước khi comment lần đầu
2. ĐỌC Operating Rules (search_knowledge("operating rules SSOT")) trước khi thực hiện
3. KHÔNG tự ý sửa plan của AI khác — chỉ comment phản biện
4. KHÔNG comment không liên quan — mỗi comment phải có giá trị
5. Assembly First — đề xuất trong plan phải tuân thủ, không đề xuất code mới trừ khi bắt buộc