@leejungkiin/awkit 1.4.2 → 1.5.0

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

@@ -8,7 +8,7 @@ description: >-
   Hỗ trợ auto-detect .kiro/specs modules để bypass khi IDE đã tạo specs.
 metadata:
   stage: core
-  version: "1.1"
+  version: "1.2"
   tags: [gate, spec, module, product-spec, documentation, core, kiro]
   requires: orchestrator
 agent: Spec Writer
@@ -21,22 +21,12 @@ activation_keywords:
   - "screen inventory"
   - "feature spec"
   - "product spec"
-  - "mô tả app"
-  - "document modules"
 ---
 
-# Module Spec Writer v1.0 — Gate 1.5: Product Specification
+# Module Spec Writer v1.2 — Gate 1.5: Product Specification (Router)
 
-> **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"
-
----
+> **Purpose:** Tạo tài liệu product-level cho từng module (screens, flows, rules)
+> TRƯỚC KHI thiết kế kỹ thuật. Đảm bảo shared understanding "app làm gì".
 
 ## ⚠️ SCOPE CLARITY
 
@@ -45,39 +35,31 @@ activation_keywords:
 | 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 |
-
----
+| Scan existing codebase để auto-generate spec | Brainstorm ý tưởng (việc của brainstorm-agent) |
 
-## 🚀 ACTIVATION
+## 📋 Topic Index — Load deep dives as needed
 
-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"
+| Topic | Khi nào load | File |
+|-------|-------------|------|
+| Module Spec Template | Khi viết spec cho 1 module | `templates/module-spec-template.md` |
+| Port/Migration Mode | Khi port iOS↔Android hoặc có .kiro/specs | `examples/port-migration-mode.md` |
 
-### Khi nào Gate 1.5 MANDATORY:
+## 🚀 ACTIVATION
 
 ```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"
-  - kiro_specs: .kiro/specs/ chứa ≥2 module folders với requirements.md
+  - kiro_specs: .kiro/specs/ chứa ≥2 module folders
     → AUTO-SKIP: "Kiro module specs detected. Gate 1.5 AUTO-PASS."
-    → Load .kiro/specs/<module>/requirements.md làm module specs
-    → Chuyển thẳng Gate 2
 ```
 
----
-
 ## 📋 INPUT REQUIREMENTS
 
 ```
@@ -87,373 +69,64 @@ REQUIRED:
   → .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)
+  → CODEBASE.md, KnowledgeItems, NeuralMemory context
 ```
 
----
-
-## 🔄 PROCESS
+## 🔄 PROCESS (6 Phases)
 
 ### Phase 1: Module Discovery
-
-```
-INPUT SOURCE DETECTION (theo thứ tự ưu tiên):
-
-  🔍 KIRO CHECK (HIGHEST PRIORITY):
-  A0) Scan .kiro/specs/ folder:
-      - Nếu tồn tại ≥2 module folders (mỗi folder có requirements.md):
-        → AUTO-PASS Gate 1.5
-        → Load từng .kiro/specs/<module>/requirements.md làm module spec
-        → Thông báo:
-          "🔍 Phát hiện .kiro/specs/ với [N] module specs từ IDE Kiro.
-             Modules: [list module names]
-             Gate 1.5 AUTO-PASS. Chuyển thẳng Gate 2 (Architecture)."
-        → SKIP Phase 2-6, không cần user approve (Kiro đã chốt)
-        → Lưu vào NeuralMemory: "Kiro module specs loaded: <list>"
-      - Nếu không có → tiếp tục các check bình thường bên dưới
-
-  FALLBACK SOURCES:
-  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é."
-```
+- Kiro check first (.kiro/specs/ → AUTO-PASS nếu ≥2 modules)
+- Fallback: BRIEF.md → extract modules | Scan source code (port)
+- Present danh sách modules → user confirm
 
 ### 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?
-```
+- Gather context (BRIEF, source code, KI, NeuralMemory)
+- Generate spec theo template → `templates/module-spec-template.md`
+- Self-review checklist: screens đủ? flows rõ? edge cases?
 
 ### 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?
-```
+- Dependency graph (circular? missing cross-refs?)
+- Shared concepts consistent?
+- Coverage vs BRIEF.md / source code
 
 ### Phase 4: Multi-Role Review (AI Simulated)
-
-```
-Trước khi gửi bản thảo cho user, AI BẮT BUỘC đóng vai 6 vai trò sau để review chéo:
-1. Tech Lead: Tính khả thi kỹ thuật? Có edge cases nào chưa cover?
-2. PM: Có phục vụ đúng mục tiêu kinh doanh? Scope creep?
-3. UX Designer: Flow có mượt không? Quá nhiều bước? Có nghĩ đến empty states/error states?
-4. QA Engineer: Acceptance Criteria đã test được chưa (SMART)? Có đủ rõ ràng?
-5. Security/Privacy: Có rò rỉ PII? Có checklist GDPR chưa (riêng đối với data y tế)?
-6. DevOps: Có cản trở CI/CD hoặc scaling không?
-```
+6 roles: Tech Lead, PM, UX Designer, QA, Security, DevOps
 
 ### Phase 5: 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).
