@longph2102/v-flow 1.5.0

package/skills/operations/incident-runbook/examples/bad/vague-incident-report.md

@@ -0,0 +1,48 @@
+# Incident Runbook — Bad Example
+
+> Ví dụ output THIẾU SÓT — không nên làm theo.
+
+## ❌ Bad Output — Quá sơ sài
+
+```markdown
+## Incident
+
+Login broke after deployment. Fixed the config. Back to normal now.
+```
+
+## Vấn đề
+
+| # | Lỗi | Giải thích |
+|---|------|-----------|
+| 1 | Không có severity | Không biết P1 hay P4 |
+| 2 | Không có timeline | "Sau deployment" — khi nào? bao lâu? |
+| 3 | Không có root cause | "Config" — config gì? |
+| 4 | Không có impact assessment | "Broke" — ảnh hưởng bao nhiêu user? |
+| 5 | Không có post-mortem | Không học được gì → sẽ lặp lại |
+| 6 | Không có action items | Không ai chịu trách nhiệm prevent |
+
+## ❌ Bad Output — Có structure nhưng thiếu depth
+
+```markdown
+## Incident Report INC-042
+
+**Severity**: P1
+**Issue**: Login not working  
+**Fix**: Updated config
+**Status**: Resolved
+
+### Actions
+- Fix the bug
+- Deploy fix
+```
+
+## Vấn đề
+
+| # | Lỗi | Giải thích |
+|---|------|-----------|
+| 1 | "Login not working" — mơ hồ | 500? 403? Timeout? |
+| 2 | "Updated config" — cụ thể gì? | File nào? Thay đổi gì? |
+| 3 | Không có timeline | Mất bao lâu detect→fix? |
+| 4 | Không có verification | Sao biết fix hoạt động? |
+| 5 | Actions quá generic | "Fix the bug" — already done? future prevention? |
+| 6 | Không blame-free analysis | Không có systemic improvement |

package/skills/operations/incident-runbook/examples/good/p1-hotfix-response.md

