@longph2102/v-flow 1.5.0

package/templates/agent-config-template.md

@@ -0,0 +1,170 @@
+# Template: Agent Configuration — Cấu hình Agent Pipeline
+
+> Tài liệu cấu hình cho AI Agent trong dự án.
+> Tạo 1 lần trong **S.0b**, cập nhật khi cần dựa trên metrics.
+
+## Thông tin dự án
+
+| Mục | Giá trị |
+|-----|--------|
+| **Tên dự án** | [TÊN DỰ ÁN] |
+| **Ngày cấu hình** | [YYYY-MM-DD] |
+| **Phiên bản** | 1.0 |
+| **Người cấu hình** | [Tên] |
+
+---
+
+## 1. Model Assignment
+
+| Agent | Model | Temperature | Max Tokens | Ghi chú |
+|-------|-------|-------------|------------|---------|
+| BA Agent | [model-name] | 0.3 | 8192 | Advanced Elicitation |
+| BA Critic Agent | [model-name] | 0.3 | 8192 | Adversarial, fresh context |
+| Plan Agent | [model-name] | 0.2 | 16384 | |
+| Test Agent | [model-name] | 0.2 | 8192 | |
+| Master Check Agent | [model-name] | 0.1 | 16384 | Cần reasoning mạnh nhất |
+| Implement Agent | [model-name] | 0.1 | 32768 | Cần code generation mạnh |
+| **Review Agent** | [model-name] | 0.2 | 16384 | Adversarial, tìm ≥3 issues |
+| Understand Agent | [model-name] | 0.2 | 16384 | Codebase scan |
+| Constitute Agent | [model-name] | 0.3 | 8192 | Infer from code |
+| Sync Agent | [model-name] | 0.1 | 8192 | Diff analysis |
+| Metrics Agent | [model-name] | 0.2 | 8192 | Data collection |
+| Sprint Agent | [model-name] | 0.2 | 8192 | Planning |
+| Retrospective Agent | [model-name] | 0.3 | 8192 | Analysis |
+| Help/Status Agent | [model-name] | 0.2 | 4096 | Quick response |
+
+---
+
+## 2. Tool Access Matrix
+
+| Tool / Quyền | BA | Plan | Test | Master Check | Implement | Review |
+|---------------|:--:|:----:|:----:|:------------:|:---------:|:------:|
+| File Read (docs) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| File Read (src) | ❌ | ✅ | ✅ | ❌ | ✅ | ✅ |
+| File Write (src) | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
+| Terminal | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
+| Browser/Internet | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ |
+| Codebase Search | ❌ | ✅ | ✅ | ❌ | ✅ | ✅ |
+| Image Viewer | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+
+> Điều chỉnh theo nhu cầu dự án. Nguyên tắc: **least privilege** — chỉ cấp quyền cần thiết.
+
+---
+
+## 3. Context & Knowledge Sources
+
+### 3.1 Input bắt buộc cho mỗi Agent
+
+| Agent | Input bắt buộc | Input tùy chọn |
+|-------|----------------|----------------|
+| BA Agent | constitution.md, yêu cầu thô | wireframe, spec cũ, domain glossary |
+| BA Critic Agent | spec.md, constitution.md | spec-review-log.md (header only) |
+| Plan Agent | constitution.md, spec.md | existing codebase, ADRs, context.md |
+| Test Agent | constitution.md, spec.md | existing test patterns |
+| Master Check | constitution.md, spec.md, plan.md, test-cases.md | context.md (No-Go Zones) |
+| Implement Agent | constitution.md, plan.md, tasks.md, test-cases.md | existing code context, concerns list |
+| Review Agent | spec.md, plan.md, tasks.md, validation-report.md | constitution.md |
+| Understand Agent | codebase files | context.md (existing) |
+| Sync Agent | spec.md (new version), plan.md, tasks.md, test-cases.md | — |
+
+### 3.2 Knowledge Base Setup
+
+| Loại | Đường dẫn | Trạng thái |
+|------|-----------|------------|
+| Domain Glossary | `.v-flow/knowledge/domain-glossary.md` | [ ] Đã tạo |
+| Architecture Decisions | `.v-flow/knowledge/architecture-decisions/` | [ ] Đã tạo |
+| Code Patterns | `.v-flow/knowledge/patterns/` | [ ] Đã tạo |
+| Lessons Learned | `.v-flow/knowledge/lessons-learned/` | [ ] Đã tạo |
+
+---
+
+## 4. Non-determinism Strategy
+
+| Chiến lược | Áp dụng cho | Mô tả |
+|------------|-------------|--------|
+| **Retry with review** | Tất cả agents | Nếu output bị reject, chạy lại với feedback |
+| **Temperature tuning** | Implement Agent | Giảm temperature cho code generation |
+| **Seed fixing** | [Agent cụ thể] | Sử dụng seed cố định khi cần reproducibility |
+| **Ensemble voting** | [ ] Áp dụng / [ ] Không áp dụng | 2-3 runs, chọn output tốt nhất |
+
+---
+
+## 5. Prompt Versions
+
+| Agent | Prompt File | Version | Lần cập nhật cuối |
+|-------|-------------|---------|-------------------|
+| BA Agent | `agents/ba-agent.md` | v2.0 | [YYYY-MM-DD] |
+| BA Critic Agent | `agents/ba-critic-agent.md` | v2.0 | [YYYY-MM-DD] |
+| Plan Agent | `agents/plan-agent.md` | v2.0 | [YYYY-MM-DD] |
+| Test Agent | `agents/test-agent.md` | v2.0 | [YYYY-MM-DD] |
+| Master Check | `agents/master-check-agent.md` | v2.0 | [YYYY-MM-DD] |
+| Implement Agent | `agents/implement-agent.md` | v2.0 | [YYYY-MM-DD] |
+| Review Agent | `agents/review-agent.md` | v2.0 | [YYYY-MM-DD] |
+| Understand Agent | `agents/understand-agent.md` | v2.0 | [YYYY-MM-DD] |
+| Constitute Agent | `agents/constitute-agent.md` | v2.0 | [YYYY-MM-DD] |
+| Sync Agent | `agents/sync-agent.md` | v2.0 | [YYYY-MM-DD] |
+| Metrics Agent | `agents/metrics-agent.md` | v2.0 | [YYYY-MM-DD] |
+| Sprint Agent | `agents/sprint-agent.md` | v2.0 | [YYYY-MM-DD] |
+| Retrospective Agent | `agents/retrospective-agent.md` | v2.0 | [YYYY-MM-DD] |
+| Help Agent | `agents/help-agent.md` | v2.0 | [YYYY-MM-DD] |
+| Status Agent | `agents/status-agent.md` | v2.0 | [YYYY-MM-DD] |
+| Import BA Docs Agent | `agents/import-ba-docs-agent.md` | v2.0 | [YYYY-MM-DD] |
+
+---
+
+## 6. Guardrails — Input/Output Validation
+
+### 6.1 Input Guardrails
+
+| Agent | Guardrail | Mô tả |
+|-------|-----------|-------|
+| Tất cả | **Constitution check** | Reject input thiếu constitution.md |
+| BA Agent | **Format validation** | Yêu cầu có ≥ 1 requirement rõ ràng |
+| Implement Agent | **Scope check** | Chỉ modify files trong `tasks.md` |
+| Tất cả | **PII filter** | [ ] Bật / [ ] Tắt — lọc thông tin cá nhân |
+
+### 6.2 Output Guardrails
+
+| Agent | Guardrail | Action khi vi phạm |
+|-------|-----------|-------------------|
+| Tất cả | **Template compliance** | Output phải đúng template → reject nếu sai format |
+| Implement Agent | **File write scope** | Chỉ ghi vào files được chỉ định → block nếu ngoài scope |
+| Implement Agent | **No secrets in code** | Scan output cho API keys, passwords → block |
+| BA Agent | **Language consistency** | Output cùng ngôn ngữ với constitution |
+
+### 6.3 Safety & Content
+
+- [ ] **Harmful content filter**: Bật lọc nội dung không phù hợp
+- [ ] **Hallucination check**: Yêu cầu agent cite sources trong output
+- [ ] **Confidence threshold**: Reject output có confidence < [X]/5
+
+---
+
+## 7. Safe Iteration — Test trước Production
+
+### 7.1 Staging Strategy
+
+| Giai đoạn | Môi trường | Mục đích |
+|-----------|-----------|---------|
+| Dev | Local / sandbox | Test prompt changes nhanh |
+| Staging | Staging environment | Test với data representative |
+| Prod | Production | Sau khi staging OK |
+
+### 7.2 Khi thay đổi Agent Config
+
+```
+1. Thay đổi trên branch riêng
+2. Test với 1-2 features trên staging
+3. So sánh metrics staging vs production
+4. Nếu tốt hơn → merge vào main
+5. Ghi lại lý do thay đổi trong decision log
+```
+
+### 7.3 Rollback Plan
+
+- [ ] Giữ version cũ của agent-config.md (git history)
+- [ ] Nếu metrics xấu hơn sau thay đổi → revert ngay
+
+---
+
+> **Lưu ý**: Agent config được tạo 1 lần và cập nhật dựa trên [Agent Metrics](../docs/agent-metrics-guide.md). Review lại config sau mỗi 5-10 features.

