Cách detect:

User nói rõ "API", "endpoint", "service" → BE
User nói "component", "UI", "trang", "màn hình" → FE
Không rõ → hỏi user: "Task này là FE, BE, hay cả hai?"

Sau khi xác định stack → follow đúng profile bên dưới.

PHASE -1 — Preflight & Tooling Check ✅ CHUNG

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ông
openspec 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)
Build/test runner của repo là gì (./mvnw, ./gradlew, npm, yarn, pnpm, ...)
Repo/service hiện tại đã có spec riêng chưa hay chỉ quản lý bằng OpenSpec
Repo/service hiện tại đã có convention Postman collection/environment riêng chưa
Xác định đúng service/repo đích trước khi tạo OpenSpec hoặc spec; không tạo tài liệu vào nhầm service

Nếu thiếu tooling bắt buộc:

Dừng ở preflight
Báo rõ thiếu gì
Đề xuất fallback path hoặc cách khởi tạo trước khi tiếp tục

Nếu stack detection chưa đủ chắc chắn:

Hỏi lại user trước khi vào Phase 0
Nếu task chạm cả API/backend và UI/frontend → treat as FS và tách plan/test theo cả hai phía

PHASE 0 — Capture & Triage (Beads) ✅ CHUNG

Kiểm tra init:

Xác nhận .beads/ đã được khởi tạo cho repo/service hiện tại
Nếu chưa có → /beads:init

Tạo issue:

bd create "<tên yêu cầu>" \
  -t <feature|bug|task|epic> \
  -p <0=critical|1=high|2=medium|3=low> \
  -d "<mô tả: input/output/context/stack/openspec(+spec nếu có)>" \
  -l "<labels: api|ui|backend|frontend|openspec|spec?>"

Map dependencies & bắt đầu:

bd dep add <issue-mới> <issue-phải-xong-trước>  # nếu có
bd update <id> -s in_progress

PHASE 1 — Plan & Design (OpenSpec là bắt buộc, Spec là tùy ngữ cảnh) ✅ CHUNG

Rule gốc

Mọi thay đổi đều phải có OpenSpec.
Không phải thay đổi nào cũng phải có Spec.
Nếu service/feature đã có spec tương ứng hoặc user yêu cầu maintain spec → cập nhật cả OpenSpec + Spec.
Nếu không có spec tương ứng → làm trên OpenSpec; không bắt buộc tạo spec mới chỉ để cho đủ bộ.
OpenSpec và spec phải được tạo đúng service/repo chứa feature đó.
Không tạo spec/OpenSpec chung ở root project, và không đặt tài liệu sang service khác chỉ để tiện quản lý.

1A. OpenSpec — bắt buộc cho mọi thay đổi

Tạo change:

openspec new change "<bd-id>-<tên-kebab-case>"

proposal.md — WHY

## Why
[Vấn đề / cơ hội business]

## What Changes
- [Bullet: thay đổi ở high level]

## Capabilities
### New Capabilities
- `<tên>`: [mô tả]

## Impact
- `path/to/file`: [thay đổi gì]

specs//spec.md — WHAT ✅ CHUNG

### Requirement: <Tên>

#### Scenario: Happy path
- WHEN <điều kiện>
- THEN <kết quả>
- AND <bổ sung>

#### Scenario: Edge case / Error
- WHEN <input không hợp lệ>
- THEN <behavior>

Format WHEN/THEN dùng được cho cả API spec lẫn UI behavior spec.

design.md — HOW

## Context
[Trạng thái hiện tại]

## Goals / Non-Goals

## Technical Decisions
### Decision: <Quyết định>
[Lý do]

## Data Flow / Component Tree
[Diagram ASCII]

tasks.md — Checklist mức change

milestone / phase chính
verification steps
mapping theo capability

1B. Spec — chỉ dùng khi đã có spec tương ứng hoặc user yêu cầu

Khi nào phải dùng thêm Spec:

Service hiện tại đã có convention specs/features/<feature>/...
Feature đang sửa đã có folder spec sẵn
User nói rõ phải cập nhật spec song song
Team đang review/trace theo requirements/design/api-contract/testcase/tasks

Khi nào KHÔNG bắt buộc thêm Spec:

Repo/service chỉ quản lý change bằng OpenSpec
Đây là thay đổi nhỏ không có feature spec tương ứng để bám
Tạo spec mới sẽ chỉ lặp lại OpenSpec mà không tạo thêm giá trị review/trace

Nếu có Spec thì dùng bộ file chuẩn theo stack:

BE/API: requirements.md, design-be.md, api-contract.md, tasks-be.md, testcase.md
FE/UI: requirements.md, design-fe.md, tasks-fe.md, testcase.md
FS: có thể tách design-be.md + design-fe.md, tasks-be.md + tasks-fe.md

requirements.md — WHY + WHAT

## Bối cảnh / Mục tiêu
[Vấn đề / cơ hội business]

## Yêu cầu
### Requirement: <Tên>
- WHEN <điều kiện>
- THEN <kết quả>
- AND <bổ sung>

## Acceptance Criteria
- [ ] AC-01 ...
- [ ] AC-02 ...

design-be.md / design-fe.md — HOW

## Context
[Trạng thái hiện tại]

## Goals / Non-Goals

## Technical Decisions
### Decision: <Quyết định>
[Lý do]

## Data Flow / Component Tree
[Diagram ASCII]

api-contract.md — API / contract chi tiết (nếu có API)

## Endpoints / Contract
- Method + path
- Request
- Response
- Error codes

testcase.md — Test scenarios

## Test Cases
- TC-01: Happy path
- TC-02: Validation error
- TC-03: Permission / security

tasks-be.md / tasks-fe.md — Checklist mức implementation

layer-by-layer implementation tasks
test coverage tasks
docs/curl/usage tasks

1C. Sync rules — chỉ áp dụng khi có cả OpenSpec + Spec

Khi feature có đủ cả hai lớp tài liệu:

Scenario trong OpenSpec spec.md phải khớp với requirement/scenario trong requirements.md
OpenSpec design.md và spec design-*.md phải cùng technical direction
OpenSpec tasks.md giữ milestone/change-level; spec tasks-be.md / tasks-fe.md giữ implementation detail
testcase.md phải trace lại được các scenario đã viết trong OpenSpec/spec
Không được update một bên mà quên bên còn lại

1D. Phase 1 checklist — bắt buộc tự check trước approval gate

Scope & placement

Đã detect đúng stack (BE / FE / FS) và hỏi lại user nếu còn mơ hồ
Đã xác định đúng service/repo/module đích trước khi tạo tài liệu
OpenSpec/spec được đặt đúng service, không đặt nhầm root hoặc service khác

OpenSpec completeness

proposal.md nêu rõ WHY, phạm vi thay đổi, impact chính
specs/<capability>/spec.md có đủ happy path + edge/error scenarios theo format WHEN/THEN
design.md có context, goals/non-goals, technical decisions, data flow/component tree
tasks.md có milestone chính, verification steps, và mapping theo capability/scenario

Spec decision

Đã chốt rõ vì sao feature này cần hoặc không cần maintain spec song song

Spec completeness (nếu áp dụng)

requirements.md khớp OpenSpec scenarios và có acceptance criteria
design-be.md / design-fe.md phản ánh đúng technical direction đã chọn
api-contract.md mô tả đủ request/response/error semantics nếu có API
testcase.md trace được requirements/scenarios
tasks-be.md / tasks-fe.md phản ánh implementation detail theo stack

Traceability & readiness

Mỗi scenario (và AC nếu có requirements.md) đã có hướng test tương ứng để sang Phase 2
Dependencies, assumptions, non-goals, và open questions đã được ghi rõ
Nếu là BE/API và cần Postman artifact ở Phase 4, đã chốt review scope / naming strategy từ Phase 1
Nếu có cả OpenSpec + Spec, scenario/design/tasks/testcase đã sync hai chiều

⛔ PHASE 1 GATE — Approval trước khi tiếp tục

Sau 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>

**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/design-fe: [quyết định chính]
- API contract / UI contract: [điểm chính]
- 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:

User yêu cầu chỉnh → cập nhật docs → trình bày lại tóm tắt
Lặp lại đến khi user nói "OK" / "approve" / "bắt đầu" / "đúng rồi"
Chỉ chuyển Phase 2 sau khi có approval rõ ràng từ user

PHASE 2 — Test Design (TDD) — KHÁC THEO STACK

─── BE Profile: Spring Boot ───

Test từ Scenarios → JUnit 5 + MockMvc

