@leejungkiin/awkit 1.1.9 → 1.3.4

package/skills/module-spec-writer/module-spec-writer/SKILL.md

@@ -0,0 +1,414 @@
+---
+name: module-spec-writer
+description: >-
+  Gate 1.5 — Module Specification Writer. Tạo tài liệu mô tả chi tiết từng module
+  của ứng dụng: screens, user flows, business rules, validation, data contracts,
+  edge cases. Chạy sau brainstorm (Gate 1) và trước architecture design (Gate 2).
+  Đặc biệt critical cho port/migration projects.
+metadata:
+  stage: core
+  version: "1.0"
+  tags: [gate, spec, module, product-spec, documentation, core]
+  requires: orchestrator
+agent: Spec Writer
+trigger: conditional
+invocation-type: auto
+priority: 1
+activation_keywords:
+  - "module spec"
+  - "mô tả module"
+  - "screen inventory"
+  - "feature spec"
+  - "product spec"
+  - "mô tả app"
+  - "document modules"
+---
+
+# Module Spec Writer v1.0 — Gate 1.5: Product Specification
+
+> **Purpose:** Tạo tài liệu mô tả chi tiết từng module/feature của ứng dụng
+> ở cấp độ **Product** (screens, flows, rules) — TRƯỚC KHI đi vào thiết kế
+> kỹ thuật (DB/API). Đảm bảo AI và user có shared understanding về "app làm gì"
+> trước khi bàn "app xây thế nào".
+>
+> **Problem it solves:**
+> - "Nhảy thẳng vào code mà chưa ai mô tả rõ app có bao nhiêu màn hình"
+> - "Port app từ iOS sang Android mà không ai document chi tiết app gốc"
+
+---
+
+## ⚠️ SCOPE CLARITY
+
+| Skill này LÀM | Skill này KHÔNG làm |
+|---------------|---------------------|
+| Mô tả screens, user flows, business rules per module | Thiết kế DB/API (việc của spec-gate) |
+| Tạo screen inventory cho toàn app | Viết code |
+| Document validation rules & edge cases | Track tasks (việc của symphony-enforcer) |
+| Scan existing codebase để auto-generate spec (port projects) | Brainstorm ý tưởng (việc của brainstorm-agent) |
+| Yêu cầu user approve module spec | Deploy |
+
+---
+
+## 🚀 ACTIVATION
+
+Skill này được kích hoạt bởi:
+1. **Orchestrator auto-trigger:** Khi Gate 1.5 check FAIL (không tìm thấy module specs)
+2. **Explicit command:** `/module-spec` hoặc `/product-spec`
+3. **Keyword trigger:** "module spec", "mô tả module", "screen inventory"
+
+### Khi nào Gate 1.5 MANDATORY:
+
+```yaml
+mandatory_when:
+  - complexity: COMPLEX (score ≥6)
+  - project_type: port/migration (iOS→Android, Android→iOS)
+  - module_count: >3 modules in BRIEF.md
+  - explicit_request: user asks for module documentation
+
+skip_when:
+  - complexity: TRIVIAL or MODERATE
+  - module_count: ≤3 AND not port/migration
+  - user_override: "skip spec" or "bỏ qua spec"
+```
+
+---
+
+## 📋 INPUT REQUIREMENTS
+
+```
+REQUIRED:
+  → BRIEF.md hoặc docs/specs/<feature>.md (output từ Gate 1)
+    HOẶC existing codebase (cho port/migration projects)
+  → .project-identity (projectId, techStack)
+
+OPTIONAL:
+  → CODEBASE.md (project structure overview)
+  → KnowledgeItems (existing module documentation)
+  → NeuralMemory context (previous decisions)
+  → Source codebase (for port/migration — iOS/Android source files)
+```
+
+---
+
+## 🔄 PROCESS
+
+### Phase 1: Module Discovery
+
+```
+INPUT SOURCE DETECTION:
+  A) Có BRIEF.md → Extract module list từ "TÍNH NĂNG" section
+  B) Có existing codebase (port project) → Scan source code structure:
+     - iOS: Xcode project groups, Views/, Features/ folders
+     - Android: feature/ packages, activities, fragments
+     - Đọc CODEBASE.md nếu có
+  C) Cả hai → Cross-reference BRIEF với source code
+
+OUTPUT: Danh sách modules cần spec:
+  Module 1: [name] — [1-line description]
+  Module 2: [name] — [1-line description]
+  ...
+
+PRESENT cho user:
+  "📋 Em tìm thấy [N] modules cần document:
+   1. [Module A] — [description]
+   2. [Module B] — [description]
+   ...
+   Anh xem có đúng/đủ không? Bổ sung/bỏ bớt cứ nói nhé."
+```
+
+### Phase 2: Per-Module Spec Generation
+
+Cho MỖI module, tạo spec theo template chuẩn:
+
+```
+Quy trình:
+1. Gather context:
+   - BRIEF.md → extract relevant features
+   - Source code (nếu port) → scan screens, ViewModels, models
+   - KnowledgeItems → extract existing documentation
+   - NeuralMemory → previous decisions
+
+2. Generate spec draft using template (see TEMPLATE section)
+
+3. Self-review checklist (per module):
+   - [ ] Tất cả screens đã liệt kê?
+   - [ ] Happy path flow rõ ràng?
+   - [ ] Error/edge cases đã cover?
+   - [ ] Business rules explicit (không implicit)?
+   - [ ] Data contracts rõ input/output?
+   - [ ] Acceptance criteria testable?
+```
+
+### Phase 3: Cross-Module Consistency Check
+
+```
+Sau khi TẤT CẢ module specs xong:
+
+1. Dependency graph:
+   - Module A depends on Module B? Đã ghi trong cả 2 specs?
+   - Circular dependency? → Cảnh báo
+
+2. Shared concepts:
+   - User model xuất hiện ở nhiều modules? → Consistent fields?
+   - Navigation flow giữa modules logic?
+
+3. Coverage check:
+   - Mọi feature trong BRIEF.md đã có module spec?
+   - Mọi screen trong source code (port) đã có trong inventory?
+```
+
+### Phase 4: Present & Approval
+
+```
+Present cho user với format:
+
+────────────────────────────────────
+📋 MODULE SPECIFICATIONS: <Project Name>
+────────────────────────────────────
+
+Đã tạo [N] module specs:
+
+| # | Module | Screens | Flows | Status |
+|---|--------|---------|-------|--------|
+| 1 | [name] | [count] | [count] | Draft |
+| 2 | [name] | [count] | [count] | Draft |
+
+## Cross-Module Notes
+- [Note 1: shared concern]
+- [Note 2: dependency]
+
+────────────────────────────────────
+⏳ Anh review từng file spec nhé. Sửa gì cứ nói.
+   Chốt hết thì mình chuyển sang thiết kế kỹ thuật (Gate 2).
+────────────────────────────────────
+```
+
+### Phase 5: Write & Store
+
+Sau khi user approve:
+
+```
+1. Tạo folder: docs/specs/modules/ (nếu chưa có)
+
+2. Write files:
+   docs/specs/modules/<module-name>_spec.md  (cho mỗi module)
+   docs/specs/modules/MODULE_INDEX.md        (index file)
+
+3. Thêm approval marker cho mỗi file:
+   ## Status: Approved
+   **Approved by:** User
+   **Approved at:** <ISO date>
+
+4. Lưu vào NeuralMemory:
+   nmem_remember(
+     content="Module specs approved for <project>. Modules: <list>. Total screens: <N>",
+     type="decision",
+     tags=["module-spec", "<projectId>"]
+   )
+
+5. Proceed → orchestrator re-checks Gate 1.5 → PASS → Gate 2
+```
+
+---
+
+## 📝 MODULE SPEC TEMPLATE
+
+```markdown
+# 📋 Module Spec: [Module Name]
+
+**Project:** [project-name]
+**Version:** 1.0
+**Created:** [date]
+**Status:** Draft | Approved
+
+---
+
+## Overview
+[1-2 câu mô tả mục đích module này trong app]
+
+## Dependencies
+- **Depends on:** [list modules this depends on]
+- **Used by:** [list modules that depend on this]
+- **Shared services:** [auth, analytics, etc.]
+
+---
+
+## Screen Inventory
+
+| # | Screen Name | Type | Key Elements | Notes |
+|---|------------|------|--------------|-------|
+| 1 | [name] | [full/modal/sheet/overlay/tab] | [main UI components] | [optional] |
+
+---
+
+## User Flows
+
+### Flow 1: [Happy Path Name]
+**Entry:** [how user gets here]
+**Steps:**
+1. User [action] → Screen [A]
+2. User [action] → System [response]
+3. System [shows/navigates] → Screen [B]
+4. **End state:** [what user sees/has achieved]
+
+### Flow 2: [Alternative Path / Error Path]
+**Trigger:** [what causes this path]
+**Steps:**
+1. ...
+
+---
+
+## Business Rules
+
+| ID | Rule | Details |
+|----|------|---------|
+| BR-01 | [rule name] | [full description] |
+| BR-02 | [rule name] | [full description] |
+
+---
+
+## Validation Rules
+
+| Field | Condition | Error Message | Screen |
+|-------|-----------|---------------|--------|
+| [field] | [rule] | [message] | [where] |
+
+---
+
+## Data Contracts
+
+### Input (consumed by this module)
+| Data | Type | Source | Required |
+|------|------|--------|----------|
+| [name] | [type] | [module/API/local] | [yes/no] |
+
+### Output (produced by this module)
+| Data | Type | Destination | Trigger |
+|------|------|-------------|---------|
+| [name] | [type] | [module/API/local] | [when] |
+
+---
+
+## Edge Cases & Error States
+
+| ID | Scenario | Expected Behavior |
+|----|----------|-------------------|
+| EC-01 | [scenario] | [what should happen] |
+| EC-02 | [scenario] | [what should happen] |
+
+---
+
+## Acceptance Criteria
+- [ ] [measurable criterion 1]
+- [ ] [measurable criterion 2]
+- [ ] [measurable criterion 3]
+```
+
+---
+
+## 📄 MODULE INDEX TEMPLATE
+
+```markdown
+# 📚 Module Index: [Project Name]
+
+**Total modules:** [N]
+**Created:** [date]
+**Status:** [All Approved / Some Draft]
+
+| # | Module | Spec File | Screens | Status |
+|---|--------|-----------|---------|--------|
+| 1 | [name] | [link to spec file] | [count] | Approved |
+| 2 | [name] | [link to spec file] | [count] | Draft |
+
+## Dependency Graph
+[Module A] → [Module B] → [Module C]
+[Module D] → [Module B]
+
+## Shared Services
+- **Auth:** Used by [modules]
+- **Analytics:** Used by [modules]
+- **AI/ML:** Used by [modules]
+```
+
+---
+
+## 🔄 PORT/MIGRATION MODE
+
+Khi project là port/migration (iOS→Android, Android→iOS):
+
+```
+SPECIAL BEHAVIOR:
+1. Scan source codebase TRƯỚC → auto-detect modules
+2. Đọc existing KnowledgeItems cho source project
+3. Cross-reference với BRIEF.md để catch missing modules
+4. Generate specs từ source code structure + knowledge
+
+AUTO-DETECTION SOURCES:
+  iOS:
+    → Xcode project navigator groups
+    → Features/ or Presentation/Views/ folders
+    → NavigationStack/TabView structure
+    → Existing CODEBASE.md
+
+  Android:
+    → feature/ packages
+    → Navigation graph (nav_graph.xml)
+    → Activity/Fragment inventory
+    → Existing CODEBASE.md
+
+OUTPUT: Pre-filled module specs with data from source code
+  → User chỉ cần review + approve, không cần viết từ đầu
+```
+
+---
+
+## 🗣️ Communication Style
+
+```
+❌ "Module specification documents are required before proceeding."
+✅ "Trước khi bắt tay vào thiết kế kỹ thuật, để em mô tả chi tiết
+    từng module — screens nào, flow ra sao — để anh em hiểu rõ cùng nhau."
+
+❌ "Please review 8 specification documents."
+✅ "Em đã viết xong spec cho 8 modules. Anh xem từng cái nhé,
+    sửa gì cứ nói, chốt hết rồi mình chuyển sang thiết kế DB/API."
+```
+
+---
+
+## 🚫 Anti-Patterns
+
+```yaml
+never_do:
+  - Tự approve module specs (user PHẢI approve)
+  - Viết spec quá vắn tắt (< 5 screens → cảnh báo "có thiếu screen không?")
+  - Skip cross-module consistency check
+  - Trộn lẫn product spec với technical spec (DB/API)
+  - Bắt đầu Gate 2 khi còn module spec ở status "Draft"
+  - Force Gate 1.5 cho TRIVIAL tasks
+
+always_do:
+  - Show module list cho user confirm TRƯỚC khi viết spec
+  - Chạy cross-module consistency check SAU khi viết hết
+  - Ghi acceptance criteria testable (SMART)
+  - Scan source code khi port/migration project
+  - Tag specs vào NeuralMemory
+```
+
+---
+
+## 🧩 Skill Relationships
+
+```
+TRIGGERED BY: orchestrator (Gate 1.5 check fail)
+DEPENDS ON: brainstorm-agent output (Gate 1 must pass first)
+FEEDS INTO: spec-gate (Gate 2 reads module specs to design DB/API)
+WORKS WITH:
+  - nm-memory-sync (store module decisions)
+  - gitnexus-intelligence (scan source codebase structure)
+  - KnowledgeItems (read existing project documentation)
+```
+
+---
+
+*module-spec-writer v1.0 — Product Specification Gate for AWKit*

