gm-kilo 2.0.15 → 2.0.16

package/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

package/.gitignore

@@ -0,0 +1,13 @@
+node_modules/
+*.log
+*.swp
+*.swo
+.DS_Store
+dist/
+build/
+*.tmp
+.env
+.env.local
+.vscode/
+.idea/
+*.iml

package/CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing
+
+Please ensure all code follows the conventions established in this project.
+
+## Before Committing
+
+Run the build to verify everything is working:
+
+```bash
+npm run build plugforge-starter [output-dir]
+```
+
+## Platform Conventions
+
+- Each platform adapter in `platforms/` extends PlatformAdapter or CLIAdapter
+- File generation logic goes in `createFileStructure()`
+- Use TemplateBuilder methods for shared generation logic
+- Skills are auto-discovered from plugforge-starter/skills/
+
+## Testing
+
+Build all 9 platform outputs:
+
+```bash
+node cli.js plugforge-starter /tmp/test-build
+```

package/cli.js

@@ -19,12 +19,18 @@ try {
 
   const filesToCopy = [
     ['agents', 'agents'],
+    ['hooks', 'hooks'],
+    ['skills', 'skills'],
     ['index.js', 'index.js'],
     ['gm.js', 'gm.js'],
     ['kilocode.json', 'kilocode.json'],
     ['package.json', 'package.json'],
     ['.mcp.json', '.mcp.json'],
-    ['README.md', 'README.md']
+    ['README.md', 'README.md'],
+    ['LICENSE', 'LICENSE'],
+    ['CONTRIBUTING.md', 'CONTRIBUTING.md'],
+    ['.gitignore', '.gitignore'],
+    ['.editorconfig', '.editorconfig']
   ];
 
   function copyRecursive(src, dst) {

package/hooks/hooks.json

@@ -0,0 +1,58 @@
+{
+  "description": "Hooks for gm Kilo CLI extension",
+  "hooks": {
+    "tool.execute.before": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${KILO_PLUGIN_ROOT}/hooks/pre-tool-use-hook.js",
+            "timeout": 3600
+          }
+        ]
+      }
+    ],
+    "session.created": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${KILO_PLUGIN_ROOT}/hooks/session-start-hook.js",
+            "timeout": 10000
+          }
+        ]
+      }
+    ],
+    "message.updated": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${KILO_PLUGIN_ROOT}/hooks/prompt-submit-hook.js",
+            "timeout": 3600
+          }
+        ]
+      }
+    ],
+    "session.closing": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${KILO_PLUGIN_ROOT}/hooks/stop-hook.js",
+            "timeout": 300000
+          },
+          {
+            "type": "command",
+            "command": "node ${KILO_PLUGIN_ROOT}/hooks/stop-hook-git.js",
+            "timeout": 60000
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/pre-tool-use-hook.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const isGemini = process.env.GEMINI_PROJECT_DIR !== undefined;
+
+const shellTools = ['Bash', 'run_shell_command'];
+const writeTools = ['Write', 'write_file'];
+const searchTools = ['Glob', 'Grep', 'glob', 'search_file_content', 'Search', 'search'];
+const forbiddenTools = ['find', 'Find'];
+
+const run = () => {
+  try {
+    const input = fs.readFileSync(0, 'utf-8');
+    const data = JSON.parse(input);
+    const { tool_name, tool_input } = data;
+
+    if (!tool_name) return { allow: true };
+
+    if (forbiddenTools.includes(tool_name)) {
+      return { block: true, reason: 'Use gm:code-search or plugin:gm:dev for semantic codebase search instead of filesystem find' };
+    }
+
+    if (shellTools.includes(tool_name)) {
+      return { block: true, reason: 'Use dev execute instead for all command execution' };
+    }
+
+    if (writeTools.includes(tool_name)) {
+      const file_path = tool_input?.file_path || '';
+      const ext = path.extname(file_path);
+      const inSkillsDir = file_path.includes('/skills/');
+      const base = path.basename(file_path).toLowerCase();
+      if ((ext === '.md' || ext === '.txt' || base.startsWith('features_list')) &&
+          !base.startsWith('claude') && !base.startsWith('readme') && !inSkillsDir) {
+        return { block: true, reason: 'Cannot create documentation files. Only CLAUDE.md and readme.md are maintained.' };
+      }
+      if (/\.(test|spec)\.(js|ts|jsx|tsx|mjs|cjs)$/.test(base) ||
+          /^(jest|vitest|mocha|ava|jasmine|tap)\.(config|setup)/.test(base) ||
+          file_path.includes('/__tests__/') || file_path.includes('/test/') ||
+          file_path.includes('/tests/') || file_path.includes('/fixtures/') ||
+          file_path.includes('/test-data/') || file_path.includes('/__mocks__/') ||
+          /\.(snap|stub|mock|fixture)\.(js|ts|json)$/.test(base)) {
+        return { block: true, reason: 'Test files forbidden on disk. Use plugin:gm:dev with real services for all testing.' };
+      }
+    }
+
+    if (searchTools.includes(tool_name)) {
+      return { block: true, reason: 'Code exploration must use: gm:code-search skill or plugin:gm:dev execute. This restriction enforces semantic search over filesystem patterns.' };
+    }
+
+    if (tool_name === 'Task') {
+      const subagentType = tool_input?.subagent_type || '';
+      if (subagentType === 'Explore') {
+        return { block: true, reason: 'Use gm:thorns-overview for codebase insight, then use gm:code-search or plugin:gm:dev' };
+      }
+    }
+
+    if (tool_name === 'EnterPlanMode') {
+      return { block: true, reason: 'Plan mode is disabled. Use GM agent planning (PLAN→EXECUTE→EMIT→VERIFY→COMPLETE state machine) via gm:gm subagent instead.' };
+    }
+
+    return { allow: true };
+  } catch (error) {
+    return { allow: true };
+  }
+};
+
+try {
+  const result = run();
+
+  if (result.block) {
+    if (isGemini) {
+      console.log(JSON.stringify({ decision: 'deny', reason: result.reason }));
+    } else {
+      console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: result.reason } }));
+    }
+    process.exit(2);
+  }
+
+  if (isGemini) {
+    console.log(JSON.stringify({ decision: 'allow' }));
+  } else {
+    console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow' } }));
+  }
+  process.exit(0);
+} catch (error) {
+  if (isGemini) {
+    console.log(JSON.stringify({ decision: 'allow' }));
+  } else {
+    console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow' } }));
+  }
+  process.exit(0);
+}