@@ -0,0 +1,119 @@
+# Incident Runbook — Good Example: P1 Hotfix
+
+> Ví dụ output chuẩn khi Operations Agent xử lý P1 incident.
+
+## Scenario
+
+**Alert**: Login API returning 500 after deployment at 14:30
+**Impact**: All users unable to login — service effectively down
+
+## Output — operations-report.md
+
+```markdown
+## 🚨 Incident Report — INC-042
+
+**Status**: ✅ Resolved
+**Severity**: P1 — Service Down
+**Detected**: 2026-04-25 14:35 (monitoring alert)
+**Resolved**: 2026-04-25 15:10 (35 min total)
+**Impact**: 100% users unable to login for 35 minutes
+
+---
+
+### Triage (T+0 → T+5 min)
+
+**Alert Source**: Automated monitoring (5xx spike > 50%)
+**Impact Assessment**:
+  - Users affected: ALL (100%)
+  - Feature affected: Authentication (login, register, password reset)
+  - Data integrity: ✅ Safe (no write operations affected)
+
+**Severity**: P1 — Service Down
+**Response SLA**: < 15 min (started investigation at T+5m)
+
+---
+
+### Root Cause Analysis
+
+**Timeline**:
+
+| Time | Event |
+|------|-------|
+| 14:30 | Deploy v2.3.1 to production |
+| 14:32 | First 500 errors appear in logs |
+| 14:35 | Monitoring alert fires (5xx > 50%) |
+| 14:37 | On-call engineer acknowledges alert |
+| 14:40 | Investigation started — review deploy diff |
+| 14:45 | Root cause identified: JWT_SECRET env var missing |
+| 14:50 | Hotfix: restore env var in deployment config |
+| 14:55 | Redeployed with fix |
+| 15:00 | 5xx rate drops to 0% |
+| 15:10 | Confirmed stable — incident resolved |
+
+**Root Cause**: Deployment script v2.3.1 introduced new config template that didn't include `JWT_SECRET` environment variable. Auth middleware threw unhandled exception when trying to verify tokens → 500 for all authenticated routes.
+
+**Direct cause**: Missing env var in deployment config template
+**Contributing factor**: No pre-deploy env var validation
+**Systemic issue**: Deployment config not versioned with code
+
+---
+
+### Containment
+
+**Actions Taken**:
+1. ✅ Restored `JWT_SECRET` in deployment config
+2. ✅ Redeployed with correct config
+3. ✅ Verified login flow working end-to-end
+4. ✅ Posted status update to #incidents channel
+
+**Verification**:
+- Login success rate: 99.9% (back to normal)
+- 5xx rate: 0%
+- Response time: 120ms (normal baseline: 100-150ms)
+
+---
+
+### Fix Details
+
+**Route**: `/v.hotfix` (skip spec, direct implement → review → deploy)
+**Branch**: `hotfix/INC-042-jwt-secret`
+**Files changed**: 1 (`deploy/config.template.yaml`)
+**Test**: ✅ Smoke test — login flow works
+**Rollback plan**: Revert to v2.3.0 deployment config
+
+---
+
+### Post-Mortem
+
+**What went well**:
+1. Fast detection (3 min from deploy to alert)
+2. Clear RCA — identified in 10 minutes
+3. Fix was minimal and non-invasive
+
+**What went wrong**:
+1. No pre-deploy env var validation check
+2. Config template change not reviewed for env var completeness
+3. No canary deployment — went straight to 100%
+
+**Action Items**:
+
+| # | Action | Owner | Due | Status |
+|---|--------|-------|-----|--------|
+| 1 | Add env var validation to deploy pipeline | DevOps | Sprint 12 | ⬜ |
+| 2 | Add config template change to review checklist | Tech Lead | Sprint 12 | ⬜ |
+| 3 | Implement canary deployment (10% → 50% → 100%) | DevOps | Sprint 13 | ⬜ |
+| 4 | Add integration test for auth middleware startup | Dev | Sprint 12 | ⬜ |
+
+### Knowledge Base Update
+→ File: `.v-flow/knowledge/lessons-learned/INC-042-jwt-secret.md`
+→ Added No-Go note: deployment config templates require env var review
+```
+
+## Why This Is Good
+
+1. ✅ **Structured timeline** — rõ ràng từng phút xảy ra gì
+2. ✅ **Multi-level RCA** — direct, contributing, systemic causes
+3. ✅ **Containment verified** — metrics chứng minh fix hoạt động
+4. ✅ **Actionable post-mortem** — 4 specific items với owner và deadline
+5. ✅ **Knowledge captured** — lessons learned filed for future prevention
+6. ✅ **Non-blame** — focus vào process improvement, không blame cá nhân

package/skills/operations/incident-runbook/gotchas.md

@@ -0,0 +1,26 @@
+# Incident Runbook — Gotchas & Common Mistakes
+
+## ⚠️ Gotcha 1: Jumping to Fix Without Understanding
+
+**Sai**: Thấy error → sửa ngay dòng code gây lỗi.  
+**Đúng**: Triage → Investigate → Understand root cause → THEN fix. Quick patch che giấu vấn đề sâu hơn.
+
+## ⚠️ Gotcha 2: Incorrect Severity
+
+**Sai**: Mọi incident đều P1 vì "user is complaining".  
+**Đúng**: P1 = service down / data loss. P2 = major feature broken. Sai severity → sai response → resource waste.
+
+## ⚠️ Gotcha 3: Skipping Post-Mortem
+
+**Sai**: Fix xong → close ticket → move on.  
+**Đúng**: Post-mortem bắt buộc cho P1/P2. Ghi lessons learned vào `.v-flow/knowledge/lessons-learned/`.
+
+## ⚠️ Gotcha 4: Modifying No-Go Zones
+
+**Sai**: Emergency = được phép sửa mọi thứ.  
+**Đúng**: No-Go Zones vẫn cần Tech Lead approval, kể cả P1. Document lý do nếu phải vi phạm.
+
+## ⚠️ Gotcha 5: No Rollback Plan
+
+**Sai**: Deploy hotfix mà không có rollback strategy.  
+**Đúng**: Mỗi hotfix PHẢI có rollback plan. Feature flags preferred over code changes khi possible.