package/skills/orchestrator/SKILL.md

@@ -1,25 +1,27 @@
 ---
 name: orchestrator
 description: >-
-  Autonomous State Machine Gatekeeper — triages task complexity, enforces 5-Gate pipeline,
+  Autonomous State Machine Gatekeeper — triages task complexity, enforces 7-Gate pipeline,
   and auto-routes to the correct skill. AI tự kiểm tra trạng thái dự án và bắt buộc
   user đi qua đúng Gate trước khi code. User KHÔNG CẦN gọi workflow bằng tay.
+  Hỗ trợ auto-detect .kiro/specs từ IDE Kiro để bypass/accelerate Gates.
 metadata:
   stage: core
-  version: "2.1"
-  replaces: "1.0"
-  tags: [orchestrator, routing, gate, triage, state-machine, core]
+  version: "2.3"
+  replaces: "2.2"
+  tags: [orchestrator, routing, gate, triage, state-machine, core, kiro]
 agent: Orchestrator
 trigger: always
 invocation-type: auto
 priority: 0
 ---
 
-# Orchestrator v2.1 — Autonomous State Machine Gatekeeper
+# Orchestrator v2.3 — Autonomous State Machine Gatekeeper
 
-> **Purpose:** Route mọi request qua hệ thống 5-Gate tự động.
+> **Purpose:** Route mọi request qua hệ thống 7-Gate tự động.
 > AI tự nhận diện project state → tự quyết định gate nào cần chạy.
 > User chỉ cần nói ý tưởng, AI lo phần còn lại.
