code-graph-llm 2.1.2 → 3.0.0

package/README.md

@@ -1,54 +1,108 @@
-# CODE-GRAPH (v2.1.2)
+# CODE-GRAPH (v3.0.0)
 
 A language-agnostic, ultra-compact codebase mapper and **agent memory system** designed specifically for LLM agents. It optimizes context and token usage while enabling agents to learn from their own mistakes across sessions.
 
-## 🚀 New in v2.1: Intelligent Reflection & Hard-Soft Enforcement
+## 🚀 New in v3.0: Major Version Upgrade
 - **Project Initializer:** Automated bootstrapping with `code-graph init`.
-- **Intelligent Reflection:** Deduplication and categorization in `PROJECT_REFLECTIONS.md`.
+- **Intelligent Reflection:** Deduplication and categorization in `llm-agent-project-learnings.md`.
 - **Commit Advisories:** Soft-nudge git hooks to remind agents of missing reflections.
 - **Production-Ready Core:** Refactored Service-based architecture with full async support.
 
-## Features
-- **Structural Knowledge Graph:** Captures `imports`, `requires`, `extends`, and `implements`.
-- **Smart Context Extraction:** Captures JSDoc, Python docstrings, and preceding comments.
-- **Signature Fallback:** Extracts function signatures (parameters/types) if documentation is missing.
-- **Recursive .gitignore Support:** Deeply respects both root and nested `.gitignore` files.
-- **Compact & Dense:** Optimized for LLM token efficiency with a dedicated `## GRAPH EDGES` section.
-- **Language-Agnostic:** Support for JS/TS, Python, Go, Rust, Java, C#, C/C++, Swift, PHP, Ruby, Dart, and more.
-
-## Installation
-
-### 1. Install via NPM
-```bash
-npm install -g code-graph-llm
-# OR
-npm install --save-dev code-graph-llm
-```
-
-### 2. Core Commands
-```bash
-# Initialize Agent Rules and Reflection files (Scaffolding)
-code-graph init
-
-# Generate the llm-code-graph.md map
-code-graph generate
-
-# Record a project reflection (Memory)
-code-graph reflect <CATEGORY> "Lesson learned"
-# Example: code-graph reflect ENV "Always use 'cmd /c npm' on Windows."
-
-# Start the live watcher for real-time updates
-code-graph watch
-
-# Install the Git pre-commit hook (Enforces Map & Memory sync)
-code-graph install-hook
-```
+## 🛠️ The Code-Graph Skillset
+
+Code-Graph transforms your codebase into an agent-friendly environment using five core skills:
+
+### 1. **Structural Mapping (`generate`)**
+*   **What it does:** Scans your project for symbols (classes, functions, interfaces) and builds a dense dependency graph (`imports`, `requires`, `inheritance`).
+*   **How to use:** Run `code-graph generate`. This creates `llm-code-graph.md`, which agents use as their "Source of Truth" for navigation.
+*   **Agent Benefit:** Prevents "hallucinating" file paths and reduces token usage by giving the agent a compact map instead of raw file content.
+
+### 2. **Memory Persistence (`reflect`)**
+*   **What it does:** Logs non-obvious fixes, environment quirks, and architectural lessons into `llm-agent-project-learnings.md`.
+*   **How to use:** `code-graph reflect <CATEGORY> "The lesson learned"`.
+*   **Agent Benefit:** Enables "Cross-Session Memory." If an agent fixes a Windows-specific bug in one session, the next agent reads the reflection and avoids the same pitfall.
+
+### 3. **Automated Integration (`install-skills`)**
+*   **What it does:** Bridges the gap between the graph and your LLM platform (Claude, Cursor, Gemini, etc.).
+*   **How to use:** `code-graph <platform> install`.
+*   **Agent Benefit:** Installs **Tool Hooks** and **Always-On Rules** that force the agent to consult the graph before using search tools. It effectively "bakes" the graph into the agent's internal loop.
+
+### 4. **Self-Healing Sync (`install-hook`)**
+*   **What it does:** Installs a Git pre-commit hook to keep the map and memory in sync with code changes.
+*   **How to use:** `code-graph install-hook`.
+*   **Agent Benefit:** Ensures the agent is never working with an outdated map. It also nudges the agent to record a reflection if significant code changed but no lesson was logged.
+
+### 5. **Real-Time Context (`watch`)**
+*   **What it does:** Monitors your filesystem and rebuilds the graph instantly as you or the agent edits code.
+*   **How to use:** `code-graph watch`.
+*   **Agent Benefit:** Vital for long-running agent sessions where the project structure is rapidly evolving.
+
+---
+
+## 🧠 Workflow: The Reflection Cycle
+
+To get the most out of Code-Graph, force your agent to follow this **Strict Protocol** (defined in `llm-agent-rules.md`):
+
+1.  **PRE-TASK (Read):** The agent MUST read `llm-agent-project-learnings.md` to check for existing pitfalls and `llm-code-graph.md` to locate the relevant "God Nodes" (core logic).
+2.  **EXECUTION (Monitor):** During the task, the agent monitors for "Learned Moments"—failures, unexpected OS behaviors, or complex regex fixes.
+3.  **POST-TASK (Reflect):** If a lesson was learned, the agent MUST run `code-graph reflect`.
+4.  **COMMIT (Sync):** Upon commit, the Git hook automatically runs `code-graph generate` to update the map for the next agent.
+
+---
+
+## 🚀 Automated Agent Integration
+
+After generating a graph, you can automatically configure your favorite LLM agent to use it by running the matching install command.
+
+| Platform | Command |
+| :--- | :--- |
+| **Claude Code** | `code-graph claude install` |
+| **Cursor** | `code-graph cursor install` |
+| **Gemini CLI** | `code-graph gemini install` |
+| **Codex** | `code-graph codex install` |
+| **OpenCode** | `code-graph opencode install` |
+| **GitHub Copilot CLI** | `code-graph copilot install` |
+| **VS Code Copilot Chat** | `code-graph vscode install` |
+| **Aider** | `code-graph aider install` |
+| **OpenClaw** | `code-graph openclaw install` |
+| **Factory Droid** | `code-graph droid install` |
+| **Trae** | `code-graph trae install` |
+| **Hermes** | `code-graph hermes install` |
+| **Kiro IDE/CLI** | `code-graph kiro install` |
+| **Google Antigravity** | `code-graph antigravity install` |
+
+### What this does:
+- **Always-on Rules:** Writes project-level rule files (e.g., `CLAUDE.md`, `.cursor/rules/`, `AGENTS.md`) telling the agent to read `llm-code-graph.md` before answering architecture questions.
+- **Pre-Tool Hooks:** For platforms that support it (Claude, Codex, Gemini, OpenCode), it installs hooks that fire before every file-search or bash call, injecting a reminder to check the graph first. This prevents the agent from grepping every file when a high-level map already exists.
+- **Global Skills:** Copies the Code-Graph skill to the platform's global skill directory for persistence across projects.
+
+**Uninstall** by replacing `install` with `uninstall` (e.g., `code-graph claude uninstall`).
+
+### Skill Installation Details
+
+| Platform | Action Taken | Directory / Files |
+| :--- | :--- | :--- |
+| **Claude Code** | Adds instructions to `CLAUDE.md` and installs a `preToolUse` hook for `glob` and `grep`. | `.claude/settings.json` |
+| **Cursor** | Writes a global rule with `alwaysApply: true`. | `.cursor/rules/code-graph.mdc` |
+| **Gemini CLI** | Copies skill globally and adds a `beforeTool` hook for `read_file`. | `~/.gemini/skills/code-graph/SKILL.md`, `.gemini/settings.json`, `GEMINI.md` |
+| **Codex** | Updates `AGENTS.md` and installs a `preToolUse` hook for `bash`. | `.codex/hooks.json` |
+| **OpenCode** | Registers a plugin that fires before `bash` tool calls. | `.opencode/plugins/code-graph.js`, `opencode.json`, `AGENTS.md` |
+| **GitHub Copilot CLI** | Copies the Code-Graph skill to the global skill directory. | `~/.copilot/skills/code-graph/SKILL.md` |
+| **VS Code Copilot** | Writes session-persistent instructions. | `.github/copilot-instructions.md` |
+| **Aider / Trae / etc.** | Updates `AGENTS.md` and copies skill to global platform directory. | `~/.<platform>/skills/code-graph/SKILL.md`, `AGENTS.md` |
+| **Kiro IDE/CLI** | Writes global skill and steering file for automatic inclusion. | `.kiro/skills/code-graph/SKILL.md`, `.kiro/steering/code-graph.md` |
+| **Antigravity** | Writes always-on rules and registers a slash command workflow. | `.agent/rules/code-graph.md`, `.agent/workflows/code-graph.md` |
+
+### How agents use it:
+1.  **Direct Instructions:** Most platforms are configured to read project-level files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, etc.) automatically. These files tell the agent: "Before searching files, read `llm-code-graph.md`."
+2.  **Tool Hooks (The "Always-On" Mechanism):** For Claude, Gemini, and Codex, the tool installs a **blocking hook**. When the agent tries to use a search tool (like `grep`), the hook intercepts the call and injects a reminder: "Knowledge graph exists. Read `llm-code-graph.md` first." This forces the agent to use the graph for navigation instead of brute-force searching.
+3.  **Slash Commands:** Some platforms (Kiro, Antigravity) register `/code-graph` as a command to manually invoke or refresh the graph context.
 
 ## 🧠 LLM Agent Strategy
 
 ### 1. The Mandatory Protocol