package/hooks/prompt-submit-hook.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const { execSync } = require('child_process');
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.env.GEMINI_PROJECT_DIR || process.env.OC_PROJECT_DIR;
+
+const COMPACT_CONTEXT = 'use gm agent | ref: TOOL_INVARIANTS | codesearch for exploration | plugin:gm:dev for execution';
+
+const PLAN_MODE_BLOCK = 'DO NOT use EnterPlanMode or any plan mode tool. Use GM agent planning (PLAN→EXECUTE→EMIT→VERIFY→COMPLETE state machine) instead. Plan mode is blocked.';
+
+const getBaseContext = (resetMsg = '') => {
+  let ctx = 'use gm agent';
+  if (resetMsg) ctx += ' - ' + resetMsg;
+  return ctx;
+};
+
+const readStdinPrompt = () => {
+  try {
+    const raw = fs.readFileSync(0, 'utf-8');
+    const data = JSON.parse(raw);
+    return data.prompt || '';
+  } catch (e) {
+    return '';
+  }
+};
+
+const runCodeSearch = (query, cwd) => {
+  if (!query || !cwd || !fs.existsSync(cwd)) return '';
+  try {
+    const escaped = query.replace(/"/g, '\\"').substring(0, 200);
+    let out;
+    try {
+      out = execSync(`bun x codebasesearch@latest "${escaped}"`, {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        cwd,
+        timeout: 55000,
+        killSignal: 'SIGTERM'
+      });
+    } catch (bunErr) {
+      if (bunErr.killed) return '';
+      out = execSync(`npx -y codebasesearch@latest "${escaped}"`, {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        cwd,
+        timeout: 55000,
+        killSignal: 'SIGTERM'
+      });
+    }
+    const lines = out.split('\n');
+    const resultStart = lines.findIndex(l => l.includes('Searching for:'));
+    return resultStart >= 0 ? lines.slice(resultStart).join('\n').trim() : out.trim();
+  } catch (e) {
+    return '';
+  }
+};
+
+const emit = (additionalContext) => {
+  const isGemini = process.env.GEMINI_PROJECT_DIR !== undefined;
+  const isOpenCode = process.env.OC_PLUGIN_ROOT !== undefined;
+
+  if (isGemini) {
+    console.log(JSON.stringify({ systemMessage: additionalContext }, null, 2));
+  } else if (isOpenCode) {
+    console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: 'message.updated', additionalContext } }, null, 2));
+  } else {
+    console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext } }, null, 2));
+  }
+};
+
+try {
+  const prompt = readStdinPrompt();
+  const parts = [getBaseContext() + ' | ' + COMPACT_CONTEXT + ' | ' + PLAN_MODE_BLOCK];
+
+  if (prompt && projectDir) {
+    const searchResults = runCodeSearch(prompt, projectDir);
+    if (searchResults) {
+      parts.push(`=== Semantic code search results for initial prompt ===\n${searchResults}`);
+    }
+  }
+
+  emit(parts.join('\n\n'));
+} catch (error) {
+  emit(getBaseContext('hook error: ' + error.message) + ' | ' + COMPACT_CONTEXT);
+  process.exit(0);
+}

