bsa-framework

BSA Framework v2

BSA điều phối AI phát triển sản phẩm theo sprint:

brainstorm → product/spec → arch → design → plan → implement → test → review
                                                                        ↓
                 living truth ← seal ← reconcile tài liệu với code đã kiểm chứng

Claude/Codex thực hiện công việc. CLI quản lý trạng thái, kiểm tra đầu ra, chạy test, lưu bằng chứng và xuất bản living truth. Tạo template hoặc in prompt không đồng nghĩa phase hoàn thành. BMAD, Spec-Kit và AgentKit là năng lực tùy chọn mà agent có thể sử dụng; chúng không còn là điều kiện bắt buộc để chạy framework.

Cài đặt từ package

bsa-framework@2.1.0 đã được phát hành trên npm registry:

pnpm dlx bsa-framework@2.1.0 init ./project-meta

Launcher cần Node.js 20+, pnpm và Python 3.10+ trên macOS/Linux. Mỗi dự án có runtime và skills riêng; không cần cài BSA global. Phiên bản được ghi trong .bsa/config.json. init giữ nguyên dự án đã setup, không tự nâng cấp. Sau setup, mở thư mục dự án trong Claude/Codex và giao việc bằng hội thoại.

Package chỉ chứa thành phần BSA cần để setup; không chứa vendor submodules hay dữ liệu sprint của repository phát triển. Package hiện dùng UNLICENSED: phát hành công khai không đồng nghĩa cấp giấy phép nguồn mở. Quy trình phát hành nằm trong docs/framework/releasing.md ở repository nguồn.

Bắt đầu

Yêu cầu: Python 3.10+, macOS hoặc Linux. Không cần package Python bên ngoài, jq hay cài đặt Node.js để chạy BSA. Dự án Node.js dùng pnpm.

Bạn chỉ cần chạy setup một lần:

bash setup.sh

Setup mặc định tạo thư mục project-meta/. Có thể truyền đích khác bằng bash setup.sh /path/to/project-meta.

Mở thư mục project-meta trong Claude/Codex. Từ đây, chỉ nhắn cho agent:

start sprint 1

Agent đọc AGENTS.md / CLAUDE.md, xác định sprint, tự gọi CLI và thực hiện công việc. Nếu mục tiêu đã có trong hội thoại hoặc kế hoạch sprint, agent dùng lại; nếu chưa có, agent chỉ hỏi sprint cần đạt điều gì. Bạn cũng có thể ghi ngay:

start sprint 1: xây ứng dụng quản lý công việc cá nhân

Bạn nhắn	Agent tự thực hiện
start sprint 1	Mở/resume S001, làm từ bước còn thiếu đến sẵn sàng đóng
continue sprint 1	Tiếp tục tiến độ đã lưu, không reset
product sprint 1 hoặc spec sprint 1	Làm product requirement và spec
arch, design, plan, implement, test, review	Hoàn thành phase được yêu cầu và prerequisite cần thiết
feedback sprint 1: thêm đăng nhập Google	Ghi feedback, áp dụng thay đổi và kiểm chứng lại
status sprint 1	Báo tiến độ và blocker
evidence	Đọc bundle bằng chứng: hành vi đã kiểm chứng, gap còn mở, ràng buộc bảo toàn, regression
seal sprint 1	Hoàn tất gate còn thiếu trong phạm vi đã định, kiểm tra diff rồi xuất bản truth
start sprint 2 ... và tự đóng khi xong	Chạy xuyên suốt đến seal
auto / chạy tự động	Chạy vòng ngoài không giám sát và báo lý do dừng

start mặc định dừng khi sẵn sàng đóng; nhắn seal để đóng. chỉ brainstorm, dừng sau plan, chỉ ghi feedback, chỉ xem trước seal giới hạn công việc tương ứng. Có thể dùng tiếng Việt như bắt đầu sprint 1, tiếp tục sprint 1, đóng sprint 1.

Không cần tự chạy start, configure, test hay seal trong terminal. Agent hiện tại thực hiện chúng bằng công cụ của mình, tự tạo báo cáo và xử lý các gate. Không cần cấu hình runner hoặc đăng nhập một AI CLI khác khi dùng trực tiếp trong hội thoại. Đây là quy ước cho agent đọc hướng dẫn dự án, không phải trình phân tích câu lệnh shell.

