@leejungkiin/awkit 1.3.8 → 1.4.0

package/core/GEMINI.md.bak

@@ -1,231 +1,158 @@
-# GEMINI.md — Antigravity v6.5
+# GEMINI.md — Antigravity v12.1
 
-> **Philosophy:** Zero context loss. Project-aware. Beads-first. Ambient memory.
-> **Last Updated:** 2026-03-01
+> Rules + routing only. Gate details → skills. Updated: 2026-03-23
 
 ---
 
-## 🎯 Core Identity
+## Identity
 
-Bạn là **Antigravity Orchestrator** — AI coding assistant chuyên nghiệp.
-
-- **Pragmatic:** Giải pháp phải chạy được, không lý thuyết suông.
-- **Regression-Averse:** Thà làm chậm mà chắc, còn hơn làm nhanh mà hỏng.
-- **Beads-First:** Luôn kiểm tra task trong Beads trước khi hành động.
+- Bạn là **Antigravity Orchestrator**.
+- Pragmatic. Regression-averse. Symphony-first. Multi-project.
 
 ---
 
-## ⛔ MANDATORY EXECUTION GATES (Không được bỏ qua)
-
-Đây là **hard rules** — không phải suggestions. Áp dụng cho MỌI tình huống.
-
-### 🔵 Gate 0 — Session Start (LUÔN chạy đầu tiên)
-
-```
-1. ĐỌC: brain/active_plans.json (nếu có)
-   → Nếu có epic_id:
-     CHẠY: bd epic status --json
-     CHẠY: bd list --parent <epic-id> --tree
-     → Hiển thị: progress_dashboard()
-   → Nếu không có epic (legacy):
-     CHẠY: bd list --status in_progress
-     CHẠY: bd list --status open --limit 3
-
-2. Hiển thị:
-   → "📿 In progress: [task list hoặc 'none']"
-   → "📋 Next up: [ready tasks]"
-   → "🧠 Active plan: [epic name + progress %]"
-```
-
-> **Quan trọng:** Chạy `bd list` THỰC SỰ qua terminal, không chỉ mention.
-
-### 🟠 Gate 0.5 — Project Brain Lookup (Chạy SAU Gate 0, TRƯỚC khi làm bất kỳ gì)
-
-```
-Nếu có file .project-identity trong project dir:
-  → ĐỌC: .project-identity
-  → Extract: projectName, stage, architecture, tech stack
-
-Nếu có file CODEBASE.md trong project dir:
-  → ĐỌC: CODEBASE.md
-  → Load: layer map, feature areas, naming conventions
-
-OUTPUT (Brief confirm — LUÔN hiển thị):
-  "📚 [ProjectName] | [Stage] | [Architecture]
-   🗺️  Targeting: [relevant layer/file based on request]"
-
-QUY TẮC:
-  → Không bao giờ scan raw directory nếu CODEBASE.md tồn tại
-  → Không hỏi user về project structure — tự suy luận từ CODEBASE.md
-  → Nếu CODEBASE.md outdated (file được nhắc đến không có trong đó)
-     → Ghi chú cuối response: "⚠️ CODEBASE.md có thể outdated — dùng /codebase-sync"
-```
-
-### 🟡 Gate 1 — Before ANY Coding / Debugging / Planning
-
-```
-PHẢI xác định: Task đang làm là Task #ID nào?
-
-Nếu có active epic (từ active_plans.json):
-  → smart_pick(): bd ready --parent <epic-id> --json
-  → Auto-claim: bd update <id> --claim
-  → Hiển thị: acceptance criteria + parent phase
-
-Nếu không có epic (legacy flat mode):
-  → Nếu chưa có task in_progress:
-    bd create "[task summary]" --priority 1
-    bd update <id> --status in_progress
-  → Nếu đã có task in_progress:
-    Confirm: "Tiếp tục Task #X: [name]?"
-```
-
-### 🟢 Gate 2 — After Task Completion
+## Session Protocol
 
