Khởi động và điều hành toàn bộ quy trình phân tích nghiệp vụ từ ý tưởng đến tài liệu bàn giao.

ba-start

Là skill trung tâm của Bakit. Nhận yêu cầu thô từ người dùng và dẫn dắt toàn bộ quy trình phân tích nghiệp vụ: từ lúc tiếp nhận yêu cầu đến khi đóng gói tài liệu để bàn giao. Từ v2.1.0, ba-start cũng là router tự do — bạn mô tả việc cần làm bằng tiếng Việt, nó tự chọn đúng bước để chạy (thay cho ba-do đã xoá).

Cách gọi

Runtime	Lệnh
Claude Code	`/ba-start`
Codex	`$ba-start`
Antigravity	"Đọc skills/ba-start/SKILL.md và chạy intake"

ba-start có thể chạy toàn bộ quy trình hoặc từng bước riêng lẻ:

# Chạy toàn bộ
/ba-start intake requirements.pdf

# Nói bằng tiếng Việt tự nhiên (router)
/ba-start Tôi có file yêu cầu mới, hãy tạo dự án BA

# Chạy từng bước
/ba-start intake --slug ten-du-an
/ba-start backbone --slug ten-du-an
/ba-start stories --slug ten-du-an --module thanh-toan
/ba-start srs --slug ten-du-an --module thanh-toan
/ba-start package --slug ten-du-an

Pipeline SRS mới (từ v2.1.0)

Trước v2.1.0, srs là một lệnh monolithic tạo mọi thứ một lần. Giờ srs chỉ sinh spec, và các phần còn lại là những bước rời rạc chạy lần lượt — mỗi bước kết thúc bằng hướng dẫn bước tiếp theo cụ thể:

stories → srs → use-case → userflow → wireframe → render-html
        → test-checklist → test-cases → …

Từng bước chi tiết

ba-start có 21 command chính, cộng thêm reverse (as-built lane) và wireframes ở chế độ tương thích deprecated cho dự án cũ.

intake — Chuẩn hóa yêu cầu

Nhận input thô (file PDF, DOCX, text, hoặc ghi chú) và chuẩn hóa thành tài liệu có cấu trúc. Agent sẽ đọc, phát hiện gap, và hỏi bạn những gì còn thiếu.

/ba-start intake /path/to/requirements.pdf

Kết quả: 01_intake/intake.md — yêu cầu đã chuẩn hóa, stakeholder, business goal, scope, out of scope, mode (hybrid/lite/formal).

Cần check: stakeholder đúng chưa? Business goal rõ chưa? Scope/out of scope đủ chưa?

options — So sánh hướng giải pháp

Khi intake cho thấy nhiều hướng giải pháp khả dĩ, bước này so sánh ưu nhược điểm từng hướng trước khi chốt.

/ba-start options --slug <slug>                    # Tạo option pack
/ba-start options --slug <slug> --select option-02 # Chọn luôn hướng
/ba-start options --slug <slug> --skip             # Bỏ qua nếu chỉ 1 hướng rõ

Kết quả: 01_intake/options/ — option pack với comparison matrix.

Khi nào dùng: intake có ≥2 hướng giải pháp hợp lệ. Nếu chỉ 1 hướng rõ, --skip.

backbone — Khóa source of truth

Khóa các quyết định nền tảng cho toàn dự án. Đây là "hiến pháp" — mọi artifact sau phải tuân theo.

/ba-start backbone --slug <slug>

Output trong 02_backbone/:

backbone.md — business goals, actors, feature map, module split, assumptions, constraints, portal matrix (nếu có UI), shared shell/menu
common-rules.md — rule dùng chung (CR-*)
message-list.md — message dùng chung (MSG-*)
shared-shell-contract.md — shared shell contract (nếu có UI)
backbone-index.md — navigator cho agent

Gate: nếu có UI, backbone dừng ở Gate 5.1a để bạn chọn UI library (Shadcn, Ant Design, ...) trước khi tạo control-type-library.

frd — Đặc tả yêu cầu chức năng

Tài liệu dành cho stakeholder business đọc — ngôn ngữ nghiệp vụ, không có kỹ thuật.

/ba-start frd --slug <slug> --module <module_slug>

Kết quả: 03_modules/{module}/frd.md

Khi nào dùng: stakeholder/manager/client cần review yêu cầu trước khi viết SRS kỹ thuật. Có thể chạy trước stories và SRS.

stories — User story & acceptance criteria

Viết user story và tiêu chí chấp nhận cho từng module.

/ba-start stories --slug <slug> --module <module_slug>

