Skip to content

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ớpVai 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 DiscoveryChat 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 KitArtifact bền: constitution → spec.md → plan.md → tasks.md → analyze → converge
SuperpowersEngine 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 1ARequirements approvalDuyệt / từ chối / sửa spec.md
Gate 1BArchitecture approvalDuyệt / từ chối / sửa plan.md / ADR
Gate 1CImplementation authorizationỦy quyền code theo tasks.md
Gate 4QA verificationQA PASS/FAIL; Owner acceptance delivery là quyết định tách
Gate 5Production release approvalDuyệt / hoãn / từ chối phát hành production
D-0xxDecision ID trong docs/architecture/11-decisions-and-open-questions.mdSổ 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) ​

  1. Mở Cursor multi-root gồm ít nhất platform-ai (kit) + repo đích (vd. platform-ui) + platform-docs khi cần.
  2. Superpowers sẵn sàng; pin/version trong platform-ai/.minap/config/framework.yaml.
  3. Spec Kit state + specs/ nằm ở repo đích (xem 12-workspace-topology.md).
  4. 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ốngMẫu prompt (platform-ai)
Đã xong BA DiscoveryPaste khối đã điền từ .minap/templates/discovery/handoff-prompt.md
Yêu cầu đã rõ, bỏ qua DiscoveryCopy .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) ​

AiViệ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) ​

AiViệc
Orchestrator / SA/speckit-plan → plan.md (+ ADR nếu trọng yếu)
HumanDuyệ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) ​

AiViệ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) ​

AiViệ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 AgentsThự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 ​

AiViệc
Orchestrator / QA/speckit-converge; QA Agent xác minh AC trên đúng commit (testing ≠ Converge)
HumanChấ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) ​

AiViệc
HumanDuyệt phát hành production tường minh (hoặc hoãn)
Infra / pipelineDeploy 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ểmHuman 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ấpDual-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 hotfixGate nén + audit + retrospective (profile trong 04-sdd-workflow.md)

Bug startup (hybrid Spec Kit + Superpowers) ​

  1. Mẫu: platform-ai/.minap/templates/orchestrator/bug-startup-prompt.md
  2. Skills Spec Kit (kit): /speckit-bug-assess, /speckit-bug-fix, /speckit-bug-test
  3. Skills Superpowers (plugin): systematic-debugging, test-driven-development, verification-before-completion
  4. 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 brainstorming viết lại spec.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 stack
  • 04-sdd-workflow.md — state machine + D-019
  • 05-human-approval-gates.md — gói Gate
  • 02-spec-kit-integration.md / SOURCES.md — cài đặt
  • .cursor/skills/platform-orchestrator/SKILL.md
  • .cursor/skills/platform-superpowers-bridge/SKILL.md
  • governance/sdd-work-item-template.md

docs/ = SoT duy nhất · văn xuôi tiếng Việt + thuật ngữ chuyên ngành English