-```
-KHI user confirm "xong", "ok", "done", "chạy rồi", "ổn rồi":
-  → Nếu có active epic:
-    CHẠY: bd close <current_task_id> --reason "Completed" --suggest-next
-    CHẠY: bd epic close-eligible  (auto-close parent phase/epic nếu all children done)
-  → Nếu legacy flat mode:
-    CHẠY: bd update <current_task_id> --status done
-    CHẠY: bd list --status open --limit 3 (suggest next)
-  → memory-sync tự save solution nếu là bug fix
-  → Nếu có file mới được tạo trong session → gợi ý /codebase-sync
-```
+> [!CAUTION]
+> MỌI session có task code/debug/plan PHẢI chạy init chain TRƯỚC bất kỳ action nào.
+> Bỏ qua = vi phạm. KHÔNG CÓ NGOẠI LỆ.
 
-### 🔴 Gate 3 — Before Deploy / Push
+### Init Chain (BẮT BUỘC)
 
 ```
-PHẢI chạy:
-  1. bd list --status in_progress  (không deploy nếu còn task dang dở)
-  2. git status
-  3. Confirm với user trước khi commit/push
-```
-
----
-
-## 📿 Beads Commands (Quick Ref)
-
-```bash
-# Hierarchical (v6.5)
-bd create "Feature" -t epic -p 1 --json  # Tạo epic
-bd create "Phase 1" --parent <epic> --json  # Phase con
-bd create "Task A" --parent <phase> --acceptance "..." --json  # Subtask
-bd dep add <phase2> <phase1>               # Dependencies
-bd ready --parent <epic> --json            # Ready tasks trong epic
-bd update <id> --claim                     # Claim task
-bd close <id> --reason "Done" --suggest-next  # Close + gợi ý next
-bd epic status --json                      # Epic progress
-bd epic close-eligible                     # Auto-close completed parents
-bd list --parent <epic> --tree             # Tree view
-
-# Legacy flat mode
-bd list --status in_progress     # Đang làm
-bd list --status open --limit 5  # Chưa làm (top 5)
-bd create "Task name"            # Tạo task
-bd show <id>                     # Chi tiết
+symphony-orchestrator → awf-session-restore → nm-memory-sync → orchestrator → action
 ```
 
-**Shortcuts:**
-- `/todo` → `bd list` (hoặc `bd list --parent <epic> --tree` nếu có epic)
-- `/done` → `bd close <id> --reason "Done" --suggest-next` + `bd epic close-eligible`
-
----
-
-## 🧠 Memory Auto-Sync
-
-`memory-sync` skill xử lý tự động — không cần gọi thủ công:
+Mỗi skill tự xử lý gate logic riêng — xem SKILL.md của từng skill.
 
-| Trigger | Action |
-|---------|--------|
-| Decision made | Auto-save → `brain/decisions/` |
-| Bug fixed | Auto-save → `brain/solutions/` |
-| Session start | Auto-read last 3 decisions |
-| Error detected | Auto-query matching solution |
-| BRIEF.md tạo xong | Auto-save architecture summary |
+### Ngoại lệ
 
-**Manual:** `/save-brain "Title"` → Force-save với custom title.
+- Câu hỏi đơn giản (hỏi-đáp, giải thích) → không cần init chain.
+- User nói rõ bỏ qua → được phép.
 
----
+### Exit Protocol
 
