SỔ TAY FLOW & USE CASE THỰC CHIẾN — AGILE 6-ROLE SQUAD

  • Bạn chỉ giao việc: Tôi (/squad) tự bật Squad, tự điều phối 6 Agents & báo cáo tiến độ.
  • Ép 100% Full Flow: Họp /bmad-party-mode + phỏng vấn /grill-me từng câu 1.
  • Tách bạch TDD: Bước 5 (Viết & Khóa Test RED) ➔ Bước 6 (Viết Code GREEN).
🎖️ Auto Step 1: spawn-squad --ensure 🎤 /grill-me 1-by-1 🔴 Bước 5: TDD RED 🟢 Bước 6: TDD GREEN
1. Flow Điều Phối Tổng Quan (Bạn ➔ Điều Phối Viên /squad ➔ 6 Agents)
Ngắn gọn • Không thao tác tay • Mọi báo cáo quy về 1 mối

👤 CHẶNG 1: BẠN (STAKEHOLDER)

  • 1. Giao bài toán: Gõ /squad <yêu cầu>.
  • 2. Trả lời /grill-me: Chọn phương án (Recommended) từng câu 1.
  • 3. Chốt & Nghiệm thu: Gõ "OK chốt" ➔ Nhận link PR sạch để Merge.
➔

🎖️ CHẶNG 2: TÔI — ĐIỀU PHỐI VIÊN (/squad)

  • Tự động Bước 1: Chạy spawn-squad --ensure vinasat-1 nếu Squad chưa bật.
  • Chủ trì /grill-me: Quét codebase trước, hỏi bạn từng câu 1 cho đến khi rõ 100%.
  • Điều phối & Báo cáo: Bắn lệnh qua squad-msg, theo dõi qua squad-status.
➔

🛰️ CHẶNG 3: ĐỘI HÌNH 6 PANES (HERDR + BMAD)

  • [1] PO-Bao Long + [2] SA-Minh Tri: Khóa prd.md, architecture.md (OpenAPI) & .story.md.
  • [4] BE-Quoc Huy + [5] FE-Hoang Nam: Bước 5 (Khóa Test RED) ➔ Bước 6 (Code GREEN trên Worktree).
  • [2] SA (Gate 3.5) ➔ [6] QA-Mai Linh (Gate 4): Duyệt kiến trúc, test API & Browser E2E.
1B. Mô Hình Ủy Quyền 2 Tầng (2-Tier Delegation)
Orchestrator chỉ điều phối • Agent trong Squad được dùng Subagent nhẹ nội bộ

🚫 TẦNG 1 — ORCHESTRATOR (/squad)

  • BẮT BUỘC: Mọi lệnh /squad <task> phải chuyển giao qua Herdr Squad Team (spawn-squad --ensure → squad-msg).
  • CẤM: Orchestrator KHÔNG ĐƯỢC tự spawn subagent nội bộ để làm thay công việc của PO, SA, SM, BE, FE, QA.
  • Vai trò: Điều phối, theo dõi tiến độ, báo cáo → Không thực thi.
⬇

✅ TẦNG 2 — NỘI BỘ TỪNG AGENT (SA, QA, PO, BE, FE, SM)

  • ĐƯỢC PHÉP: Mỗi Agent trên Herdr chủ động dùng subagent nhẹ (research / flash / haiku) cho việc phụ trợ.
  • Ví dụ: SA spawn research subagent đọc 20 file codebase → Trả kết quả tóm tắt về SA → SA ra quyết định kiến trúc.
  • Lợi ích: Bảo vệ Context Window Tier-1 (SA), tiết kiệm 60-80% token, tăng tốc quét code song song.
  • Ranh giới: Subagent chỉ trả data về Agent gọi nó — KHÔNG ghi _bmad-output/, KHÔNG liên lạc với Role khác.
2. Sơ Đồ Flow 9 Bước Thực Thi Chuẩn Hóa
Bước 1 tự động • Bước 3 hỏi /grill-me • Bước 5 viết Test RED • Bước 6 viết Code GREEN
BƯỚC 1 • AUTO🎖️ Điều Phối Viên
Tự Động Bật Squad 6 Panes
  • Kiểm tra Herdr: nếu VINASAT-1 đã mở đủ 6 panes thì dùng luôn.
  • Nếu chưa mở: tự chạy squad-init, bật 6 panes, đợi cả 6 báo idle.