+> Hỗ trợ auto-detect `.kiro/specs` để accelerate/bypass Gates khi IDE đã tạo sẵn specs.
 
 ---
 
@@ -47,6 +49,89 @@ AI LÀ NGƯỜI GIÁM SÁT "CÁN CÂN" CỦA DỰ ÁN.
 
 ---
 
+## 🔍 Kiro Spec Detection (Auto-Accelerate Gates)
+
+> **Kiro** là IDE có khả năng sinh spec cấu trúc tại `.kiro/specs/`.
+> Khi phát hiện thư mục này, orchestrator tự động map nội dung vào Gate system,
+> giúp bypass/accelerate các Gates mà không cần AI tự sinh lại tài liệu.
+
+### Detection Logic (chạy ĐẦU TIÊN trước Gate check)
+
+```yaml
+kiro_detection:
+  trigger: Mỗi khi bắt đầu COMPLEX task
+  scan_path: ".kiro/specs/" (tương đối từ project root)
+
+  structure_expected:
+    .kiro/specs/
+    ├── <project-slug>/          # Top-level project spec
+    │   ├── requirements.md      # → Gate 1 (Spec)
+    │   ├── design.md            # → Gate 2 (Architecture)
+    │   └── tasks.md             # → Gate 3 (Symphony Tasks)
+    ├── <module-01>/             # Per-module specs
+    │   ├── requirements.md      # → Gate 1.5 (Module Spec)
+    │   ├── design.md            # → Gate 2 (per-module design)
+    │   └── tasks.md             # → Gate 3 (per-module tasks)
+    └── <module-02>/
+        └── ...
+
+  gate_mapping:
+    gate_1_spec:
+      pass_if: ANY requirements.md exists in .kiro/specs/
+      source: .kiro/specs/<project-slug>/requirements.md
+      action: Load as project BRIEF — bypass brainstorm-agent
+
+    gate_1_5_module_spec:
+      pass_if: ≥2 module folders (excluding project-slug) with requirements.md
+      source: .kiro/specs/<module>/requirements.md (each)
+      action: Load as module specs — bypass module-spec-writer
+
+    gate_2_architecture:
+      pass_if: ANY design.md exists in .kiro/specs/
+      source: .kiro/specs/<project-slug>/design.md + per-module design.md
+      action: Load as approved design — auto-approve (user already approved in Kiro)
+
+    gate_2_5_visual:
+      pass_if: NOT affected (Kiro doesn't produce visual designs)
+      action: Normal Gate 2.5 flow
+
+    gate_3_tasks:
+      pass_if: ANY tasks.md exists in .kiro/specs/
+      source: .kiro/specs/<module>/tasks.md (each)
+      action: Parse tasks → auto-create Symphony tickets
+
+  output_format:
+    "🔍 KIRO SPECS DETECTED at .kiro/specs/
+       📄 Requirements: {count} files (Gate 1 + 1.5 → AUTO-PASS)
+       📐 Design docs:  {count} files (Gate 2 → AUTO-PASS)
+       📋 Task lists:   {count} files (Gate 3 → AUTO-IMPORT)
+       Modules: {list module names}"
+```
+
+### Kiro Spec Priority Rules
+
+```
+1. .kiro/specs > docs/specs > docs/architecture > Brain/NeuralMemory
+   → Kiro specs LUÔN được ưu tiên khi tồn tại
+
+2. Nếu CẢ .kiro/specs VÀ docs/specs tồn tại:
+   → Dùng .kiro/specs làm source of truth
+   → Cảnh báo: "⚠️ Phát hiện cả .kiro/specs và docs/specs.
+     Sử dụng .kiro/specs làm source of truth. docs/specs có thể outdated."
+
+3. Kiro specs KHÔNG thay thế:
+   → Gate 2.5 (Visual Design) — Kiro không tạo design visuals
+   → Gate 5 (Verification) — luôn cần run tests/build
+   → NeuralMemory decisions — vẫn lưu context vào brain
+
+4. Khi code (Gate 4), AI PHẢI đối chiếu với:
+   → .kiro/specs/<module>/requirements.md (acceptance criteria)
+   → .kiro/specs/<module>/design.md (technical design)
+   → .kiro/specs/<module>/tasks.md (task checklist)
+```
+
+---
+
 ## 🎯 STEP 1: Complexity Triage (BẮT BUỘC)
 
 Mỗi khi nhận request từ user, orchestrator PHẢI phân loại complexity **TRƯỚC** mọi action khác.