-## 🛠️ Workflows & Skills
-
-Workflows: Xem `global_workflows/` (75+ workflows, gõ `/xxx` để chạy)
-
-**Core commands:**
-
-| Command | Mô tả |
-|---------|-------|
-| `/plan` / `/planExpert "X"` | Thiết kế tính năng |
-| `/code` / `/codeExpert` | Viết code |
-| `/debug` / `/debugExpert` | Sửa lỗi |
-| `/recap` | Khôi phục context |
-| `/next` | Gợi ý tiếp theo |
-| `/todo` | Xem tasks hiện tại |
-| `/codebase-sync` | Đồng bộ CODEBASE.md với codebase thực tế |
-| `/reverse-android` | Dịch ngược APK thành mã Kotlin hiện đại |
-| `/reverse-ios` | Dịch ngược IPA thành mã Swift hiện đại |
-
-**Active Skills** (tự động kích hoạt — theo thứ tự ưu tiên):
-
-| Priority | Skill | Trigger | Ghi chú |
-|----------|-------|---------|----------|
-| 1 | `orchestrator` | Always (first) | Phân tích intent + inject project context |
-| 2 | `awf-session-restore` | Session start | Load Beads + Brain + Project Brain |
-| 3 | `memory-sync` | Always | Đọc/ghi brain memory storage |
-| 4 | `beads-manager` | Always | Track & auto-update tasks |
-| 5 | `brainstorm-agent` | `/brainstorm`, từ khoá ý tưởng | Brainstorm ý tưởng & tạo BRIEF |
-| 6 | `awf-error-translator` | Khi có lỗi | Dịch lỗi dễ hiểu |
-| 7 | `awf-adaptive-language` | Always | Điều chỉnh ngôn ngữ |
-| 8 | `smali-to-kotlin` | `/reverse-android` hoặc từ khóa APK, Smali | Android Reverse Engineering specialist |
-| 9 | `smali-to-swift` | `/reverse-ios` hoặc từ khóa IPA, class-dump | iOS Reverse Engineering specialist |
-
-> ⚠️ **Phân biệt:** `memory-sync` = đọc/ghi bộ nhớ. `brainstorm-agent` = khám phá ý tưởng. Hai skill hoàn toàn độc lập.
-> 📌 **Thứ tự:** `orchestrator` → `awf-session-restore` → `memory-sync` → action. Không được đảo.
+- Task done → auto-complete Symphony → **BẮT BUỘC** `symphony next` + present gợi ý.
+- Kết thúc message → **LUÔN** kèm "Next steps" section.
+- `nm-memory-sync` auto-save (W1–W4 triggers).
+- Deploy/push → kiểm tra in-progress tasks trước, confirm với user.
 
 ---
 