package/hooks/session-start-hook.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT || process.env.GEMINI_PROJECT_DIR || process.env.OC_PLUGIN_ROOT;
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.env.GEMINI_PROJECT_DIR || process.env.OC_PROJECT_DIR;
+
+const ensureGitignore = () => {
+  if (!projectDir) return;
+  const gitignorePath = path.join(projectDir, '.gitignore');
+  const entry = '.gm-stop-verified';
+  try {
+    let content = '';
+    if (fs.existsSync(gitignorePath)) {
+      content = fs.readFileSync(gitignorePath, 'utf-8');
+    }
+    if (!content.split('\n').some(line => line.trim() === entry)) {
+      const newContent = content.endsWith('\n') || content === ''
+        ? content + entry + '\n'
+        : content + '\n' + entry + '\n';
+      fs.writeFileSync(gitignorePath, newContent);
+    }
+  } catch (e) {
+    // Silently fail - not critical
+  }
+};
+
+ensureGitignore();
+
+try {
+  let outputs = [];
+
+  // 1. Read ./start.md
+  if (pluginRoot) {
+    const startMdPath = path.join(pluginRoot, '/agents/gm.md');
+    try {
+      const startMdContent = fs.readFileSync(startMdPath, 'utf-8');
+      outputs.push(startMdContent);
+    } catch (e) {
+      // File may not exist in this context
+    }
+  }
+
+  // 2. Add semantic code-search explanation
+  const codeSearchContext = `## 🔍 Semantic Code Search Now Available
+
+Your prompts will trigger **semantic code search** - intelligent, intent-based exploration of your codebase.
+
+### How It Works
+Describe what you need in plain language, and the search understands your intent:
+- "Find authentication validation" → locates auth checks, guards, permission logic
+- "Where is database initialization?" → finds connection setup, migrations, schemas
+- "Show error handling patterns" → discovers try/catch patterns, error boundaries
+
+NOT syntax-based regex matching - truly semantic understanding across files.
+
+### Example
+Instead of regex patterns, simply describe your intent:
+"Find where API authorization is checked"
+
+The search will find permission validations, role checks, authentication guards - however they're implemented.
+
+### When to Use Code Search
+When exploring unfamiliar code, finding similar patterns, understanding integrations, or locating feature implementations across your codebase.`;
+  outputs.push(codeSearchContext);
+
+  // 3. Run mcp-thorns (bun x with npx fallback)
+  if (projectDir && fs.existsSync(projectDir)) {
+    try {
+      let thornOutput;
+      try {
+        thornOutput = execSync(`bun x mcp-thorns@latest`, {
+          encoding: 'utf-8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+          cwd: projectDir,
+          timeout: 180000,
+          killSignal: 'SIGTERM'
+        });
+      } catch (bunErr) {
+        if (bunErr.killed && bunErr.signal === 'SIGTERM') {
+          thornOutput = '=== mcp-thorns ===\nSkipped (3min timeout)';
+        } else {
+          try {
+            thornOutput = execSync(`npx -y mcp-thorns@latest`, {
+              encoding: 'utf-8',
+              stdio: ['pipe', 'pipe', 'pipe'],
+              cwd: projectDir,
+              timeout: 180000,
+              killSignal: 'SIGTERM'
+            });
+          } catch (npxErr) {
+            if (npxErr.killed && npxErr.signal === 'SIGTERM') {
+              thornOutput = '=== mcp-thorns ===\nSkipped (3min timeout)';
+            } else {
+              thornOutput = `=== mcp-thorns ===\nSkipped (error: ${bunErr.message.split('\n')[0]})`;
+            }
+          }
+        }
+      }
+      outputs.push(`=== This is your initial insight of the repository, look at every possible aspect of this for initial opinionation and to offset the need for code exploration ===\n${thornOutput}`);
+    } catch (e) {
+      if (e.killed && e.signal === 'SIGTERM') {
+        outputs.push(`=== mcp-thorns ===\nSkipped (3min timeout)`);
+      } else {
+        outputs.push(`=== mcp-thorns ===\nSkipped (error: ${e.message.split('\n')[0]})`);
+      }
+    }
+  }
+  outputs.push('Use gm as a philosophy to coordinate all plans and the gm subagent to create and execute all plans');
+  const additionalContext = outputs.join('\n\n');
+
+  const isGemini = process.env.GEMINI_PROJECT_DIR !== undefined;
+  const isOpenCode = process.env.OC_PLUGIN_ROOT !== undefined;
+
+  if (isGemini) {
+    const result = {
+      systemMessage: additionalContext
+    };
+    console.log(JSON.stringify(result, null, 2));
+  } else if (isOpenCode) {
+    const result = {
+      hookSpecificOutput: {
+        hookEventName: 'session.created',
+        additionalContext
+      }
+    };
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    const result = {
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext
+      }
+    };
+    console.log(JSON.stringify(result, null, 2));
+  }
+} catch (error) {
+  const isGemini = process.env.GEMINI_PROJECT_DIR !== undefined;
+  const isOpenCode = process.env.OC_PLUGIN_ROOT !== undefined;
+
+  if (isGemini) {
+    console.log(JSON.stringify({
+      systemMessage: `Error executing hook: ${error.message}`
+    }, null, 2));
+  } else if (isOpenCode) {
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'session.created',
+        additionalContext: `Error executing hook: ${error.message}`
+      }
+    }, null, 2));
+  } else {
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: `Error executing hook: ${error.message}`
+      }
+    }, null, 2));
+  }
+  process.exit(0);
+}
+
+
+
+
+
+
+
+