@@ -89,8 +174,8 @@ TRIVIAL  (score 0-2): Bypass ALL gates → Execute trực tiếp
 MODERATE (score 3-5): Gate 3 + 4 + 5
   Examples: thêm UI component, sửa logic business nhỏ, update 1-2 files
 
-COMPLEX  (score 6-10): ALL 5 Gates bắt buộc
-  Examples: thêm feature mới, thay đổi DB schema, refactor architecture, thêm API
+COMPLEX  (score 6-10): ALL 7 Gates bắt buộc
+  Examples: thêm feature mới, thay đổi DB schema, thiết kế UI, refactor architecture, thêm API
 ```
 
 ### Output Format
@@ -112,27 +197,69 @@ Dừng tại Gate ĐẦU TIÊN chưa thỏa mãn.
 
 ```
 CHECK: Tồn tại file mô tả feature này?
-  → Scan: docs/specs/<feature>.md HOẶC docs/BRIEF.md có section liên quan
-  → Hoặc: NeuralMemory có BRIEF/SPEC cho feature này
+  → CHECK 1 (Kiro): .kiro/specs/<module>/requirements.md tồn tại?
+    → CÓ → AUTO-PASS Gate 1 (Kiro specs detected)
+  → CHECK 2: docs/specs/<feature>.md HOẶC docs/BRIEF.md có section liên quan
+  → CHECK 3: NeuralMemory có BRIEF/SPEC cho feature này
 