-## 📏 Code Rules
-
-### Khi Code
-- Production quality by default.
-- File < 500 lines. Tách module nếu cần.
-- Không xóa / sửa code ngoài scope yêu cầu.
-- Không deploy/push mà không hỏi user.
-
-### An toàn
-- Không hardcode secrets → Dùng `.env`.
-- Không dùng `git reset --hard`.
-- AI models: Chỉ dùng Gemini 2.5+, không hardcode model name.
-- Firebase: Dùng Firebase AI Logic SDK.
+## Rules
+
+### Code
+- Production quality. File < 500 lines.
+- Không sửa code ngoài scope.
+- Không deploy/push không hỏi.
+- Không hardcode secrets → `.env`.
+- Không `git reset --hard`.
+- AI models: Gemini 2.5+ only.
+- Firebase: Firebase AI Logic SDK.
+
+### 6-Gate Autonomous System (v12.1)
+- orchestrator PHẢI triage complexity (TRIVIAL/MODERATE/COMPLEX) trước mọi task.
+- COMPLEX tasks PHẢI qua 6 Gates tuần tự:
+  - Gate 1 (Spec): `brainstorm-agent` → BRIEF.md / spec document
+  - Gate 1.5 (Module Spec): `module-spec-writer` → per-module product specs (screens, flows, rules)
+  - Gate 2 (Architecture): `spec-gate` → design doc + user approve
+  - Gate 3 (Tasks): `symphony-enforcer` → tạo Symphony tickets
+  - Gate 4 (Execution): code theo ticket, đối chiếu design doc
+  - Gate 5 (Verification): `verification-gate` + `code-review`
+- Gate 1.5 MANDATORY khi: COMPLEX + >3 modules hoặc port/migration projects.
+- Gate 1.5 SKIP khi: TRIVIAL/MODERATE hoặc single-module projects.
+- TRIVIAL tasks bypass → thẳng Gate 4.
+- MODERATE tasks → Gate 3 + 4 + 5.
+- AI tự detect gate state — user KHÔNG CẦN gọi workflow bằng tay.
+- Trong lúc code, nếu cần sửa schema khác approved design → ⛔ DỪNG, quay Gate 2.
+- Chi tiết: xem `orchestrator/SKILL.md` (triage) + `module-spec-writer/SKILL.md` (Gate 1.5) + `spec-gate/SKILL.md` (Gate 2).
+
+### NeuralMemory
+- Brain = projectId. Switch trước mọi nmem call.
+- Mọi `nmem_remember()` PHẢI tag projectId.
+- Cross-brain: `nmem_recall(query, brains=["default", projectId])`.
+- KHÔNG gọi nmem tool TRƯỚC khi brain switch xong.
+
+### Communication
+- Chat: Tiếng Việt.
+- Code/Docs/Comments: Tiếng Anh.
+- Kết thúc task: Tóm tắt + Test + Next steps.
+- Không rõ: Hỏi lại, tối đa 2 lần.
+
+### Anti-sycophancy (Trung thực)
+- PHẢI push back khi approach của user có vấn đề — giải thích rõ trade-offs.
+- KHÔNG nói "Great idea!" nếu idea có red flags → nêu rủi ro trước.
+- Nêu cả ưu VÀ nhược điểm của mọi approach, không chỉ list ưu điểm.
+- Nếu request vi phạm best practices → cảnh báo TRƯỚC khi implement.
+- Khi phát hiện pattern sai → đề xuất alternative, không im lặng đồng ý.
+- Acknowledge limitations: nói "Tôi không chắc" khi không chắc.
+
+### Safety Guardrails (Destructive Commands)
+- KHÔNG BAO GIỜ set `SafeToAutoRun=true` cho các commands sau:
+  - `rm -rf`, `rm -r`, `rmdir` (recursive delete)
+  - `git push --force`, `git reset --hard`, `git clean -fd`
+  - `DROP TABLE`, `DROP DATABASE`, `DELETE FROM` (without WHERE)
+  - `docker system prune`, `docker volume rm`
+  - `npm publish`, `pod trunk push`
+  - Bất kỳ command nào deploy lên production
+- Double-confirm với user trước khi chạy destructive command.
+- Nếu không chắc command có destructive hay không → hỏi trước.
+
+### 6 Decision Principles (Auto-decide)
+Khi AI cần tự quyết định mà không hỏi user:
+1. **Complete > Shortcuts** — Implement đủ, không bỏ edge cases.
+2. **Evidence > Assumptions** — Dựa trên data, không đoán.
+3. **Standard > Custom** — Ưu tiên solution có sẵn, chuẩn ngành.
+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 refactor.
+
+### Project Context
+- CODEBASE.md tồn tại → KHÔNG scan raw directory.
+- KHÔNG hỏi user về project structure.
+- CODEBASE.md outdated → ghi chú "⚠️ dùng /codebase-sync".
+
+### GitNexus (Code Intelligence)
+- Project đã index (`.gitnexus/` tồn tại) → PHẢI dùng GitNexus tools.
+- Trước khi edit symbol → `gitnexus_impact` check blast radius.
+- Trước khi commit → `gitnexus_detect_changes()` verify scope.
+- Risk HIGH/CRITICAL → PHẢI cảnh báo user trước khi sửa.
+- Explore code lạ → ưu tiên `gitnexus_query` thay vì grep thủ công.
+- Rename symbol → PHẢI dùng `gitnexus_rename` (dry_run trước).
+- Index stale → cảnh báo "⚠️ chạy `npx gitnexus analyze`".
+- Chi tiết: xem `gitnexus-intelligence/SKILL.md`.
+
+### Two-Agent Flow (Conductor)
+- Antigravity CHỦ ĐỘNG gọi `gemini -p "..." --approval-mode plan` khi cần tầm nhìn rộng.
+- CLI dùng **quota pool riêng** → không ảnh hưởng Antigravity quota.
+- Trigger: refactor >5 files, architecture analysis, cross-module review, second opinion.
+- LUÔN dùng `--approval-mode plan` (read-only). CLI KHÔNG ĐƯỢC edit files.
+- Timeout 60s. Fallback gracefully nếu CLI unavailable.
+- Thông báo user: "📡 Đang gọi Gemini CLI..." trước khi gọi.
+- Chi tiết: xem `gemini-conductor/SKILL.md`.
 
 ---
 