package/hooks/stop-hook-git.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+const getCounterPath = () => {
+  const hash = crypto.createHash('md5').update(projectDir).digest('hex');
+  return path.join('/tmp', `gm-git-block-counter-${hash}.json`);
+};
+
+const readCounter = () => {
+  try {
+    const counterPath = getCounterPath();
+    if (fs.existsSync(counterPath)) {
+      const data = fs.readFileSync(counterPath, 'utf-8');
+      return JSON.parse(data);
+    }
+  } catch (e) {}
+  return { count: 0, lastGitHash: null };
+};
+
+const writeCounter = (data) => {
+  try {
+    const counterPath = getCounterPath();
+    fs.writeFileSync(counterPath, JSON.stringify(data, null, 2), 'utf-8');
+  } catch (e) {}
+};
+
+const getCurrentGitHash = () => {
+  try {
+    const hash = execSync('git rev-parse HEAD', {
+      cwd: projectDir,
+      stdio: 'pipe',
+      encoding: 'utf-8'
+    }).trim();
+    return hash;
+  } catch (e) {
+    return null;
+  }
+};
+
+const resetCounterIfCommitted = (currentHash) => {
+  const counter = readCounter();
+  if (counter.lastGitHash && currentHash && counter.lastGitHash !== currentHash) {
+    counter.count = 0;
+    counter.lastGitHash = currentHash;
+    writeCounter(counter);
+    return true;
+  }
+  return false;
+};
+
+const incrementCounter = (currentHash) => {
+  const counter = readCounter();
+  counter.count = (counter.count || 0) + 1;
+  counter.lastGitHash = currentHash;
+  writeCounter(counter);
+  return counter.count;
+};
+
+const getGitStatus = () => {
+  try {
+    execSync('git rev-parse --git-dir', {
+      cwd: projectDir,
+      stdio: 'pipe'
+    });
+  } catch (e) {
+    return { isRepo: false };
+  }
+
+  try {
+    const status = execSync('git status --porcelain', {
+      cwd: projectDir,
+      stdio: 'pipe',
+      encoding: 'utf-8'
+    }).trim();
+
+    const isDirty = status.length > 0;
+
+    let unpushedCount = 0;
+    try {
+      const unpushed = execSync('git rev-list --count @{u}..HEAD', {
+        cwd: projectDir,
+        stdio: 'pipe',
+        encoding: 'utf-8'
+      }).trim();
+      unpushedCount = parseInt(unpushed, 10) || 0;
+    } catch (e) {
+      unpushedCount = -1;
+    }
+
+    let behindCount = 0;
+    try {
+      const behind = execSync('git rev-list --count HEAD..@{u}', {
+        cwd: projectDir,
+        stdio: 'pipe',
+        encoding: 'utf-8'
+      }).trim();
+      behindCount = parseInt(behind, 10) || 0;
+    } catch (e) {}
+
+    return {
+      isRepo: true,
+      isDirty,
+      unpushedCount,
+      behindCount,
+      statusOutput: status
+    };
+  } catch (e) {
+    return { isRepo: true, isDirty: false, unpushedCount: 0, behindCount: 0 };
+  }
+};
+
+const run = () => {
+  const gitStatus = getGitStatus();
+  if (!gitStatus.isRepo) return { ok: true };
+
+  const currentHash = getCurrentGitHash();
+  resetCounterIfCommitted(currentHash);
+
+  const issues = [];
+  if (gitStatus.isDirty) {
+    issues.push('Uncommitted changes exist');
+  }
+  if (gitStatus.unpushedCount > 0) {
+    issues.push(`${gitStatus.unpushedCount} commit(s) not pushed`);
+  }
+  if (gitStatus.unpushedCount === -1) {
+    issues.push('Unable to verify push status - may have unpushed commits');
+  }
+  if (gitStatus.behindCount > 0) {
+    issues.push(`${gitStatus.behindCount} upstream change(s) not pulled`);
+  }
+
+  if (issues.length > 0) {
+    const blockCount = incrementCounter(currentHash);
+    return {
+      ok: false,
+      reason: `Git: ${issues.join(', ')}, must push to remote`,
+      blockCount
+    };
+  }
+
+  const counter = readCounter();
+  if (counter.count > 0) {
+    counter.count = 0;
+    writeCounter(counter);
+  }
+
+  return { ok: true };
+};
+
+try {
+  const result = run();
+  if (!result.ok) {
+    if (result.blockCount === 1) {
+      console.log(JSON.stringify({
+        decision: 'block',
+        reason: `Git: ${result.reason} [First violation - blocks this session]`
+      }, null, 2));
+      process.exit(2);
+    } else if (result.blockCount > 1) {
+      console.log(JSON.stringify({
+        decision: 'approve',
+        reason: `⚠️ Git warning (attempt #${result.blockCount}): ${result.reason} - Please commit and push your changes.`
+      }, null, 2));
+      process.exit(0);
+    }
+  } else {
+    console.log(JSON.stringify({
+      decision: 'approve'
+    }, null, 2));
+    process.exit(0);
+  }
+} catch (e) {
+  console.log(JSON.stringify({
+    decision: 'approve'
+  }, null, 2));
+  process.exit(0);
+}