-PASS condition: File tồn tại VÀ có nội dung rõ ràng (use cases, target users, scope)
+PASS condition:
+  - .kiro/specs requirements.md tồn tại (highest priority), HOẶC
+  - docs/specs file tồn tại VÀ có nội dung rõ ràng, HOẶC
+  - NeuralMemory có BRIEF/SPEC
 
 FAIL action:
   → Thông báo user: "Ý tưởng rất hay! Nhưng trước khi bắt tay vào code, 
      để tôi hỏi vài câu để chốt rõ yêu cầu đã nhé."
   → Kích hoạt: brainstorm-agent skill (Phase 2-6)
   → Output: BRIEF.md hoặc docs/specs/<feature>.md
-  → Sau khi tạo xong → Re-check Gate 1 → Proceed Gate 2
+  → Sau khi tạo xong → Re-check Gate 1 → Proceed Gate 1.5
+```
+
+### Gate 1.5: Module Specification 🟠
+
+```
+CHECK: Mỗi module có file spec chi tiết?
+  → CHECK 1 (Kiro): .kiro/specs/ chứa ≥2 module folders với requirements.md?
+    → CÓ → AUTO-PASS Gate 1.5 (Kiro module specs detected)
+    → Load từng .kiro/specs/<module>/requirements.md làm module spec
+  → CHECK 2: docs/specs/modules/<module>_spec.md tồn tại?
+  → CHECK 3: NeuralMemory có module specs cho project này
+
+PASS condition:
+  - .kiro/specs module folders tồn tại (highest priority), HOẶC
+  - Tất cả modules có spec file VÀ status "Approved"
+
+SKIP condition:
+  → TRIVIAL hoặc MODERATE tasks → SKIP
+  → Single-module projects (≤3 modules, không phải port) → SKIP
+  → User nói "skip spec" → SKIP
+
+MANDATORY condition:
+  → COMPLEX (score ≥6) VÀ >3 modules
+  → Port/migration projects (iOS→Android, Android→iOS)
+
+FAIL action:
+  → Thông báo user: "Trước khi thiết kế kỹ thuật, để em mô tả chi tiết
+     từng module — screens, flows, rules — để anh em hiểu rõ cùng nhau."
+  → Kích hoạt: module-spec-writer skill
+  → Output: docs/specs/modules/<module>_spec.md (per module)
+  → Sau khi tạo + approved → Re-check Gate 1.5 → Proceed Gate 2
 ```
 
 ### Gate 2: Architecture & Data Design 🟠
 
 ```
 CHECK: Tồn tại bản thiết kế kỹ thuật đã được duyệt?