package/skills/plan/architecture-designer/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: architecture-designer
+description: "Hướng dẫn Plan Agent thiết kế kiến trúc từ spec. Agent PHẢI đọc skill này khi /v.plan được gọi. Đảm bảo design tuân thủ constitution + không vi phạm No-Go Zones."
+trigger: "Khi /v.plan được gọi, bắt đầu thiết kế kiến trúc"
+phase: "B.0a"
+used_by:
+  - /v.plan
+hooks:
+  pre_design: "Load spec.md + constitution.md + context.md → extract constraints"
+  post_design: "Cross-check plan vs No-Go Zones, verify pattern alignment"
+---
+
+# Architecture Designer — Thiết Kế Kiến Trúc Từ Spec
+
+> ⚠️ Đây là **Skill bắt buộc** cho Plan Agent khi thiết kế.
+> QUAN TRỌNG: Thiết kế PHẢI tuân thủ constitution và KHÔNG vi phạm No-Go Zones.
+>
+> → Xem `gotchas.md` cho lỗi thiết kế phổ biến.
+> → Xem `examples/good/` cho mẫu plan chuẩn — và `examples/bad/` cho anti-pattern (đối chứng).
+> → Xem `config.json` để customize (architecture style, layers).
+
+---
+
+## Khi nào KHÔNG áp dụng skill này
+
+- Quick Fix (`/v.quickfix`) — không cần thiết kế kiến trúc, direct bugfix
+- Hotfix (`/v.hotfix`) — minimal change, không redesign
+- Documentation-only change — không có code change
+
+> **Lite profile**: feature `quickfix`/`hotfix` (trong `.flow-state.yaml`) → plan tối giản; `v-flow validate` tự bỏ qua nudge Tech Decisions / NFR / file-structure. Vẫn giữ §6 File Changes + §3.4 DDL nếu đụng DB.
+
+---
+
+## Quy Trình Thiết Kế — Input → Design → Validate
+
+> 💡 Phần này cung cấp **framework tư duy**, không phải step-by-step script.
+
+### Phase 1: Constraint Extraction
+
+Trước khi thiết kế, extract TẤT CẢ constraints:
+
+```
+Từ constitution.md:
+  → Architecture pattern (MVC, Clean Architecture, Hexagonal...)
+  → Layer rules (dependency direction, coupling limits)
+  → Naming conventions (file, class, function)
+  → Error handling pattern (Result type, exceptions, error codes)
+
+Từ context.md (nếu legacy):
+  → No-Go Zones (KHÔNG ĐƯỢC ĐỤNG)
+  → Existing patterns (đang dùng pattern gì)
+  → Tech debt (cẩn thận khu vực này)
+  → Entry points (extend từ đâu)
+
+Từ spec.md:
+  → REQ → component mapping (REQ nào cần component mới?)
+  → Data flow (data đi từ đâu đến đâu?)
+  → Integration points (external systems?)
+```
+
+### Phase 2: Component Design
+
+**Signals đúng:**
+- Mỗi component có **single responsibility**
+- Dependency direction tuân thủ constitution (thường: UI → Domain → Data)
+- Interfaces tại boundaries (testable, mockable)
+- No-Go Zone code KHÔNG bị modify — tạo adapter/wrapper nếu cần
+
+**Signals sai:**
+- Component làm quá nhiều việc (> 3 responsibilities)
+- Circular dependency (A → B → C → A)
+- Bypass layer (UI gọi thẳng DB)
+- Modify No-Go Zone code trực tiếp
+
+### Phase 3: File Structure
+
+```markdown
+Với mỗi component trong design:
+  1. Xác định file path CHÍNH XÁC (không dùng "somewhere in src/")
+  2. Xác định file là MỚI hay MODIFY
+  3. Nếu MODIFY → check No-Go Zone → nếu trùng → DỪNG, redesign
+  4. Ghi dependencies giữa files (import direction)
+```
+
+---
+
+## Đặc Thù Và Quy Ước
+
+> 💡 Phần này chứa patterns Plan Agent thường bỏ sót.
+
+### 1. REQ → Component Traceability
+
+Mỗi component trong plan PHẢI trace về ≥1 REQ:
+- ❌ Component không có REQ → over-engineering, bỏ đi
+- ❌ REQ không có component → gap, thiếu design
+- ✅ Ma trận REQ ↔ Component rõ ràng trong plan.md
+
+### 2. Greenfield vs Legacy Design
+
+| Aspect | Greenfield | Legacy |
+|--------|-----------|--------|
+| Component mới | Tự do tạo | Phải fit existing structure |
+| Patterns | Theo constitution | Theo existing patterns + constitution |
+| No-Go Zones | Không có | **BẮT BUỘC check** mỗi file |
+| Entry points | Tự định nghĩa | Extend từ existing entry points |
+| Test strategy | Ideal (unit + integration) | Pragmatic (integration first) |
+
+### 3. Plan phải gồm Error Architecture
+
+- Error types: liệt kê error types cho feature này
+- Error flow: error propagate qua layers như thế nào
+- Error response: format cho API/UI consumers
+- Error logging: cái nào log, cái nào swallow
+
+### 4. Security Architecture Section
+
+Nếu feature involve auth/data → plan PHẢI có section Security:
+- Authentication flow
+- Authorization checks (WHERE trong code)
+- Data validation layer
+- Sensitive data handling
+
+### 5. Brownfield — Đặc tả thay đổi mức symbol
+
+Với mỗi file **SỬA** (không phải tạo mới), KHÔNG ghi "cập nhật logic". PHẢI có:
+- **Vị trí**: hàm / class / widget / endpoint cụ thể
+- **Hiện trạng**: behavior/code hiện tại
+- **Mong muốn**: sau khi sửa
+- **Loại**: Thêm / Sửa / Xóa / Refactor
+
+- ❌ "Sửa AuthService để hỗ trợ role" → mơ hồ, dev phải hỏi lại.
+- ✅ "`AuthService.login()`: hiện trả token ngay sau khi verify password → thêm bước check `user.role ∈ allowed` trước khi cấp token; ném `ForbiddenError` nếu fail."
+
+### 6. Screen Changes — lấy từ spec, không bịa
+
+Đọc **"Mô tả màn hình"** của từng `UC-xx` trong spec → đưa vào plan §5:
+- Màn hình nào **New/Sửa**, thay đổi gì
+- Component / widget liên quan
+- Các trạng thái: empty / loading / error / success
+- Token tham chiếu từ `DESIGN.md` (`button-primary`, `input-default`...) — KHÔNG hardcode hex/size
+
+### 7. Migration — khi đụng schema có sẵn
+
+Nếu data model đụng bảng đã tồn tại → tách rõ trong plan §3.4:
+- Bảng **MỚI** vs **ALTER** bảng cũ
+- Cột: tên / kiểu / null / default / index
+- File migration + rollback + backfill (nếu cần)
+- Mỗi schema change thường là 1 task `[DB]` riêng (đầu chuỗi).
+- **DDL thật (up + down)**: ghi câu lệnh copy-paste-được trong §3.4 (`ALTER/CREATE…` hoặc lệnh ORM tương đương) — dev không phải đoán. DDL là *đặc tả schema*, không phải code logic → không vi phạm "plan không chứa code".
+- **Breaking change → Expand-Contract** (zero-downtime): đổi/bỏ cột hoặc thêm NOT NULL → tách Expand (thêm cột nullable, ghi cả cũ+mới) → Migrate (backfill + đọc cột mới) → Contract (bỏ cột cũ release sau). KHÔNG ALTER phá tương thích trong 1 bước. → mẫu đầy đủ (DDL + chia release): `examples/good/expand-contract-migration.md`.
+
+### 8. Contract-first — khi có cả Frontend và Backend
+
+Nếu feature đụng **cả `[UI]` lẫn `[API]`** (FE gọi BE), phải **đóng băng contract TRƯỚC** để hai bên làm song song an toàn:
+- Chốt **data model** + **API contract** (request/response, error codes) → ghi vào `data-model.md` (theo `.v-flow/templates/data-model-template.md`) + `contracts/` (theo `.v-flow/templates/api-contract-template.md`).
+- Contract trở thành **một task sớm** (entrypoint hoặc dependency chung); task `[UI]` và `[API]` đều `[DEPENDS]` vào nó **trước khi** chạy `[PARALLEL]`.
+- ❌ FE và BE `[PARALLEL]` mà contract chưa chốt → hai bên đoán field khác nhau → rework.
+- ✅ Contract `[GATE]`/`[CRITICAL]` ở đầu → FE mock theo contract, BE implement theo contract, ghép không vỡ.
+
+### 9. NFR — đừng để Yêu cầu phi chức năng rơi rụng
+
+Mỗi `UC-xx` trong spec có mục **"Yêu cầu đặc biệt"** (perf / security / a11y / audit). Plan PHẢI kéo từng NFR vào §10 và gắn cách đáp ứng + nơi verify:
+- **Perf** → ngân sách (p95/throughput) → task `[TEST]` đo budget.
+- **A11y** → tiêu chí trong task `[UI]` (keyboard, label, contrast).
+- **Audit/Compliance** → task `[LOGIC]` (interceptor/log) — không nhét rải rác.
+- ❌ NFR chỉ nằm trong spec mà không có task → chắc chắn bị bỏ khi code.
+
+### 10. Observability & Rollout — feature lên production
+
+Nếu feature chạy thật → plan §11 phải trả lời: làm sao biết nó **chạy đúng/đổ vỡ**, và **tung ra an toàn**:
+- Feature flag (bật dần), metrics cần emit, logs (không lộ dữ liệu nhạy cảm), alerts (ngưỡng), rollout/rollback.
+- Gieo mầm cho `metrics-agent` / `operations` agent hạ nguồn.
+
+### 11. Truy vấn quan trọng (Key Queries) — đừng để dev đoán access pattern
+
+Truy vấn có pattern **không hiển nhiên** (filter/join/phân trang/soft-delete/aggregate) → ghi vào plan §3.5: **bảng · predicate chính** (vd `WHERE deleted_at IS NULL`) **· index dùng**. Ghi **hình dạng, KHÔNG full SQL** — giữ nguyên tắc "plan không chứa code logic". CRUD đơn giản theo PK → bỏ qua. (DDL migration thì NGƯỢC lại — ghi câu lệnh đầy đủ, vì DDL là đặc tả schema.)
+
+---
+
+## Plan Output Structure
+
+→ Xem `examples/good/plan-structure.md` cho format chuẩn.
+
+Minimum required sections:
+```
+1. Overview — mô tả kiến trúc 1 đoạn
+2. Component Diagram — mermaid hoặc ASCII
+3. File Structure — path chính xác, new/modify (file SỬA: vị trí symbol + hiện trạng→mong muốn)
+4. REQ ↔ Component Matrix — traceability
+5. Data Migrations (nếu đụng schema) — bảng new/alter, cột, **DDL thật up+down**, rollback; + **Key Queries** (§3.5) nếu truy vấn không hiển nhiên
+6. Screen Changes (nếu có UI) — màn hình, component, trạng thái, token DESIGN.md
+7. Dependencies — external deps + internal imports
+8. Error Architecture — error types, flow, response
+9. Security (nếu applicable) — auth, validation, data
+10. Tech Decisions — WHY chọn approach này + **phương án đã cân nhắc/loại** (alternatives) + đánh đổi (plan §13)
+11. NFR (nếu spec có Yêu cầu đặc biệt) — perf/a11y/audit → cách đáp ứng + verify
+12. Observability & Rollout (nếu lên production) — flags, metrics, alerts, rollout
+13. Assumptions & Open Questions — gom giả định thiết kế + câu hỏi `[CLARIFY]` về một chỗ
+```
+
+---
+
+## Self-Review — soi lại bằng "mắt mới" (bắt buộc trước khi handoff)
+
+> 💡 Viết xong plan → ĐỌC LẠI spec một lượt như chưa từng thấy plan, bắt gap **ngữ nghĩa** mà validator (structural) không thấy. Đây là **checklist tự chạy**, KHÔNG dispatch subagent, KHÔNG đẩy validator sang kiểm semantics (giữ phân vai: validator = lint cấu trúc · Master Check = ngữ nghĩa · human = phán xét).
+
+1. **Phủ spec 2 chiều**: lướt từng REQ/UC/NFR của spec → mỗi cái trỏ được tới ≥1 component/section trong plan? (thiếu = gap). **Và ngược lại**: mỗi component trong plan trace về ≥1 REQ? (thừa = over-engineering → bỏ).
+2. **Quét placeholder**: không còn `TBD`/`TODO`/"xử lý sau"/"thêm validation phù hợp"/"tương tự phần trên" — thay bằng nội dung thật, hoặc gắn `[CLARIFY]` + Câu hỏi mở nếu thật sự chưa rõ.
+3. **Nhất quán ký hiệu (symbol/naming)**: tên class/hàm/endpoint/bảng/token dùng ở section sau KHỚP đúng tên đã đặt ở section trước. `AuthService.login()` ở §3 mà thành `AuthSvc.signIn()` ở §8 = bug → sửa cho khớp.
+4. **DDL/contract khớp design**: §3.4 DDL up+down chạy được & khớp cột mô tả ở §3; §4.2 field contract khớp data model.
+
+Thấy lỗi → **sửa tại chỗ**, không cần review lại. Thiếu task/section cho 1 REQ → thêm. Mục tiêu: bắt drift NGAY, trước khi sang task-breakdown / Master Check.
+
+---
+
+## V-Flow Integration Points
+
+- **spec.md** (S.1) → Input: REQs + ACs
+- **constitution.md** → Constraint: patterns, conventions
+- **context.md** → Constraint: No-Go Zones, existing patterns
+- **task-breakdown skill** → Output plan → input cho task skill
+- **_session.md** → Ghi tech decisions + open questions
+
+---
+
+## Gotchas
+
+→ Xem `gotchas.md` cho lỗi thiết kế phổ biến — cập nhật liên tục.