package/hooks/stop-hook.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+// Always use current working directory for .prd location
+// Explicitly resolve to ./.prd in the current folder
+const projectDir = process.cwd();
+const prdFile = path.resolve(projectDir, '.prd');
+
+let aborted = false;
+process.on('SIGTERM', () => { aborted = true; });
+process.on('SIGINT', () => { aborted = true; });
+
+const run = () => {
+  if (aborted) return { ok: true };
+
+  try {
+    // Check if .prd file exists and has content
+    if (fs.existsSync(prdFile)) {
+      const prdContent = fs.readFileSync(prdFile, 'utf-8').trim();
+      if (prdContent.length > 0) {
+        // .prd has content, block stopping
+        return {
+          ok: false,
+          reason: `Work items remain in ${prdFile}. Remove completed items as they finish. Current items:\n\n${prdContent}`
+        };
+      }
+    }
+
+    // .prd doesn't exist or is empty, allow stop
+    return { ok: true };
+  } catch (error) {
+    return { ok: true };
+  }
+};
+
+try {
+  const result = run();
+
+  if (!result.ok) {
+    console.log(JSON.stringify({
+      decision: 'block',
+      reason: result.reason
+    }, null, 2));
+    process.exit(2);
+  }
+
+  console.log(JSON.stringify({
+    decision: 'approve'
+  }, null, 2));
+  process.exit(0);
+} catch (e) {
+  console.log(JSON.stringify({
+    decision: 'approve'
+  }, null, 2));
+  process.exit(0);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-kilo",
-  "version": "2.0.15",
+  "version": "2.0.16",
   "description": "Advanced Claude Code plugin with WFGY integration, MCP tools, and automated hooks",
   "author": "AnEntrypoint",
   "license": "MIT",
@@ -27,14 +27,22 @@
   "engines": {
     "node": ">=16.0.0"
   },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
+    "mcp-gm": "latest",
+    "codebasesearch": "latest",
     "mcp-thorns": "^4.1.0"
   },
   "files": [
     "agents/",
+    "hooks/",
+    "skills/",
+    "scripts/",
     "gm.js",
     "index.js",
     "kilocode.json",
@@ -42,6 +50,10 @@
     ".mcp.json",
     "README.md",
     "cli.js",
-    "install.js"
+    "install.js",
+    "LICENSE",
+    "CONTRIBUTING.md",
+    ".gitignore",
+    ".editorconfig"
   ]
