Unified Agent Index (v1.6.2)

v1.6.2 giới thiệu Unified Agent Index — hệ thống chỉ mục skills trigger song song với rules index hiện có, cấu trúc agent map mới trong project schema thay thế has_rules, và cơ chế Proactive Trigger Check đảm bảo agent quét tất cả trigger tables trước khi thực hiện các thao tác có tác dụng phụ (side-effect).

Tính năng mới

1. Skills Trigger Index

Skills index tuân theo cùng mô hình Two-Tier Progressive Disclosure như rules:

Thành phần	Đường dẫn
Template	`repo/templates/common/agent/skills.md`
Bản workspace	`.agent/skills.md`
Đồng bộ bởi	`install.sh` (cùng logic với `rules.md`)

Agent đọc file index (~10 dòng) khi bắt đầu phiên và nạp từng skill riêng lẻ theo yêu cầu khi trigger khớp.

2. Agent Map trong project.md

# v1.6.2+ (mới)
agent:
  rules: true
  skills: true

# Legacy (deprecated, vẫn tương thích ngược)
has_rules: true

Workflow /open kiểm tra agent.rules trước, fallback sang has_rules để đảm bảo tương thích ngược.

3. Proactive Trigger Check

Trước BẤT KỲ thao tác nào chỉnh sửa file, chạy lệnh, hoặc tạo artifact:

Quét bảng trigger workspace rules.md
Quét bảng trigger workspace skills.md
Quét bảng trigger project (nếu đã nạp)
Nếu tìm thấy khớp → đọc file rule/skill TRƯỚC khi hành động

Nguyên tắc: Kiểm tra trước, hành động sau — không bao giờ làm ngược lại.

4. Agent Indices Pre-flight (Layer 3)

Tất cả 7 workflows có Step 0 giờ đều đọc lại cả rules.md VÀ skills.md:

/plan, /docs, /backlog, /push, /release, /retro, /end

Cơ chế này bảo vệ khỏi hiện tượng suy giảm chú ý (attention decay) trong các cuộc hội thoại dài — ngay cả khi /open đã nạp indices từ đầu phiên.

Luồng nạp dữ liệu (Loading Flow)

/open
  ↓
Step 2.5a: Đọc .agent/rules.md (rules index workspace) — LUÔN LUÔN
  → Ghi nhớ triggers (CHƯA đọc file rules chi tiết)
  ↓
Step 2.5b: Đọc .agent/skills.md (skills index workspace) — LUÔN LUÔN (v1.6.2+)
  → Ghi nhớ skill triggers
  ↓
Step 2.5c: Kiểm tra agent.rules / agent.skills / has_rules?
  → CÓ → Đọc project indices
  → KHÔNG → Bỏ qua (workspace indices vẫn đã nạp)
  ↓
Phiên coding: agent chuẩn bị chỉnh sửa file
  → Proactive Trigger Check → Tìm thấy khớp → nạp rule/skill tương ứng → tuân thủ

Cập nhật Defense-in-Depth

Layer   Nội dung                     Vị trí                          Tồn tại khi truncate
─────   ─────────────────────────    ─────────────────────────────   ────────────────────
  1     Chỉ dẫn trong index          agent-behavior.md §4            ⚠️ Mất sau truncation
  2     Khối an toàn trong output    /open Step 8 report             ✅ Trong checkpoint
  3     Workflow pre-flight          Step 0: đọc lại rules + skills  ✅ Lấy mới từ ổ đĩa
  4     File guard headers           <!-- ⚠️ ... --> trong file      ✅ Nằm trực tiếp trong file

Layer 3 giờ bao gồm Proactive Trigger Check — nguyên tắc “Kiểm tra trước, hành động sau”.

Phạm vi áp dụng trên Workflow

Workflow	Rules Index	Skills Index	Pre-flight
`/open`	✅ Step 2.5a (LUÔN)	✅ Step 2.5b (LUÔN)	— (chính là bộ nạp)
`/plan`	✅ Step 2.7 D1-D2	✅ Step 2.7 D3	✅ Step 0 (v1.6.2)
`/docs`	✅ Step 0	✅ Step 0	✅ Step 0 (v1.6.2)
`/push`	✅ Step 0	✅ Step 0	✅ Step 0 (v1.6.2)
`/release`	✅ Step 0	✅ Step 0	✅ Step 0 (v1.6.2)
`/end`	✅ Step 0	✅ Step 0	✅ Step 0 (v1.6.2)
`/backlog`	✅ Step 0	✅ Step 0	✅ Step 0 (v1.6.2)
`/retro`	✅ Step 0	✅ Step 0	✅ Step 0 (v1.6.2)
`/para-audit`	—	—	Kiểm tra tính nhất quán agent index

Di chuyển (Migration)

Không cần thao tác di chuyển nào. Hoàn toàn tương thích ngược:

has_rules: true vẫn hoạt động bình thường (fallback trong /open)
Các dự án chưa có agent map không bị ảnh hưởng
/para-audit update sẽ gợi ý di chuyển từ has_rules sang agent map

Thêm mới trong v1.6.2 (FEAT-53). Xem thêm: Rule Layers · Defense-in-Depth · Glossary

→ Tìm hiểu: Rule Layers Architecture → Tìm hiểu: Defense-in-Depth → Tìm hiểu: Glossary & Impact Map → Tìm hiểu: Para-Kit Skill