@leejungkiin/awkit 1.3.8 → 1.4.0

package/skills/gitnexus/gitnexus-exploring/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: gitnexus-exploring
+description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\""
+---
+
+# Exploring Codebases with GitNexus
+
+## When to Use
+
+- "How does authentication work?"
+- "What's the project structure?"
+- "Show me the main components"
+- "Where is the database logic?"
+- Understanding code you haven't seen before
+
+## Workflow
+
+```
+1. READ gitnexus://repos                          → Discover indexed repos
+2. READ gitnexus://repo/{name}/context             → Codebase overview, check staleness
+3. gitnexus_query({query: "<what you want to understand>"})  → Find related execution flows
+4. gitnexus_context({name: "<symbol>"})            → Deep dive on specific symbol
+5. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
+```
+
+> If step 2 says "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklist
+
+```
+- [ ] READ gitnexus://repo/{name}/context
+- [ ] gitnexus_query for the concept you want to understand
+- [ ] Review returned processes (execution flows)
+- [ ] gitnexus_context on key symbols for callers/callees
+- [ ] READ process resource for full execution traces
+- [ ] Read source files for implementation details
+```
+
+## Resources
+
+| Resource                                | What you get                                            |
+| --------------------------------------- | ------------------------------------------------------- |
+| `gitnexus://repo/{name}/context`        | Stats, staleness warning (~150 tokens)                  |
+| `gitnexus://repo/{name}/clusters`       | All functional areas with cohesion scores (~300 tokens) |
+| `gitnexus://repo/{name}/cluster/{name}` | Area members with file paths (~500 tokens)              |
+| `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens)              |
+
+## Tools
+
+**gitnexus_query** — find execution flows related to a concept:
+
+```
+gitnexus_query({query: "payment processing"})
+→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
+→ Symbols grouped by flow with file locations
+```
+
+**gitnexus_context** — 360-degree view of a symbol:
+
+```
+gitnexus_context({name: "validateUser"})
+→ Incoming calls: loginHandler, apiMiddleware
+→ Outgoing calls: checkToken, getUserById
+→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
+```
+
+## Example: "How does payment processing work?"
+
+```
+1. READ gitnexus://repo/my-app/context       → 918 symbols, 45 processes
+2. gitnexus_query({query: "payment processing"})
+   → CheckoutFlow: processPayment → validateCard → chargeStripe
+   → RefundFlow: initiateRefund → calculateRefund → processRefund
+3. gitnexus_context({name: "processPayment"})
+   → Incoming: checkoutHandler, webhookHandler
+   → Outgoing: validateCard, chargeStripe, saveTransaction
+4. Read src/payments/processor.ts for implementation details
+```

package/skills/gitnexus/gitnexus-guide/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: gitnexus-guide
+description: "Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: \"What GitNexus tools are available?\", \"How do I use GitNexus?\""
+---
+
+# GitNexus Guide
+
+Quick reference for all GitNexus MCP tools, resources, and the knowledge graph schema.
+
+## Always Start Here
+
+For any task involving code understanding, debugging, impact analysis, or refactoring:
+
+1. **Read `gitnexus://repo/{name}/context`** — codebase overview + check index freshness
+2. **Match your task to a skill below** and **read that skill file**
+3. **Follow the skill's workflow and checklist**
+
+> If step 1 warns the index is stale, run `npx gitnexus analyze` in the terminal first.
+
+## Skills
+
+| Task                                         | Skill to read       |
+| -------------------------------------------- | ------------------- |
+| Understand architecture / "How does X work?" | `gitnexus-exploring`         |
+| Blast radius / "What breaks if I change X?"  | `gitnexus-impact-analysis`   |
+| Trace bugs / "Why is X failing?"             | `gitnexus-debugging`         |
+| Rename / extract / split / refactor          | `gitnexus-refactoring`       |
+| Tools, resources, schema reference           | `gitnexus-guide` (this file) |
+| Index, status, clean, wiki CLI commands      | `gitnexus-cli`               |
+
+## Tools Reference
+
+| Tool             | What it gives you                                                        |
+| ---------------- | ------------------------------------------------------------------------ |
+| `query`          | Process-grouped code intelligence — execution flows related to a concept |
+| `context`        | 360-degree symbol view — categorized refs, processes it participates in  |
+| `impact`         | Symbol blast radius — what breaks at depth 1/2/3 with confidence         |
+| `detect_changes` | Git-diff impact — what do your current changes affect                    |
+| `rename`         | Multi-file coordinated rename with confidence-tagged edits               |
+| `cypher`         | Raw graph queries (read `gitnexus://repo/{name}/schema` first)           |
+| `list_repos`     | Discover indexed repos                                                   |
+
+## Resources Reference
+
+Lightweight reads (~100-500 tokens) for navigation:
+
+| Resource                                       | Content                                   |
+| ---------------------------------------------- | ----------------------------------------- |
+| `gitnexus://repo/{name}/context`               | Stats, staleness check                    |
+| `gitnexus://repo/{name}/clusters`              | All functional areas with cohesion scores |
+| `gitnexus://repo/{name}/cluster/{clusterName}` | Area members                              |
+| `gitnexus://repo/{name}/processes`             | All execution flows                       |
+| `gitnexus://repo/{name}/process/{processName}` | Step-by-step trace                        |
+| `gitnexus://repo/{name}/schema`                | Graph schema for Cypher                   |
+
+## Graph Schema
+
+**Nodes:** File, Function, Class, Interface, Method, Community, Process
+**Edges (via CodeRelation.type):** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
+
+```cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
+RETURN caller.name, caller.filePath
+```