-────────────────────────────────────
-```
+Show summary table → user review → approve
 
 ### Phase 6: 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:
-
-  🔍 KIRO-FIRST CHECK (luôn chạy trước):
-  0. Scan .kiro/specs/ → nếu có module folders với requirements.md:
-     → Dùng Kiro specs làm source of truth
-     → SKIP source code scanning (Kiro đã tổng hợp)
-     → Cross-reference với source code CHỈ để verify completeness
-
-  FALLBACK (khi không có .kiro/specs):
-  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
-
-  Kiro:
-    → .kiro/specs/<module>/requirements.md (pre-generated)
-    → .kiro/specs/<module>/design.md (pre-generated)
-    → .kiro/specs/<module>/tasks.md (pre-generated)
-
-OUTPUT: Pre-filled module specs with data from source code OR Kiro specs
-  → 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."
-```
-
----
+- Write to `docs/specs/modules/<module-name>_spec.md`
+- Create `MODULE_INDEX.md`
+- Tag NeuralMemory → proceed to Gate 2
 
 ## 🚫 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?")
+  - Viết spec quá vắn tắt (< 5 screens → cảnh báo)
   - 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
+  - Bắt đầu Gate 2 khi còn "Draft"
 
 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
+  - Show module list cho user confirm TRƯỚC
+  - Cross-module consistency check SAU khi viết hết
+  - Acceptance criteria phải testable (SMART)
+  - Scan source code khi port/migration
   - 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)
+DEPENDS ON: brainstorm-agent output (Gate 1 must pass)
+FEEDS INTO: spec-gate (Gate 2 reads module specs)
+WORKS WITH: nm-memory-sync, gitnexus-intelligence, KnowledgeItems
 ```
 
 ---
 
-*module-spec-writer v1.1 — Product Specification Gate for AWKit (Kiro Spec Integration)*
+*module-spec-writer v1.2 — Modular Router Architecture*

package/skills/module-spec-writer/examples/port-migration-mode.md

@@ -0,0 +1,40 @@
+# Port/Migration Mode
+
+Khi project là port/migration (iOS→Android, Android→iOS):
+
+## Special Behavior
+
+### Kiro-First Check (luôn chạy trước)
+0. Scan `.kiro/specs/` → nếu có module folders với `requirements.md`:
+   - Dùng Kiro specs làm source of truth
+   - SKIP source code scanning (Kiro đã tổng hợp)
+   - Cross-reference với source code CHỈ để verify completeness
+
+### Fallback (khi không có .kiro/specs)
+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
+
+### Kiro
+- `.kiro/specs/<module>/requirements.md` (pre-generated)
+- `.kiro/specs/<module>/design.md` (pre-generated)
+- `.kiro/specs/<module>/tasks.md` (pre-generated)
+
+## Output
+Pre-filled module specs with data from source code OR Kiro specs.
+User chỉ cần review + approve, không cần viết từ đầu.

package/skills/module-spec-writer/templates/module-spec-template.md

@@ -0,0 +1,118 @@
+# 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]
+```

package/skills/orchestrator/SKILL.md

@@ -42,10 +42,24 @@ ads_intent:
   action: Suggest `/ads-audit` or `/adsExpert`
 ```
 
-### 3. Skill Pack Check
+### 3. Lean Runtime + Skill Pack Check
 ```
-If user request involves iOS-specific → Check if mobile-ios pack enabled
-If not enabled → Suggest: "awf enable-pack mobile-ios"
+Default runtime is intentionally lean. Domain-heavy skills should be enabled on demand.
+
+If user request involves iOS / Swift / Xcode / App Clip / SwiftUI
+  → Suggest: "awkit enable-pack mobile-ios"
+
+If user request involves Android / Kotlin / Compose / AdMob / APK reverse engineering
+  → Suggest: "awkit enable-pack mobile-android"
+
+If user request involves ASO / App Store marketing / ASA / competitor tracking / ratings
+  → Suggest: "awkit enable-pack marketing"
+
+If user request involves sprite generation / LucyLab TTS / short-form video production
+  → Suggest: "awkit enable-pack creator-studio"
+
+If user request involves NeuralMemory audits / intake / evolution workflows
+  → Suggest: "awkit enable-pack neural-memory"
 ```
 
 ### 4. Fallback
@@ -54,10 +68,5 @@ No match → Ask clarifying question (max 2 times)
 Still unclear → Suggest `/help`
 ```
 
-### 5. Post-Action Rules
-```
-Build hoàn tất thành công (không có lỗi) → Tự động chạy git commit.
-```
-
 ## Auto-Activation
 This skill is always active. It runs as the first layer before any other processing.