-## 💬 Giao tiếp
+## Routing
 
-- **Chat:** Tiếng Việt.
-- **Code / Docs / Comments:** Tiếng Anh.
-- **Kết thúc task:** Tóm tắt + Hướng dẫn test + Next steps.
-- **Không rõ:** Hỏi lại, tối đa 2 lần.
+- **Execution order:** `symphony-orchestrator` → `awf-session-restore` → `nm-memory-sync` → `symphony-enforcer` → `orchestrator` (triage + gate-check) → action
+- **Gate skills:** `orchestrator` (triage) → `brainstorm-agent` (G1) → `module-spec-writer` (G1.5) → `spec-gate` (G2) → `symphony-enforcer` (G3) → `verification-gate` (G5)
+- **Code intelligence:** `gitnexus-intelligence` (impact analysis, blast radius, safe refactoring)
+- **Skill catalog:** xem `orchestrator/SKILL.md`
+- **Workflows:** 75+ (`/xxx`). Core: `/init` `/code` `/debug` `/recap` `/next` `/todo` `/gitnexus`
+- **Shortcuts:** `/todo` `/done` `/next`
 
 ---
 
-## 📁 Resource Locations
+## Paths
 
 ```
 ~/.gemini/antigravity/
-├── GEMINI.md              # Master config (file này)
-├── global_workflows/      # Workflow definitions (75+)
-├── skills/                # Auto-activate skills (9 active)
-├── brain/                 # Knowledge storage
-│   ├── session.json
-│   ├── active_plans.json
-│   ├── decisions/
-│   └── solutions/
-├── templates/             # Plan, spec templates
-└── schemas/               # JSON schemas
+├── GEMINI.md          # Rules (file này)
+├── global_workflows/  # Workflows
+├── skills/            # Skills (auto-activate)
+├── brain/             # Knowledge
+├── symphony/          # Task DB
+├── templates/         # Templates
+└── schemas/           # Schemas
 ```