-Instruct your agent to follow the **STRICT AGENT PROTOCOL** in `AGENT_RULES.md`. This ensures the agent:
-1. Reads `PROJECT_REFLECTIONS.md` before starting any task.
+Instruct your agent to follow the **STRICT AGENT PROTOCOL** in `llm-agent-rules.md`. This ensures the agent:
+1. Reads `llm-agent-project-learnings.md` before starting any task.
 2. Updates reflections after any failure or "learned moment."
 3. Regenerates the project map (`llm-code-graph.md`) after structural changes.
 
@@ -66,51 +120,52 @@ The `llm-code-graph.md` file provides a high-level map and structural graph for
 ```
 
 ### 3. Example System Prompt
-> "Before acting, read `llm-code-graph.md`. Follow the protocol in `AGENT_RULES.md`. If you encounter a bug or an environment quirk, use the `code-graph reflect` tool to record the lesson in `PROJECT_REFLECTIONS.md`."
+> "Before acting, read `llm-code-graph.md`. Follow the protocol in `llm-agent-rules.md`. If you encounter a bug or an environment quirk, use the `code-graph reflect` tool to record the lesson in `llm-agent-project-learnings.md`."
 
 ## 🤖 Agent-Specific Integration
 
-Maximize efficiency by pointing your agent directly to the `llm-code-graph.md` and `AGENT_RULES.md` files.
+Maximize efficiency by pointing your agent directly to the `llm-code-graph.md` and `llm-agent-rules.md` files.
 
 ### Roo Code (Cline)
 Add this to your `.clinerules` file:
 ```markdown
 Before starting any task:
 1. Read `llm-code-graph.md` for project structure.