-}
+}

package/scripts/postinstall.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Postinstall script for gm-cc
+ * Implements Mode 1: Standalone .claude/ directory installation
+ * 
+ * When installed via npm in a project:
+ * - Copies agents/, hooks/, .mcp.json to project's .claude/
+ * - Updates .gitignore with .gm-stop-verified
+ * - Runs silently, never breaks npm install
+ * - Safe to run multiple times (idempotent)
+ */
+
+function isInsideNodeModules() {
+  // Check if __dirname contains /node_modules/ in its path
+  // Example: /project/node_modules/gm-cc/scripts
+  return __dirname.includes(path.sep + 'node_modules' + path.sep);
+}
+
+function getProjectRoot() {
+  // From /project/node_modules/gm-cc/scripts
+  // Navigate to /project
+  if (!isInsideNodeModules()) {
+    return null;
+  }
+  
+  // Find the node_modules parent (project root)
+  let current = __dirname;
+  while (current !== path.dirname(current)) { // While not at root
+    current = path.dirname(current);
+    const parent = path.dirname(current);
+    if (path.basename(current) === 'node_modules') {
+      return parent;
+    }
+  }
+  return null;
+}
+
+function safeCopyFile(src, dst) {
+  try {
+    const content = fs.readFileSync(src, 'utf-8');
+    const dstDir = path.dirname(dst);
+    if (!fs.existsSync(dstDir)) {
+      fs.mkdirSync(dstDir, { recursive: true });
+    }
+    fs.writeFileSync(dst, content, 'utf-8');
+    return true;
+  } catch (err) {
+    // Silently skip errors
+    return false;
+  }
+}
+
+function safeCopyDirectory(src, dst) {
+  try {
+    if (!fs.existsSync(src)) {
+      return false; // Source doesn't exist, skip
+    }
+    
+    fs.mkdirSync(dst, { recursive: true });
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+    
+    entries.forEach(entry => {
+      const srcPath = path.join(src, entry.name);
+      const dstPath = path.join(dst, entry.name);
+      
+      if (entry.isDirectory()) {
+        safeCopyDirectory(srcPath, dstPath);
+      } else if (entry.isFile()) {
+        safeCopyFile(srcPath, dstPath);
+      }
+    });
+    return true;
+  } catch (err) {
+    // Silently skip errors
+    return false;
+  }
+}
+
+function updateGitignore(projectRoot) {
+  try {
+    const gitignorePath = path.join(projectRoot, '.gitignore');
+    const entry = '.gm-stop-verified';
+    
+    // Read existing content
+    let content = '';
+    if (fs.existsSync(gitignorePath)) {
+      content = fs.readFileSync(gitignorePath, 'utf-8');
+    }
+    
+    // Check if entry already exists
+    if (content.includes(entry)) {
+      return true; // Already there
+    }
+    
+    // Append entry
+    if (content && !content.endsWith('\n')) {
+      content += '\n';
+    }
+    content += entry + '\n';
+    
+    fs.writeFileSync(gitignorePath, content, 'utf-8');
+    return true;
+  } catch (err) {
+    // Silently skip errors
+    return false;
+  }
+}
+
+function install() {
+  // Only run if inside node_modules
+  if (!isInsideNodeModules()) {
+    return; // Silent exit
+  }
+  
+  const projectRoot = getProjectRoot();
+  if (!projectRoot) {
+    return; // Silent exit
+  }
+  
+  const claudeDir = path.join(projectRoot, '.claude');
+  const sourceDir = __dirname.replace(/[\/]scripts$/, ''); // Remove /scripts
+  
+  // Copy files
+  safeCopyDirectory(path.join(sourceDir, 'agents'), path.join(claudeDir, 'agents'));
+  safeCopyDirectory(path.join(sourceDir, 'hooks'), path.join(claudeDir, 'hooks'));
+  safeCopyFile(path.join(sourceDir, '.mcp.json'), path.join(claudeDir, '.mcp.json'));
+  
+  // Update .gitignore
+  updateGitignore(projectRoot);
+  
+  // Silent success
+}
+
+install();