package/skills/gitnexus/gitnexus-impact-analysis/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: gitnexus-impact-analysis
+description: "Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: \"Is it safe to change X?\", \"What depends on this?\", \"What will break?\""
+---
+
+# Impact Analysis with GitNexus
+
+## When to Use
+
+- "Is it safe to change this function?"
+- "What will break if I modify X?"
+- "Show me the blast radius"
+- "Who uses this code?"
+- Before making non-trivial code changes
+- Before committing — to understand what your changes affect
+
+## Workflow
+
+```
+1. gitnexus_impact({target: "X", direction: "upstream"})  → What depends on this
+2. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
+3. gitnexus_detect_changes()                               → Map current git changes to affected flows
+4. Assess risk and report to user
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklist
+
+```
+- [ ] gitnexus_impact({target, direction: "upstream"}) to find dependents
+- [ ] Review d=1 items first (these WILL BREAK)
+- [ ] Check high-confidence (>0.8) dependencies
+- [ ] READ processes to check affected execution flows
+- [ ] gitnexus_detect_changes() for pre-commit check
+- [ ] Assess risk level and report to user
+```
+
+## Understanding Output
+
+| Depth | Risk Level       | Meaning                  |
+| ----- | ---------------- | ------------------------ |
+| d=1   | **WILL BREAK**   | Direct callers/importers |
+| d=2   | LIKELY AFFECTED  | Indirect dependencies    |
+| d=3   | MAY NEED TESTING | Transitive effects       |
+
+## Risk Assessment
+
+| Affected                       | Risk     |
+| ------------------------------ | -------- |
+| <5 symbols, few processes      | LOW      |
+| 5-15 symbols, 2-5 processes    | MEDIUM   |
+| >15 symbols or many processes  | HIGH     |
+| Critical path (auth, payments) | CRITICAL |
+
+## Tools
+
+**gitnexus_impact** — the primary tool for symbol blast radius:
+
+```
+gitnexus_impact({
+  target: "validateUser",
+  direction: "upstream",
+  minConfidence: 0.8,
+  maxDepth: 3
+})
+
+→ d=1 (WILL BREAK):
+  - loginHandler (src/auth/login.ts:42) [CALLS, 100%]
+  - apiMiddleware (src/api/middleware.ts:15) [CALLS, 100%]
+
+→ d=2 (LIKELY AFFECTED):
+  - authRouter (src/routes/auth.ts:22) [CALLS, 95%]
+```
+
+**gitnexus_detect_changes** — git-diff based impact analysis:
+
+```
+gitnexus_detect_changes({scope: "staged"})
+
+→ Changed: 5 symbols in 3 files
+→ Affected: LoginFlow, TokenRefresh, APIMiddlewarePipeline
+→ Risk: MEDIUM
+```
+
+## Example: "What breaks if I change validateUser?"
+
+```
+1. gitnexus_impact({target: "validateUser", direction: "upstream"})
+   → d=1: loginHandler, apiMiddleware (WILL BREAK)
+   → d=2: authRouter, sessionManager (LIKELY AFFECTED)
+
+2. READ gitnexus://repo/my-app/processes
+   → LoginFlow and TokenRefresh touch validateUser
+
+3. Risk: 2 direct callers, 2 processes = MEDIUM
+```

package/skills/gitnexus/gitnexus-refactoring/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: gitnexus-refactoring
+description: "Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: \"Rename this function\", \"Extract this into a module\", \"Refactor this class\", \"Move this to a separate file\""
+---
+
+# Refactoring with GitNexus
+
+## When to Use
+
+- "Rename this function safely"
+- "Extract this into a module"
+- "Split this service"
+- "Move this to a new file"
+- Any task involving renaming, extracting, splitting, or restructuring code
+
+## Workflow
+
+```
+1. gitnexus_impact({target: "X", direction: "upstream"})  → Map all dependents
+2. gitnexus_query({query: "X"})                            → Find execution flows involving X
+3. gitnexus_context({name: "X"})                           → See all incoming/outgoing refs
+4. Plan update order: interfaces → implementations → callers → tests
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklists
+
+### Rename Symbol
+
+```
+- [ ] gitnexus_rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits
+- [ ] Review graph edits (high confidence) and ast_search edits (review carefully)
+- [ ] If satisfied: gitnexus_rename({..., dry_run: false}) — apply edits
+- [ ] gitnexus_detect_changes() — verify only expected files changed
+- [ ] Run tests for affected processes
+```
+
+### Extract Module
+
+```
+- [ ] gitnexus_context({name: target}) — see all incoming/outgoing refs
+- [ ] gitnexus_impact({target, direction: "upstream"}) — find all external callers
+- [ ] Define new module interface
+- [ ] Extract code, update imports
+- [ ] gitnexus_detect_changes() — verify affected scope
+- [ ] Run tests for affected processes
+```
+
+### Split Function/Service
+
+```
+- [ ] gitnexus_context({name: target}) — understand all callees
+- [ ] Group callees by responsibility
+- [ ] gitnexus_impact({target, direction: "upstream"}) — map callers to update
+- [ ] Create new functions/services
+- [ ] Update callers
+- [ ] gitnexus_detect_changes() — verify affected scope
+- [ ] Run tests for affected processes
+```
+
+## Tools
+
+**gitnexus_rename** — automated multi-file rename:
+
+```
+gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
+→ 12 edits across 8 files
+→ 10 graph edits (high confidence), 2 ast_search edits (review)
+→ Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}]
+```
+
+**gitnexus_impact** — map all dependents first:
+
+```
+gitnexus_impact({target: "validateUser", direction: "upstream"})
+→ d=1: loginHandler, apiMiddleware, testUtils
+→ Affected Processes: LoginFlow, TokenRefresh
+```
+
+**gitnexus_detect_changes** — verify your changes after refactoring:
+
+```
+gitnexus_detect_changes({scope: "all"})
+→ Changed: 8 files, 12 symbols
+→ Affected processes: LoginFlow, TokenRefresh
+→ Risk: MEDIUM
+```
+
+**gitnexus_cypher** — custom reference queries:
+
+```cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
+RETURN caller.name, caller.filePath ORDER BY caller.filePath
+```
+
+## Risk Rules
+
+| Risk Factor         | Mitigation                                |
+| ------------------- | ----------------------------------------- |
+| Many callers (>5)   | Use gitnexus_rename for automated updates |
+| Cross-area refs     | Use detect_changes after to verify scope  |
+| String/dynamic refs | gitnexus_query to find them               |
+| External/public API | Version and deprecate properly            |
+
+## Example: Rename `validateUser` to `authenticateUser`
+
+```
+1. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
+   → 12 edits: 10 graph (safe), 2 ast_search (review)
+   → Files: validator.ts, login.ts, middleware.ts, config.json...
+
+2. Review ast_search edits (config.json: dynamic reference!)
+
+3. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
+   → Applied 12 edits across 8 files
+
+4. gitnexus_detect_changes({scope: "all"})
+   → Affected: LoginFlow, TokenRefresh
+   → Risk: MEDIUM — run tests for these flows
+```