package/templates/agent-definition-template.md

@@ -0,0 +1,145 @@
+# {Agent Name} — {Mô tả ngắn vai trò}
+
+> **Vai trò**: {Mô tả vai trò 1 dòng}
+> **Phase**: {Phase code — ví dụ: S.1, B.0a, R.0}
+> **Trigger**: {Lệnh kích hoạt — ví dụ: /v.specify, /v.plan}
+> **Điều kiện**: {Điều kiện để chạy agent này — hoặc "Không có điều kiện đặc biệt"}
+
+---
+
+## 1. Vai trò & Trách nhiệm
+
+{Mô tả 2-3 dòng: Agent này làm gì, tại sao cần, và giá trị chính nó mang lại.}
+
+**Nguyên tắc cốt lõi**:
+- {Nguyên tắc 1 — tóm tắt 1 dòng}
+- {Nguyên tắc 2}
+- {Nguyên tắc 3}
+
+---
+
+## 2. Quy trình làm việc
+
+### Bước 1: Chuẩn bị (Pre-conditions)
+1. {Kiểm tra điều kiện 1}
+2. {Đọc file input 1}
+3. {Đọc file input 2}
+
+### Bước 2: Thực hiện (Execution)
+1. {Bước thực hiện chính 1}
+2. {Bước thực hiện chính 2}
+3. {Bước thực hiện chính 3}
+
+### Bước 3: Output
+1. {Tạo artifact 1}
+2. {Cập nhật artifact 2 nếu có}
+
+---
+
+## 3. Input / Output
+
+### Input
+
+| Loại | File/Data | Mô tả |
+|:----:|-----------|-------|
+| **Bắt buộc** | {File/data bắt buộc 1} | {Mô tả ngắn} |
+| **Bắt buộc** | {File/data bắt buộc 2} | {Mô tả ngắn} |
+| **Tùy chọn** | {File/data tùy chọn} | {Mô tả ngắn} |
+
+### Output
+
+| File | Mô tả | Template |
+|------|-------|---------|
+| {File output 1} | {Mô tả nội dung} | `templates/{template}.md` |
+| {File output 2} | {Mô tả nội dung} | — |
+
+---
+
+## 4. Quy tắc quan trọng
+
+1. **{Quy tắc 1}** — {Giải thích ngắn}
+2. **{Quy tắc 2}** — {Giải thích ngắn}
+3. **{Quy tắc 3}** — {Giải thích ngắn}
+
+---
+
+## 5. Quality Gate — Tự kiểm tra trước khi output
+
+| Tiêu chí | Câu hỏi tự kiểm | Nếu KHÔNG → |
+|----------|-----------------|-------------|
+| **{Tiêu chí 1}** | "{Câu hỏi?}" | {Hành động} |
+| **{Tiêu chí 2}** | "{Câu hỏi?}" | {Hành động} |
+| **{Tiêu chí 3}** | "{Câu hỏi?}" | {Hành động} |
+
+> ⚠️ Nếu bất kỳ tiêu chí Critical nào FAIL → KHÔNG output. Sửa trước.
+
+---
+
+## 6. Xử lý khi gặp vấn đề
+
+| Tình huống | Hành động |
+|-----------|---------|
+| {Tình huống 1 — input thiếu} | {Cách xử lý} |
+| {Tình huống 2 — conflict} | {Cách xử lý} |
+| {Tình huống 3 — unclear} | {Cách xử lý — ghi Open Question} |
+| {Tình huống 4 — No-Go Zone} | {DỪNG — báo cho human} |
+
+---
+
+## 7. Routing — Bước tiếp theo
+
+```
+{Condition 1 — success}
+  → Route: {/v.command tiếp theo}
+  → Human action: {nếu cần}
+
+{Condition 2 — failure}
+  → Route: {/v.command khác}
+  → Lý do: {giải thích}
+
+{Condition 3 — ambiguous}
+  → Route: Escalate to human
+```
+
+---
+
+## 8. Cập nhật State & Session
+
+**Cập nhật `.flow-state.yaml`**:
+```yaml
+current_phase: "{phase_code}"
+phase_status: "done"               # done | awaiting_human | blocked
+artifacts:
+  {artifact_name}:
+    exists: true
+    # ... thêm fields tùy artifact
+```
+
+**Append vào `_session.md`**:
+```markdown
+### [{Phase}] {Agent Name} — [YYYY-MM-DD]
+- **Agent**: {Agent Name}
+- **Input**: {files đã đọc}
+- **Output**: {artifacts tạo ra}
+- **Key decisions**: {quyết định quan trọng nếu có}
+- **Quality Gate**: PASS / FAIL
+- **Routing**: → {bước tiếp theo}
+```
+
+**Agent Command Block** *(cuối artifact output)*:
+```yaml
+# --- AGENT COMMAND ---
+agent: "{Agent Name}"
+phase: "{phase_code}"
+timestamp: "YYYY-MM-DDTHH:MM:SS"
+
+state_updates:
+  current_phase: "{phase_code}"
+  phase_status: "done"
+
+routing:
+  next_phase: "{next_phase}"
+  next_command: "{/v.command}"
+  condition: "{điều kiện}"
+# --- END COMMAND ---
+```