spawn-squad --ensure vinasat-1
BƯỚC 2 • INTAKE👤 Bạn ➔ 🎖️ /squad
Nhận Việc ➔ Ép 100% Full Flow
  • Bạn mô tả tính năng/bug cần làm.
  • Mặc định kích hoạt Full Flow (không đi tắt).
  • Tự động quét codebase bằng codebase-memory-mcp.
/squad <Mô tả tính năng>
BƯỚC 3 • GRILL-ME📋 PO + 🏛️ SA ↔ 👤 Bạn
Họp Team & Hỏi Từng Câu 1
  • 5 Roles tổng hợp góc nhìn & rủi ro kỹ thuật.
  • Hỏi bạn từng câu 1 kèm phương án (Recommended).
  • Bạn gõ "OK chốt" ➔ Khóa prd.md & architecture.md (OpenAPI).
/bmad-party-mode + /grill-me
BƯỚC 4 • SHARDING📋 PO + 🎯 SM
Tách Story & Tạo Git Worktree
  • Tách file _bmad-output/stories/*.story.md cho BE & FE.
  • Đính kèm tiêu chí BDD (Given/When/Then).
  • Tạo Git Worktree riêng (.worktrees/<id>) chống đụng branch.
sprint-status.yaml ➔ ready-for-dev
BƯỚC 5 • TDD RED 🔴⚙️ BE + 🎨 FE
Viết & Khóa Bộ Test Fail Trước
  • 5a: Tạo hàm/route stub 501 & import OpenAPI types.
  • 5b: Viết 100% Unit/API/Component test theo Given/When/Then.
  • 5c: Chạy test xác nhận FAIL (RED) ➔ Commit khóa test!
git commit -m "test(red): lock tests"
BƯỚC 6 • TDD GREEN 🟢⚙️ BE + 🎨 FE
Code Song Song Làm Xanh Test
  • BE (Claude) & FE (Agy) code logic thật & UI song song.
  • Cấm xóa/làm yếu assertion của bộ test Bước 5.
  • Chạy pass 100% GREEN + tsc --noEmit ➔ Mở PR.
pytest / vitest ➔ 100% GREEN
BƯỚC 7 • GATE 3.5🏛️ [2] SA-Minh Tri
SA Duyệt Kiến Trúc & TDD
  • Kiểm tra PR khớp 100% OpenAPI Contract BE ↔ FE.
  • Xác nhận bộ test Bước 5 không bị sửa yếu ở Bước 6.
  • Soi Deep Modules, 12 Fowler Code Smells, N+1 Query.
squad-msg sa "[SM->SA] Gate 3.5"
BƯỚC 8 • GATE 4🕵️ [6] QA-Mai Linh
QA Kiểm Thử API & Browser E2E
  • Chạy lại bộ test TDD Bước 5/6.
  • Bắn API thật (200/400/401/403/404).
  • Mở Playwright/DevTools test UI thật theo từng dòng BDD.
squad-msg qa "[SM->QA] Gate 4"
BƯỚC 9 • CLOSURE🎯 SM ➔ 🎖️ Báo Bạn
Đóng Sprint & Báo Bạn Merge PR
  • Cập nhật sprint-status.yaml ➔ done.
  • Tổng hợp kết quả qua squad-status.
  • Báo cáo bạn nghiệm thu & gửi link PR để Merge!
squad-status
3. Use Case Chi Tiết Từng Bước: "Tạm Khóa Tài Khoản CTV Vi Phạm + Lưu Lịch Sử Audit"
Theo dõi chính xác từng câu lệnh, câu hỏi /grill-me và kết quả ở cả 9 bước
BƯỚC 1Auto-Spawn
👤 Bạn ➔ 🎖️ Điều PhốiGiao việc 1 dòng
👤 Bạn gõ: /squad Làm tính năng Tạm khóa CTV vi phạm: Admin bấm Tạm khóa -> nhập lý do -> chặn login Web/App & lưu lịch sử.
  • Tôi tự chạy spawn-squad --ensure vinasat-1.
  • 6 panes (PO-Bao Long ➔ QA-Mai Linh) sẵn sàng ở trạng thái idle.
  • Xuất danh bạ _bmad-output/active-squad.json.
BƯỚC 2Codebase Recon
🎖️ Điều Phối + SA + POTự đọc code trước
🤖 Hệ thống tự chạy: search_graph(name_pattern=".*Collaborator.*")
api_inspect_endpoint(path="/api/cms/collaborators")
  • Phát hiện CTV dùng JWT trên cả Web & Mobile (/api/mobile/*).
  • Phát hiện model Collaborator chưa có bảng lưu lịch sử khóa/mở khóa.
  • Chuẩn bị câu hỏi /grill-me cho các điểm chưa rõ nghiệp vụ.
BƯỚC 3/grill-me 1-by-1
📋 PO + 🏛️ SA ↔ 👤 BạnHỏi từng câu 1
🎤 Câu hỏi 1 ➔ Bạn trả lời: Hỏi: CTV đang login bị khóa thì xử lý sao?
• (Recommended) A: Thu hồi JWT ngay + trả 403.
👤 Bạn: "Chọn A. Mở khóa cũng bắt nhập lý do >=10 ký tự. OK chốt!"
  • PO-Bao Long khóa _bmad-output/prd.md.
  • SA-Minh Tri khóa _bmad-output/architecture.md:
  • Endpoint: POST /api/cms/collaborators/{id}/suspend & unsuspend.
BƯỚC 4Sharding + Worktree
📋 PO-Bao Long + 🎯 SMTách 2 Story BE/FE
📂 File & Worktree sinh ra: _bmad-output/stories/1-1-suspend-be.story.md
_bmad-output/stories/1-2-suspend-fe.story.md
.worktrees/1-1-suspend-be & .worktrees/1-2-suspend-fe
  • Mỗi file .story.md ghi rõ kịch bản Given / When / Then.
  • SM-Thanh Tung đổi sprint-status.yaml sang ready-for-dev.
  • Tạo 2 Git Worktree độc lập cho BE và FE.
BƯỚC 5 🔴TDD RED (Viết Test)
⚙️ BE-Quoc Huy
🎨 FE-Hoang NamKhóa Test Fail trước
🧪 Chạy xác nhận RED & Khóa Test: pytest apps/collaborators/tests/test_suspend.py # -> FAIL (501)
vitest run SuspendModal.test.tsx # -> FAIL
git commit -m "test(red): lock failing TDD tests"
  • BE: Tạo route stub trả 501 + viết test khóa thành công (200), thiếu lý do (400), chặn JWT (403).
  • FE: Import OpenAPI types + viết test Modal (4 states: Loading/Empty/Error/Success).
  • Chạy xác nhận RED ➔ Commit khóa cứng bộ test!
BƯỚC 6 🟢TDD GREEN (Viết Code)
⚙️ BE-Quoc Huy
🎨 FE-Hoang NamCode làm xanh Test
⚡ Chạy xác nhận GREEN & Mở PR: pytest apps/collaborators/tests/test_suspend.py # -> 100% PASS
tsc --noEmit && vitest run SuspendModal.test.tsx # -> 100% PASS
git commit -m "feat: implement CTV suspend & audit log"
  • BE: Viết model CollaboratorSuspensionLog, service thu hồi token & middleware 403.
  • FE: Code SuspendModal.tsx + bảng lịch sử trạng thái.
  • 100% test Bước 5 chuyển sang GREEN (không sửa yếu assert) ➔ Mở PR.
BƯỚC 7Gate 3.5 (SA)
🏛️ SA-Minh TriReview Kiến Trúc
📨 Lệnh điều phối: squad-msg sa "[SM->SA Gate 3.5] Review PR #101 & #102 cho story 1-1 và 1-2."
  • Đối chiếu payload BE ↔ FE khớp 100% OpenAPI Contract.
  • Kiểm tra git diff: bộ test Bước 5 giữ nguyên vẹn 100%.
  • Không có N+1 query hay Code Smells ➔ Phán quyết APPROVED.
BƯỚC 8Gate 4 (QA)
🕵️ QA-Mai LinhTest API & Browser E2E
📨 Lệnh điều phối: squad-msg qa "[SM->QA Gate 4] Verify E2E & API cho story 1-1 và 1-2."
  • Bắn API thật kiểm tra 200 OK, 400 (lý do ngắn), 403 ACCOUNT_SUSPENDED.
  • Mở Playwright bấm nút Tạm khóa trên trình duyệt, kiểm tra 0 lỗi Console.
  • Phán quyết PASS (Gate 4 Approved) gửi về SM.
BƯỚC 9Closure & Merge
🎯 SM ➔ 🎖️ Báo BạnNghiệm thu hoàn tất
📊 Báo cáo tiến độ: squad-status
# 1-1-suspend-be: done | 1-2-suspend-fe: done
  • SM-Thanh Tung cập nhật sprint-status.yaml ➔ done.
  • Tôi tổng hợp báo cáo nghiệm thu (Test Pass, Gate 3.5 & Gate 4 Pass).
  • Gửi link PR để bạn bấm Merge!
4. Danh Sách Đội Hình (VINASAT / TOMAHAWK) & Khoanh Vùng Role Bundles
Mỗi Role nạp đúng Instructions + Skills + MCP riêng • Tự do sửa file thoải mái
Squad Lệnh Bật [1] PO [2] SA (Tier-1 ★) [3] SM [4] BE-Dev [5] FE-Dev [6] QA
VINASAT-1 spawn-squad vinasat-1 PO-Bao Long (claude) SA-Minh Tri ★ (agy) SM-Thanh Tung (claude) BE-Quoc Huy (claude) FE-Hoang Nam (agy) QA-Mai Linh (agy)
VINASAT-2 spawn-squad vinasat-2 PO-Minh An (agy) SA-Kien Long ★ (opus) SM-Duc Anh (agy) BE-Thanh Nam (agy) FE-Tuan Kiet (claude) QA-Thu Ha (claude)
VINASAT-3 spawn-squad vinasat-3 PO-Hoang An (claude) SA-Hoang Long ★ (agy) SM-Quang Huy (claude) BE-Minh Quan (claude) FE-Dang Khoa (agy) QA-Bao Ngoc (agy)
TOMAHAWK-1 spawn-squad tomahawk-1 PO-Gia Huy (agy) SA-Thien Long ★ (opus) SM-Hai Dang (agy) BE-Anh Tuan (agy) FE-Minh Duc (claude) QA-Khanh Vy (claude)
TOMAHAWK-2 spawn-squad tomahawk-2 PO-Khanh An (claude) SA-Viet Hoang ★ (agy) SM-Trung Kien (claude) BE-Dinh Phuc (claude) FE-Nhat Minh (agy) QA-Thao Nhi (agy)
TOMAHAWK-3 spawn-squad tomahawk-3 PO-Tuan Anh (agy) SA-Dinh Long ★ (opus) SM-Hoang Phuc (agy) BE-Gia Bao (agy) FE-Quang Minh (claude) QA-Phuong Anh (claude)
5. Review Thực Tế & 5 Công Cụ Chống Lỗi Đã Tích Hợp
Giải quyết triệt để các lỗi thực tế khi vận hành đa Agent trên Herdr
# Vấn Đề Thực Tế Giải Pháp Đã Tích Hợp (Ngắn Gọn) Lệnh Thực Thi
1 Quên bật Squad hoặc bật trùng tab • Tự kiểm tra: nếu đã có 6 panes thì dùng lại ngay.
• Nếu chưa có: tự bật mới & đợi cả 6 panes sang idle.		 spawn-squad --ensure vinasat-1
2 Gõ nhầm pane_id khi nhắn chéo • Tự lưu danh bạ vào _bmad-output/active-squad.json.
• Nhắn tin theo tên Role, không cần nhớ pane_id.		 squad-msg <po|sa|sm|be|fe|qa> "..."
3 BE & FE đụng Git Branch/Index • Mỗi Story chạy trên 1 Git Worktree riêng biệt.
• Không bao giờ ghi đè branch của nhau.		 git worktree add .worktrees/<id>
4 Chờ lâu khi hỏi đáp /grill-me • Quét codebase 1 lần ở đầu phiên.
• Điều phối viên hỏi đáp từng câu 1 trực tiếp với bạn (phản hồi tức thì).		 /bmad-party-mode + /grill-me
5 Khó theo dõi 18 panes cùng lúc • 1 lệnh duy nhất in ra toàn bộ trạng thái 6 panes, sprint-status.yaml và danh sách Worktrees. squad-status [project_dir]
6. Bộ 3 Sơ Đồ Ảnh Trực Quan (Visual Cheatsheets)
Tổng quan kiến trúc • Flow 9 bước • Use Case thực chiến

6.1. Master Cheatsheet — Đội Hình 6-Role Agile Squad × BMAD × Herdr

Master Cheatsheet

6.2. Flow Thực Thi 9 Bước (Full Flow + /grill-me + Bước 5 TDD RED ➔ Bước 6 TDD GREEN)

9-Step Execution Flow

6.3. Hướng Dẫn Thực Chiến Use Case Cụ Thể

Use Case Walkthrough