package/skills/plan/architecture-designer/config.json

@@ -0,0 +1,32 @@
+{
+  "setup_questions": [
+    {
+      "id": "architecture_style",
+      "question": "Architecture style ưu tiên?",
+      "options": ["clean-architecture", "mvc", "hexagonal", "layered", "auto-detect"],
+      "default": "auto-detect",
+      "description": "auto-detect = đọc constitution.md để xác định. Nếu không có → dùng layered."
+    },
+    {
+      "id": "diagram_format",
+      "question": "Component diagram format?",
+      "options": ["mermaid", "ascii", "none"],
+      "default": "mermaid"
+    },
+    {
+      "id": "include_security",
+      "question": "Luôn include security architecture section?",
+      "type": "boolean",
+      "default": true
+    }
+  ],
+  "hooks": {
+    "pre_design": "Extract No-Go Zones từ context.md, extract patterns từ constitution.md",
+    "post_design": "Verify: mỗi REQ có component, mỗi file path chính xác, No-Go Zone safe"
+  },
+  "memory": {
+    "file": "plan-history.log",
+    "format": "[date] | [feature] | [components_count] | [new_files] | [modified_files] | [nogo_checks_passed]",
+    "purpose": "Track design decisions — dùng cho /v.retrospective"
+  }
+}