package/skills/nm-memory-sync/SKILL.md

@@ -165,9 +165,22 @@ This surfaces memories that a keyword search would miss.
 
 ---
 
+## Auto-Install Protocol (New Machine)
+
+If `nmem` CLI is not available:
+```
+1. AI detects: command not found: nmem
+2. AI auto-runs: pip install neural-memory (or python3 -m pip install neural-memory)
+   → Requires Python >= 3.11
+3. After install: nmem init (initialize brain DB)
+4. Verify: nmem --version
+5. If Python < 3.11 or pip fails:
+   → Show user: "⚠️ NeuralMemory requires Python >= 3.11. Install via: brew install python@3.12"
+```
+
 ## Fallback Mode (NeuralMemory Not Installed)
 
-If `nmem` is not available, falls back to flat-file behavior:
+If `nmem` is not available AND auto-install fails, falls back to flat-file behavior:
 ```
 - Reads from brain/decisions/, brain/solutions/
 - Keyword overlap matching (legacy behavior)

package/skills/orchestrator/SKILL.md

@@ -48,44 +48,6 @@ If user request involves iOS-specific → Check if mobile-ios pack enabled
 If not enabled → Suggest: "awf enable-pack mobile-ios"
 ```
 
-### 3.5. Gate 4 Three-Phase Routing (v12.3 — AUTO-ENFORCE)
-
-> ⚠️ AI PHẢI CHỦ ĐỘNG kích hoạt — KHÔNG chờ user gọi.
-> Khi detect COMPLEX + UI → TỰ ĐỘNG announce Phase Announcement Block.
-
-```yaml
-gate4_triage:
-  trigger: After Gate 3 (tasks created), before execution begins
-  auto_activate: true  # AI proactively triggers, no user command needed
-  
-  complex_with_ui:
-    condition: complexity == COMPLEX AND task has UI components
-    action: Enforce Three-Phase Execution
-    phases:
-      - Phase A: Infrastructure (dependencies, DI, navigation skeleton)
-        → Must build successfully before Phase B
-      - Phase B: UI Shell (all screens with mock data)
-        → TRIGGER TP1.7: User Test Checkpoint (MANDATORY)
-        → User must confirm UI OK before Phase C
-      - Phase C: Logic Integration (per feature)
-        → TRIGGER TP1.7: after each feature (batch small ones)
-    task_ordering: UI tasks MUST be grouped before logic tasks in Symphony
-  
-  moderate_with_ui:
-    condition: complexity == MODERATE AND task has UI components
-    action: Phase A+C merged, Phase B optional (recommend for hardware features)
-  
-  trivial_or_backend:
-    condition: complexity == TRIVIAL OR no UI components
-    action: Skip phases, code straight through (no checkpoints)
-  
-  detect_ui_components:
-    signals:
-      - Task mentions: screen, view, layout, UI, button, form, navigation
-      - Files include: *.xml (Android), *.swift (iOS views), *.compose, *.tsx
-      - Spec references: wireframe, mockup, design, screenshot
-```
-
 ### 4. Fallback
 ```
 No match → Ask clarifying question (max 2 times)

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*