@leejungkiin/awkit 1.3.7 → 1.4.0

package/skills/orchestrator/SKILL.md

@@ -1,498 +1,58 @@
 ---
 name: orchestrator
-description: >-
-  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.3"
-  replaces: "2.2"
-  tags: [orchestrator, routing, gate, triage, state-machine, core, kiro]
-agent: Orchestrator
-trigger: always
-invocation-type: auto
-priority: 0
+description: Intelligent dispatcher — analyzes context and delegates to the right skill or workflow
 ---
 
-# Orchestrator v2.3 — Autonomous State Machine Gatekeeper
+# Orchestrator Skill
 
-> **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.
+## Purpose
+Route user requests to the correct workflow or skill based on context analysis.
 
----
-
-## ⚡ Core Principle
-
-```
-AI LÀ NGƯỜI GIÁM SÁT "CÁN CÂN" CỦA DỰ ÁN.
-- User không cần nhớ workflow nào để gọi
-- AI tự detect thiếu spec → tự hỏi
-- AI tự detect thiếu design → tự phác thảo
-- AI tự detect thiếu tickets → tự tạo
-- Chỉ cho phép code khi TẤT CẢ prerequisites thỏa mãn
-```
-
-### 6 Decision Principles (Auto-decide khi không cần hỏi user)
-
-```
-1. Complete > Shortcuts    — AI cost rẻ. Implement đủ, kể cả edge cases.
-2. Evidence > Assumptions  — Dựa trên data thực tế, không đoán.
-3. Standard > Custom       — Ưu tiên thư viện/pattern có sẵn.
-4. Explicit > Implicit     — Code rõ ràng, không clever tricks.
-5. Test > Trust            — Viết test, không "chắc chắn đúng".
-6. Small > Big             — Incremental changes, không big-bang.
-```
-
----
-
-## 🔍 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.
-
-### Scoring Criteria
-
-```yaml
-factors:
-  persistence_change:  # Thay đổi Database/Storage/Model
-    score: +4
-    signals: ["database", "schema", "table", "collection", "model", "migration", "storage"]
-
-  new_feature:  # Feature hoàn toàn mới
-    score: +3
-    signals: ["tính năng mới", "new feature", "implement", "build", "tạo mới"]
-
-  multi_file:  # Ảnh hưởng nhiều file/module
-    score: +2
-    signals: [">3 files", "cross-module", "refactor lớn", "architecture"]
-
-  api_change:  # Thay đổi API contract
-    score: +2
-    signals: ["API", "endpoint", "request", "response", "contract"]
-
-  ui_only:  # Chỉ thay đổi UI/styling
-    score: +0
-    signals: ["đổi màu", "UI", "layout", "font", "padding", "margin"]
-
-  single_file_fix:  # Sửa 1 file, logic nhỏ
-    score: +0
-    signals: ["fix typo", "sửa lỗi nhỏ", "update text", "rename"]
-```
-
-### Classification
-
-```
-TRIVIAL  (score 0-2): Bypass ALL gates → Execute trực tiếp
-  Examples: đổi màu nút, sửa typo, thêm log, fix linter, update string
-
-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 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
-
-```
-🔍 TRIAGE: [TRIVIAL|MODERATE|COMPLEX] (score: N/10)
-   Factors: [list detected factors]
-   Gates required: [list gates]
-```
-
----
-
-## 🚦 STEP 2: Gate State Check (Cho COMPLEX tasks)
-
-Sau khi triage = COMPLEX, orchestrator kiểm tra **tuần tự** từng Gate.
-Dừng tại Gate ĐẦU TIÊN chưa thỏa mãn.
-
-### Gate 1: Spec Clarification 🔴
-
-```
-CHECK: Tồn tại file mô tả 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:
-  - .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 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?
-  → 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:
-  - .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ế 
-     Database và API trước khi code, tránh phải sửa đi sửa lại sau nhé."
-  → 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 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?
-  → 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 (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
-  → Sau khi confirm → Proceed Gate 4
-```
-
-### Gate 4: Execution 🟢
-
-```
-CHECK: Có ticket đang In Progress?
-  → symphony_available_tasks(filter="in_progress")
-
-🔍 SEARCH BEFORE BUILDING (BẮT BUỘC trước khi viết code mới):
-  Layer 0 — Structural (GitNexus, CHỈ khi .gitnexus/ tồn tại):
-    → gitnexus_impact: Check blast radius của symbol cần sửa
-    → gitnexus_context: Xem 360° callers/callees trước khi code
-    → gitnexus_query: Tìm execution flows liên quan
-  Layer 1 — Tried-and-True:
-    → nmem_recall: Tìm similar problems đã giải quyết trong brain
-    → grep_search: Tìm existing utils/patterns trong codebase
-  Layer 2 — New-and-Popular:
-    → Tìm thư viện/SDK chuẩn ngành cho problem này
-    → Ưu tiên well-maintained, community-backed solutions
-  Layer 3 — First-Principles:
-    → CHỈ build from scratch khi Layer 1+2 không có solution phù hợp
-    → Ghi lý do tại sao existing solutions không đáp ứng
-
-  ⚠️ KHÔNG được skip layers! Log kết quả search vào progress report.
-
-ACTION:
-  → Nếu chưa có → Claim task tiếp theo: symphony_claim_task
-  → Code THEO TICKET, THEO DESIGN DOC, THEO search results
-  → Nếu phát hiện cần sửa schema khác design → ⛔ DỪNG:
-    "Schema change ngoài approved design detected. 
-     Quay lại Gate 2 để cập nhật design doc."
-  → Complete ticket → symphony_complete_task
-```
-
-### Gate 5: Verification 🔵
-
-```
-ACTION: Auto-trigger sau mỗi Gate 4 completion
-  → verification-gate skill (evidence before claims)
-  → Boil-the-Lake checklist (completeness check)
-  → code-review skill (nếu task phức tạp)
-  → Đối chiếu: code thực tế vs design doc
-  → OK → Task done → Auto-Next (TP4 in symphony-enforcer)
-```
-
----
-
-## 🔀 STEP 3: Slash Command Detection (Giữ lại)
-
-Nếu user dùng slash command rõ ràng → Load workflow file trực tiếp, SKIP triage.
+## Routing Logic
 
+### 1. Slash Command Detection
 ```
 User input starts with `/` → Load workflow file directly
   /plan     → workflows/lifecycle/plan.md
   /code     → workflows/lifecycle/code.md
   /debug    → workflows/lifecycle/debug.md
-  /brainstorm → brainstorm-agent skill
-  ...etc (see GEMINI.md)
+  ...etc (see GEMINI.md § 2)
 ```
 
-> **Note:** Slash commands bypass triage vì user ĐÃ BIẾT mình cần gì.
-
----
-
-## 🧠 STEP 4: Intent Detection (Fallback)
-
-Nếu KHÔNG phải slash command VÀ triage chưa rõ:
-
+### 2. Intent Detection (No slash command)
 ```yaml
 code_intent:
-  keywords: ["implement", "build", "create", "add", "code", "fix", "viết", "tạo", "làm"]
-  action: Run triage → route theo complexity
+  keywords: ["implement", "build", "create", "add", "code", "fix", "viết", "tạo"]
+  action: Suggest `/code` or `/codeExpert`
 
 debug_intent:
-  keywords: ["error", "bug", "crash", "fix", "lỗi", "sửa", "fail", "broken"]
-  action: systematic-debugging skill (bypass spec gates — debugging is reactive)
+  keywords: ["error", "bug", "crash", "fix", "lỗi", "sửa", "fail"]
+  action: Suggest `/debug` or `/debugExpert`
 
 plan_intent:
   keywords: ["plan", "design", "architect", "how to", "strategy", "thiết kế"]
-  action: Suggest Gate 1-2 flow
-
-brainstorm_intent:
-  keywords: ["brainstorm", "ý tưởng", "idea", "nên làm gì", "what should"]
-  action: brainstorm-agent skill
+  action: Suggest `/plan` or `/planExpert`
 
 context_intent:
   keywords: ["remember", "save", "continue", "where was I", "nhớ", "tiếp"]
-  action: Suggest /recap or /save-brain
-
-refactor_intent:
-  keywords: ["refactor", "rename", "extract", "split", "move", "restructure", "blast radius", "impact"]
-  action: gitnexus-intelligence skill (impact analysis + safe refactoring)
-```
-
----
-
-## 🗣️ Communication Style
-
-Orchestrator KHÔNG nói giọng máy móc. Dùng giọng đồng nghiệp senior:
+  action: Suggest `/recap` or `/save-brain`
 
+ads_intent:
+  keywords: ["ads", "campaign", "CPI", "ROAS", "quảng cáo"]
+  action: Suggest `/ads-audit` or `/adsExpert`
 ```
-❌ "ERROR: Gate 1 not satisfied. Spec document missing."
-✅ "Ý tưởng rất hay! Kinh nghiệm cho thấy nếu không chốt yêu cầu trước, 
-    sau sửa cực lắm. Để tôi hỏi vài câu rồi mình chốt spec nhé?"
-
-❌ "Gate 2 failed. Architecture document required."  
-✅ "Đã hiểu yêu cầu rồi. Giờ để tôi phác thảo cấu trúc database 
-    cho anh xem trước — tránh kiểu vừa làm vừa đập đi xây lại."
 
-❌ "Execution blocked. No Symphony task found."
-✅ "Design ngon rồi! Giờ tôi bẻ ra thành 5 task nhỏ trên Symphony 
-    để track tiến độ nhé."
+### 3. Skill Pack Check
 ```
-
----
-
-## 🚫 Anti-Patterns
-
-```yaml
-never_do:
-  - Cho phép code COMPLEX task mà chưa qua Gate 1-2
-  - Tự ý thêm cột DB ngoài approved design
-  - Hỏi "Bạn muốn chạy workflow nào?" — AI phải TỰ QUYẾT
-  - Tạo Symphony tickets trước khi có design doc (Gate 3 cần Gate 2)
-  - Force user qua 5 Gates cho trivial tasks
-  - Code mới mà chưa search existing solution (Search Before Building)
-  - Đồng ý approach có vấn đề mà không push back (Anti-sycophancy)
-  - Skip edge cases / error handling vì "trivial" (Boil the Lake)
-
-always_do:
-  - Hiển thị triage result trước mọi action
-  - Thông báo đang ở Gate nào khi chặn
-  - Giữ giọng thân thiện, giải thích LÝ DO chặn
-  - Cho phép user override gate: "skip gates" hoặc "bỏ qua"
-  - Re-check gates sau mỗi lần user provide input
-  - Search NeuralMemory + codebase TRƯỚC khi code mới
-  - Report DONE_WITH_CONCERNS nếu có caveats (Completion Status)
-  - Escalate sau 3 failed attempts (3-Strike Rule)
+If user request involves iOS-specific → Check if mobile-ios pack enabled
+If not enabled → Suggest: "awf enable-pack mobile-ios"
 ```
 
----
-
-## 🔗 Skill Relationships
-
+### 4. Fallback
 ```
-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
-
-WORKS WITH:
-  nm-memory-sync (đọc context từ NeuralMemory)
-  awf-session-restore (restore state)
-  symphony-orchestrator (đảm bảo Symphony server running)
-  gitnexus-intelligence (architectural awareness trước khi code)
-
-DOES NOT:
-  Execute code trực tiếp (delegates to workflows)
-  Modify files (chỉ route + enforce gates)
+No match → Ask clarifying question (max 2 times)
+Still unclear → Suggest `/help`
 ```
 
----
-
-## 🧩 Edge Cases
-
-| Tình huống | Xử lý |
-|-----------|--------|
-| User nói "skip gates" / "bỏ qua" | Cho phép bypass, ghi cảnh báo |
-| Feature đã có partial spec | Gate 1 pass, check Gate 2 |
-| Debug request | Bypass spec gates — debugging is reactive |
-| User follow-up nhỏ sau feature done | Re-triage — thường TRIVIAL |
-| 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.3 — Autonomous State Machine Gatekeeper for AWKit (Kiro Spec Integration)*
+## Auto-Activation
+This skill is always active. It runs as the first layer before any other processing.

package/skills/ship-to-code/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: ship-to-code
+description: >-
+  Universal Code Porting & Migration Specialist. Translates legacy or reference code
+  from ANY source language/framework to ANY target language/framework.
+  Rebuilds the architecture while adhering to the target's modern best practices.
+author: Antigravity Team
+version: 1.0.0
+trigger: conditional
+activation_keywords:
+  - "/ship-to-code"
+  - "/port-code"
+  - "/migrate-code"
+  - "port code"
+  - "chuyển ngôn ngữ"
+  - "ship to code"
+  - "dịch code"
+priority: high
+platform: agnostic
+---
+
+# 🚢 Ship-to-Code Skill
+
+> **Purpose:** Transform reference codebase from ANY source language/framework to ANY modern target language/framework.
+> **Philosophy:** "Read source to understand WHAT and WHY → Write target for HOW."
+
+---
+
+## ⚠️ SCOPE CLARITY
+
+| This skill DOES | This skill DOES NOT |
+|-----------------|---------------------|
+| Read & analyze source language code & structure | Write in the obsolete/source language |
+| Rebuild logic idiomatically in modern target language | Blindly translate line-by-line (syntax-only) |
+| Map source dependencies to target equivalents | Auto-migrate production database records directly |
+| Implement Clean Architecture/Modern patterns in target | Just copy-paste without adapting paradigms |
+| Extract/convert needed resources on-demand | Mass-copy entire resource folders blindly |
+
+---
+
+## 🎯 ROLE DEFINITION
+
+When this skill is active, the agent becomes:
+
+> **Expert Multi-Language Porting Architect**
+> - Master at deciphering unfamiliar, foreign or legacy codebases.
+> - Fluent in modern target architectures (Clean Architecture / MVC / MVVM / Hexagonal depending on target ecosystem).
+> - Knows how to map business logic across different language paradigms (e.g., Object-Oriented to Functional, Sync to Async, etc).
+> - Enforces exact Input/Output mathematical parity for core algorithms and cryptology.
+
+---
+
+## 📋 EXECUTION PIPELINE (6 Phases)
+
+> **Rule:** Always complete one phase fully before moving to the next.
+> **Rule:** After each phase, create a checkpoint summary for the user to approve.
+
+### Phase 0: Ecosystem & Dependency Mapping 🔍
+**Purpose:** Identify all 3rd-party libraries, SDKs, and frameworks in the source project and map them to the best modern equivalents in the target ecosystem.
+1. Scan source project configuration files (`package.json`, `build.gradle`, `requirements.txt`, `Cargo.toml`, `go.mod`, etc.).
+2. Generate a Library Detection Report featuring a **Matrix (Source Lib → Target Lib)**.
+3. Present to the user for evaluation and approval.
+
+### Phase 1: Architecture Design & Project Bootstrap 📄
+**Purpose:** Analyze application entry points, metadata, lifecycle, and propose a robust target directory structure.
+1. Identify how the app starts, handles authentication, routes traffic, and loads plugins.
+2. Propose a modern project folder layout aligned with target language standards (e.g., standard Go layout, feature-first React layout, Clean Architecture for Mobile).
+3. Scaffold initial configuration files for the target language.
+
+### Phase 2: Data & Domain Layer Reconstruction 💾
+**Purpose:** Rebuild strict data contracts and persistence infrastructure.
+1. Convert source models/POJOs/Entities into target native DTOs, interfaces, structs, or dataclasses (e.g., implementing `.fromJson()`, `Codable`, `serde`).
+2. Port Database schemas/ORMs to target paradigms (e.g., translating SQLAlchemy to Prisma, Room to SwiftData).
+3. Migrate API clients using target's native concurrency mechanisms (Coroutines, `async/await`, Goroutines).
+
+### Phase 3: Core Business Logic & Utils 🧮
+**Purpose:** Port specialized algorithms, encryption, math, and custom helpers.
+1. Translate raw logic with strict adherence to the exact mathematical and state behavior of the source.
+2. Provide **Unit Tests** in the target language to prove 100% computational parity with source output (especially for Base64, MD5/SHA, AES, timezone parsing).
+
+### Phase 4: UI & Presentation / Controller Layer 🎨
+**Purpose:** Rebuild user interfaces or API controllers utilizing the target's standard frameworks.
+1. Map source UI components to target equivalents (e.g., React to Compose, HTML/Jinja to Vue, Android XML to SwiftUI).
+2. For backend APIs: Convert source controller route handling to modern target framework routing (e.g., Express.js to FastAPI, Spring Boot to Go Gin).
+3. Implement modern state management and reactive data flows native to the new ecosystem.
+
+### Phase 5: SDK Integration & Parity Quality Gate ✅
+**Purpose:** Finalize third-party setups and ensure feature completeness.
+1. Wire up heavy SDKs (Auth, Analytics, Push Notifications, Payment gateways) with target SDKs.
+2. Perform rigorous Parity Validation across:
+   - *Branch Coverage:* Ensure all `if/switch` edge cases from source were ported.
+   - *Endpoint Parity:* Ensure headers, bodies, status codes match output.
+   - *Visual Parity:* (If UI) Layout behaves correctly.
+
+---
+
+## 🚫 ANTI-PATTERNS
+
+```yaml
+never_do:
+  - Line-by-line verbatim syntax translation (e.g., writing Java code in Go syntax using 'for' instead of 'range', or ignoring Swift optionals to force unwrap like in C#).
+  - Use deprecated patterns in the target ecosystem just because the source used them.
+  - Skip extracting business rules before writing the target implementation.
+  - Alter encryption hashes / outputs — they must match the original exactly for server compatibility!
+  
+always_do:
+  - Write Idiomatic Code: Fully embrace the target language's design patterns, conventions, and error-handling features.
+  - Checkpoint and halt after generating the Ecosystem Dependency Matrix to let the user review framework choices.
+  - Build test suites to verify math and crypto translations against known source outputs.
+```
+
+---
+
+*ship-to-code v1.0.0 — Universal Code Porting Skill*
+*Created by Antigravity Team*