obra/superpowers
318k ★ · v7.0.2- A Bước "Size the Work" chia việc thành 2 cỡ. Việc phình ra giữa chừng thì dừng lại, nâng lên cỡ lớn hơn.
- C Chọn model theo độ khó: việc 1–2 file dùng model rẻ, kiến trúc và review cuối dùng model mạnh nhất.
Phoenix hiện chạy tốt khi dự án đi từ P0 đến P7. Việc nhỏ phát sinh giữa chừng, dự án có sẵn cần polish, và kiến thức muốn dùng lại cho dự án sau đều phải chen vào cùng một chuỗi phase. Agent con cũng chưa có model riêng theo việc. Phoenix 2 chạy mọi phiên qua phoenix code, chia việc thành 3 luồng đi chung 8 bước, nhận được repo có sẵn, gom kiến thức về một kho chung, cho cả đội xem tiến độ trên Monitor Server, và đọc tài liệu từ 25Brain.
Đã giữ nguyên các phần đang chạy tốt: chia task, monitor, autopilot, cổng có bằng chứng, test case, recipe và Telegram.
Thêm task vào phase đã xong thì phase đó bị kiểm lại và cổng phải duyệt lại.
tasks.mjs:79-80 · autopilot.mjs:237Việc sau Polish phải chạy tay bằng phoenix.mjs run.
Phải có Output kèm code block, Knock-on, outputs, structure check, và ASM nếu đang ở P6.
tasks.mjs:196-213, 243-248Không ghi task, decision hay recipe. Những lỗi hay lặp lại nhất cũng không có bản ghi.
brief.mjs:33-37 · pomode.mjsRepo Axmol, Next.js hay Go có sẵn không nhận vào được.
adopt.mjs:85-87 · new-project.mjs:99Phải tạo task RE, GDD và replay trước. Dự án chỉ cần polish vẫn phải qua P1 đến P5.
adopt.mjs:293-306, 386Đường dẫn skill là đường dẫn tuyệt đối. 55/111 recipe còn ở dạng .proposed.md. Chỉ 12 recipe có nhãn.
Model khai ở cả roles.json và frontmatter. Agent con chạy model mặc định của phiên. dev.md mặc định vẫn mô tả Creator.
Cả 7 repo đều chia việc thành 2 đến 4 cỡ. Chỉ cỡ lớn nhất phải chạy toàn bộ quy trình. Nhãn A/B/C cho biết ý đó dùng cho phần nào của đề xuất.
bmad-build, khoảng 500 dòng. Có 4 tầng, việc hiển nhiên thì sửa thẳng.<!-- bmad:context --> trong AGENTS.md. Chỉ ghi lỗi đã thấy agent mắc._bmad/custom/*.toml cho cả team, *.user.toml cho từng người, external_sources trỏ tới MCP.bug có 3 bước assess → fix → test, kết luận verified / partial / failed.changes/<id>/. Archive gộp delta ADDED / MODIFIED / REMOVED vào specs/.references:, agent nhận chỉ mục 1 dòng mỗi mục./gsd-fast chạy inline. /gsd-quick ghi vào bảng trong STATE.md, không đụng ROADMAP.map-codebase chạy 4 agent song song, viết 7 file trong codebase/.grilling: hỏi theo vòng, mỗi câu kèm đáp án đề xuất. diagnosing-bugs: dựng lệnh tái hiện đỏ trước khi đoán.tdd: test ở seam đã thống nhất. to-tickets: task lát dọc có cạnh chặn.domain-modeling: GLOSSARY.md + ADR. retro: lỗi cơ học thì thêm check, không thêm luật.| Repo | Đường cho việc nhỏ | Nhận codebase có sẵn | Kiến thức dùng chung |
|---|---|---|---|
| Superpowers | 2 cỡ, chạy plan inline | Theo pattern sẵn có, không map | Plugin marketplace |
| BMAD | 1 phiên build, khoảng 500 dòng | Khối context trong AGENTS.md | custom toml, modules |
| spec-kit | Extension bug, preset lean | Constitution chỉ từ sự thật trong repo | Preset, bundle, catalog riêng |
| OpenSpec | Một vòng cho mọi cỡ | Spec delta lớn dần | Stores và references: |
| GSD | fast / quick / quick-batch | 4 mapper viết 7 file | Global learnings, giới hạn số mục nạp |
| mattpocock/skills | quick sửa lỗi theo 6 pha chẩn đoán | GLOSSARY.md, ADR khi chốt | Review 2 trục, retro đề xuất check |
| LoopForge | small → SOLO, rejectTo + maxReworks | Vai khai inputs, outputs, access | Hàng đợi knowledge.md, phiên bản không sửa |
phoenix code, giao agent theo nhóm modelMọi phiên Claude Code, kể cả agent do monitor mở, chạy qua launcher phoenix. Launcher trỏ Claude Code tới PhoenixProxy, nên một phiên gọi được cả Claude, Cursor, GPT và Kimi. Phoenix dò danh sách model, gán nhóm model cho từng vai, rồi sinh file agent có model cụ thể. Agent con không còn dùng model mặc định của phiên.
| Việc | Lệnh |
|---|---|
| Cài (macOS/Linux) | curl -fsSL http://192.168.0.5:8317/install.sh | sh |
| Cài (Windows) | irm http://192.168.0.5:8317/install.ps1 | iex |
| Lưu API key | phoenix key |
| Mở phiên | phoenix code trong thư mục dự án |
| Model khác | phoenix code --model gpt-6.2-sol |
| Tham số Claude Code | phoenix code -- --resume |
| Xem model, nhóm | /model trong phiên |
| Bước Dò | Cách dò |
|---|---|
| Trong Claude Code | CLAUDECODE=1, CLAUDE_CODE_ENTRYPOINT |
| Qua launcher | ANTHROPIC_BASE_URL trùng địa chỉ proxy |
| Cursor CLI, Codex | Tên tiến trình cha |
| Model gọi được | GET /v1/models, ghi .phoenix/env.json, giữ 1 giờ |
| Thành viên hỏng | Proxy trả model not allowed thì lấy thành viên kế tiếp |
Launcher đặt ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, bật gateway model discovery và chạy Claude Code với --dangerously-skip-permissions. Monitor mở agent bằng phoenix code -- -p … --agent <vai>@<nhóm>. Phiên phoenix code không dùng được artifact claude.ai vì đăng nhập bằng key proxy.
| Nhà cung cấp | Id dùng trong thẻ | Giao task code |
|---|---|---|
| Anthropic | claude-opus-5-5 claude-opus-4-8 claude-sonnet-5-5 claude-haiku-5-5 claude-fable-5-2 | Có, context 1M |
| Cursor | cursor/auto cursor/grok-4.7 | Có, context 200k |
| OpenAI API | gpt-6.2-sol gpt-6.2-astra | Có, 500k và 272k |
| Moonshot | kimi-k3.1-pro kimi-k2.8-code | Có, context 1M |
| ChatGPT web | chatgpt-web/gpt-image-2.5 gpt-image-2, 4 model chat | Chỉ sinh ảnh |
| Gemini web | gemini-web/gemini-4-neon -hydrogen -argon | Không |
Dùng id gốc như bảng. Picker /model hiện model ngoài Claude dưới id dạng claude-fable-5-dd-…, id đó không dùng trong file agent.
Session chính, PO, tech-lead, bản hiểu dự án. Alias opus.
20/11: claude-opus-5-5dev, qa, game-design, product-design, devops, data-bi. Alias sonnet.
20/11: cursor/auto · claude-sonnet-5-5 (chia vòng)Agent con của quick, tra cứu. Alias haiku.
20/11: claude-haiku-4-5-20251001Reviewer, khác model với analysis, kèm open-code-review. Không có alias, dùng thẻ CCR.
20/11: claude-opus-4-6Lượt Làm lại cuối khi Claude đã fail 2 lượt. Alias fable.
20/11: kimi-k3.1-proVai re-apk: APK Unity IL2CPP, Cocos.
cursor/auto → cursor/grok-4.7Vai art-game khi cần ảnh mới.
chatgpt-web/gpt-image-2.5 → gpt-image-2| Agent | Nhóm | Thang Làm lại |
|---|---|---|
| Session chính, PO, tech-lead | analysis | |
| dev-*, qa-*, game-design, product-design, devops, data-bi | coding-medium | coding-medium → analysis → frontier |
| Agent con của quick | coding-low | coding-low → coding-medium → analysis |
| reviewer | review-code | Luôn khác model với người làm |
| re-apk | re | cursor/auto → cursor/grok-4.7 → analysis |
| art-game (sinh ảnh) | art-gen |
Từ 20/11/2026 proxy mở 5 combo gọi thẳng bằng tên (analysis, coding-medium, coding-low, review-code, frontier), proxy tự chia vòng. Nhóm re và art-gen không có combo nên Phoenix tự chọn thành viên. models.json khai combo và members dự phòng; vai khai group và ladder trong role.json.
# .claude/agents/re-apk@re.md — phoenix.mjs env sinh, không viết tay --- name: re-apk@re description: Phân tích APK Unity IL2CPP và Cocos. tools: Read, Grep, Glob, Bash, Edit, Write --- <CCR-SUBAGENT-MODEL>cursor/auto</CCR-SUBAGENT-MODEL> (AGENTS.md của vai re-apk)
| Ai giao | Cách gọi |
|---|---|
| Session chính | Công cụ Agent, subagent_type: "re-apk@re", không truyền model |
| Monitor | phoenix code -- -p … --agent re-apk@re, không truyền --model |
| Làm lại | Giao cho file của nhóm kế tiếp, vd re-apk@analysis |
| Vai runtime cursor | cursor-agent --model <id>, cần agent login |
phoenix.mjs env sinh 1 file cho mỗi nhóm trong group và ladder của vai, thẻ ghi thành viên đang chọn. File nằm trong .gitignore. Nhóm có alias gọi được bằng tham số model; nhóm review-code, re, art-gen chỉ gọi được qua thẻ. Hướng dẫn nằm trong SKILL.md mục "Mở phiên và giao agent" và references/models.md.
Mỗi run có thư mục cấu hình riêng (CLAUDE_CONFIG_DIR=.phoenix/runs/<run>/home), chỉ symlink skill vai được dùng, nên agent song song không ghi đè nhau. File agent mang disallowedTools theo access của vai: reviewer chỉ ghi báo cáo, QA chỉ ghi test.
Run fail thì phân loại trước khi quyết định Làm lại. Chỉ lỗi chất lượng mới lên nhóm model kế tiếp. Quota, giới hạn tốc độ hay model không gọi được thì đổi sang thành viên khác cùng nhóm.
| Mã | Dấu hiệu | Xử lý |
|---|---|---|
| AUTH_FAILED | 401, invalid api key | Dừng, báo chạy phoenix key |
| RATE_LIMITED | 429, rate limit | Chờ lùi dần 10 s · 2^n, tối đa 5 lần, rồi đổi thành viên cùng nhóm |
| QUOTA_EXCEEDED | quota, insufficient | Đổi thành viên cùng nhóm |
| MODEL_UNAVAILABLE | model not allowed, not found | Đánh dấu trong env.json, đổi thành viên cùng nhóm |
| CONTEXT_LIMIT | context, too long | Giao lại với brief rút gọn, cùng nhóm |
| NETWORK_ERROR | ECONNREFUSED, timeout | Thử lại 1 lần, rồi báo proxy không tới được |
| CLI_START_FAILED | Thoát trước dòng jsonl đầu tiên | Chạy lại phoenix.mjs env, báo trên monitor |
| MISSING_RESULT | Thoát 0 nhưng thiếu đầu ra bắt buộc | Lỗi chất lượng: Làm lại theo thang |
| QUALITY | Kiểm trả partial hoặc failed | Làm lại theo thang |
Mỗi run fail ghi 3 mục: bằng chứng (mã lỗi, 8 dòng stderr đầu, 20 dòng cuối, lệnh), điều chưa biết, bước tiếp. Giữ 8 dòng đầu để lần thử lại không che lỗi đầu tiên. Không đoán nguyên nhân khi thiếu bằng chứng.
Mỗi run ghi thời gian chạy (hợp các khoảng agent chạy, không cộng trùng khi song song), thời gian chờ người và tổng thời gian.
Bảng giá theo id model trong models.json. Thiếu giá hoặc thiếu token thì chi phí là "chưa rõ", không ghi 0. Monitor hiện chi phí theo nhóm kèm % run tính được giá.
0–100 tính từ jsonl: Làm lại 25, thời gian 20, gọi tool lặp 20, token 15, lỗi lặp 10, đủ đầu ra 10. Dưới 70 thì harvest đưa run vào danh sách xem lại.
quick là việc nhanh: 1 agent con làm xong trong 1 phiên, không tạo task trên monitor. Làn này nhận sửa lỗi nhỏ, chỉnh UI, đổi text, chỉnh số. change là thay đổi vừa, có CHANGE.md, kiểm tự động và review khác bên, chạy cả khi autopilot đã dừng. project chạy chuỗi phase. Cả 3 luồng đi cùng 8 bước, bước giống nhau mang cùng tên.
Ô mờ là bước bỏ qua. quick và change chỉ có 1 việc nên không có bước Chia. Thời gian một vòng chấm chạy chỉ để so sánh tương đối.
| Bước (id) | Nghĩa | quick | change | project |
|---|---|---|---|---|
0 Dò probe | Biết CLI nào, model nào gọi được | Đọc .phoenix/env.json do phoenix.mjs env ghi. Xem Phần A | ||
1 Nhận intake | Ghi yêu cầu, chọn luồng sơ bộ | Brief 5 dòng | CHANGE.md mục Yêu cầu | Kick-off: PRD/GDD, workflow, blueprint |
2 Hiểu understand | Bản hiểu, duyệt, ra cỡ thật | ≤ 10 dòng, session chính duyệt | ≤ 10 dòng, người giao duyệt | Dự án ≤ 1 trang, người dùng duyệt. Mỗi task ≤ 10 dòng |
3 Chia plan | Cắt việc thành phần giao được | bỏ qua | bỏ qua | PO cắt task theo phase |
4 Giao assign | Chọn vai, nhóm model, mở agent | Agent con | Run trong .phoenix/runs/ | Dispatcher của autopilot |
5 Làm build | Sửa, test, commit có trailer | Quick: qk-n | Change: id | Commit theo task |
6 Kiểm verify | Tự chạy lại test, kiểm tự động, review khác bên | Session chính chạy lại test, đếm diff | change check + reviewer | Task QA + cổng phase |
7 Chốt close | Ghi bản ghi, nhả khoá | 1 dòng CHANGES.md | archive/, giữ log | Task done, cổng đạt, release + harvest |
Làm lại retry | Kiểm fail vì chất lượng | Giao lại cho nhóm model mạnh hơn. Xem thang | ||
Nâng luồng promote | Việc lớn hơn ngưỡng | thành change | thành project | không có |
Id bước dùng làm trạng thái trong file, tên cột trên monitor và tiêu đề tin Telegram. Kết luận bước Kiểm dùng chung: verified, partial, failed.
Ngưỡng đã chốt: quick ≤ 3 file và ≤ 300 dòng. change ≤ 20 file và ≤ 2000 dòng, 1 tới 3 run. Chạm vùng nhạy cảm thì ít nhất là change. Chỉnh trong .phoenix/sizes.json. Bước Nhận chọn sơ bộ, bước Hiểu chốt theo danh sách file trong bản hiểu.
Bước này chỉ đọc code. Bản hiểu sai thì sửa ở đây rẻ hơn sửa code đã viết.
Mục tiêu nói lại bằng lời của agent, file sẽ đụng, "Xong khi" kiểm được, seam kiểm (nơi đặt test, bắt được gì, bỏ sót gì), ngoài phạm vi, giả định, câu hỏi. Dùng đúng từ trong GLOSSARY.md.
Sự thật trong repo thì agent tự tra, không hỏi. Quyết định xếp thành cây: mỗi vòng hỏi hết các câu đang hỏi được, đánh số, kèm đáp án đề xuất, "đồng ý" là nhận đáp án.
"Xong khi" kiểm được, có ≥ 1 seam, câu hỏi mở = 0. Thuật ngữ vừa chốt ghi ngay vào GLOSSARY.md.
Danh sách file cho ra cỡ thật. Vượt ngưỡng thì Nâng luồng trước khi sửa dòng nào.
Session chính là người điều phối duy nhất. Không có run file, task hay khoá scope. Một agent con làm cả Hiểu lẫn Làm (tiếp tục bằng SendMessage), nên agent không đọc lại code.
| Tình huống | Xử lý |
|---|---|
| Kiểm fail | Làm lại: coding-low → coding-medium → analysis. Hết thang mới Nâng luồng thành change, brief thành CHANGE.md, commit đã có giữ nguyên. |
| Diff thật vượt ngưỡng | Nâng luồng ngay, review như change. |
| Chạm vùng nhạy cảm | Là change ngay từ bước Nhận, dù chỉ 1 dòng. |
| 2 việc quick cùng lúc | Chạy song song khi không trùng file. Trùng file thì chạy lần lượt. |
| Monitor tắt | Vẫn chạy. Monitor chỉ đọc CHANGES.md để hiện danh sách việc gần đây. |
Run dùng lại .phoenix/runs/ sẵn có (pid, trạng thái, thời gian chạy, log jsonl), không tạo thư mục .runs/ mới.
| # | phoenix.mjs change check (trước reviewer) |
|---|---|
| 1 | File trong commit Change: <id> nằm trong scope. Ngoài scope phải có dòng Quyết định |
| 2 | Số file, số dòng dưới ngưỡng change |
| 3 | Tự chạy lại "Cách kiểm" và test dự án, không dùng số trong REPORT |
| 4 | Mỗi dòng "Xong khi" có bằng chứng: lệnh + đầu ra, hoặc ảnh |
| 5 | REPORT ghi phần code test đã chạm |
| Kết luận Kiểm | Khi nào |
|---|---|
| verified | Đủ mọi dòng Xong khi, test xanh, không quyết lén. Sang Chốt |
| partial | Đạt một phần, không hỏng chỗ khác. Làm lại phần thiếu |
| failed | Test đỏ, hỏng chỗ khác, ngoài scope không ghi, hoặc quyết lén. Làm lại kèm lỗi |
| human | Cần người quyết phạm vi hay đánh đổi. Dừng ở inbox, không tính lượt |
Tầng dự án chạy Dò, Nhận, Hiểu một lần. Tầng phase lặp Chia, Kiểm, Chốt cho mỗi phase. Tầng task lặp Hiểu, Giao, Làm, Kiểm, Chốt cho mỗi task, giống một change nhỏ. Phase, cổng và autopilot giữ như hiện tại.
| Bước | Tầng | Việc | Ai · nhóm model | Phase |
|---|---|---|---|---|
| 0 Dò | Dự án | phoenix.mjs env lúc mở monitor, ghi .phoenix/env.json | Monitor | Trước P0 |
| 1 Nhận | Dự án | Kick-off: loại dự án, goal, workflow, blueprint, nguồn (APK, GDD, PRD, repo) → DECISIONS.md | Người dùng + PO · analysis | P0 |
| 2 Hiểu | Dự án | docs/UNDERSTANDING.md ≤ 1 trang: mục tiêu, phạm vi, nguồn, tiêu chí release, rủi ro, câu hỏi. Mới | PO · analysis, người dùng duyệt | P0 |
| 3 Chia | Phase | Cắt task cho phase hiện tại, mỗi task có vai và Xong khi kiểm được. Tối đa 3 lượt cắt | PO · analysis | Đầu mỗi phase |
| 2 Hiểu | Task | Mục ## Hiểu yêu cầu ≤ 10 dòng trong file task, cổng tự động như quick. Mới | Agent vai · nhóm của vai | Mỗi task |
| 4 Giao | Task | Dispatcher tra nhóm → model gọi được, tối đa 3 agent song song mỗi vai | Autopilot | Mỗi task |
| 5 Làm | Task | Sửa, test, commit, viết output task | Agent vai | Mỗi task |
| 6 Kiểm | Task | Task QA theo màn hoặc nhóm. Task code có review khác bên. Kết luận verified / partial / failed. Mới | QA · coding-medium, reviewer · review | Mỗi task |
| 6 Kiểm | Phase | Cổng phase có bằng chứng. Autopilot tự duyệt cổng đạt, kế hoạch review luôn chờ người dùng | Autopilot, người dùng | Cuối phase |
| 7 Chốt | Phase / dự án | Sang phase sau. Hết P6 Polish thì dừng. Release do người dùng, harvest mở MR lên hub | Người dùng + người triển khai | P7 / Release |
Kết luận partial và failed ghi quay_ve: understand khi bản hiểu sai, build khi code sai. Hết lượt Làm lại thì dừng chờ người ở inbox, không tự đóng là fail.
| Pha | Việc | Xong khi |
|---|---|---|
| 1 Vòng phản hồi | Dựng 1 lệnh tái hiện: test, script CLI, curl, qa:play, replay log | Đã chạy, đỏ đúng triệu chứng, nhanh, ổn định, agent tự chạy được |
| 2 Thu nhỏ | Cắt dần đầu vào, bước, cấu hình | Bỏ thêm phần nào cũng xanh |
| 3 Giả thuyết | 3–5 giả thuyết xếp hạng, mỗi cái kèm dự đoán | Ghi task log trước khi đo |
| 4 Đo | Mỗi lần 1 biến, log gắn [DEBUG-id] | Biết giả thuyết đúng |
| 5 Sửa | Test hồi quy ở seam đúng trước, rồi sửa | Đỏ rồi xanh; không có seam thì ghi là phát hiện |
| 6 Dọn | Gỡ [DEBUG-, bỏ code thử | Commit ghi giả thuyết đúng |
Dùng cho quick sửa lỗi, task chẩn đoán của autopilot (đã áp: references/diagnose.md) và Làm lại khi chưa rõ nguyên nhân. PO cắt task theo lát dọc (core → view → test, kiểm được riêng); refactor rộng chia 3 bước thêm dạng mới, chuyển nơi gọi, bỏ dạng cũ. Review chia 2 reviewer song song: trục Spec và trục Chuẩn (CODING_STANDARDS.md + danh sách code smell). Change ở dự án app chạy trong worktree riêng.
Vai, Việc, Đầu vào, Đầu ra (đường dẫn, bắt buộc hay không), Bằng chứng phải nộp, Lần thử, Lỗi lượt trước. Dùng chung cho quick, change và task.
Brief chép đúng các mục khai trong role.json.inputs. Agent chỉ mở file gốc khi phần trích thiếu hoặc mâu thuẫn.
status, verdict, next, đường dẫn đầu ra, 1–3 ràng buộc. Session chính và PO chọn bước tiếp từ đây, không đọc lại cả file trạng thái.
Luật chung luôn nạp. Luật Go, SQL, frontend, Axmol, Unity chỉ nạp khi repo có go.mod, thư viện, đuôi file tương ứng.
Vai phụ explorer (coding-low, access read) tìm code và tài liệu cho bước Hiểu. Không review, không sửa.
| Cơ chế | Cách làm |
|---|---|
| Chặn duyệt cũ | Yêu cầu duyệt ghi (bước, lượt, số lần Làm lại). Lúc bấm, lệch với trạng thái hiện tại thì từ chối và hiện trạng thái mới |
| Nút Telegram | Duyệt, Làm lại, Trả về bước…, Bỏ qua. Nút sinh từ trạng thái hiện tại. Bấm thì kiểm đúng chat, đúng dự án, tin dưới 24 giờ, hành động còn hợp lệ |
| Bỏ tin nhắc cũ | Ngay trước khi gửi, run đã xong, trạng thái đã đổi hoặc lượt đã tăng thì bỏ tin. Gửi lỗi thử lại lùi dần 10 s · 2^n, tối đa 5 lần |
| Agent tự tóm tắt | Khối ```notification JSON (title, summary) cuối báo cáo. Thiếu thì lấy 300 ký tự đầu. Không gọi thêm model |
| Mẫu tin an toàn | Biến trong danh sách cố định, thay 1 lượt. Mọi tin qua hàm che token, key trước khi gửi |
change/<id>-<yyyymmdd>, task/<id>-<yyyymmdd>. quick commit thẳng lên nhánh đang làm.
gh pr list --head hoặc glab mr list --source-branch. Không dò link trong log. Nhiều repo: tất cả đóng mới là đóng.
Autopilot gộp nhánh chính trước mỗi lượt Giao. Xung đột thành thẻ chặn kèm tối đa 8 đoạn xung đột, repo đó dừng nhận việc mới.
Chốt của mọi change và task ghi bài học: có | không — lý do. Có thì viết docs/knowledge/<id>.md cho hàng đợi harvest. Không quyết theo cỡ việc.
Kiểm fail vì chất lượng thì Làm lại bằng nhóm mạnh hơn. Lượt mới nhận bản hiểu đã duyệt, diff hiện tại và lỗi lượt trước.
Thang áp cả cho bước Hiểu: bản hiểu bị bác 1 lần thì lượt sau viết bằng nhóm kế tiếp. Với quick, đổi nhóm là gọi Agent mới bằng file <vai>@<nhóm> của nhóm đó, vì SendMessage giữ model cũ. Mỗi lượt ghi nhóm + model vào CHANGES.md hoặc run-summary.json để harvest chọn nhóm khởi đầu cho vai.
Nền của luồng change là artifact "Luồng change": giữ CHANGE.md làm nguồn sự thật, Quyết định ba phần, review khác bên, khoá scope, agent không tự đặt verified. Phoenix thêm bước Hiểu, kiểm tự động, số cụ thể cho agent chết (pid chết → lost, jsonl im 15 phút → cảnh báo), thời hạn 90 phút mỗi run, tối đa 3 run, và dùng .phoenix/runs/ sẵn có.
Rủi ro còn lại: nhiều change cùng cây làm việc thì test có thể chạy trên code dở của change khác. change check chạy lại test lúc kiểm và báo commit làm đỏ. Đỏ lặp do change khác thì cho chạy lần lượt.
| File | Đổi gì |
|---|---|
| tools/lib/env.mjs (mới) | Dò CLI và launcher, gọi /v1/models, chọn thành viên nhóm, ghi env.json, sinh <vai>@<nhóm>.md có thẻ CCR-SUBAGENT-MODEL |
| tools/lib/changes.mjs (mới) | CHANGE.md, vòng đời theo id bước, khoá scope, check, archive |
| tools/lib/sizes.mjs (mới) | Đọc sizes.json, đếm cỡ theo trailer, kiểm vùng nhạy cảm |
| tools/phoenix.mjs | env, change new | understand | start | check | verdict | archive, quick log |
| monitor/lib/dispatcher.mjs | Mở agent qua phoenix code -- -p … --agent <vai>@<nhóm>, bỏ modelOf, ghi nhóm + model vào run |
| monitor/lib/autopilot.mjs | Giao change kể cả khi autopilot dừng. Thang Làm lại theo nhóm |
| tools/lib/tasks.mjs | Task có mục Hiểu yêu cầu, kết luận Kiểm có quay_ve, dòng bài học |
| tools/lib/evidence.mjs (mới) | Mốc hash đầu ra, kết luận nộp 1 lần, kiểm sha256 lúc Chốt |
| tools/lib/failures.mjs (mới) | Bảng mã lỗi, failure.md, điểm sức khoẻ run |
| tools/lib/brief.mjs | Mẫu brief cố định, trích mục đầu vào, nạp luật theo dấu hiệu |
| monitor/lib/telegram.mjs | Nút duyệt, kiểm lại lúc bấm, bỏ tin cũ, che khoá |
| ui/monitor | Cột theo id bước, danh sách quick, thẻ model gọi được |
| CLAUDE.md (3 bản), SKILL.md, references/models.md | Mở phiên bằng phoenix code, bộ bước chung, chọn luồng, mẫu brief và bản hiểu, bảng vai → nhóm |
join-project.mjs: nhận repo có sẵn ở mọi stacknode <skill>/scripts/join-project.mjs <repo> --mode auto|maintain|resume. Join chỉ thêm file trên nhánh phoenix-join, nên không cần git sạch và không cần RE, GDD hay replay. Bốn agent đọc repo song song rồi viết 7 file mô tả. Agent sau đó làm việc theo luật đã đúng sẵn trong repo, có README và CI làm bằng chứng.
Map codebase, viết khối context, chạy test hiện có để ghi mốc. Cổng codebase đạt khi đủ 7 file và test mốc chạy được.
Các change nối tiếp nhau, không có điểm kết thúc. Phase này không có cổng chung, mỗi change tự kiểm.
Gom các change thành changelog và build phát hành. Cổng release giống workflow app.
Dự án đang làm dở: tìm dự án đang ở phase nào rồi chạy tiếp từ đó. Port Creator 3.x làm dở vẫn qua adopt-project.mjs hiện có.
maintain dành cho sản phẩm đã xong. resume dành cho dự án còn tính năng chưa làm. --mode auto chọn resume khi có tài liệu kế hoạch (GDD, PRD, backlog) và còn mục chưa có trong code.
| Trong bản đồ | Phoenix tạo | Ghi chú |
|---|---|---|
| Phase đủ đầu ra | Task done sinh từ git log và code. Cổng vào inbox kèm bằng chứng, nhãn imported | Người dùng duyệt 1 lần, cổng không chạy lại |
| Code có, tài liệu thiếu | Task nhỏ "viết hồi tố từ code" | Chỉ viết phần phase sau cần đọc, không chặn phase sau |
| Tính năng partial | 1 change mỗi mục, scope là file của mục đó | Đi luồng change |
| Tính năng missing | Task project trong phase tương ứng | Như dự án mới |
| Việc dở chưa commit | Change ch-wip-<nhánh>, owner là người đang làm | Không commit hộ. Người dùng chọn giao agent hay để người làm tiếp |
Bước khởi tạo chỉ thêm file trên nhánh phoenix-join, không sửa code. Không có tài liệu kế hoạch thì bản hiểu hỏi người dùng mục tiêu còn lại và hạn, câu trả lời thành PRD hoặc GDD tối thiểu. Game làm theo màn thì nhập từng màn: màn xong là task done, màn dở là change. Bản đồ sai thì sửa PROGRESS-MAP.md rồi chạy join-project.mjs --mode resume --apply, lệnh chỉ thêm, không xoá task.
Mỗi người mở phoenix code trên máy mình, cạnh thiết bị và toolchain của máy đó. Git đồng bộ dữ liệu dự án và làm khoá nhận việc. Monitor ở mỗi máy tự gửi tóm tắt lên Monitor Server trên Mac mini. Server biết dự án có mấy người tham gia, ai đang làm phần nào. Server chỉ để xem: không chạy agent, không giao việc, không ghi vào repo.
Máy chỉ gửi tóm tắt: không code, không diff, không log đầy đủ. Mất mạng thì sự kiện xếp hàng trong .phoenix/outbox.jsonl và gửi bù, id <máy>-<số> chống trùng.
| Luật | Cách làm |
|---|---|
| Nhận việc bằng push | Ghi claimed_by: người@máy vào file task (hoặc owner trong CHANGE.md), commit lên nhánh chính, push ngay. Push bị từ chối thì người khác vừa nhận: pull, chọn việc khác |
| Không trùng scope | Từ chối nhận việc có scope trùng việc đang có người nhận |
| 1 autopilot mỗi dự án | .phoenix/autopilot-owner có commit. Người khác giao tay được, không tự giao |
| Mỗi mục một file | .phoenix/gates/<phase>.json, docs/decisions/<id>.md. Bảng tổng hợp sinh lại. CHANGES.md dùng merge=union |
| Mỗi việc một nhánh | Code vào nhánh chính qua MR. Pull và gộp nhánh chính trước mỗi lượt Giao |
| Nhận lại việc bỏ dở | Claim quá 24 giờ không commit và người nhận offline thì phoenix.mjs claim <id> --takeover, ghi lý do |
| Việc cần thiết bị | Task khai needs (vd android-root), chỉ máy có thiết bị trong env.json nhận được |
| Trang | Nội dung |
|---|---|
| Tất cả dự án | Phase, số người online, việc đang chạy, cổng chờ duyệt |
| Một dự án | Từng người: online/offline (mất heartbeat 5 phút), việc đang nhận, bước, nhóm model. Bảng task có cột người nhận |
| Một người | Việc đang làm ở mọi dự án, việc xong 7 ngày qua |
| Chi phí | Theo dự án, người, nhóm model, % run tính được giá |
| Sự kiện máy gửi | Trường |
|---|---|
| heartbeat · 60 s | người, máy, dự án, phiên bản Phoenix, số run đang chạy |
| claim, release | id việc, luồng, tiêu đề, scope |
| step | id việc, bước, vai, nhóm model, model |
| run_end | kết luận, mã lỗi, thời gian chạy và chờ, token, chi phí hoặc "chưa rõ" |
| gate, blocked | phase, cổng chờ ai; lý do bị chặn (xung đột nhánh, câu hỏi, thiếu thiết bị) |
Claim, task và cổng lấy từ git. Sự kiện chỉ bổ sung trạng thái đang chạy, lệch thì hiện theo git kèm dấu "máy chưa đồng bộ". Danh tính lấy từ token của người (phoenix.mjs server join <url>), dự án nhận ra bằng git remote. Mỗi dòng có link mở monitor của máy đó qua Tailscale khi máy online. Duyệt vẫn làm ở monitor máy hoặc nút Telegram. Nhiều dự án trên 1 máy: mỗi monitor tự lấy cổng trống từ 4700, ~/.phoenix/slots.json giới hạn số agent cả máy theo priority.
Quy ước giao diện: 5 màu trạng thái có bản sáng và tối, chỉ dùng cho trạng thái thật. Huy hiệu dạng viên, chấm thở khi đang chạy. Trạng thái rỗng có biểu tượng, tiêu đề, 1 dòng mô tả. Lỗi tải có khung đỏ role="alert". Hover chỉ đổi màu. Chuyển động tắt khi prefers-reduced-motion. Giao diện chỉ hiện trạng thái server trả, không tự suy.
Hub là một repo git đặt trên GitLab công ty (git.skylinkmedia.asia, nơi đang chứa waterpack và block-crush), không cần viết server riêng. Git lo phiên bản, merge request lo bước duyệt, nhóm GitLab lo phân quyền. Server LAB là Mac mini M4 đặt ở văn phòng, tách khỏi máy Ubuntu chạy brain. Mac mini giữ một bản clone hub, job launchd pull 5 phút một lần, và chạy Monitor Server. Mỗi dự án ghim commit hub trong .phoenix/hub.lock, nên hub thay đổi không làm lệch dự án đang chạy.
phoenix-hub/ models.json # nhóm model, §A roles/ # kho AGENTS theo vai dev-axmol/ role.json # runtime, group, ladder, skills, mcp AGENTS.md # luật vai → .claude/agents knowledge/*.md # API hay dùng, bẫy, checklist lessons.md # bài học có nguồn dự án po-game/ game-design/ tech-lead/ dev-go-backend/ qa-game/ # 18 vai blueprints/ # kiến trúc mẫu puzzle-sort-axmol/ blueprint.json # thể loại, stack, cỡ, điểm ARCHITECTURE.md STRUCTURE.md DECISIONS.md starter/ | ref.json recipes/ # 112 recipe, bắt buộc nhãn stacks/ domains/ # chuyển từ knowledge/ catalog.json # chỉ mục 1 dòng mỗi mục
// roles/dev-axmol/role.json — nơi DUY NHẤT khai nhóm model { "runtime": "claude", "group": "coding-medium", // nhóm trong models.json "ladder": ["coding-medium", "analysis", "frontier"], "stacks": ["axmol-2.11"], "mcp": ["brain:search", "brain:ask"], "access": "write", // read | report | write | test-write "inputs": ["CHANGE.md#Hiểu yêu cầu"], "outputs": [{ "path": "REPORT.md", "required": true }], "inject": { "lessons": 10 } }
| Harvest thu gì | Lấy từ | Thành gì trong hub |
|---|---|---|
| Kiến trúc | STRUCTURE.md, ARCHITECTURE.md, DECISIONS.md, cây thư mục code | Blueprint mới, hoặc bản cập nhật của blueprint dự án đã dùng |
| Bài học vai | Solution và Knock-on trong task, các run fail rồi sửa được, ASSUMPTIONS.md | Mục mới trong lessons.md của vai, mỗi mục tối đa 3 dòng và ghi nguồn |
| Recipe | Các recipe trong docs/recipes có scope: generic | recipes/ (dùng lại collect.mjs, chỉ đổi đích sang hub) |
| Số liệu | Thời gian mỗi phase, số run, tỉ lệ cổng fail | blueprint.json.stats, dùng để xếp hạng khi đề xuất blueprint |
Bài học chỉ được ghi khi đã thấy agent mắc lỗi đó thật (cách BMAD "record"). Duyệt 2 bước. Người đang triển khai dự án duyệt bản nháp harvest trong inbox monitor, bỏ mục sai và che tên khách hàng. Sau đó merge request vào hub do CEO hoặc Tech lead chính duyệt (CODEOWNERS 2 người, cần 1 duyệt). Harvest còn đọc log run và đề xuất cải tiến môi trường agent: lỗi cơ học thì thêm check vào npm test, chỉ việc cần phán đoán mới vào CODING_STANDARDS.md, rút gọn CLAUDE.md, bỏ luật không đổi hành vi.
Bài học chỉ đổi hub bằng: thêm mục lessons.md, nối luật vào AGENTS.md, đổi group/ladder, thêm/bỏ 1 cổng, đổi 1 trường commands. Mỗi loại có giới hạn giá trị. Không sửa tự do.
Áp vào .phoenix/roles/<vai>.json của dự án. Chạy ổn qua 1 mốc mới thành merge request lên hub.
Mục đã phát hành chỉ ra version mới. Gửi kèm baseVersion, hub mới hơn thì báo xung đột. Dự án nâng bằng phoenix.mjs hub upgrade, có diff.
{{params.x}}, tối đa 20, kiểu string/int/number/bool. Thiếu hoặc lạ thì từ chối. Thay 1 lượt.
Id đặt trước lần gửi đầu. 429/5xx thử lại tối đa 5 lần, 4xx không thử, 409 đọc lại bản đã có. --check kiểm offline.
| Nhóm vai | 18 vai đợt đầu | Việc chính |
|---|---|---|
| Sản phẩm | po-game, po-app, game-design, product-design | GDD/PRD, SPEC màn, test case, UX/UI app |
| Kỹ thuật | tech-lead, dev-axmol, dev-cocos-creator, dev-unity, dev-go-backend, dev-nextjs, dev-tauri, devops | Tech lead chọn blueprint, duyệt kiến trúc, review cuối bằng nhóm review |
| Chất lượng | qa-game, qa-web, reviewer | Chạy test case, so ảnh, review code |
| Nội dung | art-game, re-apk | Asset, phân tích APK Unity IL2CPP và Cocos |
| Dữ liệu | data-bi | Số liệu dự án, nối BI của brain |
Hiện chỉ Axmol có khung game đầy đủ. Unity và Phaser đã có khung ở 2 skill khác trên máy, chỉ cần chuyển vào hub. Mọi blueprint game giữ cùng cách tách lớp của Axmol: core/ logic thuần có test, view/ hiển thị, app/ khởi động và QA.
| Blueprint | Hiện trạng | Nguồn | Việc cần làm |
|---|---|---|---|
game-axmol | ● Đủ | template/.variants/axmol | Chuyển nguyên sang hub |
game-cocos-creator | ● Mỏng | template/game: Boot.scene, QA, core/ và view/ rỗng | Thêm core mẫu có test, view mẫu, GUIDE, STRUCTURE |
game-unity | ● Chưa có | UnityGameBase của skill port-unity | Stack unity-6, workflow qua Unity MCP, QA runner C# |
game-phaser-h5 | ● Chưa có | H5GameBase của skill h5port | Stack phaser, QA bằng trình duyệt |
app-saas-admin | ● Có starter | Next.js + Go, gói saas-admin | Viết ARCHITECTURE + STRUCTURE |
app-booking | ● Có starter | Tauri + Go, gói booking | Như trên |
stacks.yaml hiện chỉ cho 1 engine game. Khoá game đổi thành danh sách, kick-off hỏi engine rồi mới đề xuất blueprint.
Khung mẫu là tài nguyên chung trong hub. Kick-off chọn loại dự án, hub trả cấu trúc khớp. Chưa có khung khớp thì phân tích một dự án mẫu, sắp lại theo khung gần nhất, kiểm đủ 8 tiêu chí rồi mới đưa vào hub.
| # | Tiêu chí chung của mọi blueprint | Cách kiểm |
|---|---|---|
| 1 | blueprint.json đủ trường: id, kind, stack, platforms, tags, version, source, commands, stats | Schema |
| 2 | Tách lớp: core/ logic thuần không gọi engine, view/ hiển thị, app/ khởi động và QA | Thư mục, grep import engine trong core |
| 3 | Đủ ARCHITECTURE, STRUCTURE, DECISIONS, GUIDE | File và mục bắt buộc không rỗng |
| 4 | commands khai build, test, run, qa. Tool Phoenix chỉ gọi qua đây | Schema |
| 5 | core/ có unit test xanh | Chạy commands.test |
| 6 | Phát sự kiện QA cùng định dạng qaEvents.ts / QaRunner | Chạy commands.qa smoke |
| 7 | Không tên khách hàng, key, asset bản quyền | Grep danh sách chặn |
| 8 | Dự án tạo từ blueprint build và test xanh | CI trên Mac mini |
Chuẩn lấy từ khung Axmol hiện có. Thêm tiêu chí thì sửa một chỗ (blueprints/CONTRACT.md + schema), mọi blueprint cũ chạy lại check, mục fail thành việc change.
25Brain là chương trình Go dùng PostgreSQL và pgvector, chạy trên máy chủ văn phòng, có MCP. Phoenix và brain là 2 hệ thống độc lập. Agent hỏi brain qua MCP để tra tài liệu công ty. Kho của Phoenix (phoenix-hub, repo dự án) ở GitLab, Phoenix không đẩy tài liệu, bài học hay số liệu sang brain. Brain không cần thêm phần nào riêng cho Phoenix.
Vai chỉ dùng search, ask, get_document, who_knows, recent. Vai data-bi thêm bi. Khai trong role.json.mcp.
Token OAuth 30 ngày của người chạy, lưu ở ~/.phoenix/brain.json, không vào repo. Brain lọc theo quyền người đó. Brain có token ngắn hạn thì monitor đổi sang trước khi giao agent.
Tìm trước khi đổi kiến trúc hoặc gặp lỗi lạ. Trích nguồn từ kết quả brain. Không thấy thì ghi "không có trong kho". Kiến thức mới viết vào docs/knowledge/.
Agent bỏ qua bước tra, báo cáo ghi "brain không trả lời". Không chặn việc. Tìm trong hub dùng catalog.json.
Brain muốn lập chỉ mục hub hay repo dự án thì tự thêm như một nguồn git thông thường, việc đó thuộc phía brain. Cấu hình MCP trên monitor che header và biến có TOKEN, SECRET, KEY, AUTH.
Các mốc sau cần kiểm luồng nhiều agent mỗi lần commit. Agent giả chạy theo kịch bản ghi sẵn, sửa dự án mẫu thật và chạy test thật, nên npm test không tốn token.
| Việc | Cách làm |
|---|---|
| Agent giả | fake-agent.mjs đọc fixtures/scenario-*.json, đi đủ Nhận → Chốt. Kịch bản: chạy thông, crash rồi resume, reviewer bác, thiếu đầu ra, fail lặp, duyệt cũ bị từ chối. Fail thì in transcript |
| Test model thật | Chỉ chạy khi PHOENIX_LIVE=1 |
| Hash file template | .phoenix/install-state.json ghi sha256 từng file copy. upgrade-project dừng khi gặp file người dùng đã sửa, ghi đè chỉ với --force. Lệnh doctor báo thiếu, lệch |
| Kiểm lệch nguồn sinh | .variants/* và luật 3 bản sinh từ 1 nguồn, --check báo thiếu, thừa, lệch trong npm test. Thư mục sinh có file đánh dấu |
| 1 nguồn luật | template/CLAUDE.md chỉ còn @AGENTS.md |
| Bảng nghiệm thu | Mỗi mốc 1 bảng: chức năng → file test, cần gì, mục "chưa phủ", mục "giới hạn của bằng chứng" |
Xong 21/11: 14 commit 6ae02c8…4dad403. CLI giả theo kịch bản, 7 nhóm model, phoenix.mjs env, file agent <vai>@<nhóm> có thẻ CCR, dispatcher qua launcher, 9 mã lỗi + đổi đích, thang nhóm trong autopilot, token/chi phí, huy hiệu trên monitor. npm test 352 pass, 2 fail chập chờn có sẵn; test live qua proxy pass.
Xong 21/11: 13 commit 918261c…76346b9. quick + CHANGES.md, change (CHANGE.md, bước Hiểu có seam, khoá scope, check 5 kiểm, 2 reviewer Spec/Chuẩn, verdict nộp 1 lần, sha256 lúc Chốt, archive), change-pilot chạy cả khi autopilot dừng, duyệt chặn bản cũ + nút Telegram (1 bot cả máy), nhánh/worktree, trang Change trên monitor. npm test 418 pass, 2 fail chập chờn có sẵn.
Code xong 21/11: cd15cb2…98ff59d. Dò 7 stack, join-project trên nhánh phoenix-join (chép không ghi đè, gộp package.json chỉ thêm khoá), 4 mapper → 7 file codebase, test mốc, khối phoenix:context, workflow maintain (cổng codebase, phase set), resume (bản đồ tiến độ, UNDERSTANDING.md, --apply, ch-wip), --mode auto, luật nạp theo dấu hiệu, vai explorer. npm test 457 pass. Chưa kiểm thật trên repo Go/Axmol thật.
Code xong 21/11: 5ad1303…10817fb. hub-init lập hub 18 vai (remote bare tạm khi chưa có GitLab), hub sync/status, .phoenix/hub.lock ghim từng mục và hub upgrade có diff, vai đọc theo tầng hub → dự án → người, access/inputs/outputs + MISSING_RESULT, recipe có tham số, hàng đợi harvest duyệt trên monitor, 5 loại sửa hub thử trên dự án trước, harvest push (409 đọc lại, thử lại 429/5xx), harvest retro, autopilot giao PO gom bài học sau Polish. Nghiệm thu 2 máy pass. npm test 524 pass. Chưa nối GitLab thật.
Code xong 21/11: c8bba2f…1f48cb1. 6 blueprint khởi đầu (Axmol, Cocos Creator, Unity, Phaser H5, app-saas-admin, app-booking) trong hub, chấm 8 tiêu chí (tách lớp, rò rỉ, build/test/qa), new-project --blueprint, blueprint suggest|use lúc kick-off, blueprint new từ dự án mẫu đi hàng đợi harvest, sửa gate/command áp thật, số liệu dự án vào stats. npm test 578 pass. Axmol/Unity/app chạy engine: chờ kiểm trên Mac mini.
Code xong 21/11: d9f5e5e…de9a51c. Claim task/change bằng push (người push sau bị từ chối, takeover có lý do), cổng/quyết định/agent ghi file theo người nên gộp git không xung đột, task --needs thiết bị, monitor máy tự gửi tóm tắt (outbox gửi bù khi mất mạng, không mang code), Monitor Server Node thuần chỉ xem: dự án, ai đang làm phần nào, online/offline, chi phí; mã mời 1 lần, chỉ lưu sha256 token. Nghiệm thu 2 clone + 2 PHOENIX_HOME pass. Chưa thử 2 máy thật.
Code xong 21/11: 69eb6b5…7d27abd. Client MCP chỉ đọc, tools/brain-mcp.mjs trong dự án chặn ingest, 5 công cụ đọc theo vai, brain setup|status chạy tay, blueprint suggest hỏi thêm brain. Brain tắt hoặc không trả lời trong 3s/10s thì chạy như cũ. Nghiệm thu với MCP server giả pass. Chờ brain giai đoạn 2 để kiểm thật (transport HTTP + Bearer là giả định).
upgrade-project.mjs.CCR-SUBAGENT-MODEL.phoenix code qua PhoenixProxy. Model agent con đặt bằng thẻ CCR-SUBAGENT-MODEL, id lấy từ /v1/models.join-project.mjs --mode resume.Việc ngoài Phoenix: sửa các combo trên PhoenixProxy cho khớp nhóm model và cấp quyền gọi combo cho key của đội. Địa chỉ repo hub điền vào ~/.phoenix/hub.json khi làm M4.