npm - gm-hermes - Versions diffs - 2.0.515 - Mend

gm-hermes 2.0.515

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/AGENTS.md +11 -0
package/LICENSE +21 -0
package/README.md +21 -0
package/cli.js +37 -0
package/hermes-skill.json +9 -0
package/index.html +54 -0
package/package.json +33 -0
package/skills/software-development/browser/SKILL.md +202 -0
package/skills/software-development/code-search/SKILL.md +69 -0
package/skills/software-development/create-lang-plugin/SKILL.md +183 -0
package/skills/software-development/gm/SKILL.md +28 -0
package/skills/software-development/gm-complete/SKILL.md +185 -0
package/skills/software-development/gm-emit/SKILL.md +126 -0
package/skills/software-development/gm-execute/SKILL.md +159 -0
package/skills/software-development/pages/SKILL.md +258 -0
package/skills/software-development/planning/SKILL.md +177 -0
package/skills/software-development/ssh/SKILL.md +89 -0
package/skills/software-development/update-docs/SKILL.md +113 -0

package/AGENTS.md ADDED Viewed

@@ -0,0 +1,11 @@
+# AGENTS
+## Technical Notes
+Hook response format: `{"decision":"allow|block","reason":"text"}` with exit code 0.
+Tool names for this platform: `bash` → `terminal`, `write` → `write_file`, `glob` → `glob_files`, `grep` → `search_in_file`, `search` → `web_search`
+When filtering transcript history by sessionId, use: `if (sessionId && entry.sessionId === sessionId)`
+Verification file `.gm-stop-verified` is auto-added to .gitignore and tracks session completion state.

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2025
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,21 @@
+# gm-hermes for Hermes Agent
+## Installation
+```bash
+npm install -g gm-hermes
+```
+Or install directly:
+```bash
+npx gm-hermes
+```
+Restart Hermes Agent to activate skills.
+## What it does
+Installs the gm state machine skills (PLAN→EXECUTE→EMIT→VERIFY→COMPLETE) into Hermes Agent under `~/.hermes/skills/gm/skills/software-development/`.
+Use `/gm` or invoke skills by name in Hermes to access the full state machine workflow.

package/cli.js ADDED Viewed

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const homeDir = process.env.HOME || process.env.USERPROFILE || os.homedir();
+const destDir = path.join(homeDir, '.hermes', 'skills', 'gm');
+const srcDir = __dirname;
+const isUpgrade = fs.existsSync(destDir);
+console.log(isUpgrade ? 'Upgrading gm-hermes...' : 'Installing gm-hermes...');
+try {
+  fs.mkdirSync(destDir, { recursive: true });
+  const filesToCopy = [["skills","skills"],["README.md","README.md"]];
+  function copyRecursive(src, dst) {
+    if (!fs.existsSync(src)) return;
+    if (fs.statSync(src).isDirectory()) {
+      fs.mkdirSync(dst, { recursive: true });
+      fs.readdirSync(src).forEach(f => copyRecursive(path.join(src, f), path.join(dst, f)));
+    } else {
+      fs.copyFileSync(src, dst);
+    }
+  }
+  filesToCopy.forEach(([src, dst]) => copyRecursive(path.join(srcDir, src), path.join(destDir, dst)));
+  const destPath = process.platform === 'win32' ? destDir.replace(/\\/g, '/') : destDir;
+  console.log(`✓ gm-hermes ${isUpgrade ? 'upgraded' : 'installed'} to ${destPath}`);
+  console.log('Restart Hermes to activate skills.');
+} catch (e) {
+  console.error('Installation failed:', e.message);
+  process.exit(1);
+}

package/hermes-skill.json ADDED Viewed

@@ -0,0 +1,9 @@
+{
+  "name": "gm",
+  "version": "2.0.515",
+  "description": "State machine agent with hooks, skills, and automated git enforcement",
+  "author": "AnEntrypoint",
+  "homepage": "https://github.com/AnEntrypoint/gm",
+  "skills": "./skills",
+  "category": "software-development"
+}

package/index.html ADDED Viewed

@@ -0,0 +1,54 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Hermes Agent - gm plugin</title>
+  <link rel="stylesheet" href="https://unpkg.com/rippleui@1.12.1/dist/css/styles.css">
+  <script type="importmap">{"imports":{"webjsx":"https://cdn.jsdelivr.net/npm/webjsx@0.0.42/dist/index.js"}}</script>
+  <style>
+    body{background:#0f172a;color:#e2e8f0;font-family:system-ui,sans-serif;margin:0}
+    .gradient-hero{background:linear-gradient(135deg,#0f172a 0%,#1e1b4b 50%,#0f172a 100%)}
+    .card-hover{transition:transform .2s,box-shadow .2s}
+    .card-hover:hover{transform:translateY(-2px);box-shadow:0 8px 30px rgba(0,0,0,.3)}
+    pre{scrollbar-width:thin;background:#020617;border:1px solid #1e293b;border-radius:8px;padding:12px 16px;color:#4ade80;overflow-x:auto;font-size:.875rem}
+  </style>
+</head>
+<body>
+<script type="module">
+import { createElement as h, applyDiff, Fragment } from "webjsx";
+const PLATFORM_NAME="Hermes Agent",PLATFORM_TYPE="CLI Tool",PLATFORM_TYPE_COLOR="#3b82f6";
+const DESCRIPTION="State machine agent with hooks, skills, and automated git enforcement",VERSION="2.0.515";
+const GITHUB_URL="https://github.com/AnEntrypoint/gm-hermes",BADGE_LABEL="hermes";
+const FEATURES=[{"title":"State Machine","desc":"Immutable PLAN→EXECUTE→EMIT→VERIFY→COMPLETE phases with full mutable tracking"},{"title":"Semantic Search","desc":"Natural language codebase exploration via codesearch skill — no grep needed"},{"title":"Hooks","desc":"Pre-tool, session-start, prompt-submit, and stop hooks for full lifecycle control"},{"title":"Agents","desc":"gm, codesearch, and websearch agents pre-configured and ready to use"},{"title":"MCP Integration","desc":"Model Context Protocol server support built in"},{"title":"Auto-Recovery","desc":"Supervisor hierarchy ensures the system never crashes"}],INSTALL_STEPS=[{"desc":"Install via npm","cmd":"npm install -g gm-hermes"},{"desc":"Restart Hermes Agent — skills activate automatically"}];
+const CURRENT_PLATFORM="gm-hermes";
+const ALL_PLATFORMS=[
+  {id:'gm-cc',label:'Claude Code',type:'cli'},{id:'gm-gc',label:'Gemini CLI',type:'cli'},
+  {id:'gm-oc',label:'OpenCode',type:'cli'},{id:'gm-kilo',label:'Kilo Code',type:'cli'},
+  {id:'gm-codex',label:'Codex',type:'cli'},{id:'gm-copilot-cli',label:'Copilot CLI',type:'cli'},
+  {id:'gm-qwen',label:'Qwen Code',type:'cli'},{id:'gm-hermes',label:'Hermes Agent',type:'cli'},
+  {id:'gm-vscode',label:'VS Code',type:'ide'},{id:'gm-cursor',label:'Cursor',type:'ide'},
+  {id:'gm-zed',label:'Zed',type:'ide'},{id:'gm-jetbrains',label:'JetBrains',type:'ide'},
+];
+const GH_ICON='M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z';
+function NavBar(){return h('nav',{class:'border-b border-gray-800 bg-gray-950/80 backdrop-blur sticky top-0 z-10'},h('div',{class:'max-w-5xl mx-auto px-4 py-3 flex items-center justify-between'},h('div',{class:'flex items-center gap-3'},h('a',{href:'https://anentrypoint.github.io/gm',class:'text-white font-bold text-lg hover:text-indigo-400 transition-colors'},'gm'),h('span',{class:'text-gray-500'},'/'),h('span',{class:'text-gray-300 font-medium'},BADGE_LABEL)),h('a',{href:GITHUB_URL,target:'_blank',rel:'noopener',class:'flex items-center gap-2 text-gray-400 hover:text-white transition-colors text-sm'},h('svg',{viewBox:'0 0 16 16',class:'w-5 h-5 fill-current','aria-hidden':'true'},h('path',{d:GH_ICON})),'GitHub')));}
+function Badge({label,color}){return h('span',{class:'inline-flex items-center px-3 py-1 rounded-full text-xs font-semibold text-white',style:`background-color:${color}`},label);}
+function Hero(){return h('section',{class:'gradient-hero py-20 px-4'},h('div',{class:'max-w-5xl mx-auto text-center'},h('div',{class:'flex justify-center gap-2 mb-6'},h(Badge,{label:PLATFORM_TYPE,color:PLATFORM_TYPE_COLOR}),h(Badge,{label:'v'+VERSION,color:'#374151'})),h('h1',{class:'text-4xl md:text-5xl font-bold text-white mb-4'},PLATFORM_NAME),h('p',{class:'text-lg text-gray-300 max-w-2xl mx-auto mb-8'},DESCRIPTION),h('a',{href:GITHUB_URL,target:'_blank',rel:'noopener',class:'inline-flex items-center gap-2 bg-indigo-600 hover:bg-indigo-500 text-white font-semibold px-6 py-3 rounded-lg transition-colors'},'View on GitHub')));}
+function FeatureCard({title,desc}){return h('div',{class:'card-hover bg-gray-900 border border-gray-800 rounded-xl p-5'},h('h3',{class:'font-semibold text-white mb-2'},title),h('p',{class:'text-gray-400 text-sm leading-relaxed'},desc));}
+function FeaturesSection(){return h('section',{class:'py-16 px-4'},h('div',{class:'max-w-5xl mx-auto'},h('h2',{class:'text-2xl font-bold text-white mb-8 text-center'},'Features'),h('div',{class:'grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4'},...FEATURES.map(f=>h(FeatureCard,{title:f.title,desc:f.desc})))));}
+function InstallStep({step,index}){return h('div',{class:'flex gap-4 items-start'},h('div',{class:'flex-shrink-0 w-7 h-7 rounded-full bg-indigo-600 flex items-center justify-center text-xs font-bold text-white'},String(index+1)),h('div',{class:'flex-1'},h('p',{class:'text-gray-300 text-sm mb-1'},step.desc),step.cmd?h('pre',{class:'bg-gray-950 border border-gray-700 rounded-lg px-4 py-2 text-sm text-green-400 overflow-x-auto mt-1'},step.cmd):null));}
+function InstallSection(){if(!INSTALL_STEPS.length)return null;return h('section',{class:'py-16 px-4 bg-gray-900/50'},h('div',{class:'max-w-2xl mx-auto'},h('h2',{class:'text-2xl font-bold text-white mb-8 text-center'},'Installation'),h('div',{class:'space-y-6'},...INSTALL_STEPS.map((step,i)=>h(InstallStep,{step,index:i})))));}
+function PlatformLink({p}){const isCurrent=p.id===CURRENT_PLATFORM;return h('a',{href:isCurrent?'#':`https://anentrypoint.github.io/${p.id}`,class:`px-3 py-1.5 rounded-lg text-sm font-medium transition-colors ${isCurrent?'bg-indigo-600 text-white cursor-default':'bg-gray-800 text-gray-300 hover:bg-gray-700 hover:text-white'}`},p.label);}
+const SM_PHASES=[{name:'PLAN',desc:'Write .prd with every unknown named before any work begins'},{name:'EXECUTE',desc:'Prove every hypothesis via witnessed execution, import real modules'},{name:'EMIT',desc:'Write files only after all tests pass — pre and post-emit gates'},{name:'VERIFY',desc:'End-to-end execution confirms all changes work in real context'},{name:'COMPLETE',desc:'.prd empty, git clean, all output pushed'}];
+const HOOK_ITEMS=[{title:'Tool interception',desc:'exec:<lang> commands run code directly; forbidden tools redirected to code-search'},{title:'System injection',desc:'gm.md rules prepended to every system prompt'},{title:'Context injection',desc:'session-start injects codebase analysis and pending work reminder'},{title:'Completion gate',desc:'session end blocked until .prd is empty and git is clean'}];
+function PhaseCard({phase,index,total}){return h('div',{class:'card-hover bg-gray-900 border border-gray-800 rounded-xl p-4 flex-1 min-w-0'},h('div',{class:'flex items-center gap-2 mb-2'},h('span',{class:'text-indigo-400 font-bold text-sm font-mono'},phase.name),index<total-1?h('span',{class:'text-gray-600 text-xs'},'→'):null),h('p',{class:'text-gray-400 text-xs leading-relaxed'},phase.desc));}
+function StateMachineSection(){return h('section',{class:'py-16 px-4 bg-gray-900/40'},h('div',{class:'max-w-5xl mx-auto'},h('h2',{class:'text-2xl font-bold text-white mb-2 text-center'},'State Machine'),h('p',{class:'text-gray-400 text-sm text-center mb-8'},'Every task follows the same 5-phase cycle — no skipping, no shortcuts'),h('div',{class:'flex flex-col sm:flex-row gap-3'},...SM_PHASES.map((phase,i)=>h(PhaseCard,{phase,index:i,total:SM_PHASES.length})))));}
+function HookCard({item}){return h('div',{class:'card-hover bg-gray-900 border border-gray-800 rounded-xl p-5'},h('h3',{class:'font-semibold text-white mb-2'},item.title),h('p',{class:'text-gray-400 text-sm leading-relaxed'},item.desc));}
+function HooksSection(){return h('section',{class:'py-16 px-4'},h('div',{class:'max-w-5xl mx-auto'},h('h2',{class:'text-2xl font-bold text-white mb-2 text-center'},'What the Hooks Enforce'),h('p',{class:'text-gray-400 text-sm text-center mb-8'},'Lifecycle hooks wrap every interaction to keep the agent on rails'),h('div',{class:'grid grid-cols-1 sm:grid-cols-2 gap-4'},...HOOK_ITEMS.map(item=>h(HookCard,{item})))));}
+function AlsoAvailableSection(){const cli=ALL_PLATFORMS.filter(p=>p.type==='cli'),ide=ALL_PLATFORMS.filter(p=>p.type==='ide');return h('section',{class:'py-16 px-4 bg-gray-900/30'},h('div',{class:'max-w-5xl mx-auto'},h('h2',{class:'text-2xl font-bold text-white mb-8 text-center'},'Also Available For'),h('div',{class:'space-y-6'},h('div',null,h('p',{class:'text-xs font-semibold text-blue-400 uppercase tracking-wider mb-3'},'CLI Tools'),h('div',{class:'flex flex-wrap gap-2'},...cli.map(p=>h(PlatformLink,{p,key:p.id})))),h('div',null,h('p',{class:'text-xs font-semibold text-purple-400 uppercase tracking-wider mb-3'},'IDE Extensions'),h('div',{class:'flex flex-wrap gap-2'},...ide.map(p=>h(PlatformLink,{p,key:p.id}))))),h('div',{class:'mt-8 text-center'},h('a',{href:'https://anentrypoint.github.io/gm',class:'text-sm text-gray-400 hover:text-indigo-300 transition-colors'},'← Back to gm hub'))));}
+function Footer(){return h('footer',{class:'border-t border-gray-800 py-8 px-4 text-center text-gray-500 text-sm'},h('p',null,'Generated by ',h('a',{href:'https://github.com/AnEntrypoint/gm',class:'text-indigo-400 hover:text-indigo-300'},'gm'),' — convention-driven multi-platform plugin generator'));}
+function App(){return h(Fragment,null,h(NavBar,null),h(Hero,null),h(FeaturesSection,null),h(StateMachineSection,null),h(HooksSection,null),h(InstallSection,null),h(AlsoAvailableSection,null),h(Footer,null));}
+applyDiff(document.body,[h(App,null)]);
+</script>
+</body>
+</html>

package/package.json ADDED Viewed

@@ -0,0 +1,33 @@
+{
+  "name": "gm-hermes",
+  "version": "2.0.515",
+  "description": "State machine agent with hooks, skills, and automated git enforcement",
+  "author": "AnEntrypoint",
+  "license": "MIT",
+  "keywords": [
+    "hermes-agent",
+    "hermes",
+    "agent",
+    "state-machine",
+    "automation",
+    "gm"
+  ],
+  "homepage": "https://github.com/AnEntrypoint/gm-hermes#readme",
+  "bugs": {
+    "url": "https://github.com/AnEntrypoint/gm-hermes/issues"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "skills/",
+    "cli.js",
+    "README.md",
+    "AGENTS.md",
+    "hermes-skill.json",
+    "index.html"
+  ]
+}

package/skills/software-development/browser/SKILL.md ADDED Viewed

@@ -0,0 +1,202 @@
+---
+name: browser
+description: Browser automation via playwriter. Use when user needs to interact with websites, navigate pages, fill forms, click buttons, take screenshots, extract data, test web apps, or automate any browser task.
+allowed-tools: Bash(browser:*), Bash(exec:browser*)
+---
+# Browser Automation with playwriter
+**Use gm subagents for all independent work items. Invoke all skills in the chain: planning → gm-execute → gm-emit → gm-complete → update-docs.**
+## Two Pathways
+**Session commands** (`browser:` prefix) — manage multi-step sessions via playwriter CLI. Each `browser:` block runs its commands sequentially.
+**JS execution** (`exec:browser`) — run JavaScript directly against `page`. State persists across calls via `state` global.
+**CRITICAL**: Never mix these two pathways. Each `browser:` block is a separate Bash call. Each `exec:browser` block is a separate Bash call.
+## 15-Second Ceiling — How It Works
+Every `exec:browser` call has a 15s live window. During that window, all stdout/stderr is streamed to you in real time. After 15s the task backgrounds and you receive:
+- All output produced so far (live drain)
+- A task ID with `plugkit sleep/status/close` instructions
+**The task keeps running.** Every subsequent plugkit interaction automatically drains all running browser tasks — you will see new output without asking.
+**Never use `await new Promise(r => setTimeout(r, N))` with N > 10000.** Use short poll loops instead (see patterns below).
+**"Assertion failed: UV_HANDLE_CLOSING" in output** means the call exceeded 15s and was cut off — ignore the assertion noise, look at the output before it. The task was backgrounded normally.
+## Idle Timeout & Session Reaper
+Playwriter kills idle browser sessions after 5-15 minutes of inactivity. The rs-exec tooling now automatically cleans up the spawned browser process when the Claude Code session ends, preventing zombie tabs.
+**Historical note**: Earlier versions left the browser running after session end, causing repeated tabs on reconnect. This is now fixed — the browser will be killed when your session idles and closes.
+## Session Pathway (`browser:`)
+Create a session first, use `--direct` for CDP mode (requires Chrome with remote debugging):
+```
+browser:
+playwriter session new --direct
+```
+Returns a numeric session ID (e.g. `1`). Use that ID for all subsequent calls. **Each command must be a separate Bash call:**
+```
+browser:
+playwriter -s 1 -e 'await page.goto("http://example.com")'
+```
+```
+browser:
+playwriter -s 1 -e 'await snapshot({ page })'
+```
+```
+browser:
+playwriter -s 1 -e 'await screenshotWithAccessibilityLabels({ page })'
+```
+State persists across session calls:
+```
+browser:
+playwriter -s 1 -e 'state.x = 1'
+```
+```
+browser:
+playwriter -s 1 -e 'console.log(state.x)'
+```
+**RULE**: The `-e` argument must use single quotes. The JS inside must use double quotes for strings.
+**RULE**: Never chain multiple `playwriter` commands in one `browser:` block — run one command per block.
+## JS Execution Pathway (`exec:browser`)
+For direct page access, DOM queries, and data extraction. The runtime provides `page`, `snapshot`, `screenshotWithAccessibilityLabels`, and `state` as globals.
+```
+exec:browser
+await page.goto('https://example.com')
+await snapshot({ page })
+```
+```
+exec:browser
+const title = await page.title()
+console.log(title)
+```
+Never add shell quoting — write plain JavaScript directly.
+## Core Workflow
+1. **Navigate**: `exec:browser\nawait page.goto('url')` — session auto-created on first call
+2. **Snapshot**: `exec:browser\nawait snapshot({ page })`
+3. **Interact**: click, fill, type in subsequent `exec:browser` calls
+4. **Extract data**: `exec:browser\nconsole.log(await page.evaluate(() => document.title))`
+## Long-Running Operations — Poll Pattern
+For operations that take >10s (model loading, network fetches, animations):
+**Step 1** — set up listener and kick off the operation:
+```
+exec:browser
+state.done = false
+state.result = null
+page.on('console', msg => {
+  const t = msg.text()
+  if (t.includes('loaded') || t.includes('ready')) { state.done = true; state.result = t }
+})
+await page.click('#start-button')
+console.log('started, waiting...')
+```
+**Step 2** — poll in short bursts (this will background after 15s and keep draining):
+```
+exec:browser
+const start = Date.now()
+while (!state.done && Date.now() - start < 12000) {
+  await new Promise(r => setTimeout(r, 500))
+}
+console.log('done:', state.done, 'result:', state.result)
+```
+If step 2 backgrounds (takes >15s), every subsequent plugkit call will drain its output automatically. When you see the result in the drain log, close the task:
+```
+exec:close
+task_N
+```
+## Common Patterns
+### Data Extraction
+```
+exec:browser
+const items = await page.$$eval('.product-title', els => els.map(e => e.textContent))
+console.log(JSON.stringify(items))
+```
+### Console Monitoring — set up listener first, then poll
+```
+exec:browser
+state.logs = []
+state.errors = []
+page.on('console', msg => state.logs.push({ type: msg.type(), text: msg.text() }))
+page.on('pageerror', e => state.errors.push(e.message))
+console.log('listeners attached')
+```
+```
+exec:browser
+console.log('logs so far:', JSON.stringify(state.logs.slice(-20)))
+console.log('errors:', JSON.stringify(state.errors))
+```
+```
+exec:browser
+if (page.workers().length > 0) {
+  const r = await page.workers()[0].evaluate(() => JSON.stringify({ type: 'worker alive' }))
+  console.log(r)
+}
+```
+exec:browser
+const result = await page.evaluate(() => JSON.stringify({
+  entityCount: window.debug?.scene?.children?.length,
+  playerId: window.debug?.client?.playerId
+}))
+console.log(result)
+```
+exec:browser
+const start = Date.now()
+while (Date.now() - start < 12000) {
+  const el = await page.$('#status')
+  if (el) { console.log('found:', await el.textContent()); break }
+  await new Promise(r => setTimeout(r, 300))
+}
+```
+## Key Rules
+- `browser:` prefix → playwriter session management (one command per block)
+- `exec:browser` → JS in page context (multi-line JS allowed, 15s live window)
+- Never mix pathways in the same Bash call
+- `-e` argument: single quotes on outside, double quotes inside for JS strings
+- One `playwriter` command per `browser:` block
+- Never `await setTimeout(N)` with N > 10000 — use short poll loops instead
+- All running browser tasks drain automatically on every plugkit interaction

package/skills/software-development/code-search/SKILL.md ADDED Viewed

@@ -0,0 +1,69 @@
+---
+name: code-search
+description: Mandatory codebase search workflow. Use whenever you need to find anything in the codebase. Start with two words, iterate by changing or adding words until found.
+---
+# CODEBASE SEARCH — Mandatory Workflow
+**Use gm subagents for all independent work items. Invoke all skills in the chain: planning → gm-execute → gm-emit → gm-complete → update-docs.**
+`exec:codesearch` is the only way to search the codebase. Glob, Grep, Find, Explore are hook-blocked.
+**PDFs are indexed like code.** Any `.pdf` in the repository — specs, papers, manuals, RFCs, datasheets, design docs — is extracted page-by-page at scan time and enters the BM25 + vector index alongside source files. Treat PDF hits as first-class search results. A PDF chunk reports `line_start = line_end = page_number`; cite as `path/to/doc.pdf:<page>`. Unscanned digital PDFs are a search gap — if you know a doc exists and it isn't returning, check it is not under an ignored dir and that extraction succeeded (encrypted / image-only PDFs yield empty chunks silently).
+## Syntax
+```
+exec:codesearch
+<natural language query>
+```
+## Mandatory Search Protocol
+**Start with exactly two words.** Never start broader. Never start with one word.
+**Iterate by changing or adding words** — do not switch approach or give up until the content is found:
+1. Start: two-word query most likely to match
+2. No results → change one word (synonym, related term)
+3. Still no results → add a third word (narrow scope)
+4. Still no results → swap the changed word again
+5. Keep iterating — changing or adding words each pass — until content is found
+**Never**: start with one word | start with a sentence | give up after one miss | switch to a different tool | declare content missing after fewer than 4 search attempts
+**Each search is one `exec:codesearch` call.** Run them sequentially — use each result to inform the next query.
+## Examples
+Finding where a function is defined:
+```
+exec:codesearch
+session cleanup idle
+```
+→ no results →
+```
+exec:codesearch
+cleanup sessions timeout
+```
+→ found.
+Finding config format:
+```
+exec:codesearch
+plugin registration format
+```
+→ no results →
+```
+exec:codesearch
+plugin config array
+```
+→ found.
+Finding content inside a spec PDF:
+```
+exec:codesearch
+usb descriptor endpoint
+```
+→ returns `docs/usb-spec.pdf:42` — cite page, open via Read if you need the surrounding page text.

package/skills/software-development/create-lang-plugin/SKILL.md ADDED Viewed

@@ -0,0 +1,183 @@
+---
+name: create-lang-plugin
+description: Create a lang/ plugin that wires any CLI tool or language runtime into gm-cc — adds exec:<id> dispatch, optional LSP diagnostics, and optional prompt context injection. Zero hook configuration required.
+---
+# CREATE LANG PLUGIN
+**Use gm subagents for all independent work items. Invoke all skills in the chain: planning → gm-execute → gm-emit → gm-complete → update-docs.**
+A lang plugin is a single CommonJS file at `<projectDir>/lang/<id>.js`. gm-cc's hooks auto-discover it — no hook editing, no settings changes. The plugin gets three integration points: **exec dispatch**, **LSP diagnostics**, and **context injection**.
+## PLUGIN SHAPE
+```js
+'use strict';
+module.exports = {
+  id: 'mytool',                          // must match filename: lang/mytool.js
+  exec: {
+    match: /^exec:mytool/,               // regex tested against full "exec:mytool\n<code>" string
+    run(code, cwd) {                     // returns string or Promise<string>
+      // ...
+    }
+  },
+  lsp: {                                 // optional — synchronous only
+    check(fileContent, cwd) {            // returns Diagnostic[] synchronously
+      // ...
+    }
+  },
+  extensions: ['.ext'],                  // optional — file extensions lsp.check applies to
+  context: `=== mytool ===\n...`        // optional — string or () => string
+};
+```
+```ts
+type Diagnostic = { line: number; col: number; severity: 'error'|'warning'; message: string };
+```
+## HOW IT WORKS
+- **`exec.run`** is called in a child process (30s timeout) when Claude writes `exec:mytool\n<code>`. Output is returned as `exec:mytool output:\n\n<result>`. Async is fine here.
+- **`lsp.check`** is called synchronously in the hook process on each prompt submit — must NOT be async. Use `execFileSync` or `spawnSync`.
+- **`context`** is injected into every prompt's `additionalContext` (truncated to 2000 chars) and into the session-start context.
+- **`match`** regex is tested against the full command string `exec:mytool\n<code>` — keep it simple: `/^exec:mytool/`.
+## STEP 1 — IDENTIFY THE TOOL
+Answer these before writing any code:
+1. What is the tool's CLI name or npm package? (`gdlint`, `tsc`, `deno`, `ruff`, ...)
+2. How do you run a single expression/snippet? (`tool eval <expr>`, `tool -e <code>`, HTTP POST, ...)
+3. How do you run a file? (`tool run <file>`, `tool <file>`, ...)
+4. Does it have a lint/check mode? What does its output format look like?
+5. What file extensions does it apply to?
+6. Is the game/server running required, or does it work headlessly?
+## STEP 2 — IMPLEMENT exec.run
+Pattern for **HTTP eval** (tool has a running server):
+```js
+const http = require('http');
+function httpPost(port, urlPath, body) {
+  return new Promise((resolve, reject) => {
+    const data = JSON.stringify(body);
+    const req = http.request(
+      { hostname: '127.0.0.1', port, path: urlPath, method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(data) } },
+      (res) => { let raw = ''; res.on('data', c => raw += c); res.on('end', () => { try { resolve(JSON.parse(raw)); } catch { resolve({ raw }); } }); }
+    );
+    req.setTimeout(8000, () => { req.destroy(); reject(new Error('timeout')); });
+    req.on('error', reject);
+    req.write(data); req.end();
+  });
+}
+```
+Pattern for **file-based execution** (write temp file, run headlessly):
+```js
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+function runFile(code, cwd) {
+  const tmp = path.join(os.tmpdir(), `plugin_${Date.now()}.ext`);
+  fs.writeFileSync(tmp, code);
+  try {
+    return execFileSync('mytool', ['run', tmp], { cwd, encoding: 'utf8', timeout: 10000 });
+  } finally {
+    try { fs.unlinkSync(tmp); } catch (_) {}
+  }
+}
+```
+**Distinguish single expression vs multi-line** when both modes exist:
+```js
+function isSingleExpr(code) {
+  return !code.trim().includes('\n') && !/\b(func|def|fn |class|import)\b/.test(code);
+}
+```
+## STEP 3 — IMPLEMENT lsp.check (if applicable)
+Must be **synchronous**. Parse the tool's stderr/stdout for diagnostics:
+```js
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+function check(fileContent, cwd) {
+  const tmp = path.join(os.tmpdir(), `lsp_${Math.random().toString(36).slice(2)}.ext`);
+  try {
+    fs.writeFileSync(tmp, fileContent);
+    const r = spawnSync('mytool', ['check', tmp], { encoding: 'utf8', cwd });
+    const output = r.stdout + r.stderr;
+    return output.split('\n').reduce((acc, line) => {
+      const m = line.match(/^.+:(\d+):(\d+):\s+(error|warning):\s+(.+)$/);
+      if (m) acc.push({ line: parseInt(m[1]), col: parseInt(m[2]), severity: m[3], message: m[4].trim() });
+      return acc;
+    }, []);
+  } catch (_) {
+    return [];
+  } finally {
+    try { fs.unlinkSync(tmp); } catch (_) {}
+  }
+}
+```
+Common output patterns to parse:
+- `file:line:col: error: message` → standard
+- `file:line: E001: message` → gdlint style (`E`=error, `W`=warning)
+- JSON output → `JSON.parse(r.stdout).errors.map(...)`
+## STEP 4 — WRITE context STRING
+Describe what `exec:<id>` does and when to use it. This appears in every prompt. Keep it under 300 chars:
+```js
+context: `=== mytool exec: support ===
+exec:mytool
+<expression or code block>
+Runs via <how>. Use for <when>.`
+```
+## STEP 5 — WRITE THE FILE
+File goes at `lang/<id>.js` in the project root. The `id` field must match the filename (without `.js`).
+Verify after writing:
+```
+exec:nodejs
+const p = require('/abs/path/to/lang/mytool.js');
+console.log(p.id, typeof p.exec.run, p.exec.match.toString());
+```
+Then test dispatch:
+```
+exec:mytool
+<a simple test expression>
+```
+If it returns `exec:mytool output:` → working. If it errors → fix `exec.run`.
+## CONSTRAINTS
+- `exec.run` may be async — it runs in a child process with a 30s timeout
+- `lsp.check` must be synchronous — no Promises, no async/await
+- Plugin must be CommonJS (`module.exports = { ... }`) — no ES module syntax
+- No persistent processes — `exec.run` must complete and exit cleanly
+- `id` must match the filename exactly
+- First match wins — if multiple plugins could match, make `match` specific
+## EXAMPLE — gdscript plugin (reference implementation)
+See `C:/dev/godot-kit/lang/gdscript.js` for a complete working example combining HTTP eval (single expressions via port 6009) with headless file execution fallback, synchronous gdlint LSP, and a context string.