package/skills/agent-browser/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: agent-browser
+description: Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction.
+allowed-tools: Bash(agent-browser:*)
+---
+
+# Browser Automation with agent-browser
+
+## Core Workflow
+
+Every browser automation follows this pattern:
+
+1. **Navigate**: `agent-browser open <url>`
+2. **Snapshot**: `agent-browser snapshot -i` (get element refs like `@e1`, `@e2`)
+3. **Interact**: Use refs to click, fill, select
+4. **Re-snapshot**: After navigation or DOM changes, get fresh refs
+
+```bash
+agent-browser open https://example.com/form
+agent-browser snapshot -i
+# Output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"
+
+agent-browser fill @e1 "user@example.com"
+agent-browser fill @e2 "password123"
+agent-browser click @e3
+agent-browser wait --load networkidle
+agent-browser snapshot -i  # Check result
+```
+
+## Essential Commands
+
+```bash
+# Navigation
+agent-browser open <url>              # Navigate (aliases: goto, navigate)
+agent-browser close                   # Close browser
+
+# Snapshot
+agent-browser snapshot -i             # Interactive elements with refs (recommended)
+agent-browser snapshot -i -C          # Include cursor-interactive elements (divs with onclick, cursor:pointer)
+agent-browser snapshot -s "#selector" # Scope to CSS selector
+
+# Interaction (use @refs from snapshot)
+agent-browser click @e1               # Click element
+agent-browser fill @e2 "text"         # Clear and type text
+agent-browser type @e2 "text"         # Type without clearing
+agent-browser select @e1 "option"     # Select dropdown option
+agent-browser check @e1               # Check checkbox
+agent-browser press Enter             # Press key
+agent-browser scroll down 500         # Scroll page
+
+# Get information
+agent-browser get text @e1            # Get element text
+agent-browser get url                 # Get current URL
+agent-browser get title               # Get page title
+
+# Wait
+agent-browser wait @e1                # Wait for element
+agent-browser wait --load networkidle # Wait for network idle
+agent-browser wait --url "**/page"    # Wait for URL pattern
+agent-browser wait 2000               # Wait milliseconds
+
+# Capture
+agent-browser screenshot              # Screenshot to temp dir
+agent-browser screenshot --full       # Full page screenshot
+agent-browser pdf output.pdf          # Save as PDF
+```
+
+## Common Patterns
+
+### Form Submission
+
+```bash
+agent-browser open https://example.com/signup
+agent-browser snapshot -i
+agent-browser fill @e1 "Jane Doe"
+agent-browser fill @e2 "jane@example.com"
+agent-browser select @e3 "California"
+agent-browser check @e4
+agent-browser click @e5
+agent-browser wait --load networkidle
+```
+
+### Authentication with State Persistence
+
+```bash
+# Login once and save state
+agent-browser open https://app.example.com/login
+agent-browser snapshot -i
+agent-browser fill @e1 "$USERNAME"
+agent-browser fill @e2 "$PASSWORD"
+agent-browser click @e3
+agent-browser wait --url "**/dashboard"
+agent-browser state save auth.json
+
+# Reuse in future sessions
+agent-browser state load auth.json
+agent-browser open https://app.example.com/dashboard
+```
+
+### Data Extraction
+
+```bash
+agent-browser open https://example.com/products
+agent-browser snapshot -i
+agent-browser get text @e5           # Get specific element text
+agent-browser get text body > page.txt  # Get all page text
+
+# JSON output for parsing
+agent-browser snapshot -i --json
+agent-browser get text @e1 --json
+```
+
+### Parallel Sessions
+
+```bash
+agent-browser --session site1 open https://site-a.com
+agent-browser --session site2 open https://site-b.com
+
+agent-browser --session site1 snapshot -i
+agent-browser --session site2 snapshot -i
+
+agent-browser session list
+```
+
+### Connect to Existing Chrome
+
+```bash
+# Auto-discover running Chrome with remote debugging enabled
+agent-browser --auto-connect open https://example.com
+agent-browser --auto-connect snapshot
+
+# Or with explicit CDP port
+agent-browser --cdp 9222 snapshot
+```
+
+### Visual Browser (Debugging)
+
+```bash
+agent-browser --headed open https://example.com
+agent-browser highlight @e1          # Highlight element
+agent-browser record start demo.webm # Record session
+```
+
+### Local Files (PDFs, HTML)
+
+```bash
+# Open local files with file:// URLs
+agent-browser --allow-file-access open file:///path/to/document.pdf
+agent-browser --allow-file-access open file:///path/to/page.html
+agent-browser screenshot output.png
+```
+
+### iOS Simulator (Mobile Safari)
+
+```bash
+# List available iOS simulators
+agent-browser device list
+
+# Launch Safari on a specific device
+agent-browser -p ios --device "iPhone 16 Pro" open https://example.com
+
+# Same workflow as desktop - snapshot, interact, re-snapshot
+agent-browser -p ios snapshot -i
+agent-browser -p ios tap @e1          # Tap (alias for click)
+agent-browser -p ios fill @e2 "text"
+agent-browser -p ios swipe up         # Mobile-specific gesture
+
+# Take screenshot
+agent-browser -p ios screenshot mobile.png
+
+# Close session (shuts down simulator)
+agent-browser -p ios close
+```
+
+**Requirements:** macOS with Xcode, Appium (`npm install -g appium && appium driver install xcuitest`)
+
+**Real devices:** Works with physical iOS devices if pre-configured. Use `--device "<UDID>"` where UDID is from `xcrun xctrace list devices`.
+
+## Ref Lifecycle (Important)
+
+Refs (`@e1`, `@e2`, etc.) are invalidated when the page changes. Always re-snapshot after:
+
+- Clicking links or buttons that navigate
+- Form submissions
+- Dynamic content loading (dropdowns, modals)
+
+```bash
+agent-browser click @e5              # Navigates to new page
+agent-browser snapshot -i            # MUST re-snapshot
+agent-browser click @e1              # Use new refs
+```
+
+## Semantic Locators (Alternative to Refs)
+
+When refs are unavailable or unreliable, use semantic locators:
+
+```bash
+agent-browser find text "Sign In" click
+agent-browser find label "Email" fill "user@test.com"
+agent-browser find role button click --name "Submit"
+agent-browser find placeholder "Search" type "query"
+agent-browser find testid "submit-btn" click
+```
+
+## JavaScript Evaluation (eval)
+
+Use `eval` to run JavaScript in the browser context. **Shell quoting can corrupt complex expressions** -- use `--stdin` or `-b` to avoid issues.
+
+```bash
+# Simple expressions work with regular quoting
+agent-browser eval 'document.title'
+agent-browser eval 'document.querySelectorAll("img").length'
+
+# Complex JS: use --stdin with heredoc (RECOMMENDED)
+agent-browser eval --stdin <<'EVALEOF'
+JSON.stringify(
+  Array.from(document.querySelectorAll("img"))
+    .filter(i => !i.alt)
+    .map(i => ({ src: i.src.split("/").pop(), width: i.width }))
+)
+EVALEOF
+
+# Alternative: base64 encoding (avoids all shell escaping issues)
+agent-browser eval -b "$(echo -n 'Array.from(document.querySelectorAll("a")).map(a => a.href)' | base64)"
+```
+
+**Why this matters:** When the shell processes your command, inner double quotes, `!` characters (history expansion), backticks, and `$()` can all corrupt the JavaScript before it reaches agent-browser. The `--stdin` and `-b` flags bypass shell interpretation entirely.
+
+**Rules of thumb:**
+- Single-line, no nested quotes -> regular `eval 'expression'` with single quotes is fine
+- Nested quotes, arrow functions, template literals, or multiline -> use `eval --stdin <<'EVALEOF'`
+- Programmatic/generated scripts -> use `eval -b` with base64
+
+## Deep-Dive Documentation
+
+| Reference | When to Use |
+|-----------|-------------|
+| [references/commands.md](references/commands.md) | Full command reference with all options |
+| [references/snapshot-refs.md](references/snapshot-refs.md) | Ref lifecycle, invalidation rules, troubleshooting |
+| [references/session-management.md](references/session-management.md) | Parallel sessions, state persistence, concurrent scraping |
+| [references/authentication.md](references/authentication.md) | Login flows, OAuth, 2FA handling, state reuse |
+| [references/video-recording.md](references/video-recording.md) | Recording workflows for debugging and documentation |
+| [references/proxy-support.md](references/proxy-support.md) | Proxy configuration, geo-testing, rotating proxies |
+
+## Ready-to-Use Templates
+
+| Template | Description |
+|----------|-------------|
+| [templates/form-automation.sh](templates/form-automation.sh) | Form filling with validation |
+| [templates/authenticated-session.sh](templates/authenticated-session.sh) | Login once, reuse state |
+| [templates/capture-workflow.sh](templates/capture-workflow.sh) | Content extraction with screenshots |
+
+```bash
+./templates/form-automation.sh https://example.com/form
+./templates/authenticated-session.sh https://app.example.com/login
+./templates/capture-workflow.sh https://example.com ./output
+```