package/skills/plan/architecture-designer/examples/bad/vague-plan.md

@@ -0,0 +1,62 @@
+# Ví dụ XẤU — Plan mơ hồ (KHÔNG làm theo)
+
+> ⚠️ Đây là **anti-pattern**. Đối chiếu với `examples/good/plan-structure.md`.
+> Mỗi khối dưới đây minh họa một lỗi trong `gotchas.md`.
+
+---
+
+## ❌ 1. File path mơ hồ + thiếu loại New/Modify
+
+```
+| Component | Vị trí | Mô tả |
+|-----------|--------|-------|
+| Login | đâu đó trong src/ | xử lý đăng nhập |
+| Token   | core           | lưu token |
+```
+
+**Sai vì**: "đâu đó trong src/", "core" → Implement Agent tự quyết path → cấu trúc lệch chuẩn; không biết file MỚI hay SỬA.
+**Sửa**: `lib/features/auth/data/auth_repository_impl.dart` (NEW) — path chính xác + đánh dấu New/Modify.
+
+---
+
+## ❌ 2. Thiếu REQ traceability (over-engineering)
+
+```
+Components: LoginService, AuthCache, RetryManager, CircuitBreaker, MetricsCollector, PluginRegistry
+```
+
+**Sai vì**: spec chỉ có REQ về đăng nhập email/password. `PluginRegistry`, `CircuitBreaker` không trace về REQ nào → YAGNI, thừa.
+**Sửa**: mỗi component PHẢI map ≥1 REQ-xxx. Không có REQ → bỏ.
+
+---
+
+## ❌ 3. Chỉ có happy path — thiếu Error Architecture
+
+```
+Luồng: User nhập → gọi API → nhận token → vào Home. Xong.
+```
+
+**Sai vì**: không nói gì khi 401 / mất mạng / account khóa → error handling ad-hoc, format lỗi mỗi nơi mỗi kiểu.
+**Sửa**: bảng Error Architecture (type → HTTP → handler → message), xem `examples/good`.
+
+---
+
+## ❌ 4. Đụng No-Go Zone mà không kiểm tra
+
+```
+Sửa trực tiếp `legacy/sso_handler.dart` để thêm field role.
+```
+
+**Sai vì**: `sso_handler.dart` nằm trong No-Go Zone (context.md §4). Sửa trực tiếp → Implement Agent bị block ở B.1, phải re-plan.
+**Sửa**: tạo adapter/wrapper, KHÔNG sửa code vùng cấm; ghi rõ ở §9 No-Go Verification.
+
+---
+
+## ❌ 5. Mô tả thay đổi chung chung (brownfield)
+
+```
+- AuthService: cập nhật logic để hỗ trợ role.
+```
+
+**Sai vì**: "cập nhật logic" → dev phải hỏi lại sửa hàm nào, sửa gì.
+**Sửa**: `AuthService.login()` — hiện trả token ngay sau verify password → thêm bước check `user.role ∈ allowed` trước khi cấp token; ném `ForbiddenError` nếu fail.