// Unit test — Service layer
@ExtendWith(MockitoExtension.class)
class <Feature>ServiceTest {
    @Mock private <Dep>Repository repo;
    @InjectMocks private <Feature>ServiceImpl service;

    @Test
    void <method>_<condition>_<expected>() {
        given(repo.findBy...).willReturn(...);
        var result = service.method(input);
        assertThat(result).isNotNull();
    }
}

// Integration test — Controller layer
class <Feature>ApiTest extends IntegrationTestBase {
    @Test
    @WithMockCustomUser
    void <endpoint>_<scenario>_<expected>() throws Exception {
        mockMvc.perform(get("/api/...")
                .param("key", "value"))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.data").isArray());
    }
}

Chạy: ./mvnw test → phải FAIL (RED) ✓

─── FE Profile: React / Vue ───

Test từ Scenarios → ưu tiên test runner đang có trong repo (Jest / Vitest) + React Testing Library / framework tương đương

// Unit test — Hook / utility
describe('<featureName>', () => {
  it('<condition> should <expected>', () => {
    const { result } = renderHook(() => useFeature());
    expect(result.current.data).toBeDefined();
  });
});

// Component test — RTL
describe('<ComponentName>', () => {
  it('renders correctly when <condition>', () => {
    render(<Component prop={value} />);
    expect(screen.getByText('...')).toBeInTheDocument();
  });

  it('calls handler when user <action>', async () => {
    const onAction = jest.fn();
    render(<Component onAction={onAction} />);
    await userEvent.click(screen.getByRole('button', { name: '...' }));
    expect(onAction).toHaveBeenCalledWith(expect.objectContaining({...}));
  });
});

// E2E — Playwright (critical flows)
test('<scenario>', async ({ page }) => {
  await page.goto('/booking');
  await page.click('[data-testid="select-date"]');
  await expect(page.locator('.calendar')).toBeVisible();
});

Chạy: test command hiện có của repo (npm test, yarn test, pnpm test, vitest, ...) → phải FAIL (RED) ✓

PHASE 3 — Implement — KHÁC THEO STACK

─── BE Profile: Spring Boot ───

Thứ tự implement:

Entity → Repository → Migration SQL → DTO → Mapper → Service → Controller

Conventions bắt buộc:

Layer	Convention
Entity	`*Entity`, ULID via `@UlidSequence`
DTO	`RequestDTO` / `ResponseDTO`, Jakarta Validation
Mapper	`*Mapper` interface, MapStruct `@Mapper`
Service	Interface `Service` + impl `ServiceImpl`
Controller	`@RestController`, `@Operation`, `@AuditAction`
DB	Dated SQL → register `db.changelog-master.xml`

Implementation task template BE:

Nếu feature có spec song song → dùng tasks-be.md
Nếu không có spec tương ứng → chi tiết implementation có thể nằm trong openspec/.../tasks.md

## 1. Data Layer
- [ ] 1.1 Entity (nếu cần)
- [ ] 1.2 Repository + query method
- [ ] 1.3 DB migration SQL

## 2. Business Layer
- [ ] 2.1 RequestDTO / ResponseDTO + validation
- [ ] 2.2 Mapper (MapStruct)
- [ ] 2.3 Service interface method
- [ ] 2.4 ServiceImpl