-  → Scan: docs/architecture/<feature>_design.md
-  → HOẶC: implementation_plan.md có section "Data Model" + marker "Approved"
+  → CHECK 1 (Kiro): .kiro/specs/<module>/design.md tồn tại?
+    → CÓ → AUTO-PASS Gate 2 (Kiro design specs detected, pre-approved by IDE)
+    → Load design.md làm approved architecture document
+    → Lưu vào NeuralMemory: "Kiro design docs loaded for <modules>"
+  → CHECK 2: docs/architecture/<feature>_design.md tồn tại?
+  → CHECK 3: implementation_plan.md có section "Data Model" + marker "Approved"
 
-PASS condition: File tồn tại VÀ có marker "## Status: Approved"
+PASS condition:
+  - .kiro/specs design.md tồn tại (highest priority, auto-approved), HOẶC
+  - docs/architecture file tồn tại VÀ có marker "## Status: Approved"
 
 FAIL action:
   → Thông báo user: "Đã có spec rồi. Giờ để tôi phác thảo thiết kế 
@@ -140,19 +267,45 @@ FAIL action:
   → Kích hoạt: spec-gate skill
   → Output: docs/architecture/<feature>_design.md
   → Yêu cầu user approve design
-  → Sau khi approved → Re-check Gate 2 → Proceed Gate 3
+  → Sau khi approved → Re-check Gate 2 → Proceed Gate 2.5
+```
+
+### Gate 2.5: Visual Design & UI Sync 🎨
+
+```
+CHECK: Đã có thiết kế UI/hiểu biết chung về UI chưa?
+  → Scan: docs/design/ hoặc docs/screenshot/ có ảnh/tài liệu UI
+  → HOẶC: file docs/design/<feature>.pen đã được duyệt
+
+PASS condition: Đã có ảnh UI tham chiếu HOẶC bản vẽ Pencil đính kèm.
+
+SKIP condition:
+  → Backend/Logic-only tasks (Cron, API pure, Refactor, DB Query...)
+  → User nói "skip design"
+
+FAIL action:
+  → Thông báo user: "Tính năng này có giao diện nên để đảm bảo đồng bộ, 
+     tôi sẽ phác thảo qua thiết kế bằng Pencil hoặc anh có thể gửi ảnh screenshot/vào docs/design/ trước nhé."
+  → Kích hoạt: visual-design-gate skill
+  → Output: UI layout thống nhất (ảnh / .pen file)
+  → Xác nhận approve visual preview
+  → Sau khi approved → Re-check Gate 2.5 → Proceed Gate 3
 ```
 
 ### Gate 3: Task Breakdown (Symphony) 🟡
 
 ```
 CHECK: Có Symphony tasks liên kết feature này?