package/skills/plan/architecture-designer/examples/good/expand-contract-migration.md

@@ -0,0 +1,56 @@
+# Ví dụ — Breaking migration zero-downtime (Expand-Contract) + chia release
+
+> Minh hoạ đổi cột phá tương thích **mà không downtime**, tách 3 bước qua **2 release** (milestone). Đây là case template §3.4 mô tả nhưng ít được demo. Mỗi bước = 1 task `[DB]` riêng, có **DDL up+down thật**.
+
+## Bối cảnh
+Đổi `users.full_name` (1 cột) → tách `first_name` + `last_name`. Đổi/bỏ cột trực tiếp = breaking (app cũ còn đọc `full_name`). Dùng **Expand → Migrate → Contract**.
+
+## §3.4 Database Migrations (3 bước)
+
+| Bảng | Bước | New/ALTER | Cột | DDL |
+|------|------|:---------:|-----|-----|
+| `users` | 1 Expand | ALTER | `first_name`, `last_name` (nullable) | thêm cột mới, KHÔNG bỏ `full_name` |
+| `users` | 2 Migrate | — | (backfill) | copy dữ liệu, app ghi cả cũ+mới, đọc cột mới |
+| `users` | 3 Contract | ALTER | bỏ `full_name` | chỉ sau khi không còn consumer đọc cột cũ |
+
+### DDL thật
+
+```sql
+-- Bước 1 — Expand (Release N)
+-- up
+ALTER TABLE users ADD COLUMN first_name text NULL;
+ALTER TABLE users ADD COLUMN last_name  text NULL;
+-- down
+ALTER TABLE users DROP COLUMN first_name;
+ALTER TABLE users DROP COLUMN last_name;
+
+-- Bước 2 — Migrate (Release N, sau khi deploy code ghi cả cũ+mới)
+-- up
+UPDATE users
+   SET first_name = split_part(full_name, ' ', 1),
+       last_name  = NULLIF(substring(full_name FROM position(' ' IN full_name) + 1), '')
+ WHERE first_name IS NULL;
+-- down: không cần (chỉ backfill; cột cũ vẫn còn)
+
+-- Bước 3 — Contract (Release N+1, sau khi mọi consumer đã chuyển)
+-- up
+ALTER TABLE users DROP COLUMN full_name;
+-- down
+ALTER TABLE users ADD COLUMN full_name text;
+UPDATE users SET full_name = concat_ws(' ', first_name, last_name);
+```
+
+## Phân rã task (qua 2 release)
+
+| Task | Bước | `[DB]` | Release / Milestone | Ghi chú |
+|------|------|--------|---------------------|---------|
+| T-101 | Expand | thêm 2 cột nullable | M1 (Release N) | an toàn, không breaking |
+| T-102 | App ghi cả cũ+mới | `[LOGIC]` | M1 | dual-write trước khi backfill |
+| T-103 | Migrate/backfill | UPDATE | M1 | chạy sau khi T-102 deployed |
+| T-104 | Chuyển đọc sang cột mới | `[LOGIC]` | M1 | |
+| T-105 | Contract — bỏ `full_name` | `[DB]` `[GATE]` | **M2 (Release N+1)** | chỉ khi không còn consumer cột cũ |
+
+## Vì sao chia release (Tech Decision)
+- **KHÔNG** ALTER phá tương thích trong 1 bước → tránh downtime + rollback an toàn từng bước.
+- Bước Contract (T-105) tách sang **release sau** + gắn `[GATE]` chờ xác nhận không còn ai đọc `full_name`.
+- ❌ Anti-pattern: `ALTER TABLE users RENAME COLUMN full_name ...` trong 1 migration → app cũ vỡ ngay khi deploy.

