Appearance
Hướng dẫn sử dụng đầu–cuối — AI Team + Spec Kit + Superpowers
Version: 1.1
Date: 2026-11-19
Status: Working baseline
1. Mục đích
Tài liệu này chỉ cách Human mở một yêu cầu mới và đi hết stack nền tảng:
| Lớp | Vai trò trong hành trình |
|---|---|
| Human (Project Owner) | Nêu ý định, (tuỳ chọn) chạy BA Discovery, trả lời clarify, duyệt Gate |
| BA Discovery | Chat riêng trước SDD; gói .minap/discovery/ + handoff prompt; dừng |
| Orchestrator (chat Cursor Agent chính) | Điều phối SDD sau khi Owner paste prompt / nêu yêu cầu |
| Specialist Agents (BA Requirements, SA, PM, Developers, QA, Infra) | Deliverable có biên qua .cursor/agents/ |
| Spec Kit | Artifact bền: constitution → spec.md → plan.md → tasks.md → analyze → converge |
| Superpowers | Engine implement ưu tiên sau Gate 1C (Implementation authorization) (TDD, subagent, review) |
Chi tiết chuẩn mực: 04-sdd-workflow.md, 05-human-approval-gates.md, D-019 (Decision 019 — Superpowers là engine implement ưu tiên sau Gate 1C). Skill: platform-orchestrator, platform-superpowers-bridge.
1.1 Mã Gate và Decision (không phải acronym tiếng Anh)
Các mã này là ID quy trình, không phải viết tắt kiểu “HTTP”. Sau lần ghi đầy đủ dưới đây, dùng dạng ngắn (Gate 1C, D-019) là đủ.
| Mã | Nghĩa đầy đủ | Human quyết gì |
|---|---|---|
| Gate 1A | Requirements approval | Duyệt / từ chối / sửa spec.md |
| Gate 1B | Architecture approval | Duyệt / từ chối / sửa plan.md / ADR |
| Gate 1C | Implementation authorization | Ủy quyền code theo tasks.md |
| Gate 4 | QA verification | QA PASS/FAIL; Owner acceptance delivery là quyết định tách |
| Gate 5 | Production release approval | Duyệt / hoãn / từ chối phát hành production |
| D-0xx | Decision ID trong docs/architecture/11-decisions-and-open-questions.md | Sổ DECIDED / OPEN (vd. D-019 = Superpowers sau 1C) |
Gate 1 được tách A / B / C để requirements, architecture và ủy quyền implement là ba quyết định Human riêng.
1.2 Confirm của Owner trên chat (tiếng Việt)
File Spec Kit vẫn English. Với confirm Gate / QA / clarification, Orchestrator chat với Owner bằng tiếng Việt, một câu mỗi lượt, rồi cập nhật artifact English sau mỗi câu trả lời. Chi tiết: 13-documentation-language.md và 05-human-approval-gates.md.
Ví dụ (Orchestrator → Owner ở Gate 1A):
text
Gate 1A — Duyệt yêu cầu
Work item: <id> · commit: <sha>
File: specs/<feature>/spec.md (SoT — VI + thuật ngữ EN)
Tóm tắt: …
Câu hỏi (1/1): Bạn APPROVE / REJECT / yêu cầu chỉnh spec này?Ví dụ (clarify / QA — một câu):
text
Cần confirm trước khi ghi vào spec/QA note:
Bạn muốn validation lỗi hiện inline dưới từng field, hay một banner tổng ở đầu form?
(Trả lời xong tôi sẽ cập nhật artifact English rồi hỏi câu tiếp nếu còn.)2. Mô hình tinh thần (ai gõ gì)
Quan trọng: Thường bạn chỉ nói với một chat Cursor Agent = Orchestrator. Orchestrator gọi slash skill Spec Kit và/hoặc subagent chuyên gia. Không bắt buộc mỗi role một chat riêng.
3. Điều kiện trước (một lần / máy hoặc repo)
- Mở Cursor multi-root gồm ít nhất
platform-ai(kit) + repo đích (vd.platform-ui) +platform-docskhi cần. - Superpowers sẵn sàng; pin/version trong
platform-ai/.minap/config/framework.yaml. - Spec Kit state +
specs/nằm ở repo đích (xem12-workspace-topology.md). - SoT tài liệu người:
platform-docs(VitePress).
4. Đường feature đầy đủ (mặc định)
Dùng cho feature mới / trọng yếu. Ví dụ giả định: “Admin Workspace mời thành viên bằng email.”
Bước −1 — (Tùy chọn) BA Discovery — chat riêng
Khi ý tưởng còn mơ hồ: mở chat Agent mới, gọi ba-discovery (không dùng chat Orchestrator SDD).
Mẫu prompt khởi động (SoT trong platform-ai): .minap/templates/discovery/startup-prompt.md — copy khối fenced, điền Idea/Target/Slug rồi gửi.
Khi xong: copy prompt trong handoff-prompt.md (mẫu: .minap/templates/discovery/handoff-prompt.md) → sang Bước 0. Không cần approval record discovery.
Bước 0 — Human mở Orchestrator
Trong chat Agent Cursor (hội thoại chính = Orchestrator):
| Tình huống | Mẫu prompt (platform-ai) |
|---|---|
| Đã xong BA Discovery | Paste khối đã điền từ .minap/templates/discovery/handoff-prompt.md |
| Yêu cầu đã rõ, bỏ qua Discovery | Copy .minap/templates/orchestrator/startup-prompt.md |
Điều xảy ra: Orchestrator đọc rules/governance, chọn repo + thư mục feature, có thể tạo .minap/work-items/<id>/, ủy BA Requirements + /speckit-specify. Nếu có gói discovery: dùng làm Intake input, vẫn sinh spec.md làm SoT Gate 1A.
Bước 1 — Requirements (Spec Kit + BA Requirements) → Gate 1A (Requirements approval)
| Ai | Việc |
|---|---|
| Orchestrator / BA Requirements | /speckit-specify (và /speckit-clarify nếu cần) → specs/<feature>/spec.md |
| Human | Đọc spec.md (EN SoT). Duyệt / từ chối / yêu cầu sửa |
Ví dụ (Human sau khi đọc bản nháp):
text
Gate 1A: APPROVE requirements for work item <id> at commit <sha>.
Record the approval under .minap/work-items/<id>/approvals/.
Then proceed to architecture plan with SA. Stop for Gate 1B.Chỉ “OK” trên chat là bằng chứng yếu — Orchestrator phải ghi approval record bền (xem 05-human-approval-gates.md).
Bước 2 — Architecture (Spec Kit + SA) → Gate 1B (Architecture approval)
| Ai | Việc |
|---|---|
| Orchestrator / SA | /speckit-plan → plan.md (+ ADR nếu trọng yếu) |
| Human | Duyệt kiến trúc |
Ví dụ:
text
Gate 1B: APPROVE architecture at commit <sha>. Proceed to tasks with PM. Stop for Gate 1C.Bước 3 — Tasks + analyze (Spec Kit + PM) → Gate 1C (Implementation authorization)
| Ai | Việc |
|---|---|
| Orchestrator / PM | /speckit-tasks → tasks.md; tuỳ chọn /speckit-analyze / checklist |
| Human | Ủy quyền implement (Gate 1C) |
Ví dụ:
text
Gate 1C: AUTHORIZE implementation for tasks.md at commit <sha>.
Handoff to Developers via Superpowers (D-019). Record engine = Superpowers.
Do not deploy. Stop when implementation + tests are ready for QA.Trước thông điệp này (và approval đã ghi), Developers không được bắt đầu code feature.
Bước 4 — Implement (Superpowers + Developers)
| Ai | Việc |
|---|---|
| Orchestrator | Đóng gói handoff: path feature, SHA tasks.md, path được phép, DoD, lệnh test → xem platform-superpowers-bridge |
| Frontend / Backend / Infra Agents | Thực thi bằng Superpowers (TDD, subagent-driven-development hoặc executing-plans, review). SoT = tasks.md đã duyệt |
| Fallback | /speckit-implement chỉ cho slice nhỏ; ghi engine |
Ví dụ (Human hoặc Orchestrator tiếp tục):
text
Implement authorized tasks.md @ <sha> in platform-core using Superpowers.
Do not expand scope. Do not replace spec/plan/tasks. Prefer TDD.
When done, report commits, test commands/results, then run Converge + QA.Superpowers có thể ghi: code, test, commit; ghi chú tuỳ chọn dưới docs/superpowers/. Các ghi chú đó không phải Spec Kit SoT.
Bước 5 — Converge + QA → Gate 4 (QA verification) + Owner acceptance
| Ai | Việc |
|---|---|
| Orchestrator / QA | /speckit-converge; QA Agent xác minh AC trên đúng commit (testing ≠ Converge) |
| Human | Chấp nhận hoặc từ chối delivery sau QA PASS |
Ví dụ:
text
Run Spec Kit converge and independent QA on commit <sha>.
Report Gate 4 verdict. I will Owner-accept only after QA PASS.Superpowers xong một branch ≠ Gate 4.
Bước 6 — Release → Gate 5 (Production release approval)
| Ai | Việc |
|---|---|
| Human | Duyệt phát hành production tường minh (hoặc hoãn) |
| Infra / pipeline | Deploy chỉ khi có Gate 5 + kiểm soát ngoài |
Ví dụ:
text
Gate 5: APPROVE production release of commit <sha> for <env> in change window <…>.
Follow approved rollback plan. No credential rotation in this change.5. Cheat sheet prompt
| Thời điểm | Human nói (ngắn) |
|---|---|
| Intake | “Feature mới: … Không code trước Gate 1C. Bắt đầu Specify.” |
| Sau spec | “Gate 1A: APPROVE @ <sha>. Rồi plan.” |
| Sau plan | “Gate 1B: APPROVE @ <sha>. Rồi tasks.” |
| Sau tasks | “Gate 1C: AUTHORIZE @ <sha>. Superpowers implement.” |
| Sau code | “Converge + QA trên <sha>. Gate 4?” |
| Sau QA PASS | “Owner ACCEPT delivery.” / “REJECT — lý do…” |
| Release | “Gate 5: APPROVE / DEFER release <sha>.” |
Slash skill Orchestrator thường dùng: /speckit-specify, /speckit-clarify, /speckit-plan, /speckit-tasks, /speckit-analyze, /speckit-checklist, /speckit-converge, và (fallback) /speckit-implement. Skill Superpowers thường gọi theo tên trong giai đoạn implement (test-driven-development, subagent-driven-development, …).
6. Đường nhẹ
| Loại việc | Đường tối thiểu |
|---|---|
| Docs rủi ro thấp | Dual-update EN→VI (13-documentation-language.md); bỏ architecture gate nếu không impact; Superpowers tùy chọn |
| Bug / issue (không đổi scope) | Paste platform-ai/.minap/templates/orchestrator/bug-startup-prompt.md → Spec Kit bug assess/fix/test + Superpowers systematic-debugging / TDD / verification → QA; artifact <target-repo>/.specify/bugs/<slug>/ |
| Emergency hotfix | Gate nén + audit + retrospective (profile trong 04-sdd-workflow.md) |
Bug startup (hybrid Spec Kit + Superpowers)
- Mẫu:
platform-ai/.minap/templates/orchestrator/bug-startup-prompt.md - Skills Spec Kit (kit):
/speckit-bug-assess,/speckit-bug-fix,/speckit-bug-test - Skills Superpowers (plugin):
systematic-debugging,test-driven-development,verification-before-completion - Không dùng Discovery / full feature SDD trừ khi assess escalate change control.
7. Sai thường gặp
- Bảo Agent “cứ implement” trước 1C.
- Coi Spec Kit skill xong hoặc Superpowers đóng branch là đã duyệt Gate.
- Chỉ sửa
docs/rồi kỳ vọng implementer theo đó (EN SoT thắng). - Để Superpowers
brainstormingviết lạispec.mdđã duyệt mà không change control. - Bỏ Converge/QA vì “test local đã pass.”
8. Tài liệu liên quan
01-overview.md— tổng quan stack04-sdd-workflow.md— state machine + D-01905-human-approval-gates.md— gói Gate02-spec-kit-integration.md/SOURCES.md— cài đặt.cursor/skills/platform-orchestrator/SKILL.md.cursor/skills/platform-superpowers-bridge/SKILL.mdgovernance/sdd-work-item-template.md