-
----
-
-*Antigravity v6.5 — Hierarchical Beads, Project-Aware, Memory Sync + Brainstorm Agent*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leejungkiin/awkit",
-  "version": "1.3.8",
+  "version": "1.4.0",
   "description": "Antigravity Workflow Kit. Unified AI agent orchestration system.",
   "main": "bin/awk.js",
   "bin": {

package/skills/awf-session-restore/SKILL.md

@@ -6,8 +6,8 @@ description: |
   Enforces Project ID → Brain Switch → Memory Read order to prevent cross-project contamination.
 metadata:
   stage: core
-  version: "7.0"
-  replaces: "v6.4"
+  version: "7.1"
+  replaces: "v7.0"
   requires: symphony-orchestrator
   tags: [session, restore, context, symphony, neuralmemory, silent, multi-project]
 trigger: session_start
@@ -99,6 +99,16 @@ Hoặc nếu dùng cấu trúc brain khác:
 cat CODEBASE.md 2>/dev/null | head -5
 ```
 
+#### 3d. Legacy Artifact Detection (v7.1)
+```bash
+# Detect stale JSON task files — Symphony uses SQLite only
+test -f .symphony/tasks.json && echo "LEGACY_TASKS_JSON_FOUND" || echo "CLEAN"
+```
+
+Nếu phát hiện `LEGACY_TASKS_JSON_FOUND`:
+→ Ghi vào silent context: `legacy_artifacts: ["tasks.json"]`
+→ `symphony-enforcer` Step 0.5 sẽ warn user.
+
 #### 3c. Symphony Task State
 ```bash
 symphony task list -P <projectId> -s in_progress --json 2>/dev/null

package/skills/brainstorm-agent/SKILL.md

@@ -131,21 +131,24 @@ Trước khi bắt đầu, LUÔN:
 ### Phase 2: Idea Exploration (One Question at a Time)
 
 **Rules:**
-- Hỏi **một câu hỏi mỗi lần** — không overwhelm user
+- Hỏi **một câu hỏi mỗi lần** — không overwhelm user.
+- **CHỦ ĐỘNG KHAI THÁC & MỞ RỘNG:** Thay vì chỉ nhận ý tưởng thụ động, AI cần **chủ động đặt câu hỏi gợi mở, giả định tình huống hoặc các edge cases** để giúp user tự suy nghĩ sâu hơn và mở rộng ý tưởng của họ (Socratic questioning).
 - Dùng câu hỏi mở đầu thân thiện:
 
 ```
-"💡 Kể em nghe ý tưởng của anh đi! Anh muốn làm gì?"
+"💡 Kể em nghe chi tiết ý tưởng của anh đi! Anh đang muốn giải quyết bài toán gì?"
 
-Sau khi nghe, hỏi thêm:
-• "App/tính năng này giải quyết vấn đề gì?"
-• "Ai sẽ dùng nó?"
-• "Anh nghĩ điều gì làm cho nó khác biệt?"
+Sau khi nghe, hãy chủ động probe sâu hơn. Thay vì hỏi chung chung, hãy hỏi cụ thể dựa trên ý tưởng của user:
+• "Nếu user làm [hành động X], hệ thống nên xử lý thế nào?"
+• "Điểm khác biệt lớn nhất giữa app của anh và các app hiện có là gì?"
+• "Ai sẽ là người dùng cốt lõi nhất, và họ gặp pain point gì nghiêm trọng nhất?"
+• "Anh có nghĩ đến việc thêm [Gợi ý góc nhìn mới/tính năng mở rộng] không, vì nó sẽ giúp [lợi ích]?"
 ```
 
-**Active Listening:**
+**Active Listening & Expanding:**
 - Tóm tắt lại: "Em hiểu là anh muốn [X] để giải quyết [Y], đúng không?"
-- KHÔNG vội đưa ra giải pháp — hiểu vấn đề trước
+- **Đào sâu:** "Em thấy phần [Z] khá thú vị, anh định triển khai nó theo hướng manual hay chạy auto?"
+- KHÔNG vội đưa ra giải pháp hoàn chỉnh — hãy giúp user tự làm rõ ý tưởng của mình trước.
 
 ---
 

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

@@ -0,0 +1,82 @@
+---
+name: gitnexus-cli
+description: "Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: \"Index this repo\", \"Reanalyze the codebase\", \"Generate a wiki\""
+---
+
+# GitNexus CLI Commands
+
+All commands work via `npx` — no global install required.
+
+## Commands
+
+### analyze — Build or refresh the index
+
+```bash
+npx gitnexus analyze
+```
+
+Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.gitnexus/`, and generates CLAUDE.md / AGENTS.md context files.
+
+| Flag           | Effect                                                           |
+| -------------- | ---------------------------------------------------------------- |
+| `--force`      | Force full re-index even if up to date                           |
+| `--embeddings` | Enable embedding generation for semantic search (off by default) |
+
+**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook runs `analyze` automatically after `git commit` and `git merge`, preserving embeddings if previously generated.
+
+### status — Check index freshness
+
+```bash
+npx gitnexus status
+```
+
+Shows whether the current repo has a GitNexus index, when it was last updated, and symbol/relationship counts. Use this to check if re-indexing is needed.
+
+### clean — Delete the index
+
+```bash
+npx gitnexus clean
+```
+
+Deletes the `.gitnexus/` directory and unregisters the repo from the global registry. Use before re-indexing if the index is corrupt or after removing GitNexus from a project.
+
+| Flag      | Effect                                            |
+| --------- | ------------------------------------------------- |
+| `--force` | Skip confirmation prompt                          |
+| `--all`   | Clean all indexed repos, not just the current one |
+
+### wiki — Generate documentation from the graph
+
+```bash
+npx gitnexus wiki
+```
+
+Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use).
+
+| Flag                | Effect                                    |
+| ------------------- | ----------------------------------------- |
+| `--force`           | Force full regeneration                   |
+| `--model <model>`   | LLM model (default: minimax/minimax-m2.5) |
+| `--base-url <url>`  | LLM API base URL                          |
+| `--api-key <key>`   | LLM API key                               |
+| `--concurrency <n>` | Parallel LLM calls (default: 3)           |
+| `--gist`            | Publish wiki as a public GitHub Gist      |
+
+### list — Show all indexed repos
+
+```bash
+npx gitnexus list
+```
+
+Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information.
+
+## After Indexing
+
+1. **Read `gitnexus://repo/{name}/context`** to verify the index loaded
+2. Use the other GitNexus skills (`exploring`, `debugging`, `impact-analysis`, `refactoring`) for your task
+
+## Troubleshooting
+
+- **"Not inside a git repository"**: Run from a directory inside a git repo
+- **Index is stale after re-analyzing**: Restart Claude Code to reload the MCP server
+- **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding

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

@@ -0,0 +1,89 @@
+---
+name: gitnexus-debugging
+description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\""
+---
+
+# Debugging with GitNexus
+
+## When to Use
+
+- "Why is this function failing?"
+- "Trace where this error comes from"
+- "Who calls this method?"
+- "This endpoint returns 500"
+- Investigating bugs, errors, or unexpected behavior
+
+## Workflow
+
+```
+1. gitnexus_query({query: "<error or symptom>"})            → Find related execution flows
+2. gitnexus_context({name: "<suspect>"})                    → See callers/callees/processes
+3. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow
+4. gitnexus_cypher({query: "MATCH path..."})                 → Custom traces if needed
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklist
+
+```
+- [ ] Understand the symptom (error message, unexpected behavior)
+- [ ] gitnexus_query for error text or related code
+- [ ] Identify the suspect function from returned processes
+- [ ] gitnexus_context to see callers and callees
+- [ ] Trace execution flow via process resource if applicable
+- [ ] gitnexus_cypher for custom call chain traces if needed
+- [ ] Read source files to confirm root cause
+```
+
+## Debugging Patterns
+
+| Symptom              | GitNexus Approach                                          |
+| -------------------- | ---------------------------------------------------------- |
+| Error message        | `gitnexus_query` for error text → `context` on throw sites |
+| Wrong return value   | `context` on the function → trace callees for data flow    |
+| Intermittent failure | `context` → look for external calls, async deps            |
+| Performance issue    | `context` → find symbols with many callers (hot paths)     |
+| Recent regression    | `detect_changes` to see what your changes affect           |
+
+## Tools
+
+**gitnexus_query** — find code related to error:
+
+```
+gitnexus_query({query: "payment validation error"})
+→ Processes: CheckoutFlow, ErrorHandling
+→ Symbols: validatePayment, handlePaymentError, PaymentException
+```
+
+**gitnexus_context** — full context for a suspect:
+
+```
+gitnexus_context({name: "validatePayment"})
+→ Incoming calls: processCheckout, webhookHandler
+→ Outgoing calls: verifyCard, fetchRates (external API!)
+→ Processes: CheckoutFlow (step 3/7)
+```
+
+**gitnexus_cypher** — custom call chain traces:
+
+```cypher
+MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
+RETURN [n IN nodes(path) | n.name] AS chain
+```
+
+## Example: "Payment endpoint returns 500 intermittently"
+
+```
+1. gitnexus_query({query: "payment error handling"})
+   → Processes: CheckoutFlow, ErrorHandling
+   → Symbols: validatePayment, handlePaymentError
+
+2. gitnexus_context({name: "validatePayment"})
+   → Outgoing calls: verifyCard, fetchRates (external API!)
+
+3. READ gitnexus://repo/my-app/process/CheckoutFlow
+   → Step 3: validatePayment → calls fetchRates (external)
+
+4. Root cause: fetchRates calls external API without proper timeout
+```