Smithery is now a part of Arcade.dev! Read more in our announcement here
Use when implementing any feature, bugfix, API, or UI change that should follow Beads plus OpenSpec plus Superpowers execution discipline, and also synchronize existing spec documents when the...
Quy trình đầy đủ từ yêu cầu → code đã verify. Tự động detect stack và apply conventions phù hợp.
Trước khi bắt đầu, xác định stack của task hiện tại:
BE (Backend) → Spring Boot / Java 21
FE (Frontend) → React / Vue / TypeScript
FS (Fullstack) → Cả hai
Cách detect:
Sau khi xác định stack → follow đúng profile bên dưới.
Skill này tách thành core + references/. Đọc file tương ứng, không suy đoán nội dung.
| Khi nào | Đọc file |
|---|---|
| Stack = BE hoặc FS | references/stack-be-spring.md |
| Stack = FE hoặc FS | references/stack-fe-react.md |
| Vào Phase -1 | references/superpowers.md |
| Vào Phase 1 (luôn) | references/openspec-templates.md |
| Phase 1 + Bước 0 chọn B/C/D/E | references/spec-layer.md |
| User chọn fast track | references/fast-track.md |
| Audit dọn dẹp / đầu session | references/hygiene.md |
| Vào Phase 5.5 (capture lesson) | references/lesson-schema.md |
| Có MCP nào available (Phase -1) | references/mcp-integration.md |
| Muốn cưỡng chế gate (tuỳ chọn) | hooks/README.md |
Chưa đọc reference của stack thì không được viết design-*.md, test, hay code.
Trước Phase 3 (trước khi sửa code lần đầu cho change hiện tại), phải hỏi user — không tự tạo worktree, không mặc định worktree.
Ngoại lệ (không hỏi worktree):
project: restricted cấm worktree → chỉ dùng branch trong workspace hiện tạiCâu hỏi chuẩn:
🔀 GIT CHO CHANGE NÀY — <change-name>
Bạn muốn cô lập code thế nào trước khi implement?
1. **Git worktree** — thư mục riêng (`.worktrees/<branch>/` hoặc convention repo)
2. **Feature branch** — `git switch -c <branch>` trong workspace hiện tại (không worktree)
3. **Workspace hiện tại** — chỉ khi đã ở branch feature và bạn chấp nhận rủi ro
Gợi ý: task lớn / song song nhiều việc → (1); fast track / sửa nhỏ → (2).
→ Trả lời 1, 2, hoặc 3 (hoặc mô tả ngắn).
Sau khi user chọn:
| Lựa chọn | Hành động |
|---|---|
| 1 — worktree | Invoke superpowers:using-git-worktrees; ghi path worktree + branch vào bead/OpenSpec note |
| 2 — branch | Tạo/checkout branch feature; không invoke worktree skill; vẫn cấm commit trực tiếp lên main/master |
| 3 — workspace hiện tại | Xác nhận tên branch hiện tại; nếu đang ở main → chuyển sang (2) trừ khi user insist |
Ghi lựa chọn vào metadata của epic:
bd update <epic-id> --set-metadata git_isolation=<worktree|branch|current>
Nguyên tắc: tiến độ phải query được bằng lệnh, không nằm dưới dạng chữ tự do trong description. Hai tầng, hai cơ chế:
| Tầng | Đơn vị | Cơ chế ghi | Cơ chế đọc |
|---|---|---|---|
| Change / feature | 1 epic bead ↔ 1 OpenSpec change | label sdlc:<phase> |
bd state <epic> sdlc → 4 |
| Task | child bead (--parent <epic>) |
status open/in_progress/closed + dependency |
bd children <epic>, bd epic status, bd ready |
Ghi phase (mỗi lần qua gate — bắt buộc):
bd update <epic-id> --remove-label sdlc:<cũ> --add-label sdlc:<mới>
Ghi thuộc tính change (metadata, không phải free text):
bd update <epic-id> \
--set-metadata openspec=<change-name> \
--set-metadata phase1_docs=<A|B|C|D|E> \
--set-metadata git_isolation=<worktree|branch|current>
⚠️ Key metadata không được chứa dấu
-(phải match[a-zA-Z_][a-zA-Z0-9_.]*) — dùnggit_isolation, không dùnggit-isolation.
Đọc tiến độ:
bd state <epic-id> sdlc # phase hiện tại của 1 change
bd list --label-pattern 'sdlc:*' # mọi change đang chạy + phase
bd count --by-label # phân bố: sdlc:4 = 1, sdlc:6 = 3 ...
bd children <epic-id> # cây task: ○ open ◐ in_progress ● blocked ✓ closed
bd epic status # "Progress: 2/3 children closed (67%)"
bd ready # task hết blocker, làm được ngay
bd list --metadata-field openspec=<change-name> # ghép bead ↔ OpenSpec change
Bảng phase: sdlc:0 capture → sdlc:1 docs → sdlc:2 test RED → sdlc:3 implement → sdlc:4 review → sdlc:5 docs → sdlc:6 archived (bead close ngay sau đó).
Quy tắc:
--add-label / --remove-label cho phase, không dùng bd set-state — set-state tạo thêm một event bead làm con của epic, khiến bd epic status đếm sai mẫu số (vd. báo 2/4 khi thực tế mới xong 1/3 task). Chỉ dùng set-state khi thực sự cần audit trail của từng lần đổi phase.--metadata-field openspec=..., không grep chuỗi trong description.sdlc-phase: N, phase1-docs: X, git-isolation: Y vào -d nữa — chúng đã có label/metadata tương ứng.--parent.Chi phí model không đều nhau; việc trong workflow cũng vậy. Chọn tầng theo hậu quả khi sai, không theo độ dài việc.
| Việc | Model | Lý do |
|---|---|---|
Phase 1 design (design.md, design-be/fe.md) · Phase 4 code review + security review |
opus | Suy luận sâu; quyết định sai ở đây lan xuống toàn bộ implement |
| Phase 2 viết test · Phase 3 implement | sonnet | Khối lượng lớn nhưng có test làm lưới an toàn — sai là FAIL ngay |
| Phase 5 docs (curl examples, component usage) · sinh dashboard | haiku | Cơ học, đã có contract/spec để bám |
Quy tắc:
Không gắn attribution dưới bất kỳ dạng nào — không Co-Authored-By:, không trailer ghi tên tool/agent. Luật này ghi đè hành vi mặc định của agent.
Dùng conventional commit sạch:
feat: add exchange rate lookup API
Implemented ULID-keyed entity, MapStruct mapper, and paged query endpoint.
Type: feat · fix · refactor · docs · test · chore · perf · ci
<token>, ${VAR}, your-key)..env không vào repo; chỉ commit .env.example.references/mcp-integration.md).cat / tail -f file log. Lọc trước: grep ERROR app.log | tail -20.--quiet / -q cho lệnh build/install; giới hạn log container (docker logs --tail 50).Ngoài spec, mỗi change còn sinh ra hiện vật: bàn giao giữa phase, bug tìm được khi test, báo cáo review, test report. Chỗ đặt chúng quyết định theo vòng đời, không theo tiện tay.
Nguyên tắc: OpenSpec change là ephemeral — openspec archive sẽ cuốn đi. Spec của feature là durable — sống cùng feature. Bỏ hiện vật durable vào chỗ ephemeral là mất nó.
openspec/changes/<change-name>/ ← EPHEMERAL
├─ proposal.md specs/ design.md tasks.md
├─ refs/ đầu vào của change: con trỏ tới docs/plans/, DetailDesign
├─ handoff/ bàn giao giữa phase + báo cáo review Phase 4
├─ bugs/ bug phát hiện trong Phase 2–4
└─ deliveries/ CHỈ khi feature không có Spec layer
specs/features/<feature>/ ← DURABLE
└─ deliveries/ api-spec, test report, Postman collection
← đích khi feature CÓ Spec layer
| Artifact | Vòng đời | Nơi ở |
|---|---|---|
handoff/, bugs/ |
Ephemeral — chỉ có nghĩa trong change này | Luôn openspec/changes/<change>/ |
refs/ |
Ephemeral — đầu vào của change | openspec/changes/<change>/ |
deliveries/ |
Durable — mô tả feature ở trạng thái cuối | Có Spec → specs/features/<feature>/deliveries/Không Spec → openspec/changes/<change>/deliveries/ |
Sinh gì ở phase nào:
| Phase | Ghi vào |
|---|---|
| 1 | refs/ — con trỏ tới plan (docs/plans/...), tài liệu đầu vào |
| 2–3 | bugs/ — bug phát hiện khi viết/chạy test |
| 3 | handoff/ — bàn giao khi đổi người/agent giữa task |
| 4 | handoff/ — báo cáo review + security review; deliveries/ — test report, Postman collection |
| 5 | deliveries/ — api-spec / component usage bản cuối |
⛔ Luật khử trùng lặp — bắt buộc:
refs/ và deliveries/ cố ý trùng phạm vi với OpenSpec / Spec / Postman. Khi trùng, ghi con trỏ tới file gốc, không copy nội dung:
# refs/implementation-plan.md
→ Nguồn: `docs/plans/2026-08-14-exchange-rate-api.md`
Tóm tắt 1–2 câu vì sao plan này liên quan change. Hết. Không copy nội dung plan.
Copy nội dung là tự tạo nguồn sự thật thứ hai — lần sửa sau sẽ lệch, và không ai biết bên nào đúng.
Trước khi vào Phase 0, kiểm tra nhanh các điều kiện tối thiểu:
bd / Beads workflow có dùng được khôngopenspec workflow có dùng được không/opsx:* skills có sẵn không (/opsx:propose, /opsx:apply, /opsx:verify, /opsx:archive, /opsx:ff nếu dùng fast track)./mvnw, ./gradlew, npm, yarn, pnpm, ...)references/superpowers.md; ghi nhận available / partial / unavailable trước Phase 0references/hygiene.mdhooks/, các gate Phase 1 / secret / Phase 5.5 được chặn cơ học; xem hooks/README.mdDò xem môi trường có MCP nào, in status. Thiếu MCP không chặn workflow — chỉ mất năng lực tương ứng.
🔌 MCP PREFLIGHT — <repo/service>
gitnexus : ✅ (đã index <n> repo) | ❌ → Phase 1/3/4 impact analysis
sonarqube : ✅ | ❌ → Phase 4 quality gate đo được
oracle : ✅ | ❌ → Phase 1/3 BE schema verify
atlassian : ✅ | ❌ → Phase 0 import Jira · Phase 5/6 publish
→ MCP nào ❌ thì bỏ qua bước tương ứng, KHÔNG dừng workflow
→ Riêng sonarqube ❌: Phase 4 phải ghi "quality gate: not measured", KHÔNG được ghi PASS
📄 Bảng tool đầy đủ, workflow chuẩn theo phase:
→ references/mcp-integration.md
Tra lesson đã có — trước khi tự mò một bug kỹ thuật khó:
grep -ril "<từ khoá triệu chứng>" docs/lessons/
Nếu thiếu tooling bắt buộc:
Nếu stack detection chưa đủ chắc chắn:
Kiểm tra init:
.beads/ đã được khởi tạo cho repo/service hiện tạibd init hoặc flow init Beads theo môi trường agent hiện tạiTạo epic cho change (xem Progress model):
Mỗi change/feature = 1 epic bead; task con sẽ được seed sau Phase 1 gate với --parent.
bd create "<tên yêu cầu>" \
-t epic \
-p <0=critical|1=high|2=medium|3=low> \
-d "<mô tả yêu cầu — chỉ nội dung nghiệp vụ, không nhét tiến độ>" \
-l "<domain labels: api|ui|backend|frontend>,sdlc-active,sdlc:0" \
--silent
Hotfix/task lẻ không sinh OpenSpec change riêng thì vẫn dùng
-t task, nhưng vẫn phải gắnsdlc:<phase>.
Nếu atlassian available — import từ Jira thay vì gõ tay: jira_get_issue → tạo epic + --set-metadata jira=<key>.
Gắn metadata truy vết:
bd update <epic-id> --set-metadata openspec=<change-name>
# phase1_docs và git_isolation sẽ set sau (Phase 1 Bước 0 / Phase 3 gate)
Map dependencies & bắt đầu:
bd dep add <epic-mới> <issue-phải-xong-trước> # nếu có
bd update <epic-id> -s in_progress
Trước khi chuyển sang Phase 1: chạy Phase 1 — Bước 0 (xác nhận phạm vi tài liệu với user). Không tạo file OpenSpec/Spec cho đến khi user approve bộ tài liệu.
Dừng lại và hỏi user trước khi chạy openspec new change, trước khi tạo/sửa bất kỳ proposal.md, spec.md, design.md, tasks.md, hay file Spec nào.
Superpowers (nếu scope còn mơ hồ): invoke superpowers:brainstorming trước khi đề xuất bộ tài liệu — nhưng vẫn phải có xác nhận user ở bước này trước khi viết file.
Câu hỏi chuẩn (in cho user):
📄 PHẠM VI TÀI LIỆU — Phase 1
Change/feature: <tên>
Stack: BE | FE | FS
Service/repo đích: <path>
Ở change này bạn muốn tạo những tài liệu nào?
A) OpenSpec đầy đủ (mặc định tối thiểu — luôn khuyến nghị):
- proposal.md
- specs/<capability>/spec.md
- design.md
- tasks.md
B) OpenSpec + Spec BE (khi repo đã có hoặc cần trace BE):
- A + requirements.md, design-be.md, api-contract.md, tasks-be.md, testcase.md
C) OpenSpec + Spec FE:
- A + requirements.md, design-fe.md, component-contract.md, tasks-fe.md, testcase.md
D) OpenSpec + Spec FS (BE + FE docs)
- A + requirements.md, design-be.md, design-fe.md, api-contract.md,
component-contract.md, tasks-be.md, tasks-fe.md, testcase.md
E) Tùy chỉnh — liệt kê file cụ thể (vd. chỉ proposal + spec scenarios, bỏ design tạm thời)
Ghi chú:
- OpenSpec là lớp bắt buộc cho mọi change; không được bỏ cả bộ A trừ khi user chọn Fast Track và đồng ý tối thiểu hóa rõ ràng.
- Spec chỉ thêm khi repo đã có convention, feature đã có folder spec, hoặc user yêu cầu.
→ Trả lời A/B/C/D/E (hoặc liệt kê file). Agent chỉ viết tài liệu sau khi bạn xác nhận.
Quy tắc agent:
bd update <epic-id> --set-metadata phase1_docs=A (hoặc phase1_docs=B_api_contract_only); đồng thời chuyển phase: bd update <epic-id> --remove-label sdlc:0 --add-label sdlc:1openspec new change và tạo đúng file đã chốt (không tạo file ngoài phạm vi).Mặc định khi user nói "theo repo" / không trả lời chi tiết:
openspec/ → Aspecs/features/<feature>/ cho feature này → B/C/D theo stackNếu gitnexus available — chạy TRƯỚC khi viết design.md:
impact({target: "<class>", repo: "<repo>"})
api_impact({target: "<class>", repo: "<repo>"})
→ Blast radius lớn hơn dự kiến ⇒ DỪNG, báo user trước khi tiếp tục. Đây là điểm chặn, không phải thông tin tham khảo.
Nếu oracle available và stack = BE — đối chiếu DDL trong design-be.md với schema thật (get_table_schema, get_table_constraints, search_columns) trước khi chốt.
📄 references/mcp-integration.md
Chỉ bắt đầu 1A sau Bước 0 — user đã chốt phạm vi tài liệu (ít nhất nhóm A).
Tạo change:
openspec new change "<bd-id>-<tên-kebab-case>"
Chỉ tạo các file OpenSpec nằm trong phạm vi đã approve.
📄 Template đầy đủ (proposal.md, specs/<capability>/spec.md, design.md, tasks.md):
→ references/openspec-templates.md
Chỉ bắt đầu 1B nếu Bước 0 chọn B/C/D/E có file Spec — không tự thêm Spec khi user chỉ chọn A.
📄 Luật "khi nào cần / không cần Spec" + template stack-neutral (requirements.md, testcase.md, tasks-be/fe.md):
→ references/spec-layer.md
📄 Template stack-specific:
→ references/stack-be-spring.md — design-be.md, api-contract.md
→ references/stack-fe-react.md — design-fe.md, component-contract.md
Khi feature có đủ cả hai lớp tài liệu:
spec.md phải khớp với requirement/scenario trong requirements.mddesign.md và spec design-be.md / design-fe.md phải cùng technical directiondesign-be.md mục API Specification và Error Handling Contract phải khớp api-contract.md (endpoint, payload, status, BUS codes)tasks.md giữ milestone/change-level; spec tasks-be.md / tasks-fe.md giữ implementation detail (bám Implementation Logic trong design-be.md)testcase.md phải trace lại được các scenario đã viết trong OpenSpec/specScope & placement
📄 PHẠM VI TÀI LIỆU, và có approval rõ (A/B/C/D/E)--set-metadata phase1_docs=... và label sdlc:1 trên epic; chỉ tạo file nằm trong phạm vi đã chốtOpenSpec completeness
proposal.md nêu rõ WHY, phạm vi thay đổi, impact chínhspecs/<capability>/spec.md có đủ happy path + edge/error scenarios theo format WHEN/THENdesign.md có context, goals/non-goals, technical decisions, data flow/component treetasks.md có milestone chính, verification steps, và mapping theo capability/scenarioSpec decision
Spec completeness (nếu áp dụng)
requirements.md khớp OpenSpec scenarios và có acceptance criteriadesign-be.md: Architecture Overview, Package Structure, Class Diagram (Mermaid), Entity Design, API Specification, Implementation Logic (class + method + pseudo-code), Component Interaction, Data Flow Sequences, Database Schema (Oracle DDL), Error Handling Contract (BUS codes), Non-Functional Decisionsdesign-fe.md: Component Architecture, Feature Folder Structure, Component Tree (Mermaid), State Model, API Integration Contract, Implementation Logic (hook + method + pseudo-code), Props Flow & Events, Interaction Sequences (Mermaid), Cache & Persistence, Error/Loading/Empty States, Test Strategy, Non-Functional Decisionsapi-contract.md khớp design-be.md § API Specification + error semantics nếu có APIcomponent-contract.md khớp design-fe.md § Props Flow & Events nếu có FEtestcase.md trace được requirements/scenariostasks-be.md / tasks-fe.md phản ánh implementation detail theo stackTraceability & readiness
requirements.md) đã có hướng test tương ứng để sang Phase 2review scope / naming strategy từ Phase 1Sau khi viết xong tài liệu, DỪNG LẠI và trình bày tóm tắt cho user:
📋 REVIEW TÀI LIỆU — <change-or-feature-name>
**Phạm vi đã chốt (Bước 0):** <A|B|C|D|E + file list>
**OpenSpec (bắt buộc):**
- Proposal (WHY): [tóm tắt]
- Capability + Scenarios: WHEN ... THEN ...
- Design decisions: [bullet]
- Tasks.md: [milestone chính]
**Spec (nếu có / nếu cần maintain):**
- Requirements / AC: [tóm tắt]
- Design-be: [architecture, class/method logic chính, DDL, sequence] / Design-fe: [quyết định chính]
- API contract: [điểm chính — khớp design-be API Spec + BUS codes]
- Testcase + tasks-be/tasks-fe: [coverage chính]
**Sync check:**
- Nếu có cả 2: Scenario và tasks đã khớp chưa?
- Nếu chỉ có OpenSpec: lý do không dùng spec là gì?
---
Tài liệu đã đầy đủ chưa? Có điểm nào cần chỉnh không?
→ Trả lời "OK" hoặc "bắt đầu" để chuyển sang Phase 2 (TDD)
→ Hoặc nêu điểm cần chỉnh để cập nhật lại
Loop cho đến khi user approve:
Sau Phase 1 gate (trước Phase 2):
superpowers:writing-plans → lưu docs/plans/YYYY-MM-DD-<change-name>.mdtasks.md — mỗi task/milestone chính là child bead của epic, không tạo bead rời:T1=$(bd create "<task 1>" -t task --parent <epic-id> --silent)
T2=$(bd create "<task 2>" -t task --parent <epic-id> --deps "blocks:$T1" --silent)
ID con tự sinh dạng
<epic>.1,<epic>.2— nhìn ID là biết task thuộc change nào, không cần grep description. Task con kế thừa label của epic; nếu không muốn thì thêm--no-inherit-labels. Labelsdlc:<phase>chỉ có ý nghĩa ở epic — đừng đọc phase từ task con.
bd update <epic-id> --remove-label sdlc:1 --add-label sdlc:2bd children <epic-id> và bd ready phải ra đúng task đầu tiênSuperpowers: invoke superpowers:test-driven-development — viết test fail (RED) trước khi sang Phase 3.
📄 Template test theo stack → references/stack-be-spring.md (JUnit 5 + MockMvc) · references/stack-fe-react.md (Jest/Vitest + RTL + E2E)
Bắt buộc: chạy test → phải FAIL (RED) trước khi sang Phase 3.
Bắt buộc lần đầu vào Phase 3 cho mỗi change: chạy Git worktree decision (hỏi user 1/2/3). Không sửa code cho đến khi có câu trả lời.
Superpowers (sau gate git):
superpowers:using-git-worktreesbd update <epic-id> --remove-label sdlc:2 --add-label sdlc:3bd ready → bd update <task-id> --claim (atomic: set assignee + in_progress) → TDD RED/GREEN → bd close <task-id>bd children <epic-id> hoặc bd epic statussuperpowers:dispatching-parallel-agents hoặc subagent-driven-developmentsuperpowers:systematic-debugging🔌 MCP hook (nếu available):
gitnexus: query → context trước khi sửa symbol; shape_check khi đổi DTO/Entityoracle (BE): get_dependent_objects + explain_query_plan trước khi chạy migration/query nặng📄 Thứ tự implement + convention theo stack → references/stack-be-spring.md · references/stack-fe-react.md
Superpowers: trước khi báo PASS → invoke superpowers:verification-before-completion (chạy build/test//opsx:verify thật). Khi xử lý review feedback → superpowers:receiving-code-review.
Build & Test:
# BE
# Chạy test/build command hiện có của repo (ví dụ: ./mvnw test, ./gradlew test, ./gradlew bootJar)
# FE
# Chạy test/build command hiện có của repo (ví dụ: npm test && npm run build, yarn test && yarn build, pnpm test && pnpm build)
OpenSpec Verify (chung, luôn chạy):
/opsx:verify <change-name>
Spec sync check — bắt buộc khi feature có cả 2 lớp tài liệu:
Đây là check thật, không phải lời khuyên. Đối chiếu từng cặp; lệch bất kỳ mục nào = gate FAIL, sửa trước khi sang Phase 5.
spec.md có Requirement tương ứng trong requirements.md (và ngược lại — không có requirement mồ côi)api-contract.md khớp design-be.md § API Specification: endpoint, payload, status code, BUS codescomponent-contract.md khớp design-fe.md § Props Flow & Events: props, callback signature, trạng thái hiển thịtestcase.md trace ngược được về đúng 1 Scenario hoặc 1 ACtasks.md (milestone) không mâu thuẫn tasks-be.md / tasks-fe.md (implementation); cả hai đã check hếtNếu feature chỉ có OpenSpec → bỏ qua block này, ghi rõ spec sync: n/a (OpenSpec only) trong báo cáo gate.
Backend API verification artifact (BE/API):
📄 Luật generate/update Postman collection + convention lưu trữ → references/stack-be-spring.md
🔌 Quality gate — đo được (nếu sonarqube available):
validate_quality_gate → PASSget_issues severity BLOCKER/CRITICAL → 0get_metrics coverage không giảm so với trước change⛔ Nếu sonarqube không available: ghi đúng chữ quality gate: not measured (sonarqube unavailable). Cấm ghi PASS cho hạng mục không có công cụ đo — đánh giá của reviewer là ý kiến, không phải số đo.
🔌 Review có bằng chứng (nếu gitnexus available): detect_changes → impact từng class đã sửa → ghi kết quả vào handoff/.
Code Review (chọn đúng agent):
| Stack | Agent |
|---|---|
| Java general | Ưu tiên java-reviewer, nếu không có thì dùng code-reviewer |
| Java Spring | Ưu tiên java-reviewer, nếu không có thì dùng code-reviewer |
| Spring Boot BE | Ưu tiên java-reviewer, nếu không có thì dùng code-reviewer |
| React FE | Ưu tiên typescript-reviewer, nếu không có thì dùng code-reviewer |
| Vue FE | Ưu tiên typescript-reviewer, nếu không có thì dùng code-reviewer |
| Cả hai | Thử reviewer chuyên biệt song song; nếu reviewer nào không có thì thay bằng code-reviewer |
Fallback rule:
code-reviewerSecurity Review (chung — focus khác):
security-reviewer
Sau khi có kết quả review, DỪNG LẠI và trình bày tóm tắt cho user:
🔍 KẾT QUẢ REVIEW — <change-name>
**Build & Test:** ✅ PASS / ❌ FAIL
**OpenSpec Verify:** ✅ PASS / ❌ X scenarios fail
**Quality Gate (sonarqube):** ✅ PASS / ❌ FAIL / ➖ not measured (unavailable)
**Spec Sync Check:** ✅ PASS / ❌ lệch `<nêu rõ cặp file nào lệch>` / ➖ n/a (OpenSpec only)
**Postman Collection (BE/API nếu áp dụng):** ✅ generated/updated + smoke pass / ➖ not applicable / ❌ fail
**Reviewer Used:**
- Backend/API: `java-reviewer` / `code-reviewer`
- Frontend/UI: `typescript-reviewer` / `code-reviewer`
**Tracking (đọc bằng lệnh, không gõ tay):**
- Epic: `<epic-id>` — `bd state <epic-id> sdlc` → `4`
- OpenSpec change: `<change-name>` — `bd list --metadata-field openspec=<change-name>`
- Task con: `bd epic status` → `<n>/<m> closed (<x>%)`
- Task chưa đóng: `bd children <epic-id>` → liệt kê ○ / ◐ còn lại
> Trước khi in block này phải chạy `bd update <epic-id> --remove-label sdlc:3 --add-label sdlc:4`.
> **Không** được báo Phase 4 PASS khi `bd epic status` chưa 100% hoặc còn task ◐/○.
**Code Review Issues:**
- [CRITICAL] <file>: <mô tả> → đã fix / cần fix
- [HIGH] <file>: <mô tả> → đã fix / cần fix
- [MEDIUM] <file>: <mô tả> → đã fix / bỏ qua (lý do)
**Security Issues:**
- [CRITICAL/HIGH] <mô tả> → đã fix / cần fix
- Không có issues
**Thay đổi phát sinh sau review:**
- <file>: <thay đổi gì so với plan ban đầu>
- Nếu có spec: file spec nào đã sync thêm
---
Code đã ổn chưa? Có điểm nào cần chỉnh thêm không?
→ Trả lời "OK" hoặc "viết docs" để chuyển sang Phase 5
→ Hoặc nêu điểm cần chỉnh để fix thêm
Loop cho đến khi user approve:
📄 Template docs theo stack → references/stack-be-spring.md (curl examples) · references/stack-fe-react.md (component usage)
Chạy sau khi viết docs, trước Phase 5 gate. Mục đích: change này đóng lại nhưng thứ học được thì không mất theo.
Câu hỏi bắt buộc trả lời:
Trong change này có gì mà lần sau gặp lại sẽ mất thời gian điều tra lại không?
Nếu KHÔNG — ghi nhận rồi đi tiếp, không bịa lesson cho đủ thủ tục:
bd update <epic-id> --set-metadata lesson=none
Nếu CÓ — phân loại theo câu hỏi "dự án khác có dùng được không?":
| Loại | Đích | Frontmatter |
|---|---|---|
| Kỹ thuật thuần (framework / engine / tool) | docs/lessons/<tech-stack>/<id>.md |
cross_project: true |
| Gắn business/domain riêng dự án này | docs/knowledge/<...>.md |
cross_project: false |
bd update <epic-id> --set-metadata lesson=<id>
Tiêu chí "đáng ghi" — phải thoả cả hai, nếu không thì lesson=none:
📄 Schema frontmatter đầy đủ, cấu trúc thân bài, và cách tra cứu lesson đã có:
→ references/lesson-schema.md
Nếu đã cài
hooks/sdlc-lesson-gate.cjs,bd close <epic>sẽ bị chặn cho tới khi có metadatalesson=.
Phần giá trị nhất của một lesson không phải nguyên nhân thật, mà là các giả thuyết sai đã loại trừ — đó là thứ giúp người sau không đi lại đường vòng. Đừng bỏ mục đó.
Tra cứu về sau bằng grep -ril "<từ khoá>" docs/lessons/ — đặt tên file và tags: sao cho grep tìm được.
Sau khi viết xong docs, DỪNG LẠI và trình bày tóm tắt cho user:
📝 DOCS HOÀN THÀNH — <change-name>
**BE — curl examples:**
- Happy path: [tóm tắt endpoint + response]
- Error case: [tóm tắt error scenario]
**FE — Component usage:**
- Props: [liệt kê props chính]
- Usage example: [snippet ngắn]
**Checklist Done:**
- [ ] Tất cả Scenarios có test tương ứng
- [ ] Build + tests PASS
- [ ] /opsx:verify không fail
- [ ] Nếu có spec: spec files đã sync với code và OpenSpec
- [ ] Nếu có cả 2 lớp: **Spec sync check** ở Phase 4 gate đã PASS (6 mục đối chiếu)
- [ ] Nếu BE/API có endpoint mới hoặc đổi API surface/behavior đã expose: Postman collection đã được update ở Phase 4 và smoke pass
- [ ] Không có CRITICAL/HIGH từ review
- [ ] Docs đã sinh
- [ ] Phase 5.5: đã trả lời câu hỏi capture lesson (ghi file hoặc `lesson=none`)
- [ ] `deliveries/` đã ở đúng chỗ theo vòng đời (durable → `specs/features/<feature>/` nếu có Spec)
---
Mọi thứ đã ổn chưa? Sẵn sàng đóng issue và archive chưa?
→ Trả lời "OK" hoặc "close" để chuyển sang Phase 6 (Archive & Close)
→ Hoặc nêu điểm còn thiếu để bổ sung
Chỉ chuyển Phase 6 sau khi user confirm.
Superpowers: trước archive → invoke superpowers:finishing-a-development-branch (merge/PR/push; cleanup worktree nếu đã dùng worktree ở Phase 3).
bd update <epic-id> --remove-label sdlc:5 --add-label sdlc:6
openspec archive "<change-name>"
bd epic status # phải 100% children closed trước khi đóng epic
bd close <epic-id>
bd update <epic-id> --remove-label sdlc-active
bd ready --json --limit 5 # xem việc tiếp theo
Nếu còn task con chưa closed,
bd epic close-eligiblesẽ không coi epic này đủ điều kiện — đóng task con trước, đừng đóng ép epic.
⛔ Trước khi archive — kiểm deliveries/:
Nếu feature có Spec layer mà deliveries/ vẫn nằm trong openspec/changes/<change>/ → chuyển sang specs/features/<feature>/deliveries/ trước khi archive, nếu không openspec archive sẽ cuốn mất api-spec và test report (xem Artifact trail).
Trước khi archive/close:
Implement xong (Phase 3–4) nhưng quên Phase 5 (docs) và Phase 6 (archive + bd close) → openspec/changes/* và Beads tích lũy, khó biết cái nào còn sống.
📄 Audit commands, dấu hiệu stale đọc từ label, xử lý Resume / Park / Abandon:
→ references/hygiene.md
Streamline quy trình, không bỏ quality gate. Bước 0 vẫn áp dụng; openspec archive + bd close vẫn bắt buộc trong cùng session.
📄 Lệnh + luật đầy đủ → references/fast-track.md
| Phase | BE (Spring Boot) | FE (React/Vue) |
|---|---|---|
| Test framework | JUnit 5 + MockMvc | Repo test runner (Jest/Vitest/...) + RTL/framework equivalent + E2E cho critical flows |
| Implement order | Entity→Repo→DTO→Service→Controller | Types→API→Hook→Component→Page |
| Code review agent | java-reviewer nếu environment có sẵn, fallback code-reviewer |
typescript-reviewer nếu environment có sẵn, fallback code-reviewer |
| Security focus | SQL injection, auth | XSS, data exposure |
| Docs / verify output | Postman verify artifact (Phase 4 nếu có endpoint mới hoặc đổi API surface/behavior đã expose) + curl examples (Phase 5) | Component props + usage |
| Build check | Chạy test/build command hiện có của repo | Chạy test/build command hiện có của repo |
[ ] Tất cả scenarios trong OpenSpec có test tương ứng
[ ] Nếu có spec: requirements / testcase / AC cũng có test tương ứng
[ ] Build + tests PASS
[ ] /opsx:verify không fail scenario nào
[ ] Nếu có spec: spec files đã sync với code và OpenSpec
[ ] Nếu có cả 2 lớp: Spec sync check ở Phase 4 gate đã PASS (6 mục đối chiếu)
[ ] Nếu BE/API có endpoint mới hoặc đổi API surface/behavior đã expose: Postman collection đã được update ở Phase 4 và smoke checks pass
[ ] Không có CRITICAL/HIGH từ code review
[ ] Không có security issues
[ ] Docs (curl hoặc component usage) đã sinh
[ ] Phase 5.5: đã trả lời câu hỏi capture lesson (ghi file hoặc lesson=none)
[ ] deliveries/ đã ở đúng chỗ theo vòng đời (durable → specs/features/<feature>/ nếu có Spec)
[ ] tasks.md đã hoàn tất
[ ] Nếu có spec: tasks-be.md / tasks-fe.md cũng đã hoàn tất
[ ] `bd epic status` → 100% children closed (không còn task ○/◐)
[ ] `bd state <epic-id> sdlc` → `6`
[ ] Change đã archive
[ ] Beads epic đã close + đã gỡ label `sdlc-active`
[ ] Nếu dùng Superpowers: plan file (`docs/plans/...`) khớp `tasks.md`; beads task đã close; branch/worktree đã land (push/PR)