Kết quả: 03_modules/{module}/userstories/*.md

Mỗi story phải có: actor rõ, acceptance criteria test được, priority rõ, trace về business goal.

srs — Đặc tả kỹ thuật (spec-only từ v2.1.0)

Bước quan trọng nhất. Từ v2.1.0, srs chỉ sinh spec — use case, wireframe, HTML là các bước riêng chạy sau.

/ba-start srs --slug <slug> --module <module_slug>

Kết quả:

03_modules/{module}/
├── srs/spec.md               # SRS spec — FR, NFR, BR, Error Matrix, flows, screens
├── srs/flows.md              # Optional: sequence diagrams
├── srs/states.md             # Optional: state transitions
├── srs/erd.md                # Optional: ERD canon
└── srs.md                    # Compiled SRS (spec-scope)

Quy tắc sửa: sửa source set (srs/) trước, compile lại srs.md sau. Không sửa thẳng srs.md.

use-case — Use case canon (mới từ v2.1.0)

Sinh use case canon từ spec. Chạy sau srs, trước userflow.

/ba-start use-case --slug <slug> --module <module_slug>

Kết quả: usecases/index.md + uc-*.md + diagrams.md — từng luồng nghiệp vụ, link về user stories và screens, actor actions dùng đúng terminology của stories/FRD.

Gate: Behavior review phải approved trước khi đi tiếp.

userflow — Keystone flow-split (mới từ v2.1.0)

Sinh srs/userflow.md — artifact keystone mà mọi renderer downstream đọc: screen list, flow split, transitions, primary_device (mobile 375 / tablet 768 / desktop 1024).

/ba-start userflow --slug <slug> --module <module_slug>

Kết quả: srs/userflow.md — mermaid flowchart, bảng screens, bảng flow-split, bảng transitions.

HARD STOP: bạn phải duyệt userflow trước khi chạy wireframe hoặc render-html — hai bước này từ chối chạy khi userflow chưa stage: flow-approved.

wireframe — ASCII wireframe per-flow (mới từ v2.1.0)

Sinh ASCII wireframe canon theo flow (thay cho per-screen ascii-screen/ cũ): 1 file/flow, bảng 5 cột, Description 6 lớp.

/ba-start wireframe --slug <slug> --module <module_slug>

Kết quả: ascii-wireframe/index.md + 1 file per flow.

Yêu cầu: userflow đã approved + DESIGN.md + shared-shell-contract.md. Portal/nav IDs chỉ được reference từ backbone, không định nghĩa lại.

Dự án cũ có ascii-screen/: chạy ba-kit run-script migrate-ascii-per-flow.py per module để migrate.

render-html — HTML từ canon (mới từ v2.1.0)

Render HTML functional flow từ canon đã duyệt — deterministic, chỉ đọc canon, không sửa canon.

/ba-start render-html --slug <slug> --module <module_slug>

Kết quả: schema-v3 manifest, index, 1 uc-*.html per UC, validation report, receipt.

Khi nào dùng: muốn xem/bàn giao bản HTML của UI canon. Chạy lại bất cứ lúc nào canon đổi — không ảnh hưởng package eligibility.

test-checklist — Scenario outline (mới từ v2.1.0)

Sinh checklist kiểm thử: mỗi dòng 1 case theo grammar CHK-{module}-NNN, kèm coverage gate trả lời câu hỏi "đủ chưa?".

/ba-start test-checklist --slug <slug> --module <module_slug>

Kết quả: test/checklist/{module}-checklist-index.md + checklist-{scope}.md + data.js + preview.html.

Coverage gate: mọi obligation (FR/BR/NFR/E) phải có trạng thái covered | excluded-approved | blocked | tbd | partial.

test-cases — Test cases chạy được (mới từ v2.1.0)

Expansion 1:1 nghiêm ngặt từ checklist mới nhất — mỗi checklist item thành đúng 1 test case, không tách/gộp/thêm.

/ba-start test-cases --slug <slug> --module <module_slug>

Kết quả: test cases với schema 10 fields (STT, Category, Checklist, Ref, Priority, Title, Steps, ...) + HTML viewer.

Yêu cầu: phải có test-checklist trước — không có checklist thì từ chối.

bpmn — BPMN 2.0 diagrams (mới từ v2.1.0)

Sinh BPMN 2.0 (OMG) qua kiến trúc 2 lớp: producer chỉ viết business intent (IR + src JSON), controller engine làm semcheck, layout, XML, editor rebuild. Producer không bao giờ viết XML hay tọa độ.

/ba-start bpmn --slug <slug> --module <module_slug>

Kết quả: {process}.ir.json + {process}.src.json + BPMN XML + editor HTML.

Yêu cầu: node trên PATH (Node.js ≥18). Thiếu node → command từ chối nhẹ nhàng, không crash.

prototype — Clickable prototype hi-fi (mới từ v2.1.0)

Sinh self-contained hi-fi clickable prototype per module — HTML đơn file, click được, có states thật.

/ba-start prototype --slug <slug> --module <module_slug>

Kết quả: prototype.html — mọi screen từ userflow, state-driven render, loading states, empty states, demo triggers.

Yêu cầu: ascii canon + userflow approved + DESIGN.md (thiếu thì dùng palette trung tính + cảnh báo).

preview — Whole-module viewer (mới từ v2.1.0)

HTML viewer toàn module cho quá trình đang làm việc — regenerate on demand, deterministic, không review gate. Giống như status nhưng có hình.

/ba-start preview --slug <slug> --module <module_slug>

Kết quả: 1 file HTML với 9 sections cố định: overview → intro → SRS spec → ERD → states → userflow → functions → screens catalog → wireframes + open questions.

Lưu ý: preview là derived artifact — không phải source of truth, sửa gì thì sửa canon rồi regenerate.

wireframes — Kiểm tra tương thích deprecated

Kiểm tra tương thích cho dự án cũ từng gọi command wireframes riêng.

/ba-start wireframes --slug <slug> --module <module_slug>

Kết quả: không tạo file. Command chỉ kiểm tra mọi screen canon có ASCII wireframe và state bắt buộc.

Lưu ý: trong flow hiện tại, dùng wireframe (singular) để sinh per-flow ASCII canon.

package-frd — Đóng gói FRD sớm (từ v1.4.0)

Đóng gói FRD thành HTML trước khi có stories/SRS. Dùng khi stakeholder cần xem FRD sớm trong lifecycle.

/ba-start package-frd --slug <slug>

Kết quả: 04_compiled/compiled-frd.html

Khác với package: package-frd chỉ aggregate FRD từ tất cả module — không cần SRS hoặc stories tồn tại. package đòi hỏi SRS đã compile.

package — Đóng gói bàn giao

Đóng gói toàn bộ tài liệu thành file HTML, sẵn sàng gửi stakeholder.

/ba-start package --slug <slug>

Kết quả:

04_compiled/compiled-frd.html — FRD tổng hợp
04_compiled/compiled-srs.html — SRS tổng hợp

Mở bằng browser, không cần tool gì đặc biệt.

status — Xem trạng thái dự án

/ba-start status --slug <slug>

Hiển thị: artifact nào đã có, artifact nào còn thiếu, module nào đang ở bước nào, delegation tracker nào bị stall.

next — Đề xuất bước tiếp theo

/ba-start next --slug <slug>

Giống GPS — nó đọc toàn bộ artifact hiện có và đề xuất chính xác command tiếp theo. Đừng đoán, cứ làm theo next.

impact — Phân tích tác động thay đổi

Khi stakeholder đổi requirement, chạy impact trước khi sửa bất cứ gì. Impact sinh change plan (impacts/CR-{id}-plan.md) với closure set — tập đầy đủ artifact phải cập nhật cùng nhau.

/ba-start impact --slug <slug> "Export CSV phải có audit log"

Kết quả: change plan với closure set tính deterministic từ artifact-dependency graph. Impact chỉ phân tích và lập plan — không sửa canon.

impact-cook — Thực thi change plan (mới từ v2.1.0)

Thực thi change plan đã duyệt do impact sinh ra. Artifact governed đi qua lifecycle command của nó (giữ review gates); artifact derived được ghi trực tiếp.

/ba-start impact-cook --slug <slug> [--cr <change_id>] [--auto]

Yêu cầu: phải có change plan trước — không có plan thì từ chối và route về impact.

L1/L2 change notification: mặc định BẬT trước mỗi lần ghi file; chỉ tắt được bằng --auto.

reverse — Extract ngược từ hệ thống có sẵn

Dùng khi dự án đã có code/hệ thống đang chạy. Ghi nhận evidence, không tự suy diễn thành requirement.

/ba-start reverse --slug <slug>

Kết quả: evidence dưới 00_reverse/, gồm baseline lock, reverse index và read manifest. Sau đó promote evidence đã duyệt vào lifecycle; reverse artifacts không phải source of truth.

Kết quả tạo ra

plans/{ten-du-an}-{ngay}/
├── 01_intake/intake.md          # Yêu cầu đã chuẩn hóa
├── 02_backbone/                 # Quyết định nền tảng
│   ├── backbone.md
│   ├── backbone-index.md
│   ├── common-rules.md
│   ├── message-list.md
│   └── shared-shell-contract.md
├── 03_modules/{module}/         # Tài liệu từng module
│   ├── frd.md
│   ├── userstories/
│   ├── usecases/                # Use case canon (bước use-case)
│   ├── ascii-wireframe/         # Per-flow ASCII wireframe canon (bước wireframe)
│   ├── srs/                     # SRS slices + userflow.md
│   ├── srs.md                   # Compiled SRS
│   ├── srs-compile-receipt.json
│   ├── screen-field-contract.yaml
│   ├── test/                    # Checklist + test cases (bước test-*)
│   ├── bpmn/                    # BPMN IR/src/XML (bước bpmn)
│   ├── prototype.html           # Clickable prototype (bước prototype)
│   └── preview.html             # Whole-module viewer (bước preview)
└── 04_compiled/                 # Tài liệu đã đóng gói
    ├── compiled-frd.html
    └── compiled-srs.html

ba-start — Bắt đầu dự án BA