-  → symphony_available_tasks → filter by feature keyword/tag
+  → CHECK 1 (Kiro): .kiro/specs/<module>/tasks.md tồn tại?
+    → CÓ → Parse tasks từ Kiro tasks.md
+    → Map task items → Symphony tickets (symphony_create_task)
+    → AUTO-IMPORT: Tạo Symphony tasks từ Kiro task list
+  → CHECK 2: symphony_available_tasks → filter by feature keyword/tag
 
 PASS condition: ≥1 task tồn tại cho feature này
 
 FAIL action:
-  → Đọc design doc từ Gate 2
+  → Đọc design doc từ Gate 2 (hoặc .kiro/specs design.md)
   → Auto-generate 3-8 micro-tasks
   → Tạo Symphony tasks (symphony_create_task cho mỗi task)
   → Present danh sách cho user confirm
@@ -304,7 +457,9 @@ always_do:
 ```
 DELEGATES TO:
   Gate 1 → brainstorm-agent (phỏng vấn → BRIEF.md)
+  Gate 1.5 → module-spec-writer (mô tả chi tiết per-module spec)
   Gate 2 → spec-gate (thiết kế DB/API → design doc)
+  Gate 2.5 → visual-design-gate (thống nhất UI/UX bằng Pencil)
   Gate 3 → symphony-enforcer (tạo + track tasks)
   Gate 4 → relevant coding workflow (/code, /codeExpert)
   Gate 5 → verification-gate + code-review
@@ -333,7 +488,11 @@ DOES NOT:
 | Multiple features cùng lúc | Triage TỪNG feature riêng |
 | Spec tồn tại nhưng outdated | Cảnh báo "Spec cũ, cần update?" |
 | Project chưa có docs/ folder | Tạo folder structure tự động |
+| `.kiro/specs/` tồn tại | AUTO-DETECT → accelerate Gates 1, 1.5, 2, 3 |
+| `.kiro/specs` + `docs/specs` cùng tồn tại | Ưu tiên `.kiro/specs`, cảnh báo potential conflict |
+| `.kiro/specs` chỉ có 1 module folder | Pass Gate 1, SKIP Gate 1.5 (single module) |
+| `.kiro/specs/<module>/tasks.md` format lạ | Parse best-effort, fallback tạo tasks thủ công |
 
 ---
 
-*orchestrator v2.0 — Autonomous State Machine Gatekeeper for AWKit*
+*orchestrator v2.3 — Autonomous State Machine Gatekeeper for AWKit (Kiro Spec Integration)*