## 3. API Layer
- [ ] 3.1 Controller endpoint + Swagger @Operation
- [ ] 3.2 Swagger checklist đã cover đủ `@Tag` / `@RequestMapping` trên `*Operation` interface
- [ ] 3.3 Mỗi endpoint có `@Operation(summary, description)`; thêm `operationId` nếu API quan trọng hoặc public-facing
- [ ] 3.4 Response codes đã document đủ `200`, `400`, `404`, `409`, `401/403`, `500` theo đúng behavior thực tế
- [ ] 3.5 Happy-path response có `schema` hoặc `examples`; file download/export dùng `type=string`, `format=binary`
- [ ] 3.6 Các example JSON dài được tách thành hằng `String ..._EXAMPLE` ở đầu `*Operation` interface để tái sử dụng
- [ ] 3.7 `@RequestParam` / `@PathVariable` / `Pageable` / filter params được annotate bằng `@Parameter`, có `description`, `required`, `example`, `allowableValues` khi phù hợp
- [ ] 3.8 Query/filter object và `Pageable` dùng `@ParameterObject`; mô tả rõ default paging/sort nếu có
- [ ] 3.9 Request body JSON dùng Swagger/OpenAPI `@io.swagger.v3.oas.annotations.parameters.RequestBody` với `description`, `schema`, `examples`
- [ ] 3.10 Khi mô tả request body hoặc response body trong Swagger/OpenAPI, `description` phải nêu rõ tên DTO tương ứng để người đọc refer nhanh trên Swagger UI (ví dụ `CreateExchangeRateRequestDTO`, `ExchangeRateResponseDTO`)
- [ ] 3.11 Multipart request mô tả rõ từng part (`data`, `file`) và semantics của từng part
- [ ] 3.12 Workflow/action endpoint mô tả rõ state transition, business preconditions và các conflict/error quan trọng
- [ ] 3.13 Response `Void` vẫn có `200` description rõ ràng; nếu cần có thể thêm example rỗng để FE/QA dễ đối chiếu
- [ ] 3.14 Error docs bám đúng business code/message thực tế của service, không mô tả chung chung
- [ ] 3.15 Style Swagger nhất quán trong cùng service, tham chiếu pattern `ExchangeRateOperation` và `RatingScoreRuleOperation`
- [ ] 3.16 Không bắt buộc generate `openapi.json` hoặc `openapi.yaml`; chỉ generate khi repo/service có convention hoặc downstream automation yêu cầu artifact này
- [ ] 3.17 Security config nếu cần

## 4. Tests
- [ ] 4.1 Unit test Service
- [ ] 4.2 Integration test Controller
- [ ] 4.3 Cover tất cả scenarios từ OpenSpec
- [ ] 4.4 Nếu có spec: cover thêm testcase/AC trong spec

## 5. Verify
- [ ] 5.1 ./mvnw clean package -DskipTests
- [ ] 5.2 ./mvnw test
- [ ] 5.3 Đảm bảo Swagger/OpenAPI annotations và `api-contract.md` phản ánh đúng behavior hiện tại để Phase 4 generate/update Postman collection; chỉ cần `openapi.json` / `openapi.yaml` nếu repo/service có convention hoặc downstream automation yêu cầu
- [ ] 5.4 Curl examples ở Phase 5

─── FE Profile: React / Vue ───

Thứ tự implement:

Types/Interfaces → API Service → Custom Hook → Component → Page integration

Conventions:

Ưu tiên follow structure và tooling đang có sẵn trong repo hiện tại, không ép một layout/framework convention nếu codebase đang theo pattern khác.

Layer	Convention
Types	`types/<feature>.ts` hoặc vị trí tương đương trong repo — interfaces, enums
API	`services/<feature>Api.ts` hoặc module API tương đương — axios/fetch calls
Hook	`hooks/use<Feature>.ts` hoặc composable/module state tương đương
Component	`components/<Feature>/index.tsx` hoặc feature component tương đương — UI only
Page/Route	`pages/<Page>.tsx`, `app/...`, route module hoặc screen hiện có của repo
Style	Follow styling system hiện tại của repo (CSS modules, Tailwind, SCSS, design system), không trộn style mới nếu không cần

Implementation task template FE:

Nếu feature có spec song song → dùng tasks-fe.md
Nếu không có spec tương ứng → chi tiết implementation có thể nằm trong openspec/.../tasks.md

## 1. Foundation
- [ ] 1.1 Types / interfaces
- [ ] 1.2 API service function (gọi BE endpoint)

## 2. Business Logic
- [ ] 2.1 Custom hook (state, loading, error)
- [ ] 2.2 Data transformation / helpers

## 3. UI
- [ ] 3.1 Component markup + props
- [ ] 3.2 Styling
- [ ] 3.3 Error / loading states
- [ ] 3.4 Accessibility (aria labels, keyboard nav)

## 4. Integration
- [ ] 4.1 Tích hợp vào page/route/screen hiện có của repo
- [ ] 4.2 Routing nếu cần, follow router đang dùng trong project

## 5. Tests
- [ ] 5.1 Unit test hook/state logic
- [ ] 5.2 Component test (RTL hoặc framework tương đương theo repo)
- [ ] 5.3 E2E nếu là critical flow
- [ ] 5.4 Cover tất cả scenarios từ OpenSpec
- [ ] 5.5 Nếu có spec: cover thêm testcase/AC trong spec