package/templates/agent-metrics-template.md

@@ -0,0 +1,150 @@
+# Template: Agent Metrics Report
+
+> Điền sau mỗi feature cycle (**M.0**).
+> Lưu tại: `.v-flow/features/NNN-ten-feature/metrics-report.md`
+
+## Thông tin Feature
+
+| Mục | Giá trị |
+|-----|--------|
+| **Feature** | [#NNN — Tên feature] |
+| **Ngày bắt đầu** | [YYYY-MM-DD] |
+| **Ngày hoàn thành** | [YYYY-MM-DD] |
+| **Tổng thời gian** | [X giờ / ngày] |
+| **Pipeline type** | Full / Quick Fix / Hotfix |
+| **Người đánh giá** | [Tên] |
+
+---
+
+## 1. Metrics theo Agent
+
+### 1.1 Agent Performance Matrix
+
+| Agent | Pass lần 1? | Revisions | Thời gian | Quality (1-5) | Target | Trend |
+|-------|:----------:|:---------:|:---------:|:------------:|:------:|:-----:|
+| BA Agent | ✅/❌ | [N] | [N]m | /5 | ≥4 | ↑↓→ |
+| BA Critic | N/A | [N] rounds | [N]m | /5 | ≥4 | ↑↓→ |
+| Plan Agent | ✅/❌ | [N] | [N]m | /5 | ≥4 | ↑↓→ |
+| Test Agent | ✅/❌ | [N] | [N]m | /5 | ≥4 | ↑↓→ |
+| Master Check | PASS/FAIL | [N] | [N]m | /5 | ≥4 | ↑↓→ |
+| Implement Agent | ✅/❌ | [N] | [N]m | /5 | ≥4 | ↑↓→ |
+| Review Agent | ✅/❌ | [N] | [N]m | /5 | ≥4 | ↑↓→ |
+
+### 1.2 Agent Targets (Chuẩn hiệu suất)
+
+| Agent | Tiêu chí | Target | Actual | Met? |
+|-------|---------|:------:|:------:|:----:|
+| BA Agent | First-pass approval | ≥70% | [XX]% | ✅/❌ |
+| Plan Agent | First-pass approval | ≥80% | [XX]% | ✅/❌ |
+| Test Agent | REQ coverage | 100% | [XX]% | ✅/❌ |
+| Master Check | Catch rate | ≥90% | [XX]% | ✅/❌ |
+| Implement Agent | Tests pass rate | 100% | [XX]% | ✅/❌ |
+| Review Agent | Issues found | ≥3 | [N] | ✅/❌ |
+
+---
+
+## 2. Metrics Pipeline
+
+| Metric | Giá trị |
+|--------|--------|
+| **Master Check kết quả** | PASS / PASS WITH CONCERNS / FAIL (lần thứ ___) |
+| **Tổng cycle time** | [N] giờ |
+| **Phase bottleneck** | [Phase nào mất nhiều thời gian nhất] |
+| **Rework cycles** | [N] — quay lại phase: [phase list] |
+| **Code review rounds** | [N] |
+| **Concerns generated (R.0)** | [N] |
+| **Concerns resolved (B.1)** | [N]/[N] |
+| **UAT result** | Pass / Fail |
+| **Bugs found after deploy** | [N] |
+
+---
+
+## 2.5 Cost Metrics
+
+| Agent | Model | Tokens (Input) | Tokens (Output) | Chi phí (USD) |
+|-------|-------|:--------------:|:---------------:|:-------------:|
+| BA Agent | [model] | | | $ |
+| BA Critic | [model] | | | $ |
+| Plan Agent | [model] | | | $ |
+| Test Agent | [model] | | | $ |
+| Master Check | [model] | | | $ |
+| Implement Agent | [model] | | | $ |
+| Review Agent | [model] | | | $ |
+| **Tổng cộng** | | | | **$** |
+
+> 💡 Thu thập từ API usage logs hoặc provider dashboard.
+> So sánh cost/feature để tối ưu model selection.
+
+---
+
+## 3. Requirements Coverage
+
+| Metric | Số lượng |
+|--------|---------|
+| Requirements trong spec | [N] |
+| Tasks mapped to REQ | [N/N] |
+| Test cases mapped to REQ | [N/N] |
+| Tests pass | [N] |
+| Tests fail | [N] |
+| Coverage % | [XX]% |
+
+### Ground Truth Comparison (tùy chọn)
+
+| Agent | Golden test pass? | Score | Ghi chú |
+|-------|:-----------------:|:-----:|---------| 
+| BA Agent | ✅/❌ | /100 | So với golden spec |
+| Plan Agent | ✅/❌ | /100 | So với golden plan |
+| Test Agent | ✅/❌ | /100 | So với golden test cases |
+
+> 📎 Golden test datasets lưu tại `.v-flow/knowledge/golden-tests/`
+
+---
+
+## 4. Trend Analysis (so sánh N features gần nhất)
+
+| Metric | Feature N-2 | Feature N-1 | **Feature N** | Trend |
+|--------|:----------:|:----------:|:------------:|:-----:|
+| Cycle time (giờ) | | | | ↑↓→ |
+| Rework cycles | | | | ↑↓→ |
+| Master Check pass lần 1 | | | | ↑↓→ |
+| Code Review pass lần 1 | | | | ↑↓→ |
+| Cost per feature | | | | ↑↓→ |
+| Post-deploy bugs | | | | ↑↓→ |
+| Avg Quality score | | | | ↑↓→ |
+
+> ↑ = improving, ↓ = degrading, → = stable
+
+---
+
+## 5. Vấn đề & Bài học
+
+### Vấn đề gặp phải
+<!-- Liệt kê vấn đề phát sinh trong cycle -->
+1. [Mô tả vấn đề] → [Giải pháp / Workaround]
+
+### Bài học rút ra
+<!-- Kinh nghiệm cho cycles tiếp theo -->
+1. [Bài học]
+
+### Đề xuất cải tiến Agent Config
+<!-- Thay đổi agent config, prompt, model nếu cần -->
+
+| Đề xuất | Agent | Thay đổi | Priority | Lý do |
+|---------|-------|---------|:--------:|-------|
+| [mô tả] | [agent] | [model/temp/prompt] | High/Med/Low | [data-driven reason] |
+
+---
+
+## 6. Đánh giá tổng thể
+
+| Tiêu chí | Điểm (1-5) | Target |
+|----------|:-----------:|:------:|
+| Chất lượng spec | /5 | ≥4 |
+| Chất lượng plan | /5 | ≥4 |
+| Chất lượng test cases | /5 | ≥4 |
+| Chất lượng code | /5 | ≥4 |
+| Hiệu quả pipeline tổng thể | /5 | ≥4 |
+| Cost efficiency | /5 | ≥3 |
+| **Trung bình** | **/5** | **≥4** |
+
+> **So sánh với feature trước:** Tốt hơn / Tương đương / Kém hơn — [giải thích ngắn dùng data]

package/templates/api-contract-template.md

@@ -0,0 +1,72 @@
+# Template: API Contract
+
+> Được tạo bởi **API Contract Agent** — Phase B.0 (optional, `--with-api`)
+> Lưu tại `contracts/api-contract.md`
+> Feature: [TÊN FEATURE]
+> Spec Version: [vX.Y]
+
+> 📌 Contract là **nguồn chuẩn** để FE và BE làm song song (xem skill Contract-first). Đóng băng contract TRƯỚC khi implement.
+
+---
+
+## 1. Tổng quan
+
+- **Base URL**: `[https://api.example.com/v1]`
+- **Auth**: [Bearer JWT / API key / none]
+- **Content-Type**: `application/json`
+- **Versioning**: [path `/v1` / header `Accept-Version`]
+
+---
+
+## 2. Endpoints
+
+| Method | Path | Mô tả | Auth | New/Sửa | REQ |
+|--------|------|-------|:----:|:-------:|-----|
+| POST | `/auth/login` | Đăng nhập | ❌ | Mới | REQ-xxx |
+| GET | `/products` | Danh sách (paginated) | ✅ | Mới | REQ-xxx |
+
+---
+
+## 3. Request / Response Schemas
+
+### `POST /auth/login`
+
+**Request**
+```json
+{ "email": "string", "password": "string" }
+```
+
+**Response 200**
+```json
+{ "token": "string", "refreshToken": "string" }
+```
+
+> Lặp lại block cho mỗi endpoint. Ghi rõ field bắt buộc/optional, kiểu, ràng buộc.
+
+---
+
+## 4. Error Codes
+
+| HTTP | Code | Mô tả | Khi nào |
+|:----:|------|-------|---------|
+| 400 | `VALIDATION_ERROR` | Input sai | Field thiếu/sai định dạng |
+| 401 | `AUTH_INVALID` | Sai credentials | Login fail |
+| 429 | `RATE_LIMITED` | Quá giới hạn | Quá N request |
+
+> Error envelope chuẩn: `{ "error": { "code": "...", "message": "...", "details": [] } }`
+
+---
+
+## 5. Tương thích & Versioning (nếu SỬA contract cũ)
+
+| Endpoint | Field | Thay đổi | Trước | Sau | Breaking? |
+|----------|-------|:--------:|-------|-----|:---------:|
+| `POST /x` | `status` | Thêm | — | `enum(...)` | Không |
+
+- **Breaking change** → bump version (`/v2`) hoặc Expand-Contract (thêm field mới, giữ field cũ tới khi consumer chuyển hết).
+- **Consumer**: [ai đang gọi endpoint này — FE app / 3rd party]
+
+---
+
+> **Author**: API Contract Agent
+> **Mandatory khi**: Feature expose API cho client/3rd party, hoặc có cả FE + BE (contract-first)