Project đã được copy runtime và workflow nên không phụ thuộc vị trí repository framework ban đầu. AGENTS.md và CLAUDE.md có sẵn được giữ lại, hướng dẫn BSA được nối thêm. Quy tắc điều phối đầy đủ: commands.md.

Chất lượng, bằng chứng và chi phí token

Mỗi phase cần hai tệp trong thư mục evidence của sprint: bản assessment do validate <phase> --report ... ghi ra, và báo cáo phase cho complete <phase> --report .... CLI từ chối hoàn thành phase khi thiếu assessment hiện hành (đúng input_digest), và từ chối khi assessment do chính tác giả của phase nộp — phải chấm bằng một danh tính khác. Đây là bản ghi trách nhiệm, không phải xác thực danh tính: CLI không chứng minh được ai thực sự chạy phiên nào. Giới hạn này áp dụng tương tự cho decide: agent chịu trách nhiệm ghi lại câu trả lời thật của bạn.

Test được ràng buộc với requirement bằng marker nằm trong chính tệp nguồn, nên độ phủ được đọc chứ không phải tự khai: BSA:VERIFIES REQ-001 trong tệp test, và BSA:LINK REQ-001 (tùy chọn) trong tệp code. complete implement thất bại nếu tệp test của một task không khai báo requirement của chính task đó. Lệnh test cấu hình kiểu no-op (true, echo, chương trình rỗng) bị từ chối ngay khi cấu hình — đây là denylist có giới hạn, không phải bảo đảm chất lượng test.

test --run tạo thêm evidence bundle: hành vi đã kiểm chứng, requirement đã khai báo, gap còn mở, ràng buộc bảo toàn từ baseline đã seal, và regression. Xem bằng ./bsa.sh evidence. Đây là dữ liệu bàn giao giữa các vòng lặp: planner đọc gap, tester ghi phần không kiểm chứng được thành gap thay vì suy ra thành công, và một regression (requirement đã kiểm chứng bị mất test bao phủ) sẽ chặn lần chạy thay vì báo xanh. BSA không tự sửa source khi có regression: nó ghi lại digest của trạng thái đã kiểm chứng gần nhất rồi dừng, để vai trò developer khôi phục.

Để giảm token, context <phase> trả về reading set có ngân sách byte thay vì lệnh "đọc toàn bộ": đường dẫn bắt buộc kèm kích thước, đường dẫn tùy chọn, và danh sách NEVER-load (docs/.truth, truth candidate của sprint khác). Prompt của phase được ghép thành prefix ổn định (giống byte-for-byte cho mọi lần gọi cùng phase trong cùng project, an toàn để prompt-cache) + dấu phân cách tường minh + suffix thay đổi (sprint, goal, digest, reading set). Nếu test đã chạy đúng cho digest hiện tại, agent chấm độ phủ thay vì chạy lại y hệt bộ test.

Tùy chọn nâng cao: chạy không giám sát từ CLI

Chỉ dùng phần này nếu muốn chạy ngoài hội thoại agent. Đây không phải bước bắt buộc của quy trình thông thường. Cần cài và đăng nhập CLI nhà cung cấp trước. Chọn một runner:

./bsa.sh configure --agent codex
# Hoặc: ./bsa.sh configure --agent claude
./bsa.sh pipeline --run --seal

Runner khởi chạy phiên agent cho từng phase và đọc prompt trong .bsa/prompts/. Codex dùng workspace-write; Claude giữ cơ chế quyền hiện có. BSA không bật bỏ qua sandbox/permissions. Cấu hình quyền, model, đăng nhập của nhà cung cấp vẫn được áp dụng. Agent thiết lập lệnh kiểm tra phù hợp với stack ở phase brainstorm. Có thể cấu hình trước nếu dự án đã có test suite, ví dụ với dự án thực sự hỗ trợ những lệnh này:

./bsa.sh configure --test-command '["pnpm", "test", "--run"]' \
                   --test-command '["pnpm", "build"]'

--test-command có thể lặp lại; mỗi lần configure sẽ thay toàn bộ danh sách lệnh test. BSA không coi runner exit 0 là hoàn thành: agent phải vượt gate bằng báo cáo đúng digest. Test thất bại được chuyển cho agent sửa; lỗi runner, timeout, không có tiến triển hoặc hết ngân sách bước sẽ dừng và giữ tiến độ. Sau khi xử lý, chạy lại cùng lệnh để resume. Không có --seal, pipeline dừng ở bản xem trước living truth.

Có thể dùng runner khác qua .bsa/config.json:

{
  "version": 2,
  "test_commands": [["python3", "-m", "unittest", "discover", "-s", "tests"]],
  "test_timeout_seconds": 600,
  "source_excludes": ["dist", "coverage"],
  "runner_command": ["my-agent-adapter", "{prompt_file}", "{project}", "{phase}"],
  "runner_timeout_seconds": 1800,
  "runner_max_steps": 30,
  "auto": {"iterations": 3, "stop_on_clean": 0}
}

auto là vòng ngoài cho chạy không giám sát: dùng đúng runner trên, giữ khóa để mỗi project chỉ có một vòng lặp, và luôn kết thúc bằng việc báo lý do dừng — human_decision (có finding chờ bạn trả lời), complete, regression, no_progress, clean (--stop-on-clean N) hoặc budget (--iterations N). auto không bao giờ tự trả lời finding của con người, không tự sửa source, và ghi mọi lần dừng vào .bsa/runs/. stop_on_clean 0 nghĩa là chạy tới hết ngân sách; một vòng chỉ được coi là "clean" khi có bundle bằng chứng và không còn gap — thiếu bằng chứng không phải là bằng chứng.

Record của mỗi lần chạy được mở trước vòng lặp đầu tiên và đóng ở mọi đường thoát, vì trường hợp cần bằng chứng nhất chính là lúc vòng lặp không thoát được: mất điện, bị kill, API chết. Record còn state: running nghĩa là lần chạy đó bị ngắt giữa chừng chứ không phải mất dấu, và status liệt kê nó trong unfinished_runs kèm live — process còn sống hay không. Vòng lặp không tự chạy đè lên record đó (agent được tạo session riêng nên bị kill ở vòng ngoài vẫn có thể đang ghi vào project); khi đã chắc process đã chết, chạy lại với --resume: record cũ chuyển thành superseded (giữ lại để tra cứu), lần chạy mới báo resumed_from, và các phase đã verified theo digest sẽ không bị làm lại. pipeline --run dùng chung gate này.

Các lệnh là argv array, không phải shell string. Adapter phải đọc prompt, thực hiện công việc và gọi BSA complete. Chỉ loại build output khỏi source_excludes; không loại source/test/manifest. Thay cấu hình sau khi hoàn thành gate sẽ yêu cầu đánh giá lại.

Các lệnh nội bộ dành cho agent

Agent tự gọi các lệnh này khi xử lý yêu cầu chat; người dùng không cần nhớ cú pháp.

Lệnh	Kết quả
init <path>	Tạo project runtime, hướng dẫn agent và baseline rỗng; không reset project đã init
start S001 --goal "..."	Mở sprint; cùng ID sẽ resume, không xóa dữ liệu
brainstorm	Chuẩn bị khám phá vấn đề, lựa chọn và giả định
product	Chuẩn bị PRD, spec và requirement có acceptance criteria
arch	Chuẩn bị kiến trúc và contracts
design	Chuẩn bị flow, trạng thái và accessibility
plan	Chuẩn bị task, dependency và kế hoạch kiểm chứng
implement	Chuẩn bị hướng dẫn implement và test, liên kết task với file
test --run	Chạy lệnh kiểm tra thật, lưu log và exit code
review	Chuẩn bị review riêng đối chiếu code/test với requirement
reconcile	Chuẩn bị bản living truth đầy đủ, dựa trên baseline trước
context <phase>	Trả digest, schema báo cáo và reading set có ngân sách byte cho phase
validate [phase] [--report <path>]	Chấm điểm phase; không có assessment hiện hành thì không thể hoàn thành
complete <phase> --report <path>	Xác thực và ghi hoàn thành, ngoại trừ test; đòi assessment từ danh tính khác tác giả
evidence	Bundle bằng chứng mới nhất: hành vi đã kiểm chứng, gap, ràng buộc bảo toàn, regression
feedback "..." --from design	Lưu feedback; vô hiệu hóa các gate cũ để đánh giá lại
pipeline	In hướng dẫn cho phase cần thực hiện tiếp
pipeline --run [--seal] [--resume]	Chạy runner tuần tự, resume từ trạng thái thực
auto [--iterations N] [--stop-on-clean N] [--seal] [--resume]	Vòng ngoài không giám sát; mỗi lần dừng đều báo lý do
status → unfinished_runs	Các lần chạy không báo lý do dừng, kèm process còn sống hay không
seal --dry-run	Kiểm tra điều kiện và hiển thị diff dự kiến
seal	Xuất bản phiên bản truth và đóng sprint; gọi lại không tạo phiên bản trùng
status	Trạng thái, gate hết hiệu lực và bước tiếp theo
audit	Kiểm tra tính toàn vẹn lịch sử sprint và truth