-2. Read `AGENT_RULES.md` for operational protocol.
-3. Read `PROJECT_REFLECTIONS.md` for past lessons.
+2. Read `llm-agent-rules.md` for operational protocol.
+3. Read `llm-agent-project-learnings.md` for past lessons.
+4. **MANDATORY:** After any fix or learning event, you MUST update `llm-agent-project-learnings.md` using `code-graph reflect`.
 ```
 
 ### Cursor / Windsurf
 Add to `.cursorrules` or `.windsurfrules`:
 ```text
-Always reference `llm-code-graph.md` to understand the codebase architecture before performing edits. Strictly follow the "Reflection Cycle" in `AGENT_RULES.md`.
+Always reference `llm-code-graph.md` before editing. You are REQUIRED to follow the "Reflection Cycle" in `llm-agent-rules.md`. If a task involves a non-obvious fix or an environment quirk, you MUST record it in `llm-agent-project-learnings.md` immediately.
 ```
 
 ### GitHub Copilot
 Add to `.github/copilot-instructions.md`:
 ```markdown
-When answering questions about this codebase, prioritize the mapping data in `llm-code-graph.md`. If a task fails or a mistake is corrected, suggest a reflection entry for `PROJECT_REFLECTIONS.md`.
+When answering questions about this codebase, prioritize the mapping data in `llm-code-graph.md`. You MUST suggest or perform a reflection entry for `llm-agent-project-learnings.md` after every bug fix or identified pitfall.
 ```
 
 ### Gemini CLI
-Create a `GEMINI.md` file (if not already using `AGENT_RULES.md`):
+Create a `GEMINI.md` file (if not already using `llm-agent-rules.md`):
 ```markdown
 - Always read `llm-code-graph.md` as the primary source of truth.