package/skills/plan/architecture-designer/examples/good/plan-structure.md

@@ -0,0 +1,58 @@
+# Ví dụ — Plan Structure (User Login Feature)
+
+> Đây là mẫu output chuẩn cho Plan Agent khi thiết kế kiến trúc.
+
+---
+
+## 1. Overview
+
+Feature User Login implement authentication flow với email/password. Sử dụng Clean Architecture theo constitution, tách rõ data → domain → presentation layers.
+
+## 2. Component Diagram
+
+```mermaid
+graph TD
+  A[LoginScreen] -->|events| B[LoginBloc]
+  B -->|call| C[LoginUseCase]
+  C -->|call| D[AuthRepository]
+  D -->|HTTP| E[AuthApiService]
+  D -->|cache| F[TokenStorage]
+```
+
+## 3. File Structure
+
+| File Path | Type | Description |
+|-----------|------|-------------|
+| `lib/features/auth/presentation/login_screen.dart` | NEW | Login UI |
+| `lib/features/auth/presentation/login_bloc.dart` | NEW | State management |
+| `lib/features/auth/domain/login_usecase.dart` | NEW | Business logic |
+| `lib/features/auth/domain/auth_repository.dart` | NEW | Repository interface |
+| `lib/features/auth/data/auth_repository_impl.dart` | NEW | Repository implementation |
+| `lib/features/auth/data/auth_api_service.dart` | NEW | API client |
+| `lib/core/storage/token_storage.dart` | MODIFY | Add auth token methods |
+
+⚠️ No-Go Zone check: `token_storage.dart` OK — not in No-Go Zone (verified context.md §4).
+
+## 4. REQ ↔ Component Matrix
+
+| REQ | Component(s) | Responsibility |
+|-----|-------------|----------------|
+| REQ-E01 | LoginScreen, LoginBloc, LoginUseCase, AuthRepository | Login success flow |
+| REQ-E02 | LoginBloc, LoginUseCase | Invalid credentials handling |
+| REQ-U01 | AuthApiService | Password security (hash before send) |
+| REQ-O01 | LoginBloc | Rate limiting (> 5 attempts) |
+
+## 5. Error Architecture
+
+| Error Type | HTTP Code | Handler | User Message |
+|-----------|----------|---------|--------------|
+| InvalidCredentials | 401 | LoginBloc | "Email hoặc mật khẩu không đúng" |
+| AccountLocked | 423 | LoginBloc | "Tài khoản bị khóa, liên hệ support" |
+| NetworkError | - | LoginBloc | "Không có kết nối mạng" |
+| ServerError | 500 | LoginBloc | "Hệ thống lỗi, thử lại sau" |
+
+## 6. Tech Decisions
+
+- **BLoC pattern**: Theo constitution §3.2 — state management cho Flutter.
+- **Repository pattern**: Interface tại domain boundary → testable với mock.
+- **WHY không modify legacy SSO**: No-Go Zone — tạo adapter thay vì modify.