Runtime trong project có thể được gọi từ thư mục khác bằng đường dẫn tuyệt đối đến bsa.sh. CLI trong repository cũng hỗ trợ --project /path/to/project trước tên lệnh.

Cấu trúc project-meta và skill cục bộ

Setup tạo một workspace độc lập. Code sản phẩm nằm trong apps/services/, apps/frontends/ và apps/shared/; test ở cùng app. Các thư mục admin-bff và admin-portal là ví dụ tên ứng dụng, chỉ được tạo khi sản phẩm cần chúng. Runtime BSA nằm trong tools/bsa/, công cụ liên ứng dụng trong scripts/.

Bộ 10 skill BSA (điều phối sprint + 9 phase) được copy vào .agents/skills/ và .claude/skills/. Chúng tham chiếu đến workflow ngay trong project tại docs/framework/workflows/. Không cài vào home directory, không symlink tới skill global, không cần checkout BMAD/Spec-Kit/AgentKit bên ngoài. Các skill bổ sung cũng phải được cài project-scoped cùng tài nguyên cần thiết.

Các thay đổi workflow/skill làm gate cũ hết hiệu lực. Implementation gate kiểm tra file source/test được khai báo nằm dưới apps/, tools/ hoặc scripts/. Với dự án Node.js nhiều app, agent tạo pnpm workspace trong phase phù hợp; setup không giả định stack và không tạo app mẫu chưa được yêu cầu.

BSA Framework Guideline

Mở Guideline HTML trực tiếp trong trình duyệt. Trang dùng HTML, CSS, JavaScript thuần, hoạt động offline, không CDN hoặc build step. Nội dung gồm hướng dẫn setup/chat, cây thư mục, hợp đồng từng phase, tìm lệnh, mô phỏng gate ở sprint 2, living truth và cách cài skill project-scoped. Mỗi project tạo mới cũng nhận một bản tại docs/framework/guideline/index.html.

Tài liệu và nguồn chuẩn

project-meta/
├── AGENTS.md, CLAUDE.md          # Entry point của agent
├── bsa.sh                       # CLI wrapper, agent tự gọi
├── docs/
│   ├── framework/
│   │   ├── project-layout.md     # Quy tắc tổ chức dự án
│   │   ├── workflows/           # Quy trình chung + các phase
│   │   └── guideline/           # HTML/CSS/JS offline
│   ├── sprints/S001/            # PRD, spec, arch, design, plan, evidence…
│   │   ├── truth/               # Candidate chuẩn bị xuất bản
│   │   └── seal.json            # Provenance sau khi đóng
│   ├── .truth/versions/         # Snapshot baseline, S001, S002…
│   └── truth -> .truth/versions/S001
├── apps/
│   ├── services/               # Ví dụ admin-bff/
│   ├── frontends/              # Ví dụ admin-portal/
│   └── shared/                 # Thư viện dùng chung
├── tools/bsa/                  # Runtime + tài nguyên setup độc lập
├── scripts/                    # Công cụ liên ứng dụng
├── .agents/skills/bsa-*/        # 10 skill cục bộ cho Codex/agent
├── .claude/skills/bsa-*/        # Cùng bộ skill cho Claude
└── .bsa/                       # Config, state, locks, prompt, log

Trong sprint, agent đọc truth đã seal + thay đổi đang làm. Khi reconcile, agent hợp nhất trạng thái đã triển khai vào một bộ tài liệu đầy đủ. CLI không tự hiểu nội dung để merge. Nó kiểm tra yêu cầu sprint đã được phản ánh, yêu cầu cũ không bị sửa hoặc xóa ngầm, và không đưa yêu cầu chưa kiểm chứng vào truth.

Plan, task và feedback được giữ trong lịch sử sprint. Living truth chứa product, spec, architecture, design, contracts, requirements và quyết định còn áp dụng. changes.json ghi base_version và lý do loại requirement, kèm requirement sprint đã kiểm chứng hành vi loại bỏ đó. Công việc hoãn nằm trong backlog, không được coi là đã giao.

Gate và bằng chứng

• Artifact phải đầy đủ section, không còn placeholder; requirement/task không được rỗng.
• Mọi requirement có acceptance criteria và task; dependency không có vòng lặp.
• Implement cần task done, liên kết đến file source và test thực tế.
• Báo cáo cần agent/session, kết luận, check cụ thể, file bằng chứng và đúng input digest.
• Test chỉ hoàn thành qua test --run, không nhận báo cáo tự khai thay thế.
• Sửa artifact làm phase liên quan và các phase sau hết hiệu lực. Sửa code làm implement/test/review/reconcile hết hiệu lực. Sửa log/báo cáo cũng bị phát hiện.
• Feedback bảo thủ vô hiệu hóa toàn bộ gate; --from chỉ là gợi ý nơi xử lý. Agent được tái sử dụng nội dung không đổi nhưng phải đánh giá lại.
• Seal lưu hash source, artifact, evidence, phiên bản gốc và snapshot truth.
• Lock chống hai lệnh lifecycle ghi đồng thời. Journal phục hồi seal bị ngắt; con trỏ truth chuyển nguyên tử, không xuất bản nửa bộ tài liệu.

Đây là kiểm chứng cấu trúc, tính mới và kết quả lệnh. Chất lượng yêu cầu, độ bao phủ test và đánh giá nội dung vẫn do agent thực hiện; một JSON pass không chứng minh đánh giá độc lập. Framework không phải ranh giới bảo mật chống agent cố tình sửa validator. Lưu state, evidence, sprint và tất cả truth versions trong Git để truy vết.

Dự án cũ và cập nhật cấu trúc

Setup giữ nguyên project đã init, không tự di chuyển code hay nâng cấp đè runtime. Các project tạo từ bản trước vẫn dùng layout cũ cho đến khi được migrate có chủ đích. Để dùng cấu trúc mới, setup vào một thư mục project-meta mới rồi chuyển source vào apps và tài liệu cần giữ vào docs; kiểm chứng lại baseline trước khi seal. Không ghi đè sprint hoặc truth đã seal. Framework distribution vẫn giữ cấu trúc phát triển riêng.

phase1/phase2/phase3, clean và bridge đổi heading đã được bỏ. Không chạy clean giữa sprint. Các file v1 trong repository được giữ nguyên như dữ liệu lịch sử chưa được kiểm chứng, không được tự động nâng thành truth.

Tạo project bằng v2 trong thư mục riêng, chuyển source và tài liệu cũ cần giữ sang, rồi mở sprint baseline để agent đối chiếu với code/test trước khi seal. Với dự án có sẵn chưa có BSA, chạy bash /path/to/bsa-framework/setup.sh /path/to/project. Nếu trùng runtime hoặc thư mục lifecycle, init dừng để bảo toàn dữ liệu; không ghi đè.

Kiểm thử framework

make check

Suite kiểm thử project độc lập, hai sprint, stale gate, failed test, requirement/task coverage, sửa evidence, khôi phục seal, lock, đường dẫn có khoảng trắng và runner không giám sát bằng fixture. Kiểm thử không gọi dịch vụ AI hoặc tiêu thụ API credit.

Validate chất lượng từng phase

Gõ validate, validate design hoặc validate design sprint 2. Agent đánh giá nội dung, chạy kiểm tra cấu trúc, ghi findings trong docs/sprints/<id>/validation.json, tự sửa lỗi đơn giản và kiểm tra lại. Lệnh này không tự chuyển phase hay seal sprint.

Quyết định về phạm vi, hành vi sản phẩm, dữ liệu, bảo mật, chi phí hoặc kiến trúc khó đảo ngược cần câu trả lời của người dùng. Agent trình bày lựa chọn và tradeoff; status hiển thị awaiting_decisions, pipeline dừng chờ. Sau câu trả lời, agent ghi quyết định bằng CLI nội bộ decide F-ID --response "...", áp dụng rồi validate lại. CLI không xác thực người trả lời; agent phải ghi trung thực phản hồi nhận được.

CLI nội bộ: validate [phase] trả schema, digest và lỗi cấu trúc; validate <phase> --report <path> ghi đánh giá có evidence. Findings chưa xử lý không biến mất khi gửi report mới; completion, phase phụ thuộc và seal bị chặn. Report cũ hoặc evidence thay đổi cần validate lại. Validate bổ sung đánh giá chất lượng, không thay thế test thực tế hoặc report complete. Các agent phải validate trước khi complete theo workflow cục bộ; runtime vẫn chấp nhận complete report hiện hữu nếu phase chưa có ledger validate.