-- Use the `run_shell_command` tool to execute `code-graph reflect` after fixing non-obvious bugs.
+- **CRITICAL:** Use `run_shell_command` to execute `code-graph reflect` after any bug fix or discovered quirk. Memory persistence is a mandatory part of every task completion.
 ```
 
 ### OpenCode / OpenDevin / Aider
 In your project instructions or session startup:
-> "Read `llm-code-graph.md` for a high-level overview. If you discover a project-specific quirk, record it using `code-graph reflect <CAT> <LESSON>`."
+> "Read `llm-code-graph.md` for a high-level overview. You are FORCED to record any project-specific quirk or non-obvious lesson using `code-graph reflect <CAT> <LESSON>` before finishing a task."
 
 ### Codex / GPT-Engineer / AutoGPT
 Add to your project prompt or `prompts.md`:
-> "Use `llm-code-graph.md` to navigate the file structure. Strictly adhere to the reflection cycle in `AGENT_RULES.md` to ensure project memory is maintained across iterations."
+> "Use `llm-code-graph.md` to navigate. Strictly adhere to the reflection cycle in `llm-agent-rules.md`. You MUST persist project memory by updating `llm-agent-project-learnings.md` on every failure or learned moment."
 
 ### Generic Agent (System Prompt)
 For any other agent, add this to your system instructions:
-> "This project uses `code-graph-llm` for context management. Always consult `llm-code-graph.md` before exploring files. If you learn something new about the environment (e.g., shell quirks, library oddities), persist that knowledge using the `code-graph reflect` tool."
+> "This project uses `code-graph-llm` for context management. Always consult `llm-code-graph.md`. You ARE REQUIRED to persist new knowledge about the environment or logic using the `code-graph reflect` tool. Failure to update memory is a failure of the task."
 
 ## How it works
 1. **File Scanning:** Recursively walks the directory, ignoring patterns in `.gitignore`.

package/index.js

@@ -10,6 +10,7 @@ import fs from 'fs';
 import { promises as fsp } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import os from 'os';
 import chokidar from 'chokidar';
 import ignore from 'ignore';
 
@@ -19,8 +20,8 @@ const __filename = fileURLToPath(import.meta.url);
 export const CONFIG = {
   IGNORE_FILE: '.gitignore',
   MAP_FILE: 'llm-code-graph.md',
-  REFLECTIONS_FILE: 'PROJECT_REFLECTIONS.md',
-  RULES_FILE: 'AGENT_RULES.md',
+  REFLECTIONS_FILE: 'llm-agent-project-learnings.md',
+  RULES_FILE: 'llm-agent-rules.md',
   SUPPORTED_EXTENSIONS: [
     '.js', '.ts', '.jsx', '.tsx', '.py', '.go', '.rs', '.java', 
     '.cpp', '.c', '.h', '.hpp', '.cc', '.rb', '.php', '.swift', 
@@ -235,7 +236,7 @@ class ProjectMapper {
   }
 
   formatOutput() {
-    const header = `# CODE_GRAPH_MAP\n> MISSION: COMPACT PROJECT MAP FOR LLM AGENTS.\n> PROTOCOL: Follow AGENT_RULES.md | MEMORY: See PROJECT_REFLECTIONS.md\n> Legend: [CORE] Entry Point, (↑N) Outgoing Deps, (↓M) Incoming Dependents\n> Notation: syms: [Name [Signature/Context]], desc: File Summary, [TAG: Context]\n\n`;
+    const header = `# CODE_GRAPH_MAP\n> MISSION: COMPACT PROJECT MAP FOR LLM AGENTS.\n> PROTOCOL: Follow llm-agent-rules.md | MEMORY: See llm-agent-project-learnings.md\n> Legend: [CORE] Entry Point, (↑N) Outgoing Deps, (↓M) Incoming Dependents\n> Notation: syms: [Name [Signature/Context]], desc: File Summary, [TAG: Context]\n\n`;
     const nodes = this.files.map(f => {
       const inCount = this.incomingEdges[f.path] || 0;
       const tags = f.tags.length ? ` [${f.tags.join(', ')}]` : '';
@@ -254,7 +255,7 @@ class ReflectionManager {
     if (!lesson) return console.error('[Code-Graph] Usage: reflect <cat> <lesson>');
     
     const filePath = path.join(process.cwd(), CONFIG.REFLECTIONS_FILE);
-    const header = `# PROJECT_REFLECTIONS & LESSONS LEARNED\n> LLM AGENT MEMORY: READ BEFORE STARTING TASKS. UPDATE ON FAILURES.\n`;
+    const header = `# LLM_AGENT_PROJECT_LEARNINGS\n> LLM AGENT MEMORY: READ BEFORE STARTING TASKS. UPDATE ON FAILURES.\n`;
     const entry = `- [${category.toUpperCase()}: ${new Date().toISOString().split('T')[0]}] ${lesson}`;
 
     try {
@@ -281,7 +282,7 @@ class ProjectInitializer {
     const rulesPath = path.join(cwd, CONFIG.RULES_FILE);
     const reflectPath = path.join(cwd, CONFIG.REFLECTIONS_FILE);
 
-    const rulesContent = `# AGENT OPERATIONAL PROTOCOL (STRICT)
+    const rulesContent = `# LLM_AGENT_RULES (STRICT PROTOCOL)
 > This protocol is MANDATORY for all LLM agents. Failure to update memory is a failure of the task.
 
 ## 🧠 THE REFLECTION CYCLE
@@ -296,7 +297,7 @@ class ProjectInitializer {
 - \`STYLE\`: Project-specific architectural rules.
 `;
 
-    const reflectContent = `# PROJECT_REFLECTIONS & LESSONS LEARNED\n> LLM AGENT MEMORY: READ BEFORE STARTING TASKS. UPDATE ON FAILURES.\n`;
+    const reflectContent = `# LLM_AGENT_PROJECT_LEARNINGS\n> LLM AGENT MEMORY: READ BEFORE STARTING TASKS. UPDATE ON FAILURES.\n`;
 
     try {
       if (!fs.existsSync(rulesPath)) {
@@ -313,6 +314,174 @@ class ProjectInitializer {
   }
 }
 
+/**
+ * Manages platform-specific skills and agent integrations.
+ */
+class SkillManager {
+  constructor(cwd) {
+    this.cwd = cwd;
+    this.home = os.homedir();
+  }
+
+  async execute(platform, action) {
+    if (!platform) return console.error('[Code-Graph] Platform required. Usage: code-graph <platform> [install|uninstall]');
+    const p = platform.toLowerCase();
+    const act = (action || 'install').toLowerCase();
+
+    if (act === 'install') await this.install(p);
+    else if (act === 'uninstall') await this.uninstall(p);
+    else console.error(`[Code-Graph] Unknown action: ${act}`);
+  }
+
+  async install(p) {
+    console.log(`[Code-Graph] Installing skill for ${p}...`);
+    try {
+      switch (p) {
+        case 'claude': await this.installClaude(); break;
+        case 'codex': await this.installCodex(); break;
+        case 'opencode': await this.installOpenCode(); break;
+        case 'cursor': await this.installCursor(); break;
+        case 'gemini': await this.installGemini(); break;
+        case 'aider':
+        case 'openclaw':
+        case 'droid':
+        case 'trae':
+        case 'trae-cn':
+        case 'hermes':
+          await this.installGenericAgent(p);
+          break;
+        case 'kiro': await this.installKiro(); break;
+        case 'antigravity': await this.installAntigravity(); break;
+        case 'copilot': await this.installCopilot(); break;
+        case 'vscode': await this.installVSCode(); break;
+        default: return console.error(`[Code-Graph] Unsupported platform: ${p}`);
+      }
+      console.log(`[Code-Graph] Successfully installed ${p} skill.`);
+    } catch (err) {
+      console.error(`[Code-Graph] Installation failed for ${p}: ${err.message}`);
+    }
+  }
+
+  async uninstall(p) {
+    console.log(`[Code-Graph] Uninstalling skill for ${p}...`);
+    // Simplification: just remove the primary files
+    try {
+      switch (p) {
+        case 'claude': await this.removeFile('CLAUDE.md'); break;
+        case 'codex': await this.removeFile('AGENTS.md'); break;
+        case 'opencode': await this.removeFile('AGENTS.md'); break;
+        case 'cursor': await this.removeFile('.cursor/rules/code-graph.mdc'); break;
+        case 'gemini': await this.removeFile('GEMINI.md'); break;
+        case 'aider':
+        case 'openclaw':
+        case 'droid':
+        case 'trae':
+        case 'trae-cn':
+        case 'hermes':
+          await this.removeFile('AGENTS.md');
+          break;
+        case 'kiro': await this.removeFile('.kiro/steering/code-graph.md'); break;
+        case 'antigravity': await this.removeFile('.agent/rules/code-graph.md'); break;
+        case 'copilot': await fsp.rm(path.join(this.home, '.copilot', 'skills', 'code-graph'), { recursive: true, force: true }); break;
+        case 'vscode': await this.removeFile('.github/copilot-instructions.md'); break;
+      }
+      console.log(`[Code-Graph] Successfully uninstalled ${p} skill.`);
+    } catch (err) {
+      console.error(`[Code-Graph] Uninstallation failed: ${err.message}`);
+    }
+  }
+
+  async installClaude() {
+    const section = `\n## 🗺️ Code-Graph Integration\nBefore answering architecture questions, read \`${CONFIG.MAP_FILE}\` for god nodes and community structure. This ensures high-level context before searching raw files.\n`;
+    await this.appendToFile('CLAUDE.md', section);
+    await this.writeJson('.claude/settings.json', { hooks: { preToolUse: [{ tools: ['glob', 'grep'], message: `code-graph: Knowledge graph exists. Read ${CONFIG.MAP_FILE} before searching raw files.` }] } });
+  }
+
+  async installCodex() {
+    const section = `\n## 🗺️ Code-Graph Navigation\nAlways check for \`${CONFIG.MAP_FILE}\` to understand project structure before using bash tools.\n`;
+    await this.appendToFile('AGENTS.md', section);
+    await this.writeJson('.codex/hooks.json', { hooks: { preToolUse: [{ tools: ['bash'], message: `code-graph: Knowledge graph exists. Read ${CONFIG.MAP_FILE} for architectural context.` }] } });
+  }
+
+  async installOpenCode() {
+    await this.appendToFile('AGENTS.md', `\n## 🗺️ Code-Graph\nRead \`${CONFIG.MAP_FILE}\` for high-level mapping.\n`);
+    const plugin = `export default { name: 'code-graph', beforeExecute: (tool) => { if (tool.name === 'bash') return "code-graph: Read ${CONFIG.MAP_FILE} for god nodes."; } };`;
+    await this.writeFile('.opencode/plugins/code-graph.js', plugin);
+    await this.writeJson('opencode.json', { plugins: ['./.opencode/plugins/code-graph.js'] });
+  }
+
+  async installCursor() {
+    const content = `---\ndescription: Always use knowledge graph for navigation.\nalwaysApply: true\n---\n# Code-Graph\n- Read \`${CONFIG.MAP_FILE}\` before searching.\n- Prioritize god nodes for architecture.\n- Adhere to \`${CONFIG.RULES_FILE}\`.\n`;
+    await this.writeFile('.cursor/rules/code-graph.mdc', content);
+  }
+
+  async installGemini() {
+    const skillPath = path.join(this.home, '.gemini', 'skills', 'code-graph', 'SKILL.md');
+    await fsp.mkdir(path.dirname(skillPath), { recursive: true });
+    await fsp.writeFile(skillPath, `# Code-Graph Skill\nUse \`${CONFIG.MAP_FILE}\` for navigation.\n`);
+    await this.appendToFile('GEMINI.md', `\n## 🗺️ Code-Graph\nRead \`${CONFIG.MAP_FILE}\` before file-read tools.\n`);
+    await this.writeJson('.gemini/settings.json', { hooks: { beforeTool: [{ tools: ['read_file'], message: `code-graph: Knowledge graph exists. Read ${CONFIG.MAP_FILE}.` }] } });
+  }
+
+  async installGenericAgent(p) {
+    await this.appendToFile('AGENTS.md', `\n## 🗺️ Code-Graph\nRead \`${CONFIG.MAP_FILE}\` for structural context.\n`);
+    const globalPath = path.join(this.home, `.${p}`, 'skills', 'code-graph', 'SKILL.md');
+    await fsp.mkdir(path.dirname(globalPath), { recursive: true });
+    await fsp.writeFile(globalPath, `# Code-Graph Skill for ${p}\n`);
+  }
+
+  async installKiro() {
+    await this.writeFile('.kiro/skills/code-graph/SKILL.md', `# Code-Graph Skill\n`);
+    await this.writeFile('.kiro/steering/code-graph.md', `inclusion: always\n# Code-Graph\nRead \`${CONFIG.MAP_FILE}\`.\n`);
+  }
+
+  async installAntigravity() {
+    await this.writeFile('.agent/rules/code-graph.md', `# Code-Graph Rules\nAlways read \`${CONFIG.MAP_FILE}\`.\n`);
+    await this.writeFile('.agent/workflows/code-graph.md', `# Code-Graph Workflow\nRegisters /code-graph\n`);
+  }
+
+  async installCopilot() {
+    const skillPath = path.join(this.home, '.copilot', 'skills', 'code-graph', 'SKILL.md');
+    await fsp.mkdir(path.dirname(skillPath), { recursive: true });
+    await fsp.writeFile(skillPath, `# Code-Graph Skill\nUse \`${CONFIG.MAP_FILE}\`.\n`);
+  }
+
+  async installVSCode() {
+    await this.appendToFile('.github/copilot-instructions.md', `\n## 🗺️ Code-Graph\nAlways read \`${CONFIG.MAP_FILE}\` for architectural context.\n`);
+  }
+
+  async appendToFile(filename, content) {
+    const fullPath = path.join(this.cwd, filename);
+    if (fs.existsSync(fullPath)) {
+      const existing = await fsp.readFile(fullPath, 'utf8');
+      if (!existing.includes(content.trim())) await fsp.appendFile(fullPath, content);
+    } else {
+      await fsp.writeFile(fullPath, content);
+    }
+  }
+
+  async writeFile(filename, content) {
+    const fullPath = path.join(this.cwd, filename);
+    await fsp.mkdir(path.dirname(fullPath), { recursive: true });
+    await fsp.writeFile(fullPath, content);
+  }
+
+  async writeJson(filename, data) {
+    const fullPath = path.join(this.cwd, filename);
+    let existing = {};
+    if (fs.existsSync(fullPath)) {
+      try { existing = JSON.parse(await fsp.readFile(fullPath, 'utf8')); } catch (e) {}
+    }
+    const merged = { ...existing, ...data };
+    await this.writeFile(filename, JSON.stringify(merged, null, 2));
+  }
+
+  async removeFile(filename) {
+    const fullPath = path.join(this.cwd, filename);
+    if (fs.existsSync(fullPath)) await fsp.unlink(fullPath);
+  }
+}
+
 // --- CLI Entry Point ---
 
 async function main() {
@@ -320,6 +489,8 @@ async function main() {
   const cwd = process.cwd();
 
   try {
+    const platforms = ['claude', 'codex', 'opencode', 'cursor', 'gemini', 'aider', 'openclaw', 'droid', 'trae', 'trae-cn', 'hermes', 'kiro', 'antigravity', 'copilot', 'vscode'];
+    
     switch (command || 'generate') {
       case 'generate':
         await new ProjectMapper(cwd).generate();
@@ -334,11 +505,18 @@ async function main() {
         await ProjectInitializer.init(cwd);
         await installGitHook(cwd);
         break;
+      case 'install-skills':
+        await new SkillManager(cwd).execute(args[0], args[1]);
+        break;
       case 'watch':
         startWatcher(cwd);
         break;
       default:
-        console.log('Usage: code-graph [generate|init|reflect|install-hook|watch]');
+        if (platforms.includes(command?.toLowerCase())) {
+          await new SkillManager(cwd).execute(command, args[0]);
+        } else {
+          console.log('Usage: code-graph [generate|init|reflect|install-hook|watch|install-skills <platform>]');
+        }
     }
   } catch (err) {
     console.error(`[Code-Graph] Critical Error: ${err.message}`);

package/{PROJECT_REFLECTIONS.md → llm-agent-project-learnings.md}

@@ -1,4 +1,4 @@
-# PROJECT_REFLECTIONS & LESSONS LEARNED
+# LLM_AGENT_PROJECT_LEARNINGS
 > LLM AGENT MEMORY: READ BEFORE STARTING TASKS. UPDATE ON FAILURES.
 
 ## ⚠️ CRITICAL PITFALLS
@@ -10,5 +10,6 @@
 
 ## ✅ BEST PRACTICES
 - [STYLE] Always include dependency counts (↑N ↓M) in `llm-code-graph.md` to help prioritize architectural understanding.
-
-- [TOOLING: 2026-04-15] Added reflect command to simplify LLM memory updates.
+
+- [TOOLING: 2026-04-15] Added reflect command to simplify LLM memory updates.
+- [TOOLING: 2026-04-16] Upgraded to v3.0.0: Unified agent renaming (llm-agent-*) and added `install-skills` for automated platform integration (Claude, Cursor, Gemini, etc.).

package/{AGENT_RULES.md → llm-agent-rules.md}

@@ -1,8 +1,8 @@
-# AGENT OPERATIONAL PROTOCOL (STRICT)
+# LLM_AGENT_RULES (STRICT PROTOCOL)
 > This protocol is MANDATORY for all LLM agents. Failure to update memory is a failure of the task.
 ## 🧠 THE REFLECTION CYCLE
-Every execution SHOULD follow this cycle:
-1. **PRE-TASK:** Read \`PROJECT_REFLECTIONS.md\` to identify existing pitfalls.
+Every execution MUST follow this cycle:
+1. **PRE-TASK:** Read `llm-agent-project-learnings.md` to identify existing pitfalls.
 2. **EXECUTION:** Monitor for "Learned Moments" (failures, unexpected behaviors, or non-obvious fixes).
 3. **POST-TASK:** If a significant lesson was learned, run \`code-graph reflect <CAT> <LESSON>\`. 
    - **NOTE:** Routine, expected changes do not require reflections. Focus on high-signal context.

package/llm-code-graph.md

@@ -1,18 +1,20 @@
 # CODE_GRAPH_MAP
 > MISSION: COMPACT PROJECT MAP FOR LLM AGENTS.
-> PROTOCOL: Follow AGENT_RULES.md | MEMORY: See PROJECT_REFLECTIONS.md
+> PROTOCOL: Follow llm-agent-rules.md | MEMORY: See llm-agent-project-learnings.md
 > Legend: [CORE] Entry Point, (↑N) Outgoing Deps, (↓M) Incoming Dependents
 > Notation: syms: [Name [Signature/Context]], desc: File Summary, [TAG: Context]
 
-- [CORE] index.js (↑6 ↓1) [TODO: |FIXME|BUG|DEPRECATED):?\s*(.*)/i,, bug: s or complex regex pitfalls., bug: s or version deprecations., bug: ,"] | desc: !usrbinenv node
-  - syms: [CONFIG [=], CodeParser [--- Core Services --- Handles extraction of symbols, edges, and metadata from source code.], ProjectInitializer [Scaffolds the initial agent-agnostic rule and reflection files.], ProjectMapper [Manages the project mapping and file generation.], ReflectionManager [Manages project reflections and lessons learned.], SUPPORTED_EXTENSIONS [: [], add [(context ? `${display} [${context}]` : display)], extract [(content)], init [(cwd)], installGitHook [(cwd)], main [|app|server|cli)\./i.test(path.basename(relPath))], processFile [(fullPath, relPath)], walk [(dir, ig)]]
+- [CORE] index.js (↑8 ↓1) [TODO: |FIXME|BUG|DEPRECATED):?\s*(.*)/i,, bug: s or complex regex pitfalls., bug: s or version deprecations., bug: ,"] | desc: !usrbinenv node
+  - syms: [CONFIG [=], CodeParser [--- Core Services --- Handles extraction of symbols, edges, and metadata from source code.], ProjectInitializer [Scaffolds the initial agent-agnostic rule and reflection files.], ProjectMapper [Manages the project mapping and file generation.], ReflectionManager [Manages project reflections and lessons learned.], SUPPORTED_EXTENSIONS [: [], SkillManager [Manages platform-specific skills and agent integrations.], add [(context ? `${display} [${context}]` : display)], appendToFile [('CLAUDE.md', section)], execute [(platform, action)], extract [(content)], init [(cwd)], install [|uninstall]')], installAntigravity [()], installClaude [()], installCodex [()], installCopilot [()], installCursor [()], installGemini [()], installGenericAgent [(p)], installGitHook [(cwd)], installKiro [()], installOpenCode [()], installVSCode [()], main [|app|server|cli)\./i.test(path.basename(relPath))], processFile [(fullPath, relPath)], removeFile [('CLAUDE.md')], uninstall []')], walk [(dir, ig)], writeFile [(path.join(this.cwd, CONFIG.MAP_FILE)], writeJson [('.claude/settings.json', { hooks: { preToolUse: [{ tools: ['glob', 'grep'], message: `code-graph: Knowledge graph exists. Read ${CONFIG.MAP_FILE} before searching raw files.` }] } })]]
 - [CORE] test/index.test.js (↑10 ↓0) | desc: 
   - syms: []
 
 ## GRAPH EDGES
+[index.js] -> [imports] -> [bash]
 [index.js] -> [imports] -> [chokidar]
 [index.js] -> [imports] -> [fs]
 [index.js] -> [imports] -> [ignore]
+[index.js] -> [imports] -> [os]
 [index.js] -> [imports] -> [path]
 [index.js] -> [imports] -> [symbols]
 [index.js] -> [imports] -> [url]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-graph-llm",
-  "version": "2.1.2",
+  "version": "3.0.0",
   "description": "Compact, language-agnostic codebase mapper for LLM token efficiency.",
   "main": "index.js",
   "bin": {

package/test/index.test.js

@@ -121,8 +121,8 @@ test('ProjectMapper - Format Output Header', () => {
   const output = mapper.formatOutput();
   
   assert.ok(output.includes('MISSION: COMPACT PROJECT MAP FOR LLM AGENTS.'));
-  assert.ok(output.includes('PROTOCOL: Follow AGENT_RULES.md'));
-  assert.ok(output.includes('MEMORY: See PROJECT_REFLECTIONS.md'));
+  assert.ok(output.includes('PROTOCOL: Follow llm-agent-rules.md'));
+  assert.ok(output.includes('MEMORY: See llm-agent-project-learnings.md'));
 });
 
 test('Recursive Ignore Simulation (Logic Check)', async () => {