Cấu trúc repo

Cây thư mục đầy đủ, ý nghĩa từng file khi dùng, và bảng tra “tôi muốn … thì mở file …”.

Cấu trúc thư mục

Luật lõi ở một chỗ, chi tiết tách theo thư mục

Mỗi thư mục có README.md riêng. Đây là những gì bạn thấy khi mở bản clone.

agent-agile-team/gốc repo
AGENTS.mdluật lõi — agent đọc mỗi phiên (≤120 dòng, ≤10 KB)
CLAUDE.mdmột dòng @AGENTS.md cho Claude Code
GEMINI.mdcon trỏ tới AGENTS.md cho Antigravity
README.md · README.vi.mdgiới thiệu ngắn (Anh · Việt)
GUIDE.mdsprint đầu tiên — bạn làm gì, agent làm gì
INSTALL.mdhướng dẫn cài dành cho AI agent (prompt dán ở cuối)
method/luật chơi: process, sizing, severity, evidence, review-gate, conventions
standards/chuẩn code chung và theo ngôn ngữ
roles/thẻ vai: executor/ (4) · verifier/ (2 + dual-review + 4 chuyên đề)
tiers/ba tier và hợp đồng bảng tier → model (tiers.example.json)
skills/32 skill, mỗi skill một thư mục skills/<tên>/SKILL.md
agents/13 agent chuyên đề, mỗi agent một file
templates/khuôn hồ sơ: sprint/ (6) · registry/ (5) · project/agile.json
scripts/init.py · check.py · index.py (+ _common.py)
tests/bộ test pytest và fixture
samples/order-desk/một dự án mẫu đã dùng thật, kết quả kỳ vọng cố định
hosts/cài và nạp theo harness: claude · codex · antigravity · claude-desktop
docs/OVERVIEW · MIGRATION · standardization · troubleshooting · updating-from-upstream
UPSTREAM.md · NOTICE · THIRD_PARTY.md · LICENSEnguồn gốc, bản quyền, giấy phép
CHANGELOG.mdmục mới nhất đứng đầu, trùng version của manifest
.claude-plugin/ · .codex-plugin/manifest plugin cho Claude Code và Codex

Ý nghĩa khi dùng

Khi nào bạn hoặc agent chạm tới từng thư mục, file.

Thư mục / file	Khi nào bạn hoặc agent chạm tới
`AGENTS.md`	nạp đầu mọi phiên; là bản rút gọn của `method/` — khác nhau thì `method/` thắng
`method/process.md` · `sizing.md` · `severity.md` · `evidence.md`	khi phân vân có được hỏi người dùng không, chọn cỡ việc, gán mức phát hiện, ghi kết quả kiểm
`method/review-gate.md` · `roles/verifier/dual-review.md`	khi review diff cỡ vừa trở lên, hoặc việc chạm luật / secret / xác thực
`roles/executor/.md` · `roles/verifier/.md`	khi giao vai cho một agent: mục đích, đầu vào, đầu ra, được làm, không được làm, khi nào dừng
`skills/<tên>/SKILL.md`	agent tự gọi theo tình huống; `tests/pressure.md` hay `tests/retrieval.md` là bằng chứng skill đã thử
`agents/<tên>.md`	Tech Reviewer kéo theo trigger; trên Codex / Antigravity đọc như thẻ vai trong brief
`templates/sprint/` · `templates/registry/`	`init` chép ra dự án của bạn; `templates/README.md` là hợp đồng khoá, tiêu đề, trạng thái mà `check` dựa vào
`templates/project/agile.json` → `.agile.json`	đường dẫn hồ sơ, ngưỡng coverage, sổ tập trung của từng dự án
`scripts/`	agent chạy trước mỗi cổng; bạn chỉ đọc dòng cuối
`samples/order-desk/`	xem hồ sơ thật trông thế nào trước khi mở sprint đầu tiên
`hosts/<harness>/README.md`	cài, kiểm, cập nhật, gỡ trên harness của bạn
`docs/troubleshooting.md`	triệu chứng → nguyên nhân → cách xử lý khi cài và dùng lần đầu

Tra nhanh: tôi muốn … thì mở file …

Hiểu bộ này trong 5 phút

docs/OVERVIEW.md, rồi README.vi.md

Cài lên máy

INSTALL.md (dán prompt cho agent) hoặc hosts/<harness>/README.md (tự gõ)

Chạy sprint đầu tiên

GUIDE.md

Biết agent được phép làm gì, dừng khi nào

AGENTS.md, rồi method/process.md

Biết việc này cỡ nào, có cần ADR không

method/sizing.md, method/conventions.md

Xem một hồ sơ sprint mẫu

samples/order-desk/docs/plans/

Biết mỗi mã (FR, TK, VR…) nghĩa gì

skills/id-convention/SKILL.md

Biết check báo lỗi gì, vì sao

scripts/README.md mục “Luật của check”

Sửa hay thêm skill

skills/writing-skills/SKILL.md, skills/README.md

Biết skill này lấy từ đâu, giấy phép gì

frontmatter của skill, UPSTREAM.md, THIRD_PARTY.md

Gặp tên skill cũ trong hồ sơ lịch sử

docs/MIGRATION.md

Cài rồi mà agent không biết luật

docs/troubleshooting.md