## 6. Verify
- [ ] 6.1 Chạy test command hiện có của repo (`npm test`, `yarn test`, `pnpm test`, `vitest`, ...)
- [ ] 6.2 Chạy build command hiện có của repo (no errors)
- [ ] 6.3 Visual check trên browser

PHASE 4 — Review & Verify — KHÁC AGENT

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 consistency check (nếu feature có spec):

Scenarios / requirements trong spec có khớp OpenSpec không
api-contract.md / design-*.md / testcase.md có phản ánh thay đổi cuối cùng không
tasks-be.md / tasks-fe.md đã được check hết và không lệch openspec/.../tasks.md

Backend API verification artifact (BE/API khi phù hợp):

Bắt buộc khi có endpoint mới hoặc có thay đổi runtime-observable với API consumer như path, method, request/response shape, auth behavior, validation behavior, status/error semantics, executable examples
Có thể bỏ qua nếu thay đổi thuần internal hoặc chỉ chỉnh wording tài liệu mà không làm đổi API surface/behavior đã expose
Generate hoặc update Postman collection ngay ở Phase 4 sau khi build/test pass và trước khi sang Phase 5
Agent chính trong session hiện tại chịu trách nhiệm generate/update collection, nêu rõ artifact/path hoặc nguồn export, và báo kết quả smoke checks trước review gate
Dùng collection này để chạy smoke/integration checks thủ công hoặc qua runner trước khi chốt review gate
Nếu có environment/variable cần thiết thì sync cùng collection để người test có thể dùng ngay
api-contract.md / OpenAPI / Swagger docs phải khớp với collection vừa generate

Collection / environment storage rule (BE/API):

Nếu repo/service đã có convention Postman riêng thì follow convention đó
Nếu feature có spec tương ứng và chưa có convention riêng, mặc định lưu collection tại postman/collections/<spec-name>.postman_collection.json
Nếu service không maintain spec tương ứng nhưng vẫn cần Postman artifact, Phase 1 tasks/review summary phải chốt và ghi rõ <feature-review-scope> trước khi sang Phase 4; khi đó dùng tên như postman/collections/<feature-review-scope>.postman_collection.json và không dùng OpenSpec change name làm default
review scope nên bám theo consumer-facing API boundary ổn định như service module, bounded context, hoặc endpoint prefix; không đặt theo layer kỹ thuật nội bộ
<feature-review-scope> là tên scope gốc khi không có spec; <scope> chỉ là hậu tố sub-scope dùng khi tách collection từ một spec đã có
Collection được organize theo spec/feature review scope, không theo OpenSpec change name
<spec-name>, <feature-review-scope>, và <scope> phải được normalize về lowercase kebab-case ASCII; dấu phân tách -- chỉ dùng để nối <spec-name> với <scope>
Nếu repo là mono-repo hoặc có nhiều service dễ trùng tên collection, mặc định qualify theo service boundary như postman/collections/<service>--<spec-name>.postman_collection.json, postman/collections/<service>--<spec-name>--<scope>.postman_collection.json, hoặc với non-spec case là postman/collections/<service>--<feature-review-scope>.postman_collection.json, trừ khi repo đã có convention khác
Nếu một spec có nhiều capability nhưng vẫn cùng một API surface review scope, ưu tiên gộp vào collection theo <spec-name>
Nếu một spec bao phủ nhiều API review scope độc lập, có thể tách collection theo postman/collections/<spec-name>--<scope>.postman_collection.json ngay cả khi repo chưa có convention sẵn; các <scope> này phải được nêu rõ trong Phase 1 tasks/review summary
Environment file, nếu cần, được quản lý theo runtime environment chứ không theo spec
Nếu repo là mono-repo hoặc có nhiều service dễ trùng tên env, mặc định qualify theo service boundary: postman/environments/<service>-<runtime-env>.postman_environment.json; nếu repo đã có convention env dùng chung thì follow convention đó
Luôn reuse environment file theo runtime environment trong cùng service boundary hiện có trước; chỉ tạo environment file mới khi xuất hiện runtime environment mới hoặc boundary chạy tách biệt rõ ràng không thể dùng chung env hiện có
Không tạo environment file mới cho từng spec/feature chỉ vì thêm endpoint hay đổi contract
Environment file được commit chỉ với placeholder/sanitized values; không commit token, password, secret, hoặc credential thực tế
Nếu chỉ test local đơn giản và không cần share biến runtime thì có thể không cần environment file riêng; khi đó collection và mọi file export liên quan vẫn không được hardcode secret nhạy cảm

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:

Mặc định: thử reviewer chuyên biệt theo stack trước; nếu không có sẵn trong environment hiện tại thì luôn dùng code-reviewer
Báo cáo ở review gate phải nêu rõ reviewer nào đã được dùng cho mỗi scope
Với Java/Spring/Spring Boot, prompt review nên nêu rõ layer đang sửa (controller/service/repository/security/config) để reviewer bám đúng context
Prompt phải nêu rõ stack, framework và rule/context quan trọng của repo để reviewer bám đúng chuẩn

Security Review (chung — focus khác):

security-reviewer

BE focus: SQL injection, missing @PreAuthorize, exposed fields
FE focus: XSS, exposed API keys, insecure localStorage

⛔ PHASE 4 GATE — Approval trước khi viết Docs

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
**Spec Consistency:** ✅ PASS / ❌ lệch spec (chỉ áp dụng nếu feature có spec)
**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`

**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:

User yêu cầu chỉnh → fix code → chạy lại build/test/review → báo cáo lại
Lặp lại đến khi user nói "OK" / "approve" / "viết docs" / "đúng rồi"
Chỉ chuyển Phase 5 sau khi có approval rõ ràng từ user

PHASE 5 — Documentation — KHÁC THEO STACK

BE: curl examples

# Happy path
curl -X GET "http://localhost:8080/api/..." \
  -H "Authorization: Bearer <token>"
# Response: HTTP 200 { "success": true, "data": [...] }

# Error case
curl -X GET "http://localhost:8080/api/...?invalidParam=99" \
  -H "Authorization: Bearer <token>"
# Response: HTTP 400 { "success": false, "message": "..." }

FE: Component usage docs

// Props interface
interface <Feature>Props {
  onAction: (value: string) => void;
  data: string[];
  disabled?: boolean;
}

// Usage example
<FeatureComponent
  data={items}
  onAction={(val) => handleAction(val)}
/>

⛔ PHASE 5 GATE — Approval trước khi Archive & Close

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 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

---
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.

PHASE 6 — Archive & Close ✅ CHUNG

openspec archive "<change-name>"
bd close <bd-id>
bd ready --json --limit 5   # xem việc tiếp theo

Trước khi archive/close:

OpenSpec đã validate và archive được
Nếu feature có spec: spec files đã được cập nhật xong, không còn TODO/checklist mở
Không đóng beads khi OpenSpec hoặc spec còn lệch code

Fast Track (task nhỏ < nửa ngày)

bd create "..." -t task -p 2          # capture
/opsx:ff <change-name>                 # fast-forward design
# implement + test
# BE: chạy test/build command hiện có của repo
# FE: chạy test/build command hiện có của repo
/opsx:verify <change-name>             # vẫn bắt buộc trước archive
# BE: sinh curl examples tối thiểu nếu có API
# FE: sinh usage snippet tối thiểu nếu có UI/component mới
openspec archive <name> && bd close <id>

Fast track rules:

Vẫn phải có OpenSpec
Chỉ streamline quy trình; không được bỏ qua quality gates chính như build/test pass, /opsx:verify, review phù hợp, và docs tối thiểu theo stack
Chỉ bỏ qua spec nếu feature không có spec tương ứng và user không yêu cầu
Nếu feature đã có spec sẵn thì fast track vẫn phải sync spec tối thiểu trước khi close
Nếu là BE/API và có endpoint mới hoặc đổi API surface/behavior đã expose thì fast track vẫn phải generate/update Postman collection ở Phase 4-equivalent và chạy smoke checks trước khi archive/close

Tóm tắt so sánh BE vs FE

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

Checklist Done (chung cho mọi stack)

[ ] 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 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
[ ] tasks.md đã hoàn tất
[ ] Nếu có spec: tasks-be.md / tasks-fe.md cũng đã hoàn tất
[ ] Change đã archive
[ ] Beads issue đã close

sdlc-workflow

SDLC Workflow

BƯỚC ĐẦU